docs: plan runner subscription status path

[mmabrouk]

Users can select a model subscription before Agenta knows whether the runner is active or can read the mounted login. They see setup errors only after a run fails.

This draft plan defines a safe status path:

Mounted login folder
    -> Node runner
    -> Python agent service
    -> authenticated frontend query
    -> subscription status card

The runner returns status values only. It does not return tokens, file paths, account details, or file contents.

The plan also records a routing limit. The current code selects one deployment runner through AGENTA_RUNNER_INTERNAL_URL. A different runner for each Agenta Cloud user requires a server-owned runner connection and a shared resolver for status checks and model runs.

Included documents

• Current user experience, goals, and limits.
• Code research with the present request path.
• Proposed private and public response contracts.
• Complete path from runner to frontend.
• Implementation order and candidate files.
• Test plan and open decisions.

Checks

• git diff --check
• Confirmed that the change contains seven planning documents only.
• Confirmed that the documents contain no em dash or banned product vocabulary.
• No product code changed, so no runtime test or docs site build was required.

How to review

1. Read README.md for the proposed path and document order.
2. Read research.md for the current code behavior and routing limit.
3. Review api-design.md for the response shapes and security boundary.
4. Review plan.md for the implementation order.
5. Confirm the open decisions in status.md.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Error		Aug 12, 2026 5:02pm

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 9836b869-fc4e-4e53-a27c-7a408a01646c

📥 Commits

Reviewing files that changed from the base of the PR and between de4e3ea and 3407663.

📒 Files selected for processing (7)

• docs/design/runner-subscription-status/README.md
• docs/design/runner-subscription-status/api-design.md
• docs/design/runner-subscription-status/context.md
• docs/design/runner-subscription-status/plan.md
• docs/design/runner-subscription-status/qa.md
• docs/design/runner-subscription-status/research.md
• docs/design/runner-subscription-status/status.md

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added design documentation for reporting local subscription-login status before runs.
  • Documented authenticated data flows between runners, services, and the frontend while protecting credentials and private details.
  • Defined status handling for unavailable runners, missing or usable logins, and provider-access limitations.
  • Added implementation guidance covering frontend updates, compatibility, telemetry, rollout, and manual refresh behavior.
  • Added QA scenarios for authentication, status mapping, redaction, harness isolation, and frontend state handling.

Walkthrough

This PR adds design documentation for runner subscription-status reporting. It defines authenticated runner and agent-service APIs, sanitized per-harness states, frontend query and display behavior, implementation stages, research findings, unresolved decisions, and QA scenarios.

Changes

Runner subscription-status design

Layer / File(s)	Summary
Design scope and research findings docs/design/runner-subscription-status/context.md, docs/design/runner-subscription-status/research.md, docs/design/runner-subscription-status/status.md, docs/design/runner-subscription-status/README.md	Documents the current experience, proposed scope, routing model, privacy constraints, design decisions, and limits of login-file validation.
Status API and data flow docs/design/runner-subscription-status/api-design.md	Defines authenticated runner and agent-service endpoints, sanitized versioned responses, runner resolution, status mapping, frontend data flow, and open interface decisions.
Frontend behavior and delivery validation docs/design/runner-subscription-status/api-design.md, docs/design/runner-subscription-status/plan.md, docs/design/runner-subscription-status/qa.md	Specifies frontend query and display states, refresh behavior, staged implementation work, compatibility handling, telemetry, and QA scenarios.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• Agenta-AI/agenta#4858: Adds bearer-token authentication for runner HTTP transport.
• Agenta-AI/agenta#5964: Updates runner health harness advertising and tests.
• Agenta-AI/agenta#5994: Implements the documented subscription-status design.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/runner-subscription-status-plan

---

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.}

[mmabrouk]

Implementation is starting from this plan. I added one commit (3407663) recording the five decisions taken to unblock it, each reversible before the implementation PR lands: the public route lives on the Python agent service, it uses the same authentication as agent invocation, Pi reports one state per harness in the first version, the frontend text ships as drafted in api-design.md, and the scope is the deployment runner only (the resolver seam is kept for later per-user cloud runners).