@roll-agent/protocol 0.6.1 → 0.8.0

package/dist/index.js

@@ -1,4 +1,6 @@
 import { z } from "zod/v4";
+import { appOutputDescriptorSchema, appOutputResultSchema } from "./app-output.js";
+export * from "./app-output.js";
 export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V11 = ["1.1", "1.0"];
 export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V12 = [
     "1.2",
@@ -8,10 +10,14 @@ export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V13 = [
     "1.3",
     ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V12,
 ];
-export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS = [
+export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V14 = [
     "1.4",
     ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V13,
 ];
+export const SUPPORTED_RUNTIME_PROTOCOL_VERSIONS = [
+    "1.5",
+    ...SUPPORTED_RUNTIME_PROTOCOL_VERSIONS_V14,
+];
 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";
@@ -83,6 +89,13 @@ export const USER_INPUT_CONTROL_TYPES = {
     choice: "choice",
 };
 export const RUNTIME_PROTOCOL_CAPABILITIES = {
+    "1.5": {
+        serverRequests: true,
+        serverRequestCapabilityNegotiation: true,
+        approvalResolvedEvents: true,
+        clientApprovalResponses: false,
+        requiredServerRequestMethods: [],
+    },
     "1.4": {
         serverRequests: true,
         serverRequestCapabilityNegotiation: true,
@@ -120,6 +133,7 @@ export const RUNTIME_PROTOCOL_CAPABILITIES = {
     },
 };
 export const REQUIRED_RUNTIME_SERVER_REQUEST_METHODS_BY_VERSION = {
+    "1.5": RUNTIME_PROTOCOL_CAPABILITIES["1.5"].requiredServerRequestMethods,
     "1.4": RUNTIME_PROTOCOL_CAPABILITIES["1.4"].requiredServerRequestMethods,
     "1.3": RUNTIME_PROTOCOL_CAPABILITIES["1.3"].requiredServerRequestMethods,
     "1.2": RUNTIME_PROTOCOL_CAPABILITIES["1.2"].requiredServerRequestMethods,
@@ -146,6 +160,7 @@ export function isRuntimeServerRequestMethodRequired(version, method) {
     return getRuntimeProtocolCapabilities(version).requiredServerRequestMethods.some((requiredMethod) => requiredMethod === method);
 }
 export const RUNTIME_METHODS = {
+    operationResultGet: "operation.result.get",
     initialize: "initialize",
     clientCapabilitiesSet: "client.capabilities.set",
     threadList: "thread.list",
@@ -177,7 +192,8 @@ export const RUNTIME_FEATURES_V13 = [
     "process-local-sequence",
 ];
 export const RUNTIME_FEATURES_V14 = [...RUNTIME_FEATURES_V13, "attachments"];
-export const RUNTIME_FEATURES = RUNTIME_FEATURES_V14;
+export const RUNTIME_FEATURES_V15 = [...RUNTIME_FEATURES_V14, "app-output"];
+export const RUNTIME_FEATURES = RUNTIME_FEATURES_V15;
 export const RUNTIME_ERROR_CODES_V11 = {
     protocolVersionUnsupported: "PROTOCOL_VERSION_UNSUPPORTED",
     initializeRequired: "INITIALIZE_REQUIRED",
@@ -432,8 +448,18 @@ export const initializeResultV14Schema = z
 })
     .strict()
     .readonly();
+export const initializeResultV15Schema = z
+    .object({
+    protocolVersion: z.literal("1.5"),
+    ...initializeResultV14Fields,
+    features: z.array(z.enum(RUNTIME_FEATURES_V15)),
+    limits: runtimeLimitsV14Schema,
+})
+    .strict()
+    .readonly();
 /** Any currently supported Runtime Protocol initialize result. */
 export const initializeResultSchema = z.union([
+    initializeResultV15Schema,
     initializeResultV14Schema,
     initializeResultV13Schema,
     initializeResultV12Schema,
@@ -543,7 +569,7 @@ export const toolOutcomeSchema = z
 })
     .strict()
     .readonly();
-export const operationViewSchema = z
+const operationViewObjectSchema = z
     .object({
     id: operationIdSchema,
     sequence: z.number().int().nonnegative(),
@@ -554,7 +580,12 @@ export const operationViewSchema = z
     outcome: toolOutcomeSchema,
     display: jsonValueSchema,
 })
-    .strict()
+    .strict();
+export const operationViewSchema = operationViewObjectSchema.readonly();
+export const operationViewV15Schema = operationViewObjectSchema
+    .extend({
+    appOutput: appOutputDescriptorSchema,
+})
     .readonly();
 export const activeTurnV11Schema = z
     .object({
@@ -599,13 +630,13 @@ export const messagePageV14Schema = z
 })
     .strict()
     .readonly();
-export const operationPageSchema = z
+const operationPageObjectSchema = z
     .object({
     items: z.array(operationViewSchema),
     nextBeforeSequence: z.number().int().nonnegative().nullable(),
 })
-    .strict()
-    .readonly();
+    .strict();
+export const operationPageSchema = operationPageObjectSchema.readonly();
 const threadSnapshotV11Fields = {
     thread: threadSummarySchema,
     messages: messagePageSchema,
@@ -935,20 +966,31 @@ export const threadSnapshotV13Schema = z.union([
     threadSnapshotV13FullSchema,
     threadRecoverySnapshotV13Schema,
 ]);
-export const threadSnapshotV14FullSchema = z
+const threadSnapshotV14FullObjectSchema = z
     .object({
     ...threadSnapshotV12Fields,
     messages: messagePageV14Schema,
     eventCursor: runtimeEventCursorSchema.nullable(),
 })
-    .strict()
-    .readonly();
+    .strict();
+export const threadSnapshotV14FullSchema = threadSnapshotV14FullObjectSchema.readonly();
 export const threadSnapshotV14Schema = z.union([
     threadSnapshotV14FullSchema,
     threadRecoverySnapshotV13Schema,
 ]);
 /** Latest Runtime Protocol snapshot. Use versioned schemas for compatibility. */
-export const threadSnapshotSchema = threadSnapshotV14Schema;
+export const threadSnapshotV15FullSchema = threadSnapshotV14FullObjectSchema
+    .extend({
+    operations: operationPageObjectSchema
+        .extend({ items: z.array(operationViewV15Schema) })
+        .readonly(),
+})
+    .readonly();
+export const threadSnapshotV15Schema = z.union([
+    threadSnapshotV15FullSchema,
+    threadRecoverySnapshotV13Schema,
+]);
+export const threadSnapshotSchema = threadSnapshotV15Schema;
 const pageSizeSchema = z.number().int().min(1).max(500).default(100);
 const requestFields = { requestId: requestIdSchema };
 const threadRequestFields = { threadId: threadIdSchema };
@@ -1306,6 +1348,26 @@ export const operationGetResultSchema = z
 })
     .strict()
     .readonly();
+export const operationResultGetParamsSchema = operationGetParamsSchema;
+export const operationResultViewSchema = z
+    .object({
+    threadId: threadIdSchema,
+    operationId: operationIdSchema,
+    agentName: z.string().min(1),
+    toolName: z.string().min(1),
+    createdAt: timestampSchema,
+    output: appOutputResultSchema,
+})
+    .strict()
+    .readonly();
+export const operationResultGetResultSchema = z
+    .object({ result: operationResultViewSchema.nullable() })
+    .strict()
+    .readonly();
+export const operationGetResultV15Schema = z
+    .object({ operation: operationViewV15Schema.nullable() })
+    .strict()
+    .readonly();
 export const approvalResolutionSchema = z.union([
     z
         .object({
@@ -1382,7 +1444,7 @@ const toolOutputEventSchema = z
 })
     .strict()
     .readonly();
-const toolCompletedEventSchema = z
+const toolCompletedEventObjectSchema = z
     .object({
     type: z.literal("tool.completed"),
     toolCallId: z.string().min(1),
@@ -1392,8 +1454,8 @@ const toolCompletedEventSchema = z
     outcome: toolOutcomeSchema.optional(),
     display: jsonValueSchema,
 })
-    .strict()
-    .readonly();
+    .strict();
+const toolCompletedEventSchema = toolCompletedEventObjectSchema.readonly();
 const approvalRequiredEventSchema = z
     .object({ type: z.literal("approval.required"), approval: pendingApprovalSchema })
     .strict()
@@ -1465,8 +1527,26 @@ export const runtimeEphemeralEventV13Schema = z.discriminatedUnion("type", [
 export const runtimeEventV12Schema = runtimeEventV11Schema;
 /** Runtime Protocol 1.3 retains the event payload registry and versions durability in the envelope. */
 export const runtimeEventV13Schema = runtimeEventV12Schema;
+export const toolCompletedEventV15Schema = toolCompletedEventObjectSchema
+    .extend({ appOutput: appOutputDescriptorSchema.default({ status: "not_provided" }) })
+    .readonly();
+export const runtimeDurableEventV15Schema = z.discriminatedUnion("type", [
+    turnStartedEventSchema,
+    messageCompletedEventSchema,
+    toolCompletedEventV15Schema,
+    approvalRequiredEventSchema,
+    approvalResolvedEventSchema,
+    turnCompletedEventSchema,
+    turnCancelledEventSchema,
+    turnFailedEventSchema,
+    capabilitiesChangedEventSchema,
+]);
+export const runtimeEventV15Schema = z.union([
+    runtimeDurableEventV15Schema,
+    runtimeEphemeralEventV13Schema,
+]);
 /** Latest Runtime Protocol event payloads. */
-export const runtimeEventSchema = runtimeEventV13Schema;
+export const runtimeEventSchema = runtimeEventV15Schema;
 const runtimeEventEnvelopeFields = {
     runtimeInstanceId: runtimeInstanceIdSchema,
     sequence: z.number().int().nonnegative(),
@@ -1556,8 +1636,35 @@ export const runtimeEventEnvelopeV14Schema = z.discriminatedUnion("durability",
     runtimeDurableEventEnvelopeV14Schema,
     runtimeEphemeralEventEnvelopeV14Schema,
 ]);
+export const runtimeDurableEventEnvelopeV15Schema = z
+    .object({
+    protocolVersion: z.literal("1.5"),
+    ...runtimeEventEnvelopeFields,
+    durability: z.literal("durable"),
+    eventId: runtimeEventIdSchema,
+    cursor: runtimeEventCursorSchema,
+    event: runtimeDurableEventV15Schema,
+})
+    .strict()
+    .superRefine(validateRuntimeEventCapabilities)
+    .readonly();
+export const runtimeEphemeralEventEnvelopeV15Schema = z
+    .object({
+    protocolVersion: z.literal("1.5"),
+    ...runtimeEventEnvelopeFields,
+    durability: z.literal("ephemeral"),
+    event: runtimeEphemeralEventV13Schema,
+})
+    .strict()
+    .superRefine(validateRuntimeEventCapabilities)
+    .readonly();
+export const runtimeEventEnvelopeV15Schema = z.discriminatedUnion("durability", [
+    runtimeDurableEventEnvelopeV15Schema,
+    runtimeEphemeralEventEnvelopeV15Schema,
+]);
 /** Any currently supported Runtime Event envelope. */
 export const runtimeEventEnvelopeSchema = z.union([
+    runtimeEventEnvelopeV15Schema,
     runtimeEventEnvelopeV14Schema,
     runtimeEventEnvelopeV13Schema,
     runtimeEventEnvelopeV12Schema,
@@ -1726,7 +1833,27 @@ export const runtimeMethodSchemasV14 = {
     },
 };
 /** Latest Runtime method registry. Use the version registry for negotiated availability. */
-export const runtimeMethodSchemas = runtimeMethodSchemasV14;
+export const runtimeMethodSchemasV15 = {
+    ...runtimeMethodSchemasV14,
+    [RUNTIME_METHODS.initialize]: {
+        params: initializeParamsSchema,
+        result: initializeResultV15Schema,
+    },
+    [RUNTIME_METHODS.threadOpen]: { params: threadOpenParamsSchema, result: threadSnapshotV15Schema },
+    [RUNTIME_METHODS.threadSnapshot]: {
+        params: threadSnapshotParamsV13Schema,
+        result: threadSnapshotV15Schema,
+    },
+    [RUNTIME_METHODS.operationGet]: {
+        params: operationGetParamsSchema,
+        result: operationGetResultV15Schema,
+    },
+    [RUNTIME_METHODS.operationResultGet]: {
+        params: operationResultGetParamsSchema,
+        result: operationResultGetResultSchema,
+    },
+};
+export const runtimeMethodSchemas = runtimeMethodSchemasV15;
 export const runtimeServerRequestSchemasV10 = {};
 export const runtimeServerRequestSchemasV11 = {
     [RUNTIME_SERVER_REQUEST_METHODS.approvalRequest]: {
@@ -1748,6 +1875,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.5": {
+        methods: runtimeMethodSchemasV15,
+        serverRequests: runtimeServerRequestSchemasV13,
+        serverRequestMethods: RUNTIME_SERVER_REQUEST_METHOD_VALUES,
+        serverRequestCancelParamsSchema: runtimeServerRequestCancelParamsV12Schema,
+        eventEnvelopeSchema: runtimeEventEnvelopeV15Schema,
+        errorDataSchema: runtimeProtocolErrorDataV14Schema,
+    },
     "1.4": {
         methods: runtimeMethodSchemasV14,
         serverRequests: runtimeServerRequestSchemasV13,
@@ -2015,8 +2150,36 @@ function projectUiMessagePageToTextParts(page) {
         nextBeforeSequence: page.nextBeforeSequence,
     };
 }
+export function projectOperationViewForVersion(version, value) {
+    const current = operationViewV15Schema.safeParse(value);
+    if (version === "1.5") {
+        return current.success
+            ? current.data
+            : operationViewV15Schema.parse({
+                ...operationViewSchema.parse(value),
+                appOutput: { status: "not_provided" },
+            });
+    }
+    if (!current.success)
+        return operationViewSchema.parse(value);
+    const { appOutput: _appOutput, ...legacy } = current.data;
+    return operationViewSchema.parse(legacy);
+}
 export function projectThreadSnapshotForVersion(version, value) {
-    const latestV14 = threadSnapshotV14Schema.safeParse(value);
+    const latestV15 = threadSnapshotV15Schema.safeParse(value);
+    if (version === "1.5") {
+        return threadSnapshotV15Schema.parse(value);
+    }
+    const legacyValue = latestV15.success && !("recoveryProjection" in latestV15.data)
+        ? {
+            ...latestV15.data,
+            operations: {
+                ...latestV15.data.operations,
+                items: latestV15.data.operations.items.map((op) => projectOperationViewForVersion("1.4", op)),
+            },
+        }
+        : value;
+    const latestV14 = threadSnapshotV14Schema.safeParse(legacyValue);
     if (version === "1.4") {
         if (!latestV14.success) {
             throw latestV14.error;
@@ -2028,7 +2191,7 @@ export function projectThreadSnapshotForVersion(version, value) {
             ...latestV14.data,
             messages: projectUiMessagePageToTextParts(latestV14.data.messages),
         }
-        : value;
+        : legacyValue;
     const latest = threadSnapshotV13Schema.safeParse(v13Candidate);
     if (version === "1.3") {
         if (!latest.success) {
@@ -2067,7 +2230,27 @@ export function projectThreadSnapshotForVersion(version, value) {
     });
 }
 export function projectRuntimeEventEnvelopeForVersion(version, value) {
-    const source = runtimeEventEnvelopeSchema.parse(value);
+    const parsedSource = runtimeEventEnvelopeSchema.parse(value);
+    if (version === "1.5") {
+        return runtimeEventEnvelopeV15Schema.parse({
+            ...parsedSource,
+            protocolVersion: version,
+            event: parsedSource.event.type === "tool.completed"
+                ? {
+                    ...parsedSource.event,
+                    appOutput: "appOutput" in parsedSource.event
+                        ? parsedSource.event.appOutput
+                        : { status: "not_provided" },
+                }
+                : parsedSource.event,
+        });
+    }
+    const source = {
+        ...parsedSource,
+        event: runtimeEventV13Schema.parse(parsedSource.event.type === "tool.completed" && "appOutput" in parsedSource.event
+            ? (({ appOutput: _appOutput, ...rest }) => rest)(parsedSource.event)
+            : parsedSource.event),
+    };
     if (version === "1.4") {
         return runtimeEventEnvelopeV14Schema.parse({
             ...source,
@@ -2173,3 +2356,4 @@ export function parseRuntimeServerRequestParams(method, value) {
 export function parseRuntimeServerRequestResult(method, value) {
     return runtimeServerRequestSchemas[method].result.parse(value);
 }
+export { OBSERVATION_RETENTION_META_KEY, observationRetentionDeclarationSchema, } from "./observation-retention.js";

package/dist/observation-retention.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod/v4";
+/** MCP metadata for tools whose successful results are replaceable observations. */
+export declare const OBSERVATION_RETENTION_META_KEY = "roll/observationRetention";
+export declare const observationRetentionDeclarationSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"browser-ax-snapshot">;
+}, z.core.$strict>;
+export type ObservationRetentionDeclaration = z.infer<typeof observationRetentionDeclarationSchema>;

package/dist/observation-retention.js

@@ -0,0 +1,6 @@
+import { z } from "zod/v4";
+/** MCP metadata for tools whose successful results are replaceable observations. */
+export const OBSERVATION_RETENTION_META_KEY = "roll/observationRetention";
+export const observationRetentionDeclarationSchema = z
+    .object({ kind: z.literal("browser-ax-snapshot") })
+    .strict();