feat(cli): make agent workflows project-scoped and scriptable

[Waishnav]

Agent and workflow CLI commands need a stable project scope when invoked from Codex, Pi, OpenCode, Cursor, or an MCP shell. This layer resolves the injected DevSpace workspace first, then the Git root, a project marker, and the current directory; list, lookup, continuation, status, and cancellation all use that scope.

It also adds --json output for target discovery, agent lifecycle commands, and workflow lifecycle commands so harnesses can launch once, retain an ID, and poll without holding a long tool call open. Workflow error paths preserve their original errors while returning the correct result type.

Verified with npm run typecheck and the full test suite.

Summary by CodeRabbit

• New Features

  • Added JSON output options for agent and workflow CLI commands.
  • Added workspace-aware filtering to keep agent and workflow records scoped to the active project.
  • Added structured output for agent targets, workflow runs, and workflow calls, including statuses, timestamps, errors, and summaries.
  • Added trailing --json support for local-agent runs.

• Bug Fixes

  • Improved validation and error reporting for invalid command options and inaccessible records.

• Tests

  • Expanded coverage for JSON output, workspace isolation, and CLI workspace detection.

[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]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5362f213-89e4-4106-b6d8-0fc76052c11a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR adds workspace-aware CLI behavior and structured JSON output for local agents and workflows. It adds workspace-scoped workflow listing, JSON argument parsing, output serializers, ownership checks, tests, and explicit Result.err propagation.

Changes

Workspace-scoped CLI JSON output

Layer / File(s)	Summary
Workspace resolution and scoped workflow storage src/cli-workspace.ts, src/workflow-store.ts, src/cli-workspace.test.ts, src/workflow-store.test.ts	Workspace context resolves from environment variables, DevSpace markers, Git roots, or the current directory. Workflow runs can be filtered by workspace ID, root, status, and limit.
CLI output serializers and argument parsing src/cli-output.ts, src/cli-output.test.ts, src/local-agent-targets.ts, src/local-agent-targets.test.ts, package.json	Local-agent and workflow records receive normalized serializers. A trailing --json flag is parsed separately from the prompt.
Workspace-aware agent commands src/cli.ts, src/cli.test.ts	Agent commands validate workspace ownership, persist workspace IDs, and support structured JSON output.
Workflow CLI JSON flow and Result propagation src/workflow-cli.ts, src/workflow-launch.ts, src/workflow-schema.ts, src/cli.test.ts	Workflow commands support validated JSON output and workspace checks. Launch, schema, and store error paths explicitly return Result.err values.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
participant CLI
participant WorkspaceContext
participant WorkflowStore
participant OutputSerializer
CLI->>WorkspaceContext: resolve current workspace
CLI->>WorkflowStore: list runs for workspace scope
WorkflowStore-->>CLI: filtered workflow records
CLI->>OutputSerializer: serialize workflow records
OutputSerializer-->>CLI: structured JSON output

Loading

Possibly related PRs

• Waishnav/devspace#55: Extends the local-agent CLI and workspace-scoped records with JSON output.
• Waishnav/devspace#78: Extends the workflow store and workflow CLI with scoped listing and JSON serialization.
• Waishnav/devspace#101: Shares the better-result error-handling paths in workflow components.

Poem

A rabbit hops through workspace ground,
Finds JSON fields neatly bound.
Agents and workflows show their face,
While stray records stay out of place.
Errors return with care—
Clean output everywhere!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 3.45% which is insufficient. The required threshold is 80.00%.	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 summarizes the main changes: project-scoped agent workflows and scriptable CLI behavior.
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/dw-cli-contract

---

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

The PR adds project-scoped agent and workflow CLI operations with sanitized JSON output, plus scoped workflow-store queries and supporting tests.

• Adds --json output to agent and workflow run, list, status, cancel, and detail commands.
• Resolves CLI project context using injected workspace metadata, .devspace markers, or Git roots.
• Filters workflow and agent records to the current workspace and validates record ownership before ID-based operations.
• Makes result error propagation explicit in workflow launch, schema, and store paths.

Confidence Score: 4/5

The prompt-corruption defect in agents run should be fixed before merging because valid instructions containing --json are silently altered.

The new output-option handling removes every standalone --json token before prompt parsing rather than distinguishing the CLI option from literal prompt content.

Files Needing Attention: src/cli.ts

Important Files Changed

Filename	Overview
src/cli.ts	Adds scoped agent commands and JSON output, but globally filtering --json corrupts prompts containing that literal token.
src/workflow-cli.ts	Adds project ownership checks and JSON representations across workflow CLI operations.
src/cli-workspace.ts	Introduces injected-ID, marker, and Git-based workspace resolution with ID-first record matching.
src/cli-output.ts	Defines sanitized JSON projections for agents, workflow runs, and workflow calls.
src/workflow-store.ts	Adds workspace-ID-aware run listing and explicit result error propagation.
src/workflow-launch.ts	Preserves launch error types while explicitly adapting result errors.
src/workflow-schema.ts	Explicitly propagates schema compilation and provider execution errors.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
CLI[CLI arguments] --> Scope[Resolve workspace context]
Scope --> Store[Load scoped agent or workflow records]
CLI --> Parse[Parse command and JSON option]
Store --> ProjectCheck[Validate project ownership]
Parse --> Execute[Run, inspect, list, or cancel]
ProjectCheck --> Execute
Execute --> Output{JSON requested?}
Output -->|Yes| JSON[Sanitized JSON projection]
Output -->|No| Text[Human-readable output]

Loading

_{Reviews (1): Last reviewed commit: "fix(workflow): preserve result types acr..." | Re-trigger Greptile}

[Waishnav]

[gpt-5.6 high] RESPONDING ON BEHALF OF WAISHNAV

Fixed in 1f6c021. agents run now recognizes --json only as the documented trailing output option, so a standalone --json token inside the prompt is preserved. Added parser coverage for both literal prompt content and the trailing option; typecheck and the full test suite pass.

[coderabbitai]

@Waishnav, I will perform a complete review of PR #141.

⚠️ Action not completed

Review rate limited.

---

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 57 minutes.

[Waishnav]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/workflow-cli.ts (1)

207-222: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Reject unsupported status arguments.

Line 216 selects the first positional token but does not validate the remaining tokens. devspace workflow status <runId> --json=1 returns text output. devspace workflow status <runId> --unknown also runs instead of returning usage.

Parse only --follow and --json. Require exactly one non-option run ID. Update the usage error to include both supported options.

Proposed fix

- const runId = args.find((a) => !a.startsWith("-"));- if (!runId) {+ const positionals = args.filter(+ (arg) => arg !== "--follow" && arg !== "--json",+ );+ if (+ positionals.length !== 1 ||+ positionals[0]!.startsWith("-")+ ) {
throw new InvalidWorkflowInputError({
code: "invalid_argument",
- message: "Usage: devspace workflow status <runId> [--follow]",+ message: "Usage: devspace workflow status <runId> [--follow] [--json]",
});
}
+ const runId = positionals[0]!;

As per coding guidelines, verify the actual user-consumption path, including packaged npm/npx usage.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/workflow-cli.ts` around lines 207 - 222, Update runWorkflowStatus to
validate every argument: accept only --follow and --json options, reject unknown
or malformed options such as --json=1, and require exactly one non-option run
ID. Preserve the existing follow/json mutual-exclusion check, and update the
usage error to advertise both supported options; verify this validation is used
by the packaged npm/npx command path.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/local-agent-targets.ts`:
- Around line 25-26: Update the USAGE text associated with the CLI parser to end
with "<prompt>" [--json], documenting the trailing option handled by the json
and target parsing logic. If USAGE is covered by CLI parse-error contract tests,
add or update an assertion verifying this exact usage text.
In `@src/workflow-store.ts`:
- Line 316: Update the no-ID branch in the workflow-store run listing to query
only legacy records with workspace_id null and the normalized workspace root,
rather than calling listRunsForWorkspace. Preserve the existing workspaceId
branch, which includes the identified workspace and legacy rows, and add
coverage for the no-ID scope behavior.
---
Outside diff comments:
In `@src/workflow-cli.ts`:
- Around line 207-222: Update runWorkflowStatus to validate every argument:
accept only --follow and --json options, reject unknown or malformed options
such as --json=1, and require exactly one non-option run ID. Preserve the
existing follow/json mutual-exclusion check, and update the usage error to
advertise both supported options; verify this validation is used by the packaged
npm/npx command path.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 252539bb-7969-4fe8-a2b8-1085ae3316e9

📥 Commits

Reviewing files that changed from the base of the PR and between 9860cbd and 801feb5.

📒 Files selected for processing (14)

• package.json
• src/cli-output.test.ts
• src/cli-output.ts
• src/cli-workspace.test.ts
• src/cli-workspace.ts
• src/cli.test.ts
• src/cli.ts
• src/local-agent-targets.test.ts
• src/local-agent-targets.ts
• src/workflow-cli.ts
• src/workflow-launch.ts
• src/workflow-schema.ts
• src/workflow-store.test.ts
• src/workflow-store.ts