@ouispec/agent-worker 0.1.0

package/dist/tools/input-validation.js

@@ -0,0 +1,75 @@
+/**
+ * Validate a tool call's input against the tool's declared input schema before it runs.
+ *
+ * The orchestrator hands tools to the model as raw JSON Schema (`jsonSchema(rawSchema)`),
+ * which carries no validator, and a tool call's arguments are whatever the model
+ * produced. Without this check a host's tool receives undeclared and mistyped fields:
+ * a generated entity update tool passed every key the model supplied straight to a
+ * database write.
+ *
+ * Validation is by the schema as declared. A tool that must refuse undeclared
+ * properties says so with `additionalProperties: false`, as the schema loader and the
+ * entity tool generator now do.
+ */
+import { Ajv } from 'ajv';
+import formatsPlugin from 'ajv-formats';
+// ajv-formats is CommonJS; under ESM interop its function is on `default`.
+const addFormats = formatsPlugin.default ??
+    formatsPlugin;
+/**
+ * Top-level keys removed before compiling:
+ * - `sideEffects`: the SDK's own flag, stored on the input schema; not JSON Schema.
+ * - `$schema`: hosts emit different drafts (e.g. 2020-12 from zod); the keywords tools
+ *   use are the same across them, and an unknown draft must not stop a tool working.
+ * - `$id`: two tools declaring the same id would collide in the compiler.
+ */
+const NON_VALIDATION_KEYS = ['sideEffects', '$schema', '$id'];
+const ajv = new Ajv({ allErrors: true, strict: false, useDefaults: false, coerceTypes: false });
+addFormats(ajv);
+function describeError(error) {
+    const at = error.instancePath || '(input)';
+    const params = error.params;
+    if (error.keyword === 'additionalProperties') {
+        return `${at} has a property this tool does not accept: "${String(params.additionalProperty)}"`;
+    }
+    if (error.keyword === 'required') {
+        return `${at} is missing required property "${String(params.missingProperty)}"`;
+    }
+    return `${at} ${error.message ?? 'is invalid'}`;
+}
+/**
+ * Compile a validator for a tool's input schema.
+ *
+ * A schema that cannot be compiled yields a validator that rejects every call: a tool
+ * whose input cannot be checked does not run.
+ */
+export function createToolInputValidator(inputSchema) {
+    const schema = { ...(inputSchema ?? { type: 'object', properties: {} }) };
+    for (const key of NON_VALIDATION_KEYS)
+        delete schema[key];
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return () => ({ ok: false, errors: [`this tool's input schema is invalid (${reason})`] });
+    }
+    const required = new Set(Array.isArray(schema.required) ? schema.required.map(String) : []);
+    return (input) => {
+        if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+            return { ok: false, errors: ['(input) must be an object'] };
+        }
+        // Models often send null for an optional argument they mean to leave out.
+        const value = {};
+        for (const [key, entry] of Object.entries(input)) {
+            if (entry === null && !required.has(key))
+                continue;
+            value[key] = entry;
+        }
+        if (validate(value))
+            return { ok: true, value };
+        return { ok: false, errors: (validate.errors ?? []).map(describeError) };
+    };
+}
+//# sourceMappingURL=input-validation.js.map

package/dist/tools/input-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-validation.js","sourceRoot":"","sources":["../../src/tools/input-validation.ts"],"names":[],"mappings":"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"}

package/dist/tools/load-all-tools.d.ts

@@ -0,0 +1,12 @@
+import type { RegisteredTool } from './types.js';
+import type { LoadToolsOptions } from './schema-loader.js';
+export interface LoadAllToolsOptions extends LoadToolsOptions {
+    /** Path to the schema directory (e.g. ./schemas/my-app/) */
+    schemasDir: string;
+}
+/**
+ * Generate the complete tool registry from schema + built-ins.
+ * This is the only tool-loading function a host worker should call.
+ */
+export declare function loadAllTools(options: LoadAllToolsOptions): Promise<RegisteredTool[]>;
+//# sourceMappingURL=load-all-tools.d.ts.map

package/dist/tools/load-all-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/load-all-tools.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAuB1F"}

package/dist/tools/load-all-tools.js

@@ -0,0 +1,42 @@
+/**
+ * loadAllTools — the single entry point for generating the complete tool
+ * registry from schema. Combines:
+ *   1. Intent tools (from intents/*.yaml) → apiSurface.executeIntent
+ *   2. Entity CRUD tools (from entities/*.yaml) → apiSurface.queryEntities/mutateEntity
+ *   3. Built-in interaction tools (SDK-owned, generic)
+ *
+ * This replaces hand-authored tool definitions entirely. The host provides
+ * schemas (generated by introspection) + an apiSurface binding; the SDK
+ * generates every tool.
+ *
+ * @see docs/reference/integration-contract.md §4
+ */
+import { loadToolsFromSchema } from './schema-loader.js';
+import { loadEntityToolsFromSchema } from './entity-tools.js';
+import { loadBuiltinTools } from './builtin-tools.js';
+/**
+ * Generate the complete tool registry from schema + built-ins.
+ * This is the only tool-loading function a host worker should call.
+ */
+export async function loadAllTools(options) {
+    const [intentTools, entityTools] = await Promise.all([
+        loadToolsFromSchema(options.schemasDir, {
+            ...(options.events ? { events: options.events } : {}),
+            ...(options.waiter ? { waiter: options.waiter } : {}),
+        }),
+        loadEntityToolsFromSchema(options.schemasDir),
+    ]);
+    const builtinTools = loadBuiltinTools();
+    // Merge, deduping by name (entity CRUD may overlap with intent tools for
+    // entities that also have explicit intents like create-character)
+    const seen = new Set();
+    const all = [];
+    for (const tool of [...intentTools, ...entityTools, ...builtinTools]) {
+        if (!seen.has(tool.name)) {
+            seen.add(tool.name);
+            all.push(tool);
+        }
+    }
+    return all;
+}
+//# sourceMappingURL=load-all-tools.js.map

package/dist/tools/load-all-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-all-tools.js","sourceRoot":"","sources":["../../src/tools/load-all-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAStD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAA4B;IAC7D,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACnD,mBAAmB,CAAC,OAAO,CAAC,UAAU,EAAE;YACtC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD,CAAC;QACF,yBAAyB,CAAC,OAAO,CAAC,UAAU,CAAC;KAC9C,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,gBAAgB,EAAE,CAAC;IAExC,yEAAyE;IACzE,kEAAkE;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,WAAW,EAAE,GAAG,WAAW,EAAE,GAAG,YAAY,CAAC,EAAE,CAAC;QACrE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/tools/schema-loader.d.ts

@@ -0,0 +1,24 @@
+import type { RegisteredTool } from './types.js';
+import type { EventCatalog, EventWaiter } from '@ouispec/agent-events';
+export interface LoadToolsOptions {
+    /**
+     * The product's event declarations. Required when any intent waits
+     * (`execution.subscribe`): each names declared events, or the tools fail to
+     * load, naming the intent and the event.
+     */
+    events?: EventCatalog;
+    /**
+     * How an async intent waits for its job to settle
+     * (`createHttpEventWaiter`, or the host's own). Without it an async intent
+     * returns its dispatch at once, with the job id.
+     */
+    waiter?: EventWaiter;
+}
+/**
+ * Load intent schemas from a directory and compile them into RegisteredTool[].
+ *
+ * @param schemasDir Path to the schema directory (e.g. './schemas/my-app/')
+ * @param options Optional subscription adapter for async intent resolution
+ */
+export declare function loadToolsFromSchema(schemasDir: string, options?: LoadToolsOptions): Promise<RegisteredTool[]>;
+//# sourceMappingURL=schema-loader.d.ts.map

package/dist/tools/schema-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-loader.d.ts","sourceRoot":"","sources":["../../src/tools/schema-loader.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGvE,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAWD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,cAAc,EAAE,CAAC,CAK3B"}

package/dist/tools/schema-loader.js

@@ -0,0 +1,267 @@
+/**
+ * loadToolsFromSchema — generates a RegisteredTool[] from declarative intent
+ * schemas (intents/*.yaml). This is the schema-driven replacement for
+ * hand-authored tool definitions.
+ *
+ * Each generated tool's `execute` calls the host's AgentApiSurface binding
+ * (`ctx.apiSurface.executeIntent(intentId, params)`) — the host never writes
+ * a tool body. An async intent's `subscribe:` block names the declared events
+ * that settle its job (W9): they are checked against the product's event
+ * declarations when the tools load, and with a waiter the tool waits for the
+ * job to complete or fail.
+ *
+ * @see docs/reference/integration-contract.md §1b, §4
+ */
+import { loadSchemas } from '@ouispec/agent-core';
+import { asyncToolResult, awaitAsyncTool, bindAsyncTool, parseWaitTimeout } from './async-binding.js';
+/**
+ * Load intent schemas from a directory and compile them into RegisteredTool[].
+ *
+ * @param schemasDir Path to the schema directory (e.g. './schemas/my-app/')
+ * @param options Optional subscription adapter for async intent resolution
+ */
+export async function loadToolsFromSchema(schemasDir, options) {
+    const documents = await loadSchemas(schemasDir);
+    const intents = extractIntents(documents);
+    return intents.map((intent) => compileIntentToTool(intent, bindIntent(intent, options ?? {}), options?.waiter));
+}
+/**
+ * Bind an intent's `subscribe` block to the declarations, or throw naming the
+ * intent and what is wrong. Null for an intent that does not wait.
+ */
+function bindIntent(intent, options) {
+    const sub = intent.execution?.subscribe;
+    if (!sub)
+        return null;
+    const usedBy = `intent '${intent.id}'`;
+    if (!options.events) {
+        throw new Error(`[agent-sdk] ${usedBy} waits on '${sub.event}', but no event declarations were given (LoadToolsOptions.events)`);
+    }
+    const filter = Object.entries(sub.filter ?? {});
+    if (filter.length !== 1) {
+        throw new Error(`[agent-sdk] ${usedBy}: subscribe.filter must name exactly one field, the job id of '${sub.event}' (it names ${filter.length})`);
+    }
+    const [[correlation, idFrom]] = filter;
+    const bound = bindAsyncTool(options.events, {
+        usedBy,
+        completion: sub.event,
+        ...(sub.failure !== undefined ? { failure: sub.failure } : {}),
+        correlation,
+        timeoutMs: parseWaitTimeout(usedBy, 'subscribe.timeout', sub.timeout),
+        ...(sub.resultMapping ? { resultMapping: sub.resultMapping } : {}),
+        mappingLabel: 'subscribe.resultMapping',
+    });
+    return { bound, idFrom, events: options.events, waiter: options.waiter };
+}
+/**
+ * Flatten all intent definitions from loaded schema documents.
+ * Intents appear either as top-level `doc.intent` or nested in
+ * `doc.domain.intents[]` (after $ref resolution).
+ */
+function extractIntents(documents) {
+    const intents = [];
+    for (const doc of documents) {
+        if (doc.intent) {
+            intents.push(doc.intent);
+        }
+        if (doc.domain?.intents) {
+            for (const i of doc.domain.intents) {
+                if (typeof i === 'object' && i !== null && 'id' in i) {
+                    intents.push(i);
+                }
+            }
+        }
+    }
+    // Deduplicate by id (domain $ref + standalone file may overlap)
+    const seen = new Set();
+    return intents.filter((i) => {
+        if (seen.has(i.id))
+            return false;
+        seen.add(i.id);
+        return true;
+    });
+}
+/**
+ * Compile a single intent schema into a RegisteredTool.
+ */
+function compileIntentToTool(intent, asyncIntent, waiter) {
+    const inputSchema = convertParameters(intent.parameters);
+    // Thread the sideEffects flag into the inputSchema so the orchestrator's
+    // quota check (`inputSchema.sideEffects !== false`) reads a real value
+    // instead of always getting `undefined` (which fail-closed to side-effecting).
+    if (intent.sideEffects === false) {
+        inputSchema.sideEffects = false;
+    }
+    return {
+        name: intent.id,
+        description: buildDescription(intent, !!(asyncIntent && waiter)),
+        inputSchema,
+        async execute(input, ctx) {
+            return executeIntent(intent, input, ctx, asyncIntent);
+        },
+    };
+}
+/**
+ * Build the tool description from the intent, enriching with async/duration
+ * hints so the LLM knows what to expect.
+ */
+function buildDescription(intent, waits) {
+    let desc = intent.description;
+    if (intent.outcome?.async) {
+        desc += `\n\nAsync: returns a jobId. Estimated duration: ${intent.outcome.estimatedDuration ?? 'unknown'}.`;
+        // Promise the event only when the tool will actually wait for it.
+        if (waits && intent.execution?.subscribe) {
+            desc += ` The result arrives via the ${intent.execution.subscribe.event} realtime event.`;
+        }
+    }
+    if (intent.outcome?.produces) {
+        desc += `\nProduces: ${intent.outcome.produces}.`;
+    }
+    return desc;
+}
+/**
+ * Convert RawParameterSchema (YAML) into a JSON Schema object for the LLM.
+ * Entity-typed parameters become string references (the LLM passes an entity ID).
+ */
+function convertParameters(parameters) {
+    const properties = {};
+    const required = [];
+    for (const [name, param] of Object.entries(parameters)) {
+        properties[name] = convertProperty(param);
+        if (param.required) {
+            required.push(name);
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        // An intent accepts exactly the parameters it declares. The orchestrator
+        // validates calls against this, so an undeclared argument never reaches the host.
+        additionalProperties: false,
+    };
+}
+function convertProperty(param) {
+    const schema = {};
+    // Entity-typed params are string IDs at the LLM layer
+    if (param.type === 'entity') {
+        schema.type = 'string';
+        if (param.entity) {
+            schema.description = param.description
+                ? `${param.description} (entity: ${param.entity} — pass the ID)`
+                : `Entity reference (${param.entity}) — pass the ID`;
+        }
+    }
+    else if (param.type === 'enum') {
+        schema.type = 'string';
+        if (param.values)
+            schema.enum = param.values;
+    }
+    else if (param.type === 'array') {
+        schema.type = 'array';
+        if (param.items)
+            schema.items = convertProperty(param.items);
+    }
+    else {
+        schema.type = param.type;
+    }
+    if (param.description && param.type !== 'entity') {
+        schema.description = param.description;
+    }
+    if (param.maxLength !== undefined)
+        schema.maxLength = param.maxLength;
+    if (param.minLength !== undefined)
+        schema.minLength = param.minLength;
+    if (param.default !== undefined)
+        schema.default = param.default;
+    return schema;
+}
+/**
+ * Execute an intent via the host's AgentApiSurface binding.
+ *
+ * This is the heart of the schema-driven model: the tool body is generated,
+ * not hand-authored. It calls `ctx.apiSurface.executeIntent(intentId, params)`
+ * — the host's binding decides whether that hits a REST route, a gateway
+ * inference endpoint, or anything else.
+ */
+async function executeIntent(intent, input, ctx, asyncIntent) {
+    const apiSurface = ctx.apiSurface;
+    if (!apiSurface) {
+        return {
+            success: false,
+            error: `Intent '${intent.id}' requires an AgentApiSurface binding in the tool execution context. Provide apiSurface in the worker config.`,
+        };
+    }
+    let result;
+    try {
+        result = await apiSurface.executeIntent(intent.id, input);
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: `Intent '${intent.id}' threw: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!result.success) {
+        return {
+            success: false,
+            error: result.error?.message ?? `Intent '${intent.id}' failed`,
+            data: result,
+        };
+    }
+    const exec = intent.execution;
+    const mapped = applyResultMapping(exec, result);
+    if (!result.async?.jobId || !asyncIntent?.waiter) {
+        // Sync intent, or async without a waiter: the dispatch, with clean field names.
+        return { success: true, data: mapped };
+    }
+    // Wait for the job to settle: its declared completion or failure.
+    const dispatchData = result.data ?? {};
+    const id = resolveTemplateString(String(asyncIntent.idFrom), { response: dispatchData });
+    const settled = await awaitAsyncTool(asyncIntent.events, asyncIntent.waiter, asyncIntent.bound, id, ctx.abortSignal);
+    return asyncToolResult(mapped, settled, { ...dispatchData, jobId: result.async.jobId });
+}
+/**
+ * Apply execution.resultMapping to the dispatch response so the LLM sees
+ * clean field names (jobId, imageId, status) rather than raw response shapes.
+ */
+function applyResultMapping(exec, result) {
+    const base = {
+        ...(result.data ?? {}),
+    };
+    if (result.async) {
+        base.jobId = result.async.jobId;
+        base.status = result.async.jobId ? (result.data?.status ?? 'dispatched') : base.status;
+    }
+    if (exec?.resultMapping) {
+        const mapped = {};
+        const rMapping = exec.resultMapping;
+        for (const [target, sourceExpr] of Object.entries(rMapping)) {
+            const sourcePath = sourceExpr.replace(/\$\{\s*response\./, '').replace(/\s*\}/, '').trim();
+            mapped[target] = getByPath(base, sourcePath);
+        }
+        // Merge mapped fields over base so both raw + mapped are available
+        return { ...base, ...mapped };
+    }
+    return base;
+}
+// ─── template helpers ──────────────────────────────────────────────────────
+function resolveTemplateString(str, ctx) {
+    const match = str.match(/^\$\{\s*(\w+)\.([^}]+?)\s*\}$/);
+    if (!match)
+        return str;
+    const [, ns, path] = match;
+    const root = ctx[ns];
+    if (root === undefined)
+        return undefined;
+    return getByPath(root, path);
+}
+function getByPath(obj, path) {
+    return path.split('.').reduce((acc, key) => {
+        if (acc && typeof acc === 'object') {
+            return acc[key];
+        }
+        return undefined;
+    }, obj);
+}
+//# sourceMappingURL=schema-loader.js.map

package/dist/tools/schema-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-loader.js","sourceRoot":"","sources":["../../src/tools/schema-loader.ts"],"names":[],"mappings":"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"}

package/dist/tools/types.d.ts

@@ -0,0 +1,85 @@
+import type { ActionRequestApproval, AgentApiSurface } from '@ouispec/agent-core';
+import type { EffectOrKind } from '@ouispec/bindings';
+import type { UISlot } from '../ui/ui-sequence.js';
+/**
+ * Tool registry — platforms register their tools here.
+ * The worker calls tools by name during the orchestration loop.
+ */
+/**
+ * What a tool declares it does (ADR-0226 §2.6): a host or API tool's full
+ * effect, or, for a UI action, the effect kind its OUI surface carries.
+ */
+export type ToolEffect = EffectOrKind;
+export interface RegisteredTool {
+    name: string;
+    /**
+     * `ui`: an action on the client's UI, run as the user in their own session
+     * (ADR-0209). Bounded by the turn's round cap rather than the backend
+     * side-effect quota. Default `backend`.
+     */
+    kind?: 'ui' | 'backend';
+    /**
+     * What calling the tool changes (ADR-0226 §2.6). A tool that declares none is
+     * treated as a write. Approvals key on this and `destructive` (ADR-0228).
+     */
+    effect?: ToolEffect;
+    /** The call removes or replaces something the person made (ADR-0228). */
+    destructive?: boolean;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (input: Record<string, unknown>, ctx: ToolExecutionContext) => Promise<ToolExecutionResult>;
+    /** Its name as a person reads it, for the approval card. Default: `name`. */
+    title?: string;
+    /** What running it does, for the approval card. Default: `description`. */
+    consequence?: string;
+    /**
+     * Whether its arguments are kept out of logs. Default true: an approval's
+     * arguments are logged only when its declaration says they are not sensitive.
+     */
+    argsSensitive?: boolean;
+}
+export interface ToolExecutionContext {
+    userId: string;
+    accountId: string;
+    turnId: string;
+    conversationId: string;
+    userToken?: string;
+    /**
+     * The host's AgentApiSurface binding. Schema-generated tools call
+     * `apiSurface.executeIntent(intentId, params)` instead of hand-rolled bodies.
+     * Optional only for tools that don't need host API access (e.g. pure UI actions).
+     */
+    apiSurface?: AgentApiSurface;
+    /** AbortSignal tied to the turn deadline — tools should observe this for cancellation. */
+    abortSignal?: AbortSignal;
+    /** The model's id for this call. UI tools use it as the OUI request id. */
+    toolCallId?: string;
+    /** The turn's realtime room, where the client that sent the turn listens. */
+    socketRoom?: string;
+    /**
+     * A UI tool's place in the turn's UI order, taken by the orchestrator when the
+     * model's call arrived (ui-sequence.ts). A UI tool runs its action in it.
+     */
+    uiSlot?: UISlot;
+    /**
+     * Set when the call is one the user approved (ADR-0228): a UI action's
+     * request carries it, and the browser runs the action only when it matches
+     * the grant from the user's own click.
+     */
+    approval?: ActionRequestApproval;
+    [key: string]: unknown;
+}
+export interface ToolExecutionResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+export interface ToolRegistry {
+    tools: RegisteredTool[];
+    execute(name: string, input: Record<string, unknown>, ctx: ToolExecutionContext): Promise<ToolExecutionResult>;
+}
+/**
+ * Creates a tool registry from a list of registered tools.
+ */
+export declare function createToolRegistry(tools: RegisteredTool[]): ToolRegistry;
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;GAGG;AAEH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC;AAEtC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrG,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,0FAA0F;IAC1F,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChH;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,YAAY,CAiBxE"}

package/dist/tools/types.js

@@ -0,0 +1,22 @@
+/**
+ * Creates a tool registry from a list of registered tools.
+ */
+export function createToolRegistry(tools) {
+    const toolMap = new Map(tools.map(t => [t.name, t]));
+    return {
+        tools,
+        async execute(name, input, ctx) {
+            const tool = toolMap.get(name);
+            if (!tool) {
+                return { success: false, error: `Unknown tool: ${name}` };
+            }
+            try {
+                return await tool.execute(input, ctx);
+            }
+            catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAuFA;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB;IACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,OAAO;QACL,KAAK;QACL,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,KAA8B,EAAE,GAAyB;YACnF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,IAAI,EAAE,EAAE,CAAC;YAC5D,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACrF,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/turn-policy.d.ts

@@ -0,0 +1,68 @@
+/**
+ * TurnPolicy — controls per-step tool selection and constraints.
+ *
+ * Integrators provide their own policy to encode product-specific orchestration
+ * behavior (e.g. forced tool sequences for onboarding, navigation-first flows).
+ * The SDK provides a safe, product-neutral default.
+ *
+ * The policy is consulted at two points:
+ *   1. classifyTurn — called once at turn start to classify the user's intent
+ *   2. prepareStep  — called before each LLM step to control tool selection
+ */
+export interface TurnPolicy {
+    /**
+     * Classify the current turn to determine orchestration behavior.
+     * Returns a string label that `prepareStep` uses to apply constraints.
+     * The SDK does not interpret the label — it's opaque to the orchestrator.
+     */
+    classifyTurn(content: string, history?: Array<{
+        role: string;
+        content: string;
+    }>): string;
+    /**
+     * Called before each step to control tool selection.
+     * Returns overrides for toolChoice and activeTools, or empty object for no constraint.
+     */
+    prepareStep(ctx: {
+        steps: Array<{
+            toolCalls?: Array<{
+                toolName: string;
+            }>;
+        }>;
+        turnClass: string;
+        allToolNames: string[];
+    }): Promise<{
+        toolChoice?: 'auto' | 'none' | 'required' | {
+            type: 'tool';
+            toolName: string;
+        };
+        activeTools?: string[];
+        /**
+         * An instruction for this step only, added after the system prompt. Say why
+         * the step is constrained when the model cannot tell: a model made to hand
+         * back at a step limit, without being told, invents a reason (on dev: "I
+         * navigated away before filling in the text", about text it had filled).
+         */
+        note?: string;
+    }>;
+    /**
+     * Optional: called after turn classification to perform side effects
+     * (e.g. emitting deterministic navigation events).
+     * The SDK calls this if defined, passing the emit adapter and turn context.
+     */
+    onTurnClassified?: (ctx: {
+        turnClass: string;
+        content: string;
+        emit: {
+            emit: (room: string, event: string, data: unknown) => Promise<void>;
+        };
+        socketRoom: string;
+    }) => Promise<void>;
+}
+/**
+ * Default turn policy — product-neutral, safe defaults.
+ * No forced tool sequences, no product-specific constraints.
+ * The orchestrator's existing step count and token limits provide the safety net.
+ */
+export declare const defaultTurnPolicy: TurnPolicy;
+//# sourceMappingURL=turn-policy.d.ts.map

package/dist/turn-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-policy.d.ts","sourceRoot":"","sources":["../src/turn-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GACjD,MAAM,CAAC;IAEV;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE;QACf,KAAK,EAAE,KAAK,CAAC;YAAE,SAAS,CAAC,EAAE,KAAK,CAAC;gBAAE,QAAQ,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC,CAAC;QAC1D,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB,GAAG,OAAO,CAAC;QACV,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IAEH;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE;YAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;QAC9E,UAAU,EAAE,MAAM,CAAC;KACpB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAG/B,CAAC"}