From 3a4ccd7ac13464bacda41a3ef31f448fb17fbbf1 Mon Sep 17 00:00:00 2001 From: Code UX Date: Mon, 13 Jul 2026 14:42:56 +0000 Subject: [PATCH] feat(task T03): implement via codex --- docs-web/content/docs/developer-http-api.mdx | 4 ++-- docs-web/content/docs/user-dashboard-agents.mdx | 4 ++-- docs-web/developer/http-api.md | 4 ++-- docs-web/user/dashboard/agents.md | 4 ++-- docs/architecture/agent-preset-foundation.md | 2 +- docs/architecture/agent-sync-and-planning-agent.md | 2 +- docs/dashboard/dashboard-guide.md | 7 ++++--- 7 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs-web/content/docs/developer-http-api.mdx b/docs-web/content/docs/developer-http-api.mdx index 5460bf058f..4878ebd1bf 100644 --- a/docs-web/content/docs/developer-http-api.mdx +++ b/docs-web/content/docs/developer-http-api.mdx @@ -173,9 +173,9 @@ This page lists every endpoint, grouped by domain. Path parameters use `:name` n The GET response is an array of notices with `projectId`, `role`, `baseAgentPresetId`, `selectedAgentPresetId`, `selectedAgentName`, `reason`, `currentRevision`, and `availableRevision`. `reason` is `customized_instructions` or `alternate_route`. Planning and Project manager targets are resolved independently from `agents.routing.planning.agentPresetId` and `agents.routing.dashboardReply.agentPresetId`, using their named built-ins when the route value is null. Worker, Quality assurance agent, and Project Setup Agent are outside this contract. -POST requires a current notice and a supported local provider resolved through the `planning` invocation route. It records `agent_base_update` telemetry, sends the previous base, current bundle, and selected preset to the provider, and accepts exactly one raw JSON object containing one non-empty string property, `instructionMarkdown`. The validated result must retain every original selected-preset line in order. Immediately before writing, the service verifies that the selected routed preset still matches the notice. +POST requires a current notice and a supported local provider resolved through the `planning` invocation route. It records execution invocation type `agent_base_update` and sends the previous base, current bundle, and selected preset to the provider. The provider prompt requests raw JSON only, but the server parser tolerates supported presentation noise such as surrounding text, markdown fences, and provider response envelopes. After extraction, the payload must be a non-array JSON object containing exactly one non-empty string property, `instructionMarkdown`, and no other properties. Extraction, payload-shape, and line-preservation errors continue through the structured corrective retry path in the same provider session. The validated result must retain every original selected-preset line in order. Immediately before writing, the service verifies that the selected routed preset still matches the notice. -Only instruction markdown is writable, and only compatibility-critical system additions are requested. The main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, and source metadata remain unchanged. An invalid role returns `400`; an unknown project returns `404`; disabled endpoint wiring returns `404`. A missing or stale notice, unsupported provider, invalid response, or concurrent route change is rejected, while provider execution failures propagate as request errors. All failures occur before the preset write and bundled-revision advance. A successful response is the updated `AgentPresetRecord` and advances the selected preset's role revision even if its preserved markdown does not equal the current bundle. +Only instruction markdown is writable, and only compatibility-critical system additions are requested. The main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, and source metadata remain unchanged. An invalid role returns `400`; an unknown project returns `404`; disabled endpoint wiring returns `404`. A missing or stale notice, unsupported provider, malformed or destructive response, provider execution failure, or concurrent route change is rejected. Every failure leaves the preset instructions and stored bundled revision unchanged. A successful response is the updated `AgentPresetRecord` and advances the selected preset's role revision even if its preserved markdown does not equal the current bundle. ## Quicksprint templates diff --git a/docs-web/content/docs/user-dashboard-agents.mdx b/docs-web/content/docs/user-dashboard-agents.mdx index 1cf69e7492..79a4cf8790 100644 --- a/docs-web/content/docs/user-dashboard-agents.mdx +++ b/docs-web/content/docs/user-dashboard-agents.mdx @@ -86,9 +86,9 @@ When a selected built-in has not diverged from its tracked baseline, a newer bun The Agents page heading is **Planning agent base update available** or **Project manager base update available**. It explains whether the named preset has customized instructions or is assigned to that route, followed by: **Updating invokes an agent to compare both base files and apply only important system-compatibility instructions. Your main prompt, custom instructions, and behavior are preserved.** No merge runs until you choose **Update with AI**. -To apply a notice, the dashboard uses `POST /api/projects/:projectId/agent-presets/base-updates/:baseAgentRole/apply`, where the role must be `planning_agent` or `project_manager`. The endpoint consumes no request body and runs through the configured supported local planning provider. The agent compares the previous base, current bundle, and selected preset, and may add only compatibility-critical system instructions such as changed MCP or strict output-schema requirements. Code UX tolerates harmless presentation text, markdown fences, and supported provider response envelopes, but the extracted payload must still be a JSON object containing exactly one non-empty `instructionMarkdown` string and no other properties. It verifies that all original preset lines remain in order, rechecks that routing still selects the noticed preset, and writes the markdown itself only after parsing and safety checks succeed. +To apply a notice, the dashboard uses `POST /api/projects/:projectId/agent-presets/base-updates/:baseAgentRole/apply`, where the role must be `planning_agent` or `project_manager`. The endpoint consumes no request body, uses the configured supported local provider selected by the `planning` invocation route, and records execution type `agent_base_update`. The agent compares the previous base, current bundle, and selected preset, and may add only compatibility-critical system instructions such as changed MCP or strict output-schema requirements. Although the prompt requests raw JSON only, Code UX tolerates supported presentation noise such as surrounding text, markdown fences, and provider response envelopes. The extracted payload must still be a non-array JSON object containing exactly one non-empty `instructionMarkdown` string and no other properties. Extraction, payload-shape, and line-preservation errors receive a structured corrective retry in the same provider session. Code UX verifies that all original preset lines remain in order, rechecks that routing still selects the noticed preset, and writes the markdown itself only after parsing and safety checks succeed. -The merge cannot change the main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, or source metadata. A failed provider call, unsupported provider, malformed or destructive response, stale notice, or route change leaves both the preset and its stored bundled revision unchanged, so the notice remains available for retry. A successful merge records the current bundled revision even when the preserved custom markdown differs from the bundle, preventing the same notice from returning. +The merge cannot change the main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, or source metadata. A provider failure, unsupported provider, malformed or destructive response, missing or stale notice, or route change leaves both the preset instructions and its stored bundled revision unchanged, so the notice remains available for retry. A successful merge records the current bundled revision even when the preserved custom markdown differs from the bundle, preventing the same notice from returning. ## Deleting an agent diff --git a/docs-web/developer/http-api.md b/docs-web/developer/http-api.md index e678149c08..f4e1a6adc9 100644 --- a/docs-web/developer/http-api.md +++ b/docs-web/developer/http-api.md @@ -171,9 +171,9 @@ This page lists every endpoint, grouped by domain. Path parameters use `:name` n The GET response is an array of notices with `projectId`, `role`, `baseAgentPresetId`, `selectedAgentPresetId`, `selectedAgentName`, `reason`, `currentRevision`, and `availableRevision`. `reason` is `customized_instructions` or `alternate_route`. Planning and Project manager targets are resolved independently from `agents.routing.planning.agentPresetId` and `agents.routing.dashboardReply.agentPresetId`, using their named built-ins when the route value is null. Worker, Quality assurance agent, and Project Setup Agent are outside this contract. -POST requires a current notice and a supported local provider resolved through the `planning` invocation route. It records `agent_base_update` telemetry, sends the previous base, current bundle, and selected preset to the provider, and accepts exactly one raw JSON object containing one non-empty string property, `instructionMarkdown`. The validated result must retain every original selected-preset line in order. Immediately before writing, the service verifies that the selected routed preset still matches the notice. +POST requires a current notice and a supported local provider resolved through the `planning` invocation route. It records execution invocation type `agent_base_update` and sends the previous base, current bundle, and selected preset to the provider. The provider prompt requests raw JSON only, but the server parser tolerates supported presentation noise such as surrounding text, markdown fences, and provider response envelopes. After extraction, the payload must be a non-array JSON object containing exactly one non-empty string property, `instructionMarkdown`, and no other properties. Extraction, payload-shape, and line-preservation errors continue through the structured corrective retry path in the same provider session. The validated result must retain every original selected-preset line in order. Immediately before writing, the service verifies that the selected routed preset still matches the notice. -Only instruction markdown is writable, and only compatibility-critical system additions are requested. The main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, and source metadata remain unchanged. An invalid role returns `400`; an unknown project returns `404`; disabled endpoint wiring returns `404`. A missing or stale notice, unsupported provider, invalid response, or concurrent route change is rejected, while provider execution failures propagate as request errors. All failures occur before the preset write and bundled-revision advance. A successful response is the updated `AgentPresetRecord` and advances the selected preset's role revision even if its preserved markdown does not equal the current bundle. +Only instruction markdown is writable, and only compatibility-critical system additions are requested. The main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, and source metadata remain unchanged. An invalid role returns `400`; an unknown project returns `404`; disabled endpoint wiring returns `404`. A missing or stale notice, unsupported provider, malformed or destructive response, provider execution failure, or concurrent route change is rejected. Every failure leaves the preset instructions and stored bundled revision unchanged. A successful response is the updated `AgentPresetRecord` and advances the selected preset's role revision even if its preserved markdown does not equal the current bundle. ## Quicksprint templates diff --git a/docs-web/user/dashboard/agents.md b/docs-web/user/dashboard/agents.md index 5353b8c59d..a7d04b9415 100644 --- a/docs-web/user/dashboard/agents.md +++ b/docs-web/user/dashboard/agents.md @@ -86,9 +86,9 @@ When a selected built-in has not diverged from its tracked baseline, a newer bun The Agents page heading is **Planning agent base update available** or **Project manager base update available**. It explains whether the named preset has customized instructions or is assigned to that route, followed by: **Updating invokes an agent to compare both base files and apply only important system-compatibility instructions. Your main prompt, custom instructions, and behavior are preserved.** No merge runs until you choose **Update with AI**. -To apply a notice, the dashboard uses `POST /api/projects/:projectId/agent-presets/base-updates/:baseAgentRole/apply`, where the role must be `planning_agent` or `project_manager`. The endpoint consumes no request body and runs through the configured supported local planning provider. The agent compares the previous base, current bundle, and selected preset, and may add only compatibility-critical system instructions such as changed MCP or strict output-schema requirements. Code UX tolerates harmless presentation text, markdown fences, and supported provider response envelopes, but the extracted payload must still be a JSON object containing exactly one non-empty `instructionMarkdown` string and no other properties. It verifies that all original preset lines remain in order, rechecks that routing still selects the noticed preset, and writes the markdown itself only after parsing and safety checks succeed. +To apply a notice, the dashboard uses `POST /api/projects/:projectId/agent-presets/base-updates/:baseAgentRole/apply`, where the role must be `planning_agent` or `project_manager`. The endpoint consumes no request body, uses the configured supported local provider selected by the `planning` invocation route, and records execution type `agent_base_update`. The agent compares the previous base, current bundle, and selected preset, and may add only compatibility-critical system instructions such as changed MCP or strict output-schema requirements. Although the prompt requests raw JSON only, Code UX tolerates supported presentation noise such as surrounding text, markdown fences, and provider response envelopes. The extracted payload must still be a non-array JSON object containing exactly one non-empty `instructionMarkdown` string and no other properties. Extraction, payload-shape, and line-preservation errors receive a structured corrective retry in the same provider session. Code UX verifies that all original preset lines remain in order, rechecks that routing still selects the noticed preset, and writes the markdown itself only after parsing and safety checks succeed. -The merge cannot change the main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, or source metadata. A failed provider call, unsupported provider, malformed or destructive response, stale notice, or route change leaves both the preset and its stored bundled revision unchanged, so the notice remains available for retry. A successful merge records the current bundled revision even when the preserved custom markdown differs from the bundle, preventing the same notice from returning. +The merge cannot change the main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, or source metadata. A provider failure, unsupported provider, malformed or destructive response, missing or stale notice, or route change leaves both the preset instructions and its stored bundled revision unchanged, so the notice remains available for retry. A successful merge records the current bundled revision even when the preserved custom markdown differs from the bundle, preventing the same notice from returning. ## Deleting an agent diff --git a/docs/architecture/agent-preset-foundation.md b/docs/architecture/agent-preset-foundation.md index d37e45a998..cc59632e34 100644 --- a/docs/architecture/agent-preset-foundation.md +++ b/docs/architecture/agent-preset-foundation.md @@ -95,7 +95,7 @@ Dashboard endpoints: Base-agent updates are limited to `planning_agent` and `project_manager`. The notice endpoint performs no provider work; it reports only changed bundled baselines that cannot be applied automatically because the selected preset has custom instructions or the role is routed to an alternate preset. -Applying a notice uses the existing `planning` virtual-provider route and structured invocation pipeline, recorded as execution invocation type `agent_base_update`. The provider receives the previous bundled/base instructions, current bundled instructions, and the selected preset instructions, but is restricted to returning one JSON property: `instructionMarkdown`. The parser tolerates presentation text, markdown fences, and the shared extractor's supported provider envelopes, then still requires the extracted payload to be a non-array object with exactly one non-empty string property named `instructionMarkdown`. Its prompt permits only compatibility-critical additions, such as changed MCP or JSON-schema rules, and forbids workspace writes or metadata changes. Code UX verifies the original preset remains line-for-line and in order before applying only instruction markdown through `AgentPresetSyncService`; avatar, labels, routing, provider/model, memory, MCP access, persistent skills, and source metadata remain unchanged. Extraction, payload validation, and preservation checks all complete before persistence. The stored bundled revision advances only after provider execution and parsing succeed, and the selected preset ID is checked again immediately before application to prevent a concurrent route change from redirecting the result. +Applying a notice uses the existing `planning` virtual-provider route and structured invocation pipeline, recorded as execution invocation type `agent_base_update`. The provider receives the previous bundled/base instructions, current bundled instructions, and the selected preset instructions, but is restricted to returning one JSON property: `instructionMarkdown`. Although the prompt requests raw JSON only, the server parser tolerates supported presentation noise such as surrounding text, markdown fences, and the shared extractor's provider envelopes. After extraction, the payload must still be a non-array object with exactly one non-empty string property named `instructionMarkdown`. Extraction, payload-shape, and line-preservation errors continue through the structured corrective retry path in the same provider session. The merge prompt permits only compatibility-critical additions, such as changed MCP or JSON-schema rules, and forbids workspace writes or metadata changes. Code UX verifies the original preset remains line-for-line and in order before applying only instruction markdown through `AgentPresetSyncService`; avatar, labels, routing, provider/model, memory, MCP access, persistent skills, and source metadata remain unchanged. All parsing and preservation checks complete before persistence, and the selected preset ID is checked again immediately before application to prevent a concurrent route change from redirecting the result. Malformed or destructive output, a missing or stale notice, an unsupported provider, a provider failure, or a concurrent route change leaves both the preset instructions and stored bundled revision unchanged. The revision advances only after provider execution, parsing, safety validation, and application succeed. These endpoints are project-scoped and intentionally separate from: diff --git a/docs/architecture/agent-sync-and-planning-agent.md b/docs/architecture/agent-sync-and-planning-agent.md index 58f81940f4..4d354218ce 100644 --- a/docs/architecture/agent-sync-and-planning-agent.md +++ b/docs/architecture/agent-sync-and-planning-agent.md @@ -77,7 +77,7 @@ Dashboard edits, sqlite-only edits, and project markdown edits that diverge from The Agents page discovers notices with `GET /api/projects/:projectId/agent-presets/base-updates`. The GET performs normal agent synchronization, which may auto-apply an untouched built-in update, but it does not invoke a provider. Its response contains only the remaining notices that need an explicit merge. `POST /api/projects/:projectId/agent-presets/base-updates/:baseAgentRole/apply` accepts only `planning_agent` or `project_manager`, requires an existing notice, and invokes the configured local planning-provider route with execution type `agent_base_update`. -The provider compares the previous base, current bundle, and selected preset, but may return only raw JSON with one non-empty `instructionMarkdown` property. The merge prompt permits only compatibility-critical system additions, such as changed MCP usage or strict output-schema rules. Server validation requires every original selected-preset line to remain in order; Code UX itself writes the validated markdown through `AgentPresetSyncService`. The provider cannot update the main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, or source metadata. Before writing, the service verifies that the selected route still points to the preset named by the notice. Provider failure, unsupported provider selection, malformed or destructive output, a missing/stale notice, or a concurrent route change leaves the preset instructions and stored bundled revision unchanged. A successful merge advances the selected preset's role revision to the current bundle even when its compatibility-only markdown intentionally differs from the bundle, so the same notice does not recur. +The provider compares the previous base, current bundle, and selected preset. Its prompt requests raw JSON with one non-empty `instructionMarkdown` property, while the server parser also accepts supported presentation noise such as surrounding text, markdown fences, and provider response envelopes. After extraction, validation still requires a non-array JSON object containing exactly that one non-empty string property and no others. Extraction, payload-shape, and preservation failures continue through the structured corrective retry path in the same provider session. The merge prompt permits only compatibility-critical system additions, such as changed MCP usage or strict output-schema rules. Server validation requires every original selected-preset line to remain in order; Code UX itself writes the validated markdown through `AgentPresetSyncService`. The provider cannot update the main prompt, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, or source metadata. Before writing, the service verifies that the selected route still points to the preset named by the notice. Malformed or destructive output, a missing or stale notice, unsupported provider selection, provider failure, or a concurrent route change leaves the preset instructions and stored bundled revision unchanged. A successful merge advances the selected preset's role revision to the current bundle even when its compatibility-only markdown intentionally differs from the bundle, so the same notice does not recur. ## Agent Metadata diff --git a/docs/dashboard/dashboard-guide.md b/docs/dashboard/dashboard-guide.md index 29563c82f1..b0a468888c 100644 --- a/docs/dashboard/dashboard-guide.md +++ b/docs/dashboard/dashboard-guide.md @@ -106,9 +106,10 @@ Project management: - Each remaining notice identifies the actual routed target with `selectedAgentPresetId` and `selectedAgentName`, and uses reason `customized_instructions` or `alternate_route`; this read does not invoke a provider - `POST /api/projects/:projectId/agent-presets/base-updates/:baseAgentRole/apply` - Consumes no request body; `baseAgentRole` must be `planning_agent` or `project_manager`, and a current notice must exist - - Explicitly invokes the configured supported local provider through the `planning` route and records execution type `agent_base_update`; the provider must return raw JSON containing only a non-empty `instructionMarkdown` + - Explicitly invokes the configured supported local provider through the `planning` route and records execution type `agent_base_update`; the prompt requests raw JSON, while the parser tolerates supported surrounding text, markdown fences, and provider envelopes before requiring exactly one non-empty `instructionMarkdown` string and no other properties + - Extraction, payload-shape, and line-preservation errors use the structured corrective retry path in the same provider session - Validation preserves every line of the selected preset in order and allows only compatibility-critical system-instruction additions. `AgentPresetSyncService` applies the markdown after rechecking the routed preset, while prompts, custom behavior, avatar, labels, routing, provider/model, memory, MCP access, persistent skills, and source metadata remain unchanged - - Invalid roles, missing or stale notices, unsupported providers, provider failures, invalid output, and concurrent route changes fail without changing the preset or advancing its stored bundled revision + - Invalid roles, missing or stale notices, unsupported providers, provider failures, malformed or destructive output, and concurrent route changes fail without changing the preset instructions or advancing its stored bundled revision - `POST /api/projects/:projectId/planning/improve-sprint-prompt` - Sends a draft sprint prompt to the Planning agent through the configured virtual worker provider and returns the improved prompt - Planning overrides may explicitly target a specific `planningAgentPresetId`, as well as a virtual CLI provider/model for that one request. The composer defaults to the project Agent Routing planning preset. @@ -572,7 +573,7 @@ Legacy runtime: - Worker prompt preparation honors that memory config at runtime by filtering injected memories after retrieval, so the prompt only includes the configured tier(s), categories, strength thresholds, and per-tier caps. - Agents page is DB-backed and manages project-scoped agents (`name`, `short routing description`, `instruction markdown`, `memory template markdown`) - Agents page checks for bundled Planning agent and Project manager compatibility notices without invoking a provider. Untouched selected built-ins update automatically; customized presets and alternate Planning/dashboard-reply route targets receive an amber notice naming the actual selected preset and an explicit **Update with AI** action. -- The notice explains that the agent compares both base files and applies only important system-compatibility instructions while preserving the main prompt, custom instructions, and behavior. The guarded merge cannot change agent metadata, and failure leaves the notice available for retry. +- The notice explains that the agent compares both base files and applies only important system-compatibility instructions while preserving the main prompt, custom instructions, and behavior. Supported JSON presentation noise is extracted before strict one-property validation, and parsing errors receive a structured same-session retry. The guarded merge cannot change agent metadata; malformed, destructive, stale, unsupported-provider, provider-failure, and route-change cases leave both the preset and bundled revision unchanged so the notice remains available for retry. - Agents are auto-imported from project and home `.code-ux/agents/*.md` when first discovered - Project-local markdown mirroring is enabled by default through project settings, so dashboard edits create/update `.code-ux/agents/*.md` in the selected repo without touching shipped defaults - Markdown-backed agents now show sync state and support single-agent `Import`, roster-level `Pull from files`, roster-level `Push to files`, and single-agent `Push to file`; sqlite remains the live authority, pull copies file content into sqlite, and push exports sqlite presets to project files