@tangle-network/agent-interface 0.45.0 → 0.46.0

package/dist/interaction-resolution-validation.d.ts

@@ -0,0 +1,9 @@
+import type { InteractionResolution } from "./interaction-data.js";
+import type { InteractionAnswerSpec, InteractionResponseScope } from "./interaction-fields.js";
+type InteractionResolutionRequest = {
+    kind: string;
+    answerSpec: InteractionAnswerSpec;
+    responseScopes?: InteractionResponseScope[];
+};
+export declare function validateResolutionForRequest(request: InteractionResolutionRequest, resolution: InteractionResolution): string[];
+export {};

package/dist/interaction-resolution-validation.js

@@ -0,0 +1,50 @@
+import { InteractionKind, PermissionGrantSchema, PERMISSION_GRANT_FIELD } from "./interaction-permissions.js";
+import { validateInteractionAnswer } from "./interaction-answer-validation.js";
+/**
+ * A declined or cancelled resolution submits no answer, so any secret-typed
+ * field it carries can only be leakage into a transport that retains it.
+ */
+function secretFieldErrors(spec, resolution) {
+    const secretFields = new Set(spec.fields
+        .filter((field) => field.type === "secret")
+        .map((field) => field.name));
+    return Object.keys(resolution.data ?? {})
+        .filter((fieldName) => secretFields.has(fieldName))
+        .map((fieldName) => `field "${fieldName}" is secret and cannot ride a ${resolution.outcome} resolution`);
+}
+export function validateResolutionForRequest(request, resolution) {
+    if (resolution.outcome !== "accepted") {
+        const errors = secretFieldErrors(request.answerSpec, resolution);
+        if (Object.keys(resolution.data ?? {}).length > 0) {
+            errors.push(`a ${resolution.outcome} resolution cannot carry answer fields`);
+        }
+        return errors;
+    }
+    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;
+}

package/dist/interaction-response-validation.d.ts

@@ -0,0 +1,17 @@
+import { type InteractionRequest, type InteractionResponse, type InteractionResponseCommand } from "./interaction-envelope.js";
+import { type InteractionValidation } from "./interaction-answer-validation.js";
+export type InteractionResponseValidation = {
+    ok: true;
+    response: InteractionResponse;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Validate one response against the exact outstanding request. */
+export declare function validateInteractionResponse(request: InteractionRequest, response: unknown): InteractionResponseValidation;
+/** Validate a durable response command, including its run and request digest. */
+export declare function validateInteractionResponseCommand(request: InteractionRequest, command: InteractionResponseCommand): InteractionResponseValidation;
+/** Parse and return the safe response for callers that need an enumerable result. */
+export declare function validateAndParseInteractionResponse(request: InteractionRequest, response: unknown): InteractionResponseValidation;
+/** Verdict-only form for callers that never forward the value. */
+export declare function interactionResponseIsValid(request: InteractionRequest, response: unknown): InteractionValidation;

package/dist/interaction-response-validation.js

@@ -0,0 +1,102 @@
+import { InteractionRequestSchema, InteractionResponseCommandSchema, InteractionResponseSchema, } from "./interaction-envelope.js";
+import { validateResolutionForRequest } from "./interaction-resolution-validation.js";
+const FORBIDDEN_DATA_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function validResponse(response) {
+    const result = { ok: true };
+    Object.defineProperty(result, "response", {
+        value: response,
+        enumerable: false,
+        writable: false,
+    });
+    return result;
+}
+function forbiddenKeyErrors(response) {
+    if (!response || typeof response !== "object")
+        return [];
+    const data = response.data;
+    if (!data || typeof data !== "object")
+        return [];
+    return Object.getOwnPropertyNames(data)
+        .filter((key) => FORBIDDEN_DATA_KEYS.has(key))
+        .map((key) => `unknown field "${key}"`);
+}
+/** Validate one response against the exact outstanding request. */
+export function validateInteractionResponse(request, response) {
+    const parsedRequest = InteractionRequestSchema.safeParse(request);
+    if (!parsedRequest.success) {
+        return {
+            ok: false,
+            errors: parsedRequest.error.issues.map((issue) => issue.message),
+        };
+    }
+    const exactRequest = parsedRequest.data;
+    const forbidden = forbiddenKeyErrors(response);
+    if (forbidden.length > 0)
+        return { ok: false, errors: forbidden };
+    const parsed = InteractionResponseSchema.safeParse(response);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            errors: parsed.error.issues.map((issue) => issue.message),
+        };
+    }
+    if (exactRequest.id !== parsed.data.id) {
+        return {
+            ok: false,
+            errors: ["response id does not match the outstanding interaction"],
+        };
+    }
+    if (exactRequest.allowedOutcomes !== undefined &&
+        !exactRequest.allowedOutcomes.includes(parsed.data.outcome)) {
+        return {
+            ok: false,
+            errors: ["response outcome is not allowed by the outstanding interaction"],
+        };
+    }
+    const errors = validateResolutionForRequest(exactRequest, parsed.data);
+    if (errors.length > 0)
+        return { ok: false, errors };
+    // Secret answers are ephemeral input for the provider call. The caller that
+    // persists interaction records must redact them before journaling or tracing.
+    return validResponse(parsed.data);
+}
+/** Validate a durable response command, including its run and request digest. */
+export function validateInteractionResponseCommand(request, command) {
+    const parsedRequest = InteractionRequestSchema.safeParse(request);
+    if (!parsedRequest.success) {
+        return {
+            ok: false,
+            errors: parsedRequest.error.issues.map((issue) => issue.message),
+        };
+    }
+    const parsedCommand = InteractionResponseCommandSchema.safeParse(command);
+    if (!parsedCommand.success) {
+        return {
+            ok: false,
+            errors: parsedCommand.error.issues.map((issue) => issue.message),
+        };
+    }
+    const binding = parsedCommand.data.binding;
+    if (binding.requestDigest !== parsedRequest.data.requestDigest ||
+        binding.runId !== parsedRequest.data.binding.runId ||
+        binding.provider !== parsedRequest.data.binding.provider ||
+        binding.environmentId !== parsedRequest.data.binding.environmentId ||
+        binding.sessionId !== parsedRequest.data.binding.sessionId ||
+        binding.executionId !== parsedRequest.data.binding.executionId ||
+        binding.interactionId !== parsedRequest.data.binding.interactionId) {
+        return { ok: false, errors: ["response command binding is stale"] };
+    }
+    return validateInteractionResponse(parsedRequest.data, parsedCommand.data.response);
+}
+/** Parse and return the safe response for callers that need an enumerable result. */
+export function validateAndParseInteractionResponse(request, response) {
+    const result = validateInteractionResponse(request, response);
+    if (!result.ok)
+        return result;
+    return { ok: true, response: result.response };
+}
+/** Verdict-only form for callers that never forward the value. */
+export function interactionResponseIsValid(request, response) {
+    const result = validateInteractionResponse(request, response);
+    return result.ok ? { ok: true } : { ok: false, errors: result.errors };
+}

package/dist/interaction.d.ts

@@ -1,397 +1,6 @@
-/**
- * Interaction contract — the generalized human-in-the-loop primitive.
- *
- * An agent emits an `InteractionRequest`: a typed ask that carries a
- * self-describing `answerSpec` (the fields and types of a valid answer). A
- * human (or an automated policy) returns an `InteractionResponse` keyed by the
- * same `id`. This subsumes the original question/answer pair and extends it to
- * permissions, plans, and provider-specific asks.
- *
- * Design contract:
- * - The envelope is stable; `kind` is an OPEN label, so new ask types need no
- *   change to this contract. Well-known kinds (see `InteractionKind`) get
- *   richer rendering and platform handling; unknown kinds render generically
- *   from `answerSpec` and still work end-to-end.
- * - `answerSpec` is a small closed set of flat field types, so any consumer can
- *   render a form and validate a response without a general schema engine. This
- *   mirrors MCP elicitation so MCP-originated asks map onto this 1:1.
- * - `default` + `timeoutMs`/`onTimeout` make unattended resolution explicit and
- *   auditable, replacing blanket permission-bypass flags.
- */
-import { z } from "zod";
-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>;
-export declare const InteractionSubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    type: z.ZodLiteral<"tool">;
-    toolName: z.ZodString;
-    input: z.ZodOptional<z.ZodUnknown>;
-}, z.core.$strict>, z.ZodObject<{
-    type: z.ZodLiteral<"command">;
-    command: z.ZodString;
-}, z.core.$strict>, z.ZodObject<{
-    type: z.ZodLiteral<"file">;
-    path: z.ZodString;
-    preview: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>, z.ZodObject<{
-    type: z.ZodLiteral<"resource">;
-    uri: z.ZodString;
-}, z.core.$strict>], "type">;
-export type InteractionSubject = z.infer<typeof InteractionSubjectSchema>;
-export declare const InteractionOutcomeSchema: z.ZodEnum<{
-    cancelled: "cancelled";
-    accepted: "accepted";
-    declined: "declined";
-}>;
-export type InteractionOutcome = z.infer<typeof InteractionOutcomeSchema>;
-/** Field values keyed by `InteractionField.name`. Validated against `answerSpec`. */
-export declare const InteractionDataSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
-export type InteractionData = z.infer<typeof InteractionDataSchema>;
-export declare const InteractionResolutionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    outcome: z.ZodLiteral<"accepted">;
-    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-}, z.core.$strict>, z.ZodObject<{
-    outcome: z.ZodLiteral<"declined">;
-    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-}, z.core.$strict>, z.ZodObject<{
-    outcome: z.ZodLiteral<"cancelled">;
-    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-}, z.core.$strict>], "outcome">;
-export type InteractionResolution = z.infer<typeof InteractionResolutionSchema>;
-export declare const InteractionRequestSchema: z.ZodObject<{
-    id: z.ZodString;
-    kind: z.ZodString;
-    title: z.ZodString;
-    body: z.ZodOptional<z.ZodString>;
-    subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        type: z.ZodLiteral<"tool">;
-        toolName: z.ZodString;
-        input: z.ZodOptional<z.ZodUnknown>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"command">;
-        command: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"file">;
-        path: z.ZodString;
-        preview: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"resource">;
-        uri: z.ZodString;
-    }, z.core.$strict>], "type">>;
-    answerSpec: 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>;
-    responseScopes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        interaction: "interaction";
-        session: "session";
-        persistent: "persistent";
-    }>>>;
-    default: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        outcome: z.ZodLiteral<"accepted">;
-        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    }, z.core.$strict>, z.ZodObject<{
-        outcome: z.ZodLiteral<"declined">;
-        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    }, z.core.$strict>, z.ZodObject<{
-        outcome: z.ZodLiteral<"cancelled">;
-        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    }, z.core.$strict>], "outcome">>;
-    timeoutMs: z.ZodOptional<z.ZodNumber>;
-    onTimeout: z.ZodOptional<z.ZodEnum<{
-        default: "default";
-        fail: "fail";
-        wait: "wait";
-    }>>;
-}, z.core.$strict>;
-export type InteractionRequest = z.infer<typeof InteractionRequestSchema>;
-export declare const InteractionResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    id: z.ZodString;
-    outcome: z.ZodLiteral<"accepted">;
-    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-}, z.core.$strict>, z.ZodObject<{
-    id: z.ZodString;
-    outcome: z.ZodLiteral<"declined">;
-    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-}, z.core.$strict>, z.ZodObject<{
-    id: z.ZodString;
-    outcome: z.ZodLiteral<"cancelled">;
-    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-}, z.core.$strict>], "outcome">;
-export type InteractionResponse = z.infer<typeof InteractionResponseSchema>;
-/** A request is unique only within this run and optional provider session. */
-export declare const InteractionBindingSchema: z.ZodObject<{
-    runId: z.ZodString;
-    environmentId: z.ZodString;
-    sessionId: z.ZodOptional<z.ZodString>;
-    interactionId: z.ZodString;
-}, z.core.$strict>;
-export type InteractionBinding = z.infer<typeof InteractionBindingSchema>;
-/** Retryable command sent to an environment or retained session. */
-export declare const InteractionResponseCommandSchema: z.ZodObject<{
-    operationId: z.ZodString;
-    binding: z.ZodObject<{
-        runId: z.ZodString;
-        environmentId: z.ZodString;
-        sessionId: z.ZodOptional<z.ZodString>;
-        interactionId: z.ZodString;
-    }, z.core.$strict>;
-    response: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        id: z.ZodString;
-        outcome: z.ZodLiteral<"accepted">;
-        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    }, z.core.$strict>, z.ZodObject<{
-        id: z.ZodString;
-        outcome: z.ZodLiteral<"declined">;
-        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    }, z.core.$strict>, z.ZodObject<{
-        id: z.ZodString;
-        outcome: z.ZodLiteral<"cancelled">;
-        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
-    }, z.core.$strict>], "outcome">;
-}, z.core.$strict>;
-export type InteractionResponseCommand = z.infer<typeof InteractionResponseCommandSchema>;
-export declare const InteractionAcknowledgementStatusSchema: z.ZodEnum<{
-    cancelled: "cancelled";
-    expired: "expired";
-    accepted: "accepted";
-    already_resolved_same: "already_resolved_same";
-    already_resolved_different: "already_resolved_different";
-    unknown_interaction: "unknown_interaction";
-    unknown_run: "unknown_run";
-    binding_mismatch: "binding_mismatch";
-    invalid_response: "invalid_response";
-    transport_failure: "transport_failure";
-}>;
-export type InteractionAcknowledgementStatus = z.infer<typeof InteractionAcknowledgementStatusSchema>;
-/** Durable result of one interaction response operation. */
-export declare const InteractionAcknowledgementSchema: z.ZodObject<{
-    operationId: z.ZodString;
-    binding: z.ZodObject<{
-        runId: z.ZodString;
-        environmentId: z.ZodString;
-        sessionId: z.ZodOptional<z.ZodString>;
-        interactionId: z.ZodString;
-    }, z.core.$strict>;
-    status: z.ZodEnum<{
-        cancelled: "cancelled";
-        expired: "expired";
-        accepted: "accepted";
-        already_resolved_same: "already_resolved_same";
-        already_resolved_different: "already_resolved_different";
-        unknown_interaction: "unknown_interaction";
-        unknown_run: "unknown_run";
-        binding_mismatch: "binding_mismatch";
-        invalid_response: "invalid_response";
-        transport_failure: "transport_failure";
-    }>;
-    message: z.ZodOptional<z.ZodString>;
-    retryable: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-export type InteractionAcknowledgement = z.infer<typeof InteractionAcknowledgementSchema>;
-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;
-export type InteractionValidation = {
-    ok: true;
-} | {
-    ok: false;
-    errors: string[];
-};
-/**
- * Validate an accepted answer against its spec. Used by the broker before a
- * response reaches the adapter, so malformed answers are rejected centrally.
- */
-export declare function validateInteractionAnswer(spec: InteractionAnswerSpec, data: InteractionData | undefined): InteractionValidation;
-/** Validate one response against the exact outstanding request. */
-export declare function validateInteractionResponse(request: InteractionRequest, response: InteractionResponse): InteractionValidation;
+export * from "./interaction-fields.js";
+export * from "./interaction-data.js";
+export * from "./interaction-envelope.js";
+export * from "./interaction-permissions.js";
+export * from "./interaction-answer-validation.js";
+export * from "./interaction-response-validation.js";