@roll-agent/protocol 0.8.1 → 0.10.0

package/dist/index.js

@@ -14,10 +14,14 @@ export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V14 = [
     "1.4",
     ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V13,
 ];
-export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS = [
+export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V15 = [
     "1.5",
     ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V14,
 ];
+export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS = [
+    "1.6",
+    ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V15,
+];
 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";
@@ -89,6 +93,13 @@ export const USER_INPUT_CONTROL_TYPES = {
     choice: "choice",
 };
 export const RUNTIME_PROTOCOL_CAPABILITIES = {
+    "1.6": {
+        serverRequests: true,
+        serverRequestCapabilityNegotiation: true,
+        approvalResolvedEvents: true,
+        clientApprovalResponses: false,
+        requiredServerRequestMethods: [],
+    },
     "1.5": {
         serverRequests: true,
         serverRequestCapabilityNegotiation: true,
@@ -133,6 +144,7 @@ export const RUNTIME_PROTOCOL_CAPABILITIES = {
     },
 };
 export const REQUIRED_RUNTIME_SERVER_REQUEST_METHODS_BY_VERSION = {
+    "1.6": RUNTIME_PROTOCOL_CAPABILITIES["1.6"].requiredServerRequestMethods,
     "1.5": RUNTIME_PROTOCOL_CAPABILITIES["1.5"].requiredServerRequestMethods,
     "1.4": RUNTIME_PROTOCOL_CAPABILITIES["1.4"].requiredServerRequestMethods,
     "1.3": RUNTIME_PROTOCOL_CAPABILITIES["1.3"].requiredServerRequestMethods,
@@ -175,6 +187,7 @@ export const RUNTIME_METHODS = {
     turnStart: "turn.start",
     turnCancel: "turn.cancel",
     approvalRespond: "approval.respond",
+    approvalPreview: "approval.preview",
     operationGet: "operation.get",
     attachmentStage: "attachment.stage",
     attachmentChunk: "attachment.chunk",
@@ -193,7 +206,8 @@ export const RUNTIME_FEATURES_V13 = [
 ];
 export const RUNTIME_FEATURES_V14 = [...RUNTIME_FEATURES_V13, "attachments"];
 export const RUNTIME_FEATURES_V15 = [...RUNTIME_FEATURES_V14, "app-output"];
-export const RUNTIME_FEATURES = RUNTIME_FEATURES_V15;
+export const RUNTIME_FEATURES_V16 = [...RUNTIME_FEATURES_V15, "context-recovery"];
+export const RUNTIME_FEATURES = RUNTIME_FEATURES_V16;
 export const RUNTIME_ERROR_CODES_V11 = {
     protocolVersionUnsupported: "PROTOCOL_VERSION_UNSUPPORTED",
     initializeRequired: "INITIALIZE_REQUIRED",
@@ -239,22 +253,29 @@ export const TOOL_OUTCOME_KINDS = [
     "cancelled",
     "tool_failed",
 ];
-export const threadIdSchema = z.string().uuid().brand();
-export const turnIdSchema = z.string().uuid().brand();
-export const approvalIdSchema = z.string().uuid().brand();
-export const interactionIdSchema = z.string().uuid().brand();
-export const runtimeInstanceIdSchema = z.string().uuid().brand();
-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();
+// Wire formats are owned by Protocol: dependency upgrades must not broaden UUIDs or
+// reject timestamps that existing clients could send (including minute precision).
+export const uuidSchema = z
+    .string()
+    .check(z.stringFormat("uuid", /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$/));
+export const timestampSchema = z
+    .string()
+    .check(z.stringFormat("datetime", /^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-]\d{2}:\d{2})))$/));
+export const threadIdSchema = uuidSchema.clone().brand();
+export const turnIdSchema = uuidSchema.clone().brand();
+export const approvalIdSchema = uuidSchema.clone().brand();
+export const interactionIdSchema = uuidSchema.clone().brand();
+export const runtimeInstanceIdSchema = uuidSchema.clone().brand();
+export const requestIdSchema = uuidSchema.clone().brand();
+export const streamIdSchema = uuidSchema.clone().brand();
+export const operationIdSchema = uuidSchema.clone().brand();
+export const runtimeEventIdSchema = uuidSchema.clone().brand();
+export const attachmentIdSchema = uuidSchema.clone().brand();
 export const runtimeEventCursorSchema = z
     .string()
     .max(128)
     .regex(/^rte1:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}:(?:0|[1-9]\d*):[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/u)
     .brand();
-export const timestampSchema = z.string().datetime({ offset: true });
 export const jsonValueSchema = z.json();
 export const jsonRpcIdSchema = z.union([z.string(), z.number()]);
 export const runtimeProtocolVersionSchema = z.enum(SUPPORTED_RUNTIME_PROTOCOL_VERSIONS);
@@ -285,6 +306,8 @@ export const fileChangeDiffSchema = z
     hunks: z.number().int().nonnegative(),
     unified: z.string().max(FILE_CHANGE_DIFF_UNIFIED_MAX_CHARS).optional(),
     truncated: z.boolean(),
+    /** True when the counts describe whole before/after files rather than a line diff. */
+    coarse: z.boolean().optional(),
 })
     .readonly();
 export const fileChangeDisplaySchema = z
@@ -457,8 +480,15 @@ export const initializeResultV15Schema = z
 })
     .strict()
     .readonly();
+export const initializeResultV16Schema = initializeResultV15Schema.def.innerType
+    .extend({
+    protocolVersion: z.literal("1.6"),
+    features: z.array(z.enum(RUNTIME_FEATURES_V16)),
+})
+    .readonly();
 /** Any currently supported Runtime Protocol initialize result. */
 export const initializeResultSchema = z.union([
+    initializeResultV16Schema,
     initializeResultV15Schema,
     initializeResultV14Schema,
     initializeResultV13Schema,
@@ -911,14 +941,8 @@ const recoveryThreadSummarySchema = z
     id: threadIdSchema,
     title: z.string().max(RUNTIME_V13_RECOVERY_SNAPSHOT_METADATA_MAX_CHARS).optional(),
     model: z.string().max(RUNTIME_V13_RECOVERY_SNAPSHOT_METADATA_MAX_CHARS).optional(),
-    createdAt: z
-        .string()
-        .max(RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS)
-        .datetime({ offset: true }),
-    updatedAt: z
-        .string()
-        .max(RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS)
-        .datetime({ offset: true }),
+    createdAt: timestampSchema.max(RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS),
+    updatedAt: timestampSchema.max(RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS),
     messageCount: z.number().int().nonnegative(),
 })
     .strict()
@@ -941,10 +965,7 @@ const recoveryActiveTurnSchema = z
     .object({
     id: turnIdSchema,
     status: z.enum(["running", "cancelling", "waiting-for-user"]),
-    startedAt: z
-        .string()
-        .max(RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS)
-        .datetime({ offset: true }),
+    startedAt: timestampSchema.max(RUNTIME_V13_RECOVERY_SNAPSHOT_TIMESTAMP_MAX_CHARS),
 })
     .strict()
     .readonly();
@@ -990,7 +1011,31 @@ export const threadSnapshotV15Schema = z.union([
     threadSnapshotV15FullSchema,
     threadRecoverySnapshotV13Schema,
 ]);
-export const threadSnapshotSchema = threadSnapshotV15Schema;
+/** Bounded Harness state only; no model-authored recovery notes or fact contents cross the wire. */
+export const contextRecoveryViewSchema = z
+    .object({
+    checkpointId: uuidSchema.clone(),
+    required: z.boolean(),
+    unextracted: z.boolean(),
+    requiredItemCount: z.number().int().nonnegative(),
+})
+    .strict()
+    .readonly();
+export const threadSnapshotV16FullSchema = threadSnapshotV15FullSchema.def.innerType
+    .extend({
+    contextRecovery: contextRecoveryViewSchema.nullable(),
+})
+    .readonly();
+export const threadRecoverySnapshotV16Schema = threadRecoverySnapshotV13Schema.def.innerType
+    .extend({
+    contextRecovery: contextRecoveryViewSchema.nullable(),
+})
+    .readonly();
+export const threadSnapshotV16Schema = z.union([
+    threadSnapshotV16FullSchema,
+    threadRecoverySnapshotV16Schema,
+]);
+export const threadSnapshotSchema = threadSnapshotV16Schema;
 const pageSizeSchema = z.number().int().min(1).max(500).default(100);
 const requestFields = { requestId: requestIdSchema };
 const threadRequestFields = { threadId: threadIdSchema };
@@ -1264,6 +1309,25 @@ export const approvalRespondResultSchema = z
     .object({ resolved: z.literal(true) })
     .strict()
     .readonly();
+/** Offsets count UTF-16 code units in the stable, redacted review text. */
+export const approvalPreviewParamsSchema = z
+    .object({
+    ...threadRequestFields,
+    turnId: turnIdSchema,
+    approvalId: approvalIdSchema,
+    offset: z.number().int().nonnegative().default(0),
+    maxChars: z.number().int().min(1).max(32_000).default(12_000),
+})
+    .strict()
+    .readonly();
+export const approvalPreviewResultSchema = z
+    .object({
+    text: z.string().max(32_000),
+    totalChars: z.number().int().nonnegative(),
+    nextOffset: z.number().int().nonnegative().nullable(),
+})
+    .strict()
+    .readonly();
 export const approvalRequestParamsSchema = z
     .object({
     threadId: threadIdSchema,
@@ -1545,8 +1609,23 @@ export const runtimeEventV15Schema = z.union([
     runtimeDurableEventV15Schema,
     runtimeEphemeralEventV13Schema,
 ]);
+export const contextRecoveryChangedEventSchema = z
+    .object({
+    type: z.literal("context.recovery.changed"),
+    contextRecovery: contextRecoveryViewSchema.nullable(),
+})
+    .strict()
+    .readonly();
+export const runtimeDurableEventV16Schema = z.discriminatedUnion("type", [
+    ...runtimeDurableEventV15Schema.options,
+    contextRecoveryChangedEventSchema,
+]);
+export const runtimeEventV16Schema = z.union([
+    runtimeDurableEventV16Schema,
+    runtimeEphemeralEventV13Schema,
+]);
 /** Latest Runtime Protocol event payloads. */
-export const runtimeEventSchema = runtimeEventV15Schema;
+export const runtimeEventSchema = runtimeEventV16Schema;
 const runtimeEventEnvelopeFields = {
     runtimeInstanceId: runtimeInstanceIdSchema,
     sequence: z.number().int().nonnegative(),
@@ -1663,7 +1742,34 @@ export const runtimeEventEnvelopeV15Schema = z.discriminatedUnion("durability",
     runtimeEphemeralEventEnvelopeV15Schema,
 ]);
 /** Any currently supported Runtime Event envelope. */
+export const runtimeDurableEventEnvelopeV16Schema = z
+    .object({
+    protocolVersion: z.literal("1.6"),
+    ...runtimeEventEnvelopeFields,
+    durability: z.literal("durable"),
+    eventId: runtimeEventIdSchema,
+    cursor: runtimeEventCursorSchema,
+    event: runtimeDurableEventV16Schema,
+})
+    .strict()
+    .superRefine(validateRuntimeEventCapabilities)
+    .readonly();
+export const runtimeEphemeralEventEnvelopeV16Schema = z
+    .object({
+    protocolVersion: z.literal("1.6"),
+    ...runtimeEventEnvelopeFields,
+    durability: z.literal("ephemeral"),
+    event: runtimeEphemeralEventV13Schema,
+})
+    .strict()
+    .superRefine(validateRuntimeEventCapabilities)
+    .readonly();
+export const runtimeEventEnvelopeV16Schema = z.discriminatedUnion("durability", [
+    runtimeDurableEventEnvelopeV16Schema,
+    runtimeEphemeralEventEnvelopeV16Schema,
+]);
 export const runtimeEventEnvelopeSchema = z.union([
+    runtimeEventEnvelopeV16Schema,
     runtimeEventEnvelopeV15Schema,
     runtimeEventEnvelopeV14Schema,
     runtimeEventEnvelopeV13Schema,
@@ -1853,7 +1959,23 @@ export const runtimeMethodSchemasV15 = {
         result: operationResultGetResultSchema,
     },
 };
-export const runtimeMethodSchemas = runtimeMethodSchemasV15;
+export const runtimeMethodSchemasV16 = {
+    ...runtimeMethodSchemasV15,
+    [RUNTIME_METHODS.approvalPreview]: {
+        params: approvalPreviewParamsSchema,
+        result: approvalPreviewResultSchema,
+    },
+    [RUNTIME_METHODS.initialize]: {
+        params: initializeParamsSchema,
+        result: initializeResultV16Schema,
+    },
+    [RUNTIME_METHODS.threadOpen]: { params: threadOpenParamsSchema, result: threadSnapshotV16Schema },
+    [RUNTIME_METHODS.threadSnapshot]: {
+        params: threadSnapshotParamsV13Schema,
+        result: threadSnapshotV16Schema,
+    },
+};
+export const runtimeMethodSchemas = runtimeMethodSchemasV16;
 export const runtimeServerRequestSchemasV10 = {};
 export const runtimeServerRequestSchemasV11 = {
     [RUNTIME_SERVER_REQUEST_METHODS.approvalRequest]: {
@@ -1875,6 +1997,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.6": {
+        methods: runtimeMethodSchemasV16,
+        serverRequests: runtimeServerRequestSchemasV13,
+        serverRequestMethods: RUNTIME_SERVER_REQUEST_METHOD_VALUES,
+        serverRequestCancelParamsSchema: runtimeServerRequestCancelParamsV12Schema,
+        eventEnvelopeSchema: runtimeEventEnvelopeV16Schema,
+        errorDataSchema: runtimeProtocolErrorDataV14Schema,
+    },
     "1.5": {
         methods: runtimeMethodSchemasV15,
         serverRequests: runtimeServerRequestSchemasV13,
@@ -2152,7 +2282,7 @@ function projectUiMessagePageToTextParts(page) {
 }
 export function projectOperationViewForVersion(version, value) {
     const current = operationViewV15Schema.safeParse(value);
-    if (version === "1.5") {
+    if (version === "1.5" || version === "1.6") {
         return current.success
             ? current.data
             : operationViewV15Schema.parse({
@@ -2166,6 +2296,14 @@ export function projectOperationViewForVersion(version, value) {
     return operationViewSchema.parse(legacy);
 }
 export function projectThreadSnapshotForVersion(version, value) {
+    if (version === "1.6") {
+        return threadSnapshotV16Schema.parse(value);
+    }
+    const latestV16 = threadSnapshotV16Schema.safeParse(value);
+    if (latestV16.success) {
+        const { contextRecovery: _contextRecovery, ...legacy } = latestV16.data;
+        value = legacy;
+    }
     const latestV15 = threadSnapshotV15Schema.safeParse(value);
     if (version === "1.5") {
         return threadSnapshotV15Schema.parse(value);
@@ -2230,7 +2368,17 @@ export function projectThreadSnapshotForVersion(version, value) {
     });
 }
 export function projectRuntimeEventEnvelopeForVersion(version, value) {
-    const parsedSource = runtimeEventEnvelopeSchema.parse(value);
+    const latest = runtimeEventEnvelopeSchema.parse(value);
+    if (version === "1.6") {
+        return runtimeEventEnvelopeV16Schema.parse({
+            ...latest,
+            protocolVersion: version,
+        });
+    }
+    // Preserve durable cursor continuity for old clients; the available tool set changed.
+    const parsedSource = latest.event.type === "context.recovery.changed"
+        ? { ...latest, event: { type: "capabilities.changed" } }
+        : latest;
     if (version === "1.5") {
         return runtimeEventEnvelopeV15Schema.parse({
             ...parsedSource,