@ouispec/agent-worker 0.1.0

package/dist/turn-policy.js

@@ -0,0 +1,21 @@
+/**
+ * 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
+ */
+/**
+ * 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 const defaultTurnPolicy = {
+    classifyTurn: () => 'normal',
+    prepareStep: async () => ({}),
+};
+//# sourceMappingURL=turn-policy.js.map

package/dist/turn-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-policy.js","sourceRoot":"","sources":["../src/turn-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8CH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAe;IAC3C,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ;IAC5B,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;CAC9B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,151 @@
+import type { LanguageModel, ProviderOptions } from './model.js';
+import type { RealtimeEmitAdapter } from './emit/types.js';
+import type { ToolRegistry } from './tools/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 { ApprovalStoreClient } from './approvals/client.js';
+import type { ApprovalContinuation } from '@ouispec/agent-core';
+/**
+ * Configuration for the agent worker.
+ * Platforms provide this to run the orchestration loop.
+ */
+export interface AgentWorkerConfig {
+    tools: ToolRegistry;
+    emit: RealtimeEmitAdapter;
+    /**
+     * The host's AgentApiSurface binding, threaded into ToolExecutionContext
+     * so schema-generated tools can call executeIntent. Optional.
+     */
+    apiSurface?: import('@ouispec/agent-core').AgentApiSurface;
+    systemPrompt: string | ((context: SystemPromptContext) => string);
+    /** The model, from any `ai` library provider (ADR-0227 §2.2). Required. */
+    model: LanguageModel;
+    /**
+     * Provider options that mark a prompt-cache breakpoint, placed after the
+     * system prompt (which covers the tools) and at the end of the history.
+     * See PROMPT_CACHE_BREAKPOINTS. Omit for a provider that caches on its own.
+     */
+    promptCacheBreakpoint?: ProviderOptions;
+    maxToolRounds?: number;
+    maxTokens?: number;
+    temperature?: number;
+    toolTimeoutMs?: number;
+    turnDeadlineMs?: number;
+    retries?: number;
+    /** Optional turn policy for product-specific step control. */
+    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 approval store (ADR-0228), in the realtime server. A call that needs
+     * the user's approval is stored there and the turn stops; without a store,
+     * such a call is refused and never runs.
+     */
+    approvals?: ApprovalStoreClient;
+    /**
+     * How UI actions reach the client that sent the turn and how its answers
+     * come back (ADR-0209). Required when a turn's context carries a client
+     * snapshot (`context.oui`).
+     */
+    ui?: {
+        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;
+    };
+}
+export interface SystemPromptContext {
+    userId: string;
+    accountId: string;
+    context?: Record<string, unknown> | null;
+}
+/**
+ * Input for a single agent turn.
+ */
+export interface AgentTurnInput {
+    turnId: string;
+    conversationId: string;
+    userId: string;
+    accountId: string;
+    socketRoom: string;
+    content: string;
+    context?: Record<string, unknown> | null;
+    history?: TurnHistoryMessage[];
+    userToken?: string;
+    /**
+     * Set 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). Never in the
+     * message text.
+     */
+    approval?: ApprovalContinuation;
+}
+/**
+ * Rich history message — supports full conversation state including tool calls and results.
+ * This is the format integrators prepare from their conversation store.
+ */
+export type TurnHistoryMessage = {
+    role: 'user';
+    content: string;
+} | {
+    role: 'assistant';
+    content: string | null;
+    tool_calls?: ToolCallRef[];
+} | {
+    role: 'tool';
+    content: string;
+    tool_call_id: string;
+    name?: string;
+};
+export interface ToolCallRef {
+    id: string;
+    type?: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Result from a completed agent turn.
+ */
+export interface AgentTurnResult {
+    rounds: number;
+    usage: {
+        /** Input tokens summed over every round of the turn — what the turn cost. */
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        /**
+         * Input tokens on the LARGEST single round — what the context window sees.
+         * Compare a context ceiling against this, never against `promptTokens`:
+         * the sum grows with round count and reports a context problem that is not
+         * there while staying silent about one that is.
+         */
+        peakPromptTokens: number;
+        /** Prefix tokens served from cache. Zero across a multi-round turn means the cache is being missed. */
+        cacheReadTokens: number;
+        /** Prefix tokens written to cache — expected on the first round of a turn. */
+        cacheWriteTokens: number;
+    };
+    newMessages: TurnMessage[];
+    maxRoundsReached: boolean;
+    /** Why the turn ended: which bound or condition terminated the loop */
+    stopReason: 'present_options' | 'awaiting_approval' | 'step_count' | 'token_budget' | 'deadline' | 'complete' | 'error';
+}
+export interface TurnMessage {
+    role: 'assistant' | 'tool';
+    content: string | null;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }>;
+    toolCallId?: string;
+    name?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,mBAAmB,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,qBAAqB,EAAE,eAAe,CAAC;IAC3D,YAAY,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,mBAAmB,KAAK,MAAM,CAAC,CAAC;IAClE,2EAA2E;IAC3E,KAAK,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,eAAe,CAAC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,EAAE,CAAC,EAAE;QACH,OAAO,EAAE,eAAe,CAAC;QACzB,sEAAsE;QACtE,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,kFAAkF;QAClF,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,GACzE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QACL,6EAA6E;QAC7E,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;QACpB;;;;;WAKG;QACH,gBAAgB,EAAE,MAAM,CAAC;QACzB,uGAAuG;QACvG,eAAe,EAAE,MAAM,CAAC;QACxB,8EAA8E;QAC9E,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,UAAU,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,YAAY,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;CACzH;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/ui/channel.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The UI action channel: how the worker sends a UI action to the client that
+ * sent the turn, and how it gets the client's answer (ADR-0209 D2).
+ *
+ * The worker is not on the client's socket. It reaches the client through the
+ * realtime service: the request is emitted to the turn's room, the client
+ * answers on OUI's result event, and the realtime service holds that answer
+ * until the worker collects it.
+ */
+import type { OUIActionRequest, OUIActionResult } from 'oui-spec/spec';
+/**
+ * Who received a request: how many of the room's tabs acknowledged it, and how
+ * many accepted it (oui-spec §7.3.7). Null from a realtime service that does
+ * not report receipts.
+ */
+export interface UIDispatchReceipt {
+    acknowledged: number;
+    accepted: number;
+}
+export interface UIActionChannel {
+    /**
+     * Deliver a request to the turn's room, and say who received it when the
+     * realtime service reports receipts. Rejects when it could not be delivered.
+     */
+    dispatch(room: string, request: OUIActionRequest): Promise<UIDispatchReceipt | null | void>;
+    /**
+     * Resolve with the client's first answer to `requestId`, or null if none
+     * arrives by the deadline. Only an answer from a client authenticated as
+     * `userId` counts. With `final`, the final answer instead: for an async
+     * action, the one sent once its work is done or has failed, never its
+     * acknowledgment.
+     */
+    awaitResult(requestId: string, options: {
+        userId: string;
+        timeoutMs: number;
+        signal?: AbortSignal;
+        final?: boolean;
+    }): Promise<OUIActionResult | null>;
+}
+export interface HttpUIActionChannelConfig {
+    /** The realtime service's base URL. */
+    url: string;
+    /** Its internal API key (the same key the emit adapter uses). */
+    apiKey: string;
+    /** Longest single wait the realtime service is asked to hold open. Default 20 s. */
+    maxPollMs?: number;
+    /** Timeout for delivering a request. Default 5 s. */
+    dispatchTimeoutMs?: number;
+    /**
+     * How long the realtime service waits for the tabs' receipts of a request
+     * before answering the delivery (oui-spec §7.3.7). Default 1.5 s; 0 asks for
+     * none.
+     */
+    receiptTimeoutMs?: number;
+}
+/**
+ * The channel over the realtime service's HTTP API:
+ * - `POST {url}/api/emit` delivers the request to the turn's room;
+ * - `GET {url}/internal/oui/action-results/{requestId}?userId=&waitMs=` waits
+ *   for the answer (200 with the result, 204 when none arrived in `waitMs`);
+ *   with `&final=1`, for the final answer of an async action.
+ */
+export declare function createHttpUIActionChannel(config: HttpUIActionChannelConfig): UIActionChannel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/ui/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/ui/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAKvE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IAE5F;;;;;;OAMG;IACH,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GACpF,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,yBAAyB;IACxC,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAyBD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,yBAAyB,GAAG,eAAe,CAyC5F"}

package/dist/ui/channel.js

@@ -0,0 +1,81 @@
+import { createWebSocketTransport } from 'oui-spec/transport';
+import { requireRealtime } from '../emit/http-adapter.js';
+import { longPoll } from '../realtime/long-poll.js';
+/**
+ * The OUI wire name for a dispatch, taken from OUI's own transport rather than
+ * written here: OUI owns its event names, and a copy of one here is how the
+ * two ends drift apart.
+ */
+function ouiDispatchEvent(request) {
+    let captured = null;
+    const capture = {
+        connected: true,
+        emit(event, data) {
+            captured = { event, data };
+        },
+        on() { },
+        off() { },
+        once() { },
+    };
+    const transport = createWebSocketTransport(capture);
+    transport.dispatch(request);
+    transport.dispose();
+    if (!captured)
+        throw new Error('[agent-sdk] OUI transport emitted nothing for a dispatch');
+    return captured;
+}
+/**
+ * The channel over the realtime service's HTTP API:
+ * - `POST {url}/api/emit` delivers the request to the turn's room;
+ * - `GET {url}/internal/oui/action-results/{requestId}?userId=&waitMs=` waits
+ *   for the answer (200 with the result, 204 when none arrived in `waitMs`);
+ *   with `&final=1`, for the final answer of an async action.
+ */
+export function createHttpUIActionChannel(config) {
+    const { url, apiKey } = config;
+    requireRealtime(url, apiKey);
+    const maxPollMs = config.maxPollMs ?? 20_000;
+    const dispatchTimeoutMs = config.dispatchTimeoutMs ?? 5_000;
+    const receiptTimeoutMs = config.receiptTimeoutMs ?? 1_500;
+    return {
+        async dispatch(room, request) {
+            const { event, data } = ouiDispatchEvent(request);
+            const res = await fetch(`${url}/api/emit`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'X-Api-Key': apiKey },
+                body: JSON.stringify({
+                    event,
+                    data,
+                    rooms: [room],
+                    ...(receiptTimeoutMs > 0 ? { ackTimeoutMs: receiptTimeoutMs } : {}),
+                }),
+                signal: AbortSignal.timeout(dispatchTimeoutMs + receiptTimeoutMs),
+            });
+            if (!res.ok) {
+                throw new Error(`[agent-sdk] Delivering UI action ${request.actionId} failed: HTTP ${res.status}`);
+            }
+            return receiptsOf(await res.json().catch(() => null));
+        },
+        awaitResult(requestId, { userId, timeoutMs, signal, final }) {
+            return longPoll({
+                url: (waitMs) => {
+                    const query = new URLSearchParams({ userId, waitMs: String(waitMs), ...(final ? { final: '1' } : {}) });
+                    return `${url}/internal/oui/action-results/${encodeURIComponent(requestId)}?${query}`;
+                },
+                apiKey,
+                timeoutMs,
+                maxPollMs,
+                ...(signal ? { signal } : {}),
+                describe: `the result of UI action ${requestId}`,
+            });
+        },
+    };
+}
+/** The receipts in an emit's response, or null when the realtime service reported none. */
+function receiptsOf(body) {
+    const receipts = body?.receipts;
+    if (!receipts || typeof receipts.acknowledged !== 'number' || typeof receipts.accepted !== 'number')
+        return null;
+    return { acknowledged: receipts.acknowledged, accepted: receipts.accepted };
+}
+//# sourceMappingURL=channel.js.map

package/dist/ui/channel.js.map

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

package/dist/ui/knowledge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The client's knowledge, carried on the turn.
+ *
+ * A UI client's generator emits knowledge from the same code declarations as
+ * its surfaces (ADR-0220, ADR-0226): the app's map, each page in full, how its
+ * parts relate, and the recipes its controls imply. The tab resolves it for the
+ * page the user is on (oui-bindings' `resolveKnowledge`) and sends it with the
+ * turn under `uiKnowledge`, beside its surface snapshot under `oui`.
+ *
+ * The worker renders it into the system prompt after the host's own prompt, for
+ * every host: a persona or a `systemPrompt` callback never sees it as context
+ * and never has to render it.
+ */
+import type { ResolvedKnowledge } from '@ouispec/bindings';
+/** The context key a UI client uses for its knowledge. */
+export declare const CLIENT_KNOWLEDGE_KEY = "uiKnowledge";
+/** What a UI client sends: the knowledge for the page the user is on. */
+export type ClientKnowledge = ResolvedKnowledge;
+/**
+ * Read and validate the knowledge from a turn's context. Returns null when the
+ * turn carries none (a client with no UI), and throws when it carries knowledge
+ * that is malformed: a broken payload is a client bug that must not quietly
+ * become "this client knows nothing".
+ */
+export declare function readClientKnowledge(context: Record<string, unknown> | null | undefined): ClientKnowledge | null;
+/** The knowledge as a prompt section: every entry, then every workflow with its numbered steps. */
+export declare function renderClientKnowledge(knowledge: ClientKnowledge): string;
+/** The host's system prompt, followed by the knowledge the turn's client sent, if any. */
+export declare function withClientKnowledge(systemPrompt: string, context: Record<string, unknown> | null | undefined): string;
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/ui/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/ui/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAe/G;AAED,mGAAmG;AACnG,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAgBxE;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIrH"}

package/dist/ui/knowledge.js

@@ -0,0 +1,66 @@
+/** The context key a UI client uses for its knowledge. */
+export const CLIENT_KNOWLEDGE_KEY = 'uiKnowledge';
+/**
+ * Read and validate the knowledge from a turn's context. Returns null when the
+ * turn carries none (a client with no UI), and throws when it carries knowledge
+ * that is malformed: a broken payload is a client bug that must not quietly
+ * become "this client knows nothing".
+ */
+export function readClientKnowledge(context) {
+    const raw = context?.[CLIENT_KNOWLEDGE_KEY];
+    if (raw === undefined || raw === null)
+        return null;
+    const where = `context.${CLIENT_KNOWLEDGE_KEY}`;
+    if (typeof raw !== 'object')
+        throw new Error(`[agent-sdk] ${where} must be an object`);
+    const { entries, workflows } = raw;
+    if (!Array.isArray(entries))
+        throw new Error(`[agent-sdk] ${where}.entries must be an array`);
+    if (!Array.isArray(workflows))
+        throw new Error(`[agent-sdk] ${where}.workflows must be an array`);
+    entries.forEach((e, i) => {
+        if (!isEntry(e))
+            throw new Error(`[agent-sdk] ${where}.entries[${i}] is not a knowledge entry (title, content)`);
+    });
+    workflows.forEach((w, i) => {
+        if (!isWorkflow(w))
+            throw new Error(`[agent-sdk] ${where}.workflows[${i}] is not a workflow (name, trigger, steps[])`);
+    });
+    return { entries, workflows };
+}
+/** The knowledge as a prompt section: every entry, then every workflow with its numbered steps. */
+export function renderClientKnowledge(knowledge) {
+    const sections = [];
+    if (knowledge.entries.length > 0) {
+        sections.push('## Platform Knowledge (Context-Aware)\n\n' + knowledge.entries.map((e) => `### ${e.title}\n${e.content}`).join('\n\n'));
+    }
+    if (knowledge.workflows.length > 0) {
+        sections.push('## Active Workflows\n\n' +
+            knowledge.workflows
+                .map((w) => `### ${w.name}\nTrigger: ${w.trigger}\nSteps:\n${w.steps.map((s, i) => `${i + 1}. ${s}`).join('\n')}`)
+                .join('\n\n'));
+    }
+    return sections.join('\n\n');
+}
+/** The host's system prompt, followed by the knowledge the turn's client sent, if any. */
+export function withClientKnowledge(systemPrompt, context) {
+    const knowledge = readClientKnowledge(context);
+    const rendered = knowledge ? renderClientKnowledge(knowledge) : '';
+    return rendered ? `${systemPrompt}\n\n${rendered}` : systemPrompt;
+}
+function isEntry(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const e = value;
+    return typeof e.title === 'string' && typeof e.content === 'string';
+}
+function isWorkflow(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const w = value;
+    return (typeof w.name === 'string' &&
+        typeof w.trigger === 'string' &&
+        Array.isArray(w.steps) &&
+        w.steps.every((s) => typeof s === 'string'));
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/ui/knowledge.js.map

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

package/dist/ui/observations.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Page state within the model's budget, problems first (ADR-0167).
+ *
+ * A surface may publish a `problems` observation: what its page cannot draw,
+ * load or read — a face it does not have and the text it therefore hides, an
+ * asset that failed, what an import could not reproduce. Those are exactly
+ * what the model must not miss before it tells the user a result, so when the
+ * page state is over budget they are kept whole and only the rest is cut. So
+ * are the statuses of the jobs the page follows: whether what an action
+ * started has finished is how the model knows it may say so.
+ */
+import type { OUIObservationSnapshot } from 'oui-spec/spec';
+/** The observation id a surface reports its page's problems under. */
+export declare const PROBLEMS_OBSERVATION_ID = "problems";
+/** Every surface's non-empty `problems`, by surface id; null when none reports any. */
+export declare function surfaceProblems(observations: OUIObservationSnapshot): Record<string, unknown> | null;
+/**
+ * Every job an action started that the page is following: each surface's
+ * `<surface>:<action>:status` observations (started, running, complete with
+ * what it made, failed with why), by surface id; null when there are none.
+ * The model is told an action like Generate is done only through these, so
+ * they must reach it whatever else the page reports.
+ */
+export declare function jobStatuses(observations: OUIObservationSnapshot): Record<string, Record<string, unknown>> | null;
+/** Rows past this in any list are summed up as "… and N more" at the first step of fitting an over-budget page state. */
+export declare const MAX_LIST_ROWS = 20;
+/**
+ * A list this short is never shortened: it is a field's choices (the engines a
+ * voice can speak with, a document's types), not a collection to browse.
+ */
+export declare const WHOLE_LIST_ROWS = 5;
+/**
+ * The observations as the model receives them: whole when they fit. Over
+ * budget, every surface's problems and job statuses are kept whole; the rest is
+ * fitted (see fitted): long lists shortened first, the page it acted on first
+ * and kept whole, and only if that still does not fit is the rest cut, saying so.
+ */
+export declare function boundObservations(observations: OUIObservationSnapshot, maxChars: number, actingSurfaceId?: string): unknown;
+/** The same, as the text of a `<page_state>` block. */
+export declare function observationsText(observations: OUIObservationSnapshot, maxChars: number): string;
+//# sourceMappingURL=observations.d.ts.map

package/dist/ui/observations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observations.d.ts","sourceRoot":"","sources":["../../src/ui/observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE5D,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,aAAa,CAAC;AAElD,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,YAAY,EAAE,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CASpG;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAShH;AAgBD,yHAAyH;AACzH,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAgKjC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,sBAAsB,EACpC,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAcT;AAED,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,sBAAsB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAc/F"}