@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,154 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/cordis-api/registry.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
<!-- Generated by scripts/gen-cordis-catalog.ts - do not edit by hand.
|
|
4
|
+
Run `pnpm run gen-cordis-catalog` to regenerate. -->
|
|
5
|
+
|
|
6
|
+
# Registry
|
|
7
|
+
|
|
8
|
+
Plugin loading and dependency injection.
|
|
9
|
+
|
|
10
|
+
### ctx.inject(deps, callback)
|
|
11
|
+
|
|
12
|
+
```ts cordis-catalog
|
|
13
|
+
/**
|
|
14
|
+
* Run a callback once the requested services are available.
|
|
15
|
+
*
|
|
16
|
+
* Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
|
|
17
|
+
* is unloaded and re-run whenever a required service changes.
|
|
18
|
+
*
|
|
19
|
+
* @param deps - required services, as an array or a name → config map.
|
|
20
|
+
* @param callback - plugin body called with `(ctx, config)`.
|
|
21
|
+
* @returns the fiber; awaiting it settles once loading finished.
|
|
22
|
+
*/
|
|
23
|
+
inject(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Run a callback once the requested services are available.
|
|
27
|
+
|
|
28
|
+
Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback is unloaded and re-run whenever a required service changes.
|
|
29
|
+
|
|
30
|
+
- `deps` - required services, as an array or a name → config map.
|
|
31
|
+
- `callback` - plugin body called with `(ctx, config)`.
|
|
32
|
+
|
|
33
|
+
**Returns** the fiber; awaiting it settles once loading finished.
|
|
34
|
+
|
|
35
|
+
[Source](../../vendor/cordis/src/registry.ts#L176)
|
|
36
|
+
|
|
37
|
+
### ctx.plugin(plugin, ...args)
|
|
38
|
+
|
|
39
|
+
```ts cordis-catalog
|
|
40
|
+
/**
|
|
41
|
+
* Load a plugin in the current context.
|
|
42
|
+
*
|
|
43
|
+
* @param plugin - a function, class, or `{ apply }` object plugin.
|
|
44
|
+
* @param args - the plugin config, validated against its `Config` schema.
|
|
45
|
+
* @returns the fiber; awaiting it settles once loading finished
|
|
46
|
+
* (rejecting on config or startup errors).
|
|
47
|
+
*/
|
|
48
|
+
plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Load a plugin in the current context.
|
|
52
|
+
|
|
53
|
+
- `plugin` - a function, class, or `{ apply }` object plugin.
|
|
54
|
+
- `args` - the plugin config, validated against its `Config` schema.
|
|
55
|
+
|
|
56
|
+
**Returns** the fiber; awaiting it settles once loading finished (rejecting on config or startup errors).
|
|
57
|
+
|
|
58
|
+
[Source](../../vendor/cordis/src/registry.ts#L185)
|
|
59
|
+
|
|
60
|
+
## Plugin
|
|
61
|
+
|
|
62
|
+
Supported plugin entrypoint shapes.
|
|
63
|
+
|
|
64
|
+
```ts cordis-catalog
|
|
65
|
+
/** Supported plugin entrypoint shapes. */
|
|
66
|
+
type Plugin<T = any> =
|
|
67
|
+
| Plugin.Function<T>
|
|
68
|
+
| Plugin.Constructor<T>
|
|
69
|
+
| Plugin.Object<T>
|
|
70
|
+
|
|
71
|
+
/** Types associated with plugin entrypoints and runtime records. */
|
|
72
|
+
namespace Plugin {
|
|
73
|
+
/** Shared metadata understood by the plugin registry and related tooling. */
|
|
74
|
+
export interface Base<T = any> {
|
|
75
|
+
/** Display name used for fiber diagnostics and logger names. */
|
|
76
|
+
name?: string
|
|
77
|
+
/** Standard-schema validator applied to config before the plugin starts. */
|
|
78
|
+
Config?: StandardSchemaV1<any, T>
|
|
79
|
+
/** Services the plugin requires; it only loads while all are available. */
|
|
80
|
+
inject?: Inject
|
|
81
|
+
/** Service name(s) the plugin provides (read by `Service` and by loaders). */
|
|
82
|
+
provide?: string | string[]
|
|
83
|
+
/** Service names whose intercept config the plugin declares it consumes. */
|
|
84
|
+
intercept?: Dict<boolean>
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export interface Transform<S, T> {
|
|
88
|
+
/** Marks the transform object as a schema/config transform. */
|
|
89
|
+
schema?: true
|
|
90
|
+
/** Convert user-facing config to runtime config. */
|
|
91
|
+
Config: (config: S) => T
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Function plugin called with `(ctx, config)`. */
|
|
95
|
+
export interface Function<T = any> extends Base<T> {
|
|
96
|
+
(ctx: Context, config: T): any
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Class plugin constructed with `(ctx, config)`. */
|
|
100
|
+
export interface Constructor<T = any> extends Base<T> {
|
|
101
|
+
new (ctx: Context, config: T): any
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Object plugin with an `apply(ctx, config)` method. */
|
|
105
|
+
export interface Object<T = any> extends Base<T> {
|
|
106
|
+
apply(ctx: Context, config: T): any
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Mutable registry record shared by all fibers of one plugin callback. */
|
|
110
|
+
export interface Runtime {
|
|
111
|
+
/** Display name copied from the first registered plugin shape. */
|
|
112
|
+
name?: string
|
|
113
|
+
/** Every live fiber of this plugin (one per `ctx.plugin()` call). */
|
|
114
|
+
fibers: DisposableList<Fiber>
|
|
115
|
+
/** The executable entrypoint all fibers share (registry identity key). */
|
|
116
|
+
callback: globalThis.Function
|
|
117
|
+
/** Standard-schema validator applied to each fiber's config. */
|
|
118
|
+
Config?: StandardSchemaV1
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
[Source](../../vendor/cordis/src/registry.ts#L92)
|
|
124
|
+
|
|
125
|
+
## Inject
|
|
126
|
+
|
|
127
|
+
Service dependency declaration accepted by plugins and the `@Inject` decorator.
|
|
128
|
+
|
|
129
|
+
Array form requests services without intercept config. Object form maps each service name to optional intercept config for the plugin context.
|
|
130
|
+
|
|
131
|
+
```ts cordis-catalog
|
|
132
|
+
/**
|
|
133
|
+
* Service dependency declaration accepted by plugins and the `@Inject`
|
|
134
|
+
* decorator.
|
|
135
|
+
*
|
|
136
|
+
* Array form requests services without intercept config. Object form maps each
|
|
137
|
+
* service name to optional intercept config for the plugin context.
|
|
138
|
+
*/
|
|
139
|
+
type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K] }
|
|
140
|
+
|
|
141
|
+
/** Utilities for normalizing plugin dependency declarations. */
|
|
142
|
+
namespace Inject {
|
|
143
|
+
/**
|
|
144
|
+
* Convert array/object/class-inherited inject metadata into a plain map.
|
|
145
|
+
*
|
|
146
|
+
* @param inject - the declaration to normalize; `null`/`undefined` add nothing.
|
|
147
|
+
* @param result - the map to fill (service name → intercept config or `null`).
|
|
148
|
+
* @returns `result`.
|
|
149
|
+
*/
|
|
150
|
+
export function resolve(inject: Inject | null | undefined, result: Dict = Object.create(null))
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
[Source](../../vendor/cordis/src/registry.ts#L19)
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/cordis-api/service.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
<!-- Generated by scripts/gen-cordis-catalog.ts - do not edit by hand.
|
|
4
|
+
Run `pnpm run gen-cordis-catalog` to regenerate. -->
|
|
5
|
+
|
|
6
|
+
# Service
|
|
7
|
+
|
|
8
|
+
The base class for context services. A subclass loaded as a plugin registers itself as `ctx.<name>`.
|
|
9
|
+
|
|
10
|
+
Base class for services that expose a named API on `ctx`.
|
|
11
|
+
|
|
12
|
+
Subclasses call `super(ctx, name)` from their constructor. The service is registered immediately and is automatically removed with the owning fiber.
|
|
13
|
+
|
|
14
|
+
[Source](../../vendor/cordis/src/service.ts#L11)
|
|
15
|
+
|
|
16
|
+
### service.name
|
|
17
|
+
|
|
18
|
+
```ts cordis-catalog
|
|
19
|
+
/** The service name this instance is registered under. */
|
|
20
|
+
public name!: string
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The service name this instance is registered under.
|
|
24
|
+
|
|
25
|
+
[Source](../../vendor/cordis/src/service.ts#L30)
|
|
26
|
+
|
|
27
|
+
## Static members
|
|
28
|
+
|
|
29
|
+
### Service.init
|
|
30
|
+
|
|
31
|
+
```ts cordis-catalog
|
|
32
|
+
/** Symbol key of an instance method run after construction (class plugins). */
|
|
33
|
+
static readonly init: unique symbol
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Symbol key of an instance method run after construction (class plugins).
|
|
37
|
+
|
|
38
|
+
[Source](../../vendor/cordis/src/service.ts#L13)
|
|
39
|
+
|
|
40
|
+
### Service.check
|
|
41
|
+
|
|
42
|
+
```ts cordis-catalog
|
|
43
|
+
/** Symbol key of the availability predicate passed to `ctx.provide()`. */
|
|
44
|
+
static readonly check: unique symbol
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Symbol key of the availability predicate passed to `ctx.provide()`.
|
|
48
|
+
|
|
49
|
+
[Source](../../vendor/cordis/src/service.ts#L15)
|
|
50
|
+
|
|
51
|
+
### Service.config
|
|
52
|
+
|
|
53
|
+
```ts cordis-catalog
|
|
54
|
+
/** Symbol key of the phantom intercept-config type parameter. */
|
|
55
|
+
static readonly config: unique symbol
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Symbol key of the phantom intercept-config type parameter.
|
|
59
|
+
|
|
60
|
+
[Source](../../vendor/cordis/src/service.ts#L17)
|
|
61
|
+
|
|
62
|
+
### Service.invoke
|
|
63
|
+
|
|
64
|
+
```ts cordis-catalog
|
|
65
|
+
/** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
|
|
66
|
+
static readonly invoke: unique symbol
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Symbol key of the call body making a service callable (e.g. `ctx.logger()`).
|
|
70
|
+
|
|
71
|
+
[Source](../../vendor/cordis/src/service.ts#L19)
|
|
72
|
+
|
|
73
|
+
### Service.extend
|
|
74
|
+
|
|
75
|
+
```ts cordis-catalog
|
|
76
|
+
/** Symbol key of the helper deriving an extended service instance. */
|
|
77
|
+
static readonly extend: unique symbol
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Symbol key of the helper deriving an extended service instance.
|
|
81
|
+
|
|
82
|
+
[Source](../../vendor/cordis/src/service.ts#L21)
|
|
83
|
+
|
|
84
|
+
### Service.tracker
|
|
85
|
+
|
|
86
|
+
```ts cordis-catalog
|
|
87
|
+
/** Symbol key of the tracker metadata used for context tracing. */
|
|
88
|
+
static readonly tracker: unique symbol
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Symbol key of the tracker metadata used for context tracing.
|
|
92
|
+
|
|
93
|
+
[Source](../../vendor/cordis/src/service.ts#L23)
|
|
94
|
+
|
|
95
|
+
### Service.resolveConfig
|
|
96
|
+
|
|
97
|
+
```ts cordis-catalog
|
|
98
|
+
/** Symbol key of the intercept-config resolution helper below. */
|
|
99
|
+
static readonly resolveConfig: unique symbol
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Symbol key of the intercept-config resolution helper below.
|
|
103
|
+
|
|
104
|
+
[Source](../../vendor/cordis/src/service.ts#L25)
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
<!-- Synced from acryl:docs/cordis/cordis-usage-cheatsheet.md @ 79fc28c108. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Cordis usage cheatsheet (source-validated)
|
|
4
|
+
|
|
5
|
+
> **Purpose:** one condensed, operationally-accurate page for building on Cordis / DeepSeek
|
|
6
|
+
> Harness in this repo. Distils `docs/cordis/` + `docs/cordisplugins/` and **validates them
|
|
7
|
+
> against the vendored source**, so implementers don't trip on doc-vs-source drift.
|
|
8
|
+
>
|
|
9
|
+
> **Authority:** the pinned `deepseek-harness/` submodule. The vendored framework is
|
|
10
|
+
> `@deepseek-ai/cordis` **4.0.1** (a re-scoped ESM-first fork of upstream `cordis`), flat at
|
|
11
|
+
> `deepseek-harness/vendor/cordis/src`. The **generated** reference API docs live at
|
|
12
|
+
> `deepseek-harness/docs/cordis-api/*` (context/events/fiber/registry/service/inherited) -
|
|
13
|
+
> note `vendor/cordis/README.md` links to `docs/api/core.md` etc. which are **stale and do not
|
|
14
|
+
> exist**; use `docs/cordis-api/*`.
|
|
15
|
+
>
|
|
16
|
+
> The repo rule (AGENTS.md) requires reading `docs/cordis/cordis_system_guide_for_coding_agents.md`
|
|
17
|
+
> (the long handbook) before changing a plugin/service/tool. Treat this cheatsheet as the fast
|
|
18
|
+
> entry point; the handbook and `docs/cordis-api/*` are the full contract.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 1. The kernel model
|
|
23
|
+
|
|
24
|
+
Cordis is a **meta-framework**: it knows nothing about LLMs, agents, tools, sessions, or shell.
|
|
25
|
+
DeepSeek Harness supplies those as domain services. The product is a **plugin tree** - every
|
|
26
|
+
capability above a tiny trusted substrate is a replaceable plugin.
|
|
27
|
+
|
|
28
|
+
| Piece | What it is | Key facts |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| **`Context`** | Scoped capability environment: DI container + service locator + event bus + effect owner + lifecycle scope. Proxy-backed. | `extend`/`isolate`/`intercept` are **class methods**; most `ctx.*` members are **mixed-in accessors** installed at root boot via `ReflectService.mixin`. Don't create random root `Context`s (each root is a second dependency universe). |
|
|
31
|
+
| **Service** | A named capability on `ctx` (`ctx.tools`, `ctx.llm`, `ctx.shell`). | `class X extends Service { constructor(ctx){ super(ctx,'name') } }` **provides at runtime**; `declare module 'cordis' { interface Context { name } }` is **compile-time only**. |
|
|
32
|
+
| **`inject`** | Live dependency contract. | `export const inject = ['tools']` is a **hard requirement** - the fiber stays `PENDING` until every named service exists. Not a load-order hint. Provider identity change reactivates consumers. |
|
|
33
|
+
| **Events** | Typed event bus. | 5 dispatch modes: `emit` (sync, no await), `parallel` (`Promise.allSettled`), `serial` (in order until bail), `bail` (first bail value), `waterfall` (compose; veto = **don't call `next()`**). |
|
|
34
|
+
| **Fiber** | One mounted plugin instance; the lifecycle unit. | States `PENDING → LOADING → ACTIVE → FAILED → UNLOADING → DISPOSED`. `PENDING` is valid (missing hard dep), not an error. `ACTIVE` = `apply` called. |
|
|
35
|
+
| **Effects** | Reversible ownership. | Registration = effect = ownership. Every resource is acquired inside **one owning `ctx.effect()`** and released by its disposer (LIFO, single-shot). A leak is an architecture bug. |
|
|
36
|
+
| **Loader** | `cordis.yml`/bundle/patch rows → live plugin tree. | Applies normalized `EntryOptions[]` to an `Entry` tree (`EntryGroup.update`/`Entry.create`); it does **not** parse YAML (the `include` plugin does). HMR is a plugin, requires `--expose-internals`, and is transactional. |
|
|
37
|
+
|
|
38
|
+
## 2. The plugin contract
|
|
39
|
+
|
|
40
|
+
A plugin module exports, in order of common use:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
export const name = 'my-plugin' // stable id; MUST match the Loader row
|
|
44
|
+
export const inject = ['tools'] // hard deps (the fiber PENDINGs on them)
|
|
45
|
+
export const Config = /* sync StandardSchemaV1 */ // optional, validated before apply
|
|
46
|
+
export function apply(ctx, config?) { /* register capabilities, all effect-owned */ }
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
- **Shapes:** function plugin (default, lifecycle only) → object plugin (structured) → `Service` class (only when the plugin **provides** a named service). Prefer function until you need to provide a service.
|
|
50
|
+
- **Config:** a **StandardSchemaV1, synchronous** schema (see §4 correction 1). Cordis validates the row config and fills defaults before `apply` - do NOT export a plain object.
|
|
51
|
+
- **Registration chain:**
|
|
52
|
+
```
|
|
53
|
+
profile → dsh.profile.bundles → bundle.dsh.bundle.patch → cordis.patch.yml
|
|
54
|
+
→ Loader row (name = package name or absolute module path)
|
|
55
|
+
→ import module → Cordis calls apply(ctx)
|
|
56
|
+
```
|
|
57
|
+
Desktop uses the **same** Loader/bundle contracts but inserts its own layer per generation.
|
|
58
|
+
- **Disposal rule:** every resource inside one owning `ctx.effect()`; stable Loader `id`s; config is **replaced**, not deep-merged; a provider change unloads + reactivates consumers driven by service availability, never YAML row order.
|
|
59
|
+
|
|
60
|
+
## 3. Harness Tool contract (source: `AGENTS.md`, not `docs/cordisplugins/`)
|
|
61
|
+
|
|
62
|
+
A **Harness Tool** is a cordis consumer of `ctx.tools`, not a Cordis primitive:
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
export const inject = ['tools']
|
|
66
|
+
export function apply(ctx, config) {
|
|
67
|
+
ctx.tools.register(defineTool({
|
|
68
|
+
name, description,
|
|
69
|
+
parameters: { /* ValueSchemaSpec */ },
|
|
70
|
+
output: { schema: /* ValueSchemaSpec */, render(args, value) { return [{ type: 'text', text }] } },
|
|
71
|
+
async execute(args, exec) { /* observe exec.signal; return the canonical value */ },
|
|
72
|
+
}))
|
|
73
|
+
// registration is effect-owned → disposed with the Fiber
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Contract requirements: canonical typed output split into `output.schema` (machine, lossless JSON)
|
|
78
|
+
and `output.render` (model-facing `ContentBlock[]`); honour `exec.signal`; traverse the tool
|
|
79
|
+
policy/event pipeline; no `output` declaration → `register` throws a `TypeError`. Effect-owned so
|
|
80
|
+
it disappears when its Fiber unloads.
|
|
81
|
+
|
|
82
|
+
## 4. Source corrections (doc-vs-source drift - rely on the source)
|
|
83
|
+
|
|
84
|
+
These materially affect an implementation; validate against the vendored source, not the
|
|
85
|
+
handbook wording.
|
|
86
|
+
|
|
87
|
+
1. **`Config` uses sync StandardSchema, not schemastery.** Core `resolveConfig` calls
|
|
88
|
+
`Config['~standard'].validate(config)` and **throws `TypeError('Async config validation is
|
|
89
|
+
not supported')`** for promise-yielding schemas (`vendor/cordis/src/fiber.ts:53-55`).
|
|
90
|
+
Schemastery `z.object` is used only for loader/timer/hmr *option* schemas, not plugin `Config`.
|
|
91
|
+
2. **`ctx.timer`, `ctx.hmr`, `ctx.loader` are NOT on core.** They exist only when their plugin is
|
|
92
|
+
loaded. Never assume them without an `inject` dependency. `ctx.hmr` throws unless the process
|
|
93
|
+
was launched with `--expose-internals`.
|
|
94
|
+
3. **`ctx.root` is `@experimental`**; **`ctx.baseUrl` is optional and loader-set** (core leaves it
|
|
95
|
+
`undefined`). Don't rely on them in a plugin.
|
|
96
|
+
4. **`parallel` mislabels its dispatch mode as `'emit'`** in the `internal/dispatch` diagnostic
|
|
97
|
+
(`events.ts` calls `dispatch('emit', …)` internally) - a real nuance if a plugin branches on mode.
|
|
98
|
+
5. **`FiberState` enum order is `PENDING, LOADING, ACTIVE, FAILED, DISPOSED, UNLOADING`**
|
|
99
|
+
(`DISPOSED=4`, `UNLOADING=5`) - differs from the JSDoc narrative order.
|
|
100
|
+
6. **Real generated API docs are `deepseek-harness/docs/cordis-api/*`.** The
|
|
101
|
+
`vendor/cordis/README.md` links (`docs/api/core.md`, `docs/guides/loader-config.md`, …) are
|
|
102
|
+
stale and do not exist.
|
|
103
|
+
7. **Vendored `@deepseek-ai/cordis` is 4.0.1** (ESM-first fork). The vendor manifest table's
|
|
104
|
+
`4.0.0-rc.7` is the *upstream* reference; the actual package/json in-tree is 4.0.1.
|
|
105
|
+
|
|
106
|
+
## 5. Six-part mini-design (required before any new service seam)
|
|
107
|
+
|
|
108
|
+
Per `AGENTS.md`, write these before creating a service/tool/provider/event seam:
|
|
109
|
+
|
|
110
|
+
1. **Capability and plugin boundary** - what domain owns it and why it needs independent
|
|
111
|
+
lifecycle/config/replacement.
|
|
112
|
+
2. **Provides and consumes** - services/tools/events/durable facts; hard `inject` requirements and
|
|
113
|
+
intentional optional `ctx.get()` deps.
|
|
114
|
+
3. **Effects and disposal** - every activation-owned resource, its disposer, cleanup order,
|
|
115
|
+
cancellation, quiescence.
|
|
116
|
+
4. **Configuration and composition** - validated runtime schema, stable Loader row ids,
|
|
117
|
+
scopes/isolation, provider-replacement behavior.
|
|
118
|
+
5. **Events and durability** - dispatch mode, explicit waterfall `next()` semantics, which
|
|
119
|
+
replay-critical facts live in durable session state.
|
|
120
|
+
6. **Verification** - real Loader activation + PENDING/reactivation, provider replacement,
|
|
121
|
+
disposal, repeated mount/reload, leak checks.
|
|
122
|
+
|
|
123
|
+
## 6. Worked pattern (what a correct ACRYL plugin looks like)
|
|
124
|
+
|
|
125
|
+
The shipped `acryl_workspace_status` (`@acryldev/harness-runtime/src/plugin-acryl-workspace-status.ts`)
|
|
126
|
+
follows this exactly: `inject: ['tools']`, `ctx.tools.register(defineTool({...}))` with
|
|
127
|
+
`output.schema`/`render` and `exec.signal`, auto-mounted on the booted `ctx.tools` seam, and
|
|
128
|
+
effect-owned so it disposes with its Fiber. For a **resource-owning** plugin, use the pattern:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
export const inject = ['someService']
|
|
132
|
+
export function apply(ctx, config) {
|
|
133
|
+
ctx.effect(() => {
|
|
134
|
+
const handle = startResource(config) // or ctx.on(...), ctx.tools.register(...)
|
|
135
|
+
return () => handle.stop() // sequential, idempotent disposer
|
|
136
|
+
}, 'my-plugin: resource')
|
|
137
|
+
// optional-on-this-profile capability: use ctx.get('optionalService') instead of inject
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## 6b. Where plugins run - the three ACRYL surface kinds
|
|
142
|
+
|
|
143
|
+
Don't conflate "surface" with "thin consumer." ACRYL has three UI surfaces with different
|
|
144
|
+
relationships to the runtime:
|
|
145
|
+
|
|
146
|
+
- **TUI (`acryl-cli`)** - an **in-process** pi-tui agent surface, adapted from
|
|
147
|
+
`tomowang/dsh-tui` (`@tomowang/dsh-tui` 0.7.0 @ `f7663341`, `@earendil-works/pi-tui`
|
|
148
|
+
0.84.2). It boots the runtime directly (`startDirectHost()` + `createAcrylSessionBridge()`)
|
|
149
|
+
and reads/writes `ctx` in-process - it is a rich agent UI, **not** an RPC client. It has
|
|
150
|
+
GUI-feature-parity overlays (`/model /presets /trajectory /tools /context /plugins /goal
|
|
151
|
+
/plan /compact` + approvals). DSH's `apps/cli` is only the `dsh` **launcher** and is **not**
|
|
152
|
+
the model for this.
|
|
153
|
+
- **Web (`acryl-web`)** - the browser renderer is a **separate client Cordis app** consuming
|
|
154
|
+
host services over typed RPC (typert) + `dsh-client-connection`; the Node host boots the
|
|
155
|
+
runtime in-process.
|
|
156
|
+
- **Desktop (`acryl-desktop`)** - Electron main boots the runtime; the renderer is the same
|
|
157
|
+
client shell over `file://` + IPC (not HTTP). It should NOT re-roll its own renderer.
|
|
158
|
+
|
|
159
|
+
See `docs/acryl/tomowang-dsh-tui-provenance.md` and the roadmap's M1 for the TUI origin.
|
|
160
|
+
|
|
161
|
+
## 7. Reference pointers
|
|
162
|
+
|
|
163
|
+
- Long handbook: `docs/cordis/cordis_system_guide_for_coding_agents.md`
|
|
164
|
+
- Generated API: `deepseek-harness/docs/cordis-api/{context,events,fiber,registry,service,inherited}.md`
|
|
165
|
+
- Vendor source: `deepseek-harness/vendor/cordis/src/` (core), `vendor/loader/src/`, `vendor/include/src/`
|
|
166
|
+
- Plugin authoring: `docs/cordisplugins/` (hello-world, development-canvas)
|
|
167
|
+
- Tool contract + mini-design + fiber states: repo `AGENTS.md` → "Cordis development protocol"
|