@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/kernel/tools/gate-answer.d.ts

@@ -1,13 +1,16 @@
 import type { ApiKeyCredential, BearerCredential } from '../auth/types.js';
 import type { ToolPermission } from '../schema.js';
 import type { ToolAuthChallenge } from '../turn-events.js';
-import type { InvokeToolResume } from './types.js';
+import type { InvokeToolResume, PageAnswer } from './types.js';
 /** What a sign-in gate asks for, minus the challenge's OAuth details. */
 export type ToolGateAuth = Pick<ToolAuthChallenge, 'slot' | 'authType' | 'service'>;
 /** A bad value is refused when `owner` is built, not when a gate expires. */
 export declare function resolveGateTtlMs(owner: string, gateTtlMs: number | undefined): number;
+/** True when the gate has waited as long as its time limit. */
 export declare function gateExpired(createdAt: number, now: number, ttlMs: number): boolean;
+/** How a user can answer a tool gate: approve it, deny it, or walk away. */
 export declare const GATE_DECISIONS: readonly ["approve", "deny", "abandon"];
+/** One of {@linkcode GATE_DECISIONS}. */
 export type GateDecision = (typeof GATE_DECISIONS)[number];
 /** `edited.from` is the input the model proposed. */
 export type GateAnswer = {
@@ -18,10 +21,11 @@ export type GateAnswer = {
 } | {
     decision: 'deny' | 'abandon';
 };
-/** `signIn` when the gate answered is a sign-in, so a refusal tells the model so. */
+/** `signIn` when the gate answered is a sign-in, so the model is told the person signed in or why not. */
 export declare function resumeForAnswer(answer: GateAnswer, signIn?: boolean): InvokeToolResume;
 /** Only a `session_consent` approval lasts the session; any other gate is approved for this call only. */
 export declare function sessionPermissionsAfterApproval(sessionPermissions: readonly string[], toolName: string, permission?: ToolPermission): string[];
+/** The user's answer to a held tool call. */
 export type GateAnswerRequest = {
     callId: string;
     decision: GateDecision;
@@ -29,14 +33,19 @@ export type GateAnswerRequest = {
     input?: unknown;
     /** The key typed at a sign-in gate; approvals only. */
     secret?: string;
+    /** The page's answer at a `page` gate; approvals only. */
+    page?: PageAnswer;
 };
+/** A tool call held at a gate, with what answering it needs. */
 export type HeldGatedCall = {
+    gateKind?: import('../schema.js').ToolGateKind;
     name: string;
     arguments: Record<string, unknown>;
     permission?: ToolPermission;
     /** Absent on any gate other than sign-in. */
     auth?: ToolGateAuth;
 };
+/** A tool call's gate once answered: how the call resumes and the permissions after. */
 export type AnsweredGate = {
     resume: InvokeToolResume;
     input: unknown;
@@ -45,6 +54,7 @@ export type AnsweredGate = {
         slot: string;
         credential: BearerCredential | ApiKeyCredential;
     };
+    page?: PageAnswer;
 };
 /** Shared by `createTheoremHandler` and `runSession`. A refused key throws, so the gate keeps waiting for another. */
 export declare function answerGatedCall(request: GateAnswerRequest, call: HeldGatedCall, sessionPermissions: readonly string[]): AnsweredGate;

package/esm/src/kernel/tools/gate-answer.js

@@ -9,14 +9,20 @@ export function resolveGateTtlMs(owner, gateTtlMs) {
     }
     return ttl;
 }
+/** True when the gate has waited as long as its time limit. */
 export function gateExpired(createdAt, now, ttlMs) {
     return now - createdAt >= ttlMs;
 }
+/** How a user can answer a tool gate: approve it, deny it, or walk away. */
 export const GATE_DECISIONS = ['approve', 'deny', 'abandon'];
-/** `signIn` when the gate answered is a sign-in, so a refusal tells the model so. */
+/** `signIn` when the gate answered is a sign-in, so the model is told the person signed in or why not. */
 export function resumeForAnswer(answer, signIn = false) {
     if (answer.decision === 'approve') {
-        return answer.edited ? { granted: true, edited: answer.edited } : { granted: true };
+        return {
+            granted: true,
+            ...(answer.edited ? { edited: answer.edited } : {}),
+            ...(signIn ? { signIn } : {}),
+        };
     }
     return {
         granted: false,
@@ -33,9 +39,10 @@ export function sessionPermissionsAfterApproval(sessionPermissions, toolName, pe
 }
 /** Shared by `createTheoremHandler` and `runSession`. A refused key throws, so the gate keeps waiting for another. */
 export function answerGatedCall(request, call, sessionPermissions) {
-    const { callId, decision, input, secret } = request;
-    if ((input !== undefined || secret !== undefined) && decision !== 'approve') {
-        throw new TheoremError('request', `only an approval takes edited input or a secret (call ${callId})`);
+    const { callId, decision, input, secret, page } = request;
+    const approvalOnly = input !== undefined || secret !== undefined || page !== undefined;
+    if (approvalOnly && decision !== 'approve') {
+        throw new TheoremError('request', `only an approval takes edited input, a secret, or a page answer (call ${callId})`);
     }
     if (decision !== 'approve') {
         return {
@@ -46,9 +53,13 @@ export function answerGatedCall(request, call, sessionPermissions) {
     }
     const typed = secret === undefined ? undefined : credentialForSignInGate(call.auth, secret);
     return {
-        resume: resumeForAnswer(input === undefined ? { decision } : { decision, edited: { from: call.arguments } }),
+        resume: {
+            ...resumeForAnswer(input === undefined ? { decision } : { decision, edited: { from: call.arguments } }, call.auth !== undefined),
+            ...(call.gateKind ? { gateKind: call.gateKind } : {}),
+        },
         input: input ?? call.arguments,
         sessionPermissions: sessionPermissionsAfterApproval(sessionPermissions, call.name, call.permission),
         ...(typed ? { typed } : {}),
+        ...(page ? { page } : {}),
     };
 }

package/esm/src/kernel/tools/handler-events.d.ts

@@ -0,0 +1,45 @@
+import type { ToolBoundary } from '../../guardrails/boundaries.js';
+import type { Provenance, ResolvedGuardrailPolicy } from '../../guardrails/types.js';
+import type { TurnEvent } from '../types.js';
+import { type ToolCallBase } from './events.js';
+import type { ToolStreamEvent } from './types.js';
+/** A handler's event as the tool phase it is, unchecked. */
+export declare function yieldHandlerSideEvent(base: ToolCallBase, event: Exclude<ToolStreamEvent, {
+    kind: 'complete';
+}>): Generator<TurnEvent>;
+/** What a handler's events are read against: what its output is read against at the end. */
+export interface HandlerEventChecks {
+    profileId: string;
+    provenance: Provenance;
+    policy: ResolvedGuardrailPolicy;
+    /** `tool_output_<kind>`. */
+    boundary: ToolBoundary;
+    /** `tool_shown_<kind>`: what its artifacts and trace are read at. */
+    shown: ToolBoundary;
+    callableTools: readonly string[];
+    /** Whether the host sees the handler's drafts (`outputs.streaming.mode` `sse`). */
+    drafts: boolean;
+}
+/**
+ * A handler's events before its output, as the host may see them; an HTTP tool's body as it arrives
+ * comes through here as drafts too. Its `progress` is read whole at
+ * the output's boundary: one a check stops is not sent, and its guardrail event is. Its drafts are
+ * read piece by piece there, as one text: a match stops the rest of them, and the output's own
+ * check reports it.
+ */
+export declare class HandlerEvents {
+    private readonly base;
+    private readonly checks;
+    private readonly drafts;
+    constructor(base: ToolCallBase, checks: HandlerEventChecks | undefined);
+    show(event: Exclude<ToolStreamEvent, {
+        kind: 'complete';
+    }>): AsyncGenerator<TurnEvent>;
+    /** The drafts' tail the gate still holds, once the handler has returned. */
+    end(): Generator<TurnEvent>;
+    private draft;
+    /** `value` as the person is shown it, read at `tool_shown_<kind>`; one a match blocks is not sent. */
+    private shown;
+    /** Whether a check at the output's boundary stops `data`; a flag lets it through unreported. */
+    private progressStops;
+}

package/esm/src/kernel/tools/handler-events.js

@@ -0,0 +1,106 @@
+import { createDraftGate, DraftReader, } from '../../guardrails/progressive-yield.js';
+import { guardShownValue, guardToolResult } from '../../guardrails/tool-result.js';
+import { toolEvent } from './events.js';
+/** A handler's event as the tool phase it is, unchecked. */
+export function* yieldHandlerSideEvent(base, event) {
+    if (event.kind === 'progress') {
+        yield toolEvent(base, { phase: 'progress', data: event.data });
+    }
+    else if (event.kind === 'draft') {
+        yield toolEvent(base, { phase: 'draft', text: event.text });
+    }
+    else if (event.kind === 'trace') {
+        yield toolEvent(base, { phase: 'trace', step: event.step });
+    }
+    else if (event.kind === 'artifact') {
+        yield toolEvent(base, { phase: 'artifact', artifact: event.artifact });
+    }
+    else if (event.kind === 'warning') {
+        yield toolEvent(base, { phase: 'warning', warning: event.warning });
+    }
+}
+/**
+ * A handler's events before its output, as the host may see them; an HTTP tool's body as it arrives
+ * comes through here as drafts too. Its `progress` is read whole at
+ * the output's boundary: one a check stops is not sent, and its guardrail event is. Its drafts are
+ * read piece by piece there, as one text: a match stops the rest of them, and the output's own
+ * check reports it.
+ */
+export class HandlerEvents {
+    base;
+    checks;
+    drafts;
+    constructor(base, checks) {
+        this.base = base;
+        this.checks = checks;
+        if (checks?.drafts)
+            this.drafts = new DraftReader(() => draftGate(checks));
+    }
+    async *show(event) {
+        if (event.kind === 'draft') {
+            yield* this.draft(event.text);
+            return;
+        }
+        if (event.kind === 'progress' && (yield* this.progressStops(event.data)))
+            return;
+        if (event.kind === 'artifact') {
+            const artifact = yield* this.shown(event.artifact);
+            if (artifact.shown)
+                yield* yieldHandlerSideEvent(this.base, { ...event, artifact: artifact.value });
+            return;
+        }
+        if (event.kind === 'trace') {
+            const step = yield* this.shown(event.step);
+            if (step.shown) {
+                yield* yieldHandlerSideEvent(this.base, {
+                    ...event,
+                    step: step.value,
+                });
+            }
+            return;
+        }
+        yield* yieldHandlerSideEvent(this.base, event);
+    }
+    /** The drafts' tail the gate still holds, once the handler has returned. */
+    *end() {
+        const text = this.drafts?.end();
+        if (text)
+            yield toolEvent(this.base, { phase: 'draft', text });
+    }
+    async *draft(piece) {
+        const text = await this.drafts?.read(piece);
+        if (text)
+            yield toolEvent(this.base, { phase: 'draft', text });
+    }
+    /** `value` as the person is shown it, read at `tool_shown_<kind>`; one a match blocks is not sent. */
+    *shown(value) {
+        const checks = this.checks;
+        if (!checks)
+            return { shown: true, value };
+        const read = guardShownValue(value, checks.provenance, checks.policy, checks.shown);
+        if (read.event)
+            yield { type: 'guardrail', guardrail: read.event };
+        return 'value' in read ? { shown: true, value: read.value } : { shown: false };
+    }
+    /** Whether a check at the output's boundary stops `data`; a flag lets it through unreported. */
+    *progressStops(data) {
+        const checks = this.checks;
+        if (!checks)
+            return false;
+        const { event, text } = guardToolResult('', data, checks.provenance, checks.policy, checks.boundary, checks.callableTools);
+        if (text !== undefined && (event === undefined || event.action === 'flag'))
+            return false;
+        if (event)
+            yield { type: 'guardrail', guardrail: event };
+        return true;
+    }
+}
+/** The gate a handler's drafts are read through, at the output's boundary. */
+function draftGate(checks) {
+    return createDraftGate(checks.policy, {
+        stage: 'tool_result',
+        trust: 'untrusted',
+        profileId: checks.profileId,
+        provenance: checks.provenance,
+    }, checks.boundary, { callable: checks.callableTools });
+}

package/esm/src/kernel/tools/harness.d.ts

@@ -11,6 +11,7 @@ type AskOutput = AskInput & {
 };
 /** A scope of its own registers it with `tools.register`. */
 declare const askUserTool: ToolDefinitionInput<AskInput, AskOutput>;
+/** Registers the harness tools, currently `askUserTool`, in the default registry. */
 declare function registerHarnessTools(): void;
 export type { AskInput, AskKind, AskOutput };
 export { askUserTool, registerHarnessTools };

package/esm/src/kernel/tools/harness.js

@@ -16,7 +16,7 @@ const AskOutputSchema = z.object({
 const askUserTool = {
     type: 'function',
     name: 'ask_user',
-    description: 'Ask the user a question (completes with awaiting_user_input)', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    description: 'Ask the user a question (completes with awaiting_user_input)', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     category: 'conversation',
     access: 'read-only',
     paths: ['*'],
@@ -36,6 +36,7 @@ const askUserTool = {
         return out;
     },
 };
+/** Registers the harness tools, currently `askUserTool`, in the default registry. */
 function registerHarnessTools() {
     registerTool(askUserTool);
 }

package/esm/src/kernel/tools/http-limit.d.ts

@@ -0,0 +1,27 @@
+import { type Wait } from '../../providers/shared/retry.js';
+import type { HttpToolLimit } from './types.js';
+/** Time as the limit reads it; a test passes its own. */
+export interface LimitClock {
+    now: () => number;
+    wait: Wait;
+}
+/** A place taken for one request. `answered` gives the service's reply, or nothing when the send threw. */
+export interface LimitPlace {
+    answered: (response?: Response) => void;
+}
+/** No place opens within a call's wait budget: when the next one opens, or `undefined` while every request is unanswered. */
+export interface LimitFull {
+    full: true;
+    limit: HttpToolLimit;
+    opensInMs: number | undefined;
+}
+/**
+ * Takes a place in the tool's window for one request. A request holds its place from send
+ * until a window after its answer, so requests the network delivers unevenly still land
+ * within the limit. A 429 with `Retry-After` holds every request of the tool until then.
+ * A call waits for a place at most the same five seconds a retry may wait; past that it
+ * gets `LimitFull` and sends nothing. A call is one place, its retries and redirects included.
+ */
+export declare function takeLimitPlace(tool: object, limit: HttpToolLimit, signal?: AbortSignal | null, clock?: LimitClock): Promise<LimitPlace | LimitFull>;
+/** The request sent in a place; its answer, or its failure, frees the place. */
+export declare function answeredIn(place: LimitPlace | undefined, sending: Promise<Response>): Promise<Response>;

package/esm/src/kernel/tools/http-limit.js

@@ -0,0 +1,85 @@
+import { retryAfterMs, WAIT_BUDGET_MS, waitDefault, } from '../../providers/shared/retry.js';
+const SYSTEM_CLOCK = { now: Date.now, wait: waitDefault };
+/** Keyed by the registered tool, so a scope's tool has its own window and nothing is looked up by name. */
+const windows = new WeakMap();
+function windowOf(tool) {
+    const known = windows.get(tool);
+    if (known)
+        return known;
+    const fresh = { places: [], heldUntil: 0, waiting: new Set() };
+    windows.set(tool, fresh);
+    return fresh;
+}
+/** The first moment a place is free, `Infinity` while every place's request is unanswered. */
+function nextOpening(window, limit, now) {
+    window.places = window.places.filter((place) => place.opensAt > now);
+    const freeAt = window.places.length < limit.requests
+        ? now
+        : Math.min(...window.places.map((place) => place.opensAt));
+    return Math.max(freeAt, window.heldUntil);
+}
+/** Returns when a place frees early (an answer) or the wait ends; the caller's abort rejects. */
+async function waitForChange(window, ms, signal, clock) {
+    const changed = new AbortController();
+    const wake = () => changed.abort();
+    window.waiting.add(wake);
+    try {
+        await clock.wait(ms, signal ? AbortSignal.any([signal, changed.signal]) : changed.signal);
+    }
+    catch (err) {
+        if (signal?.aborted || !changed.signal.aborted)
+            throw err;
+    }
+    finally {
+        window.waiting.delete(wake);
+    }
+}
+/**
+ * Takes a place in the tool's window for one request. A request holds its place from send
+ * until a window after its answer, so requests the network delivers unevenly still land
+ * within the limit. A 429 with `Retry-After` holds every request of the tool until then.
+ * A call waits for a place at most the same five seconds a retry may wait; past that it
+ * gets `LimitFull` and sends nothing. A call is one place, its retries and redirects included.
+ */
+export async function takeLimitPlace(tool, limit, signal, clock = SYSTEM_CLOCK) {
+    const window = windowOf(tool);
+    const deadline = clock.now() + WAIT_BUDGET_MS;
+    for (;;) {
+        const now = clock.now();
+        const opening = nextOpening(window, limit, now);
+        if (opening <= now) {
+            const place = { opensAt: Number.POSITIVE_INFINITY };
+            window.places.push(place);
+            return {
+                answered: (response) => {
+                    const at = clock.now();
+                    place.opensAt = at + limit.windowMs;
+                    const after = response?.status === 429 ? retryAfterMs(response.headers, at) : undefined;
+                    if (after !== undefined) {
+                        window.heldUntil = Math.max(window.heldUntil, at + after);
+                    }
+                    for (const wake of window.waiting)
+                        wake();
+                },
+            };
+        }
+        if (opening > deadline && opening !== Number.POSITIVE_INFINITY) {
+            return { full: true, limit, opensInMs: opening - now };
+        }
+        if (now >= deadline)
+            return { full: true, limit, opensInMs: undefined };
+        await waitForChange(window, Math.min(opening, deadline) - now, signal, clock);
+    }
+}
+/** The request sent in a place; its answer, or its failure, frees the place. */
+export async function answeredIn(place, sending) {
+    try {
+        const response = await sending;
+        place?.answered(response);
+        return response;
+    }
+    catch (err) {
+        place?.answered();
+        throw err;
+    }
+}

package/esm/src/kernel/tools/invoke.d.ts

@@ -1,10 +1,32 @@
 import type { TraceSink } from '../../observability/trace-sink.js';
 import type { KernelRegistry } from '../registry/kernel-registry.js';
 import type { TurnEvent } from '../types.js';
-import type { InvokeToolRequest } from './types.js';
+import type { InvokeToolRequest, InvokeToolStepRequest } from './types.js';
+/** A call's name and the id it goes by, known before any of its events. */
+export interface StartedCall {
+    name: string;
+    callId: string;
+}
+/** A started invoke: its call and its events. */
+export interface StartedInvoke extends StartedCall {
+    events: AsyncGenerator<TurnEvent>;
+}
+declare function invokeTool(registry: KernelRegistry, request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+declare function startInvoke(registry: KernelRegistry, request: InvokeToolRequest, sinkOverride?: TraceSink): StartedInvoke;
 /**
- * The trace record is written however the call ends, including an early stop or a failure before
- * the tool. An unknown profile is recorded under the standard observability policy: there is none to read.
+ * Runs the host's calls as one step, the way a turn runs the model's. Every call the step names
+ * itself is announced with the step's id before any runs. With `tools.parallel` they run side by
+ * side, otherwise one at a time in the order given; a call whose `pre_tool` answers `waitFor`
+ * starts once those calls in the step settle. Each call's events arrive as it gives them, and its
+ * terminal `tool` event says it settled. The calls share one snapshot. A call that gates waits for
+ * its own approval while the others run; the step then ends `gate`. One trace record holds a span
+ * per call under the step's root, rooted under the host span when one is given.
  */
-declare function invokeTool(registry: KernelRegistry, request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
-export { invokeTool };
+declare function invokeToolStep(registry: KernelRegistry, request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/** A started step: its calls in the order given, and the step's events. */
+export interface StartedStep {
+    calls: StartedCall[];
+    events: AsyncGenerator<TurnEvent>;
+}
+declare function startInvokeStep(registry: KernelRegistry, request: InvokeToolStepRequest, sinkOverride?: TraceSink): StartedStep;
+export { invokeTool, invokeToolStep, startInvoke, startInvokeStep };