@acryldev/plugin-context 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +12 -2
- package/docs/README.md +160 -0
- package/docs/delivery/local-live.md +113 -0
- package/docs/delivery/marketplace.md +16 -0
- package/docs/docs.json +2836 -0
- package/docs/extending/agent-preset.md +37 -0
- package/docs/extending/chat-command.md +28 -0
- package/docs/extending/client-slot.md +135 -0
- package/docs/extending/config-schema.md +7 -0
- package/docs/extending/cordis-core.md +63 -0
- package/docs/extending/desktop-app.md +53 -0
- package/docs/extending/desktop-main.md +25 -0
- package/docs/extending/event-hook.md +14 -0
- package/docs/extending/host-route.md +33 -0
- package/docs/extending/llm-adapter.md +38 -0
- package/docs/extending/packaging.md +53 -0
- package/docs/extending/prompt-contribution.md +9 -0
- package/docs/extending/service.md +13 -0
- package/docs/extending/skill-provider.md +9 -0
- package/docs/extending/state-and-persistence.md +71 -0
- package/docs/extending/three-role-capability.md +33 -0
- package/docs/extending/tool-plugin.md +24 -0
- package/docs/extending/tui-command.md +8 -0
- package/docs/extending/tui-components.md +61 -0
- package/docs/extending/ui-branding.md +43 -0
- package/docs/extending/ui-components.md +56 -0
- package/docs/extending/ui-customization.md +41 -0
- package/docs/extending/ui-library.md +66 -0
- package/docs/extending/ui-theme.md +55 -0
- package/docs/extending/workspace-tab.md +50 -0
- package/docs/maps/events.md +108 -0
- package/docs/maps/mount-points.md +154 -0
- package/docs/maps/slot-contracts.md +3376 -0
- package/docs/maps/taxonomy.md +306 -0
- package/docs/maps/theme-tokens.md +115 -0
- package/docs/maps/ui-components.md +26 -0
- package/docs/reference/cookbook/adding-a-package.md +174 -0
- package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
- package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
- package/docs/reference/cookbook/adding-a-tool.md +103 -0
- package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
- package/docs/reference/cookbook/extension-cookbook.md +134 -0
- package/docs/reference/cordis-api/context.md +366 -0
- package/docs/reference/cordis-api/events.md +209 -0
- package/docs/reference/cordis-api/fiber.md +377 -0
- package/docs/reference/cordis-api/inherited.md +40 -0
- package/docs/reference/cordis-api/registry.md +154 -0
- package/docs/reference/cordis-api/service.md +104 -0
- package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
- package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
- package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
- package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
- package/docs/reference/harness/agent-lifecycle.md +93 -0
- package/docs/reference/harness/architecture.md +168 -0
- package/docs/reference/harness/capability-seams.md +675 -0
- package/docs/reference/harness/config-catalog.md +4523 -0
- package/docs/reference/harness/cordis-primer.md +47 -0
- package/docs/reference/harness/defensive-patterns.md +35 -0
- package/docs/reference/harness/event-producer-consumer.md +111 -0
- package/docs/reference/harness/glossary.md +47 -0
- package/docs/reference/harness/tool-catalog.md +2721 -0
- package/docs/reference/harness/tool-execution-pipeline.md +67 -0
- package/docs/reference/subsystems/README.md +75 -0
- package/docs/reference/subsystems/agent-team.md +233 -0
- package/docs/reference/subsystems/approval.md +172 -0
- package/docs/reference/subsystems/attachment.md +363 -0
- package/docs/reference/subsystems/boot.md +324 -0
- package/docs/reference/subsystems/browser-use.md +69 -0
- package/docs/reference/subsystems/client-modules.md +186 -0
- package/docs/reference/subsystems/client-resources.md +94 -0
- package/docs/reference/subsystems/commands.md +225 -0
- package/docs/reference/subsystems/compaction.md +286 -0
- package/docs/reference/subsystems/computer-use.md +58 -0
- package/docs/reference/subsystems/conversation.md +287 -0
- package/docs/reference/subsystems/core.md +1107 -0
- package/docs/reference/subsystems/credentials.md +497 -0
- package/docs/reference/subsystems/deliverables.md +180 -0
- package/docs/reference/subsystems/extensions.md +386 -0
- package/docs/reference/subsystems/feedback.md +402 -0
- package/docs/reference/subsystems/filesystem.md +532 -0
- package/docs/reference/subsystems/goal.md +315 -0
- package/docs/reference/subsystems/invariants.md +90 -0
- package/docs/reference/subsystems/jobs.md +501 -0
- package/docs/reference/subsystems/llm-streaming.md +1131 -0
- package/docs/reference/subsystems/lsp.md +204 -0
- package/docs/reference/subsystems/mcp.md +141 -0
- package/docs/reference/subsystems/office-to-pdf.md +89 -0
- package/docs/reference/subsystems/otel.md +46 -0
- package/docs/reference/subsystems/permission-presets.md +169 -0
- package/docs/reference/subsystems/persistence.md +418 -0
- package/docs/reference/subsystems/plan.md +89 -0
- package/docs/reference/subsystems/product-telemetry.md +81 -0
- package/docs/reference/subsystems/ptc-runtime.md +234 -0
- package/docs/reference/subsystems/sandbox.md +223 -0
- package/docs/reference/subsystems/schedule.md +545 -0
- package/docs/reference/subsystems/scope.md +61 -0
- package/docs/reference/subsystems/session-projection.md +358 -0
- package/docs/reference/subsystems/session-query.md +511 -0
- package/docs/reference/subsystems/session-reference.md +226 -0
- package/docs/reference/subsystems/session-telemetry.md +214 -0
- package/docs/reference/subsystems/session-title.md +206 -0
- package/docs/reference/subsystems/session.md +1300 -0
- package/docs/reference/subsystems/settings.md +157 -0
- package/docs/reference/subsystems/shell.md +316 -0
- package/docs/reference/subsystems/sidebar-right.md +160 -0
- package/docs/reference/subsystems/skills.md +354 -0
- package/docs/reference/subsystems/slots.md +201 -0
- package/docs/reference/subsystems/spill.md +126 -0
- package/docs/reference/subsystems/ssh.md +137 -0
- package/docs/reference/subsystems/storage.md +262 -0
- package/docs/reference/subsystems/subagent.md +762 -0
- package/docs/reference/subsystems/subprocess.md +323 -0
- package/docs/reference/subsystems/system-prompt.md +226 -0
- package/docs/reference/subsystems/terminal.md +186 -0
- package/docs/reference/subsystems/todo.md +34 -0
- package/docs/reference/subsystems/token-meter.md +108 -0
- package/docs/reference/subsystems/tools.md +749 -0
- package/docs/reference/subsystems/typert.md +489 -0
- package/docs/reference/subsystems/user-questions.md +309 -0
- package/docs/reference/subsystems/voice-input.md +166 -0
- package/docs/reference/subsystems/web-client.md +102 -0
- package/docs/reference/subsystems/web-server.md +228 -0
- package/docs/reference/subsystems/web.md +208 -0
- package/docs/reference/subsystems/webhook.md +72 -0
- package/docs/reference/subsystems/workflow.md +280 -0
- package/docs/reference/subsystems/workspace.md +661 -0
- package/docs/start-here/blueprints.md +33 -0
- package/docs/start-here/this-runtime.md +84 -0
- package/docs/start-here/troubleshooting.md +29 -0
- package/docs/start-here/trust-and-safety.md +39 -0
- package/docs/start-here/verify-before-done.md +46 -0
- package/example-plugins/README.md +45 -0
- package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
- package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
- package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
- package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
- package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
- package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
- package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
- package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
- package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/chat-command-basic/index.js +26 -0
- package/example-plugins/packages/chat-command-basic/package.json +25 -0
- package/example-plugins/packages/client-chat-message-action/client.js +46 -0
- package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-chat-message-action/index.js +9 -0
- package/example-plugins/packages/client-chat-message-action/package.json +31 -0
- package/example-plugins/packages/client-slot-header-action/client.js +57 -0
- package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-slot-header-action/index.js +13 -0
- package/example-plugins/packages/client-slot-header-action/package.json +31 -0
- package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
- package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
- package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
- package/example-plugins/packages/client-theme-override/client.js +52 -0
- package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-theme-override/index.js +9 -0
- package/example-plugins/packages/client-theme-override/package.json +30 -0
- package/example-plugins/packages/client-tool-view/client.js +47 -0
- package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-tool-view/index.js +24 -0
- package/example-plugins/packages/client-tool-view/package.json +34 -0
- package/example-plugins/packages/client-ui-components/client.js +77 -0
- package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-ui-components/index.js +9 -0
- package/example-plugins/packages/client-ui-components/package.json +31 -0
- package/example-plugins/packages/client-ui-library/client.js +715 -0
- package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-ui-library/index.js +9 -0
- package/example-plugins/packages/client-ui-library/package.json +37 -0
- package/example-plugins/packages/client-workspace-tab/client.js +72 -0
- package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-workspace-tab/index.js +9 -0
- package/example-plugins/packages/client-workspace-tab/package.json +30 -0
- package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/config-schema-basic/index.js +19 -0
- package/example-plugins/packages/config-schema-basic/package.json +25 -0
- package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
- package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
- package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
- package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/event-hook-basic/index.js +17 -0
- package/example-plugins/packages/event-hook-basic/package.json +22 -0
- package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
- package/example-plugins/packages/generated-capability-template/index.js +16 -0
- package/example-plugins/packages/generated-capability-template/package.json +42 -0
- package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/host-route-basic/index.js +20 -0
- package/example-plugins/packages/host-route-basic/package.json +29 -0
- package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
- package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
- package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
- package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
- package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
- package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
- package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
- package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
- package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
- package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
- package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
- package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
- package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
- package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
- package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
- package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
- package/example-plugins/packages/service-provider-greeter/index.js +22 -0
- package/example-plugins/packages/service-provider-greeter/package.json +25 -0
- package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/settings-section-basic/index.js +34 -0
- package/example-plugins/packages/settings-section-basic/package.json +26 -0
- package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/skill-provider-basic/index.js +31 -0
- package/example-plugins/packages/skill-provider-basic/package.json +22 -0
- package/example-plugins/packages/state-host-store/client.js +57 -0
- package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
- package/example-plugins/packages/state-host-store/index.js +90 -0
- package/example-plugins/packages/state-host-store/package.json +31 -0
- package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
- package/example-plugins/packages/state-workspace-file/index.js +52 -0
- package/example-plugins/packages/state-workspace-file/package.json +25 -0
- package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/tool-basic/index.js +25 -0
- package/example-plugins/packages/tool-basic/package.json +25 -0
- package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
- package/example-plugins/packages/tool-policy-hook/index.js +28 -0
- package/example-plugins/packages/tool-policy-hook/package.json +25 -0
- package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-command-basic/index.js +24 -0
- package/example-plugins/packages/tui-command-basic/package.json +22 -0
- package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
- package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
- package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-ui-library/index.js +73 -0
- package/example-plugins/packages/tui-ui-library/package.json +29 -0
- package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
- package/example-plugins/packages/web-page-branding/index.js +31 -0
- package/example-plugins/packages/web-page-branding/package.json +22 -0
- package/example-plugins/scenarios.json +11 -0
- package/index.js +384 -0
- package/lib/blend-apply.js +107 -0
- package/lib/blend-capture.js +249 -0
- package/lib/blend-ledger.js +76 -0
- package/lib/contract.js +5 -0
- package/lib/install.js +516 -0
- package/lib/lookup.js +67 -0
- package/lib/manifest.js +56 -0
- package/lib/pack-root.js +22 -0
- package/lib/provenance.js +110 -0
- package/lib/publish.js +64 -0
- package/lib/reconcile.js +83 -0
- package/lib/router.js +55 -0
- package/lib/scopes.js +82 -0
- package/lib/skills.js +54 -0
- package/lib/stage.js +157 -0
- package/lib/verify.js +77 -0
- package/package.json +58 -3
- package/scripts/lib/indexes.mjs +45 -0
- package/scripts/lib/manifest.mjs +127 -0
- package/scripts/lib/maps.mjs +482 -0
- package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
- package/skills/acryl-add-ui/SKILL.md +18 -0
- package/skills/acryl-build-plugin/SKILL.md +21 -0
- package/skills/acryl-change-plugin/SKILL.md +16 -0
- package/skills/acryl-desktop-shell/SKILL.md +12 -0
- package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
- package/skills/acryl-fix-plugin/SKILL.md +12 -0
- package/skills/acryl-improve-ui/SKILL.md +10 -0
- package/skills/acryl-remove-plugin/SKILL.md +11 -0
- package/skills/acryl-restyle-ui/SKILL.md +14 -0
- package/skills/acryl-share-plugin/SKILL.md +23 -0
- package/skills/acryl-tui-ui/SKILL.md +12 -0
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/tool-execution-pipeline.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
|
|
4
|
+
Run `pnpm run gen-doc-graphs` to regenerate. -->
|
|
5
|
+
|
|
6
|
+
# Tool Execution Pipeline
|
|
7
|
+
|
|
8
|
+
This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
|
|
9
|
+
|
|
10
|
+
```mermaid
|
|
11
|
+
flowchart TD
|
|
12
|
+
model["Assistant message contains tool-call block"]
|
|
13
|
+
toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
|
|
14
|
+
presentCall["UI pending card<br/>presentCall(args)"]
|
|
15
|
+
pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
|
|
16
|
+
guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
|
|
17
|
+
denied["denied or approval refused<br/>tool body skipped"]
|
|
18
|
+
approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
|
|
19
|
+
around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
|
|
20
|
+
toolBody["Registered tool execute() body"]
|
|
21
|
+
fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
|
|
22
|
+
owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
|
|
23
|
+
project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
|
|
24
|
+
post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
|
|
25
|
+
normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
|
|
26
|
+
finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
|
|
27
|
+
final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
|
|
28
|
+
context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
|
|
29
|
+
toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
|
|
30
|
+
allResults["Tool batch settled<br/>recorded tool/result events complete"]
|
|
31
|
+
presentResult["UI completed card<br/>presentResult(args, result)"]
|
|
32
|
+
model --> toolCall
|
|
33
|
+
toolCall --> presentCall
|
|
34
|
+
toolCall --> pre
|
|
35
|
+
pre -->|allow| guards
|
|
36
|
+
guards -->|allow| around
|
|
37
|
+
guards -->|deny| denied
|
|
38
|
+
guards -.->|throw| normalized
|
|
39
|
+
around --> toolBody
|
|
40
|
+
pre -->|deny| denied
|
|
41
|
+
pre -->|ask| approval
|
|
42
|
+
approval -->|allowed-once| guards
|
|
43
|
+
approval -->|rejected, cancelled, unavailable| denied
|
|
44
|
+
approval -.->|throw| normalized
|
|
45
|
+
denied --> project
|
|
46
|
+
pre -.->|throw| normalized
|
|
47
|
+
toolBody --> fsGate
|
|
48
|
+
fsGate --> toolBody
|
|
49
|
+
toolBody --> owned
|
|
50
|
+
toolBody --> around
|
|
51
|
+
around --> project
|
|
52
|
+
project --> post
|
|
53
|
+
project -.->|throw| normalized
|
|
54
|
+
around -.->|wrapper throws| normalized
|
|
55
|
+
post -.->|throw| normalized
|
|
56
|
+
post --> finalize
|
|
57
|
+
normalized --> finalize
|
|
58
|
+
finalize --> final
|
|
59
|
+
final --> toolResult
|
|
60
|
+
toolResult --> presentResult
|
|
61
|
+
toolResult --> allResults
|
|
62
|
+
allResults --> context
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
|
|
66
|
+
|
|
67
|
+
Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/README.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Subsystems
|
|
4
|
+
|
|
5
|
+
English | [中文](README.zh.md)
|
|
6
|
+
|
|
7
|
+
One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and - where a `ctx` service or event scope backs it - a generated **Cordis API** section carrying its service and event reference. The folder complements [architecture.md](../architecture.md), which describes *behavior* across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring.
|
|
8
|
+
|
|
9
|
+
| Page | Owns |
|
|
10
|
+
|---|---|
|
|
11
|
+
| [boot.md](boot.md) | Current-profile plugin management and launcher reload coordination |
|
|
12
|
+
| [core.md](core.md) | how `packages/core` controls the agent loop: the package-by-package loop description, agent creation and ownership (`AgentHandle`), the `Agent` handle's delivery/cancellation/interception contracts, and the repo-wide type patterns (`…Map → derived-union`, branded ids) |
|
|
13
|
+
| [llm-streaming.md](llm-streaming.md) | the `packages/llm` conversation types - `Message`/`ContentBlock`, the assembled model request, the `StreamChunk` wire protocol and adapter contract, `BlockAssembler`, and the `LlmAdapter` provider contract |
|
|
14
|
+
| [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
|
|
15
|
+
| [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
|
|
16
|
+
| [typert.md](typert.md) | Remote invocation descriptors, lookup/Context declarations, Typert registries, and the Host Gateway/Client API boundaries |
|
|
17
|
+
| [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution |
|
|
18
|
+
| [schedule.md](schedule.md) | Host-owned reminder records, durable transitions, active and ended views, and ordinary-conversation delivery |
|
|
19
|
+
| [todo.md](todo.md) | the todo package's whole-list item type, durable event ownership, projection, and open-turn invariant |
|
|
20
|
+
| [deliverables.md](deliverables.md) | what a turn hands to the user: `PresentedFile` deliveries from `present` and the Host-served `WorkspaceChangesSummary` of changed files from git snapshots |
|
|
21
|
+
| [commands.md](commands.md) | the human-command registry service: definitions, adapter discovery, direct invocation, results, and parsing views |
|
|
22
|
+
| [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events |
|
|
23
|
+
| [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, the JSONL provider, `session/flush`, crash recovery, `SessionHeader` |
|
|
24
|
+
| [settings.md](settings.md) | the user-settings seam: `SettingsNamespace` registration, layered resolution (defaults → composition `base` → user document), owner scopes, hot commits |
|
|
25
|
+
| [credentials.md](credentials.md) | the credential seam: `CredentialRef` references (never values) in configuration, per-operation resolution, UI-safe `CredentialInfo`, provider source layers |
|
|
26
|
+
| [session-query.md](session-query.md) | logical records, bounded exact-event reads, relationship traces, semantic filters/documents, and full-text result pages |
|
|
27
|
+
| [feedback.md](feedback.md) | lifecycle-bound per-message feedback records, optimistic versions, sidecar persistence, and the Host Remote contract |
|
|
28
|
+
| [session-title.md](session-title.md) | durable title snapshots, cited source-message seqs, and the asynchronous provider contract |
|
|
29
|
+
| [session-reference.md](session-reference.md) | structured cross-session references: `SessionReferenceInput`/`Candidate`, prepared message contexts, the stable error taxonomy |
|
|
30
|
+
| [system-prompt.md](system-prompt.md) | per-assembly context, tool-provider results, prompt sections, and cooperative assembly |
|
|
31
|
+
| [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, and the guarded execution pipeline |
|
|
32
|
+
| [mcp.md](mcp.md) | external MCP connections, scoped tools and resources, server instructions, protocol results, and configuration ownership |
|
|
33
|
+
| [user-questions.md](user-questions.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
|
|
34
|
+
| [approval.md](approval.md) | the one-shot user-approval seam: `ApprovalRequest`, `ApprovalOutcome`, per-session policy, audit events, and answerer contracts |
|
|
35
|
+
| [office-to-pdf.md](office-to-pdf.md) | authorized Office-to-PDF conversion, native/WASM engines, and bounded shared reuse |
|
|
36
|
+
| [attachment.md](attachment.md) | durable image identity and metadata, validation inputs, verified reads, and the `AttachmentStore` seam |
|
|
37
|
+
| [shell.md](shell.md) | the shell executor seam: `ShellExecRequest`/`Spec`, `ShellRunResult`, background `ShellProcess` handles |
|
|
38
|
+
| [subprocess.md](subprocess.md) | the subprocess seam: fully-explicit `SubprocessSpawnSpec`, offset-based output readers, unclassified `SubprocessOutcome`, and the managed `DSH_*` environment vocabulary |
|
|
39
|
+
| [ssh.md](ssh.md) | the POSIX SSH connection and remote filesystem, subprocess and sandbox providers |
|
|
40
|
+
| [terminal.md](terminal.md) | persistent terminal ids, backend/session contracts, send readiness, bounded reads, and owner-visible snapshots |
|
|
41
|
+
| [sandbox.md](sandbox.md) | per-session policy resolution and the process-confinement seam: file-effect modes, execution/provider policies, `ConfinedArgv`, enforcement and fail-closed errors |
|
|
42
|
+
| [ptc-runtime.md](ptc-runtime.md) | the PTC execution seam: `PtcRunRequest`/`Result`, binding namespaces, captured logs, the `PtcRunFailure` taxonomy |
|
|
43
|
+
| [computer-use.md](computer-use.md) | exclusive named computer-use provider registration and Cua Driver integration choices |
|
|
44
|
+
| [browser-use.md](browser-use.md) | exclusive named browser-use registration, provider choices, and per-Session browser ownership |
|
|
45
|
+
| [extensions.md](extensions.md) | versioned dynamic Cordis Plugins and Packages, Host/Client activation, approval, runtime inspection, and lifecycle teardown |
|
|
46
|
+
| [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
|
|
47
|
+
| [lsp.md](lsp.md) | the LSP navigation seam: `LspQueryRequest`/`Result`, `LspProvider`/`Service`, four operations, `LspError` |
|
|
48
|
+
| [skills.md](skills.md) | the skill service: discovery priority, `SkillSummary`/`SkillDefinition`, session-prefix catalog, model-facing `skill` loading |
|
|
49
|
+
| [compaction.md](compaction.md) | the compaction seam: the `compaction/*` session events, `CompactionResult`, the `CompactionEngine` interface |
|
|
50
|
+
| [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split |
|
|
51
|
+
| [voice-input.md](voice-input.md) | experimental named recognizers, transient audio and revision-guarded draft insertion |
|
|
52
|
+
| [agent-team.md](agent-team.md) | Agent Teams: implicit Lead identity, named continuable teammates, durable peer mailbox, and shared task DAG |
|
|
53
|
+
| [web.md](web.md) | the web access seam: `WebSearchRequest`/`Result`, `WebFetchRequest`/`Result`, `WebFetchBody`, provider availability, `WebError` |
|
|
54
|
+
| [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
|
|
55
|
+
| [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
|
|
56
|
+
| [jobs.md](jobs.md) | the background-job runtime: branded `JobId`s, the producer contract, consumer views, and `ctx.jobs` service behavior |
|
|
57
|
+
| [permission-presets.md](permission-presets.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event |
|
|
58
|
+
| [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc |
|
|
59
|
+
| [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract |
|
|
60
|
+
| [web-server.md](web-server.md) | the HTTP carrier: `WebRouteKind`/`WebRoute`, match order, the claimable fallback seat, index taps |
|
|
61
|
+
| [webhook.md](webhook.md) | authenticated provider deliveries, arbitrary programmatic rules, and fire-and-forget Workspace Session creation |
|
|
62
|
+
| [storage.md](storage.md) | the storage subsystem: the backend contract (`StorageBackend`), `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` |
|
|
63
|
+
| [workspace.md](workspace.md) | the workspace registry: `Workspace`/`WorkspaceId`, registration and resolution, the session `cwd` relationship |
|
|
64
|
+
| [web-client.md](web-client.md) | the browser architecture: boot, Remote communication, paired Client models, UI adapters, Conversation assembly, Slots, and reconnect semantics |
|
|
65
|
+
| [client-modules.md](client-modules.md) | the web plugin table: `dsh.client` declarations, `WebBootGraph` wire composition, the bundle route and index tap |
|
|
66
|
+
| [slots.md](slots.md) | typed Web UI composition: declaration ownership, cardinality and scope, framework and feature injection, props derivation, and the shipped hierarchy |
|
|
67
|
+
| [client-resources.md](client-resources.md) | the client resource model: `dsh-resource://<type>/…` addresses, protocol providers and `ResourceProtocolMap`, the `useResource` global hook and its states, pins and release |
|
|
68
|
+
| [sidebar-right.md](sidebar-right.md) | the right Sidebar: resource and navigation addresses, tab-type registration and routing, the `ctx.sidebarRight` navigation service, the pane-tab slots and owner props, the resource model, and the Workspace Files service |
|
|
69
|
+
| [conversation.md](conversation.md) | target-neutral Session-event assembly: Context identity, Location data, replay paths, view builders, and target-owned render nodes |
|
|
70
|
+
| [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed |
|
|
71
|
+
| [session-telemetry.md](session-telemetry.md) | the outbound session-reporting capability seam: `SessionTelemetryRecord`/`SessionTelemetrySeverity`, the `SessionTelemetrySink` contract, and the `session-telemetry/record` redact waterfall |
|
|
72
|
+
| [otel.md](otel.md) | Shared ordinary-event and Session-log OTLP channels |
|
|
73
|
+
| [product-telemetry.md](product-telemetry.md) | Explicit product analytics submission and OTLP/HTTP transport |
|
|
74
|
+
|
|
75
|
+
> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis API** section.
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/agent-team.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Agent Teams
|
|
4
|
+
|
|
5
|
+
English | [中文](agent-team.zh.md)
|
|
6
|
+
|
|
7
|
+
Types shared by the experimental implicit-root Team domain, model tools, and host adapters. The [Agent Teams Agent Note](../../.agents/notes/implemented/feature/2026-08-05-agent-teams.md) owns identity, mailbox, task, and shared-checkout decisions; this page records the durable and client-visible forms from [`packages/experimental/agent-team/src/types.ts`](../../packages/experimental/agent-team/src/types.ts).
|
|
8
|
+
|
|
9
|
+
## Identity and roster
|
|
10
|
+
|
|
11
|
+
`TeamId` is the root `SessionId` under a distinct [brand](core.md#branded-ids). `TeamTaskId` is Team-local and monotonically allocated as `task-<n>`; `TeamMessageId` is globally random. A teammate's Session id remains its persistent identity, while `name` is an immutable model/UI label.
|
|
12
|
+
|
|
13
|
+
```ts type-equiv
|
|
14
|
+
/** Whole durable value written on every teammate lifecycle change. */
|
|
15
|
+
interface TeamMemberSnapshot {
|
|
16
|
+
readonly id: SessionId
|
|
17
|
+
readonly name: string
|
|
18
|
+
readonly description: string
|
|
19
|
+
readonly provider: string
|
|
20
|
+
readonly context: 'fresh' | 'fork'
|
|
21
|
+
readonly phase: TeamMemberPhase
|
|
22
|
+
readonly error?: string
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Every member starts in `provisioning` and reaches exactly one terminal roster phase, `active` or `failed`. Roster `running`/`inactive` status is derived separately and never rewrites this record.
|
|
27
|
+
|
|
28
|
+
## Durable mailbox
|
|
29
|
+
|
|
30
|
+
The Lead Session first stores the complete queued message. A target receipt is acknowledged only after its pending inbox item or recorded user message is durable, leaving queued-minus-delivered as the recovery mailbox.
|
|
31
|
+
|
|
32
|
+
```ts type-equiv
|
|
33
|
+
/** One peer message retained until its target Session records it. */
|
|
34
|
+
interface TeamMessageSnapshot {
|
|
35
|
+
readonly id: TeamMessageId
|
|
36
|
+
readonly senderId: SessionId
|
|
37
|
+
readonly senderName: string
|
|
38
|
+
readonly targetId: SessionId
|
|
39
|
+
readonly content: ContentBlock[]
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Every message attempts Steer delivery. A running target receives it at the nearest step boundary; an inactive target starts a turn if loaded or cold-resumes otherwise. Scheduling is not stored in the durable record because callers cannot select another mode.
|
|
44
|
+
|
|
45
|
+
The target Session keeps message identity and sender attribution on both the pending inbox item and the eventual user message. Folding that source across inbox and history is the target-side de-duplication key; the model-visible framing repeats the id and sender.
|
|
46
|
+
|
|
47
|
+
```ts type-equiv
|
|
48
|
+
/** Source retained by the target Session for durable mailbox de-duplication. */
|
|
49
|
+
interface TeamMessageSource {
|
|
50
|
+
readonly kind: 'team-message'
|
|
51
|
+
readonly teamId: TeamId
|
|
52
|
+
readonly messageId: TeamMessageId
|
|
53
|
+
readonly senderId: SessionId
|
|
54
|
+
readonly senderName: string
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Shared task DAG
|
|
59
|
+
|
|
60
|
+
Every task event stores a complete snapshot. `revision` is the compare-and-set value and increments by one per mutation. `blockedBy` edges must name non-deleted tasks and keep the graph acyclic. `writeScopes` are normalized advisory path prefixes rather than locks.
|
|
61
|
+
|
|
62
|
+
```ts type-equiv
|
|
63
|
+
/** Whole durable task snapshot; every mutation increments {@link revision}. */
|
|
64
|
+
interface TeamTaskSnapshot {
|
|
65
|
+
readonly id: TeamTaskId
|
|
66
|
+
readonly revision: number
|
|
67
|
+
readonly subject: string
|
|
68
|
+
readonly description: string
|
|
69
|
+
readonly status: TeamTaskStatus
|
|
70
|
+
readonly ownerId?: SessionId
|
|
71
|
+
readonly blockedBy: TeamTaskId[]
|
|
72
|
+
readonly writeScopes: string[]
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`pending` is unstarted or released, `in_progress` carries an owner, `completed` satisfies blockers, and `deleted` is a retained tombstone. Views add owner name, readiness, and write-scope overlap warnings without changing the durable snapshot.
|
|
77
|
+
|
|
78
|
+
<a id="web-projection"></a>
|
|
79
|
+
|
|
80
|
+
## Web projection
|
|
81
|
+
|
|
82
|
+
The Lead Session publishes `SessionProjectionMap.agentTeam` with durable roster rows and non-deleted task views. `failure` reports a rejected persisted record beside the last valid state. Member activity comes from Session status; model labels come from each member's `modelSelection` projection.
|
|
83
|
+
|
|
84
|
+
```ts type-equiv
|
|
85
|
+
/** One durable roster row published through the `agentTeam` Session projection. */
|
|
86
|
+
interface TeamMemberProjection {
|
|
87
|
+
readonly id: SessionId
|
|
88
|
+
readonly name: string
|
|
89
|
+
readonly role: 'lead' | 'teammate'
|
|
90
|
+
/** Durable lifecycle; the Lead row is always `active`. Turn activity comes from Session status. */
|
|
91
|
+
readonly phase: TeamMemberPhase
|
|
92
|
+
readonly error?: string
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
```ts type-equiv
|
|
97
|
+
/** Runtime-enriched task view returned to tools and hosts. */
|
|
98
|
+
interface TeamTaskView {
|
|
99
|
+
readonly id: TeamTaskId
|
|
100
|
+
readonly revision: number
|
|
101
|
+
readonly subject: string
|
|
102
|
+
readonly description: string
|
|
103
|
+
readonly status: TeamTaskStatus
|
|
104
|
+
readonly blockedBy: TeamTaskId[]
|
|
105
|
+
readonly writeScopes: string[]
|
|
106
|
+
readonly ownerName?: string
|
|
107
|
+
readonly ready: boolean
|
|
108
|
+
readonly writeScopeWarnings: string[]
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
```ts type-equiv
|
|
113
|
+
/**
|
|
114
|
+
* Durable Team state published to browser clients through the Lead Session's
|
|
115
|
+
* `agentTeam` projection. `failure` names the first rejected persisted Team
|
|
116
|
+
* record; members and tasks then stay at the last valid state.
|
|
117
|
+
*/
|
|
118
|
+
interface TeamProjection {
|
|
119
|
+
readonly members: TeamMemberProjection[]
|
|
120
|
+
readonly tasks: TeamTaskView[]
|
|
121
|
+
readonly failure?: string
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Replay
|
|
126
|
+
|
|
127
|
+
The `agentTeam` Session projection replays one root Session into the roster, task board, and queued-minus-delivered mailbox that every Team operation reads. It selects records by `TeamId`, so events inherited by an ordinary fork retain the ancestor id and never enter the new root's state. Session event `seq` and `time` remain the ordering and timing record; Team snapshots do not duplicate them. Roster and task reads reach callers as views; pending mail stays internal to delivery and recovery. The package [README](../../packages/experimental/agent-team/README.md) owns operation, authorization, recovery, and limit behavior.
|
|
128
|
+
|
|
129
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
130
|
+
|
|
131
|
+
<a id="cordis-surface"></a>
|
|
132
|
+
|
|
133
|
+
## Cordis API
|
|
134
|
+
|
|
135
|
+
Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
|
|
136
|
+
|
|
137
|
+
<a id="ctxagentteams--teamservice"></a>
|
|
138
|
+
|
|
139
|
+
### `ctx.agentTeams` - `TeamService`
|
|
140
|
+
|
|
141
|
+
Agent Teams service backed by the exact live Lead Session log.
|
|
142
|
+
|
|
143
|
+
```ts cordis-catalog
|
|
144
|
+
/**
|
|
145
|
+
* Resolve one exact live Agent's Team role.
|
|
146
|
+
* @param agent - exact live Agent used as the authority credential.
|
|
147
|
+
* @returns its root, Team identity, role, and model-facing name.
|
|
148
|
+
*/
|
|
149
|
+
membership(agent: Agent): TeamMembership
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* List the runtime-enriched roster visible to one Team member.
|
|
153
|
+
* @param agent - exact live Team member.
|
|
154
|
+
* @returns Lead and teammate rows in creation order.
|
|
155
|
+
*/
|
|
156
|
+
listMembers(agent: Agent): TeamMemberView[]
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Create one named, continuable direct child of the Team Lead.
|
|
160
|
+
* @param caller - exact live Lead Agent.
|
|
161
|
+
* @param request - immutable name, description, prompt, context mode, provider, and cancellation.
|
|
162
|
+
* @returns the active roster row.
|
|
163
|
+
*/
|
|
164
|
+
async spawnTeammate(caller: Agent, request: SpawnTeammateRequest): Promise<SpawnTeammateResult>
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* Queue one durable peer message, then attempt immediate delivery.
|
|
168
|
+
* @param caller - exact live sending Team member.
|
|
169
|
+
* @param request - target name, content, and pre-queue cancellation.
|
|
170
|
+
* @returns durable message identity and immediate-delivery observation.
|
|
171
|
+
*/
|
|
172
|
+
async sendMessage(caller: Agent, request: SendTeamMessageRequest): Promise<SendTeamMessageResult>
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* Create one unowned pending task in the Team Lead log.
|
|
176
|
+
* @param caller - exact live Team member creating the task.
|
|
177
|
+
* @param request - task text, blockers, and advisory write scopes.
|
|
178
|
+
* @returns the revision-one task view.
|
|
179
|
+
*/
|
|
180
|
+
async createTask(caller: Agent, request: CreateTeamTaskRequest): Promise<TeamTaskView>
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Return one task, including a deleted tombstone.
|
|
184
|
+
* @param caller - exact live Team member reading the task.
|
|
185
|
+
* @param id - Team-local task identity.
|
|
186
|
+
* @returns the latest task value and derived readiness diagnostics.
|
|
187
|
+
*/
|
|
188
|
+
getTask(caller: Agent, id: TeamTaskId): TeamTaskView
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* List current non-deleted tasks in numeric creation order.
|
|
192
|
+
* @param caller - exact live Team member reading the board.
|
|
193
|
+
* @returns detached current task views.
|
|
194
|
+
*/
|
|
195
|
+
listTasks(caller: Agent): TeamTaskView[]
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Compare-and-set one authorized task transition.
|
|
199
|
+
* @param caller - exact live Team member authorizing the mutation.
|
|
200
|
+
* @param request - task identity, expected revision, action, and action fields.
|
|
201
|
+
* @returns the committed next task revision.
|
|
202
|
+
*/
|
|
203
|
+
async updateTask(caller: Agent, request: UpdateTeamTaskRequest): Promise<TeamTaskView>
|
|
204
|
+
|
|
205
|
+
/**
|
|
206
|
+
* Wait for the next Team-domain or member-status change.
|
|
207
|
+
* @param caller - exact live Team member waiting for activity.
|
|
208
|
+
* @param timeoutMs - bounded wait duration from ten seconds through one hour.
|
|
209
|
+
* @param signal - caller cancellation for the wait only.
|
|
210
|
+
* @returns one observed change or a timeout result.
|
|
211
|
+
*/
|
|
212
|
+
async waitForChange(caller: Agent, timeoutMs: number, signal: AbortSignal): Promise<TeamWaitResult>
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* Interrupt one live teammate turn without clearing its pending inbox.
|
|
216
|
+
* @param caller - exact live Lead Agent.
|
|
217
|
+
* @param targetName - durable teammate name.
|
|
218
|
+
* @returns the target status sampled before cancellation.
|
|
219
|
+
*/
|
|
220
|
+
interrupt(caller: Agent, targetName: string): { previousStatus: 'running' | 'inactive' }
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Resolve a caller without throwing, used by scoped-tool installation and observers.
|
|
224
|
+
* @param agent - candidate exact live Agent.
|
|
225
|
+
* @returns Team membership, or undefined for non-Team subagents and stale identities.
|
|
226
|
+
*/
|
|
227
|
+
tryMembership(agent: Agent): TeamMembership | undefined
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Types: [Agent](core.md)
|
|
231
|
+
|
|
232
|
+
Source: [`packages/experimental/agent-team/src/index.ts`](../../packages/experimental/agent-team/src/index.ts)
|
|
233
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/approval.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# User Approval
|
|
4
|
+
|
|
5
|
+
English | [中文](approval.zh.md)
|
|
6
|
+
|
|
7
|
+
The user-approval seam of [dsh-user-approval](../../packages/interaction/user-approval) answers one question: may this specific action proceed? It owns the shared request/outcome vocabulary, the `ctx.approval` dispatch service, the `approval/request` answerer waterfall, the log-only audit pair, and the per-session `ask`/`never` policy. UI channels may provide human answerers; the [ACP automation bridge](../../packages/acp/acp) provides one-shot machine decisions for its own agents. Callers such as [dsh-tools](../../packages/core/tools) and [dsh-tool-bash](../../packages/shell/tool-bash) consume the closed outcome and fail closed unless it is `allowed-once`.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/interaction/user-approval/src/index.ts`](../../packages/interaction/user-approval/src/index.ts)
|
|
10
|
+
|
|
11
|
+
## Identity and outcome
|
|
12
|
+
|
|
13
|
+
Every request receives a fresh `ApprovalRequestId`. The brand pairs the `approval/asked` and `approval/decided` audit events without making approval ids interchangeable with tool-call or agent/session ids.
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/**
|
|
17
|
+
* Pairs one `approval/asked` audit event with its `approval/decided`.
|
|
18
|
+
* Service-issued (one fresh id per {@link ApprovalService.request} call).
|
|
19
|
+
*/
|
|
20
|
+
type ApprovalRequestId = Branded<'ApprovalRequestId'>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`ApprovalOutcome` is closed and fail-closed. `allowed-once` grants only the asked-about action; callers deny on `rejected`, `cancelled`, and `unavailable`. A missing, non-owning, throwing, or non-conforming answerer becomes `unavailable` rather than opening the gate.
|
|
24
|
+
|
|
25
|
+
```ts type-equiv
|
|
26
|
+
/**
|
|
27
|
+
* Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
|
|
28
|
+
* request, or unavailable answerer. Callers fail closed on `unavailable`.
|
|
29
|
+
*/
|
|
30
|
+
type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Per-session policy
|
|
34
|
+
|
|
35
|
+
`ApprovalPolicy` determines what happens before interactive answerers run. `ask` delegates to the composed answerer chain, whose no-answer default is `unavailable`; `never` deterministically returns `rejected` without dispatching any answerer. The effective value is the last `approval/policy` event in the session log, falling back to the service config. Consumers read it with `ctx.approval.effectivePolicy(session)`; `setApprovalPolicy(session, policy)` is the single write path, so replay reconstructs the override.
|
|
36
|
+
|
|
37
|
+
```ts type-equiv
|
|
38
|
+
/**
|
|
39
|
+
* A session's approval policy - what happens to an {@link ApprovalService}
|
|
40
|
+
* ask BEFORE any interactive answerer sees it:
|
|
41
|
+
*
|
|
42
|
+
* - `'ask'` (the default) - delegate to the composed answerers; with none
|
|
43
|
+
* composed the chain falls through to the fail-closed `'unavailable'`.
|
|
44
|
+
* - `'never'` - never prompt anyone: every ask resolves `'rejected'`
|
|
45
|
+
* deterministically. The strict headless stance (CI, unattended runs) and
|
|
46
|
+
* the policy whose outcome is knowable without asking.
|
|
47
|
+
*/
|
|
48
|
+
type ApprovalPolicy = 'ask' | 'never'
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Both policies contribute their complete current meaning to the cache-safe runtime-context snapshot. The sourced `user/message` is the durable model-visible input; changing approval state appends a new full snapshot after retained history without touching the `system/message` nodes that hold the rendered system prompt.
|
|
52
|
+
|
|
53
|
+
## Approval request
|
|
54
|
+
|
|
55
|
+
`ApprovalRequest` identifies the agent and tool action closely enough to route and audit the question. It deliberately omits tool arguments: an answerer attaches the prompt to the already-streamed tool call through `callId` instead of rendering a second copy that could drift. Optional `displayReason` carries requester-owned locale strings to presentation; `reason` remains the audit text.
|
|
56
|
+
|
|
57
|
+
```ts type-equiv
|
|
58
|
+
/**
|
|
59
|
+
* Readonly same-process permission question. `callId` links to an already
|
|
60
|
+
* presented tool call, so arguments are not duplicated here.
|
|
61
|
+
*/
|
|
62
|
+
interface ApprovalRequest extends ApprovalRequestEvent {
|
|
63
|
+
/**
|
|
64
|
+
* The agent on whose behalf the question is asked. Routes the question (a
|
|
65
|
+
* UI answerer only answers for agents it owns) and receives the audit
|
|
66
|
+
* events on its session log.
|
|
67
|
+
*/
|
|
68
|
+
readonly agent: Agent
|
|
69
|
+
/** The tool the question is about (presentation and audit). */
|
|
70
|
+
readonly toolName: string
|
|
71
|
+
/**
|
|
72
|
+
* The exact tool call being decided, when the asker has one - lets a UI
|
|
73
|
+
* attach the prompt to the tool call it already streamed.
|
|
74
|
+
*/
|
|
75
|
+
readonly callId?: ToolCallId
|
|
76
|
+
/** The asker's human-readable explanation of WHY it is asking. */
|
|
77
|
+
readonly reason?: string
|
|
78
|
+
/**
|
|
79
|
+
* Aborting withdraws the question: the request settles `'cancelled'`
|
|
80
|
+
* immediately and a late answer from a still-pending answerer is discarded.
|
|
81
|
+
*/
|
|
82
|
+
readonly signal?: AbortSignal
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Dispatch and audit
|
|
87
|
+
|
|
88
|
+
`ctx.approval.request(req)` requires the requesting session to be inside an open turn. It appends `approval/asked`, obtains one outcome, appends the matching `approval/decided`, and resolves with that outcome. The `never` policy is enforced inside the service before waterfall dispatch, so even an answerer registered later with `prepend` cannot bypass it. Answerers return an outcome when they own the request or call `next()` to delegate; the first answer occupies the single decision slot.
|
|
89
|
+
|
|
90
|
+
The audit events are log-only and do not enter the model transcript. Model-visible behavior is the caller's derived tool result plus the current runtime-context snapshot. Service disposal removes its context contribution; answerer listeners are independently effect-bound to their owning plugins.
|
|
91
|
+
|
|
92
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
93
|
+
|
|
94
|
+
<a id="cordis-surface"></a>
|
|
95
|
+
|
|
96
|
+
## Cordis API
|
|
97
|
+
|
|
98
|
+
Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
|
|
99
|
+
|
|
100
|
+
<a id="ctxapproval--approvalservice"></a>
|
|
101
|
+
|
|
102
|
+
### `ctx.approval` - `ApprovalService`
|
|
103
|
+
|
|
104
|
+
Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.
|
|
105
|
+
|
|
106
|
+
```ts cordis-catalog
|
|
107
|
+
/**
|
|
108
|
+
* Switch one live agent's policy and queue the transition for its next model
|
|
109
|
+
* step. Session initialization uses {@link setApprovalPolicy} directly
|
|
110
|
+
* because there is no previously visible policy to change.
|
|
111
|
+
* @param agent - the live agent whose policy is changing.
|
|
112
|
+
* @param policy - the new effective policy.
|
|
113
|
+
*/
|
|
114
|
+
setPolicy(agent: Agent, policy: ApprovalPolicy): void
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Ask the composed answerers to decide one readonly same-process request.
|
|
118
|
+
* The service borrows the request, agent, session, and live signal directly.
|
|
119
|
+
* The request requires an open turn because the audit pair must be enclosed
|
|
120
|
+
* by the durable log's commit/replay boundary; an idle ask rejects before
|
|
121
|
+
* appending anything. The answerer phase always produces an outcome: an
|
|
122
|
+
* aborted signal yields `'cancelled'`, a missing or throwing answerer yields
|
|
123
|
+
* `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
|
|
124
|
+
* normalized to `'unavailable'`. A failure that prevents either audit append
|
|
125
|
+
* from committing still rejects because returning an unlogged decision would
|
|
126
|
+
* violate the pair. Session contains post-commit observer failures, so an
|
|
127
|
+
* authoritative append cannot reject the request or suppress its matching
|
|
128
|
+
* audit event.
|
|
129
|
+
* @param req - the pending decision (agent, tool identity, reason, signal).
|
|
130
|
+
* @returns the closed outcome; `'allowed-once'` is the only grant.
|
|
131
|
+
* @throws when no turn is open or either audit event fails before the session
|
|
132
|
+
* append commit point.
|
|
133
|
+
*/
|
|
134
|
+
async request(req: ApprovalRequest): Promise<ApprovalOutcome>
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Read the session override without applying the configured default.
|
|
138
|
+
* @param session - session whose log supplies the override.
|
|
139
|
+
* @returns the last logged policy, or `undefined` without one.
|
|
140
|
+
*/
|
|
141
|
+
overrideOf(session: Session): ApprovalPolicy | undefined
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Types: [Agent](core.md) · [Session](session.md)
|
|
145
|
+
|
|
146
|
+
Source: [`packages/interaction/user-approval/src/index.ts`](../../packages/interaction/user-approval/src/index.ts)
|
|
147
|
+
|
|
148
|
+
<a id="approval-events"></a>
|
|
149
|
+
|
|
150
|
+
### `approval/*` events
|
|
151
|
+
|
|
152
|
+
<a id="approvalrequest--waterfall"></a>
|
|
153
|
+
|
|
154
|
+
#### `approval/request` - waterfall
|
|
155
|
+
|
|
156
|
+
Ask composed answerers for one decision. Return an outcome to claim the request or call `next()` to delegate. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
157
|
+
|
|
158
|
+
```ts cordis-catalog
|
|
159
|
+
/**
|
|
160
|
+
* Ask composed answerers for one decision. Return an outcome to claim the
|
|
161
|
+
* request or call `next()` to delegate. Scope-filtered dispatch
|
|
162
|
+
* (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
163
|
+
* @param req - pending approval request.
|
|
164
|
+
* @mode waterfall
|
|
165
|
+
*/
|
|
166
|
+
'approval/request'( this: Scoped<Agent>, req: ApprovalRequestEvent, next: () => Promise<ApprovalOutcome>, ): Promise<ApprovalOutcome>
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Types: [Agent](core.md) · [Scoped](scope.md)
|
|
170
|
+
|
|
171
|
+
Source: [`packages/interaction/user-approval/src/types.ts`](../../packages/interaction/user-approval/src/types.ts)
|
|
172
|
+
<!-- END GENERATED cordis-surface -->
|