@tangle-network/agent-interface 0.11.1 → 0.12.0

package/dist/index.d.ts

@@ -4,12 +4,19 @@
  * Shared types and interfaces for SDK provider adapters.
  * This package defines the contract between the sidecar and provider implementations.
  */
+import type { InteractionRequest, InteractionResponse } from "./interaction.js";
 export type BackendCapabilities = {
     streaming: boolean;
     toolUse: boolean;
     reasoning: boolean;
     multimodal: boolean;
     contextWindow: number;
+    /**
+     * Interaction kinds this provider can originate (e.g. `["question",
+     * "permission"]`). Empty/undefined means the provider never asks the user.
+     * Consumers use this to decide what human-in-the-loop UI to offer.
+     */
+    interactions?: string[];
 };
 /**
  * High-signal feature flags surfaced by each provider package. Routes
@@ -198,7 +205,22 @@ export type StreamEvent = MessagePartUpdatedEvent | {
         created?: number;
         updated?: number;
     };
-} | {
+}
+/** Agent asks the user; answered via `respondToInteraction`. The generalized
+ * human-in-the-loop event (question, permission, plan, …). */
+ | {
+    type: "interaction";
+    request: InteractionRequest;
+}
+/** Agent withdraws an outstanding interaction (no longer needs the answer). */
+ | {
+    type: "interaction.cancel";
+    id: string;
+    reason?: string;
+}
+/** @deprecated Use the `interaction` event with `kind: "question"`. Retained
+ * so existing emitters/consumers keep working during migration. */
+ | {
     type: "question";
     questionId: string;
     questions: Array<{
@@ -583,8 +605,19 @@ export interface SdkProviderAdapter {
     listAgentMessages?(agentId: string, options?: BackendListOptions): Promise<unknown>;
     listArtifacts?(sessionId: string): Promise<BackendArtifact[]>;
     downloadArtifact?(sessionId: string, path: string): Promise<Uint8Array>;
+    /**
+     * Respond to an outstanding interaction (question, permission, …). The
+     * generalized inbound channel; the adapter translates the response into the
+     * provider's native control call to unblock the agent.
+     */
+    respondToInteraction?(response: InteractionResponse): Promise<void>;
+    /**
+     * @deprecated Use `respondToInteraction`. Retained for back-compat; an
+     * adapter implementing only this still answers `kind: "question"` asks.
+     */
     submitQuestionAnswer?(answers: Record<string, string[]>): Promise<void>;
 }
+export * from "./interaction.js";
 export * from "./agent-profile.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";

package/dist/index.js

@@ -122,6 +122,7 @@ export function resolveNativeWebTools(tools) {
     }
     return posture;
 }
+export * from "./interaction.js";
 export * from "./agent-profile.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";

package/dist/interaction.d.ts

@@ -0,0 +1,281 @@
+/**
+ * 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>;
+    default: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, 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.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    default: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"select">;
+    options: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    multi: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"secret">;
+    placeholder: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    label: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>], "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>;
+        default: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, 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.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"boolean">;
+        default: z.ZodOptional<z.ZodBoolean>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"select">;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        multi: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"secret">;
+        placeholder: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        label: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+export type InteractionAnswerSpec = z.infer<typeof InteractionAnswerSpecSchema>;
+export declare const InteractionSubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"tool">;
+    toolName: z.ZodString;
+    input: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"command">;
+    command: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    path: z.ZodString;
+    preview: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"resource">;
+    uri: z.ZodString;
+}, z.core.$strip>], "type">;
+export type InteractionSubject = z.infer<typeof InteractionSubjectSchema>;
+export declare const InteractionOutcomeSchema: z.ZodEnum<{
+    accepted: "accepted";
+    declined: "declined";
+    cancelled: "cancelled";
+}>;
+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.ZodObject<{
+    outcome: z.ZodEnum<{
+        accepted: "accepted";
+        declined: "declined";
+        cancelled: "cancelled";
+    }>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+}, z.core.$strip>;
+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.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"command">;
+        command: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        path: z.ZodString;
+        preview: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"resource">;
+        uri: z.ZodString;
+    }, z.core.$strip>], "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>;
+            default: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            label: z.ZodString;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, 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.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"boolean">;
+            default: z.ZodOptional<z.ZodBoolean>;
+            name: z.ZodString;
+            label: z.ZodString;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"select">;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            multi: z.ZodOptional<z.ZodBoolean>;
+            default: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            name: z.ZodString;
+            label: z.ZodString;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"secret">;
+            placeholder: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            label: z.ZodString;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>;
+    default: z.ZodOptional<z.ZodObject<{
+        outcome: z.ZodEnum<{
+            accepted: "accepted";
+            declined: "declined";
+            cancelled: "cancelled";
+        }>;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+    }, z.core.$strip>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    onTimeout: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        fail: "fail";
+        wait: "wait";
+    }>>;
+}, z.core.$strip>;
+export type InteractionRequest = z.infer<typeof InteractionRequestSchema>;
+export declare const InteractionResponseSchema: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        accepted: "accepted";
+        declined: "declined";
+        cancelled: "cancelled";
+    }>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type InteractionResponse = z.infer<typeof InteractionResponseSchema>;
+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 the answer spec for a `permission` interaction (graduated grant + feedback). */
+export declare function permissionAnswerSpec(opts?: {
+    allowFeedback?: boolean;
+}): InteractionAnswerSpec;
+/** Shape of one legacy question (kept for the back-compat shim). */
+export type LegacyQuestion = {
+    question: string;
+    options?: Array<{
+        label: string;
+        description?: string;
+    }>;
+    multiSelect?: boolean;
+};
+/**
+ * Build an answer spec from the legacy `question` event shape. Each question
+ * becomes one select field (free text when it declares no options), so the old
+ * question/answer path is expressible as a `question` interaction.
+ */
+export declare function questionAnswerSpec(questions: LegacyQuestion[]): 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;

package/dist/interaction.js

@@ -0,0 +1,250 @@
+/**
+ * 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";
+// =============================================================================
+// Answer specification — describes the shape of a valid answer.
+// =============================================================================
+const FieldBase = {
+    /** Stable key the answer is returned under in `InteractionResponse.data`. */
+    name: z.string().min(1),
+    /** Human-readable label for the form control. */
+    label: z.string().min(1),
+    /** Whether the answer must supply this field to be `accepted`. */
+    required: z.boolean().optional(),
+};
+export const InteractionFieldSchema = z.discriminatedUnion("type", [
+    z.object({
+        ...FieldBase,
+        type: z.literal("text"),
+        multiline: z.boolean().optional(),
+        placeholder: z.string().optional(),
+        default: z.string().optional(),
+    }),
+    z.object({
+        ...FieldBase,
+        type: z.literal("number"),
+        min: z.number().optional(),
+        max: z.number().optional(),
+        default: z.number().optional(),
+    }),
+    z.object({
+        ...FieldBase,
+        type: z.literal("boolean"),
+        default: z.boolean().optional(),
+    }),
+    z.object({
+        ...FieldBase,
+        type: z.literal("select"),
+        options: z
+            .array(z.object({
+            value: z.string(),
+            label: z.string(),
+            description: z.string().optional(),
+        }))
+            .min(1),
+        /** When true the user may pick more than one option. */
+        multi: z.boolean().optional(),
+        default: z.array(z.string()).optional(),
+    }),
+    /** Like `text` but the value is sensitive (token/key) and must be masked. */
+    z.object({
+        ...FieldBase,
+        type: z.literal("secret"),
+        placeholder: z.string().optional(),
+    }),
+]);
+export const InteractionAnswerSpecSchema = z.object({
+    fields: z.array(InteractionFieldSchema),
+});
+// =============================================================================
+// 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() }),
+]);
+// =============================================================================
+// Outcome + resolution — the answer.
+// =============================================================================
+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(),
+});
+// =============================================================================
+// The request envelope.
+// =============================================================================
+export const InteractionRequestSchema = z.object({
+    /** Correlation id; unique within a session. The response carries the same id. */
+    id: z.string().min(1),
+    /**
+     * Open label for rendering, handling, and authorization. Well-known values:
+     * `question` | `permission` | `plan`. Vendor extensions SHOULD namespace,
+     * e.g. `x-pi.choose-extension`.
+     */
+    kind: z.string().min(1),
+    /** Short human-readable prompt. */
+    title: z.string().min(1),
+    /** Optional longer context (markdown). */
+    body: z.string().optional(),
+    subject: InteractionSubjectSchema.optional(),
+    answerSpec: InteractionAnswerSpecSchema,
+    /** 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(),
+});
+export const InteractionResponseSchema = InteractionResolutionSchema.extend({
+    id: z.string().min(1),
+});
+// =============================================================================
+// 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 the answer spec for a `permission` interaction (graduated grant + feedback). */
+export function permissionAnswerSpec(opts) {
+    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" },
+            ],
+        },
+    ];
+    if (opts?.allowFeedback !== false) {
+        fields.push({
+            type: "text",
+            name: PERMISSION_FEEDBACK_FIELD,
+            label: "Feedback (optional)",
+            multiline: true,
+        });
+    }
+    return { fields };
+}
+/**
+ * Build an answer spec from the legacy `question` event shape. Each question
+ * becomes one select field (free text when it declares no options), so the old
+ * question/answer path is expressible as a `question` interaction.
+ */
+export function questionAnswerSpec(questions) {
+    const fields = questions.map((q, i) => {
+        const name = `q${i}`;
+        if (q.options && q.options.length > 0) {
+            return {
+                type: "select",
+                name,
+                label: q.question,
+                required: true,
+                multi: q.multiSelect === true,
+                options: q.options.map((o) => ({ value: o.label, label: o.label, description: o.description })),
+            };
+        }
+        return { type: "text", name, label: q.question, required: true };
+    });
+    return { fields };
+}
+/**
+ * Validate an accepted answer against its spec. Used by the broker before a
+ * response reaches the adapter, so malformed answers are rejected centrally.
+ */
+export function validateInteractionAnswer(spec, data) {
+    const errors = [];
+    const d = data ?? {};
+    for (const field of spec.fields) {
+        const v = d[field.name];
+        const present = v !== undefined && v !== null && !(typeof v === "string" && v === "");
+        if (!present) {
+            if (field.required)
+                errors.push(`missing required field "${field.name}"`);
+            continue;
+        }
+        switch (field.type) {
+            case "text":
+            case "secret":
+                if (typeof v !== "string")
+                    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`);
+                }
+                else {
+                    if (field.min !== undefined && v < field.min)
+                        errors.push(`field "${field.name}" below min ${field.min}`);
+                    if (field.max !== undefined && v > field.max)
+                        errors.push(`field "${field.name}" above max ${field.max}`);
+                }
+                break;
+            case "boolean":
+                if (typeof v !== "boolean")
+                    errors.push(`field "${field.name}" must be a boolean`);
+                break;
+            case "select": {
+                if (!Array.isArray(v)) {
+                    errors.push(`field "${field.name}" must be an array of option values`);
+                    break;
+                }
+                if (!field.multi && v.length > 1)
+                    errors.push(`field "${field.name}" accepts a single value`);
+                if (field.required && v.length === 0)
+                    errors.push(`field "${field.name}" requires a selection`);
+                const allowed = new Set(field.options.map((o) => o.value));
+                for (const choice of v) {
+                    if (!allowed.has(choice))
+                        errors.push(`field "${field.name}" has invalid option "${choice}"`);
+                }
+                break;
+            }
+        }
+    }
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}

package/dist/profile-schema.d.ts

@@ -3,17 +3,17 @@ import type { AgentProfile } from "./agent-profile.js";
 import { type SandboxSizePreset } from "./sandbox-size.js";
 export declare const agentProfilePermissionValueSchema: z.ZodEnum<{
     allow: "allow";
-    deny: "deny";
     ask: "ask";
+    deny: "deny";
 }>;
 export declare const agentProfilePermissionSchema: z.ZodUnion<readonly [z.ZodEnum<{
     allow: "allow";
-    deny: "deny";
     ask: "ask";
+    deny: "deny";
 }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
     allow: "allow";
-    deny: "deny";
     ask: "ask";
+    deny: "deny";
 }>>]>;
 export declare const agentProfileResourceRefSchema: z.ZodUnion<readonly [z.ZodObject<{
     kind: z.ZodLiteral<"inline">;
@@ -119,10 +119,10 @@ export declare const agentProfileModelHintsSchema: z.ZodObject<{
     small: z.ZodOptional<z.ZodString>;
     provider: z.ZodOptional<z.ZodString>;
     reasoningEffort: z.ZodOptional<z.ZodEnum<{
-        medium: "medium";
         none: "none";
         minimal: "minimal";
         low: "low";
+        medium: "medium";
         high: "high";
         xhigh: "xhigh";
         ultracode: "ultracode";
@@ -140,12 +140,12 @@ export declare const agentSubagentProfileSchema: z.ZodObject<{
     tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
     permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
         allow: "allow";
-        deny: "deny";
         ask: "ask";
+        deny: "deny";
     }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
         allow: "allow";
-        deny: "deny";
         ask: "ask";
+        deny: "deny";
     }>>]>>>;
     maxSteps: z.ZodOptional<z.ZodNumber>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -164,12 +164,12 @@ export declare const agentProfileModeSchema: z.ZodObject<{
     tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
     permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
         allow: "allow";
-        deny: "deny";
         ask: "ask";
+        deny: "deny";
     }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
         allow: "allow";
-        deny: "deny";
         ask: "ask";
+        deny: "deny";
     }>>]>>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
@@ -218,10 +218,10 @@ export declare const agentProfileSchema: z.ZodObject<{
         small: z.ZodOptional<z.ZodString>;
         provider: z.ZodOptional<z.ZodString>;
         reasoningEffort: z.ZodOptional<z.ZodEnum<{
-            medium: "medium";
             none: "none";
             minimal: "minimal";
             low: "low";
+            medium: "medium";
             high: "high";
             xhigh: "xhigh";
             ultracode: "ultracode";
@@ -230,12 +230,12 @@ export declare const agentProfileSchema: z.ZodObject<{
     }, z.core.$strip>>;
     permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
         allow: "allow";
-        deny: "deny";
         ask: "ask";
+        deny: "deny";
     }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
         allow: "allow";
-        deny: "deny";
         ask: "ask";
+        deny: "deny";
     }>>]>>>;
     tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
     mcp: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -265,12 +265,12 @@ export declare const agentProfileSchema: z.ZodObject<{
         tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
         permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
             allow: "allow";
-            deny: "deny";
             ask: "ask";
+            deny: "deny";
         }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
             allow: "allow";
-            deny: "deny";
             ask: "ask";
+            deny: "deny";
         }>>]>>>;
         maxSteps: z.ZodOptional<z.ZodNumber>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -362,12 +362,12 @@ export declare const agentProfileSchema: z.ZodObject<{
         tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
         permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
             allow: "allow";
-            deny: "deny";
             ask: "ask";
+            deny: "deny";
         }>, z.ZodRecord<z.ZodString, z.ZodEnum<{
             allow: "allow";
-            deny: "deny";
             ask: "ask";
+            deny: "deny";
         }>>]>>>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",