feat(output)!: replace agent mode with a default JSON envelope for everyone

[platinummonkey]

Summary

Breaking change. Removes agent mode. Output and help are now identical for humans and AI agents, and the {status, data, metadata} JSON envelope is the default output for everyone. Agent detection now drives two things only: the ai-agent <name> User-Agent token, and auto-approving CLI prompts (unchanged from main).

Breaking changes

• JSON and YAML output are enveloped by default, for humans too. On main, humans got the raw body and only detected agents got the (JSON-only) envelope.
  • A response with a top-level data keeps it in place. Its sibling keys (meta, links, included) are now kept; the old envelope dropped them, losing cursors. status and metadata are added alongside.
  • Any other response (v1 arrays, the metrics query body, etc.) becomes data. Example: monitors list | jq '.[]' becomes jq '.data[]'.
  • A response that already has its own status or metadata key is wrapped whole. For example, monitors search keeps its API pagination at data.metadata.
• Table/CSV/TSV print only rows; metadata goes to stderr. CSV and TSV now honor each command's row and column hints the same way the table does, so monitors search -o csv prints one row per monitor (it used to print the whole {counts, metadata, monitors} body as a single row). Table, CSV and TSV always print the metadata to stderr as one block:

  metadata: command="monitors search" count=30 truncated=true next_page=1
  next_action: More results available; rerun with --page=1
  warning: <when present>
  

  The metadata: line is always printed, with keys in a fixed order (command, count, truncated, next_cursor, next_offset, next_page), absent keys omitted and strings JSON-quoted. With --no-envelope only warning: lines are printed. CSV/TSV changed for commands with hints: monitors list/search, logs search, slos list, users list, incidents list, dashboards list, and pup format --rows-at/--row-at/--columns. Commands with explicit columns now print only those columns. --jq with table/CSV/TSV renders the jq result as-is.
• --jq results are wrapped too. On main, humans got the bare filter result; now it becomes the envelope's data. So id=$(pup monitors get 1 --jq '.id') yields an envelope instead of 1. Use --no-envelope (or PUP_NO_ENVELOPE=1) to get the bare result.
• pup api output is enveloped, including with -i: the response headers are printed first and describe the raw body, then the envelope follows.
• Envelope shape changed.
  • metadata.note is gone.
  • metadata.truncated is always present.
  • New fields: next_cursor, next_offset, next_page, warnings.
  • After --jq, count describes the filtered data; truncated and next_cursor are kept.
• Opt-out: --no-envelope (or PUP_NO_ENVELOPE=1) prints the raw response. The legacy --no-agent also prints the raw response, so scripts written to the old guidance keep working, and, as on main, it opts out of agent auto-approve. --no-envelope does not affect auto-approve.
• Help is always text. --help no longer returns a JSON schema for agents; use pup agent schema.
• Agent mode env vars removed. FORCE_AGENT_MODE and PUP_AGENT_MODE are no longer read or set. --agent is a hidden no-op.
• ddsql schema tables / columns: data is the list; next_offset and warnings are in metadata. Reference-table discovery now requests sort=table_name, so offsets are stable across pages.

Changes

• src/output.rs:
  • Metadata (now Deserialize) and build_envelope.
  • Metadata is derived from the response: count, command (the running command path), next_cursor and truncated. Commands only set what the response can't say.
  • Recognized cursors: meta.page.after, meta.page.next_cursor, meta.after, meta.next_cursor, meta.pagination.next_page (cicd flaky tests), page.next_cursor, data.next_cursor (llm-obs MCP endpoints), next_cursor, next_page_token (llm-obs patterns). Only fields that always mean "next page" are used; deployment gates' meta.page.cursor is the current page and is ignored.
  • Truncation also comes from meta.page.total_filtered_count exceeding the returned items (security findings), and from page pagination: metadata.page + 1 < metadata.page_count gives next_page (monitors search). truncated: false means "not known to be truncated": some APIs (e.g. incidents search) don't report it reliably.
  • next_action names the command's own cursor or page flag, read from its clap definition (--cursor, --page-cursor, --page-token, --page); commands without one say so.
  • The stderr metadata block (stderr_block) replaces the earlier ad-hoc stderr hints. Resource-diff hints print separately only when there are no changes or with --no-envelope.
• src/formatter.rs: re-exports Metadata and adds format_and_print_with and output_with_meta. There is no agent_mode parameter.
• Agent auto-approve (useragent::agent_auto_approves) is applied in main_inner and in the extension pre-parse path (PreParsedGlobals::apply_to), so extension children still get PUP_AUTO_APPROVE. Confirm-prompt behavior is otherwise unchanged from main.
• --no-envelope is forwarded to extensions via PUP_NO_ENVELOPE.
• Command metadata restored:
  • logs/traces cursor guidance;
  • idp suggestions, counts, entity-query "Continue with" (addresses the Bits --jq '.results' finding);
  • kinds, register, summary sampling, change-stories, traces get span count, resource-diff next step.
• pup format: --count, --command and --next-action populate metadata again. Piped pup envelopes print as-is for JSON/YAML (lossless, so format | format is idempotent), while rows and --jq use their payload; a look-alike {status, data, metadata} document is only unwrapped if its metadata has a boolean truncated and only pup's own keys, otherwise it is left whole.
• pup agent schema: envelope contract in the full, compact and filtered schemas, with --no-envelope in global_flags. returns.data describes envelope data, and the conformance test runs bodies through the real envelope builder.
• Runbooks: pup steps run the child with --output json --no-envelope, so until conditions and capture: see the raw payload. The parent renders that payload for display in the user's format and envelope choice (metadata on stderr for table/CSV/TSV), using generic row selection; plain-text output passes through unchanged. No temp files or path env vars are involved.
• Test harness: the agent pass sets CLAUDECODE=1, and command discovery uses pup agent schema. Both modes' baselines are the envelope shape. id_from paths were audited against each list response's shape (merged vs wrapped whole, e.g. slos list → data.data, events list → data.events; incidents list and synthetics suites list were already wrong on main), and a path that doesn't match the output is reported as a defect instead of a silent skip.
• Docs, skills and agent markdown are updated, including jq examples for bare-array commands.

Notes for reviewers

• src/config.rs, src/client.rs and src/formatter.rs carry the openapi-transformer "generated" header. Config now lives in the hand-maintained src/settings.rs (since refactor(config): split generator-owned contract from settings #913), and src/config.rs only re-exports it. The generator must emit the same contract: no agent_mode in src/client.rs test fixtures, format_and_print(data, format, jq), format_and_print_with_table(data, format, jq, table), format_and_print_with(data, format, jq, meta, table), output, output_with_table, output_with_meta, and the Metadata re-export.
• Harness baselines were converted from the human (raw) shapes rather than captured from a live run (that needs credentials). Optional metadata keys auto-merge on the first live run.
• agent schema, auth status, runbooks and bits print their own JSON and are not enveloped (unchanged from main).

Testing

• cargo test -- --test-threads=1: 2,211 unit tests plus all integration tests pass.
• cargo clippy --all-targets -- -D warnings and cargo fmt --check pass, and the wasm32-wasip2 build is clean.
• Tests cover:
  • envelope shape, sibling preservation, collision fallback, derived truncation and cursors, and --jq keeping metadata;
  • --no-envelope / --no-agent / PUP_NO_ENVELOPE;
  • agent auto-approve: a marker such as CLAUDECODE=1 auto-approves, no marker does not, --no-agent opts out, --no-envelope does not, and the extension pre-parse path matches;
  • format flags and envelope round-trips;
  • ddsql next_offset;
  • the Bits scenario end to end (tests/idp_query_cli.rs);
  • real-binary pagination (tests/pagination_cli.rs), including a command whose cursor flag is --page-token;
  • real-binary runbooks (tests/runbook_cli.rs): poll until on a raw --jq result, a timeout negative, and capture of the raw payload, table display, a plain-text step, and PUP_PAYLOAD_FILE not being honored;
  • real-binary output formats (tests/output_formats_cli.rs): pup format idempotence for four payload shapes, one CSV/TSV row per monitor with parseable stdout and metadata on stderr, the table, the YAML envelope, raw --no-envelope YAML/CSV, --jq with CSV, an empty result, and a bare v1 array;
  • stderr notes (cursor named alongside a custom next_action, warnings), new cursor/truncation locations, look-alike envelopes left whole, and per-command cursor flags.

---

🤖 Generated with Claude Code

[datadog-prod-us1-4]

When reference-table discovery fails (e.g. HTTP 429), the code incorrectly emits a continuation offset into an incomplete result set, causing callers that resume from that offset to skip entries. The fix is to suppress next_offset whenever the discovery is incomplete so callers retry the original page.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit b4284b1}

[datadog-prod-us1-4]

Entity queries filtered with --jq '.results' lose all continuation information, allowing partial inventories to appear complete. The existing cursor-hint helper can preserve that information on stderr.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 68b7a73}

[datadog-prod-us1-4]

Two production-impacting bugs were identified: envelope re-rendering silently mutates payload structure by double-promoting the data key through unwrap_envelope/build_envelope, and runbook polling evaluates enveloped subprocess output directly against conditions (instead of unwrapping first), causing all poll conditions to time out rather than resolve. A third issue affects the test harness SLO ID lookup paths, which must be updated to account for the new data.data nesting introduced by collision wrapping.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 3911b3c}