feat(agent): per-command agent schema with response shapes

[platinummonkey]

Summary

pup agent schema returns everything at once (~185 KB) and only describes what each command takes, not what it returns, so agents guess the output format. This adds lookups for a single command or domain that also show what the command returns.

Changes

• pup agent schema logs aggregate (or logs.aggregate, or a domain like logs) returns just that part, with a returns shape for each command. --search TERM finds commands by name or description.
• Agent-mode pup <cmd> --help now covers the exact command asked for, not its whole domain.
• pup security findings schema --search/--section returns only the matching fields instead of the full ~200 KB reference.
• Output with no arguments is unchanged.

Testing

• Unit, integration, clippy and fmt all pass.
• Tests check the size limits, error paths, and that the published returns shapes match real command output.

Follow-ups

• Making all commands share one output format, and returning errors as structured data (a breaking change, so a separate PR).
• The --jq note in agent-mode output still conflicts with the published jq paths.

---

🤖 Generated with Claude Code

[datadog-prod-us1-3]

Three distinct issues were found: a timestamp unit mismatch in the metrics query contract (milliseconds vs. seconds), a missing blank-input guard in the section filter logic, and incorrect skipping of parent-local option values during help resolution.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit d1e2550 · @DataDog review to ask questions}

[datadog-prod-us1-3]

Document metric query bounds in seconds

The published contract tells agents that from_date and to_date are milliseconds, but Datadog's v1 metrics query response expresses these bounds in Unix seconds. Consumers following the contract will interpret valid dates as 1970-era timestamps.

Suggested change

	"from_date": {"type": "integer", "description": "ms since epoch"},
	"to_date": {"type": "integer", "description": "ms since epoch"},
	"from_date": {"type": "integer", "description": "seconds since epoch"},
	"to_date": {"type": "integer", "description": "seconds since epoch"},

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · @DataDog review to ask questions · Open Bits AI session}

[datadog-prod-us1-3]

Reject blank section filters

For --section='' or a whitespace-only value, trimming produces an empty string and contains("") matches every section. Instead of rejecting the invalid filter, the command returns the entire structured schema, defeating the scoped lookup and producing unexpectedly large output.

Suggested change

	let section = section.map(|s| s.trim().to_lowercase());
	let section = section.map(|s| s.trim().to_lowercase());
	if section.as_deref() == Some("") {
	anyhow::bail!("--section term must not be empty");
	}

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · @DataDog review to ask questions · Open Bits AI session}

[datadog-prod-us1-3]

Handle parent-option values during help resolution

For valid invocations such as pup profiling --header "test-drive-hummer-aurora: 1" services list --help, the header value is treated as a positional token because only global option values are skipped. Resolution stops at profiling, returning the broad parent schema instead of the requested leaf schema; any parent-local value option can break targeted agent help similarly.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · @DataDog review to ask questions · Open Bits AI session}