@acryldev/plugin-context 0.0.0-stage → 0.1.0
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/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 +56 -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
- package/README.md +0 -3
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/plan.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Plan Mode
|
|
4
|
+
|
|
5
|
+
English | [中文](plan.zh.md)
|
|
6
|
+
|
|
7
|
+
Plan mode is logged per-agent collaboration state owned by [dsh-plan-mode](../../packages/plan/plan-mode) (`ctx.planMode`, `PlanModeController`): while active, a deployment-owned guidance section is included in each model request. Plan mode is **soft guidance**. [Sandbox mode](sandbox.md) and [approval policy](approval.md) enforce restrictions independently; neither reads or writes plan state, so deployments configure them separately. The package is optional, and the agent loop does not depend on it. It contributes the `plan:policy` prompt section and registers the `exit_plan_mode` tool and `/plan` command. The [design note](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md) owns the rationale; the [package README](../../packages/plan/plan-mode/README.md) owns the model-experience and limitation detail.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
|
|
10
|
+
|
|
11
|
+
## Logged state and recovery
|
|
12
|
+
|
|
13
|
+
`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](session.md): durable and replayable, never in the model transcript. The optionally registered `plan` unit folds committed mode, command settlement, and the mode recorded at the latest request header. `ctx.planMode` reads that state through `stateOf()`; the first dependent access fails if the registry, `plan` key, or `turnBoundary` key is absent. Clients receive only `{ active, pending }`; resume, fork, and compaction recover both from the log. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md).
|
|
14
|
+
|
|
15
|
+
## Pending selections and the pre-step append
|
|
16
|
+
|
|
17
|
+
Because every session event is turn-enclosed, a user selection remains pending until the next accepted in-turn pre-step appends it before request derivation, in whichever turn that occurs. A selection never forces continuation, so one made after a turn's final accepted pre-step is appended in a later turn. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }`: the logged state used to assemble the current step plus the selected state waiting to be appended.
|
|
18
|
+
|
|
19
|
+
The only append point while an agent is running is a prepended `agent/pre-step` listener. It observes every proposed request step, including turn 1 step 1 and request-recovery retries, calls downstream listeners first, and appends only after they accept the step. Prompt admission happens before a turn and cannot append `plan/mode`, so a selection made at the prompt is appended by the first accepted in-turn pre-step of the turn it starts. An append failure cannot block the turn, and the selection remains pending for a later accepted in-turn pre-step. An appended user selection also records one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A selection made after a turn's final accepted pre-step remains process-local and is lost if the process exits before another accepted in-turn pre-step ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
|
|
20
|
+
|
|
21
|
+
## Configuration
|
|
22
|
+
|
|
23
|
+
```ts type-equiv
|
|
24
|
+
/** Deployment-owned plan guidance. */
|
|
25
|
+
interface PlanModeConfig {
|
|
26
|
+
/** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
|
|
27
|
+
section: string
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
A missing, blank, or non-string `section` and any unknown key fail at plugin load rather than being ignored. While plan mode is active, the exact `section` text renders as the `plan:policy` [system-prompt section](system-prompt.md) at order 50; inactive plan mode contributes no text.
|
|
32
|
+
|
|
33
|
+
## The exit tool and the `/plan` command
|
|
34
|
+
|
|
35
|
+
[`exit_plan_mode`](../tool-catalog.md#deepseek-aidsh-plan-mode) stays registered while plan mode is inactive, so entering or leaving plan mode changes only the prompt section, never the request tool catalog; execution outside plan mode fails. In plan mode it requires a complete markdown plan starting with a `#` heading and presents it for review through the [user-questions seam](user-questions.md). Approval returns `{ approved: true }` and records a silent (non-narrated) pending exit that is appended at the next accepted in-turn pre-step. Plan guidance therefore remains active for the rest of the assistant's current tool batch, and the tool result itself reports the transition. Keep-planning is a failed call carrying the user's feedback, so the model revises and presents again; a missing interaction channel and a service reload during review also fail the call rather than silently leaving plan mode.
|
|
36
|
+
|
|
37
|
+
When [`ctx.commands`](commands.md) is composed, the plugin registers `/plan [off|message]`: bare `/plan` selects plan mode, any other non-empty message selects it and then submits the text through `agent.steer()` so it becomes the next step's ordinary logged user message under plan guidance, and the exact argument `off` selects inactive, which also cancels a pending entry before it is appended and becomes visible to a request.
|
|
38
|
+
|
|
39
|
+
## The service
|
|
40
|
+
|
|
41
|
+
`ctx.planMode` owns the logged plan state, applies and narrates selected state at step start, and owns the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](#ctxplanmode--planmodecontroller).
|
|
42
|
+
|
|
43
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
44
|
+
|
|
45
|
+
<a id="cordis-surface"></a>
|
|
46
|
+
|
|
47
|
+
## Cordis API
|
|
48
|
+
|
|
49
|
+
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).
|
|
50
|
+
|
|
51
|
+
<a id="ctxplanmode--planmodecontroller"></a>
|
|
52
|
+
|
|
53
|
+
### `ctx.planMode` - `PlanModeController`
|
|
54
|
+
|
|
55
|
+
`ctx.planMode`: owns logged plan state, applies and narrates selected state at step start, the `plan:policy` section, the `/plan` command, and the stable exit tool. Client carriers expose the projection's cropped `{ active, pending }` view.
|
|
56
|
+
|
|
57
|
+
```ts cordis-catalog
|
|
58
|
+
/**
|
|
59
|
+
* Read the logged plan state and any selected state awaiting the next
|
|
60
|
+
* accepted in-turn pre-step.
|
|
61
|
+
*
|
|
62
|
+
* @param agent The agent to read.
|
|
63
|
+
* @returns Current logged state plus a pending selection, when present.
|
|
64
|
+
*/
|
|
65
|
+
get(agent: Agent): { active: boolean; pending?: boolean }
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Select whether plan mode should be active. Between turns the method
|
|
69
|
+
* appends the change immediately because no in-turn pre-step will run until
|
|
70
|
+
* another prompt starts a turn. The open-turn fold is the idle signal:
|
|
71
|
+
* agent status stays `running` through post-turn checkpointing, when no
|
|
72
|
+
* further in-turn pre-step runs. During an open turn the selection remains
|
|
73
|
+
* pending until the next accepted in-turn pre-step. Repeated selection of
|
|
74
|
+
* the current or already-pending state is a no-op.
|
|
75
|
+
*
|
|
76
|
+
* @param agent The agent to switch.
|
|
77
|
+
* @param active Whether plan mode should be active.
|
|
78
|
+
* @returns what happened: `committed` (logged now), `queued` (awaiting the
|
|
79
|
+
* next accepted in-turn pre-step), `cancelled` (an opposite pending selection
|
|
80
|
+
* was cleared; the logged state already matches), or `noop` (already in that
|
|
81
|
+
* state).
|
|
82
|
+
*/
|
|
83
|
+
set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Types: [Agent](core.md)
|
|
87
|
+
|
|
88
|
+
Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
|
|
89
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/product-telemetry.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Product telemetry
|
|
4
|
+
|
|
5
|
+
English | [中文](product-telemetry.zh.md)
|
|
6
|
+
|
|
7
|
+
The [product telemetry plugin](../../packages/host/product-telemetry-otel/README.md) sends explicitly selected analytics events through OTLP/HTTP. Its `productTelemetry` service owns submission only; product consumers own when an event occurs and which fields are approved. The exporter collects no Session data or identifiers automatically. The [Desktop analytics consumer](../../packages/client/product-analytics/README.md) selects interaction and live compaction events, adds available login identity, and follows the Desktop launch-time collection switch. Ordinary Web clients do not collect product events.
|
|
8
|
+
|
|
9
|
+
`ProductTelemetryRecord` requires an event name, string body, and Unix-millisecond timestamp. Attributes accept scalar strings, numbers, booleans, and one-level objects of those values (`ProductTelemetryScalar`). Optional severity uses OTel severity numbers and defaults to INFO. Observation time is assigned when the record is enqueued.
|
|
10
|
+
|
|
11
|
+
Enqueue is synchronous and does not acknowledge delivery. The SDK owns batching and retry; local diagnostics report export failures. See the package README for configuration, shutdown, and loss limits.
|
|
12
|
+
|
|
13
|
+
## Record types
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/** Scalar values accepted in product attributes. */
|
|
17
|
+
type ProductTelemetryScalar = OTelEventScalar
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```ts type-equiv
|
|
21
|
+
/** Caller-selected ordinary analytics record. */
|
|
22
|
+
type ProductTelemetryRecord = OTelEventRecord
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Source: [`packages/host/product-telemetry-otel/src/index.ts`](../../packages/host/product-telemetry-otel/src/index.ts)
|
|
26
|
+
|
|
27
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
28
|
+
|
|
29
|
+
<a id="cordis-surface"></a>
|
|
30
|
+
|
|
31
|
+
## Cordis API
|
|
32
|
+
|
|
33
|
+
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).
|
|
34
|
+
|
|
35
|
+
<a id="ctxproductanalytics--productanalytics"></a>
|
|
36
|
+
|
|
37
|
+
### `ctx.productAnalytics` - `ProductAnalytics`
|
|
38
|
+
|
|
39
|
+
Authenticated event intake; disabled instances do not inspect identity or accept new events.
|
|
40
|
+
|
|
41
|
+
```ts cordis-catalog
|
|
42
|
+
/**
|
|
43
|
+
* Read the collection policy.
|
|
44
|
+
* @returns whether this Host currently accepts Desktop analytics.
|
|
45
|
+
*/
|
|
46
|
+
@Remote enabled(): boolean
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Stream the effective policy initially and after live configuration edits.
|
|
50
|
+
* @param signal - subscriber lifetime.
|
|
51
|
+
* @returns current policy values until cancellation or service disposal.
|
|
52
|
+
*/
|
|
53
|
+
@Remote({ mode: 'stream' }) async *watchPolicy(signal: AbortSignal): AsyncIterable<boolean>
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Submit selected Desktop fields; missing identity is omitted and never generated.
|
|
57
|
+
* @param event - typed product event without message contents or credentials.
|
|
58
|
+
* @returns after local submission; no delivery or warehouse acknowledgement.
|
|
59
|
+
*/
|
|
60
|
+
@Remote async report(event: ProductEvent): Promise<void>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Source: [`packages/client/product-analytics/src/index.ts`](../../packages/client/product-analytics/src/index.ts)
|
|
64
|
+
|
|
65
|
+
<a id="ctxproducttelemetry--producttelemetry"></a>
|
|
66
|
+
|
|
67
|
+
### `ctx.productTelemetry` - `ProductTelemetry`
|
|
68
|
+
|
|
69
|
+
Host analytics sender. Mounting alone sends nothing; the owning fiber drains it on unload.
|
|
70
|
+
|
|
71
|
+
```ts cordis-catalog
|
|
72
|
+
/**
|
|
73
|
+
* Enqueue one selected product event without waiting for network delivery.
|
|
74
|
+
* Queue admission and shutdown completion are not collector or warehouse acknowledgements.
|
|
75
|
+
* @param record - caller-owned event containing only approved analytics fields.
|
|
76
|
+
*/
|
|
77
|
+
emit(record: ProductTelemetryRecord): void
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Source: [`packages/host/product-telemetry-otel/src/index.ts`](../../packages/host/product-telemetry-otel/src/index.ts)
|
|
81
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/ptc-runtime.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# PTC runtime
|
|
4
|
+
|
|
5
|
+
English | [中文](ptc-runtime.zh.md)
|
|
6
|
+
|
|
7
|
+
The PTC execution [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) supplies `ctx.ptcRuntime` through [dsh-ptc-runtime](../../packages/ptc-runtime/ptc-runtime). It runs one program against host bindings and reports output, failure and applicable sandbox facts. PTC execution is optional rather than part of [the agent-loop spine](core.md). The [PTC foundation](../../.agents/notes/implemented/feature/2026-06-15-ptc.md) owns registry presentation, the [typed-return contract](../../.agents/notes/implemented/feature/2026-07-20-ptc-typed-tool-returns.md) owns binding values, and the [sandboxed Node decision](../../.agents/notes/implemented/architecture/2026-09-11-sandboxed-node-ptc-runtime.md) owns the shipped execution provider.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/ptc-runtime/ptc-runtime/src/types.ts`](../../packages/ptc-runtime/ptc-runtime/src/types.ts)
|
|
10
|
+
|
|
11
|
+
## The run: request in, result out
|
|
12
|
+
|
|
13
|
+
`PtcRunRequest` contains the program, bindings, cancellation and optional execution choices. The provider's `resolve` validates supported choices and applies its deployment defaults; `run` receives a `PtcRunSpec` with an explicit directory and deadline choice. An omitted timeout uses provider defaults, a number requests a capped elapsed budget, and `null` requests no elapsed deadline. Providers reject unsupported choices before execution:
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/**
|
|
17
|
+
* Caller inputs for one program. The provider's resolve method validates supported
|
|
18
|
+
* options and supplies directory, deadline, and authority before execution.
|
|
19
|
+
*/
|
|
20
|
+
interface PtcRunRequest {
|
|
21
|
+
/**
|
|
22
|
+
* The program source, in the runtime's {@link ../index.ts | language}. It
|
|
23
|
+
* runs as the body of an async function: top-level `await` and `return`
|
|
24
|
+
* are available, and the completion value becomes
|
|
25
|
+
* {@link PtcRunResult.value}.
|
|
26
|
+
*/
|
|
27
|
+
program: string
|
|
28
|
+
/** Host functions exposed to the program, one global object per namespace. */
|
|
29
|
+
bindings: PtcBindingNamespace[]
|
|
30
|
+
/** Working directory in the mounted filesystem and subprocess execution world. */
|
|
31
|
+
cwd?: string
|
|
32
|
+
/**
|
|
33
|
+
* Elapsed execution budget in milliseconds. Omission uses provider defaults;
|
|
34
|
+
* null requests no deadline. Providers validate and cap numeric budgets or reject unsupported choices.
|
|
35
|
+
*/
|
|
36
|
+
timeoutMs?: number | null
|
|
37
|
+
/** Resolved authority for this execution. Providers without confinement reject an explicit policy. */
|
|
38
|
+
sandboxPolicy?: SandboxExecutionPolicy
|
|
39
|
+
/**
|
|
40
|
+
* Abort the run: the runtime stops the program (hard, even mid-loop) and
|
|
41
|
+
* resolves with a {@link PtcRunFailure} of kind `'abort'`. In-flight
|
|
42
|
+
* binding calls are the CALLER's to settle - the runtime only stops asking.
|
|
43
|
+
*/
|
|
44
|
+
signal?: AbortSignal
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
```ts type-equiv
|
|
49
|
+
/** Fully resolved execution inputs; run never supplies a missing directory or deadline choice. */
|
|
50
|
+
interface PtcRunSpec extends PtcRunRequest {
|
|
51
|
+
/** Absolute directory in the provider's execution world. */
|
|
52
|
+
cwd: string
|
|
53
|
+
/** Positive finite elapsed budget in milliseconds after provider capping, or null for no deadline. */
|
|
54
|
+
timeoutMs: number | null
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```ts type-equiv
|
|
59
|
+
/** File confinement applied to a program, independently of its terminal outcome. */
|
|
60
|
+
interface PtcRunSandbox {
|
|
61
|
+
/** File-effect mode used for this execution. */
|
|
62
|
+
mode: SandboxMode
|
|
63
|
+
/** Program failure text matched backend diagnostics; not enforcement proof or an exhaustive denial record. */
|
|
64
|
+
denied: boolean
|
|
65
|
+
/** Completeness reported by the selected confining backend; absent for full access. */
|
|
66
|
+
enforcement?: SandboxEnforcement
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Program failures resolve through `PtcRunResult.error`; invalid caller inputs may reject before execution. Sandbox mode, observed denial and enforcement completeness are separate facts, so a successful program does not by itself prove that every requested restriction was enforced:
|
|
71
|
+
|
|
72
|
+
```ts type-equiv
|
|
73
|
+
/**
|
|
74
|
+
* The outcome of one run. An error is a FIELD on a resolved result, never a
|
|
75
|
+
* rejection of `run()` - reporting a failed program is the caller's job, not
|
|
76
|
+
* an exception path.
|
|
77
|
+
*/
|
|
78
|
+
interface PtcRunResult {
|
|
79
|
+
/** Applied file policy and observed denial, when the provider enforces file policy. */
|
|
80
|
+
sandbox?: PtcRunSandbox
|
|
81
|
+
/**
|
|
82
|
+
* The program's completion value (its top-level `return`), when it ran to
|
|
83
|
+
* completion and the value crossed the runtime's lossless-JSON boundary.
|
|
84
|
+
* Invalid or over-limit completions fail the run instead of substituting a
|
|
85
|
+
* rendered string; a failed or value-less run leaves this absent.
|
|
86
|
+
*/
|
|
87
|
+
value?: PtcJsonValue
|
|
88
|
+
/**
|
|
89
|
+
* Captured text. Each source channel preserves emission order; interleaving
|
|
90
|
+
* across independent channels is backend-dependent. Bounded only as part of
|
|
91
|
+
* the outer result.
|
|
92
|
+
*/
|
|
93
|
+
logs: string[]
|
|
94
|
+
/** Present iff the run failed; see {@link PtcRunFailure} for the taxonomy. */
|
|
95
|
+
error?: PtcRunFailure
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Bindings: host functions as program globals
|
|
100
|
+
|
|
101
|
+
Each `PtcBindingNamespace` becomes a global object of async callables; PTC passes `tools`. Arguments and resolutions must be lossless JSON. Providers enforce their own transport caps; the seam sets no uniform binding-byte limit. An optional error-class descriptor creates program-visible typed rejections without naming a consumer inside the runtime. Binding names are own properties, so `__proto__` cannot traverse a prototype:
|
|
102
|
+
|
|
103
|
+
```ts type-equiv
|
|
104
|
+
/**
|
|
105
|
+
* Program-visible typed rejection for one binding namespace. The runtime
|
|
106
|
+
* injects a real error constructor under `name`; rejected member calls become
|
|
107
|
+
* its instances and expose the exact member name through
|
|
108
|
+
* `memberNameProperty`. Both strings are runtime data rather than knowledge
|
|
109
|
+
* of a particular consumer such as PTC mode.
|
|
110
|
+
*/
|
|
111
|
+
interface PtcBindingErrorClass {
|
|
112
|
+
/** Constructor global and resulting `Error.name`; same portable identifier rule as {@link PtcBindingNamespace.global}. */
|
|
113
|
+
name: string
|
|
114
|
+
/**
|
|
115
|
+
* Non-empty own property for the member name. The portable exclusion set is
|
|
116
|
+
* `RESERVED_ERROR_MEMBERS` plus dunder-form names (`__x__`, non-empty
|
|
117
|
+
* middle), enforced identically by every backend; any other name -
|
|
118
|
+
* identifiers or not - is accepted everywhere.
|
|
119
|
+
*/
|
|
120
|
+
memberNameProperty: string
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
```ts type-equiv
|
|
125
|
+
/**
|
|
126
|
+
* A named group of {@link PtcBindingFunction}s the runtime exposes to the
|
|
127
|
+
* program as one global object (e.g. `tools`). Function names are arbitrary
|
|
128
|
+
* strings - a runtime must treat names like `__proto__` or `constructor` as
|
|
129
|
+
* ordinary own properties (null-prototype construction), never as prototype
|
|
130
|
+
* collisions.
|
|
131
|
+
*/
|
|
132
|
+
interface PtcBindingNamespace {
|
|
133
|
+
/**
|
|
134
|
+
* The global identifier the program sees. Must match the LANGUAGE-PORTABLE
|
|
135
|
+
* identifier subset `[A-Za-z_][A-Za-z0-9_]*` and no language's reserved
|
|
136
|
+
* words, so the same namespace list works against every backend regardless
|
|
137
|
+
* of `language` - a JS-only spelling like `$tools` is rejected by design,
|
|
138
|
+
* not just by the Python backend. Names that satisfy the identifier rule but
|
|
139
|
+
* name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`,
|
|
140
|
+
* `__dsh_main__`) are also refused everywhere; see its declaration for the
|
|
141
|
+
* exact set and why each entry is reserved.
|
|
142
|
+
*/
|
|
143
|
+
global: string
|
|
144
|
+
/** The callable members, keyed by the exact name the program calls. */
|
|
145
|
+
functions: Record<string, PtcBindingFunction>
|
|
146
|
+
/** Optional program-visible typed rejection contract for this namespace. */
|
|
147
|
+
errorClass?: PtcBindingErrorClass
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
```ts type-equiv
|
|
152
|
+
/** A lossless JSON value transferable through the dependency-light Service Definition. */
|
|
153
|
+
type PtcJsonValue = null | boolean | number | string | PtcJsonValue[] | { [key: string]: PtcJsonValue }
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
```ts type-equiv
|
|
157
|
+
/**
|
|
158
|
+
* One host-side function exposed to the program as an async callable. The
|
|
159
|
+
* runtime bridges calls to it (possibly across a serialization boundary), so
|
|
160
|
+
* `args` and the resolution value MUST be lossless JSON. A runtime rejects a
|
|
161
|
+
* lossy or non-cloneable value with a descriptive error rather than corrupting
|
|
162
|
+
* the run. No seam-level byte cap applies to a binding resolution. A rejection
|
|
163
|
+
* of this function surfaces inside the program as a rejection of the
|
|
164
|
+
* corresponding call.
|
|
165
|
+
*/
|
|
166
|
+
type PtcBindingFunction = (args: unknown) => Promise<PtcJsonValue>
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## Captured output and the failure taxonomy
|
|
170
|
+
|
|
171
|
+
Logs are plain strings. Each source channel preserves emission order, while interleaving across independent channels is backend-dependent because channel metadata is not part of the seam. The runtime captures the program's console and stream output, and consumers render only the text. Implementations cap the serialized outer log-array plus completion-value or failure-message payload; fixed result-envelope syntax and consumer presentation whitespace are not part of that variable-payload ledger. Overflow is an explicit failure rather than in-band value substitution.
|
|
172
|
+
|
|
173
|
+
Failure kinds are **orthogonal outcomes reported independently** (per [defensive-patterns](../defensive-patterns.md)): a budget expiry is not an exception, an abort is not a timeout, and a substrate death (e.g. OOM) is neither:
|
|
174
|
+
|
|
175
|
+
```ts type-equiv
|
|
176
|
+
/**
|
|
177
|
+
* Why a run failed. The kinds are orthogonal outcomes reported independently
|
|
178
|
+
* (per docs/defensive-patterns.md): a budget expiry is not an exception, an
|
|
179
|
+
* abort is not a timeout, and a substrate death is neither.
|
|
180
|
+
*
|
|
181
|
+
* - `'exception'` - the program threw or failed to parse/transform.
|
|
182
|
+
* - `'timeout'` - an implementation-owned budget expired; the message says which.
|
|
183
|
+
* - `'abort'` - {@link PtcRunRequest.signal} fired.
|
|
184
|
+
* - `'worker-exit'` - the execution substrate died without settling (e.g. OOM).
|
|
185
|
+
* - `'invalid-output'` - the completion value was not lossless JSON.
|
|
186
|
+
* - `'output-limit'` - the serialized outer logs/value/diagnostic exceeded the configured cap.
|
|
187
|
+
* - `'protocol'` - the program sent invalid or over-budget control traffic.
|
|
188
|
+
* - `'sandbox-unavailable'` - required confinement could not be established.
|
|
189
|
+
*/
|
|
190
|
+
interface PtcRunFailure {
|
|
191
|
+
/** The failure class (see the interface doc for each kind's meaning). */
|
|
192
|
+
kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit' | 'protocol' | 'sandbox-unavailable'
|
|
193
|
+
/** Human-readable detail, suitable for feeding back to a model to self-correct. */
|
|
194
|
+
message: string
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## The service
|
|
199
|
+
|
|
200
|
+
`PtcRuntime` is defined in [`src/index.ts`](../../packages/ptc-runtime/ptc-runtime/src/index.ts). `resolve(request)` returns complete execution inputs, and `run(spec)` executes them. `executionInstructions` supplies provider-owned usage guidance for consumer presentation. `timeout` reports the configured elapsed-time default and maximum when per-call overrides are supported; `resolve` still validates and caps each request. `language` selects supported program presentation; `isolation` describes the substrate without claiming security. `sandboxMode` advertises file-policy support, with `undefined` for a provider that does not supply confinement. Each implementation keeps program state separate between runs and terminates and awaits active executions during disposal.
|
|
201
|
+
|
|
202
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
203
|
+
|
|
204
|
+
<a id="cordis-surface"></a>
|
|
205
|
+
|
|
206
|
+
## Cordis API
|
|
207
|
+
|
|
208
|
+
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).
|
|
209
|
+
|
|
210
|
+
<a id="ctxptcruntime--ptcruntime-abstract-seam"></a>
|
|
211
|
+
|
|
212
|
+
### `ctx.ptcRuntime` - `PtcRuntime` (abstract seam)
|
|
213
|
+
|
|
214
|
+
Registers one `ctx.ptcRuntime` implementation. Program, budget, abort, and substrate failures resolve in PtcRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
|
|
215
|
+
|
|
216
|
+
```ts cordis-catalog
|
|
217
|
+
/**
|
|
218
|
+
* Resolve supported options and provider defaults before execution.
|
|
219
|
+
* @param request - Program, bindings, cancellation and optional execution choices.
|
|
220
|
+
* @returns Complete directory, deadline and supported authority for run.
|
|
221
|
+
* @throws When an explicit choice is invalid or unsupported by this provider.
|
|
222
|
+
*/
|
|
223
|
+
abstract resolve(request: PtcRunRequest): PtcRunSpec
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* Execute resolved inputs; program outcomes resolve as result fields.
|
|
227
|
+
* @param spec - directory, deadline, program, bindings, cancellation and supported policy.
|
|
228
|
+
* @returns Captured output and the execution outcome.
|
|
229
|
+
*/
|
|
230
|
+
abstract run(spec: PtcRunSpec): Promise<PtcRunResult>
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Source: [`packages/ptc-runtime/ptc-runtime/src/index.ts`](../../packages/ptc-runtime/ptc-runtime/src/index.ts)
|
|
234
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/sandbox.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Process Sandbox
|
|
4
|
+
|
|
5
|
+
English | [中文](sandbox.zh.md)
|
|
6
|
+
|
|
7
|
+
The process-sandbox seam of [dsh-sandbox](../../packages/sandbox/sandbox) wraps a same-world subprocess argv in a file-effect policy without coupling consumers to a platform runner. [dsh-sandbox-local](../../packages/sandbox/sandbox-local) supplies Linux bwrap/Landlock, macOS Seatbelt, and the Windows ACL restricted-token backend; [dsh-bash-sandbox](../../packages/shell/bash-sandbox) and [dsh-pwsh-sandbox](../../packages/shell/pwsh-sandbox) consume it. [dsh-sandbox-ssh](../../packages/ssh/sandbox-ssh/README.md) applies the same policy through a remote backend paired with the SSH filesystem and subprocess providers.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/sandbox/sandbox/src/index.ts`](../../packages/sandbox/sandbox/src/index.ts)
|
|
10
|
+
|
|
11
|
+
## Modes and enforcement
|
|
12
|
+
|
|
13
|
+
`SandboxMode` governs filesystem effects only. `read-only` asks the backend to deny writes - the POSIX runners additionally grant the `/dev/null` sink their shells require, while the Windows ACL runner grants no explicit writable root and reports partial enforcement for its ambient ACL gaps; `workspace-write` permits writes under the workspace root and the backend's promised temp area; `danger-full-access` bypasses confinement. Network and process visibility are outside this vocabulary.
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/**
|
|
17
|
+
* File-effect policy for confined processes. `read-only` permits only required
|
|
18
|
+
* sinks such as `/dev/null`; `workspace-write` also permits the workspace and a
|
|
19
|
+
* backend-defined temp area; `danger-full-access` bypasses confinement. Network
|
|
20
|
+
* and process visibility are outside this vocabulary.
|
|
21
|
+
*/
|
|
22
|
+
type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access'
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Only the first two modes can be sent to a provider. A `danger-full-access` consumer spawns its original argv and does not call `ctx.sandbox`.
|
|
26
|
+
|
|
27
|
+
```ts type-equiv
|
|
28
|
+
/** A confining (non-`danger-full-access`) mode - the modes a {@link SandboxPolicy} can carry. */
|
|
29
|
+
type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Enforcement is a reported fact. `full` means the backend governs every file effect promised by the mode; `partial` means an active backend or older kernel ABI governs only a subset, so consumers that require the absolute promise must reject or surface that distinction. Older Landlock ABIs and the Windows ACL runner's hard-link, unconfined-read, and AppContainer-ACL boundaries are current partial cases.
|
|
33
|
+
|
|
34
|
+
```ts type-equiv
|
|
35
|
+
/**
|
|
36
|
+
* Enforcement completeness for this host. `partial` means an active backend or
|
|
37
|
+
* older kernel ABI cannot govern every promised file effect; callers requiring
|
|
38
|
+
* an absolute boundary must not treat it as `full`.
|
|
39
|
+
*/
|
|
40
|
+
type SandboxEnforcement = 'full' | 'partial'
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Per-call policy
|
|
44
|
+
|
|
45
|
+
The complete execution policy is resolved and carried per capability call. It includes `danger-full-access` so a consumer can resolve policy once before deciding whether to bypass confinement. Normal tool calls derive `workspaceRoot` from the calling session's immutable cwd; deployment configuration is the agentless fallback. The resolver preserves absolute execution-world spelling. Enforcing providers canonicalize the root where the files exist, so a cwd containing `symlink/..` identifies the directory where the paired subprocess provider actually runs.
|
|
46
|
+
|
|
47
|
+
```ts type-equiv
|
|
48
|
+
/**
|
|
49
|
+
* The complete file-effect policy resolved for one capability call. The root
|
|
50
|
+
* is carried even under modes that do not consume it so callers can resolve
|
|
51
|
+
* policy once before choosing the enforcement path.
|
|
52
|
+
*/
|
|
53
|
+
interface SandboxExecutionPolicy {
|
|
54
|
+
/** The file-effect mode this execution runs under. */
|
|
55
|
+
mode: SandboxMode
|
|
56
|
+
/** Absolute root directory `workspace-write` may write under. */
|
|
57
|
+
workspaceRoot: string
|
|
58
|
+
/**
|
|
59
|
+
* Opaque identity of the calling session (the branded `dsh-session`
|
|
60
|
+
* SessionId). Backends key per-session state off it (e.g. windows-acl gives
|
|
61
|
+
* each live session/workspace pair a random private temp directory and SID,
|
|
62
|
+
* while the workspace SID and standing grant remain per-workspace); absent
|
|
63
|
+
* for agentless calls, which fall back to per-call backend state.
|
|
64
|
+
*/
|
|
65
|
+
sessionId?: SessionId
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`ctx.sandboxPolicy.resolve()` accepts the active session and, for an approved retry, an explicit mode. The service owns precedence and root fallback so bash and fs do not repeat it.
|
|
70
|
+
|
|
71
|
+
```ts type-equiv
|
|
72
|
+
/** Inputs that select the sandbox policy for one capability call. */
|
|
73
|
+
interface SandboxPolicyRequest {
|
|
74
|
+
/** Calling session; its immutable cwd becomes the workspace boundary. */
|
|
75
|
+
session?: Session
|
|
76
|
+
/** Explicit approved mode override, which outranks session policy. */
|
|
77
|
+
mode?: SandboxMode
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Only a confined execution reaches `ctx.sandbox`; its provider policy narrows the mode while retaining the same root. This permits concurrent sessions, consumers, and one-shot escalated retries to ask the same provider for different boundaries without mutating provider state.
|
|
82
|
+
|
|
83
|
+
```ts type-equiv
|
|
84
|
+
/**
|
|
85
|
+
* What one confined execution is allowed to touch - carried PER CALL, not
|
|
86
|
+
* fixed on the provider: two consumers may confine under different policies
|
|
87
|
+
* at the same instant (bash under `read-only` while a confined child agent
|
|
88
|
+
* needs its state directory writable), and an approved escalated retry is a
|
|
89
|
+
* new call with a wider policy. Defaulting/resolution is an explicit step at
|
|
90
|
+
* the consumer boundary; the provider treats the policy as fully specified.
|
|
91
|
+
*/
|
|
92
|
+
interface SandboxPolicy extends SandboxExecutionPolicy {
|
|
93
|
+
/** The file-effect mode this execution runs under. */
|
|
94
|
+
mode: ConfinedSandboxMode
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
<a id="wrapped-argv-and-classification-dialects"></a>
|
|
99
|
+
|
|
100
|
+
## Wrapped argv and classification dialects
|
|
101
|
+
|
|
102
|
+
`RunnerFailureRule` combines evidence that a runner failed before executing the command. A consumer requires a nonzero exit, the optional allowed-exit-code gate, and a case-insensitive fatal signature within one remaining stderr line. Case-insensitive exact full-line informational exclusions are removed first, so a benign runner notice cannot prove failure by itself. The matched line remains available as error detail; classification does not rewrite stderr.
|
|
103
|
+
|
|
104
|
+
```ts type-equiv
|
|
105
|
+
/**
|
|
106
|
+
* Evidence that identifies a sandbox runner failing before it executes the
|
|
107
|
+
* wrapped command. A consumer first applies {@link allowedExitCodes} when
|
|
108
|
+
* present, removes {@link informationalLines} by case-insensitive exact line
|
|
109
|
+
* equality, then matches {@link fatalSignatures} case-insensitively within
|
|
110
|
+
* each remaining stderr line. Exit status alone never proves runner failure.
|
|
111
|
+
*/
|
|
112
|
+
interface RunnerFailureRule {
|
|
113
|
+
/** Nonzero process exit codes on which this rule may match; omitted permits any nonzero exit. */
|
|
114
|
+
allowedExitCodes?: readonly number[]
|
|
115
|
+
/** Non-empty substrings identifying a fatal runner diagnostic on one stderr line. */
|
|
116
|
+
fatalSignatures: readonly string[]
|
|
117
|
+
/** Benign stderr lines excluded by exact full-line equality before fatal matching. */
|
|
118
|
+
informationalLines?: readonly string[]
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`ConfinedArgv` is what the consumer spawns. Besides the replacement argv, it carries the backend's enforcement fact and two orthogonal stderr classifiers. `denialSignatures` identify the confined command being blocked while the sandbox works correctly. `runnerFailureRules` identify the sandbox runner refusing or failing before it executes the command; consumers check these first and surface a sandbox infrastructure failure, never an ordinary task failure.
|
|
123
|
+
|
|
124
|
+
```ts type-equiv
|
|
125
|
+
/**
|
|
126
|
+
* A {@link SandboxProvider.confine} result: the argv to spawn in place of
|
|
127
|
+
* the caller's own, plus the enforcement completeness the selected backend
|
|
128
|
+
* achieves for it.
|
|
129
|
+
*/
|
|
130
|
+
interface ConfinedArgv {
|
|
131
|
+
/** The wrapped argv (runner, profile, separator, then the caller's argv). */
|
|
132
|
+
argv: string[]
|
|
133
|
+
/** How completely the selected backend enforces the policy's file effects. */
|
|
134
|
+
enforcement: SandboxEnforcement
|
|
135
|
+
/**
|
|
136
|
+
* The selected backend's denial DIALECT: the case-insensitive stderr
|
|
137
|
+
* substrings a file effect denied by THIS backend produces (EROFS text
|
|
138
|
+
* under bwrap's read-only binds, EACCES under Landlock, EPERM under
|
|
139
|
+
* Seatbelt). A consumer that infers denials from a failed run's stderr
|
|
140
|
+
* matches against exactly these rather than a cross-backend union - the
|
|
141
|
+
* union claims denials a given backend never produces.
|
|
142
|
+
*/
|
|
143
|
+
denialSignatures: readonly string[]
|
|
144
|
+
/**
|
|
145
|
+
* Structured runner-failure evidence rules. Consumers require a matching
|
|
146
|
+
* fatal stderr line (after informational exclusions) and any rule-specific
|
|
147
|
+
* exit-code gate before checking denial signatures: runner failure means the
|
|
148
|
+
* command never ran, while denial means confinement worked and blocked it.
|
|
149
|
+
*/
|
|
150
|
+
runnerFailureRules: readonly RunnerFailureRule[]
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The [local provider](../../packages/sandbox/sandbox-local/README.md) owns operator configuration and maps its runner dialect into these rules. The [sandboxed bash consumer](../../packages/shell/bash-sandbox/README.md) owns spawn and result attribution.
|
|
155
|
+
|
|
156
|
+
## Provider and fail-closed errors
|
|
157
|
+
|
|
158
|
+
`await ctx.sandbox.confine(argv, policy, signal)` resolves policy paths and returns a `ConfinedArgv` from the execution world, or rejects with `SandboxUnavailableError` and code `SANDBOX_UNAVAILABLE` when no usable backend exists. The optional signal cancels resolution before launch. Consumers may also classify a failure while spawning or observing the returned argv; that attribution belongs to the consumer contract. Silent unconfined passthrough is never legal for a confined policy.
|
|
159
|
+
|
|
160
|
+
Provider selection, probing, caching, and backend-specific enforcement reports belong to the [local provider](../../packages/sandbox/sandbox-local/README.md).
|
|
161
|
+
|
|
162
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
163
|
+
|
|
164
|
+
<a id="cordis-surface"></a>
|
|
165
|
+
|
|
166
|
+
## Cordis API
|
|
167
|
+
|
|
168
|
+
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).
|
|
169
|
+
|
|
170
|
+
<a id="ctxsandbox--sandboxprovider-abstract-seam"></a>
|
|
171
|
+
|
|
172
|
+
### `ctx.sandbox` - `SandboxProvider` (abstract seam)
|
|
173
|
+
|
|
174
|
+
Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.
|
|
175
|
+
|
|
176
|
+
```ts cordis-catalog
|
|
177
|
+
/**
|
|
178
|
+
* Wrap `argv` so it executes confined under `policy` on this host; the
|
|
179
|
+
* caller spawns the returned argv in place of its own.
|
|
180
|
+
* @param argv - the exact argv the caller is about to spawn (program plus
|
|
181
|
+
* arguments), NOT a shell string - a shell-shaped consumer passes
|
|
182
|
+
* `['bash', '-c', command]`.
|
|
183
|
+
* @param policy - the file-effect policy this execution runs under,
|
|
184
|
+
* carried per call (see {@link SandboxPolicy}).
|
|
185
|
+
* @param signal - cancellation while the provider resolves the policy and runner.
|
|
186
|
+
* @returns the argv to spawn instead, plus the enforcement completeness
|
|
187
|
+
* the selected backend achieves for it.
|
|
188
|
+
*/
|
|
189
|
+
abstract confine(argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): Promise<ConfinedArgv>
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Source: [`packages/sandbox/sandbox/src/index.ts`](../../packages/sandbox/sandbox/src/index.ts)
|
|
193
|
+
|
|
194
|
+
<a id="ctxsandboxpolicy--sandboxpolicyservice"></a>
|
|
195
|
+
|
|
196
|
+
### `ctx.sandboxPolicy` - `SandboxPolicyService`
|
|
197
|
+
|
|
198
|
+
The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode, fallback workspace root, and current request-time policy section. Tool layers call resolve for each execution so a session's mode log and immutable cwd travel together to every enforcing capability.
|
|
199
|
+
|
|
200
|
+
```ts cordis-catalog
|
|
201
|
+
/**
|
|
202
|
+
* Resolve the complete policy for one capability call. An approved explicit
|
|
203
|
+
* mode outranks the session's last `sandbox/mode` event, which outranks the
|
|
204
|
+
* deployment default. A session cwd is its workspace-write boundary; the
|
|
205
|
+
* configured root is the fallback for agentless calls and sessions without a
|
|
206
|
+
* cwd.
|
|
207
|
+
* @param request - optional session and approved mode override.
|
|
208
|
+
* @returns the fully resolved per-call mode and absolute workspace root.
|
|
209
|
+
*/
|
|
210
|
+
resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Read the session override without applying the deployment default.
|
|
214
|
+
* @param session - session whose log supplies the override.
|
|
215
|
+
* @returns the last logged mode, or `undefined` without one.
|
|
216
|
+
*/
|
|
217
|
+
overrideOf(session: Session): SandboxMode | undefined
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Types: [Session](session.md)
|
|
221
|
+
|
|
222
|
+
Source: [`packages/sandbox/sandbox-policy/src/index.ts`](../../packages/sandbox/sandbox-policy/src/index.ts)
|
|
223
|
+
<!-- END GENERATED cordis-surface -->
|