@ouispec/agent-worker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Closure Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @ouispec/agent-worker
+
+The agent runtime. One core runs a turn: the model, the tool loop, UI actions answered by the user's own tab (ADR-0209), streaming, retries and deadlines. Two host adapters run that core: Lambda + SQS, and a long-running container (ADR-0227 §2.1).
+
+## What the host supplies
+
+A missing value fails when the adapter is created, and the error names it. Nothing falls back to an environment variable or an empty string.
+
+| Seam | Config | Notes |
+|---|---|---|
+| Model | `model` | Any `ai` library model: `bedrock(...)`, `openai(...)`, `anthropic(...)`, or a gateway id. The worker imports no provider itself. |
+| Prompt cache | `promptCacheBreakpoint`, optional | Provider options that mark a cache breakpoint. `PROMPT_CACHE_BREAKPOINTS.bedrock` and `.anthropic` are provided. Omit it for a provider that caches on its own. |
+| Realtime server | `realtime: { url, apiKey }` | The `agent-sdk-realtime` server and its internal key. Turn events go to `POST {url}/api/emit`, and UI action answers are collected from `GET {url}/internal/oui/action-results/:id`. |
+| Persona | `persona` or `systemPrompt`, exactly one | The assistant's identity comes only from here. The shipped rules name no product. |
+| Tools | `tools` | A list, or a per-turn resolver. Pass `[]` when the only tools are the tab's UI actions. |
+| Persistence | `getDb`, `getHistory`, `persistMessages` | `getDb`'s handle is passed to every callback. `recordTurnStart`, `recordTurnComplete` and `recordTurnFailure` are optional. |
+
+Optional tuning, with its defaults:
+- `maxRounds`: 12
+- `maxTokens`: 4096
+- `temperature`: 0.3
+- `toolTimeoutMs`: 30 s
+- `turnDeadlineMs`: 14 min (keep it below your host's own limit)
+- `retries`: 3
+
+Policy hooks: `turnPolicy`, `toolPolicy`, `uiActions`, `approvals`, `logger`.
+
+## What a UI client sends with a turn
+
+Two keys on the turn's `context` are for the worker itself, and your persona or `systemPrompt` callback never sees them:
+
+| Key | What the tab puts there | What the worker does with it |
+|---|---|---|
+| `oui` | Its surface snapshot: `ouiRuntime.snapshot()` (ADR-0209) | Builds the turn's UI tools from it, and from nothing else |
+| `uiKnowledge` | Its generated knowledge for the page the user is on: `resolveKnowledge(generatedKnowledge, path)` from `@ouispec/bindings` | Renders it after your prompt: each entry under "Platform Knowledge", then each recipe under "Active Workflows" |
+
+Every other key is the page's context, which a persona prompt shows as the current UI state. A malformed `oui` or `uiKnowledge` fails the turn, naming the bad field. The worker logs `UI surfaces for this turn` with the surface ids and the knowledge's entry and workflow counts.
+
+## Approvals (ADR-0228)
+
+An irreversible action runs only on an approval the user gave, bound to the exact call. A call needs approval when:
+
+- its declared `effect` is a `transaction` (an order, a payment, a send, a publish), which no policy can waive;
+- its declaration says `destructive: true` (a UI action's `confirm`, or a host tool's `destructive`);
+- or your `toolPolicy` returns `require_approval`. The policy's context carries the tool's `effect` and `destructive`, so it can decide on what the call does rather than on its name.
+
+A `deny` always wins, over an approval too, and an approved call still runs as the user.
+
+What happens:
+
+1. The first such call in a turn stops the turn. The worker stores it in the realtime server's approval store and emits `agent:approval_required` with the preview. The preview's words come from the declaration: the tool's `title`, its `consequence` or description, and its input schema's property titles. The model is told only that the call is waiting, and never sees a token. Any other call in the same response is not run.
+2. The user decides on the approval card.
+3. The next turn carries `approval: { approvalId, decision: 'approve', token }` or `{ approvalId, decision: 'decline' }` on its payload, outside the message text. The worker redeems the token and runs exactly the stored call. A UI action's request then carries `approval: { approvalId, argsHash }` for the browser's own check. The call and its result are persisted, and the model is told what happened in an `<approval>` block. A replayed, expired or foreign token runs nothing, and neither does a decline; the model is told why.
+
+In a browser, the turn after the decision comes from `ApprovalCard` (`@ouispec/agent-react`). Your `sendMessage` callback receives `approval` beside an empty `content`. Pass it unchanged to the worker as the turn payload's `approval`: `{ approvalId, decision: 'approve', token }` or `{ approvalId, decision: 'decline' }`. A UI action declares its effect on its OUI surface (`effect: 'transaction'`, or `confirm: true` for a destructive one). The tab's OUI runtime runs it only on the grant from the user's own click, which `grantApproval` in the client config hands it.
+
+Declare a host tool's approval needs on the tool itself: `effect`, `destructive`, `title`, `consequence`, and `argsSensitive: false` when its arguments may be logged. Without an approval store, such a call is refused and never runs. The runtime uses the realtime server's store unless you pass `approvals.store`.
+
+## Lambda + SQS
+
+```ts
+import { createLambdaAgentHandler, PROMPT_CACHE_BREAKPOINTS } from '@ouispec/agent-worker';
+import { bedrock } from '@ai-sdk/amazon-bedrock';
+
+export const handler = createLambdaAgentHandler({
+  model: bedrock('us.anthropic.claude-sonnet-4-6'),
+  promptCacheBreakpoint: PROMPT_CACHE_BREAKPOINTS.bedrock,
+  realtime: { url: env.REALTIME_URL, apiKey: env.REALTIME_INTERNAL_KEY },
+  persona,
+  tools: [],
+  getDb,
+  getHistory,
+  persistMessages,
+});
+```
+
+Each invocation takes one SQS record whose body is an `AgentTurnPayload`: `turnId`, `conversationId`, `userId`, `accountId`, `socketRoom`, `content`, and optionally `context` and `userToken`. A failure the runtime marks unrecoverable is rethrown, so your redrive policy sees it. A recoverable one, where the provider is rate-limiting or unavailable, has already been reported to the client and is not rethrown.
+
+## Container
+
+```ts
+import { startContainerAgentWorker } from '@ouispec/agent-worker';
+import { openai } from '@ai-sdk/openai';
+
+const worker = await startContainerAgentWorker({
+  model: openai('gpt-4.1'),
+  realtime: { url: env.REALTIME_URL, apiKey: env.REALTIME_INTERNAL_KEY },
+  systemPrompt: () => persona,
+  tools: [],
+  getDb,
+  getHistory,
+  persistMessages,
+  port: 8080,
+  workerApiKey: env.WORKER_KEY,
+});
+process.on('SIGTERM', () => worker.close()); // closing waits for running turns
+```
+
+Your API sends turns to the worker's HTTP endpoints:
+
+| Request | Responses |
+|---|---|
+| `POST /turns` with an `AgentTurnPayload` and `x-api-key` | `202` once accepted. `400` if the body is not a turn, `401` for a wrong key, `409` if that turn is already running, `503` at capacity (`maxConcurrentTurns`, default 8) or while shutting down. |
+| `GET /health` | The worker's status, running turns, capacity and model. |
+
+`onTurnEnd` receives each turn's outcome.
+
+## Conversation history in the browser
+
+`agent-sdk-react` restores a tab's conversation after a reload, and lists or switches conversations, when your API provides two endpoints behind `AgentClientConfig`. Both must be filtered by the signed-in user:
+
+- `listConversations`: the user's conversations, most recent first.
+- `getConversation`: one of them, with its messages.
+
+## API tools from an OpenAPI document
+
+`loadOpenApiTools` turns the product's own OpenAPI 3 document into tools for backend, MCP and external agents (ADR-0181 §2). There is no second manifest format. It is also exported at `@ouispec/agent-worker/openapi`.
+
+```ts
+import { loadOpenApiTools } from '@ouispec/agent-worker/openapi';
+
+const tools = loadOpenApiTools(document, {
+  baseUrl: 'https://api.example.com',
+  audience: 'agents',                        // or 'pa': only operations flagged pa: true
+  actAs: (ctx) => signedAssertionFor(ctx.userId, ctx.accountId), // headers; required, no default
+});
+```
+
+An operation opts in per operation, with `x-agent`:
+
+| Key | Meaning |
+|---|---|
+| `expose: true` | The operation is a tool. Without it, it is not offered. |
+| `effect` | What calling it changes (ADR-0226 §2.6): `view` (a read), `file`, `mutate`, `job` or `transaction`, or the effect's object form. `selection`, `navigate`, `open` and `edit` are a page's effects and are refused. |
+| `destructive: true` | On a write: it removes or replaces something the person made. |
+| `consequence` | A sentence saying what happens. It goes in the description, and in an approval's preview. |
+| `pa: true` | The product's own assistant may call it. Allowed only on a read (ADR-0227 §2.1). |
+
+Each tool:
+- is named by the operation's `operationId`, and described by its `summary` and `description`;
+- takes its parameters and JSON body as input, with `$ref`s inlined, 3.0 `nullable` read as `null`, and `readOnly` fields left out. A closed object body's fields sit beside the parameters; any other body is the `body` property. The input refuses undeclared properties, and the worker validates every call against it;
+- carries `effect` and `destructive` for approvals to key on, and its operation's standard `security` requirement as the permissions it needs;
+- calls the API with the headers `actAs` returns, so the API treats the call as that caller. A permission the caller lacks comes back as the route's own refusal. The tool returns it as its error, with the status and body, and the model reads it;
+- runs a `transaction` only with the person's approval of that exact call (ADR-0228): the worker's approval card supplies it, and its title and consequence come from the operation's `summary` and `x-agent.consequence`. Without one, as over MCP, it returns `APPROVAL_REQUIRED` and sends nothing.
+
+Refused at load, naming the operation: `pa` on anything but a read, a missing or invalid `operationId`, a missing `effect`, an unknown `x-agent` key, `destructive` on a read, a read on `PUT`, `PATCH` or `DELETE`, no security requirement (use `[]` for a public operation), an undeclared security scheme, a non-JSON body, a self-referencing or external `$ref`, and a path whose template and parameters disagree.
+
+**Async operations (W9).** An operation that starts a job names the declared completion it ends with, in `x-async-binding`:
+
+```yaml
+x-agent: { expose: true, effect: job }
+x-async-binding: { event: report:ready, timeout: 2m }   # optional: failure, correlation, idField
+```
+
+- `event` must be a declared completion in the product's event declarations, which are passed as `events`. Its failure and the event's id field (`correlation`) default to what the declarations pair with it.
+- The tool reads the job id from the response field named by the event's correlation. When the route returns it under another name, `idField` names that field.
+- The wait defaults to the `job` effect's `timeoutMs`, else 60 s.
+- An undeclared or non-completion event is refused at load. So are a binding on an operation whose effect isn't `job` or `transaction`, and a binding when no `events` are given.
+- With a `waiter` (e.g. `createHttpEventWaiter`), the tool waits for the job to settle and returns `status: 'complete'` with the declared result. A failure fails the call with its declared reason. If the job hasn't settled in time, the call returns `status: 'dispatched'` with the reason. Without a waiter it returns the dispatch.
+- The binding's `room`, `payload` and `lifecycleEvents` are documentation: the declarations are the authority.
+
+Header parameters are never model input: `actAs` supplies them, and a call fails if it leaves out one the operation requires.
+
+`@ouispec/agent-worker/testing` ships a fixture product's API for tests: an OpenAPI document, its event declarations (`DESK_EVENTS`), and a server that enforces its own auth and permissions. Its report export is a job, and `onReportQueued` lets a test end it with a declared event.
+
+## The socket in the browser
+
+`agent-sdk-react` connects to the realtime server through `realtime.createSocket`. The default is a Socket.IO client. Any `SocketLike` works: it must emit `connect` on every (re)connection and `disconnect` when it drops. That same socket carries the tab's OUI transport.
+
+## Testing
+
+- `pnpm test` includes the fixture turn. It runs on both adapters and on two providers, replaying recorded responses through each provider's real `ai` package, against the SDK realtime server on Redis.
+- `pnpm record:fixture-turn` re-records the Bedrock responses from a live model.
+- `pnpm eval:live` runs the live operating-rules eval.
+- Both of those live commands need Bedrock credentials in the environment.

package/dist/approvals/client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The worker's side of the approval store (ADR-0228 §2.4), which lives in the
+ * realtime server beside the UI action result store. The worker stores a
+ * pending approval when it stops a turn, redeems the token the next turn
+ * carries, and reads a decline.
+ */
+import type { ApprovalRedeemResult, ApprovalStatus, PendingApprovalInput } from '@ouispec/agent-core';
+export interface ApprovalStoreClient {
+    /** Store a pending approval. Rejects when it was not stored: the call must then not wait on it. */
+    create(pending: PendingApprovalInput): Promise<void>;
+    /** The stored call for a valid, unexpired, unused token of this user and conversation; otherwise why not. Rejects when the store cannot be reached. */
+    redeem(token: string, caller: {
+        userId: string;
+        conversationId: string;
+    }): Promise<ApprovalRedeemResult>;
+    /** Where an approval of this user's stands, or null when there is none. */
+    status(approvalId: string, userId: string): Promise<ApprovalStatus | null>;
+}
+export interface HttpApprovalStoreClientConfig {
+    /** The realtime server's base URL. */
+    url: string;
+    /** Its internal key. */
+    apiKey: string;
+    /** Per request. Default 5 s. */
+    timeoutMs?: number;
+}
+/** The store over the realtime server's internal HTTP API. */
+export declare function createHttpApprovalStoreClient(config: HttpApprovalStoreClientConfig): ApprovalStoreClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/approvals/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/approvals/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,oBAAoB,EAEpB,cAAc,EAEd,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,mBAAmB;IAClC,mGAAmG;IACnG,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,uJAAuJ;IACvJ,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzG,2EAA2E;IAC3E,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,6BAA6B;IAC5C,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,8DAA8D;AAC9D,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,6BAA6B,GAAG,mBAAmB,CA8CxG"}

package/dist/approvals/client.js

@@ -0,0 +1,50 @@
+import { requireRealtime } from '../emit/http-adapter.js';
+/** The store over the realtime server's internal HTTP API. */
+export function createHttpApprovalStoreClient(config) {
+    const { url, apiKey } = config;
+    requireRealtime(url, apiKey);
+    const timeoutMs = config.timeoutMs ?? 5_000;
+    const call = async (path, body) => {
+        const res = await fetch(`${url}${path}`, {
+            method: body === undefined ? 'GET' : 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-Api-Key': apiKey },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch {
+            // A non-JSON answer is reported by status below.
+        }
+        return { status: res.status, json };
+    };
+    return {
+        async create(pending) {
+            const { status, json } = await call('/internal/approvals', pending);
+            if (status !== 201) {
+                throw new Error(`[agent-sdk] The approval store did not keep approval ${pending.approvalId}: HTTP ${status} ${String(json.error ?? '')}`);
+            }
+        },
+        async redeem(token, caller) {
+            const { status, json } = await call('/internal/approvals/redeem', { token, ...caller });
+            if (status === 200)
+                return { ok: true, call: json.call };
+            if (status >= 400 && status < 500 && typeof json.reason === 'string') {
+                return { ok: false, reason: json.reason, error: String(json.error ?? json.reason) };
+            }
+            throw new Error(`[agent-sdk] The approval store could not redeem a token: HTTP ${status}`);
+        },
+        async status(approvalId, userId) {
+            const { status, json } = await call(`/internal/approvals/${encodeURIComponent(approvalId)}?${new URLSearchParams({ userId })}`);
+            if (status === 200)
+                return json;
+            if (status === 404)
+                return null;
+            throw new Error(`[agent-sdk] The approval store could not report approval ${approvalId}: HTTP ${status}`);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/approvals/client.js.map

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

package/dist/approvals/continuation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The turn after a decision (ADR-0228 §2.2.5). It carries, outside the
+ * message text, the token to redeem or that the user declined. The worker
+ * asks the store — never the client — what was decided, runs exactly the
+ * stored call when there is one, and tells the model what happened in an
+ * `<approval>` block on the user's message.
+ */
+import type { ApprovalContinuation, ApprovedCall } from '@ouispec/agent-core';
+import type { ApprovalStoreClient } from './client.js';
+export type ContinuationOutcome = 
+/** Approved and redeemed: run this call, exactly. */
+{
+    kind: 'run';
+    call: ApprovedCall;
+}
+/** Nothing runs; the model is told why. */
+ | {
+    kind: 'note';
+    note: string;
+};
+export declare const approvalNote: (text: string) => string;
+export declare function ranNote(title: string): string;
+export declare function unavailableNote(title: string): string;
+export declare function resolveContinuation(store: ApprovalStoreClient | undefined, continuation: ApprovalContinuation, turn: {
+    userId: string;
+    conversationId: string;
+}): Promise<ContinuationOutcome>;
+//# sourceMappingURL=continuation.d.ts.map

package/dist/approvals/continuation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation.d.ts","sourceRoot":"","sources":["../../src/approvals/continuation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAyB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACrG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,MAAM,mBAAmB;AAC7B,qDAAqD;AACnD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE;AACrC,2CAA2C;GACzC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAanC,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,WAAmC,CAAC;AAE7E,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,mBAAmB,GAAG,SAAS,EACtC,YAAY,EAAE,oBAAoB,EAClC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAC/C,OAAO,CAAC,mBAAmB,CAAC,CAyB9B"}

package/dist/approvals/continuation.js

@@ -0,0 +1,43 @@
+const WHY_NOT = {
+    used: 'this approval has already been used',
+    expired: 'the approval expired before it was used',
+    invalid: 'the approval is not valid',
+    forbidden: 'the approval belongs to another user or conversation',
+    mismatch: 'the approval is not for that call',
+    unknown: 'no such approval is waiting',
+    decided: 'the approval could not be used',
+    channel: 'the approval could not be used',
+};
+export const approvalNote = (text) => `<approval>${text}</approval>`;
+export function ranNote(title) {
+    return approvalNote(`The user approved "${title}" on the approval card, and it was run once, with the arguments they approved. Its result follows: report what it says, including a failure.`);
+}
+export function unavailableNote(title) {
+    return approvalNote(`The user approved "${title}" on the approval card, but it did not run: it is not available where they are now.`);
+}
+export async function resolveContinuation(store, continuation, turn) {
+    if (!store)
+        return { kind: 'note', note: approvalNote('An approval arrived, but the approved action did not run: this worker has no approval store.') };
+    if (continuation.decision === 'decline') {
+        const status = await store.status(continuation.approvalId, turn.userId).catch(() => null);
+        const what = status?.title ? `"${status.title}"` : 'the action';
+        return {
+            kind: 'note',
+            note: status?.status === 'declined'
+                ? approvalNote(`The user declined ${what} on the approval card, so it did not run. Do not run it again unless they ask for it again.`)
+                : approvalNote(`The user did not approve ${what}, so it did not run.`),
+        };
+    }
+    let redeemed;
+    try {
+        redeemed = await store.redeem(continuation.token, turn);
+    }
+    catch {
+        return { kind: 'note', note: approvalNote('An approval arrived, but the approved action did not run: the approval could not be checked.') };
+    }
+    if (!redeemed.ok) {
+        return { kind: 'note', note: approvalNote(`An approval arrived, but the approved action did not run: ${WHY_NOT[redeemed.reason]}.`) };
+    }
+    return { kind: 'run', call: redeemed.call };
+}
+//# sourceMappingURL=continuation.js.map

package/dist/approvals/continuation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation.js","sourceRoot":"","sources":["../../src/approvals/continuation.ts"],"names":[],"mappings":"AAgBA,MAAM,OAAO,GAA0C;IACrD,IAAI,EAAE,qCAAqC;IAC3C,OAAO,EAAE,yCAAyC;IAClD,OAAO,EAAE,2BAA2B;IACpC,SAAS,EAAE,sDAAsD;IACjE,QAAQ,EAAE,mCAAmC;IAC7C,OAAO,EAAE,6BAA6B;IACtC,OAAO,EAAE,gCAAgC;IACzC,OAAO,EAAE,gCAAgC;CAC1C,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,aAAa,IAAI,aAAa,CAAC;AAE7E,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,YAAY,CAAC,sBAAsB,KAAK,8IAA8I,CAAC,CAAC;AACjM,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,YAAY,CAAC,sBAAsB,KAAK,qFAAqF,CAAC,CAAC;AACxI,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAsC,EACtC,YAAkC,EAClC,IAAgD;IAEhD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,8FAA8F,CAAC,EAAE,CAAC;IAExJ,IAAI,YAAY,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAC1F,MAAM,IAAI,GAAG,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QAChE,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,IAAI,EACF,MAAM,EAAE,MAAM,KAAK,UAAU;gBAC3B,CAAC,CAAC,YAAY,CAAC,qBAAqB,IAAI,6FAA6F,CAAC;gBACtI,CAAC,CAAC,YAAY,CAAC,4BAA4B,IAAI,sBAAsB,CAAC;SAC3E,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,8FAA8F,CAAC,EAAE,CAAC;IAC9I,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,6DAA6D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACxI,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC"}

package/dist/approvals/preview.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The approval card's words (ADR-0228 §2.2.2). Every one comes from the
+ * tool's declaration — its title, its description, its input schema's labels —
+ * and the call's arguments. None comes from the model: the model chooses the
+ * call, never how it is described to the person approving it.
+ */
+import type { ApprovalPreview } from '@ouispec/agent-core';
+import type { RegisteredTool } from '../tools/types.js';
+/** The action's title and what it does, as its declaration states them. */
+export declare function declaredTitle(tool: RegisteredTool): {
+    title: string;
+    consequence?: string;
+};
+export declare function buildApprovalPreview(tool: RegisteredTool, args: Record<string, unknown>): ApprovalPreview;
+//# sourceMappingURL=preview.d.ts.map

package/dist/approvals/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/approvals/preview.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAA2B,MAAM,qBAAqB,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAOxD,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAI3F;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CAezG"}

package/dist/approvals/preview.js

@@ -0,0 +1,33 @@
+/** The action's title and what it does, as its declaration states them. */
+export function declaredTitle(tool) {
+    const title = tool.title?.trim() || tool.name;
+    const consequence = (tool.consequence ?? tool.description)?.trim();
+    return consequence && consequence !== title ? { title, consequence } : { title };
+}
+export function buildApprovalPreview(tool, args) {
+    const { title, consequence } = declaredTitle(tool);
+    const properties = (tool.inputSchema.properties ?? {});
+    // The schema's order first, then anything else the call carries.
+    const names = [...Object.keys(properties).filter((k) => k in args), ...Object.keys(args).filter((k) => !(k in properties))];
+    const argumentsShown = names
+        .filter((name) => args[name] !== undefined)
+        .map((name) => ({ name, label: properties[name]?.title?.trim() || name, value: valueText(args[name], properties[name]) }));
+    const listed = argumentsShown.map((a) => `${a.label} ${a.value}`).join(', ');
+    const readback = `${title}${listed ? `: ${listed}` : ''}.${consequence ? ` ${consequence}` : ''}`;
+    return { title, ...(consequence ? { consequence } : {}), arguments: argumentsShown, readback };
+}
+function valueText(value, schema) {
+    const named = schema?.oneOf?.find((o) => o.const === value && o.title);
+    if (named?.title)
+        return named.title;
+    if (value === null)
+        return 'none';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value) && value.every((v) => v === null || typeof v !== 'object'))
+        return value.map((v) => String(v)).join(', ');
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=preview.js.map

package/dist/approvals/preview.js.map

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

package/dist/approvals/requirement.d.ts

@@ -0,0 +1,15 @@
+import type { RegisteredTool, ToolEffect } from '../tools/types.js';
+export interface ApprovalRequirement {
+    effect: ToolEffect | undefined;
+    destructive: boolean;
+    /** Whether the declaration alone requires the user's approval of each call. */
+    required: boolean;
+    /** The effect as the approval store and its token name it: its kind, or `write` when none is declared. */
+    effectName: string;
+    /** How long an approval of it lasts. */
+    ttlMs: number;
+}
+export declare function approvalRequirement(tool: RegisteredTool): ApprovalRequirement;
+/** What the model reads on a tool whose calls need approval, in place of any "confirm first" instruction. */
+export declare const APPROVAL_TOOL_NOTE: string;
+//# sourceMappingURL=requirement.d.ts.map

package/dist/approvals/requirement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement.d.ts","sourceRoot":"","sources":["../../src/approvals/requirement.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB,0GAA0G;IAC1G,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,GAAG,mBAAmB,CAW7E;AAED,6GAA6G;AAC7G,eAAO,MAAM,kBAAkB,QAGX,CAAC"}

package/dist/approvals/requirement.js

@@ -0,0 +1,26 @@
+/**
+ * What a tool's declaration says about approval (ADR-0228 §2.1), for every
+ * kind of tool the worker runs: a UI action from the client's surfaces, a
+ * generated API tool (its effect from the operation's `x-agent`), a host tool.
+ * The rule itself is OUI's `requiresApproval` (through oui-bindings), which the browser applies too; a host's
+ * policy may require approval of more, never of less.
+ */
+import { DEFAULT_APPROVAL_TTL_MS, MAX_APPROVAL_TTL_MS } from '@ouispec/agent-core';
+import { effectKind, requiresApproval } from '@ouispec/bindings';
+export function approvalRequirement(tool) {
+    const effect = tool.effect;
+    const destructive = tool.destructive === true;
+    const minutes = effect && typeof effect === 'object' && effect.kind === 'transaction' ? effect.approvalMinutes : undefined;
+    return {
+        effect,
+        destructive,
+        required: requiresApproval(effect, destructive),
+        effectName: effect === undefined ? 'write' : effectKind(effect),
+        ttlMs: minutes ? Math.min(minutes * 60_000, MAX_APPROVAL_TTL_MS) : DEFAULT_APPROVAL_TTL_MS,
+    };
+}
+/** What the model reads on a tool whose calls need approval, in place of any "confirm first" instruction. */
+export const APPROVAL_TOOL_NOTE = "Needs the user's approval: calling it shows them an approval card with exactly these arguments, and it runs only when " +
+    'they approve it there. Call it directly when they ask for it. Do not ask for a yes in chat first, and never treat a typed ' +
+    'yes as approval.';
+//# sourceMappingURL=requirement.js.map

package/dist/approvals/requirement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement.js","sourceRoot":"","sources":["../../src/approvals/requirement.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAcjE,MAAM,UAAU,mBAAmB,CAAC,IAAoB;IACtD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC;IAC9C,MAAM,OAAO,GAAG,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3H,OAAO;QACL,MAAM;QACN,WAAW;QACX,QAAQ,EAAE,gBAAgB,CAAC,MAAM,EAAE,WAAW,CAAC;QAC/C,UAAU,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;QAC/D,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,uBAAuB;KAC3F,CAAC;AACJ,CAAC;AAED,6GAA6G;AAC7G,MAAM,CAAC,MAAM,kBAAkB,GAC7B,wHAAwH;IACxH,4HAA4H;IAC5H,kBAAkB,CAAC"}

package/dist/authz/tool-policy.d.ts

@@ -0,0 +1,63 @@
+import type { ToolEffect } from '../tools/types.js';
+/**
+ * ToolPolicy — evaluated before every tool execution.
+ * Integrators provide their own policy implementation via AgentWorkerConfig.toolPolicy.
+ *
+ * The policy is called AFTER quota enforcement but BEFORE the tool executes.
+ * This allows integrators to enforce per-user, per-account, per-tool authorization
+ * rules (role-based access, feature flags, rate limits, compliance checks, etc.).
+ */
+export interface ToolPolicy {
+    evaluate(ctx: ToolPolicyContext): Promise<ToolPolicyDecision>;
+}
+export interface ToolPolicyContext {
+    /** The internal user ID performing the action. */
+    userId: string;
+    /** The account ID the user belongs to. */
+    accountId: string;
+    /** The tool being invoked. */
+    toolName: string;
+    /** The arguments passed to the tool. */
+    args: Record<string, unknown>;
+    /** The current turn ID for audit/traceability. */
+    turnId: string;
+    /** Whether the tool has side effects (fail-closed: true if unknown). */
+    hasSideEffects: boolean;
+    /**
+     * `ui` for an action on the client's UI (ADR-0209), which runs in the
+     * user's browser under their own session; `backend` for a host tool.
+     * Decide by this, not by the name: a UI action id can equal a host tool's.
+     */
+    toolKind: 'ui' | 'backend';
+    /** What the tool declares it does (ADR-0226 §2.6); undefined when it declares nothing, which counts as a write. */
+    effect: ToolEffect | undefined;
+    /** Whether the tool declares it removes or replaces something the person made. */
+    destructive: boolean;
+}
+/**
+ * - `allow`: run it. A `transaction` or destructive call still needs the
+ *   user's approval (ADR-0228 §2.1): no policy waives that.
+ * - `deny`: never run it. Approval never overrides a deny.
+ * - `require_approval`: run it only on the user's approval of this exact call,
+ *   given on the approval card (or a conversation channel's readback). The
+ *   turn stops at it; the call runs in the turn after the decision.
+ */
+export type ToolPolicyDecision = {
+    action: 'allow';
+} | {
+    action: 'deny';
+    reason: string;
+} | {
+    action: 'require_approval';
+    reason: string;
+};
+/**
+ * Default policy — allows all tools. Integrators override this.
+ */
+export declare const defaultToolPolicy: ToolPolicy;
+/**
+ * Evaluate a tool policy, returning a denial on error (fail-closed).
+ * This wrapper ensures that a broken policy never silently allows execution.
+ */
+export declare function evaluateToolPolicySafe(policy: ToolPolicy, ctx: ToolPolicyContext): Promise<ToolPolicyDecision>;
+//# sourceMappingURL=tool-policy.d.ts.map

package/dist/authz/tool-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-policy.d.ts","sourceRoot":"","sources":["../../src/authz/tool-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;GAOG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,cAAc,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,QAAQ,EAAE,IAAI,GAAG,SAAS,CAAC;IAC3B,mHAAmH;IACnH,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,kFAAkF;IAClF,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GACnB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAE/B,CAAC;AAEF;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAU7B"}

package/dist/authz/tool-policy.js

@@ -0,0 +1,23 @@
+/**
+ * Default policy — allows all tools. Integrators override this.
+ */
+export const defaultToolPolicy = {
+    evaluate: async () => ({ action: 'allow' }),
+};
+/**
+ * Evaluate a tool policy, returning a denial on error (fail-closed).
+ * This wrapper ensures that a broken policy never silently allows execution.
+ */
+export async function evaluateToolPolicySafe(policy, ctx) {
+    try {
+        return await policy.evaluate(ctx);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown policy error';
+        return {
+            action: 'deny',
+            reason: `Policy evaluation failed (fail-closed): ${message}`,
+        };
+    }
+}
+//# sourceMappingURL=tool-policy.js.map

package/dist/authz/tool-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-policy.js","sourceRoot":"","sources":["../../src/authz/tool-policy.ts"],"names":[],"mappings":"AAqDA;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAe;IAC3C,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,OAAgB,EAAE,CAAC;CACrD,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAkB,EAClB,GAAsB;IAEtB,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAAC;QAChF,OAAO;YACL,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,2CAA2C,OAAO,EAAE;SAC7D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/container/server.d.ts

@@ -0,0 +1,24 @@
+import { type TurnOutcome } from '../runtime/turn-runner.js';
+import type { AgentRuntimeConfig } from '../runtime/types.js';
+export interface ContainerAgentConfig<TDb> extends AgentRuntimeConfig<TDb> {
+    /** The port to listen on. `0` picks a free one. Required. */
+    port: number;
+    /** The key the host's API sends as `x-api-key`. Required: the endpoint runs turns as any user. */
+    workerApiKey: string;
+    /** Turns run at once; more are refused with 503. Default 8. */
+    maxConcurrentTurns?: number;
+    /** Largest request body, in bytes. Default 1 MiB. */
+    maxBodyBytes?: number;
+    /** Called with each turn's outcome, after it ends. */
+    onTurnEnd?: (outcome: TurnOutcome) => void;
+}
+export interface ContainerAgentWorker {
+    /** The port the server listens on (the one picked, when configured with 0). */
+    port: number;
+    /** Turns running now. */
+    running(): number;
+    /** Stops taking turns, waits for the running ones to end, then closes. */
+    close(): Promise<void>;
+}
+export declare function startContainerAgentWorker<TDb>(config: ContainerAgentConfig<TDb>): Promise<ContainerAgentWorker>;
+//# sourceMappingURL=server.d.ts.map

package/dist/container/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/container/server.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAyC,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACpG,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,qBAAqB,CAAC;AAEhF,MAAM,WAAW,oBAAoB,CAAC,GAAG,CAAE,SAAQ,kBAAkB,CAAC,GAAG,CAAC;IACxE,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,kGAAkG;IAClG,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,OAAO,IAAI,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,oBAAoB,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA2GrH"}