Merge pull request #101 from pr/dw-8-result-errors

refactor(workflow): model operational failures with better-result

Author: Waishnav

docs/chatgpt-coding-workflow.md

@@ -85,16 +85,17 @@ DevSpace discovers standard Agent Skills from:
 - project `.agents/skills`
 - `~/.devspace/skills`
 
-It also keeps compatibility with:
+It also includes:
 
-- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
+- the package-managed `subagents` skill when the Subagents capability is enabled
+- the package-managed `dynamic-workflows` skill when the Dynamic Workflows capability is enabled
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
 When Subagents are enabled, DevSpace discovers agent profiles
 from `~/.devspace/agents/*.md` and project `.devspace/agents/*.md`.
 `open_workspace` exposes a compact catalog with profile names, descriptions,
-providers, and optional models/thinking levels so the model can choose a configured agent
+providers, and optional models/effort levels so the model can choose a configured agent
 without seeing provider-specific launch details.
 
 Example profiles are packaged under `examples/agents/` for users who want
@@ -113,10 +114,15 @@ Skill paths may be outside the workspace. DevSpace only permits reading:
 
 Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Set
 `DEVSPACE_SUBAGENTS=1` to expose the experimental subagent catalog and
-`subagent-delegation` skill. That skill teaches the minimal
-`devspace agents ls`, `devspace agents run`, and `devspace agents show`
-workflow. The catalog comes from `open_workspace`; `devspace agents ls` lists
-existing subagent sessions for that workspace.
+`subagents` skill. That skill can use target information already supplied by the
+host or discover it with `devspace agents targets`. `devspace agents ls` lists
+existing subagent sessions for the current workspace.
+
+Set `DEVSPACE_WORKFLOWS=1` to enable Dynamic Workflows independently. When the
+variable is omitted, Dynamic Workflows follows the effective Subagents setting,
+including persisted config and any environment override. Disabled features are
+omitted from the `open_workspace` schema and response rather than returned as
+empty capability arrays.
 
 ## Tool Names
 
@@ -148,12 +154,22 @@ registered. `exec_command` returns a process session ID when a command is still
 running after its yield window. Use `write_stdin` to poll it, send input, resize
 a PTY, or send Ctrl-C. Set `tty: true` only for commands that need a terminal.
 
-## Show Changes
+## Widget UI and Show Changes
 
 By default, `DEVSPACE_WIDGETS=full`.
 
-In that mode, DevSpace attaches widget UI to the exposed workspace, file, edit,
-and shell tools. The aggregate `show_changes` tool is not exposed by default.
+In that mode, DevSpace attaches widget UI to the exposed workspace, workflow,
+file, edit, and shell tools. The `open_workspace` dropdown presents the opened
+root, loaded skills and instructions, available agent providers/profiles, and
+currently active workflows for that workspace.
+
+Dynamic Workflow views are read-only. They refresh through app-only MCP tools
+and show observed phases, agent calls, replay state, worktree isolation, errors,
+and recent activity. When the host supports MCP Apps fullscreen display mode,
+the card offers an **Open dashboard** presentation control. It does not add
+cancel, resume, apply, or cleanup actions.
+
+The aggregate `show_changes` tool is not exposed by default.
 
 Use `DEVSPACE_WIDGETS=off` to disable widget UI, or `DEVSPACE_WIDGETS=changes`
 to expose the aggregate show-changes flow.

docs/configuration.md

@@ -83,7 +83,7 @@ sessions.
 
 | Value | Behavior |
 | --- | --- |
-| `full` | Default. Widget UI is attached to exposed workspace, file, edit, and shell tools. |
+| `full` | Default. Widget UI is attached to exposed workspace, workflow, file, edit, and shell tools, including read-only live workflow dashboards. |
 | `changes` | Enables the aggregate `show_changes` tool and attaches widget UI to `open_workspace` and `show_changes`. |
 | `off` | Disables widget UI. |
 
@@ -93,6 +93,7 @@ sessions.
 | --- | --- |
 | `DEVSPACE_SKILLS` | Set to `0` to hide skills. Enabled by default. |
 | `DEVSPACE_SUBAGENTS` | Set to `1` to expose configured agent profiles as Subagents. Experimental and disabled by default. |
+| `DEVSPACE_WORKFLOWS` | Experimental Dynamic Workflows gate. When unset, it follows the effective Subagents setting, including persisted config and any environment override. |
 | `DEVSPACE_AGENT_DIR` | Defaults to `~/.codex`; its `skills` child is loaded for compatibility. |
 | `DEVSPACE_SKILL_PATHS` | Optional comma-separated additional skill directories. |
 
@@ -102,25 +103,35 @@ DevSpace discovers standard Agent Skills from:
 - project `.agents/skills`
 - `~/.devspace/skills`
 
-It also keeps compatibility with:
+It also includes:
 
-- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
+- the package-managed `subagents` skill when the Subagents capability is enabled
+- the package-managed `dynamic-workflows` skill when the Dynamic Workflows capability is enabled
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
+User and project skills with the same name take precedence over bundled skills.
+DevSpace does not copy bundled skills into `~/.devspace/skills` during setup.
+
 When Subagents are enabled, DevSpace discovers agent profiles
 from:
 
 - `~/.devspace/agents/*.md`
 - project `.devspace/agents/*.md`
 
 `open_workspace` returns a compact catalog containing profile names,
-descriptions, providers, and optional models/thinking levels so the host model can choose an
+descriptions, providers, and optional models/effort levels so the host model can choose an
 agent without reading provider-specific launch details. `devspace agents ls`
 lists existing subagent sessions for the current workspace, scoped by the
-workspace environment injected into shell commands. The `subagent-delegation`
-skill teaches the model to use only the minimal `devspace agents ls`,
-`devspace agents run`, and `devspace agents show` workflow.
+workspace environment injected into shell commands. The `subagents`
+skill teaches the model to discover targets with `devspace agents targets`,
+then use the minimal `devspace agents run`, `devspace agents show`, and
+`devspace agents ls` workflow.
+
+Provider availability is detected at runtime. DevSpace does not persist probe
+timestamps, availability snapshots, or an experimental provider enable-list in
+`config.json`. Final provider policy and onboarding are deferred until the
+Subagents and Dynamic Workflows features are finalized.
 
 Starter profile templates are available under `examples/agents/`. Copy or adapt
 them into one of the active profile directories before use.

docs/dynamic-workflow/devspace/plan.md

@@ -19,7 +19,7 @@ Subagents stay **CLI-only**. Workflows get **CLI + MCP** over shared primitives.
 | `budget` stub v1 | `{ total: null, spent: () => 0, remaining: () => Infinity }`. |
 | Dual surface | `devspace workflow *` **and** MCP `run_workflow` / `workflow_status` / `workflow_cancel`. |
 | All 6 providers v1 | codex/claude/opencode/pi/cursor/copilot via existing adapters. |
-| `agentProviders.enabled` | Ordered config from onboarding; default provider = first enabled ∩ live. |
+| Provider policy | Runtime uses currently available providers in stable product order. Durable provider policy and onboarding are deferred. |
 | Resume-by-replay right after engine core | Same milestone order as locked plan. |
 
 ---
@@ -119,28 +119,28 @@ runProvider({ provider, prompt, workspace, model, effort, providerSessionId? })
 - If product later wants unified list, add a flag — not v1.
 - `workspace` is either shared `workspaceRoot` or a managed worktree path when `opts.isolation === 'worktree'`.
 
-### 4.3 Provider resolution + config
+### 4.3 Provider resolution now; policy later
 
-Config add (see primitives-spec §3):
+Current experimental runtime:
 
-```ts
-agentProviders?: {
-  enabled: AgentProviderId[]   // order = preference; [0] = default
-  detectedAt?: string
-  lastProbe?: Array<{ id, available, detail? }>
-}
-```
+- Probe provider availability at execution time.
+- Resolve `opts.provider` → `meta.defaultProvider` → first available provider
+  in stable product order.
+- Keep probe timestamps and unavailable reasons in diagnostics only; do not
+  persist them in user configuration.
+- Unknown or unavailable explicit providers fail that `agent()` call.
 
-Algorithm: `opts.provider` → `meta.defaultProvider` → first of `enabled ∩ liveAvailable`.  
-Missing `agentProviders` → compat all-available in code order.  
-Onboarding (`init`/`doctor`) probes PATH and writes `enabled`.  
-Unknown/unavailable: fail that `agent()` (throw → parallel null).
+The final onboarding release may add an ordered array of provider policy
+objects with `id`, `enabled`, `defaultModel`, and `defaultEffort`. That contract
+is deliberately deferred so the workflow stack does not publish an unfinished
+configuration shape.
 
 ### 4.4 Skills gating fix (required, not optional)
 
-Today `effectiveSkillPaths` drops **entire** bundled dir if user has seeded `subagent-delegation` — hides any new bundled skill.
-
-v1: include bundled **per-skill** (user copy wins on name collision). Seed `dynamic-workflows` in `user-config` next to subagent skill.
+Bundled `subagents` and `dynamic-workflows` skills remain package-managed.
+User/project copies win on name collision. Setup does not copy bundled skills
+into `~/.devspace/skills`, which prevents generated copies from shadowing later
+package updates. The legacy `subagent-delegation` name is suppressed.
 
 ### 4.5 MCP vs CLI symmetry
 
@@ -240,9 +240,9 @@ Provider-native strings pass through unchanged.
 | **3 Engine** | `isolation` path with fake/temp git repos in tests |
 | **4 Worker+CLI** | real worktree create/cleanup; journal fields |
 | **5 Resume** | cache key includes isolation |
-| **8 Teach** | skill isolation + effort; seed `agentProviders` docs |
+| **8 Teach** | skill isolation + effort; document deferred provider policy |
 | Cross-cutting | rename `thinking`→`effort` in profile/CLI/store/adapters (can land with M3–4) |
-| Config | `agentProviders` on user-config + init probe (with M4 or M8) |
+| Config | Keep provider availability runtime-only until final onboarding. |
 
 ---
 
@@ -305,8 +305,8 @@ E2E: `npm test` + `npm run typecheck`; live fan-out 2 providers CLI; same MCP; c
 | `cli.ts` `spawnAgentWorker` / `agents __worker` | copy for `workflow __worker` |
 | `process-platform.terminateProcessTree` | hard cancel |
 | `db/client` WAL + busy_timeout 5000 | multi-process journal |
-| `server.ts` `registerAppTool` + `config.subagents` gate | tools only if subagents on |
-| `skills.ts` / `user-config.ts` | gate fix + seed |
+| `server.ts` `registerAppTool` + workflow capability gate | tools only if workflows are enabled |
+| `skills.ts` | independent package-managed skill gates |
 | `process-sessions` yield bounds | MCP status yield caps |
 
 ---
@@ -356,7 +356,7 @@ Do not open MCP before CLI smoke — debug path must work headless without a hos
 
 ## Resolved questions (see also [primitives-spec.md](./primitives-spec.md))
 
-1. **Default provider:** `opts.provider` → `meta.defaultProvider` → first of **onboarding-configured** `agentProviders.enabled` ∩ live available. Full config schema in primitives-spec §3.  
+1. **Default provider:** `opts.provider` → `meta.defaultProvider` → first live provider in stable product order. Final provider defaults and enablement are deferred to onboarding finalization.
 2. **writeMode:** **not in v1 API**; skill teaches prompt-based RO/write.  
 3. **Isolation:** **`isolation?: 'worktree'` is v1 must-have** on `agent()`; default shared; no auto-merge.  
 4. **Effort rename:** `thinking` → **`effort`** across profiles, CLI, store, adapters, `agent()` opts, cache keys.  
@@ -366,4 +366,4 @@ Do not open MCP before CLI smoke — debug path must work headless without a hos
 8. **Cancel:** cooperative flag → then group-kill.  
 
 **File-change tracking:** out of scope.  
-**Schema:** `opts.schema` + Ajv + retries — in scope.
+**Schema:** `opts.schema` + Ajv + retries — in scope.