@tangle-network/agent-interface 0.11.0 → 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<{
@@ -214,6 +236,13 @@ export type ToolInvocation = {
     toolName: string;
     input: unknown;
     result?: unknown;
+    /**
+     * True when the tool call failed (errored, timed out, or was rejected).
+     * Failed tools are recorded — not dropped — so the run outcome can reflect
+     * them. Consumers deriving success must treat any `isError: true` invocation
+     * as a failure signal.
+     */
+    isError?: boolean;
 };
 export type TokenUsage = {
     inputTokens: number;
@@ -576,9 +605,22 @@ 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";
 export * from "./profile-schema.js";
+export * from "./profile-security.js";
+export * from "./sandbox-size.js";

package/dist/index.js

@@ -122,7 +122,10 @@ export function resolveNativeWebTools(tools) {
     }
     return posture;
 }
+export * from "./interaction.js";
 export * from "./agent-profile.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";
 export * from "./profile-schema.js";
+export * from "./profile-security.js";
+export * from "./sandbox-size.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

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import type { AgentProfile } from "./agent-profile.js";
+import { type SandboxSizePreset } from "./sandbox-size.js";
 export declare const agentProfilePermissionValueSchema: z.ZodEnum<{
     allow: "allow";
     ask: "ask";
@@ -378,3 +380,24 @@ export declare const agentProfileSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodUndefined]>>>;
 }, z.core.$strip>;
+/**
+ * A registered capability: a stable id paired with its canonical
+ * {@link AgentProfile}. `definition` is the full profile (prompt/model/tools/
+ * mcp/permissions), so a capability carries the whole agent shape, not just a
+ * system prompt. The platform capability registry validates and stores these.
+ */
+export interface Capability {
+    /** Stable, deterministic id — the key a workflow's `agent.run.profile` names. */
+    id: string;
+    /** The canonical agent profile (prompt/model/tools/mcp/permissions). */
+    definition: AgentProfile;
+    /**
+     * Recommended compute tier for a sandbox running this capability. A dispatcher
+     * uses it as the size DEFAULT when the caller does not pick one — so a
+     * capability that only ever does thin work defaults to a small box instead of
+     * a maxed one. The caller may always override it per dispatch. Omitted → the
+     * dispatcher's own default tier.
+     */
+    recommendedSize?: SandboxSizePreset;
+}
+export declare const capabilitySchema: z.ZodType<Capability>;

package/dist/profile-schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { SANDBOX_SIZE_PRESET_NAMES, } from "./sandbox-size.js";
 export const agentProfilePermissionValueSchema = z.enum([
     "allow",
     "deny",
@@ -126,3 +127,8 @@ export const agentProfileSchema = z.object({
 });
 const _agentProfileSchemaMatchesInterface = true;
 void _agentProfileSchemaMatchesInterface;
+export const capabilitySchema = z.object({
+    id: z.string().min(1),
+    definition: agentProfileSchema,
+    recommendedSize: z.enum(SANDBOX_SIZE_PRESET_NAMES).optional(),
+});

package/dist/profile-security.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Security validation for inline {@link AgentProfile} values.
+ *
+ * When a caller sends a full profile inline (rather than naming a curated,
+ * trusted capability), the profile is author-controlled and may declare surfaces
+ * that execute code OUTSIDE the agent's own reasoning — a stdio/local MCP server
+ * (an arbitrary command spawned at startup) or a hook (a shell command run
+ * automatically around the turn). A sandbox isolates the workload, but these
+ * surfaces run unattended on the owner's behalf, so a cloud dispatcher must gate
+ * them before materializing the profile.
+ *
+ * This validates the CANONICAL agent-interface shape (`mcp` keyed by
+ * `AgentProfileMcpServer`, `hooks` keyed by `AgentProfileHookCommand[]`) — the
+ * provider-neutral contract every backend translates from. The opencode-native
+ * `validateProfileSecurity` (in `sdk-provider-opencode`) operates on opencode's
+ * own profile shape and is a different layer; this is the one to use at the
+ * application boundary where profiles are still provider-neutral.
+ */
+import type { AgentProfile, AgentProfileValidationResult } from "./agent-profile.js";
+/** Policy for {@link validateAgentProfileSecurity}. */
+export interface AgentProfileSecurityPolicy {
+    /**
+     * Allow stdio/local MCP servers (a spawned local process). Off in cloud: an
+     * inline profile must not start arbitrary commands at MCP init.
+     */
+    allowLocalMcp: boolean;
+    /**
+     * Allow lifecycle hooks (shell commands run automatically around the turn).
+     * Off in cloud: hooks are author-controlled shell outside the agent's loop.
+     */
+    allowHooks: boolean;
+    /**
+     * Glob allowlist for REMOTE MCP hosts (http/sse `url` hostnames). A set list
+     * rejects any host that matches no pattern; an empty list (`[]`) blocks ALL
+     * remote MCP.
+     *
+     * SECURITY: `undefined` leaves remote MCP hosts UNRESTRICTED — it does NOT
+     * protect against SSRF (an inline profile could point an MCP server at, e.g.,
+     * `http://169.254.169.254/` cloud metadata or an internal address). When this
+     * is `undefined`, the caller MUST enforce SSRF/egress controls at the network
+     * layer, or set a restrictive allowlist (or `[]`) to fail closed.
+     */
+    allowedMcpHosts?: string[];
+    /**
+     * Allow `connections` (hub-managed integration grants). `undefined` leaves them
+     * allowed — a connection is a legitimate inline-profile feature where the host
+     * wires it. A host that does NOT support inline connection grants (e.g. a
+     * surface that grants hub access through a separate, audited path) sets this
+     * `false` so an inline profile cannot smuggle hub access through the profile.
+     */
+    allowConnections?: boolean;
+}
+/**
+ * Default cloud policy: block the two unattended-code surfaces (local MCP,
+ * hooks); leave remote MCP and everything else to the profile. Deliberately
+ * narrow — it gates code execution paths, not the agent's normal tools/edits,
+ * which the sandbox already isolates.
+ *
+ * NOTE: this default leaves `allowedMcpHosts` undefined, so REMOTE MCP hosts are
+ * unrestricted — it is NOT an SSRF guard (see `allowedMcpHosts`). A surface that
+ * must fail closed against arbitrary MCP egress should set `allowedMcpHosts`
+ * (e.g. `[]` to block all remote MCP), as the workflow inline-profile policy does.
+ */
+export declare const DEFAULT_CLOUD_AGENT_PROFILE_SECURITY_POLICY: AgentProfileSecurityPolicy;
+/**
+ * Validate an inline profile against a security policy. Returns `ok: false` with
+ * `error`-level issues when the profile declares a blocked surface; warnings do
+ * not fail. Pure and synchronous — safe to run at author (compile) time and
+ * again at dispatch as defense in depth.
+ */
+export declare function validateAgentProfileSecurity(profile: AgentProfile, policy?: AgentProfileSecurityPolicy): AgentProfileValidationResult;

package/dist/profile-security.js

@@ -0,0 +1,179 @@
+/**
+ * Security validation for inline {@link AgentProfile} values.
+ *
+ * When a caller sends a full profile inline (rather than naming a curated,
+ * trusted capability), the profile is author-controlled and may declare surfaces
+ * that execute code OUTSIDE the agent's own reasoning — a stdio/local MCP server
+ * (an arbitrary command spawned at startup) or a hook (a shell command run
+ * automatically around the turn). A sandbox isolates the workload, but these
+ * surfaces run unattended on the owner's behalf, so a cloud dispatcher must gate
+ * them before materializing the profile.
+ *
+ * This validates the CANONICAL agent-interface shape (`mcp` keyed by
+ * `AgentProfileMcpServer`, `hooks` keyed by `AgentProfileHookCommand[]`) — the
+ * provider-neutral contract every backend translates from. The opencode-native
+ * `validateProfileSecurity` (in `sdk-provider-opencode`) operates on opencode's
+ * own profile shape and is a different layer; this is the one to use at the
+ * application boundary where profiles are still provider-neutral.
+ */
+/**
+ * Default cloud policy: block the two unattended-code surfaces (local MCP,
+ * hooks); leave remote MCP and everything else to the profile. Deliberately
+ * narrow — it gates code execution paths, not the agent's normal tools/edits,
+ * which the sandbox already isolates.
+ *
+ * NOTE: this default leaves `allowedMcpHosts` undefined, so REMOTE MCP hosts are
+ * unrestricted — it is NOT an SSRF guard (see `allowedMcpHosts`). A surface that
+ * must fail closed against arbitrary MCP egress should set `allowedMcpHosts`
+ * (e.g. `[]` to block all remote MCP), as the workflow inline-profile policy does.
+ */
+export const DEFAULT_CLOUD_AGENT_PROFILE_SECURITY_POLICY = {
+    allowLocalMcp: false,
+    allowHooks: false,
+};
+/**
+ * Match one DNS label against one pattern label, where `*` matches any run of
+ * characters WITHIN the label (never a `.`). Split-on-`*` with linear
+ * prefix/suffix/in-order scanning — deliberately NOT a constructed `RegExp`, so
+ * on this security boundary it stays provably linear with no catastrophic-
+ * backtracking surface whatever pattern an allowlist carries.
+ */
+function matchLabel(label, pattern) {
+    const segments = pattern.split("*");
+    if (segments.length === 1)
+        return label === segments[0]; // no wildcard
+    const first = segments[0];
+    const last = segments[segments.length - 1];
+    if (!label.startsWith(first) || !label.endsWith(last))
+        return false;
+    // Prefix and suffix may not overlap (e.g. `aa*aa` must not match `aaa`).
+    if (first.length + last.length > label.length)
+        return false;
+    let cursor = first.length;
+    const suffixStart = label.length - last.length;
+    for (let i = 1; i < segments.length - 1; i += 1) {
+        const seg = segments[i];
+        if (seg.length === 0)
+            continue;
+        const found = label.indexOf(seg, cursor);
+        if (found === -1 || found + seg.length > suffixStart)
+            return false;
+        cursor = found + seg.length;
+    }
+    return true;
+}
+/**
+ * Case-insensitive host glob (`*` only) for allowlists, matched at DNS LABEL
+ * granularity: the host and pattern are split on `.` and matched label-by-label,
+ * and a `*` matches within a single label only — it never crosses a `.`. So
+ * `*.example.com` matches `api.example.com` but NOT `evil-example.com` (no dot
+ * boundary), `a.b.example.com` (extra label), or the bare apex `example.com`
+ * (missing label). This prevents a wildcard from reaching an unintended sibling
+ * or deeper domain on the security boundary.
+ *
+ * An IPv6 host (the hostname contains `:`) is matched EXACTLY — never split or
+ * globbed — since `.`-label semantics don't apply to it (and an IPv4-mapped form
+ * like `::ffff:1.2.3.4` contains dots that would otherwise glob unpredictably).
+ */
+function matchHostGlob(host, pattern) {
+    const h = host.toLowerCase();
+    const p = pattern.toLowerCase();
+    if (h.includes(":") || p.includes(":"))
+        return h === p;
+    const hostLabels = h.split(".");
+    const patternLabels = p.split(".");
+    if (hostLabels.length !== patternLabels.length)
+        return false;
+    return patternLabels.every((label, i) => matchLabel(hostLabels[i], label));
+}
+/**
+ * A local/stdio MCP server spawns a process; a remote one connects over the
+ * network. ANY `command` makes it local — a spawnable process command is the
+ * thing being gated, and it stays dangerous whatever `transport` is declared
+ * alongside it (pairing `command` with `transport: "sse"`/`"http"` must not slip
+ * it past as "remote"). `transport: "stdio"` is local even with no command.
+ */
+function isLocalMcpServer(server) {
+    return server.command !== undefined || server.transport === "stdio";
+}
+/**
+ * Validate an inline profile against a security policy. Returns `ok: false` with
+ * `error`-level issues when the profile declares a blocked surface; warnings do
+ * not fail. Pure and synchronous — safe to run at author (compile) time and
+ * again at dispatch as defense in depth.
+ */
+export function validateAgentProfileSecurity(profile, policy = DEFAULT_CLOUD_AGENT_PROFILE_SECURITY_POLICY) {
+    const issues = [];
+    for (const [name, server] of Object.entries(profile.mcp ?? {})) {
+        if (isLocalMcpServer(server)) {
+            if (!policy.allowLocalMcp) {
+                issues.push({
+                    level: "error",
+                    code: "BLOCKED_LOCAL_MCP",
+                    message: `local/stdio MCP server '${name}' is not allowed (it spawns an arbitrary process)`,
+                    path: `mcp.${name}`,
+                });
+            }
+            continue;
+        }
+        if (policy.allowedMcpHosts) {
+            // An allowlist is active, so a non-local server MUST present a matchable
+            // host — a missing/empty `url` cannot be allowlist-checked, so it fails
+            // closed rather than slipping through unvalidated.
+            if (!server.url) {
+                issues.push({
+                    level: "error",
+                    code: "INVALID_MCP_URL",
+                    message: `remote MCP server '${name}' has no url to check against the allowlist`,
+                    path: `mcp.${name}`,
+                });
+                continue;
+            }
+            let host;
+            try {
+                host = new URL(server.url).hostname;
+            }
+            catch {
+                issues.push({
+                    level: "error",
+                    code: "INVALID_MCP_URL",
+                    message: `MCP server '${name}' has an invalid url: ${server.url}`,
+                    path: `mcp.${name}`,
+                });
+                continue;
+            }
+            if (!policy.allowedMcpHosts.some((p) => matchHostGlob(host, p))) {
+                issues.push({
+                    level: "error",
+                    code: "BLOCKED_REMOTE_MCP_HOST",
+                    message: `remote MCP host '${host}' is not in the allowlist`,
+                    path: `mcp.${name}`,
+                });
+            }
+        }
+    }
+    if (!policy.allowHooks &&
+        profile.hooks &&
+        Object.keys(profile.hooks).length > 0) {
+        issues.push({
+            level: "error",
+            code: "BLOCKED_HOOKS",
+            message: "hooks are not allowed (they run author-controlled shell commands automatically)",
+            path: "hooks",
+        });
+    }
+    if (policy.allowConnections === false &&
+        profile.connections &&
+        profile.connections.length > 0) {
+        issues.push({
+            level: "error",
+            code: "BLOCKED_CONNECTIONS",
+            message: "hub connections are not allowed in an inline profile here — grant hub access through this surface's supported connection path instead",
+            path: "connections",
+        });
+    }
+    return {
+        ok: !issues.some((i) => i.level === "error"),
+        issues,
+    };
+}

package/dist/sandbox-size.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Portable sandbox size vocabulary.
+ *
+ * A size preset is a provider-neutral NAME for a compute tier (cpu / memory /
+ * disk). This module owns only the vocabulary — the names and their smallest→
+ * largest ordering — so the lowest shared layer can reference a size without
+ * depending on the sandbox SDK (`Capability.recommendedSize` lives here, and
+ * agent-interface must not depend on `@tangle-network/sandbox`).
+ *
+ * The concrete cpu/memory/disk numbers for each preset are the sandbox SDK's
+ * single source of truth (`@tangle-network/sandbox` → `SANDBOX_SIZE_PRESETS`),
+ * which imports these names. Mirrors how this package owns the `ReasoningEffort`
+ * vocabulary while backends own its native mapping.
+ */
+/** Compute tiers, ordered smallest → largest. */
+export declare const SANDBOX_SIZE_PRESET_NAMES: readonly ["nano", "small", "medium", "large"];
+/**
+ * A named compute tier for a sandbox. `nano` suits thin glue work (a single API
+ * call, a notify); `large` suits heavy builds over big repositories. Sizing is a
+ * per-task decision — a thin workflow step should not provision a maxed box.
+ */
+export type SandboxSizePreset = (typeof SANDBOX_SIZE_PRESET_NAMES)[number];

package/dist/sandbox-size.js

@@ -0,0 +1,21 @@
+/**
+ * Portable sandbox size vocabulary.
+ *
+ * A size preset is a provider-neutral NAME for a compute tier (cpu / memory /
+ * disk). This module owns only the vocabulary — the names and their smallest→
+ * largest ordering — so the lowest shared layer can reference a size without
+ * depending on the sandbox SDK (`Capability.recommendedSize` lives here, and
+ * agent-interface must not depend on `@tangle-network/sandbox`).
+ *
+ * The concrete cpu/memory/disk numbers for each preset are the sandbox SDK's
+ * single source of truth (`@tangle-network/sandbox` → `SANDBOX_SIZE_PRESETS`),
+ * which imports these names. Mirrors how this package owns the `ReasoningEffort`
+ * vocabulary while backends own its native mapping.
+ */
+/** Compute tiers, ordered smallest → largest. */
+export const SANDBOX_SIZE_PRESET_NAMES = [
+    "nano",
+    "small",
+    "medium",
+    "large",
+];

package/package.json

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