From 66c66509a92cfe33db2d3c6521769ce08a5e4239 Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Mon, 31 Aug 2026 07:39:34 +0530 Subject: [PATCH 1/2] docs(agents): teach XML and multi-agent wait --- docs/agent-profile-schema.md | 36 ++++++++++++++++++---- docs/chatgpt-coding-workflow.md | 3 +- docs/configuration.md | 29 +++++++++++++++--- docs/gotchas.md | 2 +- docs/local-agent-daemon.md | 29 +++++++++++------- docs/setup.md | 2 +- skills/subagents/SKILL.md | 53 +++++++++++++++++++-------------- src/cli.ts | 2 ++ 8 files changed, 111 insertions(+), 45 deletions(-) diff --git a/docs/agent-profile-schema.md b/docs/agent-profile-schema.md index 5ede01ad1..94186ce18 100644 --- a/docs/agent-profile-schema.md +++ b/docs/agent-profile-schema.md @@ -145,16 +145,40 @@ Recommended body content: ## Model-facing workflow -The Subagent skill teaches only: +The Subagent skill uses the default compact XML fragments: ```bash -devspace agents ls --json -devspace agents targets --json -devspace agents run "" --json -devspace agents continue "" --json -devspace agents show --json +devspace agents targets +devspace agents ls +devspace agents run "" +devspace agents continue "" +devspace agents show +devspace agents wait ... ``` +The commands do not add a document-level wrapper. `targets`, `ls`, and `wait` +print one fragment per item and print nothing for an empty list. This keeps the +model-facing result small: + +```xml + +Read-only code review. + +Review complete. +Provider disconnected. +Subagent not found. +``` + +`show` returns an immediate snapshot. `wait` accepts one or more agent IDs and +waits for all of their current work. It does not stream fragments as individual +agents finish. With `--timeout `, it returns each unique agent in +first-seen order and marks unfinished work with `status="running" +wait="timeout"`. + +`--json` remains available for scripts that need it, but the bundled skill does +not request it. Internal turn records, prompts, provider session IDs, workspace +paths, and timestamps are absent from both output formats. + `open_workspace` exposes compact profile metadata: ```json diff --git a/docs/chatgpt-coding-workflow.md b/docs/chatgpt-coding-workflow.md index 7d53fa397..584834364 100644 --- a/docs/chatgpt-coding-workflow.md +++ b/docs/chatgpt-coding-workflow.md @@ -150,7 +150,8 @@ the managed `subagents` skill for a separate read only when the model decides delegation would help. Set it to `preload` to include those instructions in the initial `open_workspace` result instead. The skill teaches the minimal `devspace agents targets`, `devspace agents ls`, `devspace agents run`, -`devspace agents continue`, and `devspace agents show` workflow. The catalog +`devspace agents continue`, `devspace agents show`, and `devspace agents wait` +workflow. The catalog comes from `open_workspace`; `devspace agents ls` lists existing subagent sessions for that workspace. diff --git a/docs/configuration.md b/docs/configuration.md index 2ed489c97..ead8e21fc 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -133,6 +133,11 @@ Subagent providers are explicit. Omitted providers are disabled: "enabled": true, "model": "gpt-5.4", "effort": "high", + "command": "/opt/devspace/bin/codex-wrapper", + "env": { + "CODEX_HOME": "/home/alice/.codex-work", + "OPENAI_BASE_URL": "https://api.example.com/v1", + }, }, { "id": "claude", @@ -158,10 +163,26 @@ Profiles are loaded from `~/.devspace/agents/*.md` and project `.devspace/agents/*.md`. `devspace agents targets` prints the configured targets available in the current workspace. -Provider executable discovery remains process-scoped. The supported overrides -are `CODEX_COMMAND`, `CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`, -`COPILOT_COMMAND`, `GROK_COMMAND`, and `GROK_AGENT_PROFILE`. DevSpace does not -persist provider credentials. +`command` names one executable. DevSpace does not split shell arguments, so use +a wrapper executable when startup needs fixed arguments. `env` maps environment +variable names to literal string values and preserves empty strings. DevSpace +does not expand `$NAME` references in these values. + +Codex, Claude, Cursor, Copilot, and Grok accept `command` and `env`. OpenCode and +Pi are embedded, so their provider entries reject both fields. The daemon +inherits its startup environment, then overlays the provider's `env`. An +explicit `command` wins over both the inherited command override and a command +override placed in `env`. + +Existing process-level overrides remain supported: `CODEX_COMMAND`, +`CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`, `COPILOT_COMMAND`, +`GROK_COMMAND`, and `GROK_AGENT_PROFILE`. Provider configuration takes +precedence where the same value is set in both places. + +DevSpace writes `config.jsonc` with mode `0600`, but provider environment values +are still plain text on disk. Keep the file out of version control. Leave +credentials in the process environment if you do not want DevSpace to persist +them. ## Native artifact download diff --git a/docs/gotchas.md b/docs/gotchas.md index a43a59d68..2f8bb8e97 100644 --- a/docs/gotchas.md +++ b/docs/gotchas.md @@ -232,7 +232,7 @@ its managed `subagents` skill to `~/.devspace/skills/subagents/SKILL.md` and uses that copy instead of a package-manager path. The skill keeps the model-facing workflow to `devspace agents targets`, `devspace agents ls`, `devspace agents run`, -`devspace agents continue`, and `devspace agents show`. +`devspace agents continue`, `devspace agents show`, and `devspace agents wait`. Those commands automatically manage the internal local agent daemon; `devspace serve` is not a prerequisite. `devspace agents ls` lists existing subagent sessions, not profile diff --git a/docs/local-agent-daemon.md b/docs/local-agent-daemon.md index e1313b2db..f940cfa21 100644 --- a/docs/local-agent-daemon.md +++ b/docs/local-agent-daemon.md @@ -5,7 +5,7 @@ by the MCP server and not by an individual CLI invocation. The daemon is an internal implementation detail: the normal workflow remains: ```text -devspace agents run/continue/show/ls +devspace agents targets/run/continue/show/wait/ls │ ▼ devspace-agentd @@ -58,15 +58,24 @@ devspace agents daemon stop devspace agents daemon logs ``` -Agent commands accept `--json` when a machine-readable response is needed. -They emit one compact JSON value. `run` and `continue` return only the logical -agent ID and status, `ls` returns session summaries, and `show` returns the -response or structured failure for one agent. Internal workspace paths, -provider session IDs, timestamps, and prior responses are not included in list -or receipt output. Immediate failures are emitted as -`{ error: { code, message, retryable, ... } }` with a non-zero exit code. -Successful `daemon status` and `daemon stop` output the daemon status object, -and successful `daemon logs` output is `{ "logs": "" }`. +The client and daemon compare an internal revision of the provider +configuration. A client replaces an idle daemon when that configuration has +changed. It never stops a daemon with active work; the client returns the +retryable `DAEMON_CONFIG_CHANGED` error until that work finishes. The revision +is not included in status, logs, or agent command output. + +Model-facing agent commands emit compact XML fragments by default. Lists use +one fragment per item without a root wrapper, and empty lists print nothing. +`run` and `continue` return only the logical agent ID and status. `show` returns +an immediate snapshot. `wait` blocks for one or more agents and can return a +complete ordered snapshot at a caller-supplied timeout. It does not stream +individual completions. + +Internal turns, prompts, workspace paths, provider session IDs, timestamps, and +prior responses are not included. Immediate failures use an `` fragment +and a non-zero exit code. `--json` remains available for compatibility and +scripts. Daemon diagnostic commands keep their existing text and JSON output; +they do not use the model-facing XML format. Agent identity is explicit at the client boundary. `agents run` starts a new logical agent from a profile or provider; `agents continue ` continues an diff --git a/docs/setup.md b/docs/setup.md index b7c044d3b..9d1f7e97b 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -65,7 +65,7 @@ npx skills add Waishnav/devspace --skill subagents --global ``` The Skills CLI asks which installed Coding Agents should receive the skill. -The skill uses `devspace agents targets`, `run`, `continue`, `show`, and `ls`. +The skill uses `devspace agents targets`, `run`, `continue`, `show`, `wait`, and `ls`. These commands do not require `devspace serve`. This Coding Agent installation is separate from ChatGPT MCP usage. For MCP diff --git a/skills/subagents/SKILL.md b/skills/subagents/SKILL.md index 95ca378ed..ed137cf6f 100644 --- a/skills/subagents/SKILL.md +++ b/skills/subagents/SKILL.md @@ -7,49 +7,58 @@ description: Delegate focused coding, research, review, or verification work to Subagents are optional. Use the normal workspace tools for routine work; delegate only when a separate worker materially helps through independent context, specialization, or follow-up. -Use the DevSpace CLI through the shell or process tool. Run commands from the project the subagent should work on. +Run the DevSpace CLI through the shell or process tool from the project the subagent should use. Agent commands print compact XML fragments by default. Read that output directly. Do not add `--json`. ## Choose a target Discover usable targets instead of guessing names: ```bash -devspace agents targets --json +devspace agents targets ``` -Configured profiles include a description and may define provider, model, effort, and task instructions. Choose a matching profile when one fits. Use a provider target when no profile fits or a specific provider is needed. - -Usually rely on the target's configured model and effort. Pass `--model` or `--effort` only with a value supported by that provider. DevSpace passes these values through without translating them between providers. +Each line is a `` or `description` fragment. Prefer a matching profile. Use a provider target when no profile fits or the task needs a specific provider. Keep the configured model and effort unless the task requires a supported override. ## Start work -Give the subagent a self-contained brief. Include the objective, relevant paths, constraints, decisions it needs from the current conversation, and the expected result. The subagent receives the brief and its profile instructions, not the parent conversation. +Give the subagent a self-contained brief with the objective, relevant paths, constraints, context it cannot infer, and the expected result. The subagent receives this brief and its profile instructions, not the parent conversation. ```bash -devspace agents run "" --json -devspace agents run --model --effort "" --json +devspace agents run "" +devspace agents run --model --effort "" ``` -The result contains a DevSpace agent `id` and its current status. Execution continues independently, so retain the ID for later inspection or follow-up. +The command returns an `` receipt. Keep the DevSpace agent ID for inspection, waiting, or follow-up. + +## Wait or inspect -## Inspect and continue +Use `wait` when work must finish before you proceed. One call can wait for several agents: ```bash -devspace agents show --json -devspace agents continue "" --json -devspace agents ls --json +devspace agents wait +devspace agents wait +devspace agents wait --timeout 60 ``` -- `show` waits briefly for active work, then returns the current status and any - available response or error. -- `continue` gives the same subagent another turn with its existing provider - session and context. -- `ls` returns sessions belonging to the current project. +Without `--timeout`, the command waits until every named agent's current work finishes. A timeout returns one fragment per unique agent in first-seen order; unfinished work has `status="running" wait="timeout"`. Completed output is the element text. Failures include `code` and `retryable` attributes. The command does not stream partial results. + +Use `show` for an immediate snapshot. Do not poll it when `wait` can express the dependency. + +```bash +devspace agents show +devspace agents ls +``` -Run `devspace agents show --json` again later while the status is `running`. -`completed` includes the response. `failed` includes a structured error, and -`stopped` is terminal without a successful response. Continue an agent when its -existing context is useful; start another agent for unrelated work. +`ls` lists agents for the current project. Empty `targets` and `ls` results print nothing. + +## Continue related work + +Continue an agent when its existing provider context helps. Start another agent for unrelated work. + +```bash +devspace agents continue "" +devspace agents wait +``` ## Good uses diff --git a/src/cli.ts b/src/cli.ts index 775b5a1d2..28632996b 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -488,10 +488,12 @@ function printHelp(): void { " devspace config set publicBaseUrl ", " devspace worktrees prune Prune managed worktrees unused for 3 days", " devspace show-changes [--json]", + " devspace agents targets [--json] List usable subagent providers and profiles", " devspace agents ls List subagent sessions", " devspace agents run [--model ] [--effort ] ", " devspace agents continue [--model ] [--effort ] ", " devspace agents show ", + " devspace agents wait ... [--timeout ] [--json]", " devspace agents daemon ", " devspace -v, --version Print the installed version", "", From 84d3a7e3c7e8dc49f596949fbe3791d9af8d7974 Mon Sep 17 00:00:00 2001 From: Waishnav <86405648+Waishnav@users.noreply.github.com> Date: Mon, 31 Aug 2026 19:05:49 +0530 Subject: [PATCH 2/2] docs(agents): clarify target and JSON help --- skills/subagents/SKILL.md | 2 +- src/cli.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/subagents/SKILL.md b/skills/subagents/SKILL.md index ed137cf6f..5ef4f5bb7 100644 --- a/skills/subagents/SKILL.md +++ b/skills/subagents/SKILL.md @@ -17,7 +17,7 @@ Discover usable targets instead of guessing names: devspace agents targets ``` -Each line is a `` or `description` fragment. Prefer a matching profile. Use a provider target when no profile fits or the task needs a specific provider. Keep the configured model and effort unless the task requires a supported override. +Each line is a `` or `description` fragment. Pass the profile or provider `name` as ``. Prefer a matching profile. Use a provider target when no profile fits or the task needs a specific provider. Keep the configured model and effort unless the task requires a supported override. ## Start work diff --git a/src/cli.ts b/src/cli.ts index 28632996b..418350d83 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -492,7 +492,7 @@ function printHelp(): void { " devspace agents ls List subagent sessions", " devspace agents run [--model ] [--effort ] ", " devspace agents continue [--model ] [--effort ] ", - " devspace agents show ", + " devspace agents show [--json]", " devspace agents wait ... [--timeout ] [--json]", " devspace agents daemon ", " devspace -v, --version Print the installed version",