@markusylisiurunen/tau 0.3.32 → 0.3.34

package/dist/protocol/session_protocol.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export const SESSION_PROTOCOL_VERSION = 3;
+export const SESSION_PROTOCOL_VERSION = 5;
 export const SESSION_PROTOCOL_MAX_EXEC_CAPTURE_BYTES = 24 * 1024 * 1024;
 export const SESSION_PROTOCOL_MAX_EXEC_STDIN_BYTES = 16 * 1024 * 1024;
 export const SESSION_PROTOCOL_METHODS = [
@@ -25,9 +25,8 @@ export const SESSION_PROTOCOL_METHODS = [
     "session.autocompletePaths",
     "session.reload",
     "session.compact",
-    "session.prune",
     "session.rewind",
-    "session.terminateSubagent",
+    "session.interruptSubagent",
     "session.ephemeral.create",
     "session.ephemeral.submit",
     "session.ephemeral.close",
@@ -342,10 +341,16 @@ const sessionProtocolInitializeParamsSchema = z
 const sessionProtocolUserMessageParamsSchema = z
     .object({
     sessionId: nonEmptyStringSchema,
-    text: z.string(),
+    text: nonEmptyStringSchema,
     historyEntryId: nonEmptyStringSchema.optional(),
 })
     .strip();
+const sessionProtocolSteerParamsSchema = z
+    .object({
+    sessionId: nonEmptyStringSchema,
+    text: nonEmptyStringSchema,
+})
+    .strip();
 const sessionProtocolRecordParamsSchema = sessionProtocolUserMessageParamsSchema;
 const sessionProtocolExecParamsSchema = z
     .object({
@@ -442,21 +447,13 @@ const sessionProtocolCompactParamsSchema = z
     guidance: z.string().optional(),
 })
     .strip();
-const sessionProtocolPruneParamsSchema = z
-    .object({
-    sessionId: nonEmptyStringSchema,
-    strategy: z.enum(["earliest", "largest", "smart"]),
-    fraction: z.number().min(0).max(1),
-    guidance: z.string().optional(),
-})
-    .strip();
 const sessionProtocolRewindParamsSchema = z
     .object({
     sessionId: nonEmptyStringSchema,
     historyEntryId: nonEmptyStringSchema,
 })
     .strip();
-const sessionProtocolTerminateSubagentParamsSchema = z
+const sessionProtocolInterruptSubagentParamsSchema = z
     .object({
     sessionId: nonEmptyStringSchema,
     subagentId: nonEmptyStringSchema,
@@ -755,7 +752,7 @@ const sessionProtocolNoticeSchema = z
     .strip();
 const sessionProtocolOperationSchema = z
     .object({
-    kind: z.enum(["auto-compaction", "manual-compaction", "prune", "reload", "rewind"]),
+    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(),
@@ -828,25 +825,86 @@ const sessionProtocolAgentUsageSchema = z
     contextWindow: z.number().finite(),
 })
     .strip();
+const sessionProtocolAgentFailedRunFailureSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.enum(["auto-compaction-failed", "model-subturn-limit", "runtime-error"]),
+        message: z.string(),
+    })
+        .strip(),
+    z
+        .object({
+        kind: z.literal("provider-error"),
+        message: z.string(),
+        stopReason: z.string(),
+    })
+        .strip(),
+]);
+const sessionProtocolAgentInterruptedRunFailureSchema = z
+    .object({
+    kind: z.literal("interrupted"),
+    message: z.string(),
+})
+    .strip();
+const sessionProtocolAgentRunStateBaseSchema = z.object({
+    revision: z.number().int().positive(),
+    startedAt: z.number().finite(),
+    interruptRequested: z.boolean(),
+});
+const sessionProtocolAgentRunStateSchema = z.discriminatedUnion("status", [
+    sessionProtocolAgentRunStateBaseSchema.extend({ status: z.literal("running") }).strip(),
+    sessionProtocolAgentRunStateBaseSchema
+        .extend({
+        status: z.literal("succeeded"),
+        finishedAt: z.number().finite(),
+        response: z.string(),
+    })
+        .strip(),
+    sessionProtocolAgentRunStateBaseSchema
+        .extend({
+        status: z.literal("failed"),
+        finishedAt: z.number().finite(),
+        failure: sessionProtocolAgentFailedRunFailureSchema,
+    })
+        .strip(),
+    sessionProtocolAgentRunStateBaseSchema
+        .extend({
+        status: z.literal("interrupted"),
+        finishedAt: z.number().finite(),
+        failure: sessionProtocolAgentInterruptedRunFailureSchema,
+    })
+        .strip(),
+]);
 const sessionProtocolAgentRunSchema = z
     .object({
     id: nonEmptyStringSchema,
     name: nonEmptyStringSchema,
     title: nonEmptyStringSchema,
-    status: z.enum(["running", "succeeded", "failed", "cancelled"]),
-    modelLabel: z.string().optional(),
+    availability: z.enum(["running", "idle"]),
+    model: z
+        .object({
+        provider: nonEmptyStringSchema,
+        id: nonEmptyStringSchema,
+        reasoning: sessionProtocolReasoningEffortSchema,
+    })
+        .strip(),
+    workingDirectory: nonEmptyStringSchema,
+    createdAt: z.number().finite(),
+    run: sessionProtocolAgentRunStateSchema,
     costTotal: z.number().finite(),
-    turns: z.number().finite(),
-    toolCalls: z.number().finite(),
     usage: sessionProtocolAgentUsageSchema,
-    startedAt: z.number().finite(),
-    finishedAt: z.number().finite().optional(),
-    abortRequested: z.boolean(),
-    progress: z.string().optional(),
-    finalText: z.string().optional(),
-    error: z.string().optional(),
 })
-    .strip();
+    .strip()
+    .superRefine((agent, ctx) => {
+    const running = agent.run.status === "running";
+    if ((agent.availability === "running") !== running) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["availability"],
+            message: "agent availability must match latest run status",
+        });
+    }
+});
 const sessionProtocolFacetSubjectSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("session") }).strip(),
     z.object({ type: z.literal("message"), id: nonEmptyStringSchema }).strip(),
@@ -863,10 +921,25 @@ const sessionProtocolFacetSchema = z
     data: z.record(z.string(), z.unknown()),
 })
     .strip();
+const sessionProtocolAgentStateSnapshotSchema = z
+    .object({
+    revision: z.number().int().nonnegative(),
+    contextEpoch: nonEmptyStringSchema,
+    usageCheckpoint: z
+        .object({
+        historyEntryId: nonEmptyStringSchema,
+        contextEpoch: nonEmptyStringSchema,
+        tokens: z.number().int().nonnegative(),
+    })
+        .strip()
+        .optional(),
+})
+    .strip();
 const sessionProtocolSnapshotSchema = z
     .object({
     sessionId: nonEmptyStringSchema,
     revision: z.number().int().positive(),
+    agentState: sessionProtocolAgentStateSnapshotSchema,
     lifecycle: sessionProtocolSessionLifecycleSchema,
     costTotal: z.number().nonnegative(),
     settings: sessionProtocolSettingsSnapshotSchema,
@@ -899,6 +972,31 @@ const sessionProtocolSnapshotSchema = z
         }
         messagesById.set(message.id, message);
     }
+    const checkpoint = snapshot.agentState.usageCheckpoint;
+    if (checkpoint) {
+        if (checkpoint.contextEpoch !== snapshot.agentState.contextEpoch) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["agentState", "usageCheckpoint", "contextEpoch"],
+                message: "usage checkpoint context epoch must match agent state",
+            });
+        }
+        const checkpointMessage = messagesById.get(checkpoint.historyEntryId);
+        const checkpointAssistant = checkpointMessage?.message.role === "assistant" && "stopReason" in checkpointMessage.message
+            ? checkpointMessage.message
+            : undefined;
+        if (!checkpointMessage?.modelVisible ||
+            checkpointMessage.state !== "committed" ||
+            !checkpointAssistant ||
+            checkpointAssistant.stopReason === "aborted" ||
+            checkpointAssistant.stopReason === "error") {
+            ctx.addIssue({
+                code: "custom",
+                path: ["agentState", "usageCheckpoint", "historyEntryId"],
+                message: "usage checkpoint must reference a completed model-visible assistant response",
+            });
+        }
+    }
     const timelineIds = new Set();
     const operationIds = new Set();
     for (const item of snapshot.timeline) {
@@ -1043,6 +1141,12 @@ const sessionProtocolDeltaReasonSchema = z.enum([
     "recovery",
 ]);
 const sessionProtocolChangeSchema = z.discriminatedUnion("type", [
+    z
+        .object({
+        type: z.literal("agent-state.set"),
+        agentState: sessionProtocolAgentStateSnapshotSchema,
+    })
+        .strip(),
     z
         .object({
         type: z.literal("lifecycle.set"),
@@ -1346,17 +1450,6 @@ const sessionProtocolCompactResultSchema = z
     includedLastAssistant: z.boolean(),
 })
     .strip();
-const sessionProtocolPruneResultSchema = z
-    .object({
-    snapshot: sessionProtocolSnapshotSchema,
-    message: nonEmptyStringSchema,
-    noop: z.boolean(),
-    bashResultsPruned: z.number().int().nonnegative(),
-    editCallsPruned: z.number().int().nonnegative(),
-    editResultsPruned: z.number().int().nonnegative(),
-    bytesPruned: z.number().int().nonnegative(),
-})
-    .strip();
 const sessionProtocolRewindResultSchema = z
     .object({
     snapshot: sessionProtocolSnapshotSchema,
@@ -1394,7 +1487,7 @@ const sessionProtocolUnobserveResultSchema = z
     unobserved: z.literal(true),
 })
     .strip();
-const sessionProtocolTerminateSubagentResultSchema = z
+const sessionProtocolInterruptSubagentResultSchema = z
     .object({
     found: z.boolean(),
 })
@@ -1521,12 +1614,16 @@ export function applySessionProtocolDelta(snapshot, message) {
     }
     const keyedPatchSnapshot = applyKeyedRecordDelta(snapshot, message);
     if (keyedPatchSnapshot) {
+        validateAppliedSnapshotChanges(snapshot, keyedPatchSnapshot, message.delta.changes);
         return keyedPatchSnapshot;
     }
     const next = structuredClone(snapshot);
     next.revision = message.toRevision;
     for (const change of message.delta.changes) {
         switch (change.type) {
+            case "agent-state.set":
+                next.agentState = structuredClone(change.agentState);
+                break;
             case "lifecycle.set":
                 next.lifecycle = change.lifecycle;
                 break;
@@ -1592,8 +1689,81 @@ export function applySessionProtocolDelta(snapshot, message) {
                 break;
         }
     }
+    validateAppliedSnapshotChanges(snapshot, next, message.delta.changes);
     return next;
 }
+function validateAppliedSnapshotChanges(previous, snapshot, changes) {
+    if (!changes.some((change) => changeCanInvalidateSnapshot(previous, change))) {
+        return;
+    }
+    const parsed = sessionProtocolSnapshotSchema.safeParse(snapshot);
+    if (!parsed.success) {
+        throw new Error(`session delta produced an invalid snapshot: ${formatZodError(parsed.error)}`);
+    }
+}
+function changeCanInvalidateSnapshot(snapshot, change) {
+    switch (change.type) {
+        case "lifecycle.set":
+        case "cost.set":
+        case "settings.set":
+        case "agent.set":
+            return false;
+        case "tool.set": {
+            const previous = snapshot.tools[change.tool.id];
+            return !previous || !hasSameToolReferences(previous, change.tool);
+        }
+        case "facet.set": {
+            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 "tool.remove":
+        case "agent.remove":
+        case "facet.remove":
+            return true;
+    }
+}
+function hasSameToolReferences(previous, tool) {
+    if (previous.id !== tool.id ||
+        previous.toolCallId !== tool.toolCallId ||
+        previous.toolName !== tool.toolName ||
+        previous.facetIds.length !== tool.facetIds.length ||
+        previous.facetIds.some((id, index) => id !== tool.facetIds[index])) {
+        return false;
+    }
+    if (previous.status === "streaming" || tool.status === "streaming") {
+        return (previous.status === "streaming" &&
+            tool.status === "streaming" &&
+            previous.origin.messageId === tool.origin.messageId &&
+            previous.origin.contentIndex === tool.origin.contentIndex);
+    }
+    return (previous.call.messageId === tool.call.messageId &&
+        previous.call.contentIndex === tool.call.contentIndex &&
+        previous.resultMessageId === tool.resultMessageId);
+}
+function hasSameFacetSubject(previous, facet) {
+    return (previous.id === facet.id &&
+        previous.subject.type === facet.subject.type &&
+        (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;
+    }
+    return true;
+}
 function applyKeyedRecordDelta(snapshot, message) {
     if (message.delta.type !== "snapshot.patch") {
         return undefined;
@@ -1927,8 +2097,9 @@ export function validateSessionProtocolParams(method, params) {
             return validateRecordParams(params);
         case "session.submit":
         case "session.queue":
-        case "session.steer":
             return validateUserMessageParams(method, params);
+        case "session.steer":
+            return validateSteerParams(params);
         case "session.exec":
             return validateExecParams(params);
         case "session.cancelExec":
@@ -1953,12 +2124,10 @@ export function validateSessionProtocolParams(method, params) {
             return validateAutocompletePathsParams(params);
         case "session.compact":
             return validateCompactParams(params);
-        case "session.prune":
-            return validatePruneParams(params);
         case "session.rewind":
             return validateRewindParams(params);
-        case "session.terminateSubagent":
-            return validateTerminateSubagentParams(params);
+        case "session.interruptSubagent":
+            return validateInterruptSubagentParams(params);
         case "session.ephemeral.create":
             return validateEphemeralCreateParams(params);
         case "session.ephemeral.submit":
@@ -1994,12 +2163,10 @@ export function validateSessionProtocolResult(method, result) {
             return validateResult(method, result, sessionProtocolReloadResultSchema);
         case "session.compact":
             return validateResult(method, result, sessionProtocolCompactResultSchema);
-        case "session.prune":
-            return validateResult(method, result, sessionProtocolPruneResultSchema);
         case "session.rewind":
             return validateResult(method, result, sessionProtocolRewindResultSchema);
-        case "session.terminateSubagent":
-            return validateResult(method, result, sessionProtocolTerminateSubagentResultSchema);
+        case "session.interruptSubagent":
+            return validateResult(method, result, sessionProtocolInterruptSubagentResultSchema);
         case "session.ephemeral.create":
             return validateResult(method, result, sessionProtocolEphemeralCreateResultSchema);
         case "session.ephemeral.submit":
@@ -2082,7 +2249,7 @@ function validateUserMessageParams(method, params) {
             : hasIssue(parsed.error, ["sessionId"])
                 ? `${method} params.sessionId must be a non-empty string`
                 : hasIssue(parsed.error, ["text"])
-                    ? `${method} params.text must be a string`
+                    ? `${method} params.text must be a non-empty string`
                     : hasIssue(parsed.error, ["historyEntryId"])
                         ? `${method} params.historyEntryId must be a non-empty string when provided`
                         : `${method} params are invalid: ${formatZodError(parsed.error)}`;
@@ -2099,6 +2266,20 @@ function validateUserMessageParams(method, params) {
         },
     };
 }
+function validateSteerParams(params) {
+    const parsed = sessionProtocolSteerParamsSchema.safeParse(params);
+    if (!parsed.success) {
+        const message = hasIssue(parsed.error, [], "invalid_type")
+            ? "session.steer params must be an object"
+            : hasIssue(parsed.error, ["sessionId"])
+                ? "session.steer params.sessionId must be a non-empty string"
+                : hasIssue(parsed.error, ["text"])
+                    ? "session.steer params.text must be a non-empty string"
+                    : `session.steer params are invalid: ${formatZodError(parsed.error)}`;
+        return invalidParams(message);
+    }
+    return { ok: true, value: parsed.data };
+}
 function validateRecordParams(params) {
     const parsed = sessionProtocolRecordParamsSchema.safeParse(params);
     if (!parsed.success) {
@@ -2107,7 +2288,7 @@ function validateRecordParams(params) {
             : hasIssue(parsed.error, ["sessionId"])
                 ? "session.record params.sessionId must be a non-empty string"
                 : hasIssue(parsed.error, ["text"])
-                    ? "session.record params.text must be a string"
+                    ? "session.record params.text must be a non-empty string"
                     : hasIssue(parsed.error, ["historyEntryId"])
                         ? "session.record params.historyEntryId must be a non-empty string when provided"
                         : `session.record params are invalid: ${formatZodError(parsed.error)}`;
@@ -2288,32 +2469,6 @@ function validateCompactParams(params) {
         },
     };
 }
-function validatePruneParams(params) {
-    const parsed = sessionProtocolPruneParamsSchema.safeParse(params);
-    if (!parsed.success) {
-        const message = hasIssue(parsed.error, [], "invalid_type")
-            ? "session.prune params must be an object"
-            : hasIssue(parsed.error, ["sessionId"])
-                ? "session.prune params.sessionId must be a non-empty string"
-                : hasIssue(parsed.error, ["strategy"])
-                    ? "session.prune params.strategy must be 'earliest', 'largest', or 'smart'"
-                    : hasIssue(parsed.error, ["fraction"])
-                        ? "session.prune params.fraction must be a number between 0 and 1"
-                        : hasIssue(parsed.error, ["guidance"])
-                            ? "session.prune params.guidance must be a string when provided"
-                            : `session.prune params are invalid: ${formatZodError(parsed.error)}`;
-        return invalidParams(message);
-    }
-    return {
-        ok: true,
-        value: {
-            sessionId: parsed.data.sessionId,
-            strategy: parsed.data.strategy,
-            fraction: parsed.data.fraction,
-            ...(parsed.data.guidance !== undefined ? { guidance: parsed.data.guidance } : {}),
-        },
-    };
-}
 function validateRewindParams(params) {
     const parsed = sessionProtocolRewindParamsSchema.safeParse(params);
     if (!parsed.success) {
@@ -2334,16 +2489,16 @@ function validateRewindParams(params) {
         },
     };
 }
-function validateTerminateSubagentParams(params) {
-    const parsed = sessionProtocolTerminateSubagentParamsSchema.safeParse(params);
+function validateInterruptSubagentParams(params) {
+    const parsed = sessionProtocolInterruptSubagentParamsSchema.safeParse(params);
     if (!parsed.success) {
         const message = hasIssue(parsed.error, [], "invalid_type")
-            ? "session.terminateSubagent params must be an object"
+            ? "session.interruptSubagent params must be an object"
             : hasIssue(parsed.error, ["sessionId"])
-                ? "session.terminateSubagent params.sessionId must be a non-empty string"
+                ? "session.interruptSubagent params.sessionId must be a non-empty string"
                 : hasIssue(parsed.error, ["subagentId"])
-                    ? "session.terminateSubagent params.subagentId must be a non-empty string"
-                    : `session.terminateSubagent params are invalid: ${formatZodError(parsed.error)}`;
+                    ? "session.interruptSubagent params.subagentId must be a non-empty string"
+                    : `session.interruptSubagent params are invalid: ${formatZodError(parsed.error)}`;
         return invalidParams(message);
     }
     return {