@tangle-network/agent-interface 0.45.0 → 0.46.0

package/dist/interaction-envelope.js

@@ -0,0 +1,245 @@
+import { z } from "zod";
+import { canonicalCandidateDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { boundedIdentifierSchema, boundedJsonSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, } from "./contract-limits.js";
+import { InteractionDataSchema, InteractionResolutionSchema, } from "./interaction-data.js";
+import { InteractionAnswerSpecSchema, InteractionResponseScopeSchema, } from "./interaction-fields.js";
+import { validateResolutionForRequest } from "./interaction-resolution-validation.js";
+export { InteractionDataSchema, InteractionResolutionSchema, InteractionSecretReferenceSchema, } from "./interaction-data.js";
+const interactionOutcomeValues = ["accepted", "declined", "cancelled"];
+// =============================================================================
+// Subject — what the request is about (drives preview/permission UX).
+// =============================================================================
+export const InteractionSubjectSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("tool"),
+        toolName: boundedIdentifierSchema,
+        input: boundedJsonSchema.optional(),
+    }),
+    z.strictObject({ type: z.literal("command"), command: boundedStringSchema }),
+    z.strictObject({
+        type: z.literal("file"),
+        path: boundedStringSchema,
+        preview: boundedStringSchema.optional(),
+    }),
+    z.strictObject({ type: z.literal("resource"), uri: boundedStringSchema }),
+]);
+export const InteractionOutcomeSchema = z.enum(interactionOutcomeValues);
+export const InteractionRequestBindingSchema = z.strictObject({
+    runId: boundedIdentifierSchema,
+    provider: boundedIdentifierSchema,
+    environmentId: boundedIdentifierSchema,
+    sessionId: boundedIdentifierSchema,
+    executionId: boundedIdentifierSchema,
+    interactionId: boundedIdentifierSchema,
+});
+/** Binding carried by a response command and acknowledgement. */
+export const InteractionBindingSchema = z.strictObject({
+    ...InteractionRequestBindingSchema.shape,
+    requestDigest: sha256DigestSchema,
+});
+const InteractionRequestMaterialSchema = z.strictObject({
+    id: boundedIdentifierSchema,
+    kind: boundedIdentifierSchema,
+    title: boundedStringSchema.min(1),
+    body: boundedStringSchema.optional(),
+    subject: InteractionSubjectSchema.optional(),
+    answerSpec: InteractionAnswerSpecSchema,
+    responseScopes: z
+        .array(InteractionResponseScopeSchema)
+        .min(1)
+        .max(CONTRACT_MAX_ARRAY_LENGTH)
+        .optional(),
+    allowedOutcomes: z
+        .array(InteractionOutcomeSchema)
+        .min(1)
+        .max(interactionOutcomeValues.length)
+        .optional(),
+    default: InteractionResolutionSchema.optional(),
+    timeoutMs: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+    onTimeout: z.enum(["default", "fail", "wait"]).optional(),
+    binding: InteractionRequestBindingSchema,
+});
+export function interactionRequestDigest(request) {
+    const parsed = InteractionRequestMaterialSchema.parse(request);
+    rejectSecretDefaultValues(parsed);
+    return canonicalCandidateDigest(parsed);
+}
+function rejectSecretDefaultValues(request) {
+    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)) {
+            throw new Error("secret answers cannot be embedded in interaction defaults");
+        }
+    }
+}
+// =============================================================================
+// The request envelope.
+// =============================================================================
+export const InteractionRequestSchema = z
+    .strictObject({
+    ...InteractionRequestMaterialSchema.shape,
+    requestDigest: sha256DigestSchema,
+})
+    .superRefine((request, context) => {
+    if (request.binding.interactionId !== request.id) {
+        context.addIssue({
+            code: "custom",
+            path: ["binding", "interactionId"],
+            message: "interaction binding must name the request id",
+        });
+    }
+    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.allowedOutcomes &&
+        new Set(request.allowedOutcomes).size !== request.allowedOutcomes.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["allowedOutcomes"],
+            message: "interaction outcomes 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 &&
+        request.allowedOutcomes &&
+        !request.allowedOutcomes.includes(request.default.outcome)) {
+        context.addIssue({
+            code: "custom",
+            path: ["default", "outcome"],
+            message: "default outcome is not allowed by the request",
+        });
+    }
+    if (request.default) {
+        for (const error of validateResolutionForRequest(request, request.default)) {
+            context.addIssue({ code: "custom", path: ["default"], message: error });
+        }
+        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",
+            });
+        }
+    }
+    const { requestDigest: _digest, ...material } = request;
+    const hasSecretDefault = Object.keys(request.default?.data ?? {}).some((fieldName) => request.answerSpec.fields.some((field) => field.type === "secret" && field.name === fieldName));
+    if (!hasSecretDefault) {
+        if (request.requestDigest !== interactionRequestDigest(material)) {
+            context.addIssue({
+                code: "custom",
+                path: ["requestDigest"],
+                message: "interaction request digest does not match its content",
+            });
+        }
+    }
+});
+export const InteractionResponseSchema = z.discriminatedUnion("outcome", [
+    z.strictObject({
+        id: boundedIdentifierSchema,
+        outcome: z.literal("accepted"),
+        data: InteractionDataSchema.optional(),
+    }),
+    z.strictObject({
+        id: boundedIdentifierSchema,
+        outcome: z.literal("declined"),
+        data: InteractionDataSchema.optional(),
+    }),
+    z.strictObject({
+        id: boundedIdentifierSchema,
+        outcome: z.literal("cancelled"),
+        data: InteractionDataSchema.optional(),
+    }),
+]);
+/** Digest the exact binding and response carried by a retryable command. */
+export function interactionResponseCommandDigest(material) {
+    const binding = InteractionBindingSchema.parse(material.binding);
+    const response = InteractionResponseSchema.parse(material.response);
+    return canonicalCandidateDigest({ binding, response });
+}
+/** Retryable command sent to an environment or retained session. */
+export const InteractionResponseCommandSchema = z
+    .strictObject({
+    operationId: boundedIdentifierSchema,
+    binding: InteractionBindingSchema,
+    commandDigest: sha256DigestSchema,
+    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",
+        });
+    }
+    if (command.commandDigest !==
+        interactionResponseCommandDigest({
+            binding: command.binding,
+            response: command.response,
+        })) {
+        context.addIssue({
+            code: "custom",
+            path: ["commandDigest"],
+            message: "interaction response command digest does not match its content",
+        });
+    }
+});
+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: boundedIdentifierSchema,
+    binding: InteractionBindingSchema,
+    commandDigest: sha256DigestSchema,
+    status: InteractionAcknowledgementStatusSchema,
+    message: boundedStringSchema.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",
+        });
+    }
+});
+void InteractionOutcomeSchema;

package/dist/interaction-fields.d.ts

@@ -0,0 +1,130 @@
+import { z } from "zod";
+export declare const InteractionFieldNameSchema: z.ZodString;
+export declare const InteractionFieldSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"number">;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    default: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"select">;
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    multi: z.ZodOptional<z.ZodBoolean>;
+    allowCustom: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"secret">;
+    placeholder: z.ZodOptional<z.ZodString>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "type">;
+export type InteractionField = z.infer<typeof InteractionFieldSchema>;
+export declare const InteractionAnswerSpecSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        multiline: z.ZodOptional<z.ZodBoolean>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"number">;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodNumber>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"boolean">;
+        default: z.ZodOptional<z.ZodBoolean>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"select">;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        multi: z.ZodOptional<z.ZodBoolean>;
+        allowCustom: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"secret">;
+        placeholder: z.ZodOptional<z.ZodString>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>;
+export type InteractionAnswerSpec = z.infer<typeof InteractionAnswerSpecSchema>;
+export declare const InteractionFieldTypeSchema: z.ZodEnum<{
+    number: "number";
+    boolean: "boolean";
+    text: "text";
+    select: "select";
+    secret: "secret";
+}>;
+export type InteractionFieldType = z.infer<typeof InteractionFieldTypeSchema>;
+/** Scope at which an accepted answer may be reused by an explicit policy. */
+export declare const InteractionResponseScopeSchema: z.ZodEnum<{
+    interaction: "interaction";
+    session: "session";
+    persistent: "persistent";
+}>;
+export type InteractionResponseScope = z.infer<typeof InteractionResponseScopeSchema>;
+/** Negotiated interaction behavior. Absence means interactions are unsupported. */
+export declare const InteractionCapabilitiesSchema: z.ZodObject<{
+    kinds: z.ZodArray<z.ZodString>;
+    answerFieldTypes: z.ZodArray<z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        text: "text";
+        select: "select";
+        secret: "secret";
+    }>>;
+    responseScopes: z.ZodArray<z.ZodEnum<{
+        interaction: "interaction";
+        session: "session";
+        persistent: "persistent";
+    }>>;
+    secretAnswers: z.ZodBoolean;
+    concurrentRequests: z.ZodBoolean;
+    replay: z.ZodBoolean;
+    responseIdempotency: z.ZodBoolean;
+}, z.core.$strict>;
+export type InteractionCapabilities = z.infer<typeof InteractionCapabilitiesSchema>;

package/dist/interaction-fields.js

@@ -0,0 +1,227 @@
+import { z } from "zod";
+import { boundedIdentifierSchema, boundedStringSchema, CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_STRING_LENGTH, } from "./contract-limits.js";
+const forbiddenFieldNames = new Set(["__proto__", "constructor", "prototype"]);
+export const InteractionFieldNameSchema = boundedIdentifierSchema.refine((value) => !forbiddenFieldNames.has(value), "interaction field name is reserved");
+// =============================================================================
+// Answer specification — describes the shape of a valid answer.
+// =============================================================================
+const FieldBase = {
+    /** Stable key the answer is returned under in `InteractionResponse.data`. */
+    name: InteractionFieldNameSchema,
+    /** Human-readable label for the form control. */
+    label: boundedStringSchema.min(1),
+    /** Whether the answer must supply this field to be `accepted`. */
+    required: z.boolean().optional(),
+};
+export const InteractionFieldSchema = z
+    .discriminatedUnion("type", [
+    z.strictObject({
+        ...FieldBase,
+        type: z.literal("text"),
+        multiline: z.boolean().optional(),
+        placeholder: boundedStringSchema.optional(),
+        /** Maximum answer length chosen by the request author. */
+        maxLength: z.number().int().positive().max(CONTRACT_MAX_STRING_LENGTH).optional(),
+        default: boundedStringSchema.optional(),
+    }),
+    z.strictObject({
+        ...FieldBase,
+        type: z.literal("number"),
+        min: z.number().finite().optional(),
+        max: z.number().finite().optional(),
+        default: z.number().finite().optional(),
+    }),
+    z.strictObject({
+        ...FieldBase,
+        type: z.literal("boolean"),
+        default: z.boolean().optional(),
+    }),
+    z.strictObject({
+        ...FieldBase,
+        type: z.literal("select"),
+        options: z
+            .array(z.strictObject({
+            value: boundedIdentifierSchema,
+            label: boundedStringSchema.min(1),
+            description: boundedStringSchema.optional(),
+        }))
+            .min(1)
+            .max(CONTRACT_MAX_ARRAY_LENGTH),
+        /** When true the user may pick more than one option. */
+        multi: z.boolean().optional(),
+        /**
+         * When true the answer may contain write-in values outside `options`
+         * (e.g. a rendered "Other…" choice carrying the user's own text).
+         * Write-ins must still be non-empty strings.
+         */
+        allowCustom: z.boolean().optional(),
+        default: z.array(boundedIdentifierSchema).max(CONTRACT_MAX_ARRAY_LENGTH).optional(),
+    }),
+    /** Like `text` but the value is sensitive (token/key) and must be masked. */
+    z.strictObject({
+        ...FieldBase,
+        type: z.literal("secret"),
+        placeholder: boundedStringSchema.optional(),
+        /** Maximum answer length chosen by the request author. */
+        maxLength: z.number().int().positive().max(CONTRACT_MAX_STRING_LENGTH).optional(),
+    }),
+])
+    .superRefine((field, context) => {
+    if (field.type === "text" &&
+        field.default !== undefined &&
+        field.maxLength !== undefined &&
+        field.default.length > field.maxLength) {
+        context.addIssue({
+            code: "custom",
+            path: ["default"],
+            message: "text field default exceeds maxLength",
+        });
+        return;
+    }
+    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).max(CONTRACT_MAX_ARRAY_LENGTH),
+})
+    .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(boundedIdentifierSchema).min(1).max(CONTRACT_MAX_ARRAY_LENGTH),
+    answerFieldTypes: z.array(InteractionFieldTypeSchema).min(1).max(CONTRACT_MAX_ARRAY_LENGTH),
+    responseScopes: z.array(InteractionResponseScopeSchema).min(1).max(CONTRACT_MAX_ARRAY_LENGTH),
+    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",
+        });
+    }
+});

package/dist/interaction-permissions.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { InteractionAnswerSpec, InteractionResponseScope } from "./interaction-fields.js";
+export declare const InteractionKind: {
+    /** Agent asks the user to answer/choose. Answer = the chosen field values. */
+    readonly Question: "question";
+    /** Agent requests approval to run a tool/command. Answer = a `PermissionGrant`. */
+    readonly Permission: "permission";
+    /** Agent shares a plan/todo list for review/approval. */
+    readonly Plan: "plan";
+};
+export type WellKnownInteractionKind = (typeof InteractionKind)[keyof typeof InteractionKind];
+/** Field name carrying the grant on a `permission` interaction's response. */
+export declare const PERMISSION_GRANT_FIELD = "grant";
+/** Optional free-text field carrying the user's reason on a `permission` response. */
+export declare const PERMISSION_FEEDBACK_FIELD = "feedback";
+/** Graduated permission decision — the value of the `grant` field. */
+export declare const PermissionGrantSchema: z.ZodEnum<{
+    deny: "deny";
+    allow_once: "allow_once";
+    allow_session: "allow_session";
+    allow_always: "allow_always";
+}>;
+export type PermissionGrant = z.infer<typeof PermissionGrantSchema>;
+/** Build a permission answer spec that cannot offer a broader reusable grant. */
+export declare function permissionAnswerSpec(opts?: {
+    allowFeedback?: boolean;
+    responseScopes?: readonly InteractionResponseScope[];
+}): InteractionAnswerSpec;

package/dist/interaction-permissions.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+// =============================================================================
+// Well-known kinds + helpers.
+// =============================================================================
+export const InteractionKind = {
+    /** Agent asks the user to answer/choose. Answer = the chosen field values. */
+    Question: "question",
+    /** Agent requests approval to run a tool/command. Answer = a `PermissionGrant`. */
+    Permission: "permission",
+    /** Agent shares a plan/todo list for review/approval. */
+    Plan: "plan",
+};
+/** Field name carrying the grant on a `permission` interaction's response. */
+export const PERMISSION_GRANT_FIELD = "grant";
+/** Optional free-text field carrying the user's reason on a `permission` response. */
+export const PERMISSION_FEEDBACK_FIELD = "feedback";
+/** Graduated permission decision — the value of the `grant` field. */
+export const PermissionGrantSchema = z.enum([
+    "allow_once",
+    "allow_session",
+    "allow_always",
+    "deny",
+]);
+/** 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,
+        },
+    ];
+    if (opts?.allowFeedback !== false) {
+        fields.push({
+            type: "text",
+            name: PERMISSION_FEEDBACK_FIELD,
+            label: "Feedback (optional)",
+            multiline: true,
+        });
+    }
+    return { fields };
+}