@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.
Files changed (284) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +12 -2
  3. package/docs/README.md +160 -0
  4. package/docs/delivery/local-live.md +113 -0
  5. package/docs/delivery/marketplace.md +16 -0
  6. package/docs/docs.json +2836 -0
  7. package/docs/extending/agent-preset.md +37 -0
  8. package/docs/extending/chat-command.md +28 -0
  9. package/docs/extending/client-slot.md +135 -0
  10. package/docs/extending/config-schema.md +7 -0
  11. package/docs/extending/cordis-core.md +63 -0
  12. package/docs/extending/desktop-app.md +53 -0
  13. package/docs/extending/desktop-main.md +25 -0
  14. package/docs/extending/event-hook.md +14 -0
  15. package/docs/extending/host-route.md +33 -0
  16. package/docs/extending/llm-adapter.md +38 -0
  17. package/docs/extending/packaging.md +53 -0
  18. package/docs/extending/prompt-contribution.md +9 -0
  19. package/docs/extending/service.md +13 -0
  20. package/docs/extending/skill-provider.md +9 -0
  21. package/docs/extending/state-and-persistence.md +71 -0
  22. package/docs/extending/three-role-capability.md +33 -0
  23. package/docs/extending/tool-plugin.md +24 -0
  24. package/docs/extending/tui-command.md +8 -0
  25. package/docs/extending/tui-components.md +61 -0
  26. package/docs/extending/ui-branding.md +43 -0
  27. package/docs/extending/ui-components.md +56 -0
  28. package/docs/extending/ui-customization.md +41 -0
  29. package/docs/extending/ui-library.md +66 -0
  30. package/docs/extending/ui-theme.md +55 -0
  31. package/docs/extending/workspace-tab.md +50 -0
  32. package/docs/maps/events.md +108 -0
  33. package/docs/maps/mount-points.md +154 -0
  34. package/docs/maps/slot-contracts.md +3376 -0
  35. package/docs/maps/taxonomy.md +306 -0
  36. package/docs/maps/theme-tokens.md +115 -0
  37. package/docs/maps/ui-components.md +26 -0
  38. package/docs/reference/cookbook/adding-a-package.md +174 -0
  39. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  40. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  41. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  42. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  43. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  44. package/docs/reference/cordis-api/context.md +366 -0
  45. package/docs/reference/cordis-api/events.md +209 -0
  46. package/docs/reference/cordis-api/fiber.md +377 -0
  47. package/docs/reference/cordis-api/inherited.md +40 -0
  48. package/docs/reference/cordis-api/registry.md +154 -0
  49. package/docs/reference/cordis-api/service.md +104 -0
  50. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  51. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  52. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  53. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  54. package/docs/reference/harness/agent-lifecycle.md +93 -0
  55. package/docs/reference/harness/architecture.md +168 -0
  56. package/docs/reference/harness/capability-seams.md +675 -0
  57. package/docs/reference/harness/config-catalog.md +4523 -0
  58. package/docs/reference/harness/cordis-primer.md +47 -0
  59. package/docs/reference/harness/defensive-patterns.md +35 -0
  60. package/docs/reference/harness/event-producer-consumer.md +111 -0
  61. package/docs/reference/harness/glossary.md +47 -0
  62. package/docs/reference/harness/tool-catalog.md +2721 -0
  63. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  64. package/docs/reference/subsystems/README.md +75 -0
  65. package/docs/reference/subsystems/agent-team.md +233 -0
  66. package/docs/reference/subsystems/approval.md +172 -0
  67. package/docs/reference/subsystems/attachment.md +363 -0
  68. package/docs/reference/subsystems/boot.md +324 -0
  69. package/docs/reference/subsystems/browser-use.md +69 -0
  70. package/docs/reference/subsystems/client-modules.md +186 -0
  71. package/docs/reference/subsystems/client-resources.md +94 -0
  72. package/docs/reference/subsystems/commands.md +225 -0
  73. package/docs/reference/subsystems/compaction.md +286 -0
  74. package/docs/reference/subsystems/computer-use.md +58 -0
  75. package/docs/reference/subsystems/conversation.md +287 -0
  76. package/docs/reference/subsystems/core.md +1107 -0
  77. package/docs/reference/subsystems/credentials.md +497 -0
  78. package/docs/reference/subsystems/deliverables.md +180 -0
  79. package/docs/reference/subsystems/extensions.md +386 -0
  80. package/docs/reference/subsystems/feedback.md +402 -0
  81. package/docs/reference/subsystems/filesystem.md +532 -0
  82. package/docs/reference/subsystems/goal.md +315 -0
  83. package/docs/reference/subsystems/invariants.md +90 -0
  84. package/docs/reference/subsystems/jobs.md +501 -0
  85. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  86. package/docs/reference/subsystems/lsp.md +204 -0
  87. package/docs/reference/subsystems/mcp.md +141 -0
  88. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  89. package/docs/reference/subsystems/otel.md +46 -0
  90. package/docs/reference/subsystems/permission-presets.md +169 -0
  91. package/docs/reference/subsystems/persistence.md +418 -0
  92. package/docs/reference/subsystems/plan.md +89 -0
  93. package/docs/reference/subsystems/product-telemetry.md +81 -0
  94. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  95. package/docs/reference/subsystems/sandbox.md +223 -0
  96. package/docs/reference/subsystems/schedule.md +545 -0
  97. package/docs/reference/subsystems/scope.md +61 -0
  98. package/docs/reference/subsystems/session-projection.md +358 -0
  99. package/docs/reference/subsystems/session-query.md +511 -0
  100. package/docs/reference/subsystems/session-reference.md +226 -0
  101. package/docs/reference/subsystems/session-telemetry.md +214 -0
  102. package/docs/reference/subsystems/session-title.md +206 -0
  103. package/docs/reference/subsystems/session.md +1300 -0
  104. package/docs/reference/subsystems/settings.md +157 -0
  105. package/docs/reference/subsystems/shell.md +316 -0
  106. package/docs/reference/subsystems/sidebar-right.md +160 -0
  107. package/docs/reference/subsystems/skills.md +354 -0
  108. package/docs/reference/subsystems/slots.md +201 -0
  109. package/docs/reference/subsystems/spill.md +126 -0
  110. package/docs/reference/subsystems/ssh.md +137 -0
  111. package/docs/reference/subsystems/storage.md +262 -0
  112. package/docs/reference/subsystems/subagent.md +762 -0
  113. package/docs/reference/subsystems/subprocess.md +323 -0
  114. package/docs/reference/subsystems/system-prompt.md +226 -0
  115. package/docs/reference/subsystems/terminal.md +186 -0
  116. package/docs/reference/subsystems/todo.md +34 -0
  117. package/docs/reference/subsystems/token-meter.md +108 -0
  118. package/docs/reference/subsystems/tools.md +749 -0
  119. package/docs/reference/subsystems/typert.md +489 -0
  120. package/docs/reference/subsystems/user-questions.md +309 -0
  121. package/docs/reference/subsystems/voice-input.md +166 -0
  122. package/docs/reference/subsystems/web-client.md +102 -0
  123. package/docs/reference/subsystems/web-server.md +228 -0
  124. package/docs/reference/subsystems/web.md +208 -0
  125. package/docs/reference/subsystems/webhook.md +72 -0
  126. package/docs/reference/subsystems/workflow.md +280 -0
  127. package/docs/reference/subsystems/workspace.md +661 -0
  128. package/docs/start-here/blueprints.md +33 -0
  129. package/docs/start-here/this-runtime.md +84 -0
  130. package/docs/start-here/troubleshooting.md +29 -0
  131. package/docs/start-here/trust-and-safety.md +39 -0
  132. package/docs/start-here/verify-before-done.md +46 -0
  133. package/example-plugins/README.md +45 -0
  134. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  135. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  137. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  138. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  141. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  144. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  145. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  146. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  147. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  148. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  149. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  150. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  151. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  152. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  153. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  154. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  155. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  159. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  160. package/example-plugins/packages/client-theme-override/client.js +52 -0
  161. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  162. package/example-plugins/packages/client-theme-override/index.js +9 -0
  163. package/example-plugins/packages/client-theme-override/package.json +30 -0
  164. package/example-plugins/packages/client-tool-view/client.js +47 -0
  165. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  166. package/example-plugins/packages/client-tool-view/index.js +24 -0
  167. package/example-plugins/packages/client-tool-view/package.json +34 -0
  168. package/example-plugins/packages/client-ui-components/client.js +77 -0
  169. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  170. package/example-plugins/packages/client-ui-components/index.js +9 -0
  171. package/example-plugins/packages/client-ui-components/package.json +31 -0
  172. package/example-plugins/packages/client-ui-library/client.js +715 -0
  173. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  174. package/example-plugins/packages/client-ui-library/index.js +9 -0
  175. package/example-plugins/packages/client-ui-library/package.json +37 -0
  176. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  177. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  178. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  179. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  180. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  181. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  182. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  183. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  184. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  185. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  186. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  187. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  188. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  189. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  190. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  191. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  192. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  193. package/example-plugins/packages/host-route-basic/index.js +20 -0
  194. package/example-plugins/packages/host-route-basic/package.json +29 -0
  195. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  196. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  197. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  201. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  204. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  205. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  206. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  207. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  208. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  209. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  210. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  211. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  212. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  213. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  214. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  215. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  216. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  217. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  218. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  219. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  220. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  221. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  222. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  223. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  224. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  225. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  226. package/example-plugins/packages/state-host-store/client.js +57 -0
  227. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  228. package/example-plugins/packages/state-host-store/index.js +90 -0
  229. package/example-plugins/packages/state-host-store/package.json +31 -0
  230. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  231. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  232. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  233. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  234. package/example-plugins/packages/tool-basic/index.js +25 -0
  235. package/example-plugins/packages/tool-basic/package.json +25 -0
  236. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  237. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  238. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  239. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  240. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  241. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  242. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  243. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  244. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  245. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  246. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  247. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  248. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  249. package/example-plugins/packages/web-page-branding/index.js +31 -0
  250. package/example-plugins/packages/web-page-branding/package.json +22 -0
  251. package/example-plugins/scenarios.json +11 -0
  252. package/index.js +384 -0
  253. package/lib/blend-apply.js +107 -0
  254. package/lib/blend-capture.js +249 -0
  255. package/lib/blend-ledger.js +76 -0
  256. package/lib/contract.js +5 -0
  257. package/lib/install.js +516 -0
  258. package/lib/lookup.js +67 -0
  259. package/lib/manifest.js +56 -0
  260. package/lib/pack-root.js +22 -0
  261. package/lib/provenance.js +110 -0
  262. package/lib/publish.js +64 -0
  263. package/lib/reconcile.js +83 -0
  264. package/lib/router.js +55 -0
  265. package/lib/scopes.js +82 -0
  266. package/lib/skills.js +54 -0
  267. package/lib/stage.js +157 -0
  268. package/lib/verify.js +77 -0
  269. package/package.json +58 -3
  270. package/scripts/lib/indexes.mjs +45 -0
  271. package/scripts/lib/manifest.mjs +127 -0
  272. package/scripts/lib/maps.mjs +482 -0
  273. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  274. package/skills/acryl-add-ui/SKILL.md +18 -0
  275. package/skills/acryl-build-plugin/SKILL.md +21 -0
  276. package/skills/acryl-change-plugin/SKILL.md +16 -0
  277. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  278. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  279. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  280. package/skills/acryl-improve-ui/SKILL.md +10 -0
  281. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  282. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  283. package/skills/acryl-share-plugin/SKILL.md +23 -0
  284. 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 -->