@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/kernel/stop.js

@@ -0,0 +1,125 @@
+import { CONTINUE_STOP_KINDS } from './schema.js';
+/**
+ * Profile types whose continue turn sends the continue instruction. Image and
+ * speech continue by re-sending the host's request unchanged.
+ */
+export const CONTINUE_INSTRUCTION_TYPES = ['text'];
+export const DEFAULT_ALLOW_CONTINUE = CONTINUE_STOP_KINDS;
+/** Hosts wait briefly, then continue once on their own. */
+export const DEFAULT_AUTO_CONTINUE = ['length', 'stream_incomplete'];
+/** Pause before the one-shot auto-continue so a flaky tunnel can settle. */
+export const AUTO_CONTINUE_DELAY_MS = 1_500;
+const CONTINUE_KIND_SET = new Set(CONTINUE_STOP_KINDS);
+export function isContinueStopKind(kind) {
+    return CONTINUE_KIND_SET.has(kind);
+}
+const RESUMEABLE_DEFAULT = new Set(DEFAULT_ALLOW_CONTINUE);
+export function isResumeableStop(stop, allowContinue) {
+    if (!stop)
+        return false;
+    if (!isContinueStopKind(stop.kind))
+        return false;
+    const allow = allowContinue ? new Set(allowContinue) : RESUMEABLE_DEFAULT;
+    return allow.has(stop.kind);
+}
+export function stageAbortStop(abort) {
+    return typeof abort === 'object' && abort.reason
+        ? { kind: 'cancelled', native: abort.reason }
+        : { kind: 'cancelled' };
+}
+export function isUserCancelledStop(stop) {
+    return stop?.kind === 'cancelled';
+}
+/** `policy` is the profile's `profileTurnResumption(profile)`. */
+export function shouldAutoContinue(stop, policy) {
+    if (!stop || !isContinueStopKind(stop.kind))
+        return false;
+    const auto = policy?.autoContinue ?? DEFAULT_AUTO_CONTINUE;
+    return auto.includes(stop.kind) && isResumeableStop(stop, policy?.allowContinue);
+}
+export function profileTurnResumption(profile) {
+    if (profile.type === 'live')
+        return undefined;
+    return profile.turnBehaviour?.resumption;
+}
+/** Text-only, for the interface `allowSteering` projection; `profileAllowsInject` adds live. */
+export function profileAllowsSteering(profile) {
+    if (profile.type !== 'text')
+        return false;
+    return profile.turnBehaviour?.allowSteering !== false;
+}
+/** Gates injects only, never stage emission. */
+export function profileAllowsInject(profile) {
+    if (profile.type === 'text' || profile.type === 'live') {
+        return profile.turnBehaviour?.allowSteering !== false;
+    }
+    return false;
+}
+/** OpenAI-compatible normalized `finish_reason` (+ optional `native_finish_reason`). */
+export function turnStopFromOpenAiFinishReason(finishReason, nativeFinishReason) {
+    const native = nativeFinishReason?.trim() || finishReason?.trim() || undefined;
+    const effective = (nativeFinishReason || finishReason || '').toLowerCase();
+    if (!effective)
+        return { kind: 'stream_incomplete', native };
+    if (effective === 'network_error' || effective.includes('network')) {
+        return { kind: 'provider_error', native };
+    }
+    return openAiFinishKind((finishReason || '').toLowerCase(), effective, native);
+}
+function openAiFinishKind(finish, effective, native) {
+    if (finish === 'stop') {
+        return /error|fail/.test(effective)
+            ? { kind: 'provider_error', native }
+            : { kind: 'completed', native };
+    }
+    if (finish === 'length')
+        return { kind: 'length', native };
+    if (finish === 'tool_calls' || finish === 'tool-calls')
+        return { kind: 'tool', native };
+    if (finish === 'content_filter' || finish === 'content-filter') {
+        return { kind: 'filtered', native };
+    }
+    return { kind: 'provider_error', native };
+}
+/** Gemini Interactions terminal `status`. */
+export function turnStopFromInteractionStatus(status) {
+    const s = (status || '').toLowerCase();
+    const native = status || undefined;
+    switch (s) {
+        case 'completed':
+            return { kind: 'completed', native };
+        case 'incomplete':
+        case 'budget_exceeded':
+            return { kind: 'length', native };
+        case 'requires_action':
+            return { kind: 'tool', native };
+        case 'cancelled':
+            return { kind: 'cancelled', native };
+        case 'failed':
+            return { kind: 'provider_error', native };
+        case 'in_progress':
+        case 'queued':
+            return { kind: 'stream_incomplete', native };
+        default:
+            return { kind: 'stream_incomplete', native };
+    }
+}
+/** `null` when `sawTerminal`, so the host keeps the provider's stop. */
+export function turnStopFromClientStreamEnd(opts) {
+    if (opts.sawTerminal)
+        return null;
+    if (opts.abortedByUser)
+        return { kind: 'cancelled' };
+    return { kind: 'stream_incomplete' };
+}
+export class GenerationStopError extends Error {
+    name = 'GenerationStopError';
+    stop;
+    constructor(stop, message) {
+        super(message || `Generation stopped: ${stop.kind}`);
+        this.stop = stop;
+    }
+}
+export function isGenerationStopError(err) {
+    return err instanceof GenerationStopError;
+}

package/esm/src/kernel/system-parts.d.ts

@@ -0,0 +1,26 @@
+import type { SystemPiece, SystemPrompt } from './types.js';
+/** The system prompt as sent, and the private stretches of it no reply may repeat. */
+interface BoundSystem {
+    text: string;
+    private: readonly string[];
+}
+/** What is wrong with `prompt` as a system prompt, `where` naming it, or undefined. */
+declare function systemPromptProblem(prompt: unknown, where: string): string | undefined;
+/** `where` names the prompt in the error, e.g. `Profile sol identity.system`. */
+declare function assertSystemPrompt(prompt: unknown, where: string): asserts prompt is SystemPrompt;
+/** Rewrites each part's text with `rewrite`, keeping its mark. */
+declare function mapSystemPrompt(prompt: SystemPrompt, where: string, rewrite: (text: string) => string): SystemPrompt;
+/** One prompt's pieces: all private unless some part is `{ private }`. */
+declare function systemPieces(prompt: SystemPrompt): SystemPiece[];
+/** Joins prompts from different sources a blank line apart, leaving out empty ones. */
+declare function joinSystemPieces(sources: readonly (readonly SystemPiece[])[]): SystemPiece[];
+declare function systemText(pieces: readonly SystemPiece[]): string;
+/**
+ * The wire text and its private stretches: private pieces next to each other
+ * read as one stretch, since a reply repeating across them repeats private text.
+ */
+declare function boundSystem(pieces: readonly SystemPiece[]): BoundSystem;
+/** `pieces` with Theorem's notes after them, each note private whatever the host marked. */
+declare function bindSystem(pieces: readonly SystemPiece[], notes: readonly string[]): BoundSystem;
+export type { BoundSystem };
+export { assertSystemPrompt, bindSystem, boundSystem, joinSystemPieces, mapSystemPrompt, systemPieces, systemPromptProblem, systemText, };

package/esm/src/kernel/system-parts.js

@@ -0,0 +1,98 @@
+import { TheoremError } from '../guardrails/error.js';
+const SOURCE_SEPARATOR = '\n\n';
+function partProblem(part) {
+    if (typeof part === 'string')
+        return undefined;
+    if (typeof part !== 'object' || part === null || Array.isArray(part)) {
+        return 'must be a string or { private: string }'; // lexicon-exempt: developer contract error
+    }
+    const keys = Object.keys(part);
+    if (keys.length !== 1 || keys[0] !== 'private') {
+        return 'must have exactly one key, private'; // lexicon-exempt: developer contract error
+    }
+    const text = part.private;
+    if (typeof text !== 'string')
+        return 'must be a string'; // lexicon-exempt: developer contract error
+    if (text === '')
+        return 'must not be empty'; // lexicon-exempt: developer contract error
+    return undefined;
+}
+/** What is wrong with `prompt` as a system prompt, `where` naming it, or undefined. */
+function systemPromptProblem(prompt, where) {
+    if (typeof prompt === 'string')
+        return undefined;
+    if (!Array.isArray(prompt))
+        return `${where} must be a string or an array of parts`; // lexicon-exempt: developer contract error
+    if (prompt.length === 0)
+        return `${where} must not be an empty array`; // lexicon-exempt: developer contract error
+    for (const [at, part] of prompt.entries()) {
+        const problem = partProblem(part);
+        if (!problem)
+            continue;
+        const path = typeof part === 'object' && part !== null && 'private' in part ? '.private' : '';
+        return `${where}[${at}]${path} ${problem}`;
+    }
+    return undefined;
+}
+/** `where` names the prompt in the error, e.g. `Profile sol identity.system`. */
+function assertSystemPrompt(prompt, where) {
+    const problem = systemPromptProblem(prompt, where);
+    if (problem)
+        throw new TheoremError('config', problem);
+}
+/** Rewrites each part's text with `rewrite`, keeping its mark. */
+function mapSystemPrompt(prompt, where, rewrite) {
+    assertSystemPrompt(prompt, where);
+    if (typeof prompt === 'string')
+        return rewrite(prompt);
+    return prompt.map((part) => typeof part === 'string' ? rewrite(part) : { private: rewrite(part.private) });
+}
+/** One prompt's pieces: all private unless some part is `{ private }`. */
+function systemPieces(prompt) {
+    if (typeof prompt === 'string')
+        return [{ text: prompt, private: true }];
+    const marked = prompt.some((part) => typeof part !== 'string');
+    return prompt.map((part) => typeof part === 'string'
+        ? { text: part, private: !marked }
+        : { text: part.private, private: true });
+}
+/** Joins prompts from different sources a blank line apart, leaving out empty ones. */
+function joinSystemPieces(sources) {
+    const joined = [];
+    for (const pieces of sources) {
+        if (!pieces.some((piece) => piece.text))
+            continue;
+        if (joined.length > 0)
+            joined.push({ text: SOURCE_SEPARATOR, private: true });
+        joined.push(...pieces);
+    }
+    return joined;
+}
+function systemText(pieces) {
+    return pieces.map((piece) => piece.text).join('');
+}
+/**
+ * The wire text and its private stretches: private pieces next to each other
+ * read as one stretch, since a reply repeating across them repeats private text.
+ */
+function boundSystem(pieces) {
+    const stretches = [];
+    let open = '';
+    for (const piece of pieces) {
+        if (piece.private) {
+            open += piece.text;
+            continue;
+        }
+        if (open.trim())
+            stretches.push(open);
+        open = '';
+    }
+    if (open.trim())
+        stretches.push(open);
+    return { text: systemText(pieces), private: stretches };
+}
+/** `pieces` with Theorem's notes after them, each note private whatever the host marked. */
+function bindSystem(pieces, notes) {
+    return boundSystem(joinSystemPieces([pieces, ...notes.map((text) => (text ? [{ text, private: true }] : []))]));
+}
+export { assertSystemPrompt, bindSystem, boundSystem, joinSystemPieces, mapSystemPrompt, systemPieces, systemPromptProblem, systemText, };

package/esm/src/kernel/tools/activity-label.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a placeholder
+ * with no value and no fallback leaves the whole label `undefined`, and the transcript names the tool.
+ */
+export declare function fillActivityLabel(template: string | undefined, values: {
+    input: unknown;
+    output?: unknown;
+}): string | undefined;
+/**
+ * Why a label can't fill from these JSON schemas, as a sentence for its author, or `undefined`
+ * when every placeholder can. Pass `output` for a Done label.
+ */
+export declare function activityLabelProblem(template: string, schemas: {
+    input: unknown;
+    output?: unknown;
+}): string | undefined;

package/esm/src/kernel/tools/activity-label.js

@@ -0,0 +1,209 @@
+import { isRecord } from '../util/record.js';
+const MAX_VALUE_CHARS = 40;
+const PLACEHOLDER = /\{\{?([^{}]*)\}\}?/g;
+// Control and bidi-override characters would let a tool's output restyle or reorder the label.
+const UNPRINTABLE = /[\p{Cc}\p{Cf}]/gu;
+const INDEX = /^-?\d+$/;
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+const NUMBER = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 });
+// Dates show the wall-clock time as the tool wrote it, not converted to the server's zone.
+const DAY = new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeZone: 'UTC' });
+const DAY_TIME = new Intl.DateTimeFormat(undefined, {
+    dateStyle: 'medium',
+    timeStyle: 'short',
+    timeZone: 'UTC',
+});
+function parsePlaceholder(raw) {
+    const bar = raw.indexOf('|');
+    if (bar < 0)
+        return { path: raw.trim() };
+    return { path: raw.slice(0, bar).trim(), fallback: raw.slice(bar + 1).trim() };
+}
+/** `input.x` and `output.x` read one side; a bare path reads the input, then the output. */
+function routes(path, sides) {
+    const keys = path.split('.');
+    const [head, ...rest] = keys;
+    if ((head === 'input' || head === 'output') && rest.length) {
+        return [{ side: head, keys: rest, prefixed: true }];
+    }
+    return sides.map((side) => ({ side, keys, prefixed: false }));
+}
+function valueAt(source, keys) {
+    let value = source;
+    for (const key of keys) {
+        if (Array.isArray(value)) {
+            if (key === 'length')
+                value = value.length;
+            else if (INDEX.test(key))
+                value = value.at(Number(key));
+            else
+                return undefined;
+        }
+        else if (isRecord(value) && Object.hasOwn(value, key))
+            value = value[key];
+        else
+            return undefined;
+    }
+    return value;
+}
+function dateText(text) {
+    const match = ISO_DATE.exec(text);
+    if (!match)
+        return undefined;
+    const [year = 0, month = 0, day = 0, hour = 0, minute = 0] = match
+        .slice(1)
+        .map((part) => Number(part ?? 0));
+    const at = new Date(Date.UTC(year, month - 1, day, hour, minute));
+    if (Number.isNaN(at.getTime()) || at.getUTCDate() !== day)
+        return undefined;
+    return (match[4] === undefined ? DAY : DAY_TIME).format(at);
+}
+function labelValue(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? NUMBER.format(value) : undefined;
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.replace(UNPRINTABLE, ' ').replace(/\s+/g, ' ').trim();
+    const chars = [...(dateText(text) ?? text)];
+    if (chars.length === 0)
+        return undefined;
+    if (chars.length <= MAX_VALUE_CHARS)
+        return chars.join('');
+    const head = chars.slice(0, MAX_VALUE_CHARS - 1).join('');
+    return `${head.trimEnd()}…`;
+}
+/**
+ * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a placeholder
+ * with no value and no fallback leaves the whole label `undefined`, and the transcript names the tool.
+ */
+export function fillActivityLabel(template, values) {
+    if (!template?.trim())
+        return undefined;
+    const sides = 'output' in values ? ['input', 'output'] : ['input'];
+    let missing = false;
+    const filled = template.replace(PLACEHOLDER, (_, raw) => {
+        const { path, fallback } = parsePlaceholder(raw);
+        const value = path
+            ? routes(path, sides)
+                .map((route) => labelValue(valueAt(values[route.side], route.keys)))
+                .find((text) => text !== undefined)
+            : undefined;
+        if (value === undefined && fallback === undefined)
+            missing = true;
+        return value ?? fallback ?? '';
+    });
+    const text = filled.replace(/\s+/g, ' ').trim();
+    return missing || !text ? undefined : text;
+}
+const HOLDS_RANK = ['value', 'group', 'flag', 'missing'];
+function schemaTypes(node) {
+    const types = Array.isArray(node.type) ? node.type : [node.type];
+    return types.filter((type) => typeof type === 'string' && type !== 'null');
+}
+function schemaBranches(node) {
+    return [node.anyOf, node.oneOf, node.allOf].flatMap((list) => Array.isArray(list) ? list.filter(isRecord) : []);
+}
+function mergeHolds(found) {
+    const holds = HOLDS_RANK.find((rank) => found.some((entry) => entry.holds === rank)) ?? 'missing';
+    const same = found.filter((entry) => entry.holds === holds);
+    return { holds, instead: same.flatMap((entry) => entry.instead ?? []) };
+}
+/** The paths under `node` a label can show, for suggestions. */
+function placeholdersAt(node, prefix) {
+    const at = (key) => (prefix ? `${prefix}.${key}` : key);
+    if (!isRecord(node))
+        return [];
+    const branches = schemaBranches(node);
+    if (branches.length)
+        return branches.flatMap((branch) => placeholdersAt(branch, prefix));
+    if (schemaTypes(node).includes('array'))
+        return leavesAt(node.items, at('0'));
+    if (!isRecord(node.properties))
+        return [];
+    return Object.entries(node.properties).flatMap(([key, child]) => leavesAt(child, at(key)));
+}
+function leavesAt(node, path) {
+    if (!isRecord(node) || '$ref' in node)
+        return [path];
+    const types = schemaTypes(node);
+    if (types.length && types.every((type) => type === 'boolean'))
+        return [];
+    const group = types.includes('array') || types.includes('object') || schemaBranches(node).length;
+    return group ? placeholdersAt(node, path) : [path];
+}
+// A schema that doesn't say what's there ($ref, no properties, no items) is taken on trust.
+function schemaPathHolds(node, keys, walked) {
+    if (!isRecord(node) || '$ref' in node)
+        return { holds: 'value' };
+    const branches = schemaBranches(node);
+    if (branches.length) {
+        return mergeHolds(branches.map((branch) => schemaPathHolds(branch, keys, walked)));
+    }
+    const types = schemaTypes(node);
+    const [key, ...rest] = keys;
+    if (key === undefined) {
+        if (types.length && types.every((type) => type === 'boolean'))
+            return { holds: 'flag' };
+        if (types.includes('array') || types.includes('object')) {
+            return { holds: 'group', instead: placeholdersAt(node, walked) };
+        }
+        return { holds: 'value' };
+    }
+    const next = walked ? `${walked}.${key}` : key;
+    const missing = { holds: 'missing', instead: placeholdersAt(node, walked) };
+    if (types.includes('array')) {
+        if (key === 'length')
+            return rest.length ? missing : { holds: 'value' };
+        if (INDEX.test(key)) {
+            return isRecord(node.items) ? schemaPathHolds(node.items, rest, next) : { holds: 'value' };
+        }
+    }
+    if (isRecord(node.properties)) {
+        return Object.hasOwn(node.properties, key)
+            ? schemaPathHolds(node.properties[key], rest, next)
+            : missing;
+    }
+    return types.length === 0 || types.includes('object') ? { holds: 'value' } : missing;
+}
+function tryInstead(paths) {
+    const shown = [...new Set(paths)].slice(0, 4).map((path) => `{${path}}`);
+    if (shown.length === 0)
+        return '';
+    const list = shown.length === 1 ? shown[0] : `${shown.slice(0, -1).join(', ')} or ${shown.at(-1)}`;
+    return ` Try ${list}.`;
+}
+/**
+ * Why a label can't fill from these JSON schemas, as a sentence for its author, or `undefined`
+ * when every placeholder can. Pass `output` for a Done label.
+ */
+export function activityLabelProblem(template, schemas) {
+    const sides = 'output' in schemas ? ['input', 'output'] : ['input'];
+    for (const match of template.matchAll(PLACEHOLDER)) {
+        const { path } = parsePlaceholder(match[1] ?? '');
+        if (!path) {
+            const example = placeholdersAt(schemas.input, '')[0] ?? 'name';
+            return `Put a field name between the braces, like {${example}}.`; // lexicon-exempt: builder diagnostic
+        }
+        const paths = routes(path, sides);
+        const [route] = paths;
+        if (!route)
+            continue;
+        if (route.prefixed && !sides.includes(route.side)) {
+            return `{${path}} is only there once the call is done; use it in the Done label.`; // lexicon-exempt: builder diagnostic
+        }
+        const found = mergeHolds(paths.map(({ side, keys, prefixed }) => schemaPathHolds(schemas[side], keys, prefixed ? side : '')));
+        if (found.holds === 'value')
+            continue;
+        const all = found.instead ?? [];
+        const depth = route.prefixed ? 1 : 0;
+        const near = all.filter((candidate) => candidate.split('.')[depth] === route.keys[0]);
+        const from = route.prefixed ? route.side : sides.join(' or ');
+        const reason = {
+            missing: `is not a field of this tool's ${from}.`, // lexicon-exempt: builder diagnostic
+            group: 'is a list or group; a label shows text or a number.', // lexicon-exempt: builder diagnostic
+            flag: 'is true or false; a label shows text or a number.', // lexicon-exempt: builder diagnostic
+        }[found.holds];
+        return `{${path}} ${reason}${tryInstead(near.length ? near : all)}`;
+    }
+    return undefined;
+}

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

@@ -0,0 +1,51 @@
+import type { z } from 'zod';
+import type { GuardrailEvent, NetworkGuardrailSpec } from '../../guardrails/types.js';
+import type { SpanHandle } from '../../observability/trace-span.js';
+import { type Source } from '../turn-events.js';
+import type { TurnEvent, TurnEventOf } from '../types.js';
+import type { ToolCallRequest, ToolContext, ToolFailure, ToolLabels, ToolPhaseEvent } from './types.js';
+export type ToolCallBase = Pick<ToolPhaseEvent, 'name' | 'callId'>;
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type ToolPhasePatch = DistributiveOmit<ToolPhaseEvent, keyof ToolCallBase | 'at'>;
+export declare function toolEvent(base: ToolCallBase, patch: ToolPhasePatch): TurnEventOf<'tool'>;
+/** `readBack` is passed when the call's result guard already wrote the model's text. */
+export declare function failureEvent(base: ToolCallBase, failure: ToolFailure, readBack?: string): TurnEventOf<'tool'>;
+/** The first event of every call. */
+export declare function toolCallRequestEvent(base: ToolCallBase, args: Record<string, unknown>, { thoughtSignature, stepId }?: Pick<ToolCallRequest, 'thoughtSignature' | 'stepId'>): TurnEventOf<'tool'>;
+/** Unique: readers join a call's events by it. */
+export declare function newCallId(name: string): string;
+export declare function toolCallArguments(safeInput: unknown): Record<string, unknown>;
+export declare function messageOf(err: unknown): string;
+export declare function sourceEvents(base: ToolCallBase, sources: (output: unknown) => Source[], output: unknown): Generator<TurnEvent>;
+/** `{ ok: false }` comes after the failure event is emitted, so callers only bail. */
+export declare function startToolExecution<T>(tool: {
+    input: z.ZodType<T>;
+    labels?: ToolLabels;
+}, rawInput: unknown, ctx: ToolContext, base: ToolCallBase): Generator<TurnEvent, {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+}>;
+export declare function networkBlockedEvent(): GuardrailEvent;
+export declare function networkBlocked(err: unknown, guardrail?: GuardrailEvent): Generator<TurnEvent, ToolFailure>;
+/**
+ * Shared by HTTP and MCP so they cannot diverge on what SSRF enforcement means.
+ * The check's time goes on the tool's span, when the call is traced.
+ */
+export declare function guardToolTarget(url: string, ctx: ToolContext, span?: SpanHandle): Generator<TurnEvent, {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+    failure: ToolFailure;
+}>;
+/** The checks a guarded request runs on its way, timed together: each hop's address, and its lookup. */
+export interface RequestChecks {
+    /** Pass as `fetchGuarded`'s `onCheck`. */
+    onCheck: (ms: number) => void;
+    /** Records the checks once, when any ran, with the block they raised. */
+    record: (blocked?: GuardrailEvent) => void;
+}
+export declare function requestChecks(span: SpanHandle | undefined): RequestChecks;
+export declare function toolNetworkPolicy(ctx: ToolContext): NetworkGuardrailSpec | undefined;

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

@@ -0,0 +1,149 @@
+import { throwIfAborted } from '../../guardrails/error.js';
+import { assertSafeUrl } from '../../guardrails/network.js';
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { NETWORK_RULES } from '../../guardrails/rules.js';
+import { recordToolCheck } from '../engine/tool-trace.js';
+import { sourceSchema } from '../turn-events.js';
+import { isRecord } from '../util/record.js';
+import { fillActivityLabel } from './activity-label.js';
+import { formatToolFailureForModel, formatToolResult } from './model-text.js';
+export function toolEvent(base, patch) {
+    return {
+        type: 'tool',
+        tool: { ...patch, name: base.name, callId: base.callId, at: Date.now() },
+    };
+}
+/** `readBack` is passed when the call's result guard already wrote the model's text. */
+export function failureEvent(base, failure, readBack = formatToolResult(formatToolFailureForModel(failure))) {
+    return toolEvent(base, { phase: 'error', failure, readBack });
+}
+/** The first event of every call. */
+export function toolCallRequestEvent(base, args, { thoughtSignature, stepId } = {}) {
+    return {
+        type: 'tool',
+        tool: {
+            name: base.name,
+            callId: base.callId,
+            arguments: args,
+            ...(thoughtSignature ? { thoughtSignature } : {}),
+            ...(stepId ? { stepId } : {}),
+        },
+    };
+}
+/** Unique: readers join a call's events by it. */
+export function newCallId(name) {
+    return `call_${name}_${crypto.randomUUID()}`;
+}
+export function toolCallArguments(safeInput) {
+    if (safeInput === undefined)
+        return {};
+    return isRecord(safeInput) ? safeInput : { value: safeInput };
+}
+export function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function sourcesInvalid(base, message) {
+    return toolEvent(base, {
+        phase: 'warning',
+        warning: { code: 'sources_invalid', message, severity: 'warning' },
+    });
+}
+export function* sourceEvents(base, sources, output) {
+    let listed;
+    try {
+        listed = sources(output);
+    }
+    catch (err) {
+        yield sourcesInvalid(base, `sources threw: ${messageOf(err)}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return;
+    }
+    if (!Array.isArray(listed)) {
+        yield sourcesInvalid(base, 'sources must return an array'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return;
+    }
+    const cited = [];
+    const invalid = [];
+    listed.forEach((entry, index) => {
+        const parsed = sourceSchema.safeParse(entry);
+        if (parsed.success)
+            cited.push(parsed.data);
+        else
+            invalid.push(`[${String(index)}] ${parsed.error.issues.map((i) => `${i.path.join('.') || 'source'}: ${i.message}`).join('; ')}`);
+    });
+    if (invalid.length > 0) {
+        yield sourcesInvalid(base, `sources not cited: ${invalid.join(' | ')}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (cited.length > 0)
+        yield { type: 'citation', sources: cited, callId: base.callId };
+}
+/** `{ ok: false }` comes after the failure event is emitted, so callers only bail. */
+export function* startToolExecution(tool, rawInput, ctx, base) {
+    const edited = ctx.resume?.edited;
+    const activity = fillActivityLabel(tool.labels?.activity, { input: rawInput });
+    yield toolEvent(base, {
+        phase: 'running',
+        ...(edited ? { edited: { from: edited.from, to: toolCallArguments(rawInput) } } : {}),
+        ...(activity ? { activity } : {}),
+    });
+    throwIfAborted(ctx.signal);
+    const parsed = tool.input.safeParse(rawInput);
+    if (!parsed.success) {
+        yield failureEvent(base, {
+            code: 'invalid_input',
+            kind: 'bad_response',
+            message: 'Tool input validation failed', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            details: parsed.error.flatten(),
+        });
+        return { ok: false };
+    }
+    return { ok: true, data: parsed.data };
+}
+export function networkBlockedEvent() {
+    return {
+        stage: 'network',
+        trust: 'untrusted',
+        action: 'block',
+        hits: [{ rule: NETWORK_RULES.blocked, severity: 'high' }],
+    };
+}
+export function* networkBlocked(err, guardrail = networkBlockedEvent()) {
+    yield { type: 'guardrail', guardrail };
+    return { code: 'network_blocked', kind: 'blocked', message: messageOf(err) };
+}
+/**
+ * Shared by HTTP and MCP so they cannot diverge on what SSRF enforcement means.
+ * The check's time goes on the tool's span, when the call is traced.
+ */
+export function* guardToolTarget(url, ctx, span) {
+    const start = performance.now();
+    try {
+        const safe = assertSafeUrl(url, toolNetworkPolicy(ctx));
+        recordToolCheck(span, 'network', performance.now() - start, undefined);
+        return { ok: true, url: safe };
+    }
+    catch (err) {
+        const blocked = networkBlockedEvent();
+        recordToolCheck(span, 'network', performance.now() - start, blocked);
+        return { ok: false, failure: yield* networkBlocked(err, blocked) };
+    }
+}
+export function requestChecks(span) {
+    let ms = 0;
+    let ran = false;
+    let recorded = false;
+    return {
+        onCheck: (took) => {
+            ms += took;
+            ran = true;
+        },
+        record: (blocked) => {
+            if (recorded || !ran)
+                return;
+            recorded = true;
+            recordToolCheck(span, 'network_request', ms, blocked);
+        },
+    };
+}
+export function toolNetworkPolicy(ctx) {
+    return resolveGuardrailPolicy(ctx.profile.guardrails).network;
+}