@tangle-network/agent-interface 0.39.0 → 0.41.0

package/dist/interaction.js

@@ -30,33 +30,34 @@ const FieldBase = {
     /** Whether the answer must supply this field to be `accepted`. */
     required: z.boolean().optional(),
 };
-export const InteractionFieldSchema = z.discriminatedUnion("type", [
-    z.object({
+export const InteractionFieldSchema = z
+    .discriminatedUnion("type", [
+    z.strictObject({
         ...FieldBase,
         type: z.literal("text"),
         multiline: z.boolean().optional(),
         placeholder: z.string().optional(),
         default: z.string().optional(),
     }),
-    z.object({
+    z.strictObject({
         ...FieldBase,
         type: z.literal("number"),
-        min: z.number().optional(),
-        max: z.number().optional(),
-        default: z.number().optional(),
+        min: z.number().finite().optional(),
+        max: z.number().finite().optional(),
+        default: z.number().finite().optional(),
     }),
-    z.object({
+    z.strictObject({
         ...FieldBase,
         type: z.literal("boolean"),
         default: z.boolean().optional(),
     }),
-    z.object({
+    z.strictObject({
         ...FieldBase,
         type: z.literal("select"),
         options: z
-            .array(z.object({
-            value: z.string(),
-            label: z.string(),
+            .array(z.strictObject({
+            value: z.string().min(1),
+            label: z.string().min(1),
             description: z.string().optional(),
         }))
             .min(1),
@@ -68,26 +69,179 @@ export const InteractionFieldSchema = z.discriminatedUnion("type", [
          * Write-ins must still be non-empty strings.
          */
         allowCustom: z.boolean().optional(),
-        default: z.array(z.string()).optional(),
+        default: z.array(z.string().min(1)).optional(),
     }),
     /** Like `text` but the value is sensitive (token/key) and must be masked. */
-    z.object({
+    z.strictObject({
         ...FieldBase,
         type: z.literal("secret"),
         placeholder: z.string().optional(),
     }),
-]);
-export const InteractionAnswerSpecSchema = z.object({
+])
+    .superRefine((field, context) => {
+    if (field.type === "number") {
+        if (field.min !== undefined &&
+            field.max !== undefined &&
+            field.min > field.max) {
+            context.addIssue({
+                code: "custom",
+                path: ["max"],
+                message: "number field max must be greater than or equal to min",
+            });
+        }
+        if (field.default !== undefined &&
+            field.min !== undefined &&
+            field.default < field.min) {
+            context.addIssue({
+                code: "custom",
+                path: ["default"],
+                message: "number field default must be greater than or equal to min",
+            });
+        }
+        if (field.default !== undefined &&
+            field.max !== undefined &&
+            field.default > field.max) {
+            context.addIssue({
+                code: "custom",
+                path: ["default"],
+                message: "number field default must be less than or equal to max",
+            });
+        }
+        return;
+    }
+    if (field.type !== "select")
+        return;
+    const optionValues = field.options.map((option) => option.value);
+    if (new Set(optionValues).size !== optionValues.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["options"],
+            message: "select option values must be unique",
+        });
+    }
+    if (field.default === undefined)
+        return;
+    if (new Set(field.default).size !== field.default.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["default"],
+            message: "select default values must be unique",
+        });
+    }
+    if (!field.multi && field.default.length > 1) {
+        context.addIssue({
+            code: "custom",
+            path: ["default"],
+            message: "single-select default may contain at most one value",
+        });
+    }
+    if (field.required && field.default.length === 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["default"],
+            message: "required select default must contain a value",
+        });
+    }
+    const allowed = new Set(optionValues);
+    for (const value of field.default) {
+        if (allowed.has(value))
+            continue;
+        if (field.allowCustom === true && value.trim().length > 0)
+            continue;
+        context.addIssue({
+            code: "custom",
+            path: ["default"],
+            message: `select default contains unknown option "${value}"`,
+        });
+    }
+});
+export const InteractionAnswerSpecSchema = z
+    .strictObject({
     fields: z.array(InteractionFieldSchema),
+})
+    .superRefine((spec, context) => {
+    const names = spec.fields.map((field) => field.name);
+    if (new Set(names).size !== names.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["fields"],
+            message: "interaction field names must be unique",
+        });
+    }
+});
+export const InteractionFieldTypeSchema = z.enum([
+    "text",
+    "number",
+    "boolean",
+    "select",
+    "secret",
+]);
+/** Scope at which an accepted answer may be reused by an explicit policy. */
+export const InteractionResponseScopeSchema = z.enum([
+    "interaction",
+    "session",
+    "persistent",
+]);
+/** Negotiated interaction behavior. Absence means interactions are unsupported. */
+export const InteractionCapabilitiesSchema = z
+    .strictObject({
+    kinds: z.array(z.string().min(1)).min(1),
+    answerFieldTypes: z.array(InteractionFieldTypeSchema).min(1),
+    responseScopes: z.array(InteractionResponseScopeSchema).min(1),
+    secretAnswers: z.boolean(),
+    concurrentRequests: z.boolean(),
+    replay: z.boolean(),
+    responseIdempotency: z.boolean(),
+})
+    .superRefine((capabilities, context) => {
+    const advertisesSecret = capabilities.answerFieldTypes.includes("secret");
+    if (advertisesSecret !== capabilities.secretAnswers) {
+        context.addIssue({
+            code: "custom",
+            path: ["secretAnswers"],
+            message: "secretAnswers must agree with the secret answer field capability",
+        });
+    }
+    if (new Set(capabilities.kinds).size !== capabilities.kinds.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["kinds"],
+            message: "interaction kinds must be unique",
+        });
+    }
+    if (new Set(capabilities.answerFieldTypes).size !==
+        capabilities.answerFieldTypes.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["answerFieldTypes"],
+            message: "interaction answer field types must be unique",
+        });
+    }
+    if (new Set(capabilities.responseScopes).size !==
+        capabilities.responseScopes.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["responseScopes"],
+            message: "interaction response scopes must be unique",
+        });
+    }
 });
 // =============================================================================
 // Subject — what the request is about (drives preview/permission UX).
 // =============================================================================
 export const InteractionSubjectSchema = z.discriminatedUnion("type", [
-    z.object({ type: z.literal("tool"), toolName: z.string(), input: z.unknown().optional() }),
-    z.object({ type: z.literal("command"), command: z.string() }),
-    z.object({ type: z.literal("file"), path: z.string(), preview: z.string().optional() }),
-    z.object({ type: z.literal("resource"), uri: z.string() }),
+    z.strictObject({
+        type: z.literal("tool"),
+        toolName: z.string(),
+        input: z.unknown().optional(),
+    }),
+    z.strictObject({ type: z.literal("command"), command: z.string() }),
+    z.strictObject({
+        type: z.literal("file"),
+        path: z.string(),
+        preview: z.string().optional(),
+    }),
+    z.strictObject({ type: z.literal("resource"), uri: z.string() }),
 ]);
 // =============================================================================
 // Outcome + resolution — the answer.
@@ -95,15 +249,27 @@ export const InteractionSubjectSchema = z.discriminatedUnion("type", [
 export const InteractionOutcomeSchema = z.enum(["accepted", "declined", "cancelled"]);
 /** Field values keyed by `InteractionField.name`. Validated against `answerSpec`. */
 export const InteractionDataSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]));
-export const InteractionResolutionSchema = z.object({
-    outcome: InteractionOutcomeSchema,
-    /** Present (and validated) only when `outcome === "accepted"`. */
-    data: InteractionDataSchema.optional(),
-});
+export const InteractionResolutionSchema = z.discriminatedUnion("outcome", [
+    z.strictObject({
+        outcome: z.literal("accepted"),
+        data: InteractionDataSchema.optional(),
+    }),
+    z.strictObject({
+        outcome: z.literal("declined"),
+        /** Accepted for wire compatibility; ignored by response validation. */
+        data: InteractionDataSchema.optional(),
+    }),
+    z.strictObject({
+        outcome: z.literal("cancelled"),
+        /** Accepted for wire compatibility; ignored by response validation. */
+        data: InteractionDataSchema.optional(),
+    }),
+]);
 // =============================================================================
 // The request envelope.
 // =============================================================================
-export const InteractionRequestSchema = z.object({
+export const InteractionRequestSchema = z
+    .strictObject({
     /** Correlation id; unique within a session. The response carries the same id. */
     id: z.string().min(1),
     /**
@@ -118,15 +284,131 @@ export const InteractionRequestSchema = z.object({
     body: z.string().optional(),
     subject: InteractionSubjectSchema.optional(),
     answerSpec: InteractionAnswerSpecSchema,
+    /** Omission is fail-closed and permits only this interaction. */
+    responseScopes: z.array(InteractionResponseScopeSchema).min(1).optional(),
     /** Resolution applied when unattended or timed out — explicit, not a bypass flag. */
     default: InteractionResolutionSchema.optional(),
     /** Wait this long for a human before applying `onTimeout`. */
     timeoutMs: z.number().int().positive().optional(),
     /** On timeout: apply `default`, `fail` the turn, or keep `wait`ing. Default `wait`. */
     onTimeout: z.enum(["default", "fail", "wait"]).optional(),
+})
+    .superRefine((request, context) => {
+    if (request.responseScopes &&
+        new Set(request.responseScopes).size !== request.responseScopes.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["responseScopes"],
+            message: "interaction response scopes must be unique",
+        });
+    }
+    if (request.onTimeout === "default" && request.default === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["default"],
+            message: "onTimeout=default requires a default resolution",
+        });
+    }
+    if (request.default) {
+        for (const error of validateResolutionForRequest(request, request.default)) {
+            context.addIssue({ code: "custom", path: ["default"], message: error });
+        }
+        if (request.default.outcome === "accepted") {
+            const secretFields = new Set(request.answerSpec.fields
+                .filter((field) => field.type === "secret")
+                .map((field) => field.name));
+            for (const fieldName of Object.keys(request.default.data ?? {})) {
+                if (!secretFields.has(fieldName))
+                    continue;
+                context.addIssue({
+                    code: "custom",
+                    path: ["default", "data", fieldName],
+                    message: "secret answers cannot be embedded in interaction defaults",
+                });
+            }
+        }
+    }
 });
-export const InteractionResponseSchema = InteractionResolutionSchema.extend({
-    id: z.string().min(1),
+export const InteractionResponseSchema = z.discriminatedUnion("outcome", [
+    z.strictObject({
+        id: z.string().min(1),
+        outcome: z.literal("accepted"),
+        data: InteractionDataSchema.optional(),
+    }),
+    z.strictObject({
+        id: z.string().min(1),
+        outcome: z.literal("declined"),
+        /** Accepted for compatibility with the pre-discriminated wire shape. */
+        data: InteractionDataSchema.optional(),
+    }),
+    z.strictObject({
+        id: z.string().min(1),
+        outcome: z.literal("cancelled"),
+        /** Accepted for compatibility with the pre-discriminated wire shape. */
+        data: InteractionDataSchema.optional(),
+    }),
+]);
+/** A request is unique only within this run and optional provider session. */
+export const InteractionBindingSchema = z.strictObject({
+    runId: z.string().min(1),
+    environmentId: z.string().min(1),
+    sessionId: z.string().min(1).optional(),
+    interactionId: z.string().min(1),
+});
+/** Retryable command sent to an environment or retained session. */
+export const InteractionResponseCommandSchema = z
+    .strictObject({
+    operationId: z.string().min(1),
+    binding: InteractionBindingSchema,
+    response: InteractionResponseSchema,
+})
+    .superRefine((command, context) => {
+    if (command.binding.interactionId !== command.response.id) {
+        context.addIssue({
+            code: "custom",
+            path: ["response", "id"],
+            message: "response id must match the bound interaction id",
+        });
+    }
+});
+export const InteractionAcknowledgementStatusSchema = z.enum([
+    "accepted",
+    "already_resolved_same",
+    "already_resolved_different",
+    "expired",
+    "cancelled",
+    "unknown_interaction",
+    "unknown_run",
+    "binding_mismatch",
+    "invalid_response",
+    "transport_failure",
+]);
+/** Durable result of one interaction response operation. */
+export const InteractionAcknowledgementSchema = z
+    .strictObject({
+    operationId: z.string().min(1),
+    binding: InteractionBindingSchema,
+    status: InteractionAcknowledgementStatusSchema,
+    message: z.string().min(1).optional(),
+    retryable: z.boolean().optional(),
+})
+    .superRefine((acknowledgement, context) => {
+    if (["invalid_response", "transport_failure"].includes(acknowledgement.status) &&
+        acknowledgement.message === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["message"],
+            message: `${acknowledgement.status} must include a message`,
+        });
+    }
+    if (acknowledgement.status === "transport_failure" &&
+        acknowledgement.retryable === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["retryable"],
+            message: "transport_failure must state whether retry is safe",
+        });
+    }
 });
 // =============================================================================
 // Well-known kinds + helpers.
@@ -150,20 +432,28 @@ export const PermissionGrantSchema = z.enum([
     "allow_always",
     "deny",
 ]);
-/** Build the answer spec for a `permission` interaction (graduated grant + feedback). */
+/** Build a permission answer spec that cannot offer a broader reusable grant. */
 export function permissionAnswerSpec(opts) {
+    const scopes = new Set(opts?.responseScopes ?? ["interaction"]);
+    const options = [
+        ...(scopes.has("interaction")
+            ? [{ value: "allow_once", label: "Allow once" }]
+            : []),
+        ...(scopes.has("session")
+            ? [{ value: "allow_session", label: "Allow for this session" }]
+            : []),
+        ...(scopes.has("persistent")
+            ? [{ value: "allow_always", label: "Always allow" }]
+            : []),
+        { value: "deny", label: "Deny" },
+    ];
     const fields = [
         {
             type: "select",
             name: PERMISSION_GRANT_FIELD,
             label: "Decision",
             required: true,
-            options: [
-                { value: "allow_once", label: "Allow once" },
-                { value: "allow_session", label: "Allow for this session" },
-                { value: "allow_always", label: "Always allow" },
-                { value: "deny", label: "Deny" },
-            ],
+            options,
         },
     ];
     if (opts?.allowFeedback !== false) {
@@ -183,6 +473,12 @@ export function permissionAnswerSpec(opts) {
 export function validateInteractionAnswer(spec, data) {
     const errors = [];
     const d = data ?? {};
+    const knownFields = new Set(spec.fields.map((field) => field.name));
+    for (const fieldName of Object.keys(d)) {
+        if (!knownFields.has(fieldName)) {
+            errors.push(`unknown field "${fieldName}"`);
+        }
+    }
     for (const field of spec.fields) {
         const v = d[field.name];
         const present = v !== undefined && v !== null && !(typeof v === "string" && v === "");
@@ -198,8 +494,8 @@ export function validateInteractionAnswer(spec, data) {
                     errors.push(`field "${field.name}" must be a string`);
                 break;
             case "number":
-                if (typeof v !== "number") {
-                    errors.push(`field "${field.name}" must be a number`);
+                if (typeof v !== "number" || !Number.isFinite(v)) {
+                    errors.push(`field "${field.name}" must be a finite number`);
                 }
                 else {
                     if (field.min !== undefined && v < field.min)
@@ -240,3 +536,48 @@ export function validateInteractionAnswer(spec, data) {
     }
     return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
+/** Validate one response against the exact outstanding request. */
+export function validateInteractionResponse(request, response) {
+    const parsed = InteractionResponseSchema.safeParse(response);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            errors: parsed.error.issues.map((issue) => issue.message),
+        };
+    }
+    const errors = request.id === parsed.data.id
+        ? validateResolutionForRequest(request, parsed.data)
+        : ["response id does not match the outstanding interaction"];
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+function validateResolutionForRequest(request, resolution) {
+    if (resolution.outcome !== "accepted")
+        return [];
+    const validation = validateInteractionAnswer(request.answerSpec, resolution.data);
+    const errors = validation.ok ? [] : [...validation.errors];
+    if (request.kind !== InteractionKind.Permission)
+        return errors;
+    const grant = resolution.data?.[PERMISSION_GRANT_FIELD];
+    if (!Array.isArray(grant) || grant.length !== 1) {
+        errors.push('permission response must select exactly one "grant" value');
+        return errors;
+    }
+    const parsedGrant = PermissionGrantSchema.safeParse(grant[0]);
+    if (!parsedGrant.success) {
+        errors.push(`permission response has invalid grant "${String(grant[0])}"`);
+        return errors;
+    }
+    if (parsedGrant.data === "deny")
+        return errors;
+    const requiredScope = {
+        allow_once: "interaction",
+        allow_session: "session",
+        allow_always: "persistent",
+        deny: "interaction",
+    };
+    const permitted = new Set(request.responseScopes ?? ["interaction"]);
+    if (!permitted.has(requiredScope[parsedGrant.data])) {
+        errors.push(`permission grant "${parsedGrant.data}" exceeds the request's response scopes`);
+    }
+    return errors;
+}