@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { interactionPartSchema, keptReply, sourceSchema } from '../turn-events.js';
+import { findLast } from '../util/find-last.js';
+import { profileToolAllow } from './resolve.js';
+/** A call that settled without a reply; the model reads `failure`. */
+class AgentCallFailed extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+    }
+}
+/** The agents an agent tool can run: each has a turn that takes text. */
+const AGENT_TOOL_TYPES = new Set(['text', 'image', 'speech']);
+// why: Bytes that are not base64, or a text of only spaces, would be refused inside the called turn as the host's error and end the caller's turn; checked here, the model reads a failed call.
+const textInput = z.string().regex(/\S/);
+const blobInput = z.strictObject({
+    mimeType: z.string(),
+    data: z.base64(),
+    name: z.string().optional(),
+});
+const mediaRefInput = z.strictObject({
+    mimeType: z.string(),
+    uri: z.string(),
+    name: z.string().optional(),
+});
+const speechInput = z.strictObject({
+    voice: z.string().optional(),
+    style: z.string().optional(),
+    speed: z.number().positive().optional(),
+});
+/** One choice per declared slot; a slot or a value the profile does not declare is refused. */
+function slotsInput(slots) {
+    return z.strictObject(Object.fromEntries(Object.entries(slots).map(([slot, choices]) => [slot, z.enum(choices).optional()])));
+}
+/** The fields an agent tool's input can carry to the called agent; a host field takes none of these names. */
+const AGENT_INPUT_FIELDS = new Set([
+    'text',
+    'attachments',
+    'voice',
+    'slots',
+    'speech',
+]);
+/**
+ * What the model sent, split into what goes to the called agent and what only the host reads.
+ *
+ * why: A host field is the host's own word for something (an id it resolves); the called profile does not take it, so it never reaches the agent's turn.
+ */
+function splitHostInput(tool, input) {
+    if (!tool.hostFields)
+        return { sent: input };
+    const all = { ...input };
+    const hostInput = {};
+    for (const field of Object.keys(tool.hostFields)) {
+        if (all[field] !== undefined)
+            hostInput[field] = all[field];
+    }
+    const { text, attachments, voice, slots, speech } = input;
+    return {
+        sent: {
+            text,
+            ...(attachments ? { attachments } : {}),
+            ...(voice ? { voice } : {}),
+            ...(slots ? { slots } : {}),
+            ...(speech ? { speech } : {}),
+        },
+        hostInput,
+    };
+}
+/**
+ * The input of an agent tool that runs `agent`: text, and each channel the
+ * profile's `inputs` declares. Anything else is refused, never dropped. The
+ * called turn's own ingress checks MIME types and sizes.
+ */
+function agentToolInputFor(agent, tool) {
+    const { inputs } = agent;
+    const shape = { text: textInput };
+    if (inputs?.attachments) {
+        shape.attachments = z.array(z.union([blobInput, mediaRefInput])).optional();
+    }
+    if (inputs?.voice)
+        shape.voice = z.array(blobInput).optional();
+    if (inputs?.slots)
+        shape.slots = slotsInput(inputs.slots).optional();
+    if (agent.type === 'speech')
+        shape.speech = speechInput.optional();
+    for (const channel of tool?.hostOnly ?? []) {
+        if (!shape[channel]) {
+            throw new TheoremError('config', `Tool '${tool?.name}' keeps '${channel}' for the host, which its profile does not take`);
+        }
+        delete shape[channel];
+    }
+    for (const [field, text] of Object.entries(tool?.fieldText ?? {})) {
+        const schema = shape[field];
+        if (!schema) {
+            throw new TheoremError('config', `Tool '${tool?.name}' describes '${field}', which its profile does not take`);
+        }
+        shape[field] = schema.describe(text);
+    }
+    for (const [field, schema] of Object.entries(tool?.hostFields ?? {})) {
+        if (AGENT_INPUT_FIELDS.has(field)) {
+            throw new TheoremError('config', `Tool '${tool?.name}' declares the host field '${field}', which is a field of every agent tool`);
+        }
+        shape[field] = schema;
+    }
+    // why: The shape is built key by key from the profile, which zod cannot type; each key is an `AgentToolInput` field.
+    return z.strictObject(shape);
+}
+const agentToolOutput = z.object({
+    text: z.string().optional(),
+    structured: z.unknown().optional(),
+    removed: z
+        .array(z.object({ path: z.string(), reason: z.string(), item: z.unknown() }))
+        .optional(),
+    parts: z.array(interactionPartSchema).optional(),
+    sources: z.array(sourceSchema).optional(),
+});
+function profileTakesText(profile) {
+    if (profile.type === 'speech')
+        return true;
+    return (profile.type === 'text' || profile.type === 'image') && profile.inputs.text !== false;
+}
+/** A tool that can stop the turn on a gate: a gate inside the called agent has no one to answer it. */
+function toolCanGate(tool) {
+    if (tool.type === 'builtin')
+        return false;
+    if (tool.permission !== 'auto')
+        return true;
+    return ('auth' in tool && tool.auth !== undefined && (tool.auth.onUnauthenticated ?? 'gate') === 'gate');
+}
+/** Why `profile` can't be run by an agent tool, or `undefined` when it can. */
+function agentProfileProblem(profile, find) {
+    if (!AGENT_TOOL_TYPES.has(profile.type)) {
+        return `it is a ${profile.type} profile; an agent tool runs a text, image, or speech profile`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (!profileTakesText(profile))
+        return 'it does not take text'; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    for (const id of profileToolAllow(profile)) {
+        const tool = find(id);
+        if (!tool)
+            return `its tool '${id}' is not registered; register it first`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        if (toolCanGate(tool)) {
+            return `its tool '${id}' can stop on a gate; give it permission 'auto' and no sign-in`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+    return undefined;
+}
+/** The profile an agent tool runs; throws `config` when the tool can't run it. */
+function agentToolProfile(def, findProfile, findTool) {
+    const tag = `Agent tool "${def.name}"`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    const max = def.maxCallsPerTurn;
+    if (max !== undefined && !(Number.isInteger(max) && max > 0)) {
+        throw new TheoremError('config', `${tag}: maxCallsPerTurn must be a whole number above 0`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const profile = findProfile(def.profile);
+    if (!profile) {
+        throw new TheoremError('config', `${tag}: profile '${def.profile}' must be registered before the tool`);
+    }
+    const problem = agentProfileProblem(profile, findTool);
+    if (problem) {
+        throw new TheoremError('config', `${tag} can't run '${def.profile}': ${problem}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return profile;
+}
+/** An agent with no tools of its own read only what it was sent; one with tools may have read outside content. */
+function agentToolOrigin(profile) {
+    if (!profile)
+        return 'delegated';
+    const builtins = 'models' in profile
+        ? Object.values(profile.models).some((binding) => (binding.builtInTools?.length ?? 0) > 0)
+        : false;
+    return profileToolAllow(profile).length === 0 && !builtins ? 'local' : 'delegated';
+}
+/**
+ * The called agent's reply: its text or its last structured reply, its media as parts, and what it cited.
+ *
+ * why: A structured reply's text is the same JSON as a string, so returning both would have the caller's model read the answer twice.
+ */
+function agentToolOutputOf(turn) {
+    const events = keptReply(turn);
+    const text = events.flatMap((e) => (e.type === 'text' ? [e.text] : [])).join('');
+    const reply = findLast(events, (e) => e.type === 'structured');
+    const structured = reply?.structured;
+    const parts = events.flatMap((e) => e.type === 'media'
+        ? [
+            {
+                type: e.media.mimeType.startsWith('audio/') ? 'audio' : 'image',
+                mimeType: e.media.mimeType,
+                data: e.media.data,
+            },
+        ]
+        : []);
+    const sources = events.flatMap((e) => (e.type === 'citation' ? e.sources : []));
+    return {
+        ...(structured === undefined ? { text } : { structured }),
+        ...(reply?.removed?.length ? { removed: reply.removed } : {}),
+        ...(parts.length > 0 ? { parts } : {}),
+        ...(sources.length > 0 ? { sources } : {}),
+    };
+}
+function normalizeAgent(def, input, schemas) {
+    return {
+        ...def,
+        type: 'agent',
+        input,
+        output: agentToolOutput,
+        sources: (output) => output.sources ?? [],
+        ...schemas,
+    };
+}
+export { AgentCallFailed, agentProfileProblem, agentToolInputFor, agentToolOrigin, agentToolOutput, agentToolOutputOf, agentToolProfile, normalizeAgent, splitHostInput, };

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

@@ -0,0 +1,4 @@
+import type { TurnEvent } from '../types.js';
+import type { ToolExecuteSettlement } from './execute.js';
+import { type ToolExecutionCoordinator, type ToolOperationClaim, type ToolOperationIdentity, type ToolOperationOutcome } from './operation.js';
+export declare function coordinateTool(coordinator: ToolExecutionCoordinator | undefined, identity: Omit<ToolOperationIdentity, 'invocationHash'>, invocation: unknown, signal: AbortSignal | undefined, run: (beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>) => AsyncGenerator<TurnEvent, ToolExecuteSettlement>, authorizeReplay?: (outcome: ToolOperationOutcome) => void | Promise<void>): AsyncGenerator<TurnEvent, ToolExecuteSettlement>;

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

@@ -0,0 +1,165 @@
+import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
+import { jsonObjectSchema } from '../json.js';
+import { operationUnavailable, operationWireValue, toolInvocationHash, toolOperationOutcomeSchema, } from './operation.js';
+class ReplayedOperation {
+    outcome;
+    constructor(outcome) {
+        this.outcome = outcome;
+    }
+}
+function uncertainError(cause) {
+    return new TheoremError('unavailable', labelText('tool.execution_uncertain'), {
+        copy: { key: 'tool.execution_uncertain' },
+        cause,
+    });
+}
+class CoordinatedExecution {
+    coordinator;
+    operation;
+    accepted;
+    signal;
+    claim;
+    committed = false;
+    writeFailed = false;
+    terminal;
+    constructor(coordinator, operation, accepted, signal) {
+        this.coordinator = coordinator;
+        this.operation = operation;
+        this.accepted = accepted;
+        this.signal = signal;
+    }
+    async beginBody(preparedInput) {
+        throwIfAborted(this.signal);
+        const operation = {
+            ...this.operation,
+            invocation: { accepted: this.accepted, preparedInput: operationWireValue(preparedInput) },
+        };
+        const result = await this.coordinator.begin(operation);
+        if (result.kind === 'settled')
+            throw new ReplayedOperation(result.outcome);
+        if (result.kind === 'running' || result.kind === 'uncertain')
+            throw uncertainError();
+        if (result.kind !== 'acquired' || typeof result.claimToken !== 'string' || !result.claimToken)
+            throw operationUnavailable();
+        this.claim = { ...operation, claimToken: result.claimToken };
+        throwIfAborted(this.signal);
+        return this.claim;
+    }
+    observe(event) {
+        if (event.type !== 'tool')
+            return true;
+        if (event.tool.phase === 'complete' || event.tool.phase === 'error') {
+            this.terminal = { ...event, tool: event.tool };
+            return false;
+        }
+        if (this.claim && event.tool.phase === 'gate')
+            throw uncertainError();
+        return true;
+    }
+    async finish(settlement) {
+        if (settlement.gated) {
+            if (this.claim)
+                throw uncertainError();
+            return undefined;
+        }
+        if (!this.terminal)
+            throw operationUnavailable();
+        const { modelResult, outputRaw, failure, awaiting, denied, callNotStarted, aborted, pendingInject, } = settlement;
+        const effects = this.claim ? (failure ? 'unknown' : 'completed') : 'not_started';
+        const outcome = {
+            event: this.terminal,
+            effects,
+            replay: {
+                modelResult,
+                outputRaw,
+                failure,
+                awaiting,
+                denied,
+                callNotStarted,
+                aborted,
+                pendingInject,
+            },
+        };
+        this.writeFailed = true;
+        const saved = toolOperationOutcomeSchema.parse(operationWireValue(outcome));
+        if (this.claim)
+            await this.coordinator.settle(this.claim, saved);
+        else
+            await this.coordinator.settleNotStarted(this.operation, saved);
+        this.committed = true;
+        return saved.event;
+    }
+    replay(error) {
+        const saved = toolOperationOutcomeSchema.parse(operationWireValue(error.outcome));
+        const { operationId, callId, toolId } = this.operation;
+        if (saved.event.tool.operationId !== operationId ||
+            saved.event.tool.callId !== callId ||
+            saved.event.tool.name !== toolId)
+            throw operationUnavailable();
+        this.committed = true;
+        return saved;
+    }
+    failure(error) {
+        return this.claim && !this.committed ? uncertainError(error) : error;
+    }
+    async close() {
+        if (this.claim && !this.committed) {
+            await this.coordinator.markUncertain(this.claim, this.writeFailed ? 'settlement_write_failed' : 'execution_interrupted');
+        }
+    }
+}
+export async function* coordinateTool(coordinator, identity, invocation, signal, run, authorizeReplay) {
+    if (!coordinator)
+        return yield* run();
+    const accepted = jsonObjectSchema.parse(operationWireValue(invocation));
+    const operation = { ...identity, invocationHash: await toolInvocationHash(accepted) };
+    const execution = new CoordinatedExecution(coordinator, operation, accepted, signal);
+    throwIfAborted(signal);
+    const existing = await coordinator.lookup(operation);
+    throwIfAborted(signal);
+    if (existing?.kind === 'running' || existing?.kind === 'uncertain')
+        throw uncertainError();
+    if (existing?.kind === 'settled') {
+        if (!authorizeReplay)
+            throw operationUnavailable();
+        const saved = execution.replay(new ReplayedOperation(existing.outcome));
+        await authorizeReplay(saved);
+        throwIfAborted(signal);
+        yield saved.event;
+        return saved.replay;
+    }
+    const iterator = run((input) => execution.beginBody(input));
+    try {
+        for (;;) {
+            const next = await iterator.next();
+            if (next.done) {
+                const terminal = await execution.finish(next.value);
+                if (terminal)
+                    yield terminal;
+                return next.value;
+            }
+            if (execution.observe(next.value))
+                yield next.value;
+        }
+    }
+    catch (error) {
+        if (error instanceof ReplayedOperation) {
+            if (!authorizeReplay)
+                throw operationUnavailable();
+            const saved = execution.replay(error);
+            await authorizeReplay(saved);
+            yield saved.event;
+            return saved.replay;
+        }
+        throw execution.failure(error);
+    }
+    finally {
+        try {
+            await execution.close();
+        }
+        finally {
+            await iterator.return({});
+        }
+    }
+}

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

@@ -0,0 +1,66 @@
+import type { z } from 'zod';
+import { type LabelOverrides } from '../../guardrails/labels.js';
+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 { ToolOperationClaim } from './operation.js';
+import type { ToolCallRequest, ToolContext, ToolFailure, ToolLabels, ToolPhaseEvent } from './types.js';
+export type ToolCallBase = Pick<ToolPhaseEvent, 'name' | 'callId'> & {
+    operationId?: string;
+    /** The call's failed label, from {@linkcode failedActivity}; absent, a failure names the tool. */
+    activityFailed?: string;
+};
+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'>;
+/**
+ * The label a failed call shows: the tool's own, filled from the input the model sent, else the
+ * labels' line naming the tool in words.
+ */
+export declare function failedActivity(name: string, profileLabels?: LabelOverrides, labels?: ToolLabels, input?: unknown): string;
+/** The failed label of the call `base` names. */
+export declare function failedActivityOf(base: ToolCallBase): string;
+/** `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>, { reasoning, stepId, stepCallCount, }?: Pick<ToolCallRequest, 'reasoning' | 'stepId' | 'stepCallCount'>): 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>;
+export declare function dispatchToolBody(tool: {
+    labels?: ToolLabels;
+}, input: unknown, ctx: ToolContext, base: ToolCallBase, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>): AsyncGenerator<TurnEvent, ToolOperationClaim | undefined>;
+export declare function startToolExecution<T>(tool: {
+    input: z.ZodType<T>;
+}, rawInput: unknown, ctx: ToolContext): {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    failure: ToolFailure;
+};
+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,184 @@
+import { throwIfAborted } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.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, toolNameInWords } 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,
+            ...(base.operationId ? { operationId: base.operationId } : {}),
+            at: Date.now(),
+        },
+    };
+}
+/**
+ * The label a failed call shows: the tool's own, filled from the input the model sent, else the
+ * labels' line naming the tool in words.
+ */
+export function failedActivity(name, profileLabels, labels, input) {
+    return (fillActivityLabel(labels?.activityFailed, { input }) ??
+        labelText('tool.activity_failed', { tool: toolNameInWords(name) }, profileLabels));
+}
+/** The failed label of the call `base` names. */
+export function failedActivityOf(base) {
+    return base.activityFailed ?? failedActivity(base.name);
+}
+/** `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,
+        activityPast: failedActivityOf(base),
+    });
+}
+/** The first event of every call. */
+export function toolCallRequestEvent(base, args, { reasoning, stepId, stepCallCount, } = {}) {
+    return {
+        type: 'tool',
+        tool: {
+            name: base.name,
+            callId: base.callId,
+            ...(base.operationId ? { operationId: base.operationId } : {}),
+            arguments: args,
+            ...(reasoning?.length ? { reasoning } : {}),
+            ...(stepId ? { stepId } : {}),
+            ...(stepCallCount ? { stepCallCount } : {}),
+        },
+    };
+}
+/** 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)}`); // labels-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'); // labels-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(' | ')}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (cited.length > 0)
+        yield { type: 'citation', sources: cited, callId: base.callId };
+}
+function toolRunningEvent(tool, rawInput, ctx, base) {
+    const edited = ctx.resume?.edited;
+    const activity = fillActivityLabel(tool.labels?.activity, { input: rawInput });
+    return toolEvent(base, {
+        phase: 'running',
+        ...(edited ? { edited: { from: edited.from, to: toolCallArguments(rawInput) } } : {}),
+        ...(activity ? { activity } : {}),
+    });
+}
+export async function* dispatchToolBody(tool, input, ctx, base, beginBody) {
+    const claim = await beginBody?.(input);
+    throwIfAborted(ctx.signal);
+    yield toolRunningEvent(tool, input, ctx, base);
+    return claim;
+}
+export function startToolExecution(tool, rawInput, ctx) {
+    throwIfAborted(ctx.signal);
+    const parsed = tool.input.safeParse(rawInput);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            failure: {
+                code: 'invalid_input',
+                kind: 'bad_response',
+                message: labelText('tool.input_invalid', {}, ctx.profile.labels),
+                details: parsed.error.flatten(),
+            },
+        };
+    }
+    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;
+}