Yichen Jiang
951967217a
# Conflicts: # docs/capability-seams.md # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/module-graph.md # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # packages/cordis/tool-cordis/src/api-catalog.ts # packages/ui/acp/README.md # packages/ui/acp/package.json # packages/ui/acp/tsconfig.json # packages/ui/tui/package.json # packages/ui/tui/src/index.ts # packages/ui/tui/tests/tui.spec.ts # packages/ui/tui/tsconfig.json # pnpm-lock.yaml # python/sdk-runtime/package.json # scripts/gen-doc-graphs.ts # scripts/type-equiv.manifest.json
66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
# Session References
|
|
|
|
Structured cross-session reference requests and prepared message contexts. The [package contract](../../packages/context/session-reference) owns 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.
|
|
|
|
Source: [`packages/context/session-reference/src/types.ts`](../../packages/context/session-reference/src/types.ts)
|
|
|
|
## Inputs and candidates
|
|
|
|
`SessionReferenceInput` is the host-independent selection. The id is authoritative; the label is display metadata carried into the snapshot.
|
|
|
|
```ts type-equiv
|
|
/** One source session selected by a host. */
|
|
interface SessionReferenceInput {
|
|
/** Opaque source session identity. */
|
|
sessionId: SessionId
|
|
/** Optional user-facing mention label. */
|
|
label?: string
|
|
}
|
|
```
|
|
|
|
`SessionReferenceCandidate` is host-facing discovery output. Its label uses the latest session title when present, while filtering still searches only session id and cwd and never transcript text.
|
|
|
|
```ts type-equiv
|
|
/** One host-facing candidate from exact session metadata. */
|
|
interface SessionReferenceCandidate {
|
|
/** Opaque source session identity. */
|
|
sessionId: SessionId
|
|
/** Latest log-backed title, falling back to the opaque session id. */
|
|
label: string
|
|
/** Source session working directory, when recorded. */
|
|
cwd?: string
|
|
/** Source session creation time in Unix epoch milliseconds. */
|
|
createdAt: number
|
|
}
|
|
```
|
|
|
|
## Prepared messages
|
|
|
|
Preparation preserves readable current-message content and returns at most one aggregated context. The host binds `contexts` to that exact `send()` or `steer()` call.
|
|
|
|
```ts type-equiv
|
|
/** Message payload and the zero-or-one durable snapshot contexts bound to it. */
|
|
interface PreparedReferencedMessage {
|
|
/** Readable message content after host mention tokens are removed. */
|
|
content: ContentBlock[]
|
|
/** Empty without references; otherwise one aggregated untrusted context. */
|
|
contexts: HookContext[]
|
|
}
|
|
```
|
|
|
|
## Errors
|
|
|
|
`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.
|
|
|
|
```ts type-equiv
|
|
/** Stable failure codes exposed to host adapters. */
|
|
type SessionReferenceErrorCode =
|
|
| 'SESSION_REFERENCE_INVALID_CONFIG'
|
|
| 'SESSION_REFERENCE_INVALID_REFERENCE'
|
|
| 'SESSION_REFERENCE_SELF_REFERENCE'
|
|
| 'SESSION_REFERENCE_TOO_MANY'
|
|
| 'SESSION_REFERENCE_READ_FAILED'
|
|
| 'SESSION_REFERENCE_BUDGET_EXCEEDED'
|
|
| 'SESSION_REFERENCE_CANCELLED'
|
|
```
|