@ouispec/agent-worker 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/prompt/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,mEAAmE;IACnE,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAElC,mEAAmE;IACnE,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAE5B,wEAAwE;IACxE,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAExC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC;;;OAGG;IACH,SAAS,CAAC,EAAE,qBAAqB,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,0DAA0D;IAC1D,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,iDAAiD;IACjD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,0CAA0C;IAC1C,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,SAAS,GAAG,gBAAgB,GAAG,QAAQ,CAAC;CAC9D;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1C"}

package/dist/prompt/types.js

@@ -0,0 +1,10 @@
+/**
+ * AgentPersonaConfig — the platform-specific configuration that integrators
+ * provide to define their agent's identity, knowledge, and behavior.
+ *
+ * The SDK's buildAgentSystemPrompt() combines this with generic behavioral
+ * rules (anti-hallucination, communication style, tool strategy, UI control)
+ * so platforms never re-invent the wheel.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/prompt/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/prompt/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/realtime/long-poll.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Asking the realtime server for something it holds until it arrives: a UI
+ * action's answer, a job's settlement. Each request waits server-side for at
+ * most `maxPollMs`; the caller asks again until its own deadline.
+ *
+ * 200 is the answer; 204 is "not yet", so ask again; a dropped request or a
+ * 5xx is retried after a short pause, since the server keeps what it holds; a
+ * 4xx is configuration, not timing, and throws rather than wait it out.
+ */
+export interface LongPollOptions {
+    /** The URL for one request that waits server-side up to `waitMs`. */
+    url: (waitMs: number) => string;
+    apiKey: string;
+    timeoutMs: number;
+    maxPollMs: number;
+    signal?: AbortSignal;
+    /** What is being collected, for the error a 4xx throws. */
+    describe: string;
+}
+export declare function longPoll<T>(options: LongPollOptions): Promise<T | null>;
+//# sourceMappingURL=long-poll.d.ts.map

package/dist/realtime/long-poll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"long-poll.d.ts","sourceRoot":"","sources":["../../src/realtime/long-poll.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CA6B7E"}

package/dist/realtime/long-poll.js

@@ -0,0 +1,36 @@
+export async function longPoll(options) {
+    const { apiKey, maxPollMs, signal } = options;
+    const deadline = Date.now() + options.timeoutMs;
+    while (Date.now() < deadline) {
+        if (signal?.aborted)
+            return null;
+        const waitMs = Math.max(0, Math.min(maxPollMs, deadline - Date.now()));
+        let res;
+        try {
+            res = await fetch(options.url(waitMs), {
+                headers: { 'X-Api-Key': apiKey },
+                signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(waitMs + 5_000)]) : AbortSignal.timeout(waitMs + 5_000),
+            });
+        }
+        catch {
+            if (signal?.aborted)
+                return null;
+            await sleep(Math.min(500, Math.max(0, deadline - Date.now())));
+            continue;
+        }
+        if (res.status === 200)
+            return (await res.json());
+        if (res.status === 204)
+            continue;
+        if (res.status >= 500) {
+            await sleep(Math.min(500, Math.max(0, deadline - Date.now())));
+            continue;
+        }
+        throw new Error(`[agent-sdk] Collecting ${options.describe} failed: HTTP ${res.status}`);
+    }
+    return null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=long-poll.js.map

package/dist/realtime/long-poll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"long-poll.js","sourceRoot":"","sources":["../../src/realtime/long-poll.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,OAAwB;IACxD,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAEhD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,MAAM,EAAE,OAAO;YAAE,OAAO,IAAI,CAAC;QACjC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAEvE,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE;gBACrC,OAAO,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE;gBAChC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC;aACtH,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,MAAM,EAAE,OAAO;gBAAE,OAAO,IAAI,CAAC;YACjC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;YAC/D,SAAS;QACX,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;QACvD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,SAAS;QACjC,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;YACtB,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;YAC/D,SAAS;QACX,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,CAAC,QAAQ,iBAAiB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/runtime/config.d.ts

@@ -0,0 +1,4 @@
+import type { AgentRuntimeConfig } from './types.js';
+/** Throws, naming every missing or malformed value, unless the configuration is complete. */
+export declare function assertAgentRuntimeConfig<TDb>(config: Partial<AgentRuntimeConfig<TDb>>): asserts config is AgentRuntimeConfig<TDb>;
+//# sourceMappingURL=config.d.ts.map

package/dist/runtime/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/runtime/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwBrD,6FAA6F;AAC7F,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAOjI"}

package/dist/runtime/config.js

@@ -0,0 +1,29 @@
+/**
+ * Every value the runtime cannot run without, and what it is for. A missing
+ * one fails start-up — when the adapter is created, before any turn — with
+ * this text. Nothing falls back to an environment variable or an empty
+ * string: a fallback is how a worker once ran with no realtime URL and
+ * streamed every turn to nobody (ADR-0227 §2.2).
+ */
+const REQUIRED = [
+    ['model', (c) => !!c.model, 'an `ai` library model'],
+    ['realtime.url', (c) => typeof c.realtime?.url === 'string' && /^https?:\/\//.test(c.realtime.url), 'the realtime server URL (http or https)'],
+    ['realtime.apiKey', (c) => typeof c.realtime?.apiKey === 'string' && c.realtime.apiKey.length > 0, "the realtime server's internal key"],
+    [
+        'persona or systemPrompt',
+        (c) => !!c.persona !== (typeof c.systemPrompt === 'function'),
+        'exactly one: the assistant’s identity comes only from the host',
+    ],
+    ['tools', (c) => Array.isArray(c.tools) || typeof c.tools === 'function', 'a tool list or a per-turn resolver ([] for UI actions only)'],
+    ['getDb', (c) => typeof c.getDb === 'function', 'returns the handle passed to the callbacks'],
+    ['getHistory', (c) => typeof c.getHistory === 'function', "loads the conversation's earlier messages"],
+    ['persistMessages', (c) => typeof c.persistMessages === 'function', "keeps the turn's new messages"],
+];
+/** Throws, naming every missing or malformed value, unless the configuration is complete. */
+export function assertAgentRuntimeConfig(config) {
+    const missing = REQUIRED.filter(([, ok]) => !ok((config ?? {}))).map(([name, , what]) => `${name} (${what})`);
+    if (missing.length > 0) {
+        throw new Error(`[agent-sdk] Missing required configuration: ${missing.join('; ')}`);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/runtime/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/runtime/config.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,QAAQ,GAA0F;IACtG,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,uBAAuB,CAAC;IACpD,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,GAAG,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,yCAAyC,CAAC;IAC9I,CAAC,iBAAiB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,oCAAoC,CAAC;IACxI;QACE,yBAAyB;QACzB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,YAAY,KAAK,UAAU,CAAC;QAC7D,gEAAgE;KACjE;IACD,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,UAAU,EAAE,6DAA6D,CAAC;IACxI,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,UAAU,EAAE,4CAA4C,CAAC;IAC7F,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,UAAU,KAAK,UAAU,EAAE,2CAA2C,CAAC;IACtG,CAAC,iBAAiB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,eAAe,KAAK,UAAU,EAAE,+BAA+B,CAAC;CACrG,CAAC;AAEF,6FAA6F;AAC7F,MAAM,UAAU,wBAAwB,CAAM,MAAwC;IACpF,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,CAAyC,CAAC,CAAC,CAAC,GAAG,CAC1G,CAAC,CAAC,IAAI,EAAE,AAAD,EAAG,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,GAAG,CACxC,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,+CAA+C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;AACH,CAAC"}

package/dist/runtime/turn-runner.d.ts

@@ -0,0 +1,32 @@
+import type { AgentRuntimeConfig, AgentTurnPayload } from './types.js';
+export interface CategorizedError {
+    code: string;
+    message: string;
+    recoverable: boolean;
+}
+export type TurnOutcome = {
+    status: 'completed';
+    turnId: string;
+    rounds: number;
+} | {
+    status: 'failed';
+    turnId: string;
+    error: CategorizedError;
+    cause: unknown;
+};
+export interface AgentTurnRunner {
+    /** Runs one turn to its end. Never throws for a turn's own failure: it reports it. */
+    run(payload: AgentTurnPayload): Promise<TurnOutcome>;
+    /** The model, as logs name it. */
+    readonly model: string;
+    /** The host's logger, or the default one. */
+    readonly logger: RuntimeLogger;
+}
+type RuntimeLogger = NonNullable<AgentRuntimeConfig['logger']>;
+/** Why a payload is not a turn, or null when it is one. */
+export declare function payloadRefusal(payload: unknown): string | null;
+export declare function createAgentTurnRunner<TDb>(config: AgentRuntimeConfig<TDb>): AgentTurnRunner;
+/** Sorts a failure into what the client is told, and whether trying again could help. */
+export declare function categorizeError(err: unknown): CategorizedError;
+export {};
+//# sourceMappingURL=turn-runner.d.ts.map

package/dist/runtime/turn-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/turn-runner.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGvE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAElF,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,GAAG,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACrD,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED,KAAK,aAAa,GAAG,WAAW,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC;AAa/D,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAiB9D;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,kBAAkB,CAAC,GAAG,CAAC,GAAG,eAAe,CA4J3F;AAMD,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAkB9D"}

package/dist/runtime/turn-runner.js

@@ -0,0 +1,216 @@
+/**
+ * The agent runtime's core: one turn, from payload to persisted messages.
+ *
+ * Both host adapters wrap it — the Lambda + SQS handler and the container
+ * server — so a turn runs the same way wherever it is hosted. The adapter only
+ * decides how a turn arrives and what a failure means to its transport.
+ */
+import { APICallError, RetryError } from 'ai';
+import { AGENT_SOCKET_EVENTS } from '@ouispec/agent-core';
+import { runAgentTurn } from '../orchestrator.js';
+import { createHttpEmitAdapter } from '../emit/http-adapter.js';
+import { createHttpUIActionChannel } from '../ui/channel.js';
+import { createHttpApprovalStoreClient } from '../approvals/client.js';
+import { withoutClientUI } from '../ui/snapshot.js';
+import { createToolRegistry } from '../tools/types.js';
+import { buildAgentSystemPrompt } from '../prompt/index.js';
+import { describeModel } from '../model.js';
+import { assertAgentRuntimeConfig } from './config.js';
+const DEFAULT_LOGGER = {
+    info: (msg, data) => console.log(JSON.stringify({ level: 'info', msg, ...data })),
+    warn: (msg, data) => console.warn(JSON.stringify({ level: 'warn', msg, ...data })),
+    error: (msg, data) => console.error(JSON.stringify({ level: 'error', msg, ...data })),
+    debug: (msg, data) => {
+        if (process.env.LOG_LEVEL === 'debug')
+            console.log(JSON.stringify({ level: 'debug', msg, ...data }));
+    },
+};
+const PAYLOAD_FIELDS = ['turnId', 'conversationId', 'userId', 'accountId', 'socketRoom', 'content'];
+/** Why a payload is not a turn, or null when it is one. */
+export function payloadRefusal(payload) {
+    if (!payload || typeof payload !== 'object')
+        return 'the turn payload must be an object';
+    const p = payload;
+    const missing = PAYLOAD_FIELDS.filter((f) => typeof p[f] !== 'string' || (f !== 'content' && !p[f]));
+    if (missing.length > 0)
+        return `the turn payload is missing ${missing.join(', ')}`;
+    if (p.context !== undefined && p.context !== null && typeof p.context !== 'object')
+        return 'context must be an object';
+    if (p.userToken !== undefined && typeof p.userToken !== 'string')
+        return 'userToken must be a string';
+    if (p.approval !== undefined) {
+        const a = p.approval;
+        if (!a || typeof a !== 'object' || typeof a.approvalId !== 'string' || !a.approvalId)
+            return 'approval needs an approvalId';
+        if (a.decision === 'approve') {
+            if (typeof a.token !== 'string' || !a.token)
+                return 'an approval to redeem needs its token';
+        }
+        else if (a.decision !== 'decline') {
+            return "approval.decision must be 'approve' or 'decline'";
+        }
+    }
+    return null;
+}
+export function createAgentTurnRunner(config) {
+    assertAgentRuntimeConfig(config);
+    const logger = config.logger ?? DEFAULT_LOGGER;
+    const model = describeModel(config.model);
+    const maxRounds = config.maxRounds ?? 12;
+    const maxTokens = config.maxTokens ?? 4096;
+    const temperature = config.temperature ?? 0.3;
+    const toolTimeoutMs = config.toolTimeoutMs ?? 30_000;
+    const turnDeadlineMs = config.turnDeadlineMs ?? 840_000;
+    const retries = config.retries ?? 3;
+    const emit = createHttpEmitAdapter({ url: config.realtime.url, apiKey: config.realtime.apiKey });
+    // UI actions reach the client through the same realtime server, and its
+    // answers come back through it (ADR-0209).
+    const uiChannel = config.uiActions?.channel ?? createHttpUIActionChannel({ url: config.realtime.url, apiKey: config.realtime.apiKey });
+    // Approvals are kept by the same realtime server (ADR-0228 §2.4).
+    const approvals = config.approvals?.store ?? createHttpApprovalStoreClient({ url: config.realtime.url, apiKey: config.realtime.apiKey });
+    const resolveTools = async (ctx) => createToolRegistry(typeof config.tools === 'function' ? await config.tools(ctx) : config.tools);
+    logger.info('[agent-sdk] Runtime ready', { model, maxRounds, maxTokens, turnDeadlineMs });
+    return {
+        model,
+        logger,
+        async run(payload) {
+            const { turnId, conversationId, userId, accountId, socketRoom, content, context, userToken, approval } = payload;
+            logger.info('[agent-sdk] Processing turn', { turnId, conversationId, userId });
+            let db;
+            try {
+                db = await config.getDb();
+            }
+            catch (error) {
+                // No handle, so nothing can be recorded; the client is still told.
+                return fail(payload, error);
+            }
+            if (config.recordTurnStart) {
+                try {
+                    await config.recordTurnStart({ turnId, conversationId, userId, accountId, model, db });
+                }
+                catch (err) {
+                    logger.warn('[agent-sdk] recordTurnStart failed', { error: messageOf(err) });
+                }
+            }
+            try {
+                const history = await config.getHistory(conversationId, db);
+                // What the client's UI sent for the worker is not the host's prompt
+                // text: its snapshot becomes the turn's UI tools, and its knowledge is
+                // rendered after the host's prompt (orchestrator).
+                const promptContext = { userId, accountId, context: withoutClientUI(context) };
+                const systemPrompt = config.systemPrompt
+                    ? config.systemPrompt(promptContext)
+                    : buildAgentSystemPrompt(config.persona, promptContext);
+                const turnInput = {
+                    turnId,
+                    conversationId,
+                    userId,
+                    accountId,
+                    socketRoom,
+                    content,
+                    context,
+                    history,
+                    userToken,
+                    ...(approval ? { approval } : {}),
+                };
+                const tools = await resolveTools({ userId, accountId, turnId });
+                const result = await runAgentTurn({
+                    tools,
+                    emit,
+                    apiSurface: config.apiSurfaceFactory ? config.apiSurfaceFactory({ userId, accountId, userToken }) : config.apiSurface,
+                    systemPrompt,
+                    model: config.model,
+                    promptCacheBreakpoint: config.promptCacheBreakpoint,
+                    maxToolRounds: maxRounds,
+                    maxTokens,
+                    temperature,
+                    toolTimeoutMs,
+                    turnDeadlineMs,
+                    retries,
+                    turnPolicy: config.turnPolicy,
+                    toolPolicy: config.toolPolicy,
+                    approvals,
+                    ui: {
+                        channel: uiChannel,
+                        resultTimeoutMs: config.uiActions?.resultTimeoutMs,
+                        maxObservationChars: config.uiActions?.maxObservationChars,
+                    },
+                }, turnInput);
+                logger.info('[agent-sdk] Turn completed', {
+                    turnId,
+                    rounds: result.rounds,
+                    maxRoundsReached: result.maxRoundsReached,
+                    usage: result.usage,
+                });
+                if (config.recordTurnComplete) {
+                    try {
+                        await config.recordTurnComplete({ turnId, conversationId, rounds: result.rounds, usage: result.usage, db });
+                    }
+                    catch (err) {
+                        logger.warn('[agent-sdk] recordTurnComplete failed', { error: messageOf(err) });
+                    }
+                }
+                try {
+                    await config.persistMessages({ turnId, conversationId, messages: result.newMessages, usage: result.usage, db });
+                }
+                catch (err) {
+                    logger.error('[agent-sdk] persistMessages failed', { turnId, error: messageOf(err) });
+                }
+                return { status: 'completed', turnId, rounds: result.rounds };
+            }
+            catch (error) {
+                return fail(payload, error, async (categorized) => {
+                    if (!config.recordTurnFailure)
+                        return;
+                    try {
+                        await config.recordTurnFailure({ turnId, conversationId, error: categorized, db });
+                    }
+                    catch (err) {
+                        logger.warn('[agent-sdk] recordTurnFailure failed', { error: messageOf(err) });
+                    }
+                });
+            }
+        },
+    };
+    /** Reports a failed turn to the client first, so the UI stops streaming, then to the host. */
+    async function fail(payload, error, record) {
+        const { turnId, socketRoom } = payload;
+        const categorized = categorizeError(error);
+        logger.error('[agent-sdk] Turn failed', { turnId, ...categorized });
+        try {
+            await emit.emit(socketRoom, AGENT_SOCKET_EVENTS.TURN_ERROR, {
+                turnId,
+                error: { code: categorized.code, message: categorized.message },
+                timestamp: Date.now(),
+            });
+        }
+        catch (emitErr) {
+            logger.warn('[agent-sdk] Failed to emit turn_error to client', { turnId, error: messageOf(emitErr) });
+        }
+        await record?.(categorized);
+        return { status: 'failed', turnId, error: categorized, cause: error };
+    }
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Sorts a failure into what the client is told, and whether trying again could help. */
+export function categorizeError(err) {
+    const cause = RetryError.isInstance(err) ? err.lastError : err;
+    const msg = messageOf(err);
+    const status = APICallError.isInstance(cause) ? cause.statusCode : undefined;
+    if (status === 429 || /throttl|rate limit|too many requests/i.test(msg)) {
+        return { code: 'RATE_LIMIT', message: 'The model provider is rate-limiting requests', recoverable: true };
+    }
+    if (status === 503 || status === 529 || /service ?unavailable|overloaded/i.test(msg)) {
+        return { code: 'SERVICE_UNAVAILABLE', message: 'The model provider is unavailable', recoverable: true };
+    }
+    if (/ModelTimeout|model timeout/i.test(msg)) {
+        return { code: 'MODEL_TIMEOUT', message: 'The model timed out', recoverable: true };
+    }
+    if (/timed out|deadline/i.test(msg)) {
+        return { code: 'TURN_TIMEOUT', message: msg, recoverable: false };
+    }
+    return { code: 'WORKER_ERROR', message: msg, recoverable: false };
+}
+//# sourceMappingURL=turn-runner.js.map

package/dist/runtime/turn-runner.js.map

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

package/dist/runtime/types.d.ts

@@ -0,0 +1,244 @@
+/**
+ * The agent runtime's configuration: what the host supplies, for either host
+ * adapter (Lambda + SQS, or a container). Every seam without a `?` is
+ * required, and a missing one fails at start-up, naming it (ADR-0227 §2.2).
+ *
+ * Integrators provide these callbacks so the SDK can interact with their
+ * platform without knowing anything about their database schema, API, or
+ * realtime infrastructure.
+ */
+import type { RegisteredTool } from '../tools/types.js';
+import type { AgentPersonaConfig } from '../prompt/index.js';
+import type { AgentApiSurface } from '@ouispec/agent-core';
+import type { TurnMessage, TurnHistoryMessage } from '../types.js';
+import type { TurnPolicy } from '../turn-policy.js';
+import type { ToolPolicy } from '../authz/tool-policy.js';
+import type { UIActionChannel } from '../ui/channel.js';
+import type { LanguageModel, ProviderOptions } from '../model.js';
+import type { ApprovalStoreClient } from '../approvals/client.js';
+import type { ApprovalContinuation } from '@ouispec/agent-core';
+/**
+ * Database handle — opaque to the SDK. The integrator's callbacks receive
+ * whatever they return from `getDb` so they can use it directly.
+ */
+export type IntegratorDb = unknown;
+/**
+ * One turn, as the host's API hands it to the worker: the SQS message body
+ * for the Lambda adapter, the request body for the container adapter.
+ */
+export interface AgentTurnPayload {
+    turnId: string;
+    conversationId: string;
+    userId: string;
+    accountId: string;
+    socketRoom: string;
+    content: string;
+    context?: Record<string, unknown> | null;
+    callbackUrl?: string;
+    userToken?: string;
+    /**
+     * On the turn that follows the user's decision on an approval card: the
+     * token to redeem, or that they declined (ADR-0228 §2.2.5).
+     */
+    approval?: ApprovalContinuation;
+}
+/**
+ * Configuration for the agent runtime, whichever adapter hosts it.
+ *
+ * The integrator provides the model, the realtime server, the persona or
+ * system prompt, tools, and a handful of callbacks. The SDK handles
+ * everything else: orchestration, streaming, tool execution, UI actions,
+ * error handling, and persistence.
+ */
+export interface AgentRuntimeConfig<TDb = IntegratorDb> {
+    /**
+     * The tools the agent can call. Each tool receives its input and a
+     * ToolExecutionContext (userId, accountId, userToken, etc.).
+     *
+     * UI tools are not listed here. They come from the client's surface snapshot
+     * on the turn (`context.oui`, ADR-0209), and the SDK builds them itself.
+     *
+     * Tools can be a static array, or a per-turn resolver function.
+     * The resolver receives the turn context and returns tools for that specific turn.
+     * Use this when tools vary per-user (e.g. OUI surface tools).
+     */
+    tools: RegisteredTool[] | ((ctx: {
+        userId: string;
+        accountId: string;
+        turnId: string;
+    }) => Promise<RegisteredTool[]> | RegisteredTool[]);
+    /**
+     * The host's AgentApiSurface binding. Required when tools are loaded from
+     * schema (loadToolsFromSchema) — generated tool execute bodies call
+     * `apiSurface.executeIntent(intentId, params)`. Optional for hand-authored
+     * tools that don't need host API access.
+     *
+     * Use `apiSurfaceFactory` instead if the surface needs per-turn context
+     * (userId, accountId) — which is the common case.
+     */
+    apiSurface?: AgentApiSurface;
+    /**
+     * Factory that creates a per-turn AgentApiSurface with the turn's
+     * userId/accountId. Preferred over the static `apiSurface` when the
+     * surface needs per-turn context.
+     */
+    apiSurfaceFactory?: (payload: {
+        userId: string;
+        accountId: string;
+        userToken?: string;
+    }) => AgentApiSurface;
+    /**
+     * The assistant's identity and voice, through the SDK's prompt framework.
+     * The shipped prompts carry no identity of their own: it comes only from
+     * here. Exactly one of `persona` and `systemPrompt` is required.
+     */
+    persona?: AgentPersonaConfig;
+    /**
+     * A system prompt builder, for full control instead of `persona`. Receives
+     * the same context the persona would. Exactly one of the two is required.
+     */
+    systemPrompt?: (context: {
+        userId: string;
+        accountId: string;
+        context?: Record<string, unknown> | null;
+    }) => string;
+    /** The model, from any `ai` library provider (ADR-0227 §2.2, D5). Required. */
+    model: LanguageModel;
+    /**
+     * Provider options that mark a prompt-cache breakpoint (see
+     * PROMPT_CACHE_BREAKPOINTS). Omit for a provider that caches on its own.
+     */
+    promptCacheBreakpoint?: ProviderOptions;
+    /** Max tool-use rounds per turn. Default: 12 */
+    maxRounds?: number;
+    /** Max tokens per model response. Default: 4096 */
+    maxTokens?: number;
+    /** Temperature. Default: 0.3 */
+    temperature?: number;
+    /** Per-tool execution timeout in ms. Default: 30000 */
+    toolTimeoutMs?: number;
+    /** Total turn deadline in ms. Default: 840000 (14 min). Keep it below the host's own limit. */
+    turnDeadlineMs?: number;
+    /** Retries of a transient model error. Default: 3 */
+    retries?: number;
+    /**
+     * Optional turn policy for product-specific step control.
+     * Controls turn classification and per-step tool selection constraints.
+     * If not provided, the default policy applies no constraints.
+     */
+    turnPolicy?: TurnPolicy;
+    /**
+     * Per-tool authorization policy. Evaluated before every tool execution.
+     * If omitted, the default policy allows all tools.
+     * Policy errors are fail-closed (treated as deny).
+     */
+    toolPolicy?: ToolPolicy;
+    /**
+     * The realtime server (agent-sdk-realtime) and its internal key, one per
+     * environment, from the host's secret store. Required. Turn events go to
+     * `POST {url}/api/emit`.
+     */
+    realtime: {
+        url: string;
+        apiKey: string;
+    };
+    /**
+     * How UI actions reach the client and how its answers come back. Defaults
+     * to the realtime server: requests are emitted to the turn's room and
+     * answers collected from `GET /internal/oui/action-results/{requestId}`.
+     */
+    uiActions?: {
+        channel?: UIActionChannel;
+        /** How long a UI tool waits for the client's answer. Default 20 s. */
+        resultTimeoutMs?: number;
+        /** Largest page-state payload given to the model, in characters. Default 6000. */
+        maxObservationChars?: number;
+    };
+    /**
+     * The approval store (ADR-0228). Defaults to the realtime server's
+     * (`/internal/approvals`), where it lives beside the UI action results.
+     */
+    approvals?: {
+        store?: ApprovalStoreClient;
+    };
+    /**
+     * Returns a database client/handle. Called once per invocation.
+     * The returned value is passed to `getHistory` and `persistMessages`.
+     *
+     * Example: `async () => prisma`
+     */
+    getDb: () => Promise<TDb>;
+    /**
+     * Loads conversation history for context. Called once per turn.
+     * Return prior user/assistant/tool messages in chronological order.
+     *
+     * The SDK handles appending the current user message — don't include it.
+     */
+    getHistory: (conversationId: string, db: TDb) => Promise<TurnHistoryMessage[]>;
+    /**
+     * Persists the new messages generated during this turn.
+     * Called after the turn completes successfully.
+     */
+    persistMessages: (input: {
+        turnId: string;
+        conversationId: string;
+        messages: TurnMessage[];
+        usage: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+        db: TDb;
+    }) => Promise<void>;
+    /**
+     * Optional: record turn start in your database. Receives the db handle.
+     * Default: no-op (the SDK still emits `agent:turn_started` to realtime).
+     */
+    recordTurnStart?: (input: {
+        turnId: string;
+        conversationId: string;
+        userId: string;
+        accountId: string;
+        model: string;
+        db: TDb;
+    }) => Promise<void>;
+    /**
+     * Optional: record turn completion. Default: no-op.
+     */
+    recordTurnComplete?: (input: {
+        turnId: string;
+        conversationId: string;
+        rounds: number;
+        usage: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+        db: TDb;
+    }) => Promise<void>;
+    /**
+     * Optional: record turn failure. Default: no-op.
+     */
+    recordTurnFailure?: (input: {
+        turnId: string;
+        conversationId: string;
+        error: {
+            code: string;
+            message: string;
+            recoverable: boolean;
+        };
+        db: TDb;
+    }) => Promise<void>;
+    /**
+     * Optional: custom logger. Default: structured console logger.
+     */
+    logger?: {
+        info: (msg: string, data?: Record<string, unknown>) => void;
+        warn: (msg: string, data?: Record<string, unknown>) => void;
+        error: (msg: string, data?: Record<string, unknown>) => void;
+        debug: (msg: string, data?: Record<string, unknown>) => void;
+    };
+}
+/** The Lambda adapter's configuration: the runtime's, unchanged. */
+export type LambdaAgentConfig<TDb = IntegratorDb> = AgentRuntimeConfig<TDb>;
+//# sourceMappingURL=types.d.ts.map