@markusylisiurunen/tau 0.3.42 → 0.3.44

package/dist/protocol/session_protocol.js

@@ -1,7 +1,10 @@
 import { z } from "zod";
-export const SESSION_PROTOCOL_VERSION = 8;
+export const SESSION_PROTOCOL_VERSION = 10;
 export const SESSION_PROTOCOL_MAX_EXEC_CAPTURE_BYTES = 24 * 1024 * 1024;
 export const SESSION_PROTOCOL_MAX_EXEC_STDIN_BYTES = 16 * 1024 * 1024;
+const SESSION_PROTOCOL_NOTICE_TITLE_MAX_CHARS = 512;
+const SESSION_PROTOCOL_NOTICE_CONTENT_MAX_ENTRIES = 16;
+const SESSION_PROTOCOL_NOTICE_CONTENT_ENTRY_MAX_CHARS = 4_096;
 export const SESSION_PROTOCOL_METHODS = [
     "initialize",
     "session.create",
@@ -65,6 +68,22 @@ const SESSION_PROTOCOL_ERROR_CODE_VALUES = [
     SESSION_PROTOCOL_ERROR_CODES.cancelled,
     SESSION_PROTOCOL_ERROR_CODES.internalError,
 ];
+export function projectSessionProtocolNoticePresentation(title, content) {
+    const projectedContent = content
+        ? content
+            .slice(0, SESSION_PROTOCOL_NOTICE_CONTENT_MAX_ENTRIES)
+            .map((entry) => truncateNoticeText(entry, SESSION_PROTOCOL_NOTICE_CONTENT_ENTRY_MAX_CHARS))
+        : [];
+    return {
+        title: truncateNoticeText(title, SESSION_PROTOCOL_NOTICE_TITLE_MAX_CHARS),
+        ...(projectedContent.length > 0 ? { content: projectedContent } : {}),
+    };
+}
+function truncateNoticeText(value, maxChars) {
+    if (value.length <= maxChars)
+        return value;
+    return `${value.slice(0, maxChars - 1)}…`;
+}
 const sessionProtocolMethodSchema = z.enum(SESSION_PROTOCOL_METHODS);
 const sessionProtocolMethodListSchema = z
     .array(sessionProtocolMethodSchema)
@@ -86,6 +105,10 @@ const nonEmptyStringSchema = z
     .string()
     .min(1)
     .refine((value) => value.trim().length > 0);
+const historyEntryIdSchema = nonEmptyStringSchema.transform((value) => value.trim());
+const noticeTitleSchema = nonEmptyStringSchema
+    .max(SESSION_PROTOCOL_NOTICE_TITLE_MAX_CHARS)
+    .refine((value) => !value.includes("\n") && !value.includes("\r"), "notice title must be one line");
 const sessionProtocolRequestIdSchema = nonEmptyStringSchema;
 const nullableSessionProtocolRequestIdSchema = sessionProtocolRequestIdSchema.nullable();
 const absolutePathSchema = nonEmptyStringSchema.refine((value) => value.startsWith("/"));
@@ -348,7 +371,7 @@ const sessionProtocolUserMessageParamsSchema = z
     .object({
     sessionId: nonEmptyStringSchema,
     text: nonEmptyStringSchema,
-    historyEntryId: nonEmptyStringSchema.optional(),
+    historyEntryId: historyEntryIdSchema.optional(),
 })
     .strip();
 const sessionProtocolStartGoalParamsSchema = z
@@ -462,7 +485,7 @@ const sessionProtocolCompactParamsSchema = z
 const sessionProtocolRewindParamsSchema = z
     .object({
     sessionId: nonEmptyStringSchema,
-    historyEntryId: nonEmptyStringSchema,
+    historyEntryId: historyEntryIdSchema,
 })
     .strip();
 const sessionProtocolInterruptSubagentParamsSchema = z
@@ -753,50 +776,136 @@ const sessionProtocolMessageSchema = z
     state: z.enum(["draft", "committed", "interrupted", "discarded"]),
     modelVisible: z.boolean(),
     message: sessionProtocolMessagePayloadSchema,
-    turn: sessionProtocolTurnOutcomeSchema.optional(),
 })
     .strip();
+const sessionProtocolSubjectSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("session") }).strip(),
+    z.object({ type: z.literal("message"), id: nonEmptyStringSchema }).strip(),
+    z.object({ type: z.literal("tool"), id: nonEmptyStringSchema }).strip(),
+    z.object({ type: z.literal("agent"), id: nonEmptyStringSchema }).strip(),
+    z.object({ type: z.literal("operation"), id: nonEmptyStringSchema }).strip(),
+]);
+const timelineNoticeKindSchema = nonEmptyStringSchema.regex(/^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/, "timeline notice kind must be a lowercase dotted identifier");
 const sessionProtocolNoticeSchema = z
     .object({
+    kind: timelineNoticeKindSchema,
+    version: z.number().int().positive(),
     severity: z.enum(["info", "warn", "error"]),
-    text: z.string(),
-    timestamp: z.number().finite(),
+    subject: sessionProtocolSubjectSchema,
+    presentation: z
+        .object({
+        title: noticeTitleSchema,
+        content: z
+            .array(z.string().max(SESSION_PROTOCOL_NOTICE_CONTENT_ENTRY_MAX_CHARS))
+            .min(1)
+            .max(SESSION_PROTOCOL_NOTICE_CONTENT_MAX_ENTRIES)
+            .optional(),
+    })
+        .strip(),
+    data: z.record(z.string(), z.unknown()),
 })
     .strip();
-const sessionProtocolOperationSchema = z
-    .object({
+const sessionProtocolOperationBaseSchema = {
+    id: nonEmptyStringSchema,
     kind: z.enum(["auto-compaction", "manual-compaction", "reload", "rewind"]),
-    status: z.enum(["running", "succeeded", "failed", "cancelled", "skipped"]),
     startedAt: z.number().finite(),
-    finishedAt: z.number().finite().optional(),
-    summary: z.string().optional(),
-    error: z.string().optional(),
-    data: z.record(z.string(), z.unknown()).optional(),
-})
-    .strip();
+};
+const sessionProtocolOperationSchema = z.discriminatedUnion("status", [
+    z.object({ ...sessionProtocolOperationBaseSchema, status: z.literal("running") }).strip(),
+    z
+        .object({
+        ...sessionProtocolOperationBaseSchema,
+        status: z.literal("succeeded"),
+        finishedAt: z.number().finite(),
+    })
+        .strip(),
+    z
+        .object({
+        ...sessionProtocolOperationBaseSchema,
+        status: z.literal("failed"),
+        finishedAt: z.number().finite(),
+        error: nonEmptyStringSchema,
+    })
+        .strip(),
+    z
+        .object({
+        ...sessionProtocolOperationBaseSchema,
+        status: z.literal("skipped"),
+        finishedAt: z.number().finite(),
+        reason: z.literal("no-eligible-history"),
+    })
+        .strip(),
+    z
+        .object({
+        ...sessionProtocolOperationBaseSchema,
+        status: z.literal("cancelled"),
+        finishedAt: z.number().finite(),
+        reason: z.enum(["interrupted", "session-recovered"]),
+    })
+        .strip(),
+]);
+const sessionProtocolTimelineItemBaseSchema = {
+    id: nonEmptyStringSchema,
+    sequence: z.number().int().positive(),
+    createdAt: z.number().finite().nonnegative(),
+};
 const sessionProtocolTimelineItemSchema = z.discriminatedUnion("type", [
     z
         .object({
+        ...sessionProtocolTimelineItemBaseSchema,
         type: z.literal("message"),
-        id: nonEmptyStringSchema,
         messageId: nonEmptyStringSchema,
     })
         .strip(),
     z
         .object({
+        ...sessionProtocolTimelineItemBaseSchema,
+        type: z.literal("tool"),
+        toolId: nonEmptyStringSchema,
+    })
+        .strip(),
+    z
+        .object({
+        ...sessionProtocolTimelineItemBaseSchema,
         type: z.literal("notice"),
-        id: nonEmptyStringSchema,
         notice: sessionProtocolNoticeSchema,
     })
         .strip(),
     z
         .object({
+        ...sessionProtocolTimelineItemBaseSchema,
         type: z.literal("operation"),
-        id: nonEmptyStringSchema,
-        operation: sessionProtocolOperationSchema,
+        operationId: nonEmptyStringSchema,
     })
         .strip(),
 ]);
+const sessionProtocolTimelineSchema = z
+    .object({
+    epoch: z.number().int().positive(),
+    sequence: z.number().int().nonnegative(),
+    items: z.array(sessionProtocolTimelineItemSchema),
+})
+    .strip()
+    .superRefine((timeline, ctx) => {
+    let previousSequence = 0;
+    for (const [index, item] of timeline.items.entries()) {
+        if (item.sequence <= previousSequence) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["items", index, "sequence"],
+                message: "timeline item sequences must be strictly increasing",
+            });
+        }
+        if (item.sequence > timeline.sequence) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["items", index, "sequence"],
+                message: "timeline item sequence exceeds the timeline high-water sequence",
+            });
+        }
+        previousSequence = item.sequence;
+    }
+});
 const sessionProtocolToolRunBaseSchema = z.object({
     id: nonEmptyStringSchema,
     toolCallId: nonEmptyStringSchema,
@@ -918,17 +1027,10 @@ const sessionProtocolAgentRunSchema = z
         });
     }
 });
-const sessionProtocolFacetSubjectSchema = z.discriminatedUnion("type", [
-    z.object({ type: z.literal("session") }).strip(),
-    z.object({ type: z.literal("message"), id: nonEmptyStringSchema }).strip(),
-    z.object({ type: z.literal("tool"), id: nonEmptyStringSchema }).strip(),
-    z.object({ type: z.literal("agent"), id: nonEmptyStringSchema }).strip(),
-    z.object({ type: z.literal("operation"), id: nonEmptyStringSchema }).strip(),
-]);
 const sessionProtocolFacetSchema = z
     .object({
     id: nonEmptyStringSchema,
-    subject: sessionProtocolFacetSubjectSchema,
+    subject: sessionProtocolSubjectSchema,
     kind: nonEmptyStringSchema,
     version: z.number().int().positive(),
     data: z.record(z.string(), z.unknown()),
@@ -943,17 +1045,27 @@ const sessionProtocolGoalSchema = z
 const sessionProtocolAgentStateSnapshotSchema = z
     .object({
     revision: z.number().int().nonnegative(),
-    contextEpoch: nonEmptyStringSchema,
+    modelContextKey: nonEmptyStringSchema,
     usageCheckpoint: z
         .object({
         historyEntryId: nonEmptyStringSchema,
-        contextEpoch: nonEmptyStringSchema,
+        modelContextKey: nonEmptyStringSchema,
         tokens: z.number().int().nonnegative(),
     })
         .strip()
         .optional(),
 })
     .strip();
+const sessionProtocolTurnRecordSchema = z.discriminatedUnion("state", [
+    z.object({ userHistoryEntryId: nonEmptyStringSchema, state: z.literal("running") }).strip(),
+    z
+        .object({
+        userHistoryEntryId: nonEmptyStringSchema,
+        state: z.literal("settled"),
+        outcome: sessionProtocolTurnOutcomeSchema,
+    })
+        .strip(),
+]);
 const sessionProtocolSnapshotSchema = z
     .object({
     sessionId: nonEmptyStringSchema,
@@ -969,8 +1081,10 @@ const sessionProtocolSnapshotSchema = z
     catalog: sessionProtocolContentCatalogSnapshotSchema,
     executionEnvironment: sessionProtocolExecutionEnvironmentSnapshotSchema,
     messages: z.array(sessionProtocolMessageSchema),
-    timeline: z.array(sessionProtocolTimelineItemSchema),
+    turns: z.record(nonEmptyStringSchema, sessionProtocolTurnRecordSchema),
+    timeline: sessionProtocolTimelineSchema,
     tools: z.record(nonEmptyStringSchema, sessionProtocolToolRunSchema),
+    operations: z.record(nonEmptyStringSchema, sessionProtocolOperationSchema),
     agents: z.record(nonEmptyStringSchema, sessionProtocolAgentRunSchema),
     facets: z.record(nonEmptyStringSchema, sessionProtocolFacetSchema),
 })
@@ -985,22 +1099,15 @@ const sessionProtocolSnapshotSchema = z
                 message: `duplicate message id '${message.id}'`,
             });
         }
-        if (message.turn && message.message.role !== "user") {
-            ctx.addIssue({
-                code: "custom",
-                path: ["messages"],
-                message: `turn outcome belongs to non-user message '${message.id}'`,
-            });
-        }
         messagesById.set(message.id, message);
     }
     const checkpoint = snapshot.agentState.usageCheckpoint;
     if (checkpoint) {
-        if (checkpoint.contextEpoch !== snapshot.agentState.contextEpoch) {
+        if (checkpoint.modelContextKey !== snapshot.agentState.modelContextKey) {
             ctx.addIssue({
                 code: "custom",
-                path: ["agentState", "usageCheckpoint", "contextEpoch"],
-                message: "usage checkpoint context epoch must match agent state",
+                path: ["agentState", "usageCheckpoint", "modelContextKey"],
+                message: "usage checkpoint model context key must match agent state",
             });
         }
         const checkpointMessage = messagesById.get(checkpoint.historyEntryId);
@@ -1019,29 +1126,109 @@ const sessionProtocolSnapshotSchema = z
             });
         }
     }
+    const subjectExists = (subject) => subject.type === "session" ||
+        (subject.type === "message" && messagesById.has(subject.id)) ||
+        (subject.type === "tool" && snapshot.tools[subject.id] !== undefined) ||
+        (subject.type === "agent" && snapshot.agents[subject.id] !== undefined) ||
+        (subject.type === "operation" && snapshot.operations[subject.id] !== undefined);
     const timelineIds = new Set();
-    const operationIds = new Set();
-    for (const item of snapshot.timeline) {
+    const timelineSequences = new Set();
+    const timelineToolIds = new Set();
+    const timelineOperationIds = new Set();
+    let previousTimelineSequence = 0;
+    for (const item of snapshot.timeline.items) {
         if (timelineIds.has(item.id)) {
             ctx.addIssue({
                 code: "custom",
-                path: ["timeline"],
+                path: ["timeline", "items"],
                 message: `duplicate timeline item id '${item.id}'`,
             });
         }
         timelineIds.add(item.id);
+        if (timelineSequences.has(item.sequence) ||
+            item.sequence <= previousTimelineSequence ||
+            item.sequence > snapshot.timeline.sequence) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["timeline", "items"],
+                message: `timeline item '${item.id}' has invalid sequence '${item.sequence}'`,
+            });
+        }
+        timelineSequences.add(item.sequence);
+        previousTimelineSequence = item.sequence;
         if (item.type === "message" && !messagesById.has(item.messageId)) {
             ctx.addIssue({
                 code: "custom",
-                path: ["timeline"],
+                path: ["timeline", "items"],
                 message: `timeline message item '${item.id}' references unknown message '${item.messageId}'`,
             });
         }
+        if (item.type === "tool") {
+            if (timelineToolIds.has(item.toolId)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["timeline", "items"],
+                    message: `tool '${item.toolId}' has multiple timeline items`,
+                });
+            }
+            timelineToolIds.add(item.toolId);
+            if (snapshot.tools[item.toolId] === undefined) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["timeline", "items"],
+                    message: `timeline tool item '${item.id}' references unknown tool '${item.toolId}'`,
+                });
+            }
+        }
         if (item.type === "operation") {
-            operationIds.add(item.id);
+            if (timelineOperationIds.has(item.operationId)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["timeline", "items"],
+                    message: `operation '${item.operationId}' has multiple timeline items`,
+                });
+            }
+            timelineOperationIds.add(item.operationId);
+            if (snapshot.operations[item.operationId] === undefined) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["timeline", "items"],
+                    message: `timeline operation item '${item.id}' references unknown operation '${item.operationId}'`,
+                });
+            }
+        }
+        if (item.type === "notice" && !subjectExists(item.notice.subject)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["timeline", "items"],
+                message: `timeline notice '${item.id}' references an unknown ${item.notice.subject.type} subject`,
+            });
+        }
+    }
+    for (const [id, operation] of Object.entries(snapshot.operations)) {
+        if (!timelineOperationIds.has(id)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["operations", id],
+                message: `operation '${id}' has no timeline item`,
+            });
+        }
+        if (id !== operation.id) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["operations", id],
+                message: `operation map key '${id}' does not match embedded id '${operation.id}'`,
+            });
         }
     }
     for (const [id, tool] of Object.entries(snapshot.tools)) {
+        if (!timelineToolIds.has(id)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["tools", id],
+                message: `tool '${id}' has no timeline item`,
+            });
+        }
         if (id !== tool.id || id !== tool.toolCallId) {
             ctx.addIssue({
                 code: "custom",
@@ -1119,6 +1306,15 @@ const sessionProtocolSnapshotSchema = z
             }
         }
     }
+    for (const [id, turn] of Object.entries(snapshot.turns)) {
+        if (id !== turn.userHistoryEntryId) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["turns", id],
+                message: `turn map key '${id}' does not match embedded user history entry id '${turn.userHistoryEntryId}'`,
+            });
+        }
+    }
     for (const [id, agent] of Object.entries(snapshot.agents)) {
         if (id !== agent.id) {
             ctx.addIssue({
@@ -1136,12 +1332,7 @@ const sessionProtocolSnapshotSchema = z
                 message: `facet map key '${id}' does not match embedded id '${facet.id}'`,
             });
         }
-        const subjectExists = facet.subject.type === "session" ||
-            (facet.subject.type === "message" && messagesById.has(facet.subject.id)) ||
-            (facet.subject.type === "tool" && snapshot.tools[facet.subject.id] !== undefined) ||
-            (facet.subject.type === "agent" && snapshot.agents[facet.subject.id] !== undefined) ||
-            (facet.subject.type === "operation" && operationIds.has(facet.subject.id));
-        if (!subjectExists) {
+        if (!subjectExists(facet.subject)) {
             ctx.addIssue({
                 code: "custom",
                 path: ["facets", id, "subject"],
@@ -1150,18 +1341,41 @@ const sessionProtocolSnapshotSchema = z
         }
     }
 });
-const sessionProtocolDeltaReasonSchema = z.enum([
-    "user-message",
-    "assistant-stream",
-    "assistant-message",
-    "tool-run",
-    "tool-result",
-    "notice",
-    "agent-run",
-    "maintenance",
-    "configuration",
-    "goal",
-    "recovery",
+const sessionProtocolDeltaCauseSchema = z.union([
+    z
+        .object({
+        type: z.enum([
+            "user-message",
+            "assistant-stream",
+            "assistant-message",
+            "tool-run",
+            "tool-result",
+            "notice",
+            "agent-run",
+            "maintenance",
+            "configuration",
+            "goal",
+        ]),
+    })
+        .strip(),
+    z
+        .object({
+        type: z.literal("compaction"),
+        previousEpoch: z.number().int().positive(),
+        epoch: z.number().int().positive(),
+        kind: z.enum(["auto", "manual"]),
+        cutType: z.enum(["turn-boundary", "split-turn"]),
+        retainedMessageCount: z.number().int().nonnegative(),
+    })
+        .strip(),
+    z
+        .object({
+        type: z.literal("rewind"),
+        epoch: z.number().int().positive(),
+        cutoffSequence: z.number().int().nonnegative(),
+    })
+        .strip(),
+    z.object({ type: z.literal("resync") }).strip(),
 ]);
 const sessionProtocolChangeSchema = z.discriminatedUnion("type", [
     z
@@ -1194,11 +1408,16 @@ const sessionProtocolChangeSchema = z.discriminatedUnion("type", [
         settings: sessionProtocolSettingsSnapshotSchema,
     })
         .strip(),
+    z
+        .object({
+        type: z.literal("turn.set"),
+        turn: sessionProtocolTurnRecordSchema,
+    })
+        .strip(),
     z
         .object({
         type: z.literal("message.append"),
         message: sessionProtocolMessageSchema,
-        timelineItem: sessionProtocolTimelineItemSchema.optional(),
     })
         .strip(),
     z
@@ -1224,14 +1443,15 @@ const sessionProtocolChangeSchema = z.discriminatedUnion("type", [
         .strip(),
     z
         .object({
-        type: z.literal("timeline.replace"),
-        item: sessionProtocolTimelineItemSchema,
+        type: z.literal("timeline.remove"),
+        id: nonEmptyStringSchema,
     })
         .strip(),
     z
         .object({
-        type: z.literal("timeline.remove"),
-        id: nonEmptyStringSchema,
+        type: z.literal("timeline.advance"),
+        epoch: z.number().int().positive(),
+        sequence: z.number().int().positive(),
     })
         .strip(),
     z
@@ -1246,6 +1466,18 @@ const sessionProtocolChangeSchema = z.discriminatedUnion("type", [
         id: nonEmptyStringSchema,
     })
         .strip(),
+    z
+        .object({
+        type: z.literal("operation.set"),
+        operation: sessionProtocolOperationSchema,
+    })
+        .strip(),
+    z
+        .object({
+        type: z.literal("operation.remove"),
+        id: nonEmptyStringSchema,
+    })
+        .strip(),
     z
         .object({
         type: z.literal("agent.set"),
@@ -1292,7 +1524,7 @@ const sessionProtocolDeltaMessageSchema = z
     sessionId: nonEmptyStringSchema,
     fromRevision: z.number().int().positive().nullable(),
     toRevision: z.number().int().positive(),
-    reason: sessionProtocolDeltaReasonSchema,
+    cause: sessionProtocolDeltaCauseSchema,
     delta: sessionProtocolDeltaSchema,
 })
     .strip()
@@ -1334,6 +1566,29 @@ const sessionProtocolDeltaMessageSchema = z
             message: "snapshot.reset revision must equal toRevision",
         });
     }
+    if (message.cause.type === "compaction") {
+        if (message.delta.type !== "snapshot.reset" ||
+            message.cause.epoch !== message.cause.previousEpoch + 1 ||
+            message.delta.snapshot.timeline.epoch !== message.cause.epoch) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["cause"],
+                message: "compaction cause must reset the snapshot to the next timeline epoch",
+            });
+        }
+    }
+    if (message.cause.type === "rewind") {
+        const { cutoffSequence, epoch } = message.cause;
+        if (message.delta.type !== "snapshot.reset" ||
+            message.delta.snapshot.timeline.epoch !== epoch ||
+            message.delta.snapshot.timeline.items.some((item) => item.sequence > cutoffSequence)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["cause"],
+                message: "rewind cause must reset and truncate the active timeline epoch",
+            });
+        }
+    }
 });
 const sessionProtocolEphemeralAgentThreadUpdateEventSchema = z
     .object({
@@ -1349,7 +1604,27 @@ const sessionProtocolEphemeralAgentThreadUpdateEventSchema = z
         .strip(),
 })
     .strip();
-const sessionProtocolEphemeralEventSchema = sessionProtocolEphemeralAgentThreadUpdateEventSchema;
+const sessionProtocolFeedbackEventSchema = z
+    .object({
+    type: z.literal("feedback.notice"),
+    title: noticeTitleSchema,
+    tone: z.enum(["default", "error"]),
+    presentation: z.literal("footer"),
+    durationMs: z.number().int().positive().max(60_000),
+})
+    .strip();
+const sessionProtocolEphemeralTimelineEventSchema = z
+    .object({
+    type: z.literal("timeline.item"),
+    epoch: z.number().int().positive(),
+    item: sessionProtocolTimelineItemSchema.refine((item) => item.type === "notice", "ephemeral timeline items must be notices"),
+})
+    .strip();
+const sessionProtocolEphemeralEventSchema = z.union([
+    sessionProtocolEphemeralAgentThreadUpdateEventSchema,
+    sessionProtocolFeedbackEventSchema,
+    sessionProtocolEphemeralTimelineEventSchema,
+]);
 const sessionProtocolEphemeralMessageSchema = z
     .object({
     version: z.literal(SESSION_PROTOCOL_VERSION),
@@ -1594,7 +1869,7 @@ export function createSessionProtocolDeltaMessage(options) {
         sessionId: options.sessionId,
         fromRevision: options.fromRevision,
         toRevision: options.toRevision,
-        reason: options.reason,
+        cause: options.cause,
         delta: options.delta,
     };
     const parsedMessage = sessionProtocolDeltaMessageSchema.safeParse(message);
@@ -1629,11 +1904,33 @@ export function createSessionProtocolPendingUserMessagesMessage(options) {
     }
     return parsedMessage.data;
 }
+function validateSnapshotResetCause(snapshot, message) {
+    if (message.delta.type !== "snapshot.reset") {
+        return;
+    }
+    if (message.cause.type === "compaction" &&
+        message.cause.previousEpoch !== snapshot.timeline.epoch) {
+        throw new Error(`compaction delta previous epoch ${message.cause.previousEpoch} does not match current timeline epoch ${snapshot.timeline.epoch}`);
+    }
+    if (message.cause.type !== "rewind") {
+        return;
+    }
+    if (message.cause.epoch !== snapshot.timeline.epoch) {
+        throw new Error(`rewind delta epoch ${message.cause.epoch} does not match current timeline epoch ${snapshot.timeline.epoch}`);
+    }
+    if (message.cause.cutoffSequence > snapshot.timeline.sequence) {
+        throw new Error(`rewind delta cutoff sequence ${message.cause.cutoffSequence} exceeds current timeline sequence ${snapshot.timeline.sequence}`);
+    }
+    if (message.delta.snapshot.timeline.sequence !== snapshot.timeline.sequence) {
+        throw new Error(`rewind delta timeline sequence ${message.delta.snapshot.timeline.sequence} does not preserve current timeline sequence ${snapshot.timeline.sequence}`);
+    }
+}
 export function applySessionProtocolDelta(snapshot, message) {
     if (message.sessionId !== snapshot.sessionId) {
         throw new Error(`session delta targets '${message.sessionId}' but current snapshot is '${snapshot.sessionId}'`);
     }
     if (message.delta.type === "snapshot.reset") {
+        validateSnapshotResetCause(snapshot, message);
         return structuredClone(message.delta.snapshot);
     }
     if (message.fromRevision !== snapshot.revision) {
@@ -1667,11 +1964,11 @@ export function applySessionProtocolDelta(snapshot, message) {
             case "settings.set":
                 next.settings = structuredClone(change.settings);
                 break;
+            case "turn.set":
+                setSessionProtocolTurn(next.turns, change.turn);
+                break;
             case "message.append":
                 next.messages.push(structuredClone(change.message));
-                if (change.timelineItem) {
-                    next.timeline.push(structuredClone(change.timelineItem));
-                }
                 break;
             case "message.replace": {
                 const index = next.messages.findIndex((entry) => entry.id === change.message.id);
@@ -1688,20 +1985,23 @@ export function applySessionProtocolDelta(snapshot, message) {
                 break;
             }
             case "timeline.append":
-                next.timeline.push(structuredClone(change.item));
-                break;
-            case "timeline.replace": {
-                const index = next.timeline.findIndex((item) => item.id === change.item.id);
-                if (index === -1) {
-                    next.timeline.push(structuredClone(change.item));
-                }
-                else {
-                    next.timeline[index] = structuredClone(change.item);
+                if (change.item.sequence <= next.timeline.sequence) {
+                    throw new Error(`timeline append sequence ${change.item.sequence} must exceed current timeline sequence ${next.timeline.sequence}`);
                 }
+                next.timeline.items.push(structuredClone(change.item));
+                next.timeline.sequence = change.item.sequence;
                 break;
-            }
             case "timeline.remove":
-                next.timeline = next.timeline.filter((item) => item.id !== change.id);
+                next.timeline.items = next.timeline.items.filter((item) => item.id !== change.id);
+                break;
+            case "timeline.advance":
+                if (next.timeline.epoch !== change.epoch) {
+                    throw new Error("timeline advance epoch does not match the active epoch");
+                }
+                if (change.sequence <= next.timeline.sequence) {
+                    throw new Error(`timeline advance sequence ${change.sequence} must exceed current timeline sequence ${next.timeline.sequence}`);
+                }
+                next.timeline.sequence = change.sequence;
                 break;
             case "tool.set":
                 next.tools[change.tool.id] = structuredClone(change.tool);
@@ -1709,6 +2009,12 @@ export function applySessionProtocolDelta(snapshot, message) {
             case "tool.remove":
                 delete next.tools[change.id];
                 break;
+            case "operation.set":
+                next.operations[change.operation.id] = structuredClone(change.operation);
+                break;
+            case "operation.remove":
+                delete next.operations[change.id];
+                break;
             case "agent.set":
                 next.agents[change.agent.id] = structuredClone(change.agent);
                 break;
@@ -1741,6 +2047,7 @@ function changeCanInvalidateSnapshot(snapshot, change) {
         case "goal.set":
         case "cost.set":
         case "settings.set":
+        case "turn.set":
         case "agent.set":
             return false;
         case "tool.set": {
@@ -1751,17 +2058,16 @@ function changeCanInvalidateSnapshot(snapshot, change) {
             const previous = snapshot.facets[change.facet.id];
             return !previous || !hasSameFacetSubject(previous, change.facet);
         }
-        case "timeline.replace": {
-            const previous = snapshot.timeline.find((item) => item.id === change.item.id);
-            return !previous || !hasSameTimelineReferences(previous, change.item);
-        }
         case "agent-state.set":
         case "message.append":
         case "message.replace":
         case "message.content.append":
         case "timeline.append":
         case "timeline.remove":
+        case "timeline.advance":
         case "tool.remove":
+        case "operation.set":
+        case "operation.remove":
         case "agent.remove":
         case "facet.remove":
             return true;
@@ -1791,25 +2097,41 @@ function hasSameFacetSubject(previous, facet) {
         (previous.subject.type === "session" ||
             (facet.subject.type !== "session" && previous.subject.id === facet.subject.id)));
 }
-function hasSameTimelineReferences(previous, item) {
-    if (previous.type !== item.type)
-        return false;
-    if (previous.type === "message" && item.type === "message") {
-        return previous.messageId === item.messageId;
+function setSessionProtocolTurn(turns, turn) {
+    const previous = Object.hasOwn(turns, turn.userHistoryEntryId)
+        ? turns[turn.userHistoryEntryId]
+        : undefined;
+    if (previous?.state === "settled" && JSON.stringify(previous) !== JSON.stringify(turn)) {
+        throw new Error(`settled turn '${turn.userHistoryEntryId}' cannot be changed`);
     }
-    return true;
+    Object.defineProperty(turns, turn.userHistoryEntryId, {
+        configurable: true,
+        enumerable: true,
+        value: structuredClone(turn),
+        writable: true,
+    });
 }
 function applyKeyedRecordDelta(snapshot, message) {
     if (message.delta.type !== "snapshot.patch") {
         return undefined;
     }
+    let nextTurns;
     let nextTools;
+    let nextOperations;
     let nextAgents;
     let nextFacets;
+    const cloneTurns = () => {
+        nextTurns ??= { ...snapshot.turns };
+        return nextTurns;
+    };
     const cloneTools = () => {
         nextTools ??= { ...snapshot.tools };
         return nextTools;
     };
+    const cloneOperations = () => {
+        nextOperations ??= { ...snapshot.operations };
+        return nextOperations;
+    };
     const cloneAgents = () => {
         nextAgents ??= { ...snapshot.agents };
         return nextAgents;
@@ -1820,12 +2142,21 @@ function applyKeyedRecordDelta(snapshot, message) {
     };
     for (const change of message.delta.changes) {
         switch (change.type) {
+            case "turn.set":
+                setSessionProtocolTurn(cloneTurns(), change.turn);
+                break;
             case "tool.set":
                 cloneTools()[change.tool.id] = structuredClone(change.tool);
                 break;
             case "tool.remove":
                 delete cloneTools()[change.id];
                 break;
+            case "operation.set":
+                cloneOperations()[change.operation.id] = structuredClone(change.operation);
+                break;
+            case "operation.remove":
+                delete cloneOperations()[change.id];
+                break;
             case "agent.set":
                 cloneAgents()[change.agent.id] = structuredClone(change.agent);
                 break;
@@ -1845,7 +2176,9 @@ function applyKeyedRecordDelta(snapshot, message) {
     return {
         ...snapshot,
         revision: message.toRevision,
+        ...(nextTurns ? { turns: nextTurns } : {}),
         ...(nextTools ? { tools: nextTools } : {}),
+        ...(nextOperations ? { operations: nextOperations } : {}),
         ...(nextAgents ? { agents: nextAgents } : {}),
         ...(nextFacets ? { facets: nextFacets } : {}),
     };
@@ -2730,8 +3063,8 @@ function parseSessionProtocolDeltaMessage(payload) {
         if (hasIssue(deltaMessage.error, ["toRevision"])) {
             return fail("session.delta.toRevision must be a positive integer");
         }
-        if (hasIssue(deltaMessage.error, ["reason"])) {
-            return fail("session.delta.reason is invalid");
+        if (hasIssue(deltaMessage.error, ["cause"])) {
+            return fail("session.delta.cause is invalid");
         }
         if (hasIssue(deltaMessage.error, ["delta"])) {
             return fail("session.delta.delta is invalid");
@@ -2746,7 +3079,7 @@ function parseSessionProtocolDeltaMessage(payload) {
             sessionId: deltaMessage.data.sessionId,
             fromRevision: deltaMessage.data.fromRevision,
             toRevision: deltaMessage.data.toRevision,
-            reason: deltaMessage.data.reason,
+            cause: deltaMessage.data.cause,
             delta: deltaMessage.data.delta,
         },
     };