@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,201 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/slots.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Web Client Slots
|
|
4
|
+
|
|
5
|
+
English | [中文](slots.zh.md)
|
|
6
|
+
|
|
7
|
+
Slots are the Web Client's typed React composition system. [`dsh-client-ui-slots`](../../packages/client/ui-slots/README.md) defines the React-free registry and type algebra; [`dsh-client-ui-renderer`](../../packages/client/ui-renderer/README.md) binds observable sources to hooks, renders the tree, and owns React contexts internally. A feature plugin contributes UI through `ctx.slots.register()` and never imports another feature plugin's component.
|
|
8
|
+
|
|
9
|
+
This page documents slot ownership, component inputs, extension APIs, and the shipped hierarchy. The surrounding boot, Remote, Client model, and Conversation paths are in [Web Client architecture](web-client.md).
|
|
10
|
+
|
|
11
|
+
`plugins.bundle.config` supplies bundle detail configuration, keyed by npm package name. `plugins.bundle.activation` renders optional guidance after user-requested enablement, with owner callbacks to dismiss or open that bundle’s details. `conversation.input.activity` supplies one action between the model selector and Send, with toolbar expansion released on unmount.
|
|
12
|
+
|
|
13
|
+
## Declaration and lifecycle
|
|
14
|
+
|
|
15
|
+
`SlotMap` is the compile-time registry. A package declaration-merges the key, cardinality, scope, owner props, keyed props, and optional slot-level inject face. The runtime declaration is the matching `children` entry on the component that owns the render location.
|
|
16
|
+
|
|
17
|
+
Declaring a child has three effects: it makes the child key live, authorizes that parent entry's `renderSlot` or `renderSlotChain` call, and records the runtime dispatch specification. One live entry owns each declaration. Registering into an undeclared slot or declaring a child already owned elsewhere fails during plugin activation.
|
|
18
|
+
|
|
19
|
+
`root` is the only built-in declaration and the only key rendered through the Cordis service itself. `ui-renderer` calls `ctx.slots.renderSlot('root', {})`; every descendant is rendered through the `renderSlot` or `renderSlotChain` prop of the entry that declared it.
|
|
20
|
+
|
|
21
|
+
Registrations and declarations follow Cordis effect lifetimes. Disposing an entry removes its contribution and recursively collapses the child slots it declared. A feature that contributes into another package's slot therefore uses `ctx.slots.inject(key, callback)`: the callback runs for each declaration lifetime, its effects are removed when the owner collapses, and it runs again if the owner is mounted again.
|
|
22
|
+
|
|
23
|
+
```tsx ignore-check
|
|
24
|
+
import type { Context } from '@deepseek-ai/cordis'
|
|
25
|
+
import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
|
|
26
|
+
import type {} from '@deepseek-ai/dsh-client-ui-session/client'
|
|
27
|
+
import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
|
|
28
|
+
|
|
29
|
+
type HeaderActionProps = PropsRuntime<'conversation.session.header.actions'>
|
|
30
|
+
|
|
31
|
+
function HeaderAction({ useSession }: HeaderActionProps) {
|
|
32
|
+
const running = useSession(snapshot => snapshot.running)
|
|
33
|
+
return <button disabled={running}>Review</button>
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export const inject = ['slots']
|
|
37
|
+
|
|
38
|
+
export function apply(ctx: Context): void {
|
|
39
|
+
ctx.slots.inject('conversation.session.header.actions', () =>
|
|
40
|
+
ctx.slots.register({
|
|
41
|
+
name: 'conversation.session.header.actions',
|
|
42
|
+
id: 'review',
|
|
43
|
+
order: 100,
|
|
44
|
+
}, HeaderAction))
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Cardinality and scope
|
|
49
|
+
|
|
50
|
+
The slot declaration fixes two independent axes.
|
|
51
|
+
|
|
52
|
+
| Axis | Value | Meaning |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| cardinality | `single` | One cell. The active priority winner renders. Use a child slot instead of treating this as an additive list. |
|
|
55
|
+
| cardinality | `list` | Cells are addressed by required `id` and ordered by `order`, then registration order. |
|
|
56
|
+
| cardinality | `keyed` | The owner dispatches an `entryKey`; the matching cell renders with any key-specific props. |
|
|
57
|
+
| cardinality | `chain` | Each entry supplies a pure `select(owner)` function. The first non-null result in priority order renders and receives that result as `matched`; otherwise the owner fallback renders. |
|
|
58
|
+
| scope | `root` | One root-scoped component and store instance. |
|
|
59
|
+
| scope | `session-maybe` | Inherits the surrounding Provider binding but stays renderable without one; Session values are optional. |
|
|
60
|
+
| scope | `session` | Requires a resolved surrounding Provider binding and receives definite Session values. |
|
|
61
|
+
|
|
62
|
+
`priority` is a shadowing rank for `single`, `list`, and `keyed` cells and an election order for `chain`. Lower values run or render first. Ordinary additive contributions should choose a fresh list `id` or keyed `key`; intentionally reusing a shipped cell replaces its presentation.
|
|
63
|
+
|
|
64
|
+
## Component inputs
|
|
65
|
+
|
|
66
|
+
A registered component receives inputs assembled at its binding site. Components derive these types rather than copying their members.
|
|
67
|
+
|
|
68
|
+
| Input | Declared by | Component type |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| owner values and standard scope values | the `SlotMap` row and installed scope adapters | `PropsRuntime<K>` |
|
|
71
|
+
| authorized child renderers | the registration's `children` keys | `PropsRenderSlots<S>` |
|
|
72
|
+
| selector hook and mutation callbacks for shared view state | the registration's `store` | `PropsStore<H>` |
|
|
73
|
+
| private data, callbacks, and observable hooks | the registration's `inject` factory | `InjectFace<I>` |
|
|
74
|
+
| localized `t` function | the registration's `locale` namespace | `PropsLocale<N>` |
|
|
75
|
+
| selected chain value | the registration's `select` result | `matched` through `ComposedProps` |
|
|
76
|
+
|
|
77
|
+
`SessionProvider` is also present in `PropsRenderSlots` when an entry declares a `session` or `session-maybe` child. With no `session` prop it inherits the surrounding binding; an explicit `SessionReference` or `undefined` overrides only that subtree. The Provider does not key its whole body. A strict `session` entry remounts when its binding generation changes. A blank `session-maybe` entry adopts its first binding without remounting, then remounts for a later generation or a return to absence.
|
|
78
|
+
|
|
79
|
+
Components never receive `ctx`. Parent-owned point-in-time values enter through the owner argument to `renderSlot`; shared view state uses a declared store; services and model objects stay in the `apply` closure and are projected into callbacks or observable sources.
|
|
80
|
+
|
|
81
|
+
## Framework-provided hooks
|
|
82
|
+
|
|
83
|
+
The shipped adapters add these standard props. They are available according to the target slot's scope, independent of which package registered the component.
|
|
84
|
+
|
|
85
|
+
| Availability | Props | Owner |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| every scope | `useSessions`, `useSessionStatus`, `useSessionRetainInfo` | `ui-session` |
|
|
88
|
+
| every scope | `useWorkspaces` | `ui-workspace` |
|
|
89
|
+
| every scope | `usePanelInfo` | `ui-layout` |
|
|
90
|
+
| `session` | `sessionId`, `useSession`, `useProjection` | `ui-session` |
|
|
91
|
+
| `session-maybe` | optional `sessionId`, `useSession`, `useProjection` results | `ui-session` |
|
|
92
|
+
| `session` | `useConversation`, `useInput`, `inputActions` | `ui-conversation` |
|
|
93
|
+
| `session-maybe` | optional `useConversation`, `useInput`, `inputActions` results | `ui-conversation` |
|
|
94
|
+
| `session` | `useChat` | `ui-chat` |
|
|
95
|
+
| `session` | `useTrajectory` | `ui-trajectory` |
|
|
96
|
+
|
|
97
|
+
The renderer also creates `useStore` from a declared store and `t` from a declared locale namespace. These are registration-derived props rather than global standard props.
|
|
98
|
+
|
|
99
|
+
Framework and domain-adapter owners may extend the standard set through `ctx.slots.provideRoot()` or `ctx.uiSession.provide()` together with the corresponding `GlobalStandardProps`, `SessionStandardProps`, or `SessionMaybeStandardProps` declaration merge. A feature component should not create a React hook prop itself or add a global standard prop for entry-private data.
|
|
100
|
+
|
|
101
|
+
## Developer-provided injection
|
|
102
|
+
|
|
103
|
+
The `inject` option on a registration is the ordinary feature-owned injection point. Its factory runs in the plugin's `apply` world, may close over injected Cordis services, and returns only the data and callbacks that the component needs. For a `session` slot it receives `sessionId`; for `session-maybe` it receives `sessionId | undefined`; when a store is declared it also receives the store's bound actions.
|
|
104
|
+
|
|
105
|
+
A reserved `hooks` object in that return value accepts bare `getSnapshot`/`subscribe` sources. The renderer converts `hooks: { status }` into a `useStatus(selector)` component prop and caches the binding by source identity. Components do not receive the source itself and do not call `useSyncExternalStore` directly.
|
|
106
|
+
|
|
107
|
+
The owner of a slot may put an `inject` face in the child declaration when every occupant needs the same capability. Plain members reach all occupants unchanged. Function-valued members inside its `hooks` object are hook factories; they receive the slot's standard props and optional per-render `hookContext`, then return the constrained hook exposed to the occupant. `conversation.chat.node` uses this mechanism to provide `useTurnData(key)` for the node currently being rendered.
|
|
108
|
+
|
|
109
|
+
Use owner props for values already known at one render occurrence, registration `inject` for one entry's callbacks and private observables, slot-level `inject` for a capability controlled by the slot owner, and a declared store for mutable view state shared across entries or preserved across remounts. React nodes compose through child slots, not through injected values.
|
|
110
|
+
|
|
111
|
+
## Current hierarchy
|
|
112
|
+
|
|
113
|
+
The hierarchy below is the shipped declaration tree. A child exists only while the named parent entry is mounted; optional feature entries can therefore make a subtree appear or disappear as one lifecycle unit.
|
|
114
|
+
|
|
115
|
+
```text
|
|
116
|
+
root
|
|
117
|
+
├─ sidebar
|
|
118
|
+
│ ├─ sidebar.brand.mark
|
|
119
|
+
│ ├─ sidebar.brand.name
|
|
120
|
+
│ ├─ sidebar.panellist
|
|
121
|
+
│ ├─ sidebar.footer.action
|
|
122
|
+
│ ├─ sidebar.workspaces
|
|
123
|
+
│ │ ├─ sidebar.workspaces.directoryFlow
|
|
124
|
+
│ │ ├─ sidebar.workspaces.session.menu.item
|
|
125
|
+
│ │ └─ sidebar.workspaces.session.row.action
|
|
126
|
+
│ └─ sidebar.settings
|
|
127
|
+
│ ├─ settings.trigger
|
|
128
|
+
│ ├─ settings.header
|
|
129
|
+
│ ├─ settings.action
|
|
130
|
+
│ ├─ settings.close
|
|
131
|
+
│ ├─ settings.onboarding
|
|
132
|
+
│ └─ settings.section
|
|
133
|
+
│ ├─ settings.general.item
|
|
134
|
+
│ ├─ settings.models.provider-card
|
|
135
|
+
│ ├─ settings.models.footer
|
|
136
|
+
│ └─ settings.plugins.tab
|
|
137
|
+
├─ main
|
|
138
|
+
│ ├─ plugins.item
|
|
139
|
+
│ ├─ plugins.bundle.config
|
|
140
|
+
│ ├─ plugins.row.config
|
|
141
|
+
│ ├─ plugins.detail.actions
|
|
142
|
+
│ ├─ plugins.detail.badge
|
|
143
|
+
│ ├─ plugins.detail.section
|
|
144
|
+
│ └─ main.conversation
|
|
145
|
+
│ ├─ conversation.session
|
|
146
|
+
│ │ └─ conversation.view
|
|
147
|
+
│ │ ├─ conversation.chat.node
|
|
148
|
+
│ │ │ ├─ conversation.chat.assistant-actions
|
|
149
|
+
│ │ │ ├─ conversation.chat.commandview
|
|
150
|
+
│ │ │ ├─ conversation.chat.turnTail
|
|
151
|
+
│ │ │ └─ tool.call.toolview
|
|
152
|
+
│ │ │ ├─ tool.call.images
|
|
153
|
+
│ │ │ └─ tool.view.cordis
|
|
154
|
+
│ │ ├─ conversation.message.images
|
|
155
|
+
│ │ └─ conversation.trajectory.images
|
|
156
|
+
│ ├─ conversation.header
|
|
157
|
+
│ │ ├─ conversation.header.leading
|
|
158
|
+
│ │ └─ conversation.session.header
|
|
159
|
+
│ │ ├─ conversation.session.header.lineage
|
|
160
|
+
│ │ ├─ conversation.session.header.actions
|
|
161
|
+
│ │ ├─ conversation.session.header.utilities
|
|
162
|
+
│ │ └─ conversation.session.header.corner
|
|
163
|
+
│ ├─ conversation.composer
|
|
164
|
+
│ │ ├─ conversation.approval.detail
|
|
165
|
+
│ │ └─ conversation.plan-review.actions
|
|
166
|
+
│ ├─ conversation.composer.bar
|
|
167
|
+
│ │ ├─ conversation.input.attachments
|
|
168
|
+
│ │ ├─ conversation.input.permission
|
|
169
|
+
│ │ ├─ conversation.input.plan
|
|
170
|
+
│ │ └─ conversation.input.model
|
|
171
|
+
│ ├─ conversation.input.overlay
|
|
172
|
+
│ ├─ conversation.input.dock
|
|
173
|
+
│ ├─ conversation.composer.dock
|
|
174
|
+
│ ├─ conversation.input.left
|
|
175
|
+
│ ├─ conversation.input.right
|
|
176
|
+
│ ├─ conversation.hero.brand.mark
|
|
177
|
+
│ ├─ conversation.hero.workspace
|
|
178
|
+
│ │ └─ conversation.hero.workspace.directoryFlow
|
|
179
|
+
│ └─ conversation.hero.agentPreset
|
|
180
|
+
├─ rightbar
|
|
181
|
+
│ └─ rightbar.session
|
|
182
|
+
│ ├─ sidebar.right.pane.tab
|
|
183
|
+
│ │ ├─ sidebar.right.tab.guide
|
|
184
|
+
│ │ └─ sidebar.right.tab.guide.entry
|
|
185
|
+
│ ├─ sidebar.right.pane.tab.title
|
|
186
|
+
│ └─ sidebar.right.tab.menu.item
|
|
187
|
+
├─ shell.leading
|
|
188
|
+
└─ shell.overlay
|
|
189
|
+
└─ shell.quota-notice
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The generated Client inspect catalog is the exhaustive contract for each key: cardinality, scope, owner props, standard props, current occupants, declaration owner, and replacement risk. A running dynamic package can query the live tree and an exact key with `cordis_inspect what:"client"`; the source catalog is generated from `SlotMap` declarations and `slots.register()` call sites by `pnpm run gen-client-catalog`.
|
|
193
|
+
|
|
194
|
+
## Extension rules
|
|
195
|
+
|
|
196
|
+
- Import another feature package only for declarations with `import type`; never import or re-export its runtime values.
|
|
197
|
+
- Declare a new child slot only in the component that owns and renders that location. Other packages wait with `ctx.slots.inject()` and contribute through `ctx.slots.register()`.
|
|
198
|
+
- Keep business and transport state in their owning Cordis services or Client models. Slot stores hold shared viewing and interaction state only.
|
|
199
|
+
- Keep observable source and snapshot identities stable between changes. Republish through the same source whenever its value changes.
|
|
200
|
+
- Pass JSON-compatible data and callbacks between UI domains. The `hooks` compartment is the sole exception for bare observables; React content travels through slots.
|
|
201
|
+
- Treat `single` and an occupied keyed cell as replacement points. Use list ids or an unoccupied key for additive extensions.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/spill.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Spill Storage
|
|
4
|
+
|
|
5
|
+
English | [中文](spill.zh.md)
|
|
6
|
+
|
|
7
|
+
The spill storage [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) persists caller-provided text and returns a model-facing locator with retrieval guidance. Its Service Definition is [dsh-spill](../../packages/spill/spill) (`ctx.spillStore`), and its local Service Provider is [dsh-spill-local](../../packages/spill/spill-local). Consumers include the [tool-result policy](../../packages/spill/spill-policy) and [session references](../../packages/context/session-reference/README.md). Spill is optional, not part of the [agent-loop spine](core.md); consumers own preview and spill decisions, while storage saves the supplied text verbatim.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
|
|
10
|
+
|
|
11
|
+
## The save request
|
|
12
|
+
|
|
13
|
+
`saveText` is the sole service operation: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), descriptive producer details (`source`, never access control), and a `suggestedName` the backend may use as a naming hint, not a path. A tool source identifies the actual tool call; a session-reference source identifies the captured source session, while its owner is the target session receiving the context.
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/** One request to persist text to a spill artifact. */
|
|
17
|
+
interface SaveTextSpill {
|
|
18
|
+
owner: SpillOwner
|
|
19
|
+
source: SpillSource
|
|
20
|
+
/**
|
|
21
|
+
* A caller-suggested base name (e.g. `web_fetch.txt`). The backend sanitizes
|
|
22
|
+
* it to a single safe path segment before use - it is a hint, never a path.
|
|
23
|
+
*/
|
|
24
|
+
suggestedName: string
|
|
25
|
+
/** The full text to persist (UTF-8). */
|
|
26
|
+
content: string
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```ts type-equiv
|
|
31
|
+
/**
|
|
32
|
+
* Save-time storage namespace for a spilled artifact. The session id lets a
|
|
33
|
+
* backend group storage under the producing session, but the returned
|
|
34
|
+
* {@link SpillLocator} is the model-facing handle. Forked sessions inherit
|
|
35
|
+
* locators already present in the seeded log; those artifacts are not copied or
|
|
36
|
+
* re-owned, and spills produced after the fork use the child session id.
|
|
37
|
+
*/
|
|
38
|
+
interface SpillOwner {
|
|
39
|
+
sessionId: SessionId
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
A retention-period cleanup may expire old locators with other old session artifacts; the spill seam does not define a per-session cleanup policy.
|
|
44
|
+
|
|
45
|
+
```ts type-equiv
|
|
46
|
+
/**
|
|
47
|
+
* Producer of a spilled artifact. Tool results carry their model-issued call id;
|
|
48
|
+
* session references identify the captured source session instead. Descriptive
|
|
49
|
+
* source description only, never access control.
|
|
50
|
+
*/
|
|
51
|
+
type SpillSource = {
|
|
52
|
+
kind: 'tool'
|
|
53
|
+
/** The tool whose result was spilled (e.g. `web_fetch`). */
|
|
54
|
+
toolName: string
|
|
55
|
+
/** The model-issued call id the result belongs to. */
|
|
56
|
+
callId: ToolCallId
|
|
57
|
+
/** A short human label for the artifact (e.g. `result`). */
|
|
58
|
+
label: string
|
|
59
|
+
} | {
|
|
60
|
+
kind: 'session-reference'
|
|
61
|
+
/** Session whose projected conversation was captured. */
|
|
62
|
+
sessionId: SessionId
|
|
63
|
+
/** Host-provided label for the referenced session. */
|
|
64
|
+
label: string
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## The result
|
|
69
|
+
|
|
70
|
+
```ts type-equiv
|
|
71
|
+
/** A saved spill artifact: its locator, byte length, and backend-specific retrieval guidance. */
|
|
72
|
+
interface SpillRef {
|
|
73
|
+
locator: SpillLocator
|
|
74
|
+
bytes: number
|
|
75
|
+
retrievalHint: string
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`SpillLocator` is a [branded](core.md#branded-ids) model-facing handle returned by the backend. The local backend renders it as a filesystem path; a remote or database backend can render a URI, key, or command token. Consumers treat it as opaque and render it with `retrievalHint` instead of assuming `read` is always the right retrieval mechanism.
|
|
80
|
+
|
|
81
|
+
```ts type-equiv
|
|
82
|
+
/**
|
|
83
|
+
* Opaque model-facing handle for one spilled artifact. A local backend may use a
|
|
84
|
+
* filesystem path; a remote or database backend may use a URI or key. Consumers
|
|
85
|
+
* render it with {@link SpillRef.retrievalHint}, but do not parse it.
|
|
86
|
+
*/
|
|
87
|
+
type SpillLocator = Branded<'SpillLocator'>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## The service
|
|
91
|
+
|
|
92
|
+
`SpillStore` (`ctx.spillStore`, defined in [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)) is a one-method abstract service: `saveText(input) → Promise<SpillRef>`. It persists the FULL `content` and REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable). The seam owns storage only: no retention policy, no tool-result replacement, no retrieval/search API.
|
|
93
|
+
|
|
94
|
+
The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes under `<root>/session-<hash>/<random>-<safeName>` - a configured or lazily-created private (0700) root, a `sha256(sessionId)` session subdir, and an exclusive owner-only (`open(path, 'wx', 0o600)`) write so a planted symlink cannot redirect it. Its `locator` is the local path and its `retrievalHint` tells the model to use `read` or `grep` on that path. The policy consumer ([dsh-spill-policy](../../packages/spill/spill-policy)) replaces an over-`maxInlineTokens` text/image result with ordered head/tail content and a spill address, best-effort: a save failure keeps the original inline result rather than turning a successful call into an `isError`.
|
|
95
|
+
|
|
96
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
97
|
+
|
|
98
|
+
<a id="cordis-surface"></a>
|
|
99
|
+
|
|
100
|
+
## Cordis API
|
|
101
|
+
|
|
102
|
+
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).
|
|
103
|
+
|
|
104
|
+
<a id="ctxspillstore--spillstore-abstract-seam"></a>
|
|
105
|
+
|
|
106
|
+
### `ctx.spillStore` - `SpillStore` (abstract seam)
|
|
107
|
+
|
|
108
|
+
Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin - it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
|
|
109
|
+
|
|
110
|
+
Semantics every implementation must honor:
|
|
111
|
+
|
|
112
|
+
- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
|
|
113
|
+
- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from - never equal to - the caller's `suggestedName`.
|
|
114
|
+
- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
|
|
115
|
+
|
|
116
|
+
```ts cordis-catalog
|
|
117
|
+
/**
|
|
118
|
+
* Persist `input.content` to a session-scoped spill artifact.
|
|
119
|
+
* @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
|
|
120
|
+
* @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
|
|
121
|
+
*/
|
|
122
|
+
abstract saveText(input: SaveTextSpill): Promise<SpillRef>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Source: [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)
|
|
126
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/ssh.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# SSH
|
|
4
|
+
|
|
5
|
+
English | [中文](ssh.zh.md)
|
|
6
|
+
|
|
7
|
+
The [SSH provider family](../../packages/ssh/README.md) supplies one remote filesystem/process world through a deployment-owned OpenSSH connection. The Harness, model transport and Session storage remain on the host. The family implements the existing filesystem, subprocess and sandbox APIs; it introduces no SSH-specific model tools.
|
|
8
|
+
|
|
9
|
+
## Execution coordinates
|
|
10
|
+
|
|
11
|
+
Filesystem identities, executable lookup, process cwd, sandbox workspace roots and language-server file URLs refer to the SSH host. Providers canonicalize paths where the files exist, preserving filesystem interpretation of `symlink/..`. The policy resolver carries absolute execution-world spelling without trying to resolve remote paths on the Harness host.
|
|
12
|
+
|
|
13
|
+
`processPath()` supplies a path usable by the paired subprocess provider. `processPathFromHostPath()` remains unavailable for SSH; installing a remote artifact does not make an arbitrary host path portable. [`NodePtcRuntime`](../../packages/ptc-runtime/ptc-runtime-node/README.md) therefore takes an explicitly installed, digest-verified remote bootstrap.
|
|
14
|
+
|
|
15
|
+
## Transport and trust
|
|
16
|
+
|
|
17
|
+
Administrative RPC uses the helper’s SSH exec streams. Ordinary stdin, stdout, stderr, terminal output and optional fd 7 control traffic use separately authenticated forwarded Unix sockets. Each forwarded stream has its own SSH channel window; paused program output does not share the control or administrative window. All channels still share connection bandwidth and transport failure.
|
|
18
|
+
|
|
19
|
+
Deployment authentication, installed artifact verification and per-stream TLS authentication belong to [`dsh-ssh`](../../packages/ssh/ssh/README.md). The helper executes filesystem and process requests with trusted local providers on the remote machine. SSH is a transport; the selected remote sandbox provider enforces file effects.
|
|
20
|
+
|
|
21
|
+
## Process lifetime and cancellation
|
|
22
|
+
|
|
23
|
+
A process is reserved before its streams are connected, and launch is accepted at most once. `done` reports the direct result; `waitForExit` observes the remote managed range. Terminal operations retain the asynchronous shared API. Preparation cancellation, launched-process termination and provider disposal release their owned resources through the helper.
|
|
24
|
+
|
|
25
|
+
Administrative deadlines bound individual RPC observations; they do not replace the execution deadline chosen by a Bash or ptc-runtime consumer. Remote waits can remain pending while other requests progress. SSH loss invalidates pending operations; helper EOF, signals and lease expiry start remote cleanup. The client reports unconfirmed outcomes honestly and never reconnects to replay a possibly executed action.
|
|
26
|
+
|
|
27
|
+
## Composition scope
|
|
28
|
+
|
|
29
|
+
Headless records and checks Session cwd through the mounted filesystem provider. Remote FS, Bash, terminal, LSP and PTC consumers can therefore share those coordinates. Web workspace views that assume host filesystem access need separate integration; replacing providers alone does not make those views remote-aware.
|
|
30
|
+
|
|
31
|
+
See the [decision record](../../.agents/notes/implemented/architecture/2026-09-11-posix-ssh-runtime.md) for the alternatives and verification obligations.
|
|
32
|
+
|
|
33
|
+
## Connection API
|
|
34
|
+
|
|
35
|
+
```ts type-equiv
|
|
36
|
+
/** Deployment-owned SSH identity and installed helper; no model argument selects these values. */
|
|
37
|
+
interface Config {
|
|
38
|
+
/** OpenSSH host alias, including its existing user, key and known-host configuration. */
|
|
39
|
+
host: string
|
|
40
|
+
/** Absolute remote Node executable. */
|
|
41
|
+
node: string
|
|
42
|
+
/** Absolute path to the installed, bundled helper entry. */
|
|
43
|
+
helper: string
|
|
44
|
+
/** SHA-256 of that bundled helper; mismatches refuse the connection. */
|
|
45
|
+
helperHash: string
|
|
46
|
+
/** Absolute remote default workspace. */
|
|
47
|
+
workspace: string
|
|
48
|
+
/** Optional preinstalled built PTC entry, paired with its expected digest. */
|
|
49
|
+
bootstrapPath?: string
|
|
50
|
+
/** SHA-256 of bootstrapPath; both fields must be supplied together. */
|
|
51
|
+
bootstrapHash?: string
|
|
52
|
+
/** Connection and administrative-request deadline, at most 2,147,483,647 milliseconds. */
|
|
53
|
+
requestTimeoutMs?: number
|
|
54
|
+
/** Maximum JSON payload bytes per helper request or response. */
|
|
55
|
+
maxFrameBytes?: number
|
|
56
|
+
/** Maximum ordinary requests; heartbeat and bounded resource cleanup have reserved capacity. */
|
|
57
|
+
maxPending?: number
|
|
58
|
+
/** Remote helper lease; loss of heartbeats starts remote managed cleanup. */
|
|
59
|
+
leaseMs?: number
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
```ts public-api
|
|
64
|
+
/** One non-reconnecting SSH session; loss invalidates all active operations. */
|
|
65
|
+
declare class SshConnection extends Service {
|
|
66
|
+
static Config: schema<Config>;
|
|
67
|
+
/** Verified remote helper coordinates; callers must await this before launch. */
|
|
68
|
+
readonly ready: Promise<Hello>;
|
|
69
|
+
constructor(ctx: Context, config: Config);
|
|
70
|
+
/** Hold plugin readiness until the remote identity and helper digest are verified. */
|
|
71
|
+
async [Service.init](): Promise<void>;
|
|
72
|
+
/** Verified remote Node executable for the paired PTC runtime. */
|
|
73
|
+
get nodeExecutable(): string;
|
|
74
|
+
/** Verified preinstalled PTC entry; unconfigured runtimes fail before program execution. */
|
|
75
|
+
get bootstrapPath(): string;
|
|
76
|
+
/**
|
|
77
|
+
* Send a helper operation; cancellation never replays an ambiguous mutation.
|
|
78
|
+
* @param method - the private helper operation.
|
|
79
|
+
* @param params - JSON request fields validated by the helper.
|
|
80
|
+
* @param result - response validation before returning provider-visible data.
|
|
81
|
+
* @param signal - cancellation, which does not undo completed remote effects.
|
|
82
|
+
* @param wait - allow a process observation to outlast the administrative deadline.
|
|
83
|
+
* @returns the validated remote result.
|
|
84
|
+
*/
|
|
85
|
+
async request<T>(method: string, params: unknown, result: z.ZodType<T>, signal?: AbortSignal, wait: boolean = false): Promise<T>;
|
|
86
|
+
/**
|
|
87
|
+
* Forward one authenticated stream through an independent SSH channel.
|
|
88
|
+
* @param endpoint - private coordinates issued by this connection's helper.
|
|
89
|
+
* @param signal - cancellation of allocation and the resulting socket.
|
|
90
|
+
* @returns a paused socket; attach a consumer before resuming it.
|
|
91
|
+
*/
|
|
92
|
+
async connectStream(endpoint: SshStreamEndpoint, signal?: AbortSignal): Promise<Socket>;
|
|
93
|
+
/** Tear down the helper's remote managed ranges before releasing the SSH master when reachable. */
|
|
94
|
+
dispose(): Promise<void>;
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
99
|
+
|
|
100
|
+
<a id="cordis-surface"></a>
|
|
101
|
+
|
|
102
|
+
## Cordis API
|
|
103
|
+
|
|
104
|
+
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).
|
|
105
|
+
|
|
106
|
+
<a id="ctxssh--sshconnection"></a>
|
|
107
|
+
|
|
108
|
+
### `ctx.ssh` - `SshConnection`
|
|
109
|
+
|
|
110
|
+
One non-reconnecting SSH session; loss invalidates all active operations.
|
|
111
|
+
|
|
112
|
+
```ts cordis-catalog
|
|
113
|
+
/**
|
|
114
|
+
* Send a helper operation; cancellation never replays an ambiguous mutation.
|
|
115
|
+
* @param method - the private helper operation.
|
|
116
|
+
* @param params - JSON request fields validated by the helper.
|
|
117
|
+
* @param result - response validation before returning provider-visible data.
|
|
118
|
+
* @param signal - cancellation, which does not undo completed remote effects.
|
|
119
|
+
* @param wait - allow a process observation to outlast the administrative deadline.
|
|
120
|
+
* @returns the validated remote result.
|
|
121
|
+
*/
|
|
122
|
+
async request<T>(method: string, params: unknown, result: z.ZodType<T>, signal?: AbortSignal, wait: boolean = false): Promise<T>
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Forward one authenticated stream through an independent SSH channel.
|
|
126
|
+
* @param endpoint - private coordinates issued by this connection's helper.
|
|
127
|
+
* @param signal - cancellation of allocation and the resulting socket.
|
|
128
|
+
* @returns a paused socket; attach a consumer before resuming it.
|
|
129
|
+
*/
|
|
130
|
+
async connectStream(endpoint: SshStreamEndpoint, signal?: AbortSignal): Promise<Socket>
|
|
131
|
+
|
|
132
|
+
/** Tear down the helper's remote managed ranges before releasing the SSH master when reachable. */
|
|
133
|
+
dispose(): Promise<void>
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Source: [`packages/ssh/ssh/src/index.ts`](../../packages/ssh/ssh/src/index.ts)
|
|
137
|
+
<!-- END GENERATED cordis-surface -->
|