@acryldev/plugin-context 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +12 -2
- package/docs/README.md +160 -0
- package/docs/delivery/local-live.md +113 -0
- package/docs/delivery/marketplace.md +16 -0
- package/docs/docs.json +2836 -0
- package/docs/extending/agent-preset.md +37 -0
- package/docs/extending/chat-command.md +28 -0
- package/docs/extending/client-slot.md +135 -0
- package/docs/extending/config-schema.md +7 -0
- package/docs/extending/cordis-core.md +63 -0
- package/docs/extending/desktop-app.md +53 -0
- package/docs/extending/desktop-main.md +25 -0
- package/docs/extending/event-hook.md +14 -0
- package/docs/extending/host-route.md +33 -0
- package/docs/extending/llm-adapter.md +38 -0
- package/docs/extending/packaging.md +53 -0
- package/docs/extending/prompt-contribution.md +9 -0
- package/docs/extending/service.md +13 -0
- package/docs/extending/skill-provider.md +9 -0
- package/docs/extending/state-and-persistence.md +71 -0
- package/docs/extending/three-role-capability.md +33 -0
- package/docs/extending/tool-plugin.md +24 -0
- package/docs/extending/tui-command.md +8 -0
- package/docs/extending/tui-components.md +61 -0
- package/docs/extending/ui-branding.md +43 -0
- package/docs/extending/ui-components.md +56 -0
- package/docs/extending/ui-customization.md +41 -0
- package/docs/extending/ui-library.md +66 -0
- package/docs/extending/ui-theme.md +55 -0
- package/docs/extending/workspace-tab.md +50 -0
- package/docs/maps/events.md +108 -0
- package/docs/maps/mount-points.md +154 -0
- package/docs/maps/slot-contracts.md +3376 -0
- package/docs/maps/taxonomy.md +306 -0
- package/docs/maps/theme-tokens.md +115 -0
- package/docs/maps/ui-components.md +26 -0
- package/docs/reference/cookbook/adding-a-package.md +174 -0
- package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
- package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
- package/docs/reference/cookbook/adding-a-tool.md +103 -0
- package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
- package/docs/reference/cookbook/extension-cookbook.md +134 -0
- package/docs/reference/cordis-api/context.md +366 -0
- package/docs/reference/cordis-api/events.md +209 -0
- package/docs/reference/cordis-api/fiber.md +377 -0
- package/docs/reference/cordis-api/inherited.md +40 -0
- package/docs/reference/cordis-api/registry.md +154 -0
- package/docs/reference/cordis-api/service.md +104 -0
- package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
- package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
- package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
- package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
- package/docs/reference/harness/agent-lifecycle.md +93 -0
- package/docs/reference/harness/architecture.md +168 -0
- package/docs/reference/harness/capability-seams.md +675 -0
- package/docs/reference/harness/config-catalog.md +4523 -0
- package/docs/reference/harness/cordis-primer.md +47 -0
- package/docs/reference/harness/defensive-patterns.md +35 -0
- package/docs/reference/harness/event-producer-consumer.md +111 -0
- package/docs/reference/harness/glossary.md +47 -0
- package/docs/reference/harness/tool-catalog.md +2721 -0
- package/docs/reference/harness/tool-execution-pipeline.md +67 -0
- package/docs/reference/subsystems/README.md +75 -0
- package/docs/reference/subsystems/agent-team.md +233 -0
- package/docs/reference/subsystems/approval.md +172 -0
- package/docs/reference/subsystems/attachment.md +363 -0
- package/docs/reference/subsystems/boot.md +324 -0
- package/docs/reference/subsystems/browser-use.md +69 -0
- package/docs/reference/subsystems/client-modules.md +186 -0
- package/docs/reference/subsystems/client-resources.md +94 -0
- package/docs/reference/subsystems/commands.md +225 -0
- package/docs/reference/subsystems/compaction.md +286 -0
- package/docs/reference/subsystems/computer-use.md +58 -0
- package/docs/reference/subsystems/conversation.md +287 -0
- package/docs/reference/subsystems/core.md +1107 -0
- package/docs/reference/subsystems/credentials.md +497 -0
- package/docs/reference/subsystems/deliverables.md +180 -0
- package/docs/reference/subsystems/extensions.md +386 -0
- package/docs/reference/subsystems/feedback.md +402 -0
- package/docs/reference/subsystems/filesystem.md +532 -0
- package/docs/reference/subsystems/goal.md +315 -0
- package/docs/reference/subsystems/invariants.md +90 -0
- package/docs/reference/subsystems/jobs.md +501 -0
- package/docs/reference/subsystems/llm-streaming.md +1131 -0
- package/docs/reference/subsystems/lsp.md +204 -0
- package/docs/reference/subsystems/mcp.md +141 -0
- package/docs/reference/subsystems/office-to-pdf.md +89 -0
- package/docs/reference/subsystems/otel.md +46 -0
- package/docs/reference/subsystems/permission-presets.md +169 -0
- package/docs/reference/subsystems/persistence.md +418 -0
- package/docs/reference/subsystems/plan.md +89 -0
- package/docs/reference/subsystems/product-telemetry.md +81 -0
- package/docs/reference/subsystems/ptc-runtime.md +234 -0
- package/docs/reference/subsystems/sandbox.md +223 -0
- package/docs/reference/subsystems/schedule.md +545 -0
- package/docs/reference/subsystems/scope.md +61 -0
- package/docs/reference/subsystems/session-projection.md +358 -0
- package/docs/reference/subsystems/session-query.md +511 -0
- package/docs/reference/subsystems/session-reference.md +226 -0
- package/docs/reference/subsystems/session-telemetry.md +214 -0
- package/docs/reference/subsystems/session-title.md +206 -0
- package/docs/reference/subsystems/session.md +1300 -0
- package/docs/reference/subsystems/settings.md +157 -0
- package/docs/reference/subsystems/shell.md +316 -0
- package/docs/reference/subsystems/sidebar-right.md +160 -0
- package/docs/reference/subsystems/skills.md +354 -0
- package/docs/reference/subsystems/slots.md +201 -0
- package/docs/reference/subsystems/spill.md +126 -0
- package/docs/reference/subsystems/ssh.md +137 -0
- package/docs/reference/subsystems/storage.md +262 -0
- package/docs/reference/subsystems/subagent.md +762 -0
- package/docs/reference/subsystems/subprocess.md +323 -0
- package/docs/reference/subsystems/system-prompt.md +226 -0
- package/docs/reference/subsystems/terminal.md +186 -0
- package/docs/reference/subsystems/todo.md +34 -0
- package/docs/reference/subsystems/token-meter.md +108 -0
- package/docs/reference/subsystems/tools.md +749 -0
- package/docs/reference/subsystems/typert.md +489 -0
- package/docs/reference/subsystems/user-questions.md +309 -0
- package/docs/reference/subsystems/voice-input.md +166 -0
- package/docs/reference/subsystems/web-client.md +102 -0
- package/docs/reference/subsystems/web-server.md +228 -0
- package/docs/reference/subsystems/web.md +208 -0
- package/docs/reference/subsystems/webhook.md +72 -0
- package/docs/reference/subsystems/workflow.md +280 -0
- package/docs/reference/subsystems/workspace.md +661 -0
- package/docs/start-here/blueprints.md +33 -0
- package/docs/start-here/this-runtime.md +84 -0
- package/docs/start-here/troubleshooting.md +29 -0
- package/docs/start-here/trust-and-safety.md +39 -0
- package/docs/start-here/verify-before-done.md +46 -0
- package/example-plugins/README.md +45 -0
- package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
- package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
- package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
- package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
- package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
- package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
- package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
- package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
- package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/chat-command-basic/index.js +26 -0
- package/example-plugins/packages/chat-command-basic/package.json +25 -0
- package/example-plugins/packages/client-chat-message-action/client.js +46 -0
- package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-chat-message-action/index.js +9 -0
- package/example-plugins/packages/client-chat-message-action/package.json +31 -0
- package/example-plugins/packages/client-slot-header-action/client.js +57 -0
- package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-slot-header-action/index.js +13 -0
- package/example-plugins/packages/client-slot-header-action/package.json +31 -0
- package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
- package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
- package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
- package/example-plugins/packages/client-theme-override/client.js +52 -0
- package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-theme-override/index.js +9 -0
- package/example-plugins/packages/client-theme-override/package.json +30 -0
- package/example-plugins/packages/client-tool-view/client.js +47 -0
- package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-tool-view/index.js +24 -0
- package/example-plugins/packages/client-tool-view/package.json +34 -0
- package/example-plugins/packages/client-ui-components/client.js +77 -0
- package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-ui-components/index.js +9 -0
- package/example-plugins/packages/client-ui-components/package.json +31 -0
- package/example-plugins/packages/client-ui-library/client.js +715 -0
- package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-ui-library/index.js +9 -0
- package/example-plugins/packages/client-ui-library/package.json +37 -0
- package/example-plugins/packages/client-workspace-tab/client.js +72 -0
- package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-workspace-tab/index.js +9 -0
- package/example-plugins/packages/client-workspace-tab/package.json +30 -0
- package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/config-schema-basic/index.js +19 -0
- package/example-plugins/packages/config-schema-basic/package.json +25 -0
- package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
- package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
- package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
- package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/event-hook-basic/index.js +17 -0
- package/example-plugins/packages/event-hook-basic/package.json +22 -0
- package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
- package/example-plugins/packages/generated-capability-template/index.js +16 -0
- package/example-plugins/packages/generated-capability-template/package.json +42 -0
- package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/host-route-basic/index.js +20 -0
- package/example-plugins/packages/host-route-basic/package.json +29 -0
- package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
- package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
- package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
- package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
- package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
- package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
- package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
- package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
- package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
- package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
- package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
- package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
- package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
- package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
- package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
- package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
- package/example-plugins/packages/service-provider-greeter/index.js +22 -0
- package/example-plugins/packages/service-provider-greeter/package.json +25 -0
- package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/settings-section-basic/index.js +34 -0
- package/example-plugins/packages/settings-section-basic/package.json +26 -0
- package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/skill-provider-basic/index.js +31 -0
- package/example-plugins/packages/skill-provider-basic/package.json +22 -0
- package/example-plugins/packages/state-host-store/client.js +57 -0
- package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
- package/example-plugins/packages/state-host-store/index.js +90 -0
- package/example-plugins/packages/state-host-store/package.json +31 -0
- package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
- package/example-plugins/packages/state-workspace-file/index.js +52 -0
- package/example-plugins/packages/state-workspace-file/package.json +25 -0
- package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/tool-basic/index.js +25 -0
- package/example-plugins/packages/tool-basic/package.json +25 -0
- package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
- package/example-plugins/packages/tool-policy-hook/index.js +28 -0
- package/example-plugins/packages/tool-policy-hook/package.json +25 -0
- package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-command-basic/index.js +24 -0
- package/example-plugins/packages/tui-command-basic/package.json +22 -0
- package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
- package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
- package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-ui-library/index.js +73 -0
- package/example-plugins/packages/tui-ui-library/package.json +29 -0
- package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
- package/example-plugins/packages/web-page-branding/index.js +31 -0
- package/example-plugins/packages/web-page-branding/package.json +22 -0
- package/example-plugins/scenarios.json +11 -0
- package/index.js +384 -0
- package/lib/blend-apply.js +107 -0
- package/lib/blend-capture.js +249 -0
- package/lib/blend-ledger.js +76 -0
- package/lib/contract.js +5 -0
- package/lib/install.js +516 -0
- package/lib/lookup.js +67 -0
- package/lib/manifest.js +56 -0
- package/lib/pack-root.js +22 -0
- package/lib/provenance.js +110 -0
- package/lib/publish.js +64 -0
- package/lib/reconcile.js +83 -0
- package/lib/router.js +55 -0
- package/lib/scopes.js +82 -0
- package/lib/skills.js +54 -0
- package/lib/stage.js +157 -0
- package/lib/verify.js +77 -0
- package/package.json +58 -3
- package/scripts/lib/indexes.mjs +45 -0
- package/scripts/lib/manifest.mjs +127 -0
- package/scripts/lib/maps.mjs +482 -0
- package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
- package/skills/acryl-add-ui/SKILL.md +18 -0
- package/skills/acryl-build-plugin/SKILL.md +21 -0
- package/skills/acryl-change-plugin/SKILL.md +16 -0
- package/skills/acryl-desktop-shell/SKILL.md +12 -0
- package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
- package/skills/acryl-fix-plugin/SKILL.md +12 -0
- package/skills/acryl-improve-ui/SKILL.md +10 -0
- package/skills/acryl-remove-plugin/SKILL.md +11 -0
- package/skills/acryl-restyle-ui/SKILL.md +14 -0
- package/skills/acryl-share-plugin/SKILL.md +23 -0
- package/skills/acryl-tui-ui/SKILL.md +12 -0
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/boot.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Profile management
|
|
4
|
+
|
|
5
|
+
English | [中文](boot.zh.md)
|
|
6
|
+
|
|
7
|
+
The [boot package group](../../packages/boot/README.md) owns launcher-provided profile access and the plugin manager. [Plugin Manager](../../packages/boot/plugin-manager/README.md) documents persistence, reload and package-operation behavior.
|
|
8
|
+
|
|
9
|
+
## Management records
|
|
10
|
+
|
|
11
|
+
`PluginEntryId` identifies one Loader entry; callers obtain it from `listPlugins` rather than constructing a patch id.
|
|
12
|
+
|
|
13
|
+
`PluginInfo` carries module identity, effective enablement, fiber phase and optional display `meta`, plus a unique `patchId` or a `readOnlyReason`.
|
|
14
|
+
|
|
15
|
+
`BundleInfo` carries the package name, optional installed version, selected enablement, removal availability and optional resolution error. Its optional `meta` and each `BundleRowInfo.meta` contain display text or a metadata diagnostic; Clients select a language at render time.
|
|
16
|
+
|
|
17
|
+
`InstallBundleOptions.enabled` defaults to true. False installs without selecting the bundle layer. `approvedBuilds` grants persistent script permission to the supplied pending package names before installation. `registry` names the registry asked first; absent, the configured one.
|
|
18
|
+
|
|
19
|
+
`PluginRegistries` carries the configured first registry, `null` for the one pnpm's own configuration names, the fallbacks asked after it, and `resolved`, the URL pnpm's own configuration names or `null` while unread. `InspectOptions.registry` names the registry a lookup asks first.
|
|
20
|
+
|
|
21
|
+
`ChangeResult.changed` reports a disk edit independently of `application`: `applied`, `restart-required`, `overridden` or `failed`. Optional `error` carries a localizable code and external diagnostic. `packageResult` records the pnpm exit code, bounded output, truncation flag and complete diagnostic log path, plus `timedOut` when the manager terminated a run that stopped printing. A terminated run is classified `timeout` whatever exit status the signal left behind, so installation and removal report failure instead of success and no further registry is asked. `pendingBuilds` lists undecided packages across the profile; `approvedBuilds` records the names granted permission by this operation; `registries` lists the registries an installation asked, in order; `failedAt` says whether the last failed run could not reach the registry it asked or the host a git or tarball spec is fetched from.
|
|
22
|
+
|
|
23
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
24
|
+
|
|
25
|
+
<a id="cordis-surface"></a>
|
|
26
|
+
|
|
27
|
+
## Cordis API
|
|
28
|
+
|
|
29
|
+
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).
|
|
30
|
+
|
|
31
|
+
<a id="ctxconfigeditor--configeditor"></a>
|
|
32
|
+
|
|
33
|
+
### `ctx.configEditor` - `ConfigEditor`
|
|
34
|
+
|
|
35
|
+
Persist complete raw configs and apply them through the normal Loader path.
|
|
36
|
+
|
|
37
|
+
```ts cordis-catalog
|
|
38
|
+
/** Addressable profile rows; nested Includes have independent configuration ownership.
|
|
39
|
+
* @returns Active entries with unique profile patch ids.
|
|
40
|
+
*/
|
|
41
|
+
entries(): Entry[]
|
|
42
|
+
|
|
43
|
+
/** Read inherited and explicit profile values for the active entries.
|
|
44
|
+
* @returns Detached layer values alongside their Loader entries.
|
|
45
|
+
*/
|
|
46
|
+
configuration(): Array<{ entry: Entry; inherited: Record<string, unknown>; override: Record<string, unknown> }>
|
|
47
|
+
|
|
48
|
+
/** Validate, persist, and reconcile a plugin's next config; ordinary fields keep normal lifecycle rules.
|
|
49
|
+
* @param entry Current Loader entry, also used to detect replacement during the write.
|
|
50
|
+
* @param change Derive a raw config from the current entry and its inherited layer.
|
|
51
|
+
* @returns Fulfillment after Loader reconciliation completes.
|
|
52
|
+
*/
|
|
53
|
+
async edit( entry: Entry, change: (current: Record<string, unknown>, inherited: Record<string, unknown>) => Record<string, unknown>, ): Promise<void>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Source: [`packages/boot/config-editor/src/index.ts`](../../packages/boot/config-editor/src/index.ts)
|
|
57
|
+
|
|
58
|
+
<a id="ctxhmr--hmr"></a>
|
|
59
|
+
|
|
60
|
+
### `ctx.hmr` - `Hmr`
|
|
61
|
+
|
|
62
|
+
Hot reload service with Cordis-compatible module configuration and events.
|
|
63
|
+
|
|
64
|
+
```ts cordis-catalog
|
|
65
|
+
/** Serialize a caller-owned mutation with all automatic reload paths.
|
|
66
|
+
* @param operation Work that must not overlap module or configuration replacement.
|
|
67
|
+
* @returns The operation result after its asynchronous work completes.
|
|
68
|
+
*/
|
|
69
|
+
runExclusive<T>(operation: () => Promise<T>): Promise<T>
|
|
70
|
+
|
|
71
|
+
/** Watch a configuration path through the same queue as module replacement.
|
|
72
|
+
* @param filename Absolute path, which may not exist yet.
|
|
73
|
+
* @param refresh Rebuilds configuration from its current files and awaits Loader completion.
|
|
74
|
+
* @returns Disposer closing this registration and waiting for its pending refresh.
|
|
75
|
+
*/
|
|
76
|
+
async watchConfig(filename: string, refresh: () => Promise<void>): Promise<() => Promise<void>>
|
|
77
|
+
|
|
78
|
+
/** Read direct module dependency URLs from the active Node loader.
|
|
79
|
+
* @param url Module URL.
|
|
80
|
+
* @returns Linked module URLs, or an empty list for an uncached module.
|
|
81
|
+
*/
|
|
82
|
+
async getLinked(url: string): Promise<string[]>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Source: [`packages/boot/hmr/src/index.ts`](../../packages/boot/hmr/src/index.ts)
|
|
86
|
+
|
|
87
|
+
<a id="ctxpluginmanager--pluginmanager"></a>
|
|
88
|
+
|
|
89
|
+
### `ctx.pluginManager` - `PluginManager`
|
|
90
|
+
|
|
91
|
+
Manage profile files and apply their declared reload lifecycle.
|
|
92
|
+
|
|
93
|
+
```ts cordis-catalog
|
|
94
|
+
/** Read exact plugin-version exemptions saved in this profile.
|
|
95
|
+
* @returns Accepted package-name@version keys with the runtime versions they may run on, and any
|
|
96
|
+
* record or file problem the reader rejected, which the caller reports instead of failing.
|
|
97
|
+
*/
|
|
98
|
+
@Remote listVersionExemptions(): { exemptions: Record<string, string[]>; warnings: string[] }
|
|
99
|
+
|
|
100
|
+
/** Grant or revoke one exact plugin/runtime exemption and reevaluate live plugins.
|
|
101
|
+
* @param packageVersion Exact manifest package name followed by @ and its version; never an installation spec or alias.
|
|
102
|
+
* @param runtimeVersion Exact current DSH version for grants; revocation may name a previous runtime.
|
|
103
|
+
* @param enabled Whether to grant rather than revoke the exemption.
|
|
104
|
+
* @param acceptRisk Required true for grants after the user accepts possible crashes and data loss.
|
|
105
|
+
* @returns Saved and runtime outcomes. Startup-only profiles require restart.
|
|
106
|
+
*/
|
|
107
|
+
@Remote setVersionExemption(packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk?: boolean): Promise<ChangeResult>
|
|
108
|
+
|
|
109
|
+
/** Read current plugins, including why a row cannot be changed through the profile patch.
|
|
110
|
+
* @returns Current runtime entries with persistent patch targets.
|
|
111
|
+
*/
|
|
112
|
+
@Remote async listPlugins(): Promise<PluginInfo[]>
|
|
113
|
+
|
|
114
|
+
/** Read the profile's installed bundles, the bundles this dsh installation supplies, and the selected names that are not bundles.
|
|
115
|
+
* A dependency without a bundle patch is listed, as a `not-bundle` problem, only while it is selected.
|
|
116
|
+
* @returns Package versions, manifest descriptions, rows, optional display metadata, activation selections,
|
|
117
|
+
* whether the installation offers the bundle, and removal availability.
|
|
118
|
+
*/
|
|
119
|
+
@Remote listBundles(): Promise<BundleInfo[]>
|
|
120
|
+
|
|
121
|
+
/** Read the registries this manager asks: the configured first one, its fallbacks in order, and what pnpm's own configuration names.
|
|
122
|
+
* @returns The registries in pnpm's comparison form; null is the one pnpm's own configuration names, `resolved` as pnpm reads it now.
|
|
123
|
+
*/
|
|
124
|
+
@Remote async registries(): Promise<PluginRegistries>
|
|
125
|
+
|
|
126
|
+
/** Read what a spec names before installing it.
|
|
127
|
+
* @param spec One package spec: a registry name, an absolute path, a git address, or a tarball.
|
|
128
|
+
* @param options The registry asked first.
|
|
129
|
+
* @param signal Ends a registry lookup early.
|
|
130
|
+
* @returns The package the spec names, or why it is refused.
|
|
131
|
+
*/
|
|
132
|
+
@Remote async inspect(spec: string, options?: InspectOptions, signal?: AbortSignal): Promise<PluginSpecInspection>
|
|
133
|
+
|
|
134
|
+
/** Persist a plugin entry's desired enablement and apply it on live profiles.
|
|
135
|
+
* @param id Loader entry identity returned by listPlugins.
|
|
136
|
+
* @param enabled Whether the plugin should run.
|
|
137
|
+
* @returns Saved and runtime outcomes, including higher-priority overrides.
|
|
138
|
+
*/
|
|
139
|
+
@Remote setPluginEnabled(id: PluginEntryId, enabled: boolean): Promise<ChangeResult>
|
|
140
|
+
|
|
141
|
+
/** Select or remove a bundle layer while retaining installed dependencies.
|
|
142
|
+
* @param name Bundle package name.
|
|
143
|
+
* @param enabled Whether the bundle contributes its patch layer.
|
|
144
|
+
* @returns Persisted and runtime outcomes.
|
|
145
|
+
*/
|
|
146
|
+
@Remote setBundleEnabled(name: string, enabled: boolean): Promise<ChangeResult>
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Install a package using the same pnpm implementation as dsh plugin. GitHub
|
|
150
|
+
* repositories get a connection check bounded by githubConnectionTimeoutMs before pnpm starts;
|
|
151
|
+
* only network failures or timeouts stop installation, while pnpm owns authentication and transport fallback. A run
|
|
152
|
+
* that fails, is cancelled, or adds a package without a bundle patch restores
|
|
153
|
+
* `package.json` and `pnpm-lock.yaml` as they were; downloaded files can stay.
|
|
154
|
+
* @param spec One package spec, including local paths relative to the invocation directory.
|
|
155
|
+
* @param options Whether to activate the installed bundle (defaults to true), the request id a cancellation names,
|
|
156
|
+
* the pending build scripts to allow for this profile before pnpm runs, and the registry asked first.
|
|
157
|
+
* @returns Package-manager diagnostics, the registries asked, and the observed activation outcome.
|
|
158
|
+
*/
|
|
159
|
+
@Remote installBundle(spec: string, options?: InstallBundleOptions): Promise<ChangeResult>
|
|
160
|
+
|
|
161
|
+
/** Recover the result of an active installation without cancelling it.
|
|
162
|
+
* @param requestId The id supplied when installation started.
|
|
163
|
+
* @returns The installation's outcome after it settles, or null if no active request has that id.
|
|
164
|
+
* Completed results are not retained; null establishes neither success nor cancellation.
|
|
165
|
+
*/
|
|
166
|
+
@Remote async waitForInstall(requestId: PluginInstallRequestId): Promise<ChangeResult | null>
|
|
167
|
+
|
|
168
|
+
/** Stop an installation this manager owns and wait until its files are back.
|
|
169
|
+
* @param requestId The id the installation was started with.
|
|
170
|
+
* @returns `cancelled` once the Git check or pnpm exited and the files are restored, `too-late` once the bundle is being
|
|
171
|
+
* applied, `not-running` for any other id.
|
|
172
|
+
*/
|
|
173
|
+
@Remote async cancelInstall(requestId: PluginInstallRequestId): Promise<PluginInstallCancellation>
|
|
174
|
+
|
|
175
|
+
/** Unload and remove a profile-owned bundle dependency through dsh plugin's pnpm path.
|
|
176
|
+
* @param name Installed dependency name.
|
|
177
|
+
* @returns Removal diagnostics and the remaining profile state.
|
|
178
|
+
*/
|
|
179
|
+
@Remote removeBundle(name: string): Promise<ChangeResult>
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Source: [`packages/boot/plugin-manager/src/index.ts`](../../packages/boot/plugin-manager/src/index.ts)
|
|
183
|
+
|
|
184
|
+
<a id="ctxpluginregistryprobe--pluginregistryprobe"></a>
|
|
185
|
+
|
|
186
|
+
### `ctx.pluginRegistryProbe` - `PluginRegistryProbe`
|
|
187
|
+
|
|
188
|
+
Compares public registry responses on the Host; the Client owns the initial selection.
|
|
189
|
+
|
|
190
|
+
```ts cordis-catalog
|
|
191
|
+
/**
|
|
192
|
+
* Race npm and npmmirror HTTPS ping responses through the Host's fetch proxy.
|
|
193
|
+
* Concurrent readers share a probe; a winner cancels and awaits the other request.
|
|
194
|
+
* @returns the first registry with a successful response, or null when disabled or neither responds successfully; results are cached.
|
|
195
|
+
* @throws rejects when the service has been unloaded.
|
|
196
|
+
*/
|
|
197
|
+
@Remote async fastest(): Promise<string | null>
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Source: [`packages/client/ui-plugin-manager/src/index.ts`](../../packages/client/ui-plugin-manager/src/index.ts)
|
|
201
|
+
|
|
202
|
+
<a id="ctxprofilecontext--profilecontext"></a>
|
|
203
|
+
|
|
204
|
+
### `ctx.profileContext` - `ProfileContext`
|
|
205
|
+
|
|
206
|
+
Current profile facts; scheduling and mutation belong to their callers.
|
|
207
|
+
|
|
208
|
+
Source: [`packages/boot/app-boot/src/profile-context.ts`](../../packages/boot/app-boot/src/profile-context.ts)
|
|
209
|
+
|
|
210
|
+
<a id="app-boot-events"></a>
|
|
211
|
+
|
|
212
|
+
### `app-boot/*` events
|
|
213
|
+
|
|
214
|
+
<a id="app-bootconfig-reload--emit"></a>
|
|
215
|
+
|
|
216
|
+
#### `app-boot/config-reload` - emit
|
|
217
|
+
|
|
218
|
+
Profile patches were reconciled into the running Loader tree: every entry update settled and no new inactive entry was introduced. Carries no diff; listeners re-read Loader entries.
|
|
219
|
+
|
|
220
|
+
```ts cordis-catalog
|
|
221
|
+
/**
|
|
222
|
+
* Profile patches were reconciled into the running Loader tree: every entry update settled and no new
|
|
223
|
+
* inactive entry was introduced. Carries no diff; listeners re-read Loader entries.
|
|
224
|
+
* @mode emit
|
|
225
|
+
*/
|
|
226
|
+
'app-boot/config-reload'(): void
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Source: [`packages/boot/app-boot/src/index.ts`](../../packages/boot/app-boot/src/index.ts)
|
|
230
|
+
|
|
231
|
+
<a id="hmr-events"></a>
|
|
232
|
+
|
|
233
|
+
### `hmr/*` events
|
|
234
|
+
|
|
235
|
+
<a id="hmrchange--emit"></a>
|
|
236
|
+
|
|
237
|
+
#### `hmr/change` - emit
|
|
238
|
+
|
|
239
|
+
A watched file has no module or configuration handler.
|
|
240
|
+
|
|
241
|
+
```ts cordis-catalog
|
|
242
|
+
/** A watched file has no module or configuration handler.
|
|
243
|
+
* @mode emit
|
|
244
|
+
* @param url Canonical file URL.
|
|
245
|
+
*/
|
|
246
|
+
'hmr/change'(url: string): void
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Source: [`packages/boot/hmr/src/index.ts`](../../packages/boot/hmr/src/index.ts)
|
|
250
|
+
|
|
251
|
+
<a id="hmrreload--emit"></a>
|
|
252
|
+
|
|
253
|
+
#### `hmr/reload` - emit
|
|
254
|
+
|
|
255
|
+
Module replacements have finished loading.
|
|
256
|
+
|
|
257
|
+
```ts cordis-catalog
|
|
258
|
+
/** Module replacements have finished loading.
|
|
259
|
+
* @mode emit
|
|
260
|
+
* @param reloads Replaced plugins and their module locations.
|
|
261
|
+
*/
|
|
262
|
+
'hmr/reload'(reloads: Map<Plugin, Reload>): void
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Source: [`packages/boot/hmr/src/index.ts`](../../packages/boot/hmr/src/index.ts)
|
|
266
|
+
|
|
267
|
+
<a id="plugin-manager-events"></a>
|
|
268
|
+
|
|
269
|
+
### `plugin-manager/*` events
|
|
270
|
+
|
|
271
|
+
<a id="plugin-managerchanged--emit"></a>
|
|
272
|
+
|
|
273
|
+
#### `plugin-manager/changed` - emit
|
|
274
|
+
|
|
275
|
+
The profile's plugins, bundles, or composition changed: a manager operation completed. A patch generation applied outside the manager, by HMR's watcher after a CLI or hand edit, announces nothing here.
|
|
276
|
+
|
|
277
|
+
```ts cordis-catalog
|
|
278
|
+
/**
|
|
279
|
+
* The profile's plugins, bundles, or composition changed: a manager
|
|
280
|
+
* operation completed. A patch generation applied outside the manager,
|
|
281
|
+
* by HMR's watcher after a CLI or hand edit, announces nothing here.
|
|
282
|
+
* @mode emit
|
|
283
|
+
* @param change - what changed.
|
|
284
|
+
*/
|
|
285
|
+
'plugin-manager/changed'(change: PluginChange): void
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
|
|
289
|
+
|
|
290
|
+
<a id="plugin-managerinstall-log--emit"></a>
|
|
291
|
+
|
|
292
|
+
#### `plugin-manager/install-log` - emit
|
|
293
|
+
|
|
294
|
+
One chunk of a pnpm run's output, streamed as the run produces it.
|
|
295
|
+
|
|
296
|
+
```ts cordis-catalog
|
|
297
|
+
/**
|
|
298
|
+
* One chunk of a pnpm run's output, streamed as the run produces it.
|
|
299
|
+
* @mode emit
|
|
300
|
+
* @param chunk - the chunk and the run it belongs to.
|
|
301
|
+
*/
|
|
302
|
+
'plugin-manager/install-log'(chunk: PluginInstallLogChunk): void
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
|
|
306
|
+
|
|
307
|
+
<a id="plugin-managerinstall-state--emit"></a>
|
|
308
|
+
|
|
309
|
+
#### `plugin-manager/install-state` - emit
|
|
310
|
+
|
|
311
|
+
An installation moved between its Host phases. `installing` is announced once per registry the installation asks, with the attempt's registry and position; `cancelling` and `applying` once.
|
|
312
|
+
|
|
313
|
+
```ts cordis-catalog
|
|
314
|
+
/**
|
|
315
|
+
* An installation moved between its Host phases. `installing` is announced once per registry the
|
|
316
|
+
* installation asks, with the attempt's registry and position; `cancelling` and `applying` once.
|
|
317
|
+
* @mode emit
|
|
318
|
+
* @param progress - the installation's request id and phase, with the attempt while installing.
|
|
319
|
+
*/
|
|
320
|
+
'plugin-manager/install-state'(progress: PluginInstallProgress): void
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
|
|
324
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/browser-use.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Browser use
|
|
4
|
+
|
|
5
|
+
English | [中文](browser-use.zh.md)
|
|
6
|
+
|
|
7
|
+
Browser use lets a model inspect and operate web pages through a configured backend. DSH owns the task loop; the provider supplies browser operations and keeps browser state across turns of one live Session.
|
|
8
|
+
|
|
9
|
+
## Choose a provider
|
|
10
|
+
|
|
11
|
+
Mount [`dsh-browser-use`](../../packages/browser-use/browser-use/README.md) and one provider in the same composition. The providers are experimental public npm packages and require explicit activation. Their initial browser engine is Chromium.
|
|
12
|
+
|
|
13
|
+
| Provider | Integration |
|
|
14
|
+
|---|---|
|
|
15
|
+
| [Playwright MCP](../../packages/experimental/browser-use-playwright-mcp/README.md) | Playwright's browser-control MCP tools |
|
|
16
|
+
| [Chrome DevTools MCP](../../packages/experimental/browser-use-chrome-devtools-mcp/README.md) | Chrome DevTools inspection and control through MCP |
|
|
17
|
+
| [Stagehand](../../packages/experimental/browser-use-stagehand-native/README.md) | Native browser operations with AI-assisted actions, observation, and extraction |
|
|
18
|
+
|
|
19
|
+
The shared service registers only a name and rejects any second provider, including another instance with the same name. It has no common browser-operation methods, browser resources, or model-controlled selector. Provider configuration in a profile or preset selects launch or attachment for that activation.
|
|
20
|
+
|
|
21
|
+
## Session ownership
|
|
22
|
+
|
|
23
|
+
A launched browser belongs to the exact live Agent and Session that uses it. Calls across turns reuse that browser. Disposing the Session runtime closes its launched resources; reloading or forking a Session starts fresh browser state. Browser profiles and login state are not restored from the Session log.
|
|
24
|
+
|
|
25
|
+
An attached browser remains externally owned. The provider reserves it for one Session within that provider instance, preserves its existing browser state, and rejects simultaneous attachment by another Session. Teardown disconnects and leaves the external browser running. Separate DSH processes and other clients remain outside this reservation.
|
|
26
|
+
|
|
27
|
+
Provider shutdown stops tool admission and waits for owned work and resource cleanup before releasing the shared provider registration. Cancellation cannot undo a browser action already delivered.
|
|
28
|
+
|
|
29
|
+
## MCP initialization
|
|
30
|
+
|
|
31
|
+
An MCP provider initializes one client for each live Agent created after the provider loads. The existing serial `agent/created` event awaits connection and discovery before creation or resume completes and queued input runs. The client remains with the Session across turns. Startup failure or cancellation rejects creation or resume and triggers client cleanup.
|
|
32
|
+
|
|
33
|
+
If an attachment is busy, that activation continues without the browser and does not retry on later turns. After release, a newly created or resumed activation can acquire it. Loading or reloading the provider does not adopt already active Sessions; the [shared runtime](../../packages/experimental/browser-use-runtime/README.md) owns these initialization rules.
|
|
34
|
+
|
|
35
|
+
## Tools and recorded results
|
|
36
|
+
|
|
37
|
+
Provider tools use the normal DSH execution pipeline and Session log. The providers own their tool schemas, result rendering, image support, configuration, and upstream limitations; the shared service adds no model-visible content. Stagehand's AI-assisted operations use its explicitly configured native model while DSH retains the task loop. DSH model routing, credential reuse, underlying inference request/response capture, and integration into Session usage accounting are deferred; returned SDK data and metadata remain ordinary logged tool results.
|
|
38
|
+
|
|
39
|
+
Browser MCP connections also expose [resources and server instructions](mcp.md). Resource calls addressed to a browser server use its Session queue and reject other Sessions; server instructions are assembled only for its owning Session.
|
|
40
|
+
|
|
41
|
+
The [decision record](../../.agents/notes/implemented/architecture/2026-09-12-browser-use-provider-registration.md) explains the registration-only service and per-Session ownership.
|
|
42
|
+
|
|
43
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
44
|
+
|
|
45
|
+
<a id="cordis-surface"></a>
|
|
46
|
+
|
|
47
|
+
## Cordis API
|
|
48
|
+
|
|
49
|
+
Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
|
|
50
|
+
|
|
51
|
+
<a id="ctxbrowseruse--browseruseregistry"></a>
|
|
52
|
+
|
|
53
|
+
### `ctx.browserUse` - `BrowserUseRegistry`
|
|
54
|
+
|
|
55
|
+
Owns one optional provider registration in the shared browser-use service.
|
|
56
|
+
|
|
57
|
+
```ts cordis-catalog
|
|
58
|
+
/**
|
|
59
|
+
* Reserve the sole provider slot until the contribution is disposed.
|
|
60
|
+
* A second registration fails even when it repeats the current name. Providers
|
|
61
|
+
* must stop their tools and await owned work before releasing this registration.
|
|
62
|
+
* @param name - provider-owned name used in registration diagnostics.
|
|
63
|
+
* @returns the effect disposer for this exact registration.
|
|
64
|
+
*/
|
|
65
|
+
register(name: BrowserUseProviderName): () => Promise<void>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Source: [`packages/browser-use/browser-use/src/index.ts`](../../packages/browser-use/browser-use/src/index.ts)
|
|
69
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/client-modules.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Client Modules
|
|
4
|
+
|
|
5
|
+
English | [中文](client-modules.zh.md)
|
|
6
|
+
|
|
7
|
+
The web plugin table: the Node half of the client module system in [dsh-client-modules](../../packages/client/modules), provided as `ctx.clientModules` (`ClientModuleRegistry`). It scans the host Loader's entries for packages declaring `dsh.client`, composes the `window.__DSH_BOOT__` entry graph, serves versioned one-or-more-resource combo scripts under `/plugins`, and answers every index-injection collection with the boot protocol rows - the four faces of one service. It is an optional capability of the web GUI stack, not part of the agent-loop spine, and it is a consumer of [dsh-host-webserver](../../packages/host/webserver): the carrier described in [web-server.md](web-server.md) supplies the prefix route and the `webserver/index-inject` event this service answers. The same package's browser half (`ctx.modules`, the lazy-CJS module table that fetches and materializes these bundles) is kernel machinery documented in the [package README](../../packages/client/modules/README.md), not here.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
|
|
10
|
+
|
|
11
|
+
## The wire
|
|
12
|
+
|
|
13
|
+
The graph is the wire single source between the Node and browser halves. The host composes `WebBootEntry` rows and `WebBootBatch` descriptors from scanned packages, then contributes the registration facade, application preloads, bootstrap scripts, and graph global to the structured index-injection table before the Vite entry. The `global` row renders as `globalThis["__DSH_BOOT__"]` with `<` escaped so plugin-controlled strings cannot break out of the script element. A page without a valid manifest cannot boot: the browser parser rejects malformed rows or batches, unknown members, and entries without exactly one initial combo descriptor.
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/**
|
|
17
|
+
* One composed client entry pushed by the host (a graph row). Wire
|
|
18
|
+
* single source: the host node half (package root) produces this same shape.
|
|
19
|
+
* `immediately` marks stage-one prefetch. `inject` names package rows whose
|
|
20
|
+
* factories must arrive before this row materializes, while Cordis separately
|
|
21
|
+
* uses the same package edges to compose entries. `external` carries exact
|
|
22
|
+
* non-inject module requests (see {@link WebBootGraph.entries}).
|
|
23
|
+
*/
|
|
24
|
+
interface WebBootEntry {
|
|
25
|
+
/** Entry name == package name. */
|
|
26
|
+
id: string
|
|
27
|
+
/**
|
|
28
|
+
* Revisioned single-resource combo reference used by HMR. It is relative to
|
|
29
|
+
* the document, so the browser resolves it under whatever mount served the page.
|
|
30
|
+
*/
|
|
31
|
+
url: string
|
|
32
|
+
/** Opaque plugin-artifact revision used for HMR cache busting. */
|
|
33
|
+
rev: string
|
|
34
|
+
/** Package-name dependency edges used for factory arrival and plugin composition. */
|
|
35
|
+
inject?: string[]
|
|
36
|
+
/** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
|
|
37
|
+
immediately?: boolean
|
|
38
|
+
/** Non-baseline module specifiers this row requests; omitted when it requests none. */
|
|
39
|
+
external?: string[]
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
```ts type-equiv
|
|
44
|
+
/** Initial scheduling phase for one revisioned combo script. */
|
|
45
|
+
type WebBootBatchPhase = 'bootstrap' | 'application'
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
```ts type-equiv
|
|
49
|
+
/** One initial combo script; a scheduling phase may span several descriptors. */
|
|
50
|
+
interface WebBootBatch {
|
|
51
|
+
/** Parser-blocking bootstrap or preloaded application scheduling. */
|
|
52
|
+
phase: WebBootBatchPhase
|
|
53
|
+
/** Content-addressed combo script reference, document-relative like {@link WebBootEntry.url}. */
|
|
54
|
+
url: string
|
|
55
|
+
/** Revision derived from the ordered entry revisions. */
|
|
56
|
+
rev: string
|
|
57
|
+
/** Graph entry ids whose factories the script registers, in execution order. */
|
|
58
|
+
entries: string[]
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```ts type-equiv
|
|
63
|
+
/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
|
|
64
|
+
interface WebBootGraph {
|
|
65
|
+
/** Consistency anchor over the current entry and batch descriptors. */
|
|
66
|
+
rev: string
|
|
67
|
+
/**
|
|
68
|
+
* Composed entries in module-graph order - a dynamic package row precedes
|
|
69
|
+
* rows whose `external` requests that package. Cordis activation order is
|
|
70
|
+
* unrelated and remains owned by fiber service waiting.
|
|
71
|
+
*/
|
|
72
|
+
entries: WebBootEntry[]
|
|
73
|
+
/** Initial combo descriptors; every entry belongs to exactly one descriptor. */
|
|
74
|
+
batches: WebBootBatch[]
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Initial publication and HMR derive each row's `rev` from the entry's mtime, ctime, and size, without hashing executable bytes. The same artifacts retain their revisions across Host restarts. The initial descriptors partition rows into bootstrap and application scheduling phases, and either phase may contain several descriptors. Their URLs contain only the ordered package-resource list and a revision derived from those row revisions; phase names do not enter the route. Graph composition preserves row order while greedily splitting before the map-form URL exceeds 3 KiB, without concatenating scripts or reading maps. The graph revision hashes the entry and batch descriptors. `immediately` marks the stage-one registration barrier; rows within one combo share its script transport, while separate combos load independently.
|
|
79
|
+
|
|
80
|
+
## The scan
|
|
81
|
+
|
|
82
|
+
A package joins the table by declaring `dsh.client` (`platform: 'web'`, optional `inject` edges, optional `immediately`) in its package.json and exporting its built bundle at `exports["./client"]`. Each live row resolves from its own Loader specifier and owning-tree `baseUrl`, through the same `loader.internal.resolveSync` implementation that imports its Host face when available. The nearest owning package manifest supplies the browser module id, so relative source and built overlays retain the package identity. Distinct active Loader sources resolving to one package name fail composition; after one source unloads, the surviving source supplies the row without a fiber restart.
|
|
83
|
+
|
|
84
|
+
Scanning is incremental per package; there is no full-rescan code path. Every cordis `internal/plugin` emission (fiber construction or disposal) marks the fiber's entry name dirty, and a microtask flush reconciles each dirty name against the live loader entries. The activation pass seeds the same dirty set with all current entries and flushes synchronously, so first scan and steady state share one implementation - with opposite failure postures. At activation, a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud `AggregateError` listing every broken package: the fiber FAILS and the boot's fail-loud sweep reports it. In steady state, a broken package logs a warning and must not poison the others.
|
|
85
|
+
|
|
86
|
+
Package metadata - including the negative "not a client package" verdict - is cached per Loader specifier and owning-tree base URL until restart. A fiber restart from the same source reuses its row and rev untouched; bundle content changes reach the graph only through `rebuilt()`.
|
|
87
|
+
|
|
88
|
+
## The bundle route and index injection
|
|
89
|
+
|
|
90
|
+
`GET`/`HEAD /plugins/??<package-a>/client.js,<package-b>/client.js&rev=<rev>` addresses one generated combo script; a one-resource request uses the same form and is the HMR path. The script is concatenated once on its first `GET` and ends with a `sourceMappingURL` that carries the combo query alone - `??<package-a>/client.js.map,<package-b>/client.js.map&rev=<rev>`, resolved against the script's own directory rather than the document. The map files are not read by startup, index rendering, script `GET`, or `HEAD`; the first map `GET` reads and validates them, composes one Indexed Source Map v3, and caches that body. An authored component map supplies its section; a component without one receives an identity section whose `sourcesContent` is the captured bundle and whose source name is its packaged `sourceURL` or plugin route. Every startup request URL is at most 3 KiB measured as UTF-8 bytes; partitioning uses the longer map form. All application URLs are preloaded, and all bootstrap URLs execute before the graph global and Vite entry. Materialized responses use long-lived immutable caching. Unknown or altered resource lists, missing revisions, and stale revisions answer 404 rather than serving different bytes or letting the SPA fallback return HTML as JavaScript; other methods are 405. The injection rows carry the current graph on every index render, so a reload always boots against the live composition.
|
|
91
|
+
|
|
92
|
+
## The service
|
|
93
|
+
|
|
94
|
+
```ts type-equiv
|
|
95
|
+
/** Filesystem baseline captured before a client artifact snapshot is read. */
|
|
96
|
+
interface ClientArtifactBaseline {
|
|
97
|
+
/** Absolute path of the client bundle. */
|
|
98
|
+
readonly path: string
|
|
99
|
+
/** Bundle modification time in milliseconds. */
|
|
100
|
+
readonly mtimeMs: number
|
|
101
|
+
/** Bundle status-change time in milliseconds, including writes that preserve mtime. */
|
|
102
|
+
readonly ctimeMs: number
|
|
103
|
+
/** Bundle size in bytes. */
|
|
104
|
+
readonly size: number
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`ClientModuleRegistry` (`ctx.clientModules`, defined in [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)) exposes reads and the rebuild face; signatures are in the generated [service catalog](#ctxclientmodules--clientmoduleregistry). `graph()` returns the current composed graph (a stable object between changes), `clientPath(id)` returns the bundle's absolute path, and `artifactBaseline(id)` returns the bundle stat values captured before the current snapshot was read. `fetchBundle()` resolves the same lazy response used by the HTTP route. `rebuilt(id)` is the only entry point through which changed bundle content reaches the graph: it derives the revision from filesystem metadata, and only a revision change reads the new bytes, recomposes the graph, and notifies. `onRebuilt` fires per changed bundle with the new revision; `onGraphChanged` fires after any flush that recomposed the graph (row added or removed, or a rebuilt revision change) and is pull-model - listeners re-read `graph()`. Both notification paths contain listener exceptions so one throwing subscriber cannot skip later subscribers or kill whatever triggered the flush.
|
|
109
|
+
|
|
110
|
+
[`dsh-client-hmr`](../../packages/client/hmr/README.md) delivers live graph snapshots in the shipped Web composition. The Host forwards existing graph-change notifications immediately, and reconnect sends the current full graph. A graph describes desired browser entries without asserting that Host cleanup has completed. Its artifact poll separately reports rebuilt revisions. Source-map changes alone do not trigger a reload; a new combo-map URL appears only after a bundle revision changes, and each map body is fixed by its first `GET`. Client Modules validates snapshots and serializes reconciliation with those rebuilds; it owns the boot-created entry map, single-resource arrivals, asynchronous removal, unused-module/style cleanup and page-local retry status. Static platform modules and the bootstrap retain their page lifetime; Electron installation is a separate flow.
|
|
111
|
+
|
|
112
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
113
|
+
|
|
114
|
+
<a id="cordis-surface"></a>
|
|
115
|
+
|
|
116
|
+
## Cordis API
|
|
117
|
+
|
|
118
|
+
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).
|
|
119
|
+
|
|
120
|
+
<a id="ctxclientmodules--clientmoduleregistry"></a>
|
|
121
|
+
|
|
122
|
+
### `ctx.clientModules` - `ClientModuleRegistry`
|
|
123
|
+
|
|
124
|
+
The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index injection rows. Construction runs the activation scan synchronously - a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
|
|
125
|
+
|
|
126
|
+
```ts cordis-catalog
|
|
127
|
+
/**
|
|
128
|
+
* Current composed entry graph (stable object between changes).
|
|
129
|
+
* @returns the graph served as `window.__DSH_BOOT__`.
|
|
130
|
+
*/
|
|
131
|
+
graph(): WebBootGraph
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Absolute path of an entry's client bundle.
|
|
135
|
+
* @param id - entry id (package name).
|
|
136
|
+
* @returns the path, or undefined for an unknown id.
|
|
137
|
+
*/
|
|
138
|
+
clientPath(id: string): string | undefined
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Serve an advertised revisioned bundle or source map without a Web server.
|
|
142
|
+
* Unknown URLs return 404, unsupported methods return 405, and `HEAD`
|
|
143
|
+
* returns the same immutable headers without materializing a body. Each body
|
|
144
|
+
* is built once on its first `GET`; script construction never reads maps.
|
|
145
|
+
* @param request - shell-carrier request for a `/plugins` resource.
|
|
146
|
+
* @returns the exact response also exposed by the optional Web route.
|
|
147
|
+
*/
|
|
148
|
+
async fetchBundle(request: Request): Promise<Response>
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Filesystem baseline captured before an entry's current bytes were read.
|
|
152
|
+
* HMR compares it with the live files when installing a watch, so a write
|
|
153
|
+
* between startup composition and watch installation cannot disappear into
|
|
154
|
+
* the watcher's initial state.
|
|
155
|
+
* @param id - entry id (package name).
|
|
156
|
+
* @returns the path and baseline, or undefined for an unknown id.
|
|
157
|
+
*/
|
|
158
|
+
artifactBaseline(id: string): ClientArtifactBaseline | undefined
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Publish one completed bundle generation (the HMR watch's registration
|
|
162
|
+
* hook - the only entry point through which build changes reach the graph).
|
|
163
|
+
* Unchanged mtime, ctime and size preserve the graph without reading the bundle.
|
|
164
|
+
* @param id - entry id (package name).
|
|
165
|
+
* @returns the current artifact rev, or undefined for an unknown id.
|
|
166
|
+
*/
|
|
167
|
+
rebuilt(id: string): string | undefined
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Subscribe to bundle rebuilds; fires only when artifact metadata changes the rev.
|
|
171
|
+
* @param listener - receives the entry id and its new bundle rev.
|
|
172
|
+
* @returns the unsubscriber.
|
|
173
|
+
*/
|
|
174
|
+
onRebuilt(listener: (id: string, rev: string) => void): () => void
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Fires after any flush that recomposed the graph (row added/removed, or a
|
|
178
|
+
* rebuilt rev change). Pull model: listeners re-read {@link graph}.
|
|
179
|
+
* @param listener - notified with no payload.
|
|
180
|
+
* @returns the unsubscriber.
|
|
181
|
+
*/
|
|
182
|
+
onGraphChanged(listener: () => void): () => void
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Source: [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)
|
|
186
|
+
<!-- END GENERATED cordis-surface -->
|