@aid-framework/runtime 0.0.0-stage → 0.1.39

package/dist/agents/gateway_chat_model.js

@@ -0,0 +1,350 @@
+/**
+ * Expose {@link ModelGateway} as a LangChain chat model.
+ *
+ * This module is the load-bearing part of the Deep Agents backend. A harness handed a
+ * provider would keep working while silently dropping every guarantee the gateway exists
+ * to provide: the fallback chain, the budget preflight, the cost ledger and the
+ * per-attempt LLM span. The agent would look fine and the budget would stop applying. So
+ * the harness is never handed a provider -- it is handed *this adapter*, and every model
+ * call inside the graph goes back out through our gateway.
+ *
+ * What the adapter is responsible for:
+ *
+ * - **Translation, both directions.** LangChain messages to our {@link Message}, and our
+ *   {@link CompletionResponse} back to an `AIMessage` carrying tool calls, `usage_metadata`
+ *   and the alias/cost the gateway actually charged. The alias matters: a fallback means
+ *   the answer did not come from the pinned model, and the response says so rather than
+ *   letting the harness believe otherwise.
+ * - **Tool filtering.** `bindTools` is the single funnel every tool reaches the model
+ *   through, which makes it the one place to enforce what the agent may call. Deep Agents
+ *   bundles `ls`/`read_file`/`write_file`/`edit_file`/`delete`/`glob`/`grep`/`execute` and
+ *   binds all of them; the allow-list drops everything the agent did not declare, so the
+ *   filesystem and shell tools are unreachable rather than merely undocumented.
+ * - **Budget continuity.** The agent's ceiling travels with every call, so a breach
+ *   surfaces as the gateway's own {@link BudgetExceededError} from inside the harness.
+ *   There is no second accounting path here to disagree with it.
+ *
+ * Everything in here statically imports `@langchain/*`. That is deliberate and safe: the
+ * harness is optional for consumers, `agents/deep_agents.ts` is the only module that
+ * reaches this one, and it does so with a dynamic `import()` after {@link checkEngine} has
+ * proved the packages are installed.
+ */
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { AIMessage, HumanMessage, SystemMessage, ToolMessage } from '@langchain/core/messages';
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { DeepAgentsEngineError, DeepAgentsMaxStepsError } from '../errors.js';
+import { CompletionRequest, Message, ToolCall, ToolDefinition } from '../types.js';
+/**
+ * A LangChain chat model whose every generation is a gateway call.
+ *
+ * Construct it with the alias the IR pinned, the gateway that owns fallback and
+ * accounting, and the ceiling this agent may spend. `allowedTools` is the tool allow-list:
+ * `undefined` admits everything the harness binds, which is only appropriate for an agent
+ * that declares no tools.
+ */
+export class GatewayChatModel extends BaseChatModel {
+    gateway;
+    alias;
+    fallbacks;
+    budget;
+    allowedTools;
+    /**
+     * The agent's `maxSteps`, counted in model calls. Enforced here because this adapter is
+     * the only place that sees every model call -- and because the harness's own limiter
+     * *completes* the run with a synthetic answer instead of failing.
+     */
+    maxCalls;
+    /** What `bindTools` last admitted. Read by tests, never by the harness. */
+    boundTools;
+    /** Every generation this model produced, in order: proof the harness went through us. */
+    calls;
+    constructor(init) {
+        super({});
+        this.gateway = init.gateway;
+        this.alias = init.alias;
+        this.fallbacks = [...(init.fallbacks ?? [])];
+        this.budget = init.budget;
+        this.allowedTools = init.allowedTools;
+        this.maxCalls = init.maxCalls;
+        this.boundTools = [...(init.boundTools ?? [])];
+        this.calls = init.calls ?? [];
+    }
+    /**
+     * Admit only the tools this agent declared.
+     *
+     * Every tool the harness offers -- bundled ones included -- arrives here, so an
+     * allow-list applied at this point is the difference between "we do not document a
+     * shell" and "there is no shell the model can reach". The filtered set is kept on a copy
+     * rather than on `this` so two agents sharing one adapter cannot widen each other's
+     * grant; the copy shares `calls`, because the accumulator is the run's spend record and a
+     * per-copy one would silently lose the generations of every bound model.
+     */
+    bindTools(tools) {
+        const admitted = toToolDefinitions(tools, { allowed: this.allowedTools });
+        return new GatewayChatModel({
+            gateway: this.gateway,
+            alias: this.alias,
+            fallbacks: this.fallbacks,
+            ...(this.budget === undefined ? {} : { budget: this.budget }),
+            ...(this.allowedTools === undefined ? {} : { allowedTools: this.allowedTools }),
+            ...(this.maxCalls === undefined ? {} : { maxCalls: this.maxCalls }),
+            boundTools: admitted,
+            calls: this.calls,
+        });
+    }
+    _llmType() {
+        return 'aid-gateway';
+    }
+    _identifyingParams() {
+        return { alias: this.alias, fallbacks: [...this.fallbacks] };
+    }
+    /**
+     * One harness model call, routed through the gateway.
+     *
+     * LangChain 1.x exposes a single async generation hook: `generate` and `invoke` both
+     * return promises and there is no synchronous entry point at all, so unlike the Python
+     * adapter there is no second path to refuse here.
+     *
+     * `fallbacks` and `budget` travel with the call, so the harness gets the same fallback
+     * behaviour and the same hard ceiling as the native loop. A breach is raised, not
+     * returned: the harness must not be able to continue past a budget the ledger refused.
+     */
+    async _generate(messages, _options, _runManager) {
+        const request = new CompletionRequest({
+            messages: toAidMessages(messages),
+            tools: this.boundTools,
+        });
+        if (this.maxCalls !== undefined && this.calls.length >= this.maxCalls) {
+            // Refused before the call, not after: an agent that has spent its step budget must
+            // not spend one more to discover that it has.
+            throw new DeepAgentsMaxStepsError(this.alias, this.maxCalls);
+        }
+        const generation = await this.gateway.generate(this.alias, request, {
+            fallbacks: this.fallbacks,
+            ...(this.budget === undefined ? {} : { budget: this.budget }),
+        });
+        this.calls.push(generation);
+        return {
+            generations: [{ text: generation.response.text, message: toAiMessage(generation) }],
+        };
+    }
+    // biome-ignore lint/correctness/useYield: a stream that works is the bug; this refuses.
+    async *_streamResponseChunks(_messages, _options, _runManager) {
+        throw new DeepAgentsEngineError('streaming is not exposed through the deepagents engine: ModelGateway.stream serves ' +
+            'Server-Sent Event bytes for the HTTP layer, but the engine consumes ' +
+            'request/response generation and never an SSE byte stream. A structured LangChain ' +
+            'chunk stream would be a second streaming contract and a second accounting path, ' +
+            'so it is refused here rather than buffered into a non-stream.');
+    }
+}
+/** Carry the gateway's answer across, including what it cost and where from. */
+function toAiMessage(generation) {
+    const response = generation.response;
+    const usage = generation.usage;
+    return new AIMessage({
+        content: response.text,
+        tool_calls: response.toolCalls.map((call) => ({
+            name: call.name,
+            args: { ...call.args },
+            id: call.id,
+            type: 'tool_call',
+        })),
+        usage_metadata: {
+            input_tokens: usage.inputTokens,
+            output_tokens: usage.outputTokens,
+            total_tokens: usage.totalTokens,
+        },
+        response_metadata: {
+            model: response.model,
+            provider: response.provider,
+            finish_reason: response.finishReason,
+            // Not decoration: after a fallback these differ from the alias the IR pinned, and
+            // that has to stay visible to the caller.
+            alias: generation.alias,
+            cost_usd: generation.costUsd,
+            fell_back: generation.fellBack,
+        },
+    });
+}
+/**
+ * Translate the harness transcript into ours.
+ *
+ * Tool calls and their ids are preserved verbatim: the harness pairs a result with its
+ * call by id, and renaming or renumbering them here would break the pairing in a way that
+ * only shows up as a tool result attached to the wrong call.
+ */
+export function toAidMessages(messages) {
+    const converted = [];
+    for (const message of messages) {
+        const type = message.getType();
+        if (type === 'system') {
+            converted.push(Message.system(text(message)));
+        }
+        else if (type === 'human') {
+            converted.push(Message.user(text(message)));
+        }
+        else if (type === 'ai') {
+            const calls = message.tool_calls ?? [];
+            if (calls.length > 0) {
+                converted.push(Message.assistantToolCalls(text(message), calls.map((call, index) => new ToolCall({
+                    id: call.id ?? `call_${index}`,
+                    name: call.name,
+                    arguments: call.args ?? {},
+                }))));
+            }
+            else {
+                converted.push(Message.assistant(text(message)));
+            }
+        }
+        else if (type === 'tool') {
+            const observed = message;
+            converted.push(Message.tool(observed.tool_call_id, text(message), {
+                ...(observed.name === undefined ? {} : { name: observed.name }),
+            }));
+        }
+        else {
+            // Deep Agents may hand us one of its own message subclasses. Dropping it would lose
+            // a turn from the transcript, so it is carried as plain text.
+            converted.push(Message.user(text(message)));
+        }
+    }
+    return converted;
+}
+/**
+ * Normalise the harness's tool specs and drop everything outside the grant.
+ *
+ * The harness offers OpenAI-shaped objects, bare `{name, parameters}` records, and
+ * `BaseTool` instances carrying a Zod schema. All are accepted so the allow-list cannot be
+ * bypassed by a shape the filter did not recognise: anything unparseable has no name, and
+ * a tool with no name is refused rather than passed through.
+ */
+export function toToolDefinitions(tools, options = {}) {
+    const allowed = options.allowed;
+    const definitions = [];
+    for (const entry of tools) {
+        const definition = toolDefinition(entry);
+        if (definition === undefined)
+            continue;
+        if (allowed !== undefined && !allowed.has(definition.name))
+            continue;
+        definitions.push(definition);
+    }
+    return definitions;
+}
+function toolDefinition(entry) {
+    const record = entry;
+    const body = record.type === 'function' && isRecord(record.function)
+        ? record.function
+        : record;
+    const name = body.name;
+    if (typeof name !== 'string' || name.length === 0)
+        return undefined;
+    return new ToolDefinition({
+        name,
+        description: typeof body.description === 'string' ? body.description : '',
+        parameters: jsonSchemaOf(body),
+    });
+}
+/**
+ * The parameter schema of one harness tool, as JSON Schema.
+ *
+ * A LangChain tool normally carries a Zod schema here. Reading it through
+ * `z.toJSONSchema` keeps the model's parameter schema intact instead of handing it an
+ * empty one, which would only fail later as a tool call with no arguments.
+ */
+function jsonSchemaOf(body) {
+    const declared = body.parameters;
+    if (isRecord(declared))
+        return { ...declared };
+    const schema = body.schema;
+    if (schema === undefined || schema === null)
+        return {};
+    try {
+        const json = z.toJSONSchema(schema);
+        // `$schema` is metadata about the dialect, not a constraint the model can act on.
+        const { $schema: _dialect, ...rest } = json;
+        return rest;
+    }
+    catch {
+        return {};
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Flatten message content to text, keeping block content that carries prose. */
+function text(message) {
+    const content = message.content;
+    if (typeof content === 'string')
+        return content;
+    const parts = [];
+    for (const block of content) {
+        if (typeof block === 'string')
+            parts.push(block);
+        else if (isRecord(block) && typeof block.text === 'string')
+            parts.push(block.text);
+    }
+    return parts.join('');
+}
+/**
+ * Translate our transcript back out, for seeding the harness with prior turns.
+ *
+ * This exists so a resumed run hands the harness the same transcript the native loop would
+ * have, rather than a summary of it. Tool calls are re-emitted as `AIMessage.tool_calls` so
+ * the harness sees them as calls it can pair, which is what keeps a resumed run's
+ * transcript comparable to an uninterrupted one.
+ */
+export function toLangchainMessages(messages) {
+    const converted = [];
+    for (const message of messages) {
+        if (message.role === 'system') {
+            converted.push(new SystemMessage(message.content));
+        }
+        else if (message.role === 'user') {
+            converted.push(new HumanMessage(message.content));
+        }
+        else if (message.role === 'tool') {
+            converted.push(new ToolMessage({
+                content: message.content,
+                tool_call_id: message.toolCallId ?? '',
+                name: message.name ?? '',
+            }));
+        }
+        else if (message.toolCalls.length > 0) {
+            converted.push(new AIMessage({
+                content: message.content,
+                tool_calls: message.toolCalls.map((call) => ({
+                    name: call.name,
+                    args: { ...call.args },
+                    id: call.id,
+                    type: 'tool_call',
+                })),
+            }));
+        }
+        else {
+            converted.push(new AIMessage(message.content));
+        }
+    }
+    return converted;
+}
+/**
+ * Wrap one declared tool as a harness tool whose body is our executor.
+ *
+ * The body is deliberately thin: authorization and the tool-call guardrail run in the
+ * guardrail middleware of whichever agent is calling, and execution goes through the same
+ * `ToolExecutor` the native loop uses. That is what makes a tool call under this engine the
+ * same event as one under the native engine.
+ *
+ * The call id is derived, not random: the harness pairs a result with its call by id, and a
+ * random one would make two identical runs differ.
+ */
+export function harnessTool(spec) {
+    const schema = z.fromJSONSchema(spec.parameters);
+    return tool(async (args) => spec.call(args), {
+        name: spec.name,
+        description: spec.description,
+        schema,
+    });
+}
+//# sourceMappingURL=gateway_chat_model.js.map

package/dist/agents/gateway_chat_model.js.map

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

package/dist/agents/guardrail_middleware.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Our authorization and tool-call guardrail engine, at the harness's tool boundary.
+ *
+ * The harness has no guardrail concept, so this is where ours wraps it. It runs before the
+ * tool body -- the only point where a decision can still stop the call -- and it throws
+ * rather than returning an observation, so the harness cannot hand the decision back to the
+ * model as something to work around.
+ *
+ * One middleware instance is bound to one frame. The caller's is attached to the graph; a
+ * delegate's is attached to its subagent spec and bound to the *delegate's* frame, which is
+ * the same split the native loop makes by driving each frame with its own agent's
+ * guardrails.
+ */
+import type { AgentMiddleware } from 'langchain';
+import type { Principal } from '../policy.js';
+import type { DeepAgentsHost } from './deep_agents.js';
+import type { Frame, Outcome } from './loop.js';
+/**
+ * The harness's delegation tool.
+ *
+ * Delegation is the one harness tool this engine exposes on purpose, and only an agent that
+ * declares a delegate is granted it. It carries no side effect of its own: the delegate's
+ * own grant governs what it may do once it is running.
+ */
+export declare const DELEGATE_TOOL = "task";
+/**
+ * A guardrail decision the harness must not be able to continue past.
+ *
+ * An error rather than a returned observation: a `ToolMessage` saying "blocked" would be
+ * fed back to the model as a tool result, and the model would be free to try again. The
+ * harness propagates an exception, so the decision ends the run -- which is what `blocked`
+ * means.
+ */
+export declare class HaltError extends Error {
+    readonly outcome: Outcome;
+    constructor(outcome: Outcome);
+}
+/** The parts of the runtime this middleware is allowed to reach. */
+export interface GuardrailMiddlewareOptions {
+    readonly host: DeepAgentsHost;
+    readonly frame: Frame;
+    readonly principal: Principal;
+    readonly memoryKey: string;
+}
+/**
+ * Build the middleware for one frame.
+ *
+ * The `task` branch is the delegation boundary, and it is deliberately the first thing the
+ * hook does: a delegate's call is authorized and guarded by the middleware bound to the
+ * *delegate's* frame, so running the caller's authorize/guardrail over it would refuse a
+ * call the delegate is entitled to make and would apply the caller's redactions inside
+ * another agent's grant. That is the native loop's semantic too -- `#delegate` opens a frame
+ * for the target and drives it, so the target's `tool-call` stage is what runs and the
+ * caller's does not cross the boundary.
+ */
+export declare function guardrailMiddleware(options: GuardrailMiddlewareOptions): AgentMiddleware;
+//# sourceMappingURL=guardrail_middleware.d.ts.map

package/dist/agents/guardrail_middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail_middleware.d.ts","sourceRoot":"","sources":["../../src/agents/guardrail_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAoC,MAAM,WAAW,CAAC;AAGnF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,YAAY,OAAO,EAAE,OAAO,EAI3B;CACF;AAWD,oEAAoE;AACpE,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,eAAe,CA6BxF"}

package/dist/agents/guardrail_middleware.js

@@ -0,0 +1,85 @@
+/**
+ * Our authorization and tool-call guardrail engine, at the harness's tool boundary.
+ *
+ * The harness has no guardrail concept, so this is where ours wraps it. It runs before the
+ * tool body -- the only point where a decision can still stop the call -- and it throws
+ * rather than returning an observation, so the harness cannot hand the decision back to the
+ * model as something to work around.
+ *
+ * One middleware instance is bound to one frame. The caller's is attached to the graph; a
+ * delegate's is attached to its subagent spec and bound to the *delegate's* frame, which is
+ * the same split the native loop makes by driving each frame with its own agent's
+ * guardrails.
+ */
+import { canonicalJson } from '../internal/json.js';
+import { ToolCall } from '../types.js';
+/**
+ * The harness's delegation tool.
+ *
+ * Delegation is the one harness tool this engine exposes on purpose, and only an agent that
+ * declares a delegate is granted it. It carries no side effect of its own: the delegate's
+ * own grant governs what it may do once it is running.
+ */
+export const DELEGATE_TOOL = 'task';
+/**
+ * A guardrail decision the harness must not be able to continue past.
+ *
+ * An error rather than a returned observation: a `ToolMessage` saying "blocked" would be
+ * fed back to the model as a tool result, and the model would be free to try again. The
+ * harness propagates an exception, so the decision ends the run -- which is what `blocked`
+ * means.
+ */
+export class HaltError extends Error {
+    outcome;
+    constructor(outcome) {
+        super(`the harness was halted at the tool boundary with status ${outcome.status}`);
+        this.name = 'HaltError';
+        this.outcome = outcome;
+    }
+}
+/** The harness's call shape, converted to ours. */
+function asCall(raw) {
+    return new ToolCall({
+        id: raw.id ?? raw.name ?? 'tool-call',
+        name: raw.name ?? '',
+        arguments: raw.args ?? {},
+    });
+}
+/**
+ * Build the middleware for one frame.
+ *
+ * The `task` branch is the delegation boundary, and it is deliberately the first thing the
+ * hook does: a delegate's call is authorized and guarded by the middleware bound to the
+ * *delegate's* frame, so running the caller's authorize/guardrail over it would refuse a
+ * call the delegate is entitled to make and would apply the caller's redactions inside
+ * another agent's grant. That is the native loop's semantic too -- `#delegate` opens a frame
+ * for the target and drives it, so the target's `tool-call` stage is what runs and the
+ * caller's does not cross the boundary.
+ */
+export function guardrailMiddleware(options) {
+    const { host, frame, principal, memoryKey } = options;
+    return {
+        name: 'aid-guardrails',
+        async wrapToolCall(request, handler) {
+            const call = asCall(request.toolCall);
+            if (call.name === DELEGATE_TOOL)
+                return await handler(request);
+            host.authorize(frame.agent, call, principal);
+            const guarded = host.guardrailToolCalls(frame, [call], memoryKey);
+            if (guarded.paused !== undefined)
+                throw new HaltError(guarded.paused);
+            const rewritten = guarded.calls[0];
+            if (rewritten !== undefined &&
+                canonicalJson(rewritten.arguments) !== canonicalJson(call.arguments)) {
+                // A redaction rewrote the arguments; the tool must see the rewritten ones, not the
+                // model's originals.
+                return await handler({
+                    ...request,
+                    toolCall: { ...request.toolCall, args: rewritten.arguments },
+                });
+            }
+            return await handler(request);
+        },
+    };
+}
+//# sourceMappingURL=guardrail_middleware.js.map

package/dist/agents/guardrail_middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail_middleware.js","sourceRoot":"","sources":["../../src/agents/guardrail_middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,OAAO,CAAU;IAE1B,YAAY,OAAgB;QAC1B,KAAK,CAAC,2DAA2D,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,mDAAmD;AACnD,SAAS,MAAM,CAAC,GAAmE;IACjF,OAAO,IAAI,QAAQ,CAAC;QAClB,EAAE,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,IAAI,IAAI,WAAW;QACrC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;QACpB,SAAS,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;KAC1B,CAAC,CAAC;AACL,CAAC;AAUD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACrE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACtD,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,KAAK,CAAC,YAAY,CAChB,OAAwB,EACxB,OAAwB;YAExB,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACtC,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa;gBAAE,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;YAE/D,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;YAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC;YAClE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;gBAAE,MAAM,IAAI,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtE,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnC,IACE,SAAS,KAAK,SAAS;gBACvB,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,EACpE,CAAC;gBACD,mFAAmF;gBACnF,qBAAqB;gBACrB,OAAO,MAAM,OAAO,CAAC;oBACnB,GAAG,OAAO;oBACV,QAAQ,EAAE,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,SAAS,EAAE;iBAC7D,CAAC,CAAC;YACL,CAAC;YACD,OAAO,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/agents/guardrails.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The guardrails engine: the IR's `guardrails` collection, actually evaluated.
+ *
+ * The IR already carries the *declaration* -- stages, policy kinds, an action, the fields
+ * a redaction may touch. This module is the missing other half: something that looks at
+ * text and decides. It is deliberately small and offline. Every detector is a regular
+ * expression, so the answer for a given input does not depend on a model, a network call,
+ * or a random seed, and a spec that passes here will pass here again tomorrow.
+ *
+ * Four stages, in the order a run meets them:
+ *
+ * - `input` -- before the model sees the user's turn.
+ * - `retrieval` -- around the chunks a retriever would splice into the prompt.
+ * - `tool-call` -- before a tool's handler body runs, over the call's arguments.
+ * - `output` -- after the model answers.
+ *
+ * Three decisions this module owns:
+ *
+ * **Undecidable is a block.** A guardrail naming a policy with no evaluator, or whose
+ * `redact` fields do not cover the text it matched, raises {@link GuardrailBlockedError}.
+ * There is no path from "the check could not run" to "no violation found".
+ *
+ * **Evaluation order is declaration order, except that `block` outranks it.** At one stage
+ * the engine walks the agent's guardrails in the order the IR declared them and collects
+ * every guardrail that fired. If *any* of them is a `block`, the first such guardrail
+ * decides -- a later `flag` cannot talk an earlier `block` down. Otherwise the first
+ * guardrail that fired decides.
+ *
+ * **`flag` cannot be ignored, but it does not stop anything.** A flag is recorded on the
+ * run (`RunResult.guardrails`) and the guarded text passes through unchanged. The consumer
+ * is whoever reads the run result -- an eval, a log shipper, a reviewer. It is *not* an
+ * allow: a flag means a detector matched, and the run carried on because the spec said the
+ * run may.
+ */
+import type { GuardrailDefinition } from './ir.js';
+export type GuardrailStage = 'input' | 'output' | 'retrieval' | 'tool-call';
+export type GuardrailAction = 'block' | 'redact' | 'flag' | 'escalate';
+export declare const ACTION_BLOCK: GuardrailAction;
+export declare const ACTION_REDACT: GuardrailAction;
+export declare const ACTION_FLAG: GuardrailAction;
+export declare const ACTION_ESCALATE: GuardrailAction;
+export declare const GUARDRAIL_STAGES: readonly GuardrailStage[];
+export declare const GUARDRAIL_ACTIONS: readonly GuardrailAction[];
+/** One match: which policy fired, and the half-open span it fired on. */
+export interface Detection {
+    readonly policy: string;
+    readonly start: number;
+    readonly end: number;
+}
+/** One guardrail that fired at one stage. The audit trail's unit. */
+export interface GuardrailRecord {
+    readonly guardrail: string;
+    readonly stage: GuardrailStage;
+    readonly action: GuardrailAction;
+    readonly policies: readonly string[];
+    readonly message: string;
+}
+/**
+ * A guardrail that entered human-in-the-loop instead of deciding by itself.
+ *
+ * `text` is the guarded payload, kept so that approving an `output` escalation can release
+ * the model's answer without re-running the model -- and so that a rejection can show the
+ * human what they rejected.
+ */
+export interface GuardrailEscalation {
+    readonly guardrail: string;
+    readonly stage: GuardrailStage;
+    readonly message: string;
+    readonly channel: string;
+    readonly text: string;
+}
+/**
+ * The engine's answer for one stage of one turn.
+ *
+ * `records` is every guardrail that fired, not only the deciding one: a `flag` next to a
+ * `block` still has to reach the audit trail. `action` and `deciding` are the outcome;
+ * `text` and `arguments` are the payload after any `redact` was applied.
+ */
+export interface GuardrailVerdict {
+    readonly stage: GuardrailStage;
+    readonly records: readonly GuardrailRecord[];
+    readonly action: string | undefined;
+    readonly deciding: GuardrailRecord | undefined;
+    readonly text: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+/** Whether any guardrail matched, whatever it decided to do about it. */
+export declare function fired(verdict: GuardrailVerdict): boolean;
+/**
+ * One entry per `GuardrailPolicyKind` in `packages/ir/src/shapes.ts`.
+ *
+ * These are *heuristics*, and saying so is the honest description. They catch the shapes a
+ * red-team corpus is built from -- an instruction-override phrase, a well-formed email or
+ * card-like digit run, a jailbreak persona -- and they will not catch a paraphrase.
+ */
+export declare const DETECTORS: Readonly<Record<string, readonly RegExp[]>>;
+/**
+ * Every match of `policy` in `text`, in document order.
+ *
+ * Raises {@link ConfigurationError} for an unknown policy: that is a caller bug, not
+ * untrusted input, and the engine reports it as a block before it ever gets here.
+ */
+export declare function detect(policy: string, text: string): readonly Detection[];
+/** Evaluates an agent's guardrails at one stage. */
+export declare class GuardrailEngine {
+    #private;
+    constructor(guardrails?: ReadonlyMap<string, GuardrailDefinition>);
+    declared(guardrailId: string): GuardrailDefinition | undefined;
+    checkInput(guardrails: readonly GuardrailDefinition[], text: string): GuardrailVerdict;
+    checkOutput(guardrails: readonly GuardrailDefinition[], text: string): GuardrailVerdict;
+    /**
+     * Guard what a retriever would splice into the prompt.
+     *
+     * Only the *results* are in the payload, not the query. The stage is about the text a
+     * model is handed, and putting the user's question in the same payload would let a
+     * `redact` guardrail over the `text` field fire on a violation it cannot remove -- which
+     * fails closed as a block and hides the real cause. The query's own checks belong to the
+     * `input` stage.
+     */
+    checkRetrieval(guardrails: readonly GuardrailDefinition[], results: readonly string[]): GuardrailVerdict;
+    checkToolCall(guardrails: readonly GuardrailDefinition[], toolId: string, arguments_: Readonly<Record<string, unknown>>): GuardrailVerdict;
+    check(stage: GuardrailStage, guardrails: readonly GuardrailDefinition[], payload: Readonly<Record<string, unknown>>, toolId: string | undefined): GuardrailVerdict;
+}
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/agents/guardrails.d.ts.map

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