@roll-agent/protocol 0.6.1 → 0.8.0

package/README.md

@@ -94,7 +94,7 @@ function handleEvent(event: RuntimeEventEnvelopeV13): void {
 
 协议版本与 npm 包版本相互独立。`RUNTIME_PROTOCOL_VERSION` 表示这个包提供的最新 wire
 schema，并不代表调用方已实现对应 Client 能力。当前支持顺序为
-`["1.4", "1.3", "1.2", "1.1", "1.0"]`。`initialize` 请求保持旧 strict 形状；协商到 `"1.2"`、
+`["1.5", "1.4", "1.3", "1.2", "1.1", "1.0"]`。`initialize` 请求保持旧 strict 形状；协商到 `"1.2"`、
 `"1.3"` 或 `"1.4"` 后，
 Client 必须用 `client.capabilities.set` 提交单调 `revision` 与当前 Handler methods，Runtime
 返回 registry 交集后才进入 interaction-ready。ACK 可以为空或为请求集的任意子集，顺序按

package/dist/app-output.d.ts

@@ -0,0 +1,86 @@
+import { z } from "zod/v4";
+/** Independent of a renderer and of the lossy model/display projections. */
+export declare const APP_OUTPUT_META_KEY = "roll/appOutput";
+export declare const APP_OUTPUT_STATUS_META_KEY = "roll/appOutputStatus";
+export declare const APP_OUTPUT_LIMITS: {
+    readonly resultBytes: number;
+    readonly schemaBytes: number;
+    readonly threadBytes: number;
+    readonly threadRecords: 2000;
+    readonly maxAgeMs: number;
+};
+export declare const appOutputDeclarationSchema: z.ZodReadonly<z.ZodObject<{
+    schemaId: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    remoteReadable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>>;
+export type AppOutputDeclaration = z.infer<typeof appOutputDeclarationSchema>;
+export declare const appOutputContractSchema: z.ZodReadonly<z.ZodObject<{
+    outputSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    schemaId: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    remoteReadable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>>;
+export type AppOutputContract = z.infer<typeof appOutputContractSchema>;
+export declare const APP_OUTPUT_UNAVAILABLE_STATUSES: readonly ["not_provided", "invalid", "too_large", "expired", "denied"];
+export declare const appOutputRejectionSchema: z.ZodReadonly<z.ZodObject<{
+    status: z.ZodLiteral<"rejected">;
+    reason: z.ZodEnum<{
+        credential_field: "credential_field";
+        credential_value: "credential_value";
+    }>;
+    field: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export type AppOutputRejection = z.infer<typeof appOutputRejectionSchema>;
+export declare const appOutputResultSchema: z.ZodReadonly<z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    status: z.ZodLiteral<"rejected">;
+    reason: z.ZodEnum<{
+        credential_field: "credential_field";
+        credential_value: "credential_value";
+    }>;
+    field: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>, z.ZodObject<{
+    status: z.ZodLiteral<"available">;
+    schemaId: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    remoteReadable: z.ZodBoolean;
+    data: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    fallbackText: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodEnum<{
+        not_provided: "not_provided";
+        invalid: "invalid";
+        too_large: "too_large";
+        expired: "expired";
+        denied: "denied";
+    }>;
+}, z.core.$strict>]>>;
+export type AppOutputResult = z.infer<typeof appOutputResultSchema>;
+export declare const appOutputDescriptorSchema: z.ZodReadonly<z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    status: z.ZodLiteral<"rejected">;
+    reason: z.ZodEnum<{
+        credential_field: "credential_field";
+        credential_value: "credential_value";
+    }>;
+    field: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>, z.ZodObject<{
+    status: z.ZodLiteral<"available">;
+    schemaId: z.ZodString;
+    schemaVersion: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodEnum<{
+        not_provided: "not_provided";
+        invalid: "invalid";
+        too_large: "too_large";
+        expired: "expired";
+        denied: "denied";
+    }>;
+}, z.core.$strict>]>>;
+export type AppOutputDescriptor = z.infer<typeof appOutputDescriptorSchema>;
+export declare function describeAppOutput(result: AppOutputResult): AppOutputDescriptor;
+/** Validate portable, self-contained contracts without dereferencing network resources. */
+export declare function validateAppOutputContract(value: unknown): AppOutputContract;
+/** MCP uses isError for invalid output even when execution has completed. */
+export declare const COMPLETED_APP_OUTPUT_STATUSES: readonly ["invalid", "too_large"];
+export type CompletedAppOutputStatus = (typeof COMPLETED_APP_OUTPUT_STATUSES)[number];
+export declare function getCompletedAppOutputStatus(value: unknown): CompletedAppOutputStatus | undefined;

package/dist/app-output.js

@@ -0,0 +1,178 @@
+import { z } from "zod/v4";
+/** Independent of a renderer and of the lossy model/display projections. */
+export const APP_OUTPUT_META_KEY = "roll/appOutput";
+export const APP_OUTPUT_STATUS_META_KEY = "roll/appOutputStatus";
+export const APP_OUTPUT_LIMITS = {
+    resultBytes: 256 * 1024,
+    schemaBytes: 32 * 1024,
+    threadBytes: 16 * 1024 * 1024,
+    threadRecords: 2000,
+    maxAgeMs: 30 * 24 * 60 * 60 * 1000,
+};
+const appOutputDeclarationObjectSchema = z
+    .object({
+    schemaId: z.string().min(1).max(256),
+    schemaVersion: z.number().int().positive(),
+    remoteReadable: z.boolean().default(false),
+})
+    .strict();
+export const appOutputDeclarationSchema = appOutputDeclarationObjectSchema.readonly();
+export const appOutputContractSchema = z
+    .object({
+    ...appOutputDeclarationObjectSchema.shape,
+    outputSchema: z.record(z.string(), z.json()),
+})
+    .strict()
+    .readonly();
+export const APP_OUTPUT_UNAVAILABLE_STATUSES = [
+    "not_provided",
+    "invalid",
+    "too_large",
+    "expired",
+    "denied",
+];
+export const appOutputRejectionSchema = z
+    .object({
+    status: z.literal("rejected"),
+    reason: z.enum(["credential_field", "credential_value"]),
+    field: z.string().max(64).optional(),
+})
+    .strict()
+    .readonly();
+export const appOutputResultSchema = z
+    .discriminatedUnion("status", [
+    appOutputRejectionSchema,
+    z
+        .object({
+        status: z.literal("available"),
+        schemaId: z.string().min(1).max(256),
+        schemaVersion: z.number().int().positive(),
+        remoteReadable: z.boolean(),
+        data: z.record(z.string(), z.json()),
+        fallbackText: z.string().max(4096),
+    })
+        .strict(),
+    z.object({ status: z.enum(APP_OUTPUT_UNAVAILABLE_STATUSES) }).strict(),
+])
+    .readonly();
+export const appOutputDescriptorSchema = z
+    .discriminatedUnion("status", [
+    appOutputRejectionSchema,
+    z
+        .object({
+        status: z.literal("available"),
+        schemaId: z.string().min(1).max(256),
+        schemaVersion: z.number().int().positive(),
+    })
+        .strict(),
+    z.object({ status: z.enum(APP_OUTPUT_UNAVAILABLE_STATUSES) }).strict(),
+])
+    .readonly();
+export function describeAppOutput(result) {
+    if (result.status === "rejected")
+        return result;
+    return result.status === "available"
+        ? { status: result.status, schemaId: result.schemaId, schemaVersion: result.schemaVersion }
+        : { status: result.status };
+}
+/** Validate portable, self-contained contracts without dereferencing network resources. */
+export function validateAppOutputContract(value) {
+    const contract = appOutputContractSchema.parse(value);
+    const schema = contract.outputSchema;
+    if (schema.type !== "object")
+        throw new Error("appOutput outputSchema must be an object schema");
+    if (new TextEncoder().encode(JSON.stringify(schema)).byteLength > APP_OUTPUT_LIMITS.schemaBytes) {
+        throw new Error("appOutput outputSchema exceeds 32 KiB");
+    }
+    const visit = (node) => {
+        if (typeof node !== "object" || node === null || Array.isArray(node))
+            return;
+        const record = { ...node };
+        if ("$dynamicRef" in record || "$recursiveRef" in record) {
+            throw new Error("appOutput supports only static local references");
+        }
+        if ("$ref" in record) {
+            const ref = record["$ref"];
+            if (typeof ref !== "string" || (ref !== "#" && !ref.startsWith("#/"))) {
+                throw new Error("appOutput outputSchema only supports local JSON Pointer references");
+            }
+            let target = schema;
+            for (const part of ref === "#" ? [] : ref.slice(2).split("/")) {
+                const key = decodeURIComponent(part).replace(/~1/g, "/").replace(/~0/g, "~");
+                if (typeof target !== "object" || target === null || !Object.hasOwn(target, key)) {
+                    throw new Error("appOutput outputSchema has an unresolved local reference");
+                }
+                target = Reflect.get(target, key);
+            }
+            if (typeof target !== "boolean" &&
+                (typeof target !== "object" || target === null || Array.isArray(target))) {
+                throw new Error("appOutput local reference must target a schema");
+            }
+        }
+        for (const key of [
+            "properties",
+            "patternProperties",
+            "$defs",
+            "definitions",
+            "dependentSchemas",
+            "dependencies",
+        ]) {
+            const children = record[key];
+            if (typeof children === "object" && children !== null && !Array.isArray(children)) {
+                for (const child of Object.values(children))
+                    visit(child);
+            }
+        }
+        for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+            const children = record[key];
+            if (Array.isArray(children))
+                children.forEach(visit);
+        }
+        for (const key of [
+            "additionalProperties",
+            "additionalItems",
+            "contains",
+            "not",
+            "if",
+            "then",
+            "else",
+            "propertyNames",
+            "unevaluatedProperties",
+            "unevaluatedItems",
+        ]) {
+            visit(record[key]);
+        }
+        const items = record["items"];
+        if (Array.isArray(items))
+            items.forEach(visit);
+        else
+            visit(items);
+        // A nested identifier can change the meaning of otherwise local references.
+        if (node !== schema && ("$id" in record || "id" in record)) {
+            throw new Error("appOutput does not support nested schema identifiers");
+        }
+    };
+    visit(schema);
+    return contract;
+}
+/** MCP uses isError for invalid output even when execution has completed. */
+export const COMPLETED_APP_OUTPUT_STATUSES = ["invalid", "too_large"];
+export function getCompletedAppOutputStatus(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("isError" in value) ||
+        value.isError !== true ||
+        !("_meta" in value)) {
+        return undefined;
+    }
+    const meta = value._meta;
+    if (typeof meta !== "object" ||
+        meta === null ||
+        !("roll/executionStatus" in meta) ||
+        meta["roll/executionStatus"] !== "completed" ||
+        !(APP_OUTPUT_STATUS_META_KEY in meta)) {
+        return undefined;
+    }
+    const status = meta[APP_OUTPUT_STATUS_META_KEY];
+    return status === "invalid" || status === "too_large" ? status : undefined;
+}