refactor(agents): compact CLI output

[Waishnav]

Subagent CLI commands currently print persisted agent records directly, so routine orchestration can inject workspace paths, provider session IDs, timestamps, and old responses into the parent model context. This PR gives target discovery, run receipts, session lists, and observations dedicated compact output shapes, while mapping internal lifecycle states to the actionable running, completed, failed, and stopped vocabulary.

This is stacked on #219. The bundled subagents skill now uses --json for every command, and the agent docs describe the smaller public contract.

Summary by CodeRabbit

• New Features

  • Improved local-agent command output with concise, command-specific JSON formats.
  • Added clearer agent statuses, responses, and structured failure details.
  • Target listings now show selectable, available providers and profiles.

• Bug Fixes

  • Removed sensitive internal session details from agent listings and command results.
  • Standardized error output and exit behavior for immediate failures.

• Documentation

  • Updated agent workflows, target discovery, status guidance, and JSON output examples.

• Tests

  • Expanded coverage for agent presentation, filtering, statuses, responses, and errors.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7ae64b0f-1e57-4a21-998f-5a2628e9173d

📥 Commits

Reviewing files that changed from the base of the PR and between 54d5661 and 40feef2.

📒 Files selected for processing (9)

• docs/agent-profile-schema.md
• docs/configuration.md
• docs/local-agent-daemon.md
• package.json
• skills/subagents/SKILL.md
• src/cli.test.ts
• src/cli.ts
• src/local-agent-presentation.test.ts
• src/local-agent-presentation.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The CLI adds a dedicated presentation layer for local-agent catalogs, receipts, summaries, observations, and failures. Agent commands use compact JSON and text output. Tests and documentation cover sanitized fields, status handling, target filtering, and structured errors.

Changes

Local agent output

Layer / File(s)	Summary
Agent output projections and formatting src/local-agent-presentation.ts, src/local-agent-presentation.test.ts	Added public output types and presenters for catalogs, receipts, summaries, observations, and failures. The presenters normalize statuses, omit private fields, filter unusable providers, and format text output.
CLI integration and workflow documentation src/cli.ts, src/cli.test.ts, docs/..., skills/subagents/SKILL.md, package.json	Agent and daemon commands now use centralized JSON output and presentation functions. Tests validate compact output and structured errors. Documentation describes JSON commands, target filtering, and lifecycle statuses. The test script includes the local-agent suites.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 40fee

This PR narrows subagent CLI output to compact public shapes and maps lifecycle states to actionable values; no actionable merge-blocking risk remains beyond normal checks and review.

Poem

A rabbit reviews the agents with care,
Compact little outputs hop through the air.
Private fields hide, statuses shine,
Errors wear structure in orderly line.
Tests thump their paws: “The shapes are just right!”
Then documentation settles the night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 21 functions across 4 files. (5 skipped: 5 unsupported.)	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: refactoring agent CLI output into compact forms.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/v11-agent-cli-output

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR replaces persisted agent-record output with compact, command-specific CLI projections and translates internal lifecycle states into a smaller public vocabulary.

• Adds compact target, receipt, session-summary, and observation presentation types and formatters.
• Routes agent commands and structured errors through single-line JSON output.
• Updates the bundled subagent skill, documentation, and tests to describe and verify the new contract.

Confidence Score: 5/5

The PR appears safe to merge with no concrete blocking or independently actionable non-blocking issues identified.

The compact projections align with the documented command-specific contracts, preserve final responses and structured failures where needed, and update the repository’s bundled consumers and tests consistently.

Important Files Changed

Filename	Overview
src/local-agent-presentation.ts	Introduces compact public projections, lifecycle-status mapping, structured observations, and human-readable formatters without exposing persisted internal fields.
src/cli.ts	Applies the new projections across agent commands and emits compact single-line JSON while retaining non-zero exits for immediate failures.
src/local-agent-presentation.test.ts	Verifies status translation, output formatting, target filtering, structured failures, and omission of private record data.
src/cli.test.ts	Updates CLI integration coverage for compact list output and the revised immediate-error envelope.
skills/subagents/SKILL.md	Updates orchestration guidance to consistently request JSON and use the new running, completed, failed, and stopped states.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Internal agent record] --> B{CLI command}
    B -->|targets| C[Target catalog]
    B -->|run / continue| D[ID and status receipt]
    B -->|ls| E[Session summary]
    B -->|show| F[Observation]
    G[starting / running] --> H[running]
    I[idle] --> J[completed]
    K[error] --> L[failed]
    M[stopped] --> N[stopped]

Loading

_{Reviews (1): Last reviewed commit: "docs(agents): use structured CLI output" | Re-trigger Greptile}