@roll-agent/protocol 0.4.1 → 0.6.0

package/dist/index.js

@@ -4,10 +4,14 @@ export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V12 = [
     "1.2",
     ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V11,
 ];
-export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS = [
+export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V13 = [
     "1.3",
     ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V12,
 ];
+export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS = [
+    "1.4",
+    ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V13,
+];
 export const RUNTIME_PROTOCOL_VERSION = SUPPORTED_RUNTIME_PROTOCOL_VERSIONS[0];
 export const RUNTIME_EVENT_NOTIFICATION = "runtime.event";
 export const RUNTIME_SERVER_REQUEST_CANCEL_NOTIFICATION = "runtime.serverRequest.cancel";
@@ -26,6 +30,10 @@ export const RUNTIME_V13_RECOVERY_SNAPSHOT_METADATA_MAX_CHARS = 1_024;
 export const RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS = 64;
 export const APPROVAL_EXPLANATION_PREVIEW_KEY = "explanation";
 export const APPROVAL_EXPLANATION_MAX_CHARS = 100;
+export const APPROVAL_DIFF_PREVIEW_KEY = "diff";
+export const FILE_CHANGE_DIFF_PATH_MAX_CHARS = 4_096;
+export const FILE_CHANGE_DIFF_UNIFIED_MAX_CHARS = 20_000;
+export const FILE_CHANGE_KINDS = ["create", "modify"];
 export const CLIENT_CAPABILITY_METHOD_MAX_COUNT = 64;
 export const CLIENT_CAPABILITY_METHOD_MAX_CHARS = 100;
 export const USER_INPUT_CONTROL_MAX_COUNT = 16;
@@ -35,6 +43,25 @@ export const USER_INPUT_DESCRIPTION_MAX_CHARS = 500;
 export const USER_INPUT_CHOICE_OPTION_MAX_COUNT = 50;
 export const USER_INPUT_TEXT_MAX_CHARS = 10_000;
 export const USER_INPUT_CANCEL_REASON_MAX_CHARS = 500;
+export const RUNTIME_V14_MAX_ATTACHMENT_BYTES = 16 * 1_024 * 1_024;
+export const RUNTIME_V14_MAX_TURN_ATTACHMENTS = 8;
+/**
+ * Chunk payloads are raw bytes before base64 framing. 2 MiB of raw data grows to about 2.7 MiB of
+ * base64 text, which keeps a full attachment.chunk request inside the 4 MiB stdio frame limit.
+ */
+export const RUNTIME_V14_MAX_ATTACHMENT_CHUNK_BYTES = 2 * 1_024 * 1_024;
+export const RUNTIME_V14_MAX_STAGED_ATTACHMENTS = 16;
+export const ATTACHMENT_FILE_NAME_MAX_CHARS = 255;
+export const SUPPORTED_ATTACHMENT_MEDIA_TYPES = [
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "application/pdf",
+    "text/plain",
+    "text/markdown",
+];
+export const ATTACHMENT_SOURCES = ["local-path", "chunks"];
 export const INTERACTION_SENSITIVITIES = ["normal"];
 export const RUNTIME_SERVER_REQUEST_METHODS = {
     approvalRequest: "approval.request",
@@ -56,6 +83,13 @@ export const USER_INPUT_CONTROL_TYPES = {
     choice: "choice",
 };
 export const RUNTIME_PROTOCOL_CAPABILITIES = {
+    "1.4": {
+        serverRequests: true,
+        serverRequestCapabilityNegotiation: true,
+        approvalResolvedEvents: true,
+        clientApprovalResponses: false,
+        requiredServerRequestMethods: [],
+    },
     "1.2": {
         serverRequests: true,
         serverRequestCapabilityNegotiation: true,
@@ -86,6 +120,7 @@ export const RUNTIME_PROTOCOL_CAPABILITIES = {
     },
 };
 export const REQUIRED_RUNTIME_SERVER_REQUEST_METHODS_BY_VERSION = {
+    "1.4": RUNTIME_PROTOCOL_CAPABILITIES["1.4"].requiredServerRequestMethods,
     "1.3": RUNTIME_PROTOCOL_CAPABILITIES["1.3"].requiredServerRequestMethods,
     "1.2": RUNTIME_PROTOCOL_CAPABILITIES["1.2"].requiredServerRequestMethods,
     "1.1": RUNTIME_PROTOCOL_CAPABILITIES["1.1"].requiredServerRequestMethods,
@@ -113,8 +148,12 @@ export const RUNTIME_METHODS = {
     turnCancel: "turn.cancel",
     approvalRespond: "approval.respond",
     operationGet: "operation.get",
+    attachmentStage: "attachment.stage",
+    attachmentChunk: "attachment.chunk",
+    attachmentCommit: "attachment.commit",
+    attachmentRelease: "attachment.release",
 };
-export const RUNTIME_FEATURES = [
+export const RUNTIME_FEATURES_V13 = [
     "thread-management",
     "snapshots",
     "turns",
@@ -124,6 +163,8 @@ export const RUNTIME_FEATURES = [
     "operation-projection",
     "process-local-sequence",
 ];
+export const RUNTIME_FEATURES_V14 = [...RUNTIME_FEATURES_V13, "attachments"];
+export const RUNTIME_FEATURES = RUNTIME_FEATURES_V14;
 export const RUNTIME_ERROR_CODES_V11 = {
     protocolVersionUnsupported: "PROTOCOL_VERSION_UNSUPPORTED",
     initializeRequired: "INITIALIZE_REQUIRED",
@@ -143,12 +184,24 @@ export const RUNTIME_ERROR_CODES_V12 = {
     ...RUNTIME_ERROR_CODES_V11,
     capabilityRevisionConflict: "CAPABILITY_REVISION_CONFLICT",
 };
-export const RUNTIME_ERROR_CODES = {
+export const RUNTIME_ERROR_CODES_V13 = {
     ...RUNTIME_ERROR_CODES_V12,
     eventCursorExpired: "EVENT_CURSOR_EXPIRED",
     eventCursorGap: "EVENT_CURSOR_GAP",
 };
-export const RUNTIME_ERROR_CODES_V13 = RUNTIME_ERROR_CODES;
+/** Runtime Protocol 1.4 error registry. Keep this object frozen. */
+export const RUNTIME_ERROR_CODES_V14 = {
+    ...RUNTIME_ERROR_CODES_V13,
+    attachmentNotFound: "ATTACHMENT_NOT_FOUND",
+    attachmentNotCommitted: "ATTACHMENT_NOT_COMMITTED",
+    attachmentTooLarge: "ATTACHMENT_TOO_LARGE",
+    attachmentTypeUnsupported: "ATTACHMENT_TYPE_UNSUPPORTED",
+    attachmentHashMismatch: "ATTACHMENT_HASH_MISMATCH",
+    attachmentQuotaExceeded: "ATTACHMENT_QUOTA_EXCEEDED",
+    attachmentUploadIncomplete: "ATTACHMENT_UPLOAD_INCOMPLETE",
+    attachmentPathRejected: "ATTACHMENT_PATH_REJECTED",
+};
+export const RUNTIME_ERROR_CODES = RUNTIME_ERROR_CODES_V14;
 export const TOOL_OUTCOME_KINDS = [
     "success",
     "user_rejected",
@@ -166,6 +219,7 @@ export const requestIdSchema = z.string().uuid().brand();
 export const streamIdSchema = z.string().uuid().brand();
 export const operationIdSchema = z.string().uuid().brand();
 export const runtimeEventIdSchema = z.string().uuid().brand();
+export const attachmentIdSchema = z.string().uuid().brand();
 export const runtimeEventCursorSchema = z
     .string()
     .max(128)
@@ -193,6 +247,23 @@ export const approvalExplanationSchema = z
     .trim()
     .min(1)
     .max(APPROVAL_EXPLANATION_MAX_CHARS);
+export const fileChangeDiffSchema = z
+    .object({
+    path: z.string().min(1).max(FILE_CHANGE_DIFF_PATH_MAX_CHARS),
+    change: z.enum(FILE_CHANGE_KINDS),
+    added: z.number().int().nonnegative(),
+    removed: z.number().int().nonnegative(),
+    hunks: z.number().int().nonnegative(),
+    unified: z.string().max(FILE_CHANGE_DIFF_UNIFIED_MAX_CHARS).optional(),
+    truncated: z.boolean(),
+})
+    .readonly();
+export const fileChangeDisplaySchema = z
+    .object({
+    text: z.string(),
+    diff: fileChangeDiffSchema,
+})
+    .readonly();
 function runtimeEventCursorParts(cursor) {
     const parsed = runtimeEventCursorSchema.parse(cursor);
     const [, eventLogId, threadSequence, eventId] = parsed.split(":");
@@ -279,7 +350,24 @@ export const runtimeLimitsV13Schema = z
 })
     .strict()
     .readonly();
-export const runtimeLimitsSchema = z.union([runtimeLimitsV13Schema, runtimeLimitsV12Schema]);
+export const runtimeLimitsV14Schema = z
+    .object({
+    maxFrameBytes: z.number().int().positive(),
+    maxPageSize: z.number().int().positive(),
+    eventReplay: z.literal(true),
+    idempotencyCacheEntries: z.number().int().positive(),
+    maxAttachmentBytes: z.number().int().positive(),
+    maxAttachmentChunkBytes: z.number().int().positive(),
+    maxTurnAttachments: z.number().int().positive(),
+    maxStagedAttachments: z.number().int().positive(),
+})
+    .strict()
+    .readonly();
+export const runtimeLimitsSchema = z.union([
+    runtimeLimitsV14Schema,
+    runtimeLimitsV13Schema,
+    runtimeLimitsV12Schema,
+]);
 export const initializeParamsSchema = z
     .object({
     protocolVersions: z.array(z.string().min(1)).min(1),
@@ -290,7 +378,12 @@ export const initializeParamsSchema = z
 const initializeResultCommonFields = {
     runtimeInstanceId: runtimeInstanceIdSchema,
     server: runtimeServerInfoSchema,
-    features: z.array(z.enum(RUNTIME_FEATURES)),
+    features: z.array(z.enum(RUNTIME_FEATURES_V13)),
+};
+const initializeResultV14Fields = {
+    runtimeInstanceId: runtimeInstanceIdSchema,
+    server: runtimeServerInfoSchema,
+    features: z.array(z.enum(RUNTIME_FEATURES_V14)),
 };
 /** Runtime Protocol 1.1/1.0 initialize result. Keep this schema frozen. */
 export const initializeResultV11Schema = z
@@ -318,8 +411,17 @@ export const initializeResultV13Schema = z
 })
     .strict()
     .readonly();
+export const initializeResultV14Schema = z
+    .object({
+    protocolVersion: z.literal("1.4"),
+    ...initializeResultV14Fields,
+    limits: runtimeLimitsV14Schema,
+})
+    .strict()
+    .readonly();
 /** Any currently supported Runtime Protocol initialize result. */
 export const initializeResultSchema = z.union([
+    initializeResultV14Schema,
     initializeResultV13Schema,
     initializeResultV12Schema,
     initializeResultV11Schema,
@@ -389,6 +491,20 @@ export const uiMessagePartSchema = z
 })
     .strict()
     .readonly();
+/**
+ * Safe attachment metadata inside a projected message. Carries no binary content and no
+ * filesystem path; bytes are derived from the persisted model message.
+ */
+export const uiMessageAttachmentPartSchema = z
+    .object({
+    type: z.literal("attachment"),
+    mediaType: z.string().min(1),
+    bytes: z.number().int().nonnegative(),
+    displayName: z.string().min(1).max(ATTACHMENT_FILE_NAME_MAX_CHARS).optional(),
+})
+    .strict()
+    .readonly();
+export const uiMessagePartV14Schema = z.union([uiMessagePartSchema, uiMessageAttachmentPartSchema]);
 export const uiMessageSchema = z
     .object({
     sequence: z.number().int().nonnegative(),
@@ -398,6 +514,15 @@ export const uiMessageSchema = z
 })
     .strict()
     .readonly();
+export const uiMessageV14Schema = z
+    .object({
+    sequence: z.number().int().nonnegative(),
+    role: z.enum(["user", "assistant"]),
+    createdAt: timestampSchema,
+    parts: z.array(uiMessagePartV14Schema),
+})
+    .strict()
+    .readonly();
 export const toolOutcomeSchema = z
     .object({
     kind: z.enum(TOOL_OUTCOME_KINDS),
@@ -454,6 +579,13 @@ export const messagePageSchema = z
 })
     .strict()
     .readonly();
+export const messagePageV14Schema = z
+    .object({
+    items: z.array(uiMessageV14Schema),
+    nextBeforeSequence: z.number().int().nonnegative().nullable(),
+})
+    .strict()
+    .readonly();
 export const operationPageSchema = z
     .object({
     items: z.array(operationViewSchema),
@@ -790,8 +922,20 @@ export const threadSnapshotV13Schema = z.union([
     threadSnapshotV13FullSchema,
     threadRecoverySnapshotV13Schema,
 ]);
+export const threadSnapshotV14FullSchema = z
+    .object({
+    ...threadSnapshotV12Fields,
+    messages: messagePageV14Schema,
+    eventCursor: runtimeEventCursorSchema.nullable(),
+})
+    .strict()
+    .readonly();
+export const threadSnapshotV14Schema = z.union([
+    threadSnapshotV14FullSchema,
+    threadRecoverySnapshotV13Schema,
+]);
 /** Latest Runtime Protocol snapshot. Use versioned schemas for compatibility. */
-export const threadSnapshotSchema = threadSnapshotV13Schema;
+export const threadSnapshotSchema = threadSnapshotV14Schema;
 const pageSizeSchema = z.number().int().min(1).max(500).default(100);
 const requestFields = { requestId: requestIdSchema };
 const threadRequestFields = { threadId: threadIdSchema };
@@ -898,6 +1042,105 @@ export const threadCapabilitiesResultSchema = z
 })
     .strict()
     .readonly();
+export const attachmentSourceSchema = z.enum(ATTACHMENT_SOURCES);
+export const attachmentMediaTypeSchema = z.enum(SUPPORTED_ATTACHMENT_MEDIA_TYPES);
+export const attachmentSha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
+export const attachmentFileNameSchema = z.string().min(1).max(ATTACHMENT_FILE_NAME_MAX_CHARS);
+export const ATTACHMENT_STATES = ["staged", "committed"];
+export const attachmentStateSchema = z.enum(ATTACHMENT_STATES);
+/**
+ * Safe attachment metadata. Never carries client filesystem paths or inline binary content; the
+ * displayName is a server-sanitized rendering of the client-declared fileName.
+ */
+export const attachmentDescriptorSchema = z
+    .object({
+    attachmentId: attachmentIdSchema,
+    fileName: attachmentFileNameSchema,
+    displayName: attachmentFileNameSchema,
+    mediaType: attachmentMediaTypeSchema,
+    bytes: z.number().int().positive().max(RUNTIME_V14_MAX_ATTACHMENT_BYTES),
+    sha256: attachmentSha256Schema,
+    source: attachmentSourceSchema,
+    createdAt: timestampSchema,
+})
+    .strict()
+    .readonly();
+export const attachmentStageParamsSchema = z
+    .object({
+    ...requestFields,
+    ...threadRequestFields,
+    fileName: attachmentFileNameSchema,
+    mediaType: attachmentMediaTypeSchema,
+    bytes: z.number().int().positive().max(RUNTIME_V14_MAX_ATTACHMENT_BYTES),
+    sha256: attachmentSha256Schema,
+    source: attachmentSourceSchema,
+    sourcePath: z.string().min(1).optional(),
+})
+    .strict()
+    .refine((params) => (params.source === "local-path" ? params.sourcePath !== undefined : true), {
+    message: "source 为 local-path 时必须提供 sourcePath",
+})
+    .refine((params) => (params.source === "chunks" ? params.sourcePath === undefined : true), {
+    message: "source 为 chunks 时不能提供 sourcePath",
+})
+    .readonly();
+export const attachmentStageResultSchema = z
+    .object({
+    attachmentId: attachmentIdSchema,
+    state: attachmentStateSchema,
+    descriptor: attachmentDescriptorSchema.optional(),
+})
+    .strict()
+    .readonly();
+export const attachmentChunkParamsSchema = z
+    .object({
+    ...requestFields,
+    ...threadRequestFields,
+    attachmentId: attachmentIdSchema,
+    sequence: z.number().int().nonnegative(),
+    dataBase64: z
+        .string()
+        .min(1)
+        .max(Math.ceil(RUNTIME_V14_MAX_ATTACHMENT_CHUNK_BYTES / 3) * 4 + 4)
+        .regex(/^[A-Za-z0-9+/]+={0,2}$/u),
+})
+    .strict()
+    .readonly();
+export const attachmentChunkResultSchema = z
+    .object({
+    receivedBytes: z.number().int().nonnegative(),
+    nextSequence: z.number().int().nonnegative(),
+})
+    .strict()
+    .readonly();
+export const attachmentCommitParamsSchema = z
+    .object({
+    ...requestFields,
+    ...threadRequestFields,
+    attachmentId: attachmentIdSchema,
+})
+    .strict()
+    .readonly();
+export const attachmentCommitResultSchema = z
+    .object({
+    descriptor: attachmentDescriptorSchema,
+})
+    .strict()
+    .readonly();
+export const attachmentReleaseParamsSchema = z
+    .object({
+    ...requestFields,
+    ...threadRequestFields,
+    attachmentId: attachmentIdSchema,
+})
+    .strict()
+    .readonly();
+export const attachmentReleaseResultSchema = z
+    .object({
+    released: z.boolean(),
+})
+    .strict()
+    .readonly();
 export const turnStartParamsSchema = z
     .object({
     ...requestFields,
@@ -912,6 +1155,28 @@ export const turnStartParamsSchema = z
 })
     .strict()
     .readonly();
+export const turnStartParamsV14Schema = z
+    .object({
+    ...requestFields,
+    ...threadRequestFields,
+    turnId: turnIdSchema,
+    input: z
+        .object({
+        text: z.string(),
+        attachments: z
+            .array(attachmentIdSchema)
+            .min(1)
+            .max(RUNTIME_V14_MAX_TURN_ATTACHMENTS)
+            .optional(),
+    })
+        .strict()
+        .refine((input) => input.text.length > 0 || input.attachments !== undefined, {
+        message: "input.text 为空时必须至少引用一个附件",
+    })
+        .readonly(),
+})
+    .strict()
+    .readonly();
 export const turnStartResultSchema = z
     .object({
     accepted: z.literal(true),
@@ -1252,8 +1517,35 @@ export const runtimeEventEnvelopeV13Schema = z.discriminatedUnion("durability",
     runtimeDurableEventEnvelopeV13Schema,
     runtimeEphemeralEventEnvelopeV13Schema,
 ]);
+export const runtimeDurableEventEnvelopeV14Schema = z
+    .object({
+    protocolVersion: z.literal("1.4"),
+    ...runtimeEventEnvelopeFields,
+    durability: z.literal("durable"),
+    eventId: runtimeEventIdSchema,
+    cursor: runtimeEventCursorSchema,
+    event: runtimeDurableEventV13Schema,
+})
+    .strict()
+    .superRefine(validateRuntimeEventCapabilities)
+    .readonly();
+export const runtimeEphemeralEventEnvelopeV14Schema = z
+    .object({
+    protocolVersion: z.literal("1.4"),
+    ...runtimeEventEnvelopeFields,
+    durability: z.literal("ephemeral"),
+    event: runtimeEphemeralEventV13Schema,
+})
+    .strict()
+    .superRefine(validateRuntimeEventCapabilities)
+    .readonly();
+export const runtimeEventEnvelopeV14Schema = z.discriminatedUnion("durability", [
+    runtimeDurableEventEnvelopeV14Schema,
+    runtimeEphemeralEventEnvelopeV14Schema,
+]);
 /** Any currently supported Runtime Event envelope. */
 export const runtimeEventEnvelopeSchema = z.union([
+    runtimeEventEnvelopeV14Schema,
     runtimeEventEnvelopeV13Schema,
     runtimeEventEnvelopeV12Schema,
     runtimeEventEnvelopeV11Schema,
@@ -1284,6 +1576,14 @@ export const runtimeProtocolErrorDataV13Schema = z
 })
     .strict()
     .readonly();
+export const runtimeProtocolErrorDataV14Schema = z
+    .object({
+    rollCode: z.enum(Object.values(RUNTIME_ERROR_CODES_V14)),
+    retryable: z.boolean(),
+    details: jsonValueSchema.optional(),
+})
+    .strict()
+    .readonly();
 export const runtimeMethodSchemasV11 = {
     [RUNTIME_METHODS.initialize]: {
         params: initializeParamsSchema,
@@ -1366,19 +1666,54 @@ export const runtimeMethodSchemasV13 = {
     },
     [RUNTIME_METHODS.threadOpen]: {
         params: threadOpenParamsSchema,
-        result: threadOpenResultSchema,
+        result: threadSnapshotV13Schema,
     },
     [RUNTIME_METHODS.threadSnapshot]: {
         params: threadSnapshotParamsV13Schema,
-        result: threadSnapshotResultSchema,
+        result: threadSnapshotV13Schema,
     },
     [RUNTIME_METHODS.runtimeEventsResume]: {
         params: runtimeEventsResumeParamsSchema,
         result: runtimeEventsResumeResultSchema,
     },
 };
+export const runtimeMethodSchemasV14 = {
+    ...runtimeMethodSchemasV13,
+    [RUNTIME_METHODS.initialize]: {
+        params: initializeParamsSchema,
+        result: initializeResultV14Schema,
+    },
+    [RUNTIME_METHODS.threadOpen]: {
+        params: threadOpenParamsSchema,
+        result: threadSnapshotV14Schema,
+    },
+    [RUNTIME_METHODS.threadSnapshot]: {
+        params: threadSnapshotParamsV13Schema,
+        result: threadSnapshotV14Schema,
+    },
+    [RUNTIME_METHODS.turnStart]: {
+        params: turnStartParamsV14Schema,
+        result: turnStartResultSchema,
+    },
+    [RUNTIME_METHODS.attachmentStage]: {
+        params: attachmentStageParamsSchema,
+        result: attachmentStageResultSchema,
+    },
+    [RUNTIME_METHODS.attachmentChunk]: {
+        params: attachmentChunkParamsSchema,
+        result: attachmentChunkResultSchema,
+    },
+    [RUNTIME_METHODS.attachmentCommit]: {
+        params: attachmentCommitParamsSchema,
+        result: attachmentCommitResultSchema,
+    },
+    [RUNTIME_METHODS.attachmentRelease]: {
+        params: attachmentReleaseParamsSchema,
+        result: attachmentReleaseResultSchema,
+    },
+};
 /** Latest Runtime method registry. Use the version registry for negotiated availability. */
-export const runtimeMethodSchemas = runtimeMethodSchemasV13;
+export const runtimeMethodSchemas = runtimeMethodSchemasV14;
 export const runtimeServerRequestSchemasV10 = {};
 export const runtimeServerRequestSchemasV11 = {
     [RUNTIME_SERVER_REQUEST_METHODS.approvalRequest]: {
@@ -1400,6 +1735,14 @@ export const runtimeServerRequestSchemasV13 = runtimeServerRequestSchemasV12;
 /** Protocol 1.1 compatibility facade. Prefer the version registry in new code. */
 export const runtimeServerRequestSchemas = runtimeServerRequestSchemasV11;
 export const RUNTIME_PROTOCOL_REGISTRY = {
+    "1.4": {
+        methods: runtimeMethodSchemasV14,
+        serverRequests: runtimeServerRequestSchemasV13,
+        serverRequestMethods: RUNTIME_SERVER_REQUEST_METHOD_VALUES,
+        serverRequestCancelParamsSchema: runtimeServerRequestCancelParamsV12Schema,
+        eventEnvelopeSchema: runtimeEventEnvelopeV14Schema,
+        errorDataSchema: runtimeProtocolErrorDataV14Schema,
+    },
     "1.3": {
         methods: runtimeMethodSchemasV13,
         serverRequests: runtimeServerRequestSchemasV13,
@@ -1458,6 +1801,18 @@ export function getApprovalExplanation(approval) {
     const parsed = approvalExplanationSchema.safeParse(preview[APPROVAL_EXPLANATION_PREVIEW_KEY]);
     return parsed.success ? parsed.data : undefined;
 }
+export function getApprovalDiffPreview(approval) {
+    const preview = approval.preview;
+    if (typeof preview !== "object" || preview === null || Array.isArray(preview)) {
+        return undefined;
+    }
+    const parsed = fileChangeDiffSchema.safeParse(preview[APPROVAL_DIFF_PREVIEW_KEY]);
+    return parsed.success ? parsed.data : undefined;
+}
+export function getFileChangeDisplay(display) {
+    const parsed = fileChangeDisplaySchema.safeParse(display);
+    return parsed.success ? parsed.data : undefined;
+}
 function validateUserInputTextValue(control, value, path, addIssue) {
     if (typeof value !== "string") {
         addIssue(path, `${control.type} control requires a string value`);
@@ -1632,8 +1987,36 @@ export function parseRuntimeMethodParams(method, value) {
 export function parseRuntimeMethodResult(method, value) {
     return runtimeMethodSchemasV11[method].result.parse(value);
 }
+export function parseLatestRuntimeMethodParams(method, value) {
+    return runtimeMethodSchemas[method].params.parse(value);
+}
+export function parseLatestRuntimeMethodResult(method, value) {
+    return runtimeMethodSchemas[method].result.parse(value);
+}
+function projectUiMessagePageToTextParts(page) {
+    return {
+        items: page.items.map((message) => ({
+            ...message,
+            parts: message.parts.filter((part) => part.type === "text"),
+        })),
+        nextBeforeSequence: page.nextBeforeSequence,
+    };
+}
 export function projectThreadSnapshotForVersion(version, value) {
-    const latest = threadSnapshotV13Schema.safeParse(value);
+    const latestV14 = threadSnapshotV14Schema.safeParse(value);
+    if (version === "1.4") {
+        if (!latestV14.success) {
+            throw latestV14.error;
+        }
+        return latestV14.data;
+    }
+    const v13Candidate = latestV14.success && !("recoveryProjection" in latestV14.data)
+        ? {
+            ...latestV14.data,
+            messages: projectUiMessagePageToTextParts(latestV14.data.messages),
+        }
+        : value;
+    const latest = threadSnapshotV13Schema.safeParse(v13Candidate);
     if (version === "1.3") {
         if (!latest.success) {
             throw latest.error;
@@ -1650,7 +2033,7 @@ export function projectThreadSnapshotForVersion(version, value) {
             pendingInteractions: latest.data.pendingInteractions,
             transcriptCompleteness: latest.data.transcriptCompleteness,
         })
-        : threadSnapshotV12Schema.parse(value);
+        : threadSnapshotV12Schema.parse(v13Candidate);
     if (version === "1.2") {
         return v12;
     }
@@ -1672,8 +2055,17 @@ export function projectThreadSnapshotForVersion(version, value) {
 }
 export function projectRuntimeEventEnvelopeForVersion(version, value) {
     const source = runtimeEventEnvelopeSchema.parse(value);
+    if (version === "1.4") {
+        return runtimeEventEnvelopeV14Schema.parse({
+            ...source,
+            protocolVersion: version,
+        });
+    }
     if (version === "1.3") {
-        return runtimeEventEnvelopeV13Schema.parse(source);
+        return runtimeEventEnvelopeV13Schema.parse({
+            ...source,
+            protocolVersion: version,
+        });
     }
     const projectedEnvelopeFields = {
         runtimeInstanceId: source.runtimeInstanceId,