@namzu/sdk 48.3.1 → 50.0.0

package/src/types/message/inbound-delivery.ts

@@ -0,0 +1,63 @@
+import type { SessionLogHead } from '../../store/session-log/core.js'
+import type { MessageId, SessionId, TurnId } from '../ids/index.js'
+import type { RuntimeContextMessageSource, UserMessage } from './index.js'
+
+/** Host provenance only; this reference grants no operator authority. */
+export interface InboundDeliveryRef {
+	readonly namespace: string
+	readonly id: string
+	readonly digest: string
+}
+
+/** Bounded validation for persisted or JavaScript-authored delivery references. */
+export function isInboundDeliveryRef(value: unknown): value is InboundDeliveryRef {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+	const candidate = value as Record<string, unknown>
+	return ['namespace', 'id', 'digest'].every((key) => {
+		const field = candidate[key]
+		return (
+			typeof field === 'string' &&
+			field.length > 0 &&
+			field.length <= 512 &&
+			[...field].every(
+				(character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127,
+			)
+		)
+	})
+}
+
+/** Durable delivery carries host context and cannot acquire operator authority. */
+export type DurableInboundMessage = UserMessage & {
+	readonly source: RuntimeContextMessageSource & {
+		readonly kind: Exclude<RuntimeContextMessageSource['kind'], 'steering'>
+		readonly deliveryRef: InboundDeliveryRef
+	}
+}
+
+export interface InboundDeliveryClaim {
+	readonly claimId: string
+	readonly ref: InboundDeliveryRef
+	readonly message: DurableInboundMessage
+}
+
+/** Exact ordinary session-log append, flushed before the host acknowledges it. */
+export interface InboundDeliveryReceipt {
+	readonly claimId: string
+	readonly ref: InboundDeliveryRef
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	readonly messageId: MessageId
+	readonly through: SessionLogHead
+}
+
+/** Host-owned durable input. Claim, write and acknowledgement failures stop execution. */
+export interface DurableInboundSource {
+	claim(context: {
+		readonly sessionId: SessionId
+		readonly turnId: TurnId
+		readonly signal: AbortSignal
+	}): Promise<readonly InboundDeliveryClaim[]>
+	recorded(receipts: readonly InboundDeliveryReceipt[]): Promise<void>
+	/** Wake only. An aborted wait must remove its listener. */
+	wait?(signal: AbortSignal): Promise<void>
+}

package/src/types/message/index.ts

@@ -1,4 +1,5 @@
 import type { GoalId, MessageId } from '../ids/index.js'
+import { type InboundDeliveryRef, isInboundDeliveryRef } from './inbound-delivery.js'
 
 export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
 
@@ -350,6 +351,8 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'advisory',
 	'answer-review',
 	'auto-continuation',
+	'channel-message',
+	'host-observation',
 	'job-exit',
 	'limit-finalization',
 	'peer-message',
@@ -367,6 +370,8 @@ export type RuntimeContextMessageKind = (typeof RUNTIME_CONTEXT_MESSAGE_KINDS)[n
 export interface RuntimeContextMessageSource {
 	readonly type: 'runtime-context'
 	readonly kind: RuntimeContextMessageKind
+	/** Optional durable host delivery identity; it never grants operator authority. */
+	readonly deliveryRef?: InboundDeliveryRef
 }
 
 export type UserMessageSource =
@@ -422,11 +427,13 @@ export function isRuntimeContextMessageSource(
 	const candidate = value as {
 		readonly type?: unknown
 		readonly kind?: unknown
+		readonly deliveryRef?: unknown
 	}
 	return (
 		candidate.type === 'runtime-context' &&
 		typeof candidate.kind === 'string' &&
-		(RUNTIME_CONTEXT_MESSAGE_KINDS as readonly string[]).includes(candidate.kind)
+		(RUNTIME_CONTEXT_MESSAGE_KINDS as readonly string[]).includes(candidate.kind) &&
+		(candidate.deliveryRef === undefined || isInboundDeliveryRef(candidate.deliveryRef))
 	)
 }
 

package/src/types/plugin/index.ts

@@ -371,6 +371,8 @@ export interface PluginMCPServerConfig {
 	readonly command: string
 	readonly args?: readonly string[]
 	readonly env?: Readonly<Record<string, string>>
+	/** Maximum time to connect and discover this server. Default 10,000 ms. */
+	readonly connectTimeoutMs?: number
 }
 
 // ---------------------------------------------------------------------------
@@ -392,12 +394,15 @@ export interface PluginManifest {
 	readonly personas?: readonly string[]
 }
 
-export const PluginMCPServerConfigSchema = z.object({
-	name: z.string().min(1),
-	command: z.string().min(1),
-	args: z.array(z.string()).optional(),
-	env: z.record(z.string()).optional(),
-})
+export const PluginMCPServerConfigSchema = z
+	.object({
+		name: z.string().min(1),
+		command: z.string().min(1),
+		args: z.array(z.string()).optional(),
+		env: z.record(z.string()).optional(),
+		connectTimeoutMs: z.number().int().positive().max(3_600_000).optional(),
+	})
+	.strict()
 
 export const PluginManifestSchema = z.object({
 	name: z

package/src/types/sandbox/index.ts

@@ -226,6 +226,12 @@ export interface SandboxDetachedProcess {
 	readonly child: import('node:child_process').ChildProcess
 	/** Signal everything the sandbox started for this process, inside the boundary and out. */
 	kill(signal: NodeJS.Signals): void
+	/**
+	 * Stop and confirm the entire owned process tree ended. Remote wrappers
+	 * provide this when closing the host child alone cannot prove guest exit.
+	 * Reject on an unconfirmed stop; retain ownership so the caller can retry.
+	 */
+	terminate?(signal?: NodeJS.Signals): Promise<void>
 }
 
 export interface SandboxSpawnOptions {
@@ -233,6 +239,39 @@ export interface SandboxSpawnOptions {
 	readonly env?: Record<string, string>
 }
 
+/** Host-selected guest process options; never inherits the operator environment. */
+export interface SandboxStdioOptions extends SandboxSpawnOptions {
+	readonly signal?: AbortSignal
+	/** Rechecked at admission and before every write/operation, e.g. Pal writer/lifetime. */
+	readonly assertExecutionAllowed?: () => void | Promise<void>
+}
+
+export interface SandboxStdioEvent {
+	readonly stream: 'stdout' | 'stderr'
+	readonly data: Uint8Array
+}
+
+/** A trusted host's ownership barrier for one application request. */
+export interface SandboxStdioOperation {
+	/** Call only after an exact application reply, or before dispatch was attempted. */
+	complete(): void
+	/** Permanently fence this allocation until computer stop. Never replay the request. */
+	outcomeUnknown(): void
+}
+
+/** Interactive pipes for an allocation-owned guest process, not a host child. */
+export interface SandboxStdioChannel {
+	/** One bounded, backpressured consumer. Bytes preserve binary and UTF-8 boundaries. */
+	readonly events: AsyncIterable<SandboxStdioEvent>
+	write(data: string | Uint8Array, signal?: AbortSignal): Promise<void>
+	/** Idle services do not prevent takeover; each actual request must hold this barrier. */
+	beginOperation(signal?: AbortSignal): Promise<SandboxStdioOperation>
+	/** Confirm this server's process group stopped; does not quiesce external applications. */
+	close(): Promise<void>
+	/** Resolves only on confirmed process-group exit; rejects on lost confirmation. */
+	readonly closed: Promise<void>
+}
+
 /**
  * One host-side end of a TCP connection opened from inside the sandbox.
  *
@@ -310,6 +349,13 @@ export interface Sandbox {
 		opts?: SandboxSpawnOptions,
 	): SandboxDetachedProcess
 
+	/** Optional interactive guest stdio. Never falls back to a host subprocess. */
+	openStdio?(
+		command: string,
+		args?: readonly string[],
+		options?: SandboxStdioOptions,
+	): Promise<SandboxStdioChannel>
+
 	/**
 	 * Narrow or widen what this sandbox can reach, while it is running.
 	 *

package/src/types/session/checkpoint.ts

@@ -40,12 +40,14 @@ export interface Checkpoint {
 	/**
 	 * Review corrections already consumed at this checkpoint, independent of
 	 * compactable history: host structured-output review, prose-answer review
-	 * and native structured-output correction.
+	 * and tool/native structured-output correction.
 	 */
 	readonly review: {
 		readonly structuredAttempts: number
 		readonly answerAttempts: number
 		readonly nativeStructuredAttempts: number
+		/** Tool-output corrections; absent in older v1 checkpoints and restored as zero. */
+		readonly toolStructuredAttempts?: number
 	}
 	/** The turn's current operator/goal/steering message, independent of compaction. */
 	readonly latestUserMessageId?: MessageId
@@ -120,6 +122,7 @@ export const CheckpointSchema = z
 				structuredAttempts: count,
 				answerAttempts: count,
 				nativeStructuredAttempts: count,
+				toolStructuredAttempts: count.optional(),
 			})
 			.strict(),
 		latestUserMessageId: id<MessageId>('message').optional(),

package/src/types/session/events.ts

@@ -18,7 +18,7 @@ import type { Message } from '../message/index.js'
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
-import type { ToolResultView } from '../tool/presentation.js'
+import type { ToolFacts, ToolResultView } from '../tool/presentation.js'
 import type { CancelCause } from './cancel-cause.js'
 import type { FencingToken } from './durable.js'
 import type { Lineage } from './lineage.js'
@@ -416,12 +416,30 @@ type CoreSessionEvent =
 			type: 'tool_completed'
 			/** Bounded result view; omitted when output was overridden or truncated. */
 			presentation?: ToolResultView
+			/**
+			 * What a saved conversation keeps of a call that has no diff: one
+			 * label line (or a command's first line), never the output. Live
+			 * hosts ignore it and draw the real result.
+			 */
+			savedPresentation?: ToolResultView
+			/**
+			 * What the call did, as typed fields for the person's view (see
+			 * `ToolResult.facts`). Absent when a post-tool hook replaced the
+			 * output, so a redaction is never undone by a structured copy.
+			 */
+			facts?: ToolFacts
 			sessionId: SessionId
 			turnId: TurnId
 			toolUseId: ToolUseId
 			toolName: string
 			result: string
 			isError: boolean
+			/** Executor-classified provider argument failure; absent for host policy, rewrites and cancellation. */
+			inputFailure?: 'invalid_json' | 'schema_validation' | 'input_truncated'
+			/** Execution was deliberately skipped by a pre-tool hook; a non-error receipt, not a produced output. */
+			skipped?: true
+			/** Opt-in successful structured_output JSON after screening and post-tool hooks, before preview capping. Not an accepted result. */
+			structuredResultJson?: string
 			/** See {@link tool_executing}'s `via`. Carried on both, so a
 			 * consumer can pair them without holding the start event. */
 			via?: {
@@ -939,6 +957,8 @@ type CoreSessionEvent =
 			 */
 			blockedBy?: readonly TaskId[]
 			owner?: string
+			/** The present-continuous form the model gave ("Running the tests"); absent when it gave none. */
+			activeForm?: string
 	  }
 	| {
 			type: 'task_updated'
@@ -950,6 +970,8 @@ type CoreSessionEvent =
 			owner?: string
 			/** See `task_created`. Carried on updates because an edge can be added later. */
 			blockedBy?: readonly TaskId[]
+			/** See `task_created`. */
+			activeForm?: string
 			/**
 			 * The task was removed from the list (`task_update` with status
 			 * `deleted`). `status` and `subject` are what it had when it went.

package/src/types/session/records.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod'
 import { type EntityIdKind, isEntityId } from '../../utils/id.js'
+import {
+	STRUCTURED_RESULT_MAX_BYTES,
+	parseStructuredResultJson,
+} from '../../utils/structured-result-json.js'
+import { HarnessBindingSchema, HarnessJournalTransitionSchema } from '../harness/schema.js'
 import type { HITLDecisionRequest, HITLResumeDecision } from '../hitl/index.js'
 import type {
 	CheckpointId,
@@ -11,7 +16,7 @@ import type {
 	TopicId,
 	TurnId,
 } from '../ids/index.js'
-import type { Message } from '../message/index.js'
+import { type Message, isRuntimeContextMessageSource } from '../message/index.js'
 import type { ActorRef } from './actor.js'
 import { CostInfoSchema, TokenUsageSchema, TurnBudgetBindingSchema } from './checkpoint.js'
 import {
@@ -70,7 +75,15 @@ const MESSAGE_ROLES = new Set(['system', 'user', 'assistant', 'tool'])
  * schema checks the discriminant and leaves the content to the message types.
  */
 const messageBody = z.custom<Message>(
-	(value) => isPlainObject(value) && MESSAGE_ROLES.has(value.role as string),
+	(value) => {
+		if (!isPlainObject(value) || !MESSAGE_ROLES.has(value.role as string)) return false
+		const source = value.source
+		return (
+			!isPlainObject(source) ||
+			source.type !== 'runtime-context' ||
+			isRuntimeContextMessageSource(source)
+		)
+	},
 	{ message: 'expected a message with a system, user, assistant or tool role' },
 )
 
@@ -276,6 +289,16 @@ const spill = z
 	})
 	.strict()
 
+const structuredResultSpill = spill
+	.extend({
+		path: text.regex(/^tool-results\/[a-f0-9]{64}\.txt$/),
+		manifest: text.regex(/^tool-results\/[a-f0-9]{64}\.txt\.manifest\.json$/),
+		bytes: positive.max(STRUCTURED_RESULT_MAX_BYTES),
+	})
+	.refine((ref) => ref.manifest === `${ref.path}.manifest.json`, {
+		message: 'a structured spill manifest must name its body',
+	})
+
 const subSessionKind = z.enum(['agent_spawn', 'user_handoff', 'intervention'])
 
 const actorRef = z.custom<ActorRef>(
@@ -319,6 +342,7 @@ function inTurn<T extends string, S extends z.ZodRawShape>(type: T, shape: S) {
 // Session
 
 export const SessionStartedRecordSchema = recordSchema('session_started', {
+	harness: HarnessBindingSchema.optional(),
 	projectId,
 	tenantId: tenantId.optional(),
 	topicId: topicId.optional(),
@@ -340,6 +364,7 @@ export const SessionStartedRecordSchema = recordSchema('session_started', {
 })
 
 export const SessionUpdatedRecordSchema = recordSchema('session_updated', {
+	harness: HarnessJournalTransitionSchema.optional(),
 	title: text.optional(),
 	titleSource: z.enum(['derived', 'named']).optional(),
 	archived: z.boolean().optional(),
@@ -382,6 +407,8 @@ export const TurnCompletedRecordSchema = inTurn('turn_completed', {
 	/** The settled answer, or a preview of it when `resultSpill` holds the whole text. */
 	result: text,
 	resultSpill: spill.optional(),
+	/** Accepted JSON stored separately; settlement.structuredOutput is then absent. */
+	structuredOutputSpill: structuredResultSpill.optional(),
 	stopReason: stopReason.optional(),
 	cancelCause: cancelCause.optional(),
 	budget: tokenBudgetSummary.optional(),
@@ -787,6 +814,83 @@ export const SessionRecordSchema = z
 				message: `${r.type} happens only inside a turn and must carry turnId`,
 			})
 		}
+		if (
+			r.type === 'tool_completed' &&
+			r.inputFailure !== undefined &&
+			(!['invalid_json', 'schema_validation', 'input_truncated'].includes(
+				r.inputFailure as string,
+			) ||
+				r.isError !== true)
+		) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['inputFailure'],
+				message: 'inputFailure must classify a failed tool admission',
+			})
+		}
+		if (
+			r.type === 'tool_completed' &&
+			r.skipped !== undefined &&
+			(r.skipped !== true || r.isError !== false || r.inputFailure !== undefined)
+		) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['skipped'],
+				message: 'skipped must classify a non-error pre-tool hook skip without an input failure',
+			})
+		}
+		if (
+			r.type === 'tool_completed' &&
+			(r.structuredResultJson !== undefined || r.structuredResultSpill !== undefined)
+		) {
+			let validJson = false
+			try {
+				if (r.structuredResultSpill !== undefined) {
+					validJson =
+						r.structuredResultJson === undefined &&
+						structuredResultSpill.safeParse(r.structuredResultSpill).success
+				} else {
+					parseStructuredResultJson(r.structuredResultJson)
+					validJson = true
+				}
+			} catch {
+				// Retained evidence is never repaired or downgraded to a preview.
+			}
+			if (
+				!validJson ||
+				r.toolName !== 'structured_output' ||
+				r.isError !== false ||
+				r.skipped !== undefined ||
+				r.inputFailure !== undefined ||
+				r.via !== undefined
+			) {
+				context.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: [
+						r.structuredResultSpill !== undefined
+							? 'structuredResultSpill'
+							: 'structuredResultJson',
+					],
+					message:
+						'structured result evidence must hold JSON or a spill from a successful direct structured_output execution, never both',
+				})
+			}
+		}
+		if (r.type === 'turn_completed' && r.structuredOutputSpill !== undefined) {
+			const settlement = r.settlement as Record<string, unknown>
+			if (
+				settlement.status !== 'completed' ||
+				settlement.resultSource !== 'structured_output' ||
+				settlement.structuredOutput !== undefined
+			) {
+				context.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['structuredOutputSpill'],
+					message:
+						'a structured output spill requires a completed structured_output settlement without inline structuredOutput',
+				})
+			}
+		}
 		if (r.type === 'message') {
 			const content = r.content as { role: unknown }
 			if (r.role !== content.role) {
@@ -851,6 +955,14 @@ export type SessionEventRecord<T extends PersistedSessionEventType = PersistedSe
 	T extends PersistedSessionEventType
 		? Omit<EventOf<T>, 'sessionId' | 'turnId' | 'lineage' | 'v' | 'seq' | 'generation'> &
 				RecordEnvelope &
+				(T extends 'tool_completed'
+					? { readonly structuredResultSpill?: z.infer<typeof structuredResultSpill> }
+					: T extends 'turn_completed'
+						? {
+								readonly resultSpill?: z.infer<typeof spill>
+								readonly structuredOutputSpill?: z.infer<typeof structuredResultSpill>
+							}
+						: unknown) &
 				(T extends TurnBoundSessionEventType ? { readonly turnId: TurnId } : unknown)
 		: never
 

package/src/types/session/step.ts

@@ -159,6 +159,8 @@ export interface StepToolResult {
 	/** Text form, after the model-visible output budget was applied. */
 	output: string
 	isError: boolean
+	/** The pre-tool hook skipped this call; its receipt is not an executed answer. */
+	skipped?: true
 	durationMs: number
 }
 

package/src/types/session/store.ts

@@ -16,7 +16,7 @@ import type {
 	SubSessionKind,
 } from '../../types/session/sub-session.js'
 import type { SessionSummaryRef } from '../../types/summary/ref.js'
-import type { SessionId, TenantId } from '../ids/index.js'
+import type { SessionId, TenantId, TurnId } from '../ids/index.js'
 import type { ProjectId, SubSessionId, SummaryId, TopicId } from '../session/ids.js'
 
 /**
@@ -145,6 +145,10 @@ export interface SessionView {
  * callers never get a fallback and must branch on missing explicitly.
  */
 export interface SessionStore {
+	/** Explicit opt-in to immutable turn-keyed summaries. Omission does not support child continuation. */
+	readonly supportsInvocationSummaries?: boolean
+	/** Opt in only when updateSession and recordSummary enforce owner-version CAS. */
+	readonly supportsOwnerVersionCas?: boolean
 	// Project CRUD ------------------------------------------------------------
 
 	createProject(params: CreateProjectParams, tenantId: TenantId): Promise<Project>
@@ -241,7 +245,8 @@ export interface SessionStore {
 	 * into.
 	 *
 	 * **In-process only, stated rather than implied.** `DiskSessionStore`
-	 * writes atomically, but its read-compare-write is not a critical section,
+	 * serializes session writes across instances using the same root within a
+	 * process. Its read-compare-write is not a cross-process critical section,
 	 * so two PROCESSES can still both pass the check. Closing that needs a
 	 * lease with an expiry — not a PID registry, because a Session is durable
 	 * and written from hosts where a PID is not a checkable fact. The same
@@ -359,21 +364,30 @@ export interface SessionStore {
 	 * writes commit as one logical unit; mid-crash recovery is replay via
 	 * `SessionSummaryMaterializer.recover()`.
 	 *
-	 * Rejects with {@link SessionAlreadySummarizedError} if a summary already
-	 * exists for the session (re-materialization forbidden; see
-	 * session-hierarchy.md §4.7 immutability invariant).
+	 * Summaries are immutable per `(sessionRef, turnRef)`. An absent `turnRef`
+	 * preserves the original single conversation-summary contract. A supplied
+	 * `turnRef` seals one invocation without replacing any previous summary.
+	 * Rejects a different summary at an already sealed key.
+	 * With expectedOwnerVersion, refuse before persisting or flipping status if
+	 * the current session owner changed. Omission preserves the legacy behavior.
 	 */
 	recordSummary(
 		summary: SessionSummaryRef & { materializedBy: 'kernel' },
 		tenantId: TenantId,
+		expectedOwnerVersion?: number,
 	): Promise<void>
 
 	/**
-	 * Loads the persisted summary for a session. Returns `null` when none has
-	 * been materialized. Cross-tenant reads reject with `TenantIsolationError`
-	 * (Convention #17).
+	 * Loads the original conversation summary, or the exact invocation summary
+	 * when `turnId` is supplied. Returns `null` when that key is unsealed; it
+	 * never substitutes the original or newest summary for a missing invocation.
+	 * Cross-tenant reads reject with `TenantIsolationError` (Convention #17).
 	 */
-	getSummary(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null>
+	getSummary(
+		sessionId: SessionId,
+		tenantId: TenantId,
+		turnId?: TurnId,
+	): Promise<SessionSummaryRef | null>
 }
 
 /**

package/src/types/session/tool-execution.ts

@@ -14,6 +14,12 @@ export interface CompletedToolRecord {
 	readonly toolName: string
 	readonly result: string
 	readonly isError: boolean
+	/** Trusted admission classification retained with the completion, absent in legacy records. */
+	readonly inputFailure?: 'invalid_json' | 'schema_validation' | 'input_truncated'
+	/** Trusted pre-tool hook skip, absent in legacy records; the tool produced no output. */
+	readonly skipped?: true
+	/** Opt-in screened, post-hook JSON from a successful structured_output; independent of the bounded receipt. */
+	readonly structuredResultJson?: string
 }
 
 /** The latest recorded execution boundary of a tool call, not its inferred external effect. */

package/src/types/structured-output/index.ts

@@ -17,8 +17,19 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
 	mode?: 'tool' | 'native'
 
 	/**
-	 * Turns spent re-prompting when the model answers in prose or fails
-	 * validation. Defaults to {@link DEFAULT_STRUCTURED_OUTPUT_RETRIES}.
+	 * Tool mode only. Default `receipt` settles from the bounded tool message.
+	 * `durable` also records the screened, post-hook JSON before preview capping,
+	 * so a truncated preview does not destroy the candidate. The session log's
+	 * record size limit still applies. This is execution evidence, not acceptance;
+	 * recovered batches retain the existing fresh-inference settlement policy.
+	 */
+	toolResultRetention?: 'receipt' | 'durable'
+
+	/**
+	 * Correction opportunities after missing output or model-argument validation
+	 * failure. Default 2; zero stops after the first invalid response. Tool-mode
+	 * prose and invalid output calls share a checkpointed counter, once per response.
+	 * Host review rejections use the separate maxReviews allowance.
 	 *
 	 * Bounded so a model that cannot satisfy the schema fails loudly rather
 	 * than iterating against `maxIterations`.

package/src/types/summary/ref.ts

@@ -20,7 +20,7 @@
  * `session/summary/errors.ts` — they are NOT pure shapes.
  */
 
-import type { SessionId, TenantId } from '../ids/index.js'
+import type { SessionId, TenantId, TurnId } from '../ids/index.js'
 import type { SummaryId } from '../session/ids.js'
 import type { DeliverableRef } from './deliverable.js'
 
@@ -53,6 +53,8 @@ export interface SessionSummaryKeyDecision {
 export interface SessionSummaryRef {
 	readonly id: SummaryId
 	readonly sessionRef: SessionId
+	/** Immutable completion of one invocation; omission is the legacy conversation summary. */
+	readonly turnRef?: TurnId
 	readonly tenantId: TenantId
 	readonly outcome: SessionSummaryOutcome
 	readonly deliverables: readonly DeliverableRef[]