@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,186 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/terminal.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Persistent PTY Sessions
|
|
4
|
+
|
|
5
|
+
English | [中文](terminal.zh.md)
|
|
6
|
+
|
|
7
|
+
Types shared by PTY backends, `ctx.terminals`, and the model-facing consumer. The [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) owns the rationale; this page records the cross-package vocabulary from [`packages/terminal/terminal/src/types.ts`](../../packages/terminal/terminal/src/types.ts).
|
|
8
|
+
|
|
9
|
+
## Identity and readiness
|
|
10
|
+
|
|
11
|
+
`TerminalSessionId` is a service-minted branded id. Optional names are owner-local display metadata; authorization compares the exact owning `Agent`, not a name or guessed id.
|
|
12
|
+
|
|
13
|
+
`TerminalWaitReason` says why one send returned. It is independent from `TerminalSessionStatus`: silence or timeout may return while the top-level shell remains alive, while `session_exit` means that shell exited rather than an arbitrary foreground child.
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/** Why one interactive send returned control to its caller. */
|
|
17
|
+
type TerminalWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```ts type-equiv
|
|
21
|
+
/** Top-level PTY process status, independent of a send's wait reason. */
|
|
22
|
+
type TerminalSessionStatus =
|
|
23
|
+
| { kind: 'running' }
|
|
24
|
+
| { kind: 'exited'; exitCode: number | null; signal: NodeJS.Signals | null }
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Backend and live session
|
|
28
|
+
|
|
29
|
+
A backend owns how one registered type starts and detects readiness. `TerminalSessionService` publishes the returned session only after setup succeeds, then owns id authorization and cleanup. A backend that cannot clean partial startup resources rejects with `TerminalBackendCleanupError`, allowing disposal to retain the cleanup failure without replacing the caller's cancellation reason. A backend session owns terminal state and captured-resource quiescence.
|
|
30
|
+
|
|
31
|
+
```ts type-equiv
|
|
32
|
+
/** Replaceable provider for one PTY session type. */
|
|
33
|
+
interface TerminalBackend {
|
|
34
|
+
/** Stable type selected by {@link TerminalSpawnRequest.type}. */
|
|
35
|
+
readonly type: string
|
|
36
|
+
/** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link TerminalBackendCleanupError}. */
|
|
37
|
+
spawn(spec: TerminalBackendSpawnSpec): Promise<TerminalBackendSession>
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```ts type-equiv
|
|
42
|
+
/** Backend-owned live session retained by {@link TerminalSessionService}. */
|
|
43
|
+
interface TerminalBackendSession {
|
|
44
|
+
/** Initial bounded terminal output returned from `terminal_open`. */
|
|
45
|
+
readonly motd: string
|
|
46
|
+
/** Top-level process id when one exists. */
|
|
47
|
+
readonly pid?: number
|
|
48
|
+
/** Start one exclusive send operation. */
|
|
49
|
+
startSend(request: TerminalSendRequest): TerminalSendOperation
|
|
50
|
+
/** Read one bounded page from retained scrollback. */
|
|
51
|
+
read(request: TerminalReadRequest): TerminalReadResult
|
|
52
|
+
/** Signal the verified foreground process group. */
|
|
53
|
+
signal(signal: TerminalSignal): Promise<TerminalSignalResult>
|
|
54
|
+
/** Observe top-level process status. */
|
|
55
|
+
status(): TerminalSessionStatus
|
|
56
|
+
/** Idempotently close the captured owned process tree and await quiescence. */
|
|
57
|
+
close(reason: string): Promise<void>
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Send and retained output
|
|
62
|
+
|
|
63
|
+
One live session accepts one active send. Its operation exposes a consuming output cursor for generic background jobs and one terminal result for a foreground caller. `TerminalReadResult` separately pages the bounded session scrollback.
|
|
64
|
+
|
|
65
|
+
```ts type-equiv
|
|
66
|
+
/** Live backend-owned send; exactly one may be active per PTY session. */
|
|
67
|
+
interface TerminalSendOperation {
|
|
68
|
+
/** Resolves after readiness, timeout, cancellation, or top-level process exit. */
|
|
69
|
+
done: Promise<TerminalSendResult>
|
|
70
|
+
/** Consume output produced since the prior call. */
|
|
71
|
+
readOutput(): TerminalSendRead
|
|
72
|
+
/** Request `SIGINT`; returns false after the operation settled. */
|
|
73
|
+
cancel(): boolean
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
```ts type-equiv
|
|
78
|
+
/** Settled result for one foreground or background send. */
|
|
79
|
+
interface TerminalSendResult {
|
|
80
|
+
/** Bounded rendered terminal delta remaining at settlement. */
|
|
81
|
+
viewport: string
|
|
82
|
+
/** Why the wait returned; this does not imply arbitrary child-process exit. */
|
|
83
|
+
waitReason: TerminalWaitReason
|
|
84
|
+
/** Top-level session status observed at settlement. */
|
|
85
|
+
sessionStatus: TerminalSessionStatus
|
|
86
|
+
/** Whether output was dropped from the operation or retained scrollback. */
|
|
87
|
+
truncated: boolean
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Ownership and durability
|
|
92
|
+
|
|
93
|
+
`TerminalSessionService` attaches one awaited cleanup to the exact owner scope, rejects foreign operations, and keeps sessions alive across backend or tool-plugin reload. PTY state and raw bytes remain process-local. Model input and bounded returned output are durable through the existing `tool/call`, `tool/result`, and task-result paths rather than duplicate PTY session events.
|
|
94
|
+
|
|
95
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
96
|
+
|
|
97
|
+
<a id="cordis-surface"></a>
|
|
98
|
+
|
|
99
|
+
## Cordis API
|
|
100
|
+
|
|
101
|
+
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).
|
|
102
|
+
|
|
103
|
+
<a id="ctxterminals--terminalsessionservice"></a>
|
|
104
|
+
|
|
105
|
+
### `ctx.terminals` - `TerminalSessionService`
|
|
106
|
+
|
|
107
|
+
In-process registry for replaceable PTY backends and exact-Agent sessions.
|
|
108
|
+
|
|
109
|
+
```ts cordis-catalog
|
|
110
|
+
/**
|
|
111
|
+
* Register one backend type for this effect scope.
|
|
112
|
+
* @param backend - provider with a non-empty unique type.
|
|
113
|
+
* @returns disposer that removes exactly this contribution.
|
|
114
|
+
*/
|
|
115
|
+
registerBackend(backend: TerminalBackend): () => void
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* List registered backend types in registration order.
|
|
119
|
+
* @returns fresh backend type names.
|
|
120
|
+
*/
|
|
121
|
+
listBackends(): string[]
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Create and publish one owner-scoped session after backend setup succeeds.
|
|
125
|
+
* @param owner - exact registered Agent that owns access and cleanup.
|
|
126
|
+
* @param request - backend type plus optional owner-local name and cwd.
|
|
127
|
+
* @param signal - cancellation of unpublished setup.
|
|
128
|
+
* @returns published identity, metadata, status, and MOTD.
|
|
129
|
+
*/
|
|
130
|
+
async spawn(owner: Agent, request: TerminalSpawnRequest, signal?: AbortSignal): Promise<TerminalSpawnResult>
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* Test whether an exact owner has a published session or unpublished spawn.
|
|
134
|
+
* @param owner - exact live owner to inspect.
|
|
135
|
+
* @returns true across the entire spawn-to-close interval, with no publication gap.
|
|
136
|
+
*/
|
|
137
|
+
hasOwnerActivity(owner: Agent): boolean
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Start one exclusive interactive send.
|
|
141
|
+
* @param owner - exact session owner.
|
|
142
|
+
* @param id - target PTY identity.
|
|
143
|
+
* @param request - explicit text, submit behavior, and cancellation.
|
|
144
|
+
* @returns live operation handle for foreground await or task registration.
|
|
145
|
+
*/
|
|
146
|
+
startSend(owner: Agent, id: TerminalSessionId, request: TerminalSendRequest): TerminalSendOperation
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Read one bounded scrollback page from an owned session.
|
|
150
|
+
* @param owner - exact session owner.
|
|
151
|
+
* @param id - target PTY identity.
|
|
152
|
+
* @param request - optional newest-relative offset and line count.
|
|
153
|
+
* @returns bounded retained text and pagination metadata.
|
|
154
|
+
*/
|
|
155
|
+
read(owner: Agent, id: TerminalSessionId, request: TerminalReadRequest = {}): TerminalReadResult
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* Deliver an allowed signal through an owned backend session.
|
|
159
|
+
* @param owner - exact session owner.
|
|
160
|
+
* @param id - target PTY identity.
|
|
161
|
+
* @param signal - allowed POSIX signal name.
|
|
162
|
+
* @returns delivered foreground process-group identity.
|
|
163
|
+
*/
|
|
164
|
+
signal(owner: Agent, id: TerminalSessionId, signal: TerminalSignal): Promise<TerminalSignalResult>
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* Close one owned session and remove it only after quiescent backend cleanup.
|
|
168
|
+
* @param owner - exact session owner.
|
|
169
|
+
* @param id - target PTY identity.
|
|
170
|
+
* @param reason - diagnostic cleanup reason.
|
|
171
|
+
* @returns true for a newly closed session, false when the same close is already in flight.
|
|
172
|
+
*/
|
|
173
|
+
async kill(owner: Agent, id: TerminalSessionId, reason: string = 'model request'): Promise<boolean>
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* List fresh snapshots for exactly one owner.
|
|
177
|
+
* @param owner - exact owner whose sessions are visible.
|
|
178
|
+
* @returns owner-visible snapshots in publication order.
|
|
179
|
+
*/
|
|
180
|
+
list(owner: Agent): TerminalSessionSnapshot[]
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Types: [Agent](core.md)
|
|
184
|
+
|
|
185
|
+
Source: [`packages/terminal/terminal/src/index.ts`](../../packages/terminal/terminal/src/index.ts)
|
|
186
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/todo.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Todo
|
|
4
|
+
|
|
5
|
+
English | [中文](todo.zh.md)
|
|
6
|
+
|
|
7
|
+
The durable todo vocabulary owned by [`@deepseek-ai/dsh-tool-todo`](../../packages/todo/tool-todo/README.md). The model-facing tool replaces one agent session's whole list; the package also owns the event declaration, replay projection, and invariant companion. Tool behavior and configuration are on the [package README](../../packages/todo/tool-todo/README.md).
|
|
8
|
+
|
|
9
|
+
Source: [`packages/todo/tool-todo/src/types.ts`](../../packages/todo/tool-todo/src/types.ts)
|
|
10
|
+
|
|
11
|
+
## `TodoItem` - one list entry
|
|
12
|
+
|
|
13
|
+
```ts type-equiv
|
|
14
|
+
/**
|
|
15
|
+
* One entry in an agent's todo list - the unit of the `todo/write`
|
|
16
|
+
* whole-list snapshot declared by this package.
|
|
17
|
+
*
|
|
18
|
+
* Deliberately minimal: a human-readable `content` line and a three-state
|
|
19
|
+
* `status`. No id, priority, or `activeForm` - the list is replaced wholesale
|
|
20
|
+
* on every write (last-write-wins), so entries need no stable identity. The
|
|
21
|
+
* three statuses describe the complete portable lifecycle needed by model and
|
|
22
|
+
* UI consumers.
|
|
23
|
+
*/
|
|
24
|
+
interface TodoItem {
|
|
25
|
+
/** What this task is - a short imperative line shown in the UI. */
|
|
26
|
+
content: string
|
|
27
|
+
/** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
|
|
28
|
+
status: 'pending' | 'in_progress' | 'completed'
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Durable event and invariant
|
|
33
|
+
|
|
34
|
+
The package declaration-merges `todo/write: { todos: TodoItem[] }` into `SessionEventMap`. The event is log-only and carries the complete replacement list; the generated [persistence catalog](../persistence-catalog.md#todowrite--log-only) records its declaration site. The package's invariant companion validates existing and newly announced sessions in one pass, then tracks committed turn boundaries incrementally so every live `todo/write` is checked before append without rescanning the log.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/token-meter.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Token Meter
|
|
4
|
+
|
|
5
|
+
English | [中文](token-meter.zh.md)
|
|
6
|
+
|
|
7
|
+
`@deepseek-ai/dsh-token-meter` exposes one detached replay snapshot for request pressure and positional surface pricing. `logRevision` is the number of durable events consumed for every field in the measurement.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/llm/token-meter/src/types.ts`](../../packages/llm/token-meter/src/types.ts)
|
|
10
|
+
|
|
11
|
+
## `TokenMeasurement`
|
|
12
|
+
|
|
13
|
+
```ts type-equiv
|
|
14
|
+
/** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
|
|
15
|
+
interface TokenMeasurement {
|
|
16
|
+
/** Number of durable events consumed; equal to the next unread event seq. */
|
|
17
|
+
readonly logRevision: SessionLogOffset
|
|
18
|
+
/** Provider or heuristic anchor used for this measurement. */
|
|
19
|
+
readonly baseline: TokenMeasurementBaseline
|
|
20
|
+
/** Signed repricing of current surface content relative to the baseline anchor. */
|
|
21
|
+
readonly surfaceDeltaTokens: number
|
|
22
|
+
/** Non-negative current request-and-response pressure. */
|
|
23
|
+
readonly totalTokens: number
|
|
24
|
+
/** Total route-priced request tokens across the current surface; equals the sum of the node prices. */
|
|
25
|
+
readonly surfaceTokens: number
|
|
26
|
+
/** Current surface nodes in positional head-to-tail order. */
|
|
27
|
+
readonly nodes: readonly TokenSurfaceNode[]
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Every measurement resolves the effective envelope's routed provider/model to that route's declared request-image pricing through `ctx.llm`, so image occurrences are priced as the visual tokens plus model-visible text the request actually sends; routes and compositions without declared pricing keep the fixed heuristic. `baseline.kind === 'usage'` means the latest successful provider call has the same canonical request envelope and its total is no lower than that call's full route-priced anchor. `estimated` means no reusable conservative usage anchor exists, so the service priced the complete envelope and surface itself. A later successful request replaces the earlier anchor; signed `surfaceDeltaTokens` preserves growth and shrinkage relative to a matching anchor, repricing both sides under the same route. `totalTokens` remains request-and-response pressure, while `surfaceTokens` is the surface-only route-priced total and equals the sum of the node prices.
|
|
32
|
+
|
|
33
|
+
## `TokenSurfaceNode`
|
|
34
|
+
|
|
35
|
+
```ts type-equiv
|
|
36
|
+
/** One token-priced node in the current ordered session surface. */
|
|
37
|
+
interface TokenSurfaceNode {
|
|
38
|
+
/** Durable sequence number of the surface event. */
|
|
39
|
+
readonly seq: SessionSeq
|
|
40
|
+
/**
|
|
41
|
+
* Request-pressure tokens for the exact message projected by this node under
|
|
42
|
+
* the measured route: image occurrences carry the route's declared visual
|
|
43
|
+
* price when the routed adapter declares one, and the fixed heuristic
|
|
44
|
+
* otherwise. Trigger, retention, and range selection all read this price.
|
|
45
|
+
*/
|
|
46
|
+
readonly tokens: number
|
|
47
|
+
/**
|
|
48
|
+
* Fixed-heuristic tokens for the same message, independent of any route.
|
|
49
|
+
* The shadow-price protocol prices replacements with this value so the O(1)
|
|
50
|
+
* projection fold stays in agreement with its own appends.
|
|
51
|
+
*/
|
|
52
|
+
readonly heuristicTokens: number
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Surface order is authoritative; replacement nodes can have higher durable seqs than later positional nodes. The snapshot is immutable and does not grow when the underlying replay fold advances.
|
|
57
|
+
|
|
58
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
59
|
+
|
|
60
|
+
<a id="cordis-surface"></a>
|
|
61
|
+
|
|
62
|
+
## Cordis API
|
|
63
|
+
|
|
64
|
+
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).
|
|
65
|
+
|
|
66
|
+
<a id="ctxtokenmeter--tokenmeter"></a>
|
|
67
|
+
|
|
68
|
+
### `ctx.tokenMeter` - `TokenMeter`
|
|
69
|
+
|
|
70
|
+
Replay owner for one service-wide estimator and isolated per-session folds.
|
|
71
|
+
|
|
72
|
+
```ts cordis-catalog
|
|
73
|
+
/**
|
|
74
|
+
* Measure current request pressure and surface through the durable tail.
|
|
75
|
+
*
|
|
76
|
+
* The effective envelope's routed provider/model selects the request-image
|
|
77
|
+
* pricing every node is priced under: a route whose adapter declares image
|
|
78
|
+
* pricing charges each retained image its visual tokens plus its
|
|
79
|
+
* model-visible text, while other routes keep the fixed heuristic. Provider
|
|
80
|
+
* usage is reused only when the latest successful call's canonical request
|
|
81
|
+
* envelope matches `requestHeader` and its total is no lower than that
|
|
82
|
+
* call's full route-priced anchor; otherwise the complete envelope and
|
|
83
|
+
* surface are repriced. The anchor includes all surface nodes immediately
|
|
84
|
+
* before the assistant message, including inputs admitted after step/start.
|
|
85
|
+
*
|
|
86
|
+
* `requestHeader` replaces the latest logged envelope for pressure and node
|
|
87
|
+
* pricing; the node set always describes the current session surface. Every
|
|
88
|
+
* call clones those positional nodes, so measurement is O(surface).
|
|
89
|
+
*
|
|
90
|
+
* @param session - session to replay through its current durable tail.
|
|
91
|
+
* @param requestHeader - optional effective request envelope replacing the latest logged header.
|
|
92
|
+
* @returns a detached deeply immutable pressure and surface measurement.
|
|
93
|
+
*/
|
|
94
|
+
measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Heuristically price one model-visible message (instance face of the pure
|
|
98
|
+
* `estimateMessage` export from `estimate.ts`).
|
|
99
|
+
* @param message - message to price without mutation.
|
|
100
|
+
* @returns content and role-framing tokens under the fixed service heuristic.
|
|
101
|
+
*/
|
|
102
|
+
estimateMessage(message: Message): number
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Types: [EpochHeader](session.md) · [Message](llm-streaming.md) · [Session](session.md)
|
|
106
|
+
|
|
107
|
+
Source: [`packages/llm/token-meter/src/index.ts`](../../packages/llm/token-meter/src/index.ts)
|
|
108
|
+
<!-- END GENERATED cordis-surface -->
|