@cogenta/agents 0.1.0

package/dist/runtime/loop.js

@@ -0,0 +1,116 @@
+import { assertProviderAllowed } from '../privacy/assert-provider-allowed.js';
+import { RepetitionGuard } from './repetition.js';
+import { retryModelCall, withTimeout } from './retry.js';
+const DEFAULT_MAX_STEPS = 25;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_REPEATS = 2;
+function addUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+    };
+}
+function toolByName(tools) {
+    return new Map(tools.map((tool) => [tool.spec.name, tool]));
+}
+async function runTool(tool, call, signal) {
+    if (tool === undefined) {
+        return { call, ok: false, error: `No tool named "${call.name}" is available in this run.` };
+    }
+    try {
+        const result = await tool.execute(call.input, { signal });
+        return { call, ok: true, output: result === undefined ? '' : JSON.stringify(result) };
+    }
+    catch (error) {
+        return { call, ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * L4 task 2: one model call, tool dispatch, repeat — with the three guards
+ * the lot's own "pièges connus" call out by name: a step ceiling, repetition
+ * detection, and per-call cost (usage) measured from the first line rather
+ * than discovered later. Permission checking (task 4) and budgets (task 8)
+ * wrap this from the outside; this loop only knows how to hold a
+ * conversation with a model and the tools it was handed.
+ */
+export async function runAgentLoop(input) {
+    const maxSteps = input.maxSteps ?? DEFAULT_MAX_STEPS;
+    const maxAttempts = input.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const now = input.now ?? Date.now;
+    const tools = input.tools ?? [];
+    const toolIndex = toolByName(tools);
+    const toolSpecs = tools.length === 0 ? undefined : tools.map((tool) => tool.spec);
+    const repetitionGuard = new RepetitionGuard(input.maxRepeats ?? DEFAULT_MAX_REPEATS);
+    const messages = [...input.messages];
+    const steps = [];
+    let totalUsage = { inputTokens: 0, outputTokens: 0 };
+    let finalText = null;
+    const runStartedAt = now();
+    for (let step = 0; step < maxSteps; step++) {
+        if (input.privacyPolicy !== undefined) {
+            assertProviderAllowed(input.client, input.privacyPolicy);
+        }
+        if (input.signal?.aborted === true) {
+            return { messages, steps, finalText, stopReason: 'cancelled', usage: totalUsage };
+        }
+        if (input.killSwitch?.isActive() === true) {
+            return { messages, steps, finalText, stopReason: 'killed', usage: totalUsage };
+        }
+        if (input.maxRunDurationMs !== undefined && now() - runStartedAt >= input.maxRunDurationMs) {
+            return { messages, steps, finalText, stopReason: 'max_duration', usage: totalUsage };
+        }
+        if (input.budget !== undefined) {
+            const check = input.budget.checkCall();
+            if (!check.allowed) {
+                if (check.reason !== undefined)
+                    input.onBudgetExceeded?.(check.reason);
+                return { messages, steps, finalText, stopReason: 'budget_exceeded', usage: totalUsage };
+            }
+        }
+        const response = await retryModelCall(() => withTimeout((signal) => input.client.chat({
+            model: input.client.model,
+            ...(input.system === undefined ? {} : { system: input.system }),
+            messages: [...messages],
+            ...(toolSpecs === undefined ? {} : { tools: toolSpecs }),
+            maxTokens: input.maxTokens,
+            ...(input.temperature === undefined ? {} : { temperature: input.temperature }),
+        }, { signal }), timeoutMs, input.signal), { maxAttempts });
+        totalUsage = addUsage(totalUsage, response.usage);
+        input.budget?.recordCall(response.usage);
+        const assistantMessage = {
+            role: 'assistant',
+            ...(response.content === null ? {} : { content: response.content }),
+            ...(response.toolCalls.length === 0 ? {} : { toolCalls: response.toolCalls }),
+        };
+        messages.push(assistantMessage);
+        if (response.content !== null)
+            finalText = response.content;
+        if (response.toolCalls.length === 0) {
+            steps.push({ response: assistantMessage, usage: response.usage, toolOutcomes: [] });
+            const stopReason = response.stopReason === 'max_tokens' ? 'max_tokens' : 'end_turn';
+            return { messages, steps, finalText, stopReason, usage: totalUsage };
+        }
+        if (response.toolCalls.some((call) => repetitionGuard.wouldRepeat(call))) {
+            steps.push({ response: assistantMessage, usage: response.usage, toolOutcomes: [] });
+            return { messages, steps, finalText, stopReason: 'repetition_detected', usage: totalUsage };
+        }
+        for (const call of response.toolCalls)
+            repetitionGuard.record(call);
+        const toolOutcomes = [];
+        for (const call of response.toolCalls) {
+            const outcome = await runTool(toolIndex.get(call.name), call, input.signal ?? new AbortController().signal);
+            toolOutcomes.push(outcome);
+            messages.push({
+                role: 'tool',
+                toolCallId: call.id,
+                toolName: call.name,
+                content: outcome.ok ? (outcome.output ?? '') : `Error: ${outcome.error ?? 'unknown error'}`,
+            });
+        }
+        steps.push({ response: assistantMessage, usage: response.usage, toolOutcomes });
+    }
+    return { messages, steps, finalText, stopReason: 'max_steps', usage: totalUsage };
+}
+//# sourceMappingURL=loop.js.map

package/dist/runtime/loop.js.map

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

package/dist/runtime/repetition.d.ts

@@ -0,0 +1,16 @@
+import type { ProviderToolCall } from '../providers/types.js';
+/**
+ * Guards against the "infinite loop" failure mode L4's own pitfalls call out:
+ * an agent that calls the same tool with the same input over and over,
+ * getting nowhere. Keys on name + a stable stringify of the input (sorted
+ * keys, so `{a:1,b:2}` and `{b:2,a:1}` count as the same call).
+ */
+export declare class RepetitionGuard {
+    private readonly seen;
+    private readonly maxRepeats;
+    constructor(maxRepeats?: number);
+    /** True once `call` has already been made `maxRepeats` times before this one. */
+    wouldRepeat(call: ProviderToolCall): boolean;
+    record(call: ProviderToolCall): void;
+}
+//# sourceMappingURL=repetition.d.ts.map

package/dist/runtime/repetition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repetition.d.ts","sourceRoot":"","sources":["../../src/runtime/repetition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE7D;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IAEnC,YAAY,UAAU,SAAI,EAEzB;IAED,iFAAiF;IACjF,WAAW,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAE3C;IAED,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAGnC;CACF"}

package/dist/runtime/repetition.js

@@ -0,0 +1,38 @@
+/**
+ * Guards against the "infinite loop" failure mode L4's own pitfalls call out:
+ * an agent that calls the same tool with the same input over and over,
+ * getting nowhere. Keys on name + a stable stringify of the input (sorted
+ * keys, so `{a:1,b:2}` and `{b:2,a:1}` count as the same call).
+ */
+export class RepetitionGuard {
+    seen = new Map();
+    maxRepeats;
+    constructor(maxRepeats = 2) {
+        this.maxRepeats = maxRepeats;
+    }
+    /** True once `call` has already been made `maxRepeats` times before this one. */
+    wouldRepeat(call) {
+        return (this.seen.get(signatureOf(call)) ?? 0) >= this.maxRepeats;
+    }
+    record(call) {
+        const key = signatureOf(call);
+        this.seen.set(key, (this.seen.get(key) ?? 0) + 1);
+    }
+}
+function signatureOf(call) {
+    return `${call.name}:${stableStringify(call.input)}`;
+}
+function stableStringify(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, entryValue]) => [key, sortKeysDeep(entryValue)]));
+    }
+    return value;
+}
+//# sourceMappingURL=repetition.js.map

package/dist/runtime/repetition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repetition.js","sourceRoot":"","sources":["../../src/runtime/repetition.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACT,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAA;IAChC,UAAU,CAAQ;IAEnC,YAAY,UAAU,GAAG,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;IAED,iFAAiF;IACjF,WAAW,CAAC,IAAsB;QAChC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAA;IACnE,CAAC;IAED,MAAM,CAAC,IAAsB;QAC3B,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;QAC7B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IACnD,CAAC;CACF;AAED,SAAS,WAAW,CAAC,IAAsB;IACzC,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAA;AACtD,CAAC;AAED,SAAS,eAAe,CAAC,KAAwC;IAC/D,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;AAC5C,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IACxD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7C,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;aACtC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAC/D,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/runtime/retry.d.ts

@@ -0,0 +1,22 @@
+export interface RetryOptions {
+    readonly maxAttempts: number;
+    /** Exponential backoff, 250ms base — injectable so tests never actually sleep. */
+    readonly delayMs?: (attempt: number) => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Retries only what a retry can plausibly fix: a dropped connection, a rate
+ * limit, a timeout. `PROVIDER_RESPONSE_INVALID` (a malformed vendor payload)
+ * and everything else is not retried — a second identical request against
+ * the same malformed state just wastes a call and a budget unit.
+ */
+export declare function retryModelCall<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+/**
+ * Races a model call against a timeout, distinguishing three outcomes: the
+ * call resolved, it was cancelled by `parentSignal` (the run's own
+ * cancellation, handled by the loop, not thrown as a timeout), or it timed
+ * out (thrown as `PROVIDER_TIMEOUT`, which `retryModelCall` treats as
+ * retryable).
+ */
+export declare function withTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, timeoutMs: number, parentSignal?: AbortSignal): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/runtime/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/runtime/retry.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C;AAMD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAkB/F;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACvC,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,WAAW,GACzB,OAAO,CAAC,CAAC,CAAC,CAyBZ"}

package/dist/runtime/retry.js

@@ -0,0 +1,69 @@
+import { CogentaError } from '@cogenta/core';
+const RETRYABLE_CODES = new Set([
+    'PROVIDER_REQUEST_FAILED',
+    'PROVIDER_RATE_LIMITED',
+    'PROVIDER_TIMEOUT',
+]);
+const DEFAULT_DELAY = (attempt) => 250 * 2 ** attempt;
+const DEFAULT_SLEEP = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Retries only what a retry can plausibly fix: a dropped connection, a rate
+ * limit, a timeout. `PROVIDER_RESPONSE_INVALID` (a malformed vendor payload)
+ * and everything else is not retried — a second identical request against
+ * the same malformed state just wastes a call and a budget unit.
+ */
+export async function retryModelCall(fn, options) {
+    const delayMs = options.delayMs ?? DEFAULT_DELAY;
+    const sleep = options.sleep ?? DEFAULT_SLEEP;
+    let lastError;
+    for (let attempt = 0; attempt < options.maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            const retryable = error instanceof CogentaError && RETRYABLE_CODES.has(error.code);
+            if (!retryable || attempt === options.maxAttempts - 1)
+                throw error;
+            await sleep(delayMs(attempt));
+        }
+    }
+    // Unreachable when maxAttempts >= 1 (the loop above always returns or throws),
+    // kept only so the function has a total return type.
+    throw lastError;
+}
+/**
+ * Races a model call against a timeout, distinguishing three outcomes: the
+ * call resolved, it was cancelled by `parentSignal` (the run's own
+ * cancellation, handled by the loop, not thrown as a timeout), or it timed
+ * out (thrown as `PROVIDER_TIMEOUT`, which `retryModelCall` treats as
+ * retryable).
+ */
+export async function withTimeout(fn, timeoutMs, parentSignal) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const onParentAbort = () => controller.abort();
+    parentSignal?.addEventListener('abort', onParentAbort);
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    try {
+        return await fn(controller.signal);
+    }
+    catch (error) {
+        if (timedOut) {
+            throw new CogentaError({
+                code: 'PROVIDER_TIMEOUT',
+                message: `The model call did not respond within ${timeoutMs}ms.`,
+                hint: 'Increase timeoutMs for this agent, or check the provider status page.',
+            });
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        parentSignal?.removeEventListener('abort', onParentAbort);
+    }
+}
+//# sourceMappingURL=retry.js.map

package/dist/runtime/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/runtime/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,yBAAyB;IACzB,uBAAuB;IACvB,kBAAkB;CACnB,CAAC,CAAA;AASF,MAAM,aAAa,GAAG,CAAC,OAAe,EAAU,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,OAAO,CAAA;AACrE,MAAM,aAAa,GAAG,CAAC,EAAU,EAAiB,EAAE,CAClD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,EAAoB,EAAE,OAAqB;IACjF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,aAAa,CAAA;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAA;IAC5C,IAAI,SAAkB,CAAA;IAEtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAC/D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,CAAA;YACjB,MAAM,SAAS,GAAG,KAAK,YAAY,YAAY,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAClF,IAAI,CAAC,SAAS,IAAI,OAAO,KAAK,OAAO,CAAC,WAAW,GAAG,CAAC;gBAAE,MAAM,KAAK,CAAA;YAClE,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;QAC/B,CAAC;IACH,CAAC;IACD,+EAA+E;IAC/E,qDAAqD;IACrD,MAAM,SAAS,CAAA;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAuC,EACvC,SAAiB,EACjB,YAA0B;IAE1B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;IACxC,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,MAAM,aAAa,GAAG,GAAS,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,CAAA;IACpD,YAAY,EAAE,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IACtD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,QAAQ,GAAG,IAAI,CAAA;QACf,UAAU,CAAC,KAAK,EAAE,CAAA;IACpB,CAAC,EAAE,SAAS,CAAC,CAAA;IAEb,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,IAAI,YAAY,CAAC;gBACrB,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,yCAAyC,SAAS,KAAK;gBAChE,IAAI,EAAE,uEAAuE;aAC9E,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,KAAK,CAAA;IACb,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAA;QACnB,YAAY,EAAE,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IAC3D,CAAC;AACH,CAAC"}

package/dist/runtime/types.d.ts

@@ -0,0 +1,78 @@
+import type { BudgetExceededReason, BudgetTracker, KillSwitch } from '../budget/types.js';
+import type { NoDataLeavesPolicy } from '../privacy/types.js';
+import type { ChatMessage, ProviderClient, ProviderToolCall, ProviderToolSpec, TokenUsage } from '../providers/types.js';
+export interface ToolExecutionContext {
+    /** The run's cancellation signal — a tool that makes its own HTTP calls should thread this through. */
+    readonly signal: AbortSignal;
+}
+/**
+ * A tool the loop can actually call. `sideEffects`/`reversible` are optional
+ * because a bare `ExecutableTool` (hand-built in a test, or from a source
+ * that never declared them) should not silently claim safety it did not
+ * declare — `withAutonomy` (task 9) treats an unset `sideEffects` as "assume
+ * side-effecting" for exactly that reason.
+ */
+export interface ExecutableTool {
+    readonly spec: ProviderToolSpec;
+    readonly sideEffects?: boolean;
+    readonly reversible?: boolean;
+    execute(input: Readonly<Record<string, unknown>>, ctx: ToolExecutionContext): Promise<unknown>;
+    /** Undoes one past call, given the receipt (that call's own output) — present exactly when `reversible` is `true` (task 10). */
+    revert?(receipt: unknown, ctx: ToolExecutionContext): Promise<void>;
+}
+export interface ToolCallOutcome {
+    readonly call: ProviderToolCall;
+    readonly ok: boolean;
+    /** The tool's return value, serialised to a string for the model — present when `ok`. */
+    readonly output?: string;
+    /** A human-readable failure reason, fed back to the model as the tool result — present when not `ok`. */
+    readonly error?: string;
+}
+export interface StepRecord {
+    readonly response: ChatMessage;
+    readonly usage: TokenUsage;
+    readonly toolOutcomes: readonly ToolCallOutcome[];
+}
+export type RunStopReason = 'end_turn' | 'max_tokens' | 'max_steps' | 'repetition_detected' | 'cancelled' | 'budget_exceeded' | 'max_duration' | 'killed'
+/** The run threw instead of returning — e.g. a model call's retries were exhausted (task 11: this is how `runSubagent` reports a sub-agent's crash as data instead of an exception, so it cannot propagate into the parent's own loop). */
+ | 'errored';
+export interface RunResult {
+    readonly messages: readonly ChatMessage[];
+    readonly steps: readonly StepRecord[];
+    /** The last assistant turn's text — `null` if the run stopped before producing one. */
+    readonly finalText: string | null;
+    readonly stopReason: RunStopReason;
+    readonly usage: TokenUsage;
+    /** Set only when `stopReason` is `'errored'` — the caught error's message. */
+    readonly error?: string;
+}
+export interface RunAgentLoopInput {
+    readonly client: ProviderClient;
+    readonly messages: readonly ChatMessage[];
+    readonly system?: string;
+    readonly tools?: readonly ExecutableTool[];
+    readonly maxTokens: number;
+    readonly temperature?: number;
+    /** Hard ceiling on model-call turns — the "infinite loop" backstop (default 25). */
+    readonly maxSteps?: number;
+    /** Per model call, including retries (default 3). */
+    readonly maxAttempts?: number;
+    /** Per model call attempt (default 60_000ms). */
+    readonly timeoutMs?: number;
+    /** How many times an identical tool call (name + input) may repeat before the run stops (default 2). */
+    readonly maxRepeats?: number;
+    readonly signal?: AbortSignal;
+    /** Checked before every model call; a call that would exceed it never happens ("arrêt propre et alerte, jamais dégradation silencieuse"). */
+    readonly budget?: BudgetTracker;
+    /** Checked before every model call — an explicit, human-flipped stop, independent of budgets. */
+    readonly killSwitch?: KillSwitch;
+    /** The alert half of a budget stop — called once, with which limit tripped, right before the run returns. */
+    readonly onBudgetExceeded?: (reason: BudgetExceededReason) => void;
+    /** Wall-clock ceiling for the whole run — "durée maximale par run", the fourth budget dimension the lot's design section names, checked independently of `BudgetTracker` since it belongs to one run, not to the agent's calendar-bucketed totals. */
+    readonly maxRunDurationMs?: number;
+    /** Clock the loop measures `maxRunDurationMs` against — injectable for tests, defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** "Mode « rien ne sort »" (task 21) — checked before every model call; an out-of-allowlist provider throws instead of returning a stop reason, since a privacy leak is a configuration error, not a run outcome to record. */
+    readonly privacyPolicy?: NoDataLeavesPolicy;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

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

package/dist/runtime/types.js

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

package/dist/runtime/types.js.map

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

package/dist/sandbox/types.d.ts

@@ -0,0 +1,20 @@
+import type { DiffEntry } from '../reversibility/diff.js';
+/**
+ * "Un agent peut être exécuté contre une copie du site, en lecture réelle et
+ * écriture simulée, avec production des diffs qu'il aurait appliqués."
+ */
+export interface SandboxCallResult {
+    /**
+     * `true` when the write genuinely ran, against the copy, and was
+     * immediately undone via the tool's own `revert()` — a real dry run, not
+     * a guess. `false` when the tool has no `revert()`: there is no safe way
+     * to undo it on the copy, so it was never called at all, not even once.
+     */
+    readonly simulated: boolean;
+    /** The tool's own output from the reverted call — present only when `simulated` is `true`. */
+    readonly wouldHaveApplied?: unknown;
+    /** `diffValues(before, after)` around the reverted call — present only when both a `snapshot()` was supplied and `simulated` is `true`. */
+    readonly diff?: readonly DiffEntry[];
+    readonly note: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sandbox/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sandbox/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAEzD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,8FAA8F;IAC9F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IACnC,2IAA2I;IAC3I,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}

package/dist/sandbox/types.js

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

package/dist/sandbox/types.js.map

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

package/dist/sandbox/with-sandbox.d.ts

@@ -0,0 +1,26 @@
+import type { ExecutableTool } from '../runtime/types.js';
+export interface WithSandboxOptions {
+    /**
+     * Reads whatever state a diff should be computed over (e.g. the copied
+     * site's data) — called once before and once after a reverted write. No
+     * generic "read the current state" exists in this runtime (same limit
+     * `diffValues` itself documents), so without this the sandbox still
+     * simulates the write safely, it just cannot report a `diff`, only
+     * `wouldHaveApplied`.
+     */
+    readonly snapshot?: () => Promise<unknown>;
+}
+/**
+ * A read tool (`sideEffects` not `true`) is unchanged — "lecture réelle".
+ * A side-effecting, reversible tool is genuinely called against the copy and
+ * immediately reverted — "écriture simulée": the copy ends the call in the
+ * same state it started in, but what the call produced (and, with
+ * `snapshot`, a real before/after diff) is captured and returned instead of
+ * the tool's own output. A side-effecting tool with no `revert()` is never
+ * called at all — there is no safe way to undo it on the copy, so refusing
+ * is the only sandbox-safe answer. "C'est le prérequis à toute activation en
+ * autonomie" (task 9's `autonomous` level).
+ */
+export declare function withSandbox(tool: ExecutableTool, options?: WithSandboxOptions): ExecutableTool;
+export declare function withSandboxForManifest(tools: readonly ExecutableTool[], options?: WithSandboxOptions): readonly ExecutableTool[];
+//# sourceMappingURL=with-sandbox.d.ts.map

package/dist/sandbox/with-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/with-sandbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAA;AAG/E,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CAC3C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,kBAAuB,GAC/B,cAAc,CA6BhB;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,OAAO,CAAC,EAAE,kBAAkB,GAC3B,SAAS,cAAc,EAAE,CAE3B"}

package/dist/sandbox/with-sandbox.js

@@ -0,0 +1,41 @@
+import { diffValues } from '../reversibility/diff.js';
+/**
+ * A read tool (`sideEffects` not `true`) is unchanged — "lecture réelle".
+ * A side-effecting, reversible tool is genuinely called against the copy and
+ * immediately reverted — "écriture simulée": the copy ends the call in the
+ * same state it started in, but what the call produced (and, with
+ * `snapshot`, a real before/after diff) is captured and returned instead of
+ * the tool's own output. A side-effecting tool with no `revert()` is never
+ * called at all — there is no safe way to undo it on the copy, so refusing
+ * is the only sandbox-safe answer. "C'est le prérequis à toute activation en
+ * autonomie" (task 9's `autonomous` level).
+ */
+export function withSandbox(tool, options = {}) {
+    if (tool.sideEffects !== true)
+        return tool;
+    return {
+        ...tool,
+        async execute(input, ctx) {
+            if (tool.revert === undefined) {
+                return {
+                    simulated: false,
+                    note: `"${tool.spec.name}" has no revert() — refusing to run it even once, since the sandbox could not undo it on the copied site.`,
+                };
+            }
+            const before = await options.snapshot?.();
+            const output = await tool.execute(input, ctx);
+            const after = await options.snapshot?.();
+            await tool.revert(output, ctx);
+            return {
+                simulated: true,
+                wouldHaveApplied: output,
+                note: `"${tool.spec.name}" ran against the copy and was immediately reverted — a simulated write.`,
+                ...(before === undefined || after === undefined ? {} : { diff: diffValues(before, after) }),
+            };
+        },
+    };
+}
+export function withSandboxForManifest(tools, options) {
+    return tools.map((tool) => withSandbox(tool, options));
+}
+//# sourceMappingURL=with-sandbox.js.map

package/dist/sandbox/with-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-sandbox.js","sourceRoot":"","sources":["../../src/sandbox/with-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAgBrD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,IAAoB,EACpB,OAAO,GAAuB,EAAE;IAEhC,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IAE1C,OAAO;QACL,GAAG,IAAI;QACP,KAAK,CAAC,OAAO,CACX,KAAwC,EACxC,GAAyB;YAEzB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC9B,OAAO;oBACL,SAAS,EAAE,KAAK;oBAChB,IAAI,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,2GAA2G;iBACpI,CAAA;YACH,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAA;YACzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YAC7C,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAA;YACxC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;YAE9B,OAAO;gBACL,SAAS,EAAE,IAAI;gBACf,gBAAgB,EAAE,MAAM;gBACxB,IAAI,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,0EAA0E;gBAClG,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;aAC5F,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,KAAgC,EAChC,OAA4B;IAE5B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;AACxD,CAAC"}

package/dist/skills/file-store.d.ts

@@ -0,0 +1,13 @@
+import type { SkillStore } from './types.js';
+/**
+ * A skill is a folder — `<dir>/<name>/SKILL.md` plus whatever resource files
+ * sit alongside it — under `options.dir`. No external service (R1): this is
+ * the whole store, the same "real but local" tier the trace/media file
+ * stores already use. `list()` only reads each `SKILL.md`'s frontmatter, so
+ * scanning many skills stays cheap; the (potentially large) instructions
+ * body and resource file names are read only by `load()`, on demand.
+ */
+export declare function createFileSkillStore(options: {
+    readonly dir: string;
+}): SkillStore;
+//# sourceMappingURL=file-store.d.ts.map

package/dist/skills/file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../../src/skills/file-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAwB,UAAU,EAAE,MAAM,YAAY,CAAA;AAIlE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CA+DlF"}

package/dist/skills/file-store.js

@@ -0,0 +1,73 @@
+import { cp, mkdir, readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { CogentaError } from '@cogenta/core';
+import { parseSkillFile } from './frontmatter.js';
+const SKILL_FILE = 'SKILL.md';
+/**
+ * A skill is a folder — `<dir>/<name>/SKILL.md` plus whatever resource files
+ * sit alongside it — under `options.dir`. No external service (R1): this is
+ * the whole store, the same "real but local" tier the trace/media file
+ * stores already use. `list()` only reads each `SKILL.md`'s frontmatter, so
+ * scanning many skills stays cheap; the (potentially large) instructions
+ * body and resource file names are read only by `load()`, on demand.
+ */
+export function createFileSkillStore(options) {
+    const ready = mkdir(options.dir, { recursive: true });
+    async function readSkillFile(name) {
+        const path = join(options.dir, name, SKILL_FILE);
+        let raw;
+        try {
+            raw = await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new CogentaError({
+                    code: 'SKILL_UNKNOWN',
+                    message: `No skill named "${name}" (expected "${path}").`,
+                    hint: 'Install the skill first, or check the name against `list()`.',
+                });
+            }
+            throw error;
+        }
+        return parseSkillFile(path, raw);
+    }
+    return {
+        async list() {
+            await ready;
+            const entries = await readdir(options.dir, { withFileTypes: true }).catch(() => []);
+            const skills = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                try {
+                    const { metadata } = await readSkillFile(entry.name);
+                    skills.push(metadata);
+                }
+                catch {
+                    // A folder without a valid SKILL.md is not a skill — skip it rather than fail the whole listing.
+                }
+            }
+            return skills;
+        },
+        async load(name) {
+            await ready;
+            const { metadata, instructions } = await readSkillFile(name);
+            const skillDir = join(options.dir, name);
+            const allFiles = await readdir(skillDir, { withFileTypes: true, recursive: true });
+            const resources = allFiles
+                .filter((entry) => entry.isFile())
+                .map((entry) => relative(skillDir, join(entry.parentPath, entry.name)))
+                .filter((path) => path !== SKILL_FILE);
+            const skill = { ...metadata, instructions, dir: skillDir, resources };
+            return skill;
+        },
+        async install(sourceDir) {
+            await ready;
+            const raw = await readFile(join(sourceDir, SKILL_FILE), 'utf8');
+            const { metadata } = parseSkillFile(join(sourceDir, SKILL_FILE), raw);
+            await cp(sourceDir, join(options.dir, metadata.name), { recursive: true });
+            return metadata;
+        },
+    };
+}
+//# sourceMappingURL=file-store.js.map

package/dist/skills/file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.js","sourceRoot":"","sources":["../../src/skills/file-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGjD,MAAM,UAAU,GAAG,UAAU,CAAA;AAE7B;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAiC;IACpE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAErD,KAAK,UAAU,aAAa,CAAC,IAAY;QAIvC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,CAAA;QAChD,IAAI,GAAW,CAAA;QACf,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,MAAM,IAAI,YAAY,CAAC;oBACrB,IAAI,EAAE,eAAe;oBACrB,OAAO,EAAE,mBAAmB,IAAI,gBAAgB,IAAI,KAAK;oBACzD,IAAI,EAAE,8DAA8D;iBACrE,CAAC,CAAA;YACJ,CAAC;YACD,MAAM,KAAK,CAAA;QACb,CAAC;QACD,OAAO,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAClC,CAAC;IAED,OAAO;QACL,KAAK,CAAC,IAAI;YACR,MAAM,KAAK,CAAA;YACX,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;YACnF,MAAM,MAAM,GAAoB,EAAE,CAAA;YAClC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;oBAAE,SAAQ;gBAClC,IAAI,CAAC;oBACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;oBACpD,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;gBACvB,CAAC;gBAAC,MAAM,CAAC;oBACP,iGAAiG;gBACnG,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAA;QACf,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,IAAI;YACb,MAAM,KAAK,CAAA;YACX,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAA;YAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;YACxC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YAClF,MAAM,SAAS,GAAG,QAAQ;iBACvB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;iBACjC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;iBACtE,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,UAAU,CAAC,CAAA;YAExC,MAAM,KAAK,GAAU,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;YAC5E,OAAO,KAAK,CAAA;QACd,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,SAAS;YACrB,MAAM,KAAK,CAAA;YACX,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAAA;YAC/D,MAAM,EAAE,QAAQ,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,GAAG,CAAC,CAAA;YACrE,MAAM,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YAC1E,OAAO,QAAQ,CAAA;QACjB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/skills/frontmatter.d.ts

@@ -0,0 +1,11 @@
+import type { SkillMetadata } from './types.js';
+/**
+ * Deliberately not a YAML parser (R9: no new dependency for three flat
+ * string fields) — `---\nkey: value\n---\nbody`, one `key: value` per line,
+ * nothing nested.
+ */
+export declare function parseSkillFile(path: string, raw: string): {
+    readonly metadata: SkillMetadata;
+    readonly instructions: string;
+};
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/skills/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/skills/frontmatter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAI/C;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV;IAAE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAsCrE"}