@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,204 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/lsp.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# LSP navigation
|
|
4
|
+
|
|
5
|
+
English | [中文](lsp.zh.md)
|
|
6
|
+
|
|
7
|
+
The LSP seam - a [capability seam](../glossary.md#capability-seam) exposing semantic code navigation on one `ctx.lsp` service, split across packages: Service Definition ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic Service Provider ([dsh-lsp-stdio](../../packages/lsp/lsp-stdio), a configured stdio language-server host), and Consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine - so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
|
|
10
|
+
|
|
11
|
+
## Operations and coordinates
|
|
12
|
+
|
|
13
|
+
The seam and model expose exactly four semantic queries; the union is closed, so adding one is a compile-enforced change across the seam, providers, and the tool. Positions and ranges are zero-based UTF-16, matching the protocol; the model-facing tool owns the one-based cursor convention and converts on the way in and out.
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/**
|
|
17
|
+
* The four semantic queries the seam and model expose. A closed union: adding an operation is a
|
|
18
|
+
* compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are
|
|
19
|
+
* not operations here; they need different schemas.
|
|
20
|
+
*/
|
|
21
|
+
type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover'
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```ts type-equiv
|
|
25
|
+
/** A zero-based UTF-16 cursor coordinate, matching the LSP wire convention. */
|
|
26
|
+
interface LspPosition {
|
|
27
|
+
/** Zero-based line. */
|
|
28
|
+
readonly line: number
|
|
29
|
+
/** Zero-based UTF-16 code-unit offset within the line. */
|
|
30
|
+
readonly character: number
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```ts type-equiv
|
|
35
|
+
/** A zero-based UTF-16 half-open range `[start, end)`. */
|
|
36
|
+
interface LspRange {
|
|
37
|
+
readonly start: LspPosition
|
|
38
|
+
readonly end: LspPosition
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Request
|
|
43
|
+
|
|
44
|
+
Every field is required: `workspaceRoot` is caller-supplied, `languageId` comes from the provider's registration (not the request), and consumers own timeouts and result limits - so no field needs implementation defaulting and there is no `resolve()` step. The provider receives the caller's request plus the derived `languageId`, which only synchronizes the transient document and never participates in selection.
|
|
45
|
+
|
|
46
|
+
```ts type-equiv
|
|
47
|
+
/**
|
|
48
|
+
* A caller's normalized query. Every field is required: `workspaceRoot` is caller-supplied,
|
|
49
|
+
* `languageId` comes from the provider registration (not here), and consumers own timeouts and
|
|
50
|
+
* result limits - so no field needs implementation defaulting and there is no `resolve()` step.
|
|
51
|
+
*/
|
|
52
|
+
interface LspQueryRequest {
|
|
53
|
+
/** Which semantic query to run. */
|
|
54
|
+
readonly operation: LspOperation
|
|
55
|
+
/** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */
|
|
56
|
+
readonly filePath: string
|
|
57
|
+
/** The zero-based UTF-16 cursor position to query at. */
|
|
58
|
+
readonly position: LspPosition
|
|
59
|
+
/** The workspace root the provider resolves against and indexes; required, never defaulted. */
|
|
60
|
+
readonly workspaceRoot: string
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
```ts type-equiv
|
|
65
|
+
/**
|
|
66
|
+
* A request as a provider receives it: the caller's {@link LspQueryRequest} plus the `languageId`
|
|
67
|
+
* the seam derived from the provider's extension mapping. The language id only synchronizes the
|
|
68
|
+
* transient document; it does not participate in selection.
|
|
69
|
+
*/
|
|
70
|
+
interface LspProviderQuery extends LspQueryRequest {
|
|
71
|
+
/** The LSP language id for `filePath`, from this provider's extension mapping. */
|
|
72
|
+
readonly languageId: string
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Result
|
|
77
|
+
|
|
78
|
+
A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `findReferences` always includes declarations - the provider enforces this internally, so callers get no flag. The `locations` variant carries `resolvedWorkspaceUri`, the provider's canonical workspace `file:` URI. A caller relativizing location URIs uses that coordinate rather than applying host-platform path rules to the possibly-symlinked request root.
|
|
79
|
+
|
|
80
|
+
```ts type-equiv
|
|
81
|
+
/** One resolved location: a document URI and the range within it. */
|
|
82
|
+
interface LspLocation {
|
|
83
|
+
/** The target document URI (`file:` or otherwise), verbatim from the server. */
|
|
84
|
+
readonly uri: string
|
|
85
|
+
/** The range within the target document. */
|
|
86
|
+
readonly range: LspRange
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
```ts type-equiv
|
|
91
|
+
/** Normalized hover content, or `null` for no hover at the position. */
|
|
92
|
+
interface LspHover {
|
|
93
|
+
/** The normalized hover text (markdown or plaintext, provider-joined). */
|
|
94
|
+
readonly contents: string
|
|
95
|
+
/** The range the hover applies to, when the server supplied one. */
|
|
96
|
+
readonly range?: LspRange
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```ts type-equiv
|
|
101
|
+
/**
|
|
102
|
+
* The closed result union. Navigation operations (`goToDefinition`, `findReferences`,
|
|
103
|
+
* `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
|
|
104
|
+
* Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
|
|
105
|
+
*
|
|
106
|
+
* The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
|
|
107
|
+
* the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
|
|
108
|
+
* request's possibly symlinked process path with host-platform rules; the execution platform may
|
|
109
|
+
* differ from the caller's.
|
|
110
|
+
*/
|
|
111
|
+
type LspQueryResult =
|
|
112
|
+
| { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
|
|
113
|
+
| { readonly kind: 'hover'; readonly hover: LspHover | null }
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Provider and service
|
|
117
|
+
|
|
118
|
+
A provider owns a stable branded `id` and an exclusive lowercase leading-dot extension map. `registerProvider` reserves the id and every extension atomically - an invalid or conflicting registration publishes nothing - and its disposer releases all reservations. Selection is per query and order-independent; no match throws `LspError` `LSP_UNAVAILABLE`. The seam exposes no protocol types, process/document controls, or generic JSON-RPC escape hatch.
|
|
119
|
+
|
|
120
|
+
```ts type-equiv
|
|
121
|
+
/**
|
|
122
|
+
* A language-server backend registered on `ctx.lsp`. Each provider owns a stable {@link
|
|
123
|
+
* LspProviderId} and an extension-to-language-id map (lowercase, leading-dot keys).
|
|
124
|
+
* `findReferences` always includes declarations - the provider enforces this internally; callers
|
|
125
|
+
* get no flag.
|
|
126
|
+
*/
|
|
127
|
+
interface LspProvider {
|
|
128
|
+
/** Stable provider identity, reserved atomically with the extension mappings. */
|
|
129
|
+
readonly id: LspProviderId
|
|
130
|
+
/** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */
|
|
131
|
+
readonly extensionToLanguage: Readonly<Record<string, string>>
|
|
132
|
+
/**
|
|
133
|
+
* Run one query. The seam has already selected this provider and derived `languageId`.
|
|
134
|
+
* @param request - the resolved provider query (caller request + derived language id).
|
|
135
|
+
* @param signal - optional cancellation; the provider stops its own work when it aborts.
|
|
136
|
+
* @returns the normalized, closed-union result.
|
|
137
|
+
*/
|
|
138
|
+
query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult>
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
```ts type-equiv
|
|
143
|
+
/**
|
|
144
|
+
* The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query
|
|
145
|
+
* execution; exposes exactly the four operations and no protocol escape hatch.
|
|
146
|
+
*/
|
|
147
|
+
interface LspService {
|
|
148
|
+
/**
|
|
149
|
+
* Register a provider, atomically reserving its id and every normalized extension. Any conflict
|
|
150
|
+
* or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
|
|
151
|
+
* reservations. Disposed with the calling fiber.
|
|
152
|
+
* @param provider - the backend to register.
|
|
153
|
+
* @returns a synchronous disposer releasing the id and all extension reservations.
|
|
154
|
+
*/
|
|
155
|
+
registerProvider(provider: LspProvider): () => void
|
|
156
|
+
/**
|
|
157
|
+
* Select a provider by the file's extension and run one query. Selection is per-query and
|
|
158
|
+
* order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
|
|
159
|
+
* @param request - the normalized query.
|
|
160
|
+
* @param signal - optional cancellation forwarded to the selected provider.
|
|
161
|
+
* @returns the normalized, closed-union result.
|
|
162
|
+
*/
|
|
163
|
+
query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`LspProviderId` is the seam's branded id (`Branded<'LspProviderId'>` from [dsh-brand](../../packages/util/brand)); `LspError` extends `HarnessError` with stable codes such as `LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_DISPOSED`, `LSP_UNSUPPORTED_OPERATION`, and `LSP_MALFORMED_RESPONSE`, which callers route on instead of parsing `message`.
|
|
168
|
+
|
|
169
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
170
|
+
|
|
171
|
+
<a id="cordis-surface"></a>
|
|
172
|
+
|
|
173
|
+
## Cordis API
|
|
174
|
+
|
|
175
|
+
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).
|
|
176
|
+
|
|
177
|
+
<a id="ctxlsp--lspservice"></a>
|
|
178
|
+
|
|
179
|
+
### `ctx.lsp` - `LspService`
|
|
180
|
+
|
|
181
|
+
The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query execution; exposes exactly the four operations and no protocol escape hatch.
|
|
182
|
+
|
|
183
|
+
```ts cordis-catalog
|
|
184
|
+
/**
|
|
185
|
+
* Register a provider, atomically reserving its id and every normalized extension. Any conflict
|
|
186
|
+
* or invalid input publishes nothing and throws `LspError`; the returned disposer releases all
|
|
187
|
+
* reservations. Disposed with the calling fiber.
|
|
188
|
+
* @param provider - the backend to register.
|
|
189
|
+
* @returns a synchronous disposer releasing the id and all extension reservations.
|
|
190
|
+
*/
|
|
191
|
+
registerProvider(provider: LspProvider): () => void
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Select a provider by the file's extension and run one query. Selection is per-query and
|
|
195
|
+
* order-independent; no match throws `LspError` `LSP_UNAVAILABLE`.
|
|
196
|
+
* @param request - the normalized query.
|
|
197
|
+
* @param signal - optional cancellation forwarded to the selected provider.
|
|
198
|
+
* @returns the normalized, closed-union result.
|
|
199
|
+
*/
|
|
200
|
+
query(request: LspQueryRequest, signal?: AbortSignal): Promise<LspQueryResult>
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)
|
|
204
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/mcp.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# MCP
|
|
4
|
+
|
|
5
|
+
English | [中文](mcp.zh.md)
|
|
6
|
+
|
|
7
|
+
## Summary
|
|
8
|
+
|
|
9
|
+
Model Context Protocol (MCP) connects the model to tools supplied by external servers. Each configured server contributes ordinary harness tools with cancellation, permission checks, recorded results, and supported image output. Shared tools discover and read resources when a server is configured in the caller's scope, while server instructions join the logged system prompt. The official SDK negotiates modern or supported legacy protocol revisions. This reference covers the MCP package group's responsibilities, scope, and composition choices; the [client README](../../packages/mcp/mcp-client/README.md) owns server configuration.
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Configuration](#configuration)
|
|
14
|
+
- [Responsibilities and scope](#responsibilities-and-scope)
|
|
15
|
+
- [Protocol and results](#protocol-and-results)
|
|
16
|
+
- [Resources and instructions](#resources-and-instructions)
|
|
17
|
+
- [Resource provider types](#resource-provider-types)
|
|
18
|
+
- [Limits](#limits)
|
|
19
|
+
- [Further reading](#further-reading)
|
|
20
|
+
|
|
21
|
+
-----
|
|
22
|
+
|
|
23
|
+
<a id="configuration"></a>
|
|
24
|
+
## Configuration
|
|
25
|
+
|
|
26
|
+
MCP servers are opt-in. Configure one `@deepseek-ai/dsh-mcp-client` entry per server in the intended Cordis scope. Every shipped profile supplies the [tool registry](tools.md) and mounts the shared resource service once; users configure only client entries. Callers with no visible configured server receive no MCP prompt text or tools in native or PTC mode.
|
|
27
|
+
|
|
28
|
+
| Choice | Configuration owner |
|
|
29
|
+
|---|---|
|
|
30
|
+
| Server identity, local process or HTTP endpoint, credentials, and process environment | [Client configuration](../../packages/mcp/mcp-client/README.md#use-this-package) |
|
|
31
|
+
| Tool and resource request timeout, startup failure policy, and reconnection | [Client configuration](../../packages/mcp/mcp-client/README.md#use-this-package) |
|
|
32
|
+
| Resource discovery and reading | The [MCP resource service](../../packages/mcp/mcp-resources/README.md#use-this-package) is included in shipped profiles; it has no configuration fields |
|
|
33
|
+
| Server instruction size limit | Client `maxInstructionBytes`; the composition supplies [system-prompt assembly](system-prompt.md) |
|
|
34
|
+
| Permission decisions and supported image output | [Tool execution](tools.md) and [attachments](attachment.md) |
|
|
35
|
+
|
|
36
|
+
Protocol negotiation follows the SDK's supported revisions; there is no product setting that forces a protocol revision. The [configuration catalog](../config-catalog.md#deepseek-aidsh-mcp-client) lists accepted client fields and defaults.
|
|
37
|
+
|
|
38
|
+
-----
|
|
39
|
+
|
|
40
|
+
<a id="responsibilities-and-scope"></a>
|
|
41
|
+
## Responsibilities and scope
|
|
42
|
+
|
|
43
|
+
The client is a per-server connection plugin and a consumer of the harness tool registry. It does not publish a shared `ctx.mcp` service. The external server implements MCP operations; the SDK owns protocol exchange; the client adapts discovered tools to harness execution.
|
|
44
|
+
|
|
45
|
+
`mcp-resources` owns the shared resource tools and selects providers in the caller's scope. Each MCP client supplies resource operations through its own connection. The first provider in a scope enables the local shared tools, and removing the last removes them; inherited providers remain visible. The service owns these tool registrations independently of any one client. Connection failures do not remove shared resource tools while a visible client entry remains active.
|
|
46
|
+
|
|
47
|
+
Configured `serverName` identifies a server in its registration scope. Two entries in that scope cannot reserve the same name; separate Agent scopes can reuse it. Public tool names include the configured server name, so equally named tools from different servers remain distinct. Registration effects own names and discovered tools; plugin disposal closes the connection and removes its contributions.
|
|
48
|
+
|
|
49
|
+
The [native Cua Driver provider](../../packages/experimental/computer-use-cua-driver-native/README.md) shares the client's exported result adapter without opening an MCP connection. Desktop provider selection belongs to the [computer-use subsystem](computer-use.md).
|
|
50
|
+
|
|
51
|
+
-----
|
|
52
|
+
|
|
53
|
+
<a id="protocol-and-results"></a>
|
|
54
|
+
## Protocol and results
|
|
55
|
+
|
|
56
|
+
Both stdio and Streamable HTTP use the official SDK's negotiation, discovery, protocol validation, and cancellation. Tool-list changes trigger discovery through legacy notifications or a modern subscription. A failed refresh retains the previous tool generation; connection recovery follows the [client lifecycle](../../packages/mcp/mcp-client/README.md#use-this-package).
|
|
57
|
+
|
|
58
|
+
The result adapter retains canonical MCP JSON for programmatic callers and prepares ordinary tool content. Supported images use the attachment system; unsupported rich content produces explicit text diagnostics. The tool registry remains authoritative for policy failures and replaced results. The [tool contracts](tools.md) own recording and final presentation; the [client result reference](../../packages/mcp/mcp-client/README.md#use-this-package) owns MCP-specific projection details.
|
|
59
|
+
|
|
60
|
+
-----
|
|
61
|
+
|
|
62
|
+
<a id="resources-and-instructions"></a>
|
|
63
|
+
## Resources and instructions
|
|
64
|
+
|
|
65
|
+
Resource calls require an explicit configured server name. When system-prompt assembly is available, the resource service lists caller-visible names from the same registry used for dispatch, including servers with no tools or instructions. The shared registry resolves that name in the calling Agent's scope before dispatch; unavailable servers fail without a network request. Discovery and reads are on demand, including for servers that expose resources without tools. The [resource package](../../packages/mcp/mcp-resources/README.md) owns pagination and content rendering; its generated tool schemas live in the [tool catalog](../tool-catalog.md#deepseek-aidsh-mcp-resources).
|
|
66
|
+
|
|
67
|
+
Resource providers remain connection-owned. Scope disposal removes registrations; the MCP client controls cancellation and recovery. Canonical results retain complete JSON for programmatic callers, while the text projection replaces binary blobs with descriptions. Returned text enters ordinary tool history; content is not fetched merely because a server connects.
|
|
68
|
+
|
|
69
|
+
When system-prompt assembly is composed, the client publishes nonblank server instructions as a scoped, server-attributed section. Instructions remain literal text and pass the configured size limit before publication. A replacement connection publishes instructions only after discovery succeeds; absent instructions add no section. The [system-prompt subsystem](system-prompt.md) owns assembly and recording.
|
|
70
|
+
|
|
71
|
+
-----
|
|
72
|
+
|
|
73
|
+
<a id="resource-provider-types"></a>
|
|
74
|
+
## Resource provider types
|
|
75
|
+
|
|
76
|
+
The connection provider receives one operation and the original tool execution, including its caller and cancellation signal.
|
|
77
|
+
|
|
78
|
+
```ts type-equiv
|
|
79
|
+
/** One supported resource operation, with server-owned cursors and URIs. */
|
|
80
|
+
type McpResourceRequest =
|
|
81
|
+
| { method: 'resources/list' | 'resources/templates/list'; cursor?: string }
|
|
82
|
+
| { method: 'resources/read'; uri: string }
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```ts type-equiv
|
|
86
|
+
/** One configured server's resource access, owned by its MCP connection plugin. */
|
|
87
|
+
interface McpResourceProvider {
|
|
88
|
+
/**
|
|
89
|
+
* Run an operation against one live connection generation.
|
|
90
|
+
* @param request - MCP resource method and parameters.
|
|
91
|
+
* @param exec - caller identity and cancellation for this invocation.
|
|
92
|
+
* @returns the protocol result as lossless JSON.
|
|
93
|
+
*/
|
|
94
|
+
request(request: McpResourceRequest, exec: ToolExecution): Promise<JsonValue>
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
-----
|
|
99
|
+
|
|
100
|
+
<a id="limits"></a>
|
|
101
|
+
## Limits
|
|
102
|
+
|
|
103
|
+
MCP prompt templates, human-input elicitation, task-based execution, and resource subscriptions are unsupported. Resource tools require a caller-visible configured server; binary resources remain programmatic data with text descriptions for the model. Servers without a tools capability connect with an empty tool set. Connection and discovery timeouts follow the SDK; the client has no separate settings for them.
|
|
104
|
+
|
|
105
|
+
-----
|
|
106
|
+
|
|
107
|
+
<a id="further-reading"></a>
|
|
108
|
+
## Further reading
|
|
109
|
+
|
|
110
|
+
- [MCP package group](../../packages/mcp/README.md) - package entry points.
|
|
111
|
+
- [MCP resources](../../packages/mcp/mcp-resources/README.md) - shared tools and resource-provider semantics.
|
|
112
|
+
- [Resource visibility decision](../../.agents/notes/implemented/feature/2026-09-13-mcp-resources-in-profiles.md) - shared profile mounting and visibility from configured servers.
|
|
113
|
+
- [Third-party memory servers](../user/guide/mcp-memory.md) - product configuration guide.
|
|
114
|
+
- [Protocol negotiation decision](../../.agents/notes/implemented/feature/2026-09-12-mcp-sdk-protocol-negotiation.md) - SDK ownership and compatibility decisions.
|
|
115
|
+
|
|
116
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
117
|
+
|
|
118
|
+
<a id="cordis-surface"></a>
|
|
119
|
+
|
|
120
|
+
## Cordis API
|
|
121
|
+
|
|
122
|
+
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).
|
|
123
|
+
|
|
124
|
+
<a id="ctxmcpresources--mcpresourceruntime"></a>
|
|
125
|
+
|
|
126
|
+
### `ctx.mcpResources` - `McpResourceRuntime`
|
|
127
|
+
|
|
128
|
+
Scoped resource access plus three tools shared by configured MCP servers.
|
|
129
|
+
|
|
130
|
+
```ts cordis-catalog
|
|
131
|
+
/**
|
|
132
|
+
* Register one server and expose resource tools while that scope has providers.
|
|
133
|
+
* @param server - configured server name, unique in this scope.
|
|
134
|
+
* @param provider - connection-owned resource operations.
|
|
135
|
+
* @returns the effect disposer for this exact registration.
|
|
136
|
+
*/
|
|
137
|
+
register(server: string, provider: McpResourceProvider): () => void
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Source: [`packages/mcp/mcp-resources/src/index.ts`](../../packages/mcp/mcp-resources/src/index.ts)
|
|
141
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/office-to-pdf.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Office to PDF
|
|
4
|
+
|
|
5
|
+
English | [中文](office-to-pdf.zh.md)
|
|
6
|
+
|
|
7
|
+
The [document package family](../../packages/document/README.md) converts Office files to PDFs on the Node Host. Consumers authorize source reads and own presentation; the shared provider owns conversion, bounded admission, and transient PDF reuse. This subsystem creates no model-facing tool or Session event.
|
|
8
|
+
|
|
9
|
+
## Ownership
|
|
10
|
+
|
|
11
|
+
| Owner | Responsibility |
|
|
12
|
+
|---|---|
|
|
13
|
+
| [office-to-pdf](../../packages/document/office-to-pdf/README.md) | `ctx.officeToPdf`: shared LibreOffice conversion, bounded admission, and PDF caching |
|
|
14
|
+
| [Web bundle](../../packages/bundle/web-app/README.md) | One configurable conversion provider shared by Host consumers |
|
|
15
|
+
| [Office preview Client](../../packages/client/ui-sidebar-documentpreview/README.md#office-preview) | Office extension selection, PDF reuse, and missing-font notices |
|
|
16
|
+
|
|
17
|
+
## Requests and results
|
|
18
|
+
|
|
19
|
+
[`OfficeToPdfRequest`](../../packages/document/office-to-pdf/src/types.ts) contains an already-authorized source key/version, optional stat size, a deferred `read(signal, maxBytes)` callback, foreground/background priority, and a `OfficeExtension`: `doc`, `docx`, `xls`, `xlsx`, `ppt`, or `pptx`. `OfficeToPdf.convert(request, signal?)` returns one complete PDF result. Cancellation follows the caller and provider lifetimes; validation, output, and engine failures reject with a classified `OfficeToPdfError`.
|
|
20
|
+
|
|
21
|
+
`OfficeToPdfPriority` is `foreground` for requested preview/QA and `background` for speculation. `OfficeSourceKey` brands the caller-owned authorized source locator. `OfficeToPdfGeneration` brands a provider lifetime, and `OfficeToPdfKey` brands its content identity; neither opaque value is parsed by consumers.
|
|
22
|
+
|
|
23
|
+
| Result field | Meaning |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `pdf` | Caller-owned `Uint8Array` containing the complete PDF |
|
|
26
|
+
| `missingFonts` | Requested document font families unavailable to this conversion |
|
|
27
|
+
| `cacheKey` | Opaque converter generation plus extension/source-content identity |
|
|
28
|
+
| `generation` | Provider lifetime; replacement invalidates cached PDF reuse |
|
|
29
|
+
|
|
30
|
+
The provider admits the deferred read before allocating source bytes, shares conversions by content identity, and removes its private scratch directory before returning. Returned PDF bytes remain valid after provider disposal. Source and PDF bytes do not enter Session storage. Consumers can use [Workspace Files](../../packages/api/workspace-files/README.md) for authorized bounded reads.
|
|
31
|
+
|
|
32
|
+
## Preview reads
|
|
33
|
+
|
|
34
|
+
`RenderedDocumentBytes` carries workspace file metadata, native PDF `data`, `missingFonts`, and `generation`; the original source identity accompanies the converted PDF.
|
|
35
|
+
|
|
36
|
+
The `officeToPdf.render` Remote method checks source authorization and versions through the Session's [Workspace Files](../../packages/api/workspace-files/README.md) service. After conversion admission, `fs.readBytes` supplies raw input within the reserved byte capacity; Office input limits govern this read. The binary Remote projects the PDF into a multipart attachment and restores an `ArrayBuffer`-backed `Uint8Array` on the Client. Source access failures pass through; size and engine failures expose a classified reason without diagnostics. Conversion does not activate an Agent or append events.
|
|
37
|
+
|
|
38
|
+
The `api/remotes` assembly mounts the conversion service's generated Remote descriptor. The shared Document Preview package registers Office formats with complete-byte loading and its existing PDF.js Worker. Each preview read rechecks renderer generation, source authorization, and version before sharing an in-flight conversion or cached PDF. Connection resets and plugin disposal cancel requests and clear cached bytes. Missing services show localized configuration guidance.
|
|
39
|
+
|
|
40
|
+
## Engine selection and limits
|
|
41
|
+
|
|
42
|
+
The external [`@deepseek-ai/libreoffice-kit`](https://github.com/deepseek-harness/libreoffice-kit) Node API selects its precompiled engines. The kit has an independent version and release workflow, defined by the [release ownership decision](../../.agents/notes/implemented/architecture/2026-09-14-independent-libreoffice-kit.md). Application builds install the published npm packages. Application packaging requires the target’s declared native engine, or Node WASM when the kit declares no native engine for that target. The [platform engine decision](../../.agents/notes/implemented/architecture/2026-09-15-platform-office-engines.md) defines installation and packaging. Invalid metadata, missing required assets, and conversion errors reject without switching engines. Conversion uses disk input and output paths on the Host, with no browser conversion engine or font RPC.
|
|
43
|
+
|
|
44
|
+
The [Host provider configuration](../../packages/document/office-to-pdf/README.md#use-this-package) owns concurrency, deadlines, input/output limits, archive limits, image resolution, and font access. Native/WASM implementation and asset distribution belong to the kit workspace. System LibreOffice discovery, runtime engine downloads, persistent PDF caching, and model-facing rendering are outside this provider.
|
|
45
|
+
|
|
46
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
47
|
+
|
|
48
|
+
<a id="cordis-surface"></a>
|
|
49
|
+
|
|
50
|
+
## Cordis API
|
|
51
|
+
|
|
52
|
+
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).
|
|
53
|
+
|
|
54
|
+
<a id="ctxofficetopdf--officetopdf"></a>
|
|
55
|
+
|
|
56
|
+
### `ctx.officeToPdf` - `OfficeToPdf`
|
|
57
|
+
|
|
58
|
+
A provider lifetime owns all converters, queued calls, and temporary files.
|
|
59
|
+
|
|
60
|
+
```ts cordis-catalog
|
|
61
|
+
/**
|
|
62
|
+
* Convert Office bytes without modifying the source or writing Session events.
|
|
63
|
+
* @param request - authorized metadata and deferred bounded source read.
|
|
64
|
+
* @param signal - caller cancellation; provider disposal also stops active work.
|
|
65
|
+
* @returns caller-owned PDF bytes after conversion and scratch cleanup settle; canceled readers reject independently.
|
|
66
|
+
* @throws {OfficeToPdfError} Invalid input, unusable output, or engine failure; cancellation rejects with its reason.
|
|
67
|
+
*/
|
|
68
|
+
convert(request: OfficeToPdfRequest, signal?: AbortSignal): Promise<OfficeToPdfResult>
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Read and convert one Office file using the Session's ordinary filesystem authorization.
|
|
72
|
+
* @param workspaceFileScope - Session header lookup shared with workspaceFiles.
|
|
73
|
+
* @param path - absolute or workspace-relative Office path.
|
|
74
|
+
* @param priority - foreground preview or speculative background work.
|
|
75
|
+
* @param signal - Remote cancellation; disposal also cancels outstanding reads and conversions.
|
|
76
|
+
* @returns complete PDF bytes with original source identity and missing font families.
|
|
77
|
+
*/
|
|
78
|
+
@Remote async render( workspaceFileScope: WorkspaceFileScope, path: string, priority: OfficeToPdfPriority, signal: AbortSignal, ): Promise<RenderedDocumentBytes>
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Read the current rendering generation before reusing a Client PDF.
|
|
82
|
+
* @param signal - Remote caller cancellation.
|
|
83
|
+
* @returns provider lifetime, replaced with rendering, font, or engine configuration.
|
|
84
|
+
*/
|
|
85
|
+
@Remote('generation') getGeneration(signal: AbortSignal): OfficeToPdfGeneration
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Source: [`packages/document/office-to-pdf/src/index.ts`](../../packages/document/office-to-pdf/src/index.ts)
|
|
89
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/otel.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# OTel reporting
|
|
4
|
+
|
|
5
|
+
English | [中文](otel.zh.md)
|
|
6
|
+
|
|
7
|
+
The [OTel plugin](../../packages/telemetry/otel/README.md) registers `ctx.otel`, a shared factory for independent ordinary-event and Session-log channels. It owns transport and SDK batching implementations. Business consumers inject the service, supply explicit transport/resource/scope options, and own each returned channel's shutdown.
|
|
8
|
+
|
|
9
|
+
UI feedback reaches the Session feedback services through their existing Remote APIs. Feedback recording authorizes the Session adapter's canonical-prefix capture and redaction before it reports through an OTel channel. Ordinary product consumers submit selected fields through the product adapter. The shared service has no automatic identity or capture policy, and channels never share queues or requests.
|
|
10
|
+
|
|
11
|
+
The [product adapter](../../packages/host/product-telemetry-otel/README.md) and [Session adapter](../../packages/session/session-telemetry-otel/README.md) retain their deployment configuration and disposal deadlines. Consumers must not reuse a channel after shutdown. Mounting only the OTel service allocates no provider or transport.
|
|
12
|
+
|
|
13
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
14
|
+
|
|
15
|
+
<a id="cordis-surface"></a>
|
|
16
|
+
|
|
17
|
+
## Cordis API
|
|
18
|
+
|
|
19
|
+
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).
|
|
20
|
+
|
|
21
|
+
<a id="ctxotel--otel"></a>
|
|
22
|
+
|
|
23
|
+
### `ctx.otel` - `OTel`
|
|
24
|
+
|
|
25
|
+
Shared transport provider. Mounting creates no queue, identity, or network connection.
|
|
26
|
+
|
|
27
|
+
```ts cordis-catalog
|
|
28
|
+
/**
|
|
29
|
+
* Create an independent ordinary-event channel with count-based batching.
|
|
30
|
+
* The injected consumer must drain it during its fiber disposal.
|
|
31
|
+
* @param options - transport, scope, resource, queue, and diagnostic settings selected by the consumer.
|
|
32
|
+
* @returns the caller-owned channel; no state is shared with other channels.
|
|
33
|
+
*/
|
|
34
|
+
createEventReporter(options: EventLogOptions): EventLogReporter
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Create an independent byte-bounded Session-log channel.
|
|
38
|
+
* Authorization and redaction precede reporting; the consumer owns shutdown and its outer deadline.
|
|
39
|
+
* @param options - transport, scope, resource, queue, and diagnostic settings selected by the consumer.
|
|
40
|
+
* @returns the caller-owned channel, preserving complete accepted events within the request byte ceiling.
|
|
41
|
+
*/
|
|
42
|
+
createSessionLogReporter(options: SessionLogOptions): SessionLogReporter
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Source: [`packages/telemetry/otel/src/index.ts`](../../packages/telemetry/otel/src/index.ts)
|
|
46
|
+
<!-- END GENERATED cordis-surface -->
|