@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,226 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/session-reference.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Session References
|
|
4
|
+
|
|
5
|
+
English | [中文](session-reference.zh.md)
|
|
6
|
+
|
|
7
|
+
Host-backed file discovery plus structured cross-session reference requests and prepared message contexts. The [file-reference contract](../../packages/context/file-reference) owns path-only completion records and grammar; the [session-reference contract](../../packages/context/session-reference) defines canonical URIs, current-surface projection, tag-safe JSON and byte retention, stable errors, and the untrusted model prompt. Host adapters use these types instead of passing their UI mention syntax into the agent core.
|
|
8
|
+
|
|
9
|
+
Sources: [`packages/context/file-reference/src/types.ts`](../../packages/context/file-reference/src/types.ts) · [`packages/context/session-reference/src/types.ts`](../../packages/context/session-reference/src/types.ts)
|
|
10
|
+
|
|
11
|
+
## File candidates
|
|
12
|
+
|
|
13
|
+
`FileReferenceCandidate` is the path-only discovery result. The addressed agent supplies the working-directory scope; providers decide ranking and namespace access without reading file contents.
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/** One path-only completion candidate inside the target session cwd. */
|
|
17
|
+
interface FileReferenceCandidate {
|
|
18
|
+
/** User-facing path accepted by normal prompts and filesystem tools. */
|
|
19
|
+
path: string
|
|
20
|
+
/** Directories keep completion open; files finish the mention. */
|
|
21
|
+
kind: 'file' | 'directory'
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Inputs and candidates
|
|
26
|
+
|
|
27
|
+
`SessionReferenceInput` is the host-independent selection. The id is authoritative; the label is display metadata carried into the snapshot.
|
|
28
|
+
|
|
29
|
+
```ts type-equiv
|
|
30
|
+
/** One source session selected by a host. */
|
|
31
|
+
interface SessionReferenceInput {
|
|
32
|
+
/** Opaque source session identity. */
|
|
33
|
+
sessionId: SessionId
|
|
34
|
+
/** Optional user-facing mention label. */
|
|
35
|
+
label?: string
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`SessionReferenceCandidate` is host-facing discovery output. Its `label` uses the latest Session title when present, while its optional display text prefers a subagent's durable creation label; filtering searches both alongside Session id and cwd, never transcript text. The Remote candidate's canonical mention uses the display text when present.
|
|
40
|
+
|
|
41
|
+
```ts type-equiv
|
|
42
|
+
/** One host-facing candidate from exact session metadata. */
|
|
43
|
+
interface SessionReferenceCandidate {
|
|
44
|
+
/** Opaque source session identity. */
|
|
45
|
+
sessionId: SessionId
|
|
46
|
+
/** Latest log-backed title, falling back to the opaque session id. */
|
|
47
|
+
label: string
|
|
48
|
+
/** Display and canonical-mention text, preferring a subagent's durable creation label over {@link label}. */
|
|
49
|
+
displayTitle?: string
|
|
50
|
+
/** Source session working directory, when recorded. */
|
|
51
|
+
cwd?: string
|
|
52
|
+
/**
|
|
53
|
+
* True when {@link SessionReferenceCandidate.cwd} is recorded and equals the
|
|
54
|
+
* requesting agent's. Hosts that only surface a distinguishing location
|
|
55
|
+
* read this instead of comparing paths they never received.
|
|
56
|
+
*/
|
|
57
|
+
sameWorkspace: boolean
|
|
58
|
+
/** Source session creation time in Unix epoch milliseconds. */
|
|
59
|
+
createdAt: number
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The `sessionReferenceResolver/candidates` Remote method serves the same discovery to browser consumers and attaches each candidate's canonical prompt mention.
|
|
64
|
+
|
|
65
|
+
```ts type-equiv
|
|
66
|
+
/** One discovery candidate carrying its canonical prompt mention. */
|
|
67
|
+
interface SessionReferenceMentionCandidate extends SessionReferenceCandidate {
|
|
68
|
+
/** Canonical `@[label](dsh-session:…)` mention serialized into the prompt draft. */
|
|
69
|
+
mention: string
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Prepared messages
|
|
74
|
+
|
|
75
|
+
Preparation preserves readable current-message content and returns at most one aggregated context. Its durable source records keep `capturedThroughSeq` as a coordinate in the referenced Session's original generation; they never reinterpret it as a seq in the containing Session. `capturedFormatVersion` records that generation, with absence meaning released format v0.
|
|
76
|
+
|
|
77
|
+
```ts type-equiv
|
|
78
|
+
/** Durable source session, cited event seqs, and snapshot facts for prepared cross-session context. */
|
|
79
|
+
interface SessionReferenceSource {
|
|
80
|
+
kind: 'session-reference'
|
|
81
|
+
/** Material lifted out of another session's log (`recall` context form). */
|
|
82
|
+
form: 'recall'
|
|
83
|
+
version: 1
|
|
84
|
+
references: {
|
|
85
|
+
sessionId: string
|
|
86
|
+
label: string
|
|
87
|
+
/** Source Session format generation; absence identifies version 0. */
|
|
88
|
+
capturedFormatVersion?: number
|
|
89
|
+
capturedThroughSeq: OptionalSessionSeq
|
|
90
|
+
compacted: boolean
|
|
91
|
+
originalMessages: number
|
|
92
|
+
retainedMessages: number
|
|
93
|
+
omittedMessages: number
|
|
94
|
+
omittedBytes: number
|
|
95
|
+
truncated: boolean
|
|
96
|
+
inputIndex: number
|
|
97
|
+
}[]
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
```ts type-equiv
|
|
102
|
+
/** Direct message content and optional referenced-session context. */
|
|
103
|
+
interface PreparedReferencedMessage {
|
|
104
|
+
/** Readable message content after host mention tokens are removed. */
|
|
105
|
+
content: ContentBlock[]
|
|
106
|
+
/** Aggregated untrusted snapshot, absent when the message has no references. */
|
|
107
|
+
additionalContext?: UserMessage
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Errors
|
|
112
|
+
|
|
113
|
+
`SessionReferenceError.code` separates invalid configuration or input, self-reference, count limits, source-read failure, budget failure, and cancellation. Host protocols map these codes to their own error envelopes without inspecting prompt bytes.
|
|
114
|
+
|
|
115
|
+
```ts type-equiv
|
|
116
|
+
/** Stable failure codes exposed to host adapters. */
|
|
117
|
+
type SessionReferenceErrorCode =
|
|
118
|
+
| 'SESSION_REFERENCE_INVALID_CONFIG'
|
|
119
|
+
| 'SESSION_REFERENCE_INVALID_REFERENCE'
|
|
120
|
+
| 'SESSION_REFERENCE_SELF_REFERENCE'
|
|
121
|
+
| 'SESSION_REFERENCE_TOO_MANY'
|
|
122
|
+
| 'SESSION_REFERENCE_READ_FAILED'
|
|
123
|
+
| 'SESSION_REFERENCE_BUDGET_EXCEEDED'
|
|
124
|
+
| 'SESSION_REFERENCE_CANCELLED'
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
128
|
+
|
|
129
|
+
<a id="cordis-surface"></a>
|
|
130
|
+
|
|
131
|
+
## Cordis API
|
|
132
|
+
|
|
133
|
+
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).
|
|
134
|
+
|
|
135
|
+
<a id="ctxfilereferences--filereferenceservice-abstract-seam"></a>
|
|
136
|
+
|
|
137
|
+
### `ctx.fileReferences` - `FileReferenceService` (abstract seam)
|
|
138
|
+
|
|
139
|
+
Host capability for cancellable file-reference discovery.
|
|
140
|
+
|
|
141
|
+
```ts cordis-catalog
|
|
142
|
+
/**
|
|
143
|
+
* List file and directory candidates for one agent's working directory.
|
|
144
|
+
* @param agent - target agent whose session cwd bounds discovery.
|
|
145
|
+
* @param query - path text following `@` or `@"`.
|
|
146
|
+
* @param signal - caller cancellation.
|
|
147
|
+
* @returns deterministic path-only candidates.
|
|
148
|
+
*/
|
|
149
|
+
abstract list( agent: Agent, query: string, signal: AbortSignal, ): Promise<FileReferenceCandidate[]>
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Types: [Agent](core.md)
|
|
153
|
+
|
|
154
|
+
Source: [`packages/context/file-reference/src/index.ts`](../../packages/context/file-reference/src/index.ts)
|
|
155
|
+
|
|
156
|
+
<a id="ctxsessionfilereferences--sessionfilereferences"></a>
|
|
157
|
+
|
|
158
|
+
### `ctx.sessionFileReferences` - `SessionFileReferences`
|
|
159
|
+
|
|
160
|
+
Host Remote adapter over the composed file-reference provider.
|
|
161
|
+
|
|
162
|
+
```ts cordis-catalog
|
|
163
|
+
/**
|
|
164
|
+
* List file and directory candidates for one Agent's working directory.
|
|
165
|
+
* @param agent - target Agent resolved from the Session identity on the wire.
|
|
166
|
+
* @param query - path text following `@` or `@"`.
|
|
167
|
+
* @param signal - caller cancellation.
|
|
168
|
+
* @returns deterministic path-only candidates from the composed provider.
|
|
169
|
+
*/
|
|
170
|
+
@Remote list( agent: Agent, query: string, signal: AbortSignal, ): Promise<FileReferenceCandidate[]>
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Types: [Agent](core.md)
|
|
174
|
+
|
|
175
|
+
Source: [`packages/api/session-controller/src/file-references.ts`](../../packages/api/session-controller/src/file-references.ts)
|
|
176
|
+
|
|
177
|
+
<a id="ctxsessionreferenceresolver--sessionreferenceresolver"></a>
|
|
178
|
+
|
|
179
|
+
### `ctx.sessionReferenceResolver` - `SessionReferenceResolver`
|
|
180
|
+
|
|
181
|
+
Exact-read consumer that prepares immutable cross-session message context.
|
|
182
|
+
|
|
183
|
+
```ts cordis-catalog
|
|
184
|
+
/**
|
|
185
|
+
* List reference candidates, ranked by working-directory affinity.
|
|
186
|
+
*
|
|
187
|
+
* Discovery runs at keystroke rate, so titles and subagent labels only ever
|
|
188
|
+
* come from projection reads; sessions without either fall back to their id.
|
|
189
|
+
* @param agent - target agent; self is excluded and its cwd drives ranking.
|
|
190
|
+
* @param query - optional case-insensitive session-id/cwd/title/display-title substring.
|
|
191
|
+
* @param limit - optional positive result cap.
|
|
192
|
+
* @param signal - optional cancellation boundary for host autocomplete teardown.
|
|
193
|
+
* @returns candidates with canonical mention labels and presentation titles.
|
|
194
|
+
*/
|
|
195
|
+
async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Remote face of {@link listCandidates}: the configured candidate limit
|
|
199
|
+
* applies, and every candidate carries the canonical mention a host inserts
|
|
200
|
+
* into the prompt draft.
|
|
201
|
+
* @param agent - target agent; self is excluded and its cwd drives ranking.
|
|
202
|
+
* @param query - optional case-insensitive session-id/cwd/title substring.
|
|
203
|
+
* @param signal - caller cancellation.
|
|
204
|
+
* @returns mention-carrying candidates in rank order.
|
|
205
|
+
*/
|
|
206
|
+
@Remote('candidates') async remoteExportCandidates( agent: Agent, query: string, signal: AbortSignal, ): Promise<SessionReferenceMentionCandidate[]>
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Snapshot all references for one accepted direct message and return one aggregated durable context.
|
|
210
|
+
* Automatic budgets use the last assembled route, or agent options before any assembly.
|
|
211
|
+
* Missing model capacity or adapter uses 64 KiB; other metadata lookup failures and cancellation reject preparation.
|
|
212
|
+
* Truncated previews include omission facts and a full-snapshot spill locator, or an explicit unavailable notice.
|
|
213
|
+
* Cancellation prevents context publication, including when storage completes after cancellation.
|
|
214
|
+
* @param agent - target agent; references to it are rejected.
|
|
215
|
+
* @param content - already host-normalized readable message content.
|
|
216
|
+
* @param references - structured source sessions in mention order.
|
|
217
|
+
* @param signal - optional cancellation boundary for the active turn.
|
|
218
|
+
* @returns detached content and optional referenced-session context.
|
|
219
|
+
*/
|
|
220
|
+
async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Types: [Agent](core.md) · [ContentBlock](llm-streaming.md)
|
|
224
|
+
|
|
225
|
+
Source: [`packages/context/session-reference/src/index.ts`](../../packages/context/session-reference/src/index.ts)
|
|
226
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/session-telemetry.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# SessionTelemetryBackend
|
|
4
|
+
|
|
5
|
+
English | [中文](session-telemetry.zh.md)
|
|
6
|
+
|
|
7
|
+
The [capture service](../../packages/session/session-telemetry/README.md) owns canonical-event capture, redaction, and handoff cursors. The [feedback backend](../../packages/session/session-telemetry-otel/README.md) authorizes Session prefixes and owns their independent queue, per-request scheduling, and 4,000,000-byte ceiling. No reporting data reaches model requests.
|
|
8
|
+
|
|
9
|
+
Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
|
|
10
|
+
|
|
11
|
+
## The logical record
|
|
12
|
+
|
|
13
|
+
```ts type-equiv
|
|
14
|
+
/**
|
|
15
|
+
* Severity of a telemetry record, pre-mapped at capture so a receiver can
|
|
16
|
+
* alert with zero configuration: `error` for events whose own outcome flag
|
|
17
|
+
* says so (the tool message's `isError`, `turn/end` error reasons) and for
|
|
18
|
+
* `agent-error` operational records. Captured events otherwise default to
|
|
19
|
+
* `info`; `warn` remains available to `session-telemetry/record` policies and
|
|
20
|
+
* backends.
|
|
21
|
+
*/
|
|
22
|
+
type SessionTelemetrySeverity = 'info' | 'warn' | 'error'
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```ts type-equiv
|
|
26
|
+
/**
|
|
27
|
+
* One logical record handed to a backend - the capture contract's whole outbound
|
|
28
|
+
* vocabulary. Ledger records mirror session-log events one-to-one;
|
|
29
|
+
* operational records (`channel: 'ops'`) carry the two signals with no log
|
|
30
|
+
* home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
|
|
31
|
+
* identity so they can never be mistaken for ledger rows.
|
|
32
|
+
*/
|
|
33
|
+
interface SessionTelemetryRecord {
|
|
34
|
+
/** Canonical envelope without data; body carries the separately redacted payload. Absent for operational records. */
|
|
35
|
+
sourceEvent?: { sessionId: SessionId; envelope: Omit<SessionEvent, 'data'> }
|
|
36
|
+
/** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
|
|
37
|
+
channel: 'ledger' | 'ops'
|
|
38
|
+
/** Unix epoch milliseconds - the source event's append time for ledger records, the emission time for ops records. */
|
|
39
|
+
time: number
|
|
40
|
+
/** Pre-mapped alerting severity; see {@link SessionTelemetrySeverity}. */
|
|
41
|
+
severity: SessionTelemetrySeverity
|
|
42
|
+
/**
|
|
43
|
+
* Identity attributes, deliberately minimal: ledger records carry
|
|
44
|
+
* `session.id`, `session.format_version`, `event.type`, `event.seq`, plus optional
|
|
45
|
+
* `session.cwd` / `session.parent_id`; a seeded Session also carries
|
|
46
|
+
* `session.seed_length` from its exact inherited event count;
|
|
47
|
+
* ops records carry `telemetry.op`, `session.id`, and (for `agent-error`)
|
|
48
|
+
* `agent.id`, `turn`, `step`, `error.name`. Anything recoverable from the
|
|
49
|
+
* body is intentionally NOT duplicated here.
|
|
50
|
+
*/
|
|
51
|
+
attributes: Record<string, string | number>
|
|
52
|
+
/**
|
|
53
|
+
* The complete payload: a deep copy of the session event's `data` for
|
|
54
|
+
* ledger records (JSON-serializable by `Session.append`'s own
|
|
55
|
+
* validation), or the op payload for ops records. Never mutated after
|
|
56
|
+
* handoff.
|
|
57
|
+
*/
|
|
58
|
+
body: unknown
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Every canonical [session event](session.md), including each `assistant/message` or `assistant/attempt` with its complete compact stream and every plugin-merged type the seam never heard of, passes through whole as one ordered ledger record. Process-local `agent/assistant-stream` frames do not enter this durable feed. A new fork starts at its child-owned suffix, including the inherited marker and fork closers; restored Sessions start after their stored prefix, including restored forks. The backend can select `includeHistory` to include the complete prefix; re-adopting the same object resumes after its handoff cursor. Delivery is best-effort: the cursor marks handed-off, not delivered, and records can be lost (crash, reload window) or duplicated (new-object replay, SDK retries), so receivers dedupe ledger records on `(session.id, session.format_version, event.seq)`; ops records deliberately omit that identity - they are signals to alert on, not entries to sum, and tolerate duplicates instead.
|
|
63
|
+
|
|
64
|
+
## The sharing disclosure
|
|
65
|
+
|
|
66
|
+
Every backend exposes its deployment-selected mode through the required abstract `sharing` member on `ctx.sessionTelemetry` ([Service Definition README](../../packages/session/session-telemetry/README.md#the-sharing-disclosure)). This is neither a per-Session admission decision nor a delivery receipt. The `/feedback` acknowledgement does not consult it.
|
|
67
|
+
|
|
68
|
+
```ts type-equiv
|
|
69
|
+
/**
|
|
70
|
+
* Deployment-selected session-sharing mode, not confirmation of SDK delivery.
|
|
71
|
+
*/
|
|
72
|
+
type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Capture policy
|
|
76
|
+
|
|
77
|
+
```ts type-equiv
|
|
78
|
+
/** Whether capture follows live events or reads the canonical log only when requested. */
|
|
79
|
+
type SessionTelemetryCapture = 'live' | 'on-demand'
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
```ts type-equiv
|
|
83
|
+
/** Backend-selected capture mode and history policy. */
|
|
84
|
+
interface SessionTelemetryCaptureOptions {
|
|
85
|
+
/** Follow live events, or wait for explicit capture; defaults to live. */
|
|
86
|
+
capture?: SessionTelemetryCapture
|
|
87
|
+
/** Include inherited fork history and stored history from earlier lifecycles; defaults to false. */
|
|
88
|
+
includeHistory?: boolean
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`includeHistory` permits stored and inherited records but does not itself authorize capture. The [OTel backend](../../packages/session/session-telemetry-otel/README.md) uses on-demand capture and requires new own explicit feedback; it releases only the complete prefix through that feedback, for every provider.
|
|
93
|
+
|
|
94
|
+
## The backend contract
|
|
95
|
+
|
|
96
|
+
```ts type-equiv
|
|
97
|
+
/**
|
|
98
|
+
* The minimum backend contract the coordinator requires. {@link SessionTelemetryBackend} is
|
|
99
|
+
* its service-registered form; tests compose the coordinator with a bare
|
|
100
|
+
* implementation of this interface.
|
|
101
|
+
*/
|
|
102
|
+
interface SessionTelemetrySink {
|
|
103
|
+
/**
|
|
104
|
+
* Hand one record to the backend's pipeline. MUST be a non-blocking
|
|
105
|
+
* enqueue - the coordinator calls this synchronously from the
|
|
106
|
+
* `session/event` hot path or an explicit canonical-log capture, so anything
|
|
107
|
+
* slower than a queue push would tax the agent loop or feedback handling.
|
|
108
|
+
* Errors thrown here are contained by the coordinator and logged; they
|
|
109
|
+
* never reach the loop.
|
|
110
|
+
* @param record - the logical record to report; owned by the backend after the call.
|
|
111
|
+
*/
|
|
112
|
+
emit(record: SessionTelemetryRecord): void
|
|
113
|
+
/**
|
|
114
|
+
* Optional hint that a turn ended. A backend may forward it to its SDK's
|
|
115
|
+
* flush so records are exported after each turn. Called
|
|
116
|
+
* fire-and-forget; implementations must not block and must not throw
|
|
117
|
+
* meaningfully (the coordinator contains exceptions). Most backends should
|
|
118
|
+
* leave this unimplemented and let their SDK's own batching cadence govern
|
|
119
|
+
* export timing: a backend that does implement it owns the interaction
|
|
120
|
+
* between its concurrent flushes and {@link shutdown}'s drain (the OTel
|
|
121
|
+
* backend leaves it unimplemented for exactly that hazard - see the
|
|
122
|
+
* revival Agent Note).
|
|
123
|
+
*/
|
|
124
|
+
flush?(): void
|
|
125
|
+
/**
|
|
126
|
+
* Forward the fiber's disposal to the SDK: flush whatever is queued and
|
|
127
|
+
* reach quiescence, per the SDK's own shutdown contract. Everything
|
|
128
|
+
* emitted before this call must still be delivered - including records
|
|
129
|
+
* enqueued while a {@link flush} hint is in flight, so a backend whose SDK
|
|
130
|
+
* guards against concurrent flushes orders behind the outstanding one (the
|
|
131
|
+
* coordinator emits its dispose-time `shutdown` markers immediately before
|
|
132
|
+
* calling this). Awaited by the coordinator's dispose; a rejection is
|
|
133
|
+
* logged as a warning and never fails application teardown.
|
|
134
|
+
* The coordinator captures dispose-time shutdown markers immediately before
|
|
135
|
+
* this call for live capture; on-demand capture creates no ops records.
|
|
136
|
+
* @returns resolves when the backend's pipeline has quiesced.
|
|
137
|
+
*/
|
|
138
|
+
shutdown(): Promise<void>
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
`SessionTelemetryBackend` (`ctx.sessionTelemetry`, [signatures](#ctxsessiontelemetry--sessiontelemetrybackend-abstract-seam)) is the contract's loadable form - one implementation per context, duplicate load throws - and a backend composes the seam's `SessionTelemetryCoordinator` in its constructor to install the capture side.
|
|
143
|
+
|
|
144
|
+
## The redact waterfall: `session-telemetry/record`
|
|
145
|
+
|
|
146
|
+
Every record passes the `session-telemetry/record` [waterfall](../cordis-primer.md#cordis-waterfall-semantics) between the canonical-event copy and `emit()` ([event entry](#session-telemetryrecord--waterfall)). The seam ships NO rules of its own: with no listener mounted, records reach the backend exactly as captured, so exported data is precisely as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath; a throwing listener withholds that one record fail-closed inside the coordinator's containment. Redaction applies to the exported copy only - the canonical session log is never rewritten.
|
|
147
|
+
|
|
148
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
149
|
+
|
|
150
|
+
<a id="cordis-surface"></a>
|
|
151
|
+
|
|
152
|
+
## Cordis API
|
|
153
|
+
|
|
154
|
+
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).
|
|
155
|
+
|
|
156
|
+
<a id="ctxsessiontelemetry--sessiontelemetrybackend-abstract-seam"></a>
|
|
157
|
+
|
|
158
|
+
### `ctx.sessionTelemetry` - `SessionTelemetryBackend` (abstract seam)
|
|
159
|
+
|
|
160
|
+
Loadable form of the backend contract: one implementation per context - the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a SessionTelemetryCoordinator in its constructor to install the capture side.
|
|
161
|
+
|
|
162
|
+
```ts cordis-catalog
|
|
163
|
+
/**
|
|
164
|
+
* See {@link SessionTelemetrySink.emit} - that declaration is the contract's one home.
|
|
165
|
+
* @param record - the logical record to report; owned by the backend after the call.
|
|
166
|
+
*/
|
|
167
|
+
abstract emit(record: SessionTelemetryRecord): void
|
|
168
|
+
|
|
169
|
+
/** See {@link SessionTelemetrySink.flush}. */
|
|
170
|
+
flush?(): void
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* See {@link SessionTelemetrySink.shutdown}.
|
|
174
|
+
* @returns resolves when the backend's pipeline has quiesced.
|
|
175
|
+
*/
|
|
176
|
+
abstract shutdown(): Promise<void>
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
|
|
180
|
+
|
|
181
|
+
<a id="session-telemetry-events"></a>
|
|
182
|
+
|
|
183
|
+
### `session-telemetry/*` events
|
|
184
|
+
|
|
185
|
+
<a id="session-telemetryrecord--waterfall"></a>
|
|
186
|
+
|
|
187
|
+
#### `session-telemetry/record` - waterfall
|
|
188
|
+
|
|
189
|
+
Transform one outbound record before it reaches the backend. This waterfall is the Service Definition's redaction extension point. It ships NO rules of its own: the innermost `next()` passes the record through unchanged, and with no listener mounted records reach the backend as captured, so exported data is exactly as clean as the rules a deployment mounts. Listeners stack by transforming `next()`'s return value; returning without `next()` replaces everything beneath. Dispatched synchronously on the capture hot path inside the coordinator's containment: a throwing listener withholds that one record (fail-closed) and never reaches the agent loop. Live capture dispatches at append time; on-demand capture dispatches while reading the canonical log. Redaction applies to the exported copy only; the canonical session log is never rewritten.
|
|
190
|
+
|
|
191
|
+
```ts cordis-catalog
|
|
192
|
+
/**
|
|
193
|
+
* Transform one outbound record before it reaches the backend. This
|
|
194
|
+
* waterfall is the Service Definition's redaction extension point. It ships NO rules
|
|
195
|
+
* of its own: the
|
|
196
|
+
* innermost `next()` passes the record through unchanged, and with no
|
|
197
|
+
* listener mounted records reach the backend as captured, so exported
|
|
198
|
+
* data is exactly as clean as the rules a deployment mounts. Listeners
|
|
199
|
+
* stack by transforming `next()`'s return value; returning without
|
|
200
|
+
* `next()` replaces everything beneath. Dispatched synchronously on the
|
|
201
|
+
* capture hot path inside the coordinator's containment: a throwing
|
|
202
|
+
* listener withholds that one record (fail-closed) and never reaches the
|
|
203
|
+
* agent loop. Live capture dispatches at append time; on-demand capture
|
|
204
|
+
* dispatches while reading the canonical log. Redaction applies to the
|
|
205
|
+
* exported copy only; the canonical session log is never rewritten.
|
|
206
|
+
* @param record - the candidate record, already the coordinator's own deep
|
|
207
|
+
* copy; listeners return a (possibly new) record and must not mutate it.
|
|
208
|
+
* @mode waterfall
|
|
209
|
+
*/
|
|
210
|
+
'session-telemetry/record'(record: SessionTelemetryRecord, next: () => SessionTelemetryRecord): SessionTelemetryRecord
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)
|
|
214
|
+
<!-- END GENERATED cordis-surface -->
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
<!-- Synced from deepseek-harness:docs/subsystems/session-title.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Session Titles
|
|
4
|
+
|
|
5
|
+
English | [中文](session-title.zh.md)
|
|
6
|
+
|
|
7
|
+
Durable latest-wins title state and the optional asynchronous provider vocabulary owned by [`@deepseek-ai/dsh-session-title`](../../packages/session/session-title). The shared LLM helper owns the exact auxiliary request record. Package READMEs own timing, fallback, failure, and fork behavior; the generated [persistence catalog](../persistence-catalog.md) owns the complete event declarations.
|
|
8
|
+
|
|
9
|
+
Sources: [`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts), [`packages/session/session-title-llm/src/index.ts`](../../packages/session/session-title-llm/src/index.ts)
|
|
10
|
+
|
|
11
|
+
## Durable title state
|
|
12
|
+
|
|
13
|
+
`SessionTitleProviderId` is recorded for provider-produced revisions. `SessionTitleEventData` lists the exact human-message seqs used for the title, while `SessionTitleSnapshot` adds the durable event envelope facts returned by `ctx.sessionTitle.get()` and `foldSessionTitle()`. The `title` projection keeps its version-1 state and client view as only the title string or `null`, so existing persisted cache rows remain readable.
|
|
14
|
+
|
|
15
|
+
```ts type-equiv
|
|
16
|
+
/** Identifies one session-title provider registration. */
|
|
17
|
+
type SessionTitleProviderId = Branded<'SessionTitleProviderId'>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```ts type-equiv
|
|
21
|
+
/** Exact auxiliary model route that produced a title. */
|
|
22
|
+
interface SessionTitleModelIdentity {
|
|
23
|
+
/** Registered LLM provider route. */
|
|
24
|
+
readonly provider: string
|
|
25
|
+
/** Provider model id. */
|
|
26
|
+
readonly model: string
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```ts type-equiv
|
|
31
|
+
/** Durable ownership record for an accepted session title. */
|
|
32
|
+
type SessionTitleSource =
|
|
33
|
+
| { readonly kind: 'fallback' }
|
|
34
|
+
| {
|
|
35
|
+
readonly kind: 'provider'
|
|
36
|
+
readonly provider: SessionTitleProviderId
|
|
37
|
+
readonly model?: SessionTitleModelIdentity
|
|
38
|
+
}
|
|
39
|
+
| {
|
|
40
|
+
/** Explicit user rename: pins the title - automatic generation stops scheduling. */
|
|
41
|
+
readonly kind: 'user'
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```ts type-equiv
|
|
46
|
+
/** Payload of the log-only `session/title` event. */
|
|
47
|
+
interface SessionTitleEventData {
|
|
48
|
+
/** Normalized non-empty title text. */
|
|
49
|
+
readonly title: string
|
|
50
|
+
/** Exact human `user/message` seqs used to derive this title; empty for an explicit user rename. */
|
|
51
|
+
readonly messageSeqs: SessionSeq[]
|
|
52
|
+
/** Whether the built-in fallback, a registered provider, or the user supplied the title. */
|
|
53
|
+
readonly source: SessionTitleSource
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```ts type-equiv
|
|
58
|
+
/** Latest folded title plus the title event's durable envelope facts. */
|
|
59
|
+
interface SessionTitleSnapshot extends SessionTitleEventData {
|
|
60
|
+
/** Seq of the latest `session/title` event. */
|
|
61
|
+
readonly eventSeq: SessionSeq
|
|
62
|
+
/** Timestamp of the latest `session/title` event. */
|
|
63
|
+
readonly updatedAt: number
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Auxiliary request record
|
|
68
|
+
|
|
69
|
+
The shared LLM helper records each validated, dispatchable title request before calling the model. The payload reproduces the model-visible system and message input, routing, output limit, provider ownership, and source-message attribution even when generation later fails.
|
|
70
|
+
|
|
71
|
+
```ts type-equiv
|
|
72
|
+
/** Exact model-visible request recorded before one auxiliary title dispatch. */
|
|
73
|
+
interface SessionTitleLlmRequestEventData {
|
|
74
|
+
/** Registered title-provider identity responsible for the request. */
|
|
75
|
+
readonly titleProvider: SessionTitleProviderId
|
|
76
|
+
/** Exact human `user/message` seqs represented in `messages`. */
|
|
77
|
+
readonly messageSeqs: SessionSeq[]
|
|
78
|
+
/** Exact auxiliary LLM route. */
|
|
79
|
+
readonly route: SessionTitleModelIdentity
|
|
80
|
+
/** Exact auxiliary system prompt. */
|
|
81
|
+
readonly system: string
|
|
82
|
+
/** Exact auxiliary message list. */
|
|
83
|
+
readonly messages: Message[]
|
|
84
|
+
/** Exact auxiliary output-token cap. */
|
|
85
|
+
readonly maxTokens: number
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Provider input and output
|
|
90
|
+
|
|
91
|
+
The service snapshots eligible messages through one revision. A provider returns only seqs from that request; service-owned acceptance verifies ordering, normalizes the title, enforces the byte limit, and appends the title with its source-message seqs and source kind.
|
|
92
|
+
|
|
93
|
+
```ts type-equiv
|
|
94
|
+
/** One eligible human text message exposed to title providers. */
|
|
95
|
+
interface SessionTitleUserMessage {
|
|
96
|
+
/** Source `user/message` event seq. */
|
|
97
|
+
readonly seq: SessionSeq
|
|
98
|
+
/** Exact concatenated text-block content. */
|
|
99
|
+
readonly text: string
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```ts type-equiv
|
|
104
|
+
/** Automatic generation cadence owned by a registered provider. */
|
|
105
|
+
type SessionTitleAutomaticMode = 'first-prompt' | 'all-prompts'
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```ts type-equiv
|
|
109
|
+
/** Immutable input supplied to one title-provider call. */
|
|
110
|
+
interface SessionTitleProviderRequest {
|
|
111
|
+
/** Live session being titled. */
|
|
112
|
+
readonly session: Session
|
|
113
|
+
/** All eligible human messages through this generation revision. */
|
|
114
|
+
readonly messages: readonly SessionTitleUserMessage[]
|
|
115
|
+
/** Exact current logged main-request route, when one has been recorded. */
|
|
116
|
+
readonly route?: SessionTitleModelIdentity
|
|
117
|
+
/** Cancellation for supersession, disposal, timeout composition, or the explicit caller. */
|
|
118
|
+
readonly signal: AbortSignal
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
```ts type-equiv
|
|
123
|
+
/** Provider output before service-owned normalization and log acceptance. */
|
|
124
|
+
interface SessionTitleProviderResult {
|
|
125
|
+
/** Proposed title text. */
|
|
126
|
+
readonly title: string
|
|
127
|
+
/** Exact seqs from `request.messages` used by this result. */
|
|
128
|
+
readonly messageSeqs: readonly SessionSeq[]
|
|
129
|
+
/** Auxiliary LLM route, when generation used a model. */
|
|
130
|
+
readonly model?: SessionTitleModelIdentity
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
```ts type-equiv
|
|
135
|
+
/** One optional asynchronous title implementation registered with the service. */
|
|
136
|
+
interface SessionTitleProvider {
|
|
137
|
+
/** Stable id of the provider recorded with the title. */
|
|
138
|
+
readonly id: SessionTitleProviderId
|
|
139
|
+
/** When new human prompts start automatic generation. */
|
|
140
|
+
readonly automatic: SessionTitleAutomaticMode
|
|
141
|
+
/**
|
|
142
|
+
* Produce one title revision.
|
|
143
|
+
* @param request - message snapshot, current route, session, and cancellation.
|
|
144
|
+
* @returns proposed title plus exact input seqs and the optional provider/model route used to generate it.
|
|
145
|
+
*/
|
|
146
|
+
generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
|
|
151
|
+
|
|
152
|
+
<a id="cordis-surface"></a>
|
|
153
|
+
|
|
154
|
+
## Cordis API
|
|
155
|
+
|
|
156
|
+
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).
|
|
157
|
+
|
|
158
|
+
<a id="ctxsessiontitle--sessiontitleservice"></a>
|
|
159
|
+
|
|
160
|
+
### `ctx.sessionTitle` - `SessionTitleService`
|
|
161
|
+
|
|
162
|
+
Log-backed title fold plus asynchronous fallback generation.
|
|
163
|
+
|
|
164
|
+
```ts cordis-catalog
|
|
165
|
+
/**
|
|
166
|
+
* Read the latest folded title from one live or replayed session.
|
|
167
|
+
* @param session - session whose log is the title source of truth.
|
|
168
|
+
* @returns latest title snapshot, or `undefined` before eligible input.
|
|
169
|
+
*/
|
|
170
|
+
get(session: Session): SessionTitleSnapshot | undefined
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* Accept an explicit user title. Appends a `session/title` event with the
|
|
174
|
+
* `user` source, which pins the title: in-flight automatic generation is
|
|
175
|
+
* superseded and later user messages schedule none (an explicit
|
|
176
|
+
* {@link SessionTitleService.refresh} remains the deliberate unpin).
|
|
177
|
+
* @param session - exact live session to rename.
|
|
178
|
+
* @param title - raw user input; normalized before acceptance.
|
|
179
|
+
* @returns the accepted title snapshot.
|
|
180
|
+
* @throws {SessionTitleInvalidError} when the title normalizes to empty.
|
|
181
|
+
* @throws {Error} when the session is not live or the service is disposed.
|
|
182
|
+
*/
|
|
183
|
+
rename(session: Session, title: string): SessionTitleSnapshot
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* Explicitly retry the registered provider, or materialize the built-in
|
|
187
|
+
* fallback when no provider is registered.
|
|
188
|
+
* @param session - exact live session to refresh.
|
|
189
|
+
* @param signal - optional caller cancellation.
|
|
190
|
+
* @returns latest accepted title, or `undefined` when no eligible text exists.
|
|
191
|
+
*/
|
|
192
|
+
async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* Register the sole optional title provider. Disposal aborts its pending and
|
|
196
|
+
* active work before another provider may register.
|
|
197
|
+
* @param provider - provider identity, cadence, and generation function.
|
|
198
|
+
* @returns exact Cordis effect disposer, which settles after active calls quiesce.
|
|
199
|
+
*/
|
|
200
|
+
register(provider: SessionTitleProvider): () => Promise<void>
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Types: [Session](session.md)
|
|
204
|
+
|
|
205
|
+
Source: [`packages/session/session-title/src/index.ts`](../../packages/session/session-title/src/index.ts)
|
|
206
|
+
<!-- END GENERATED cordis-surface -->
|