@alisio/core 0.2.0 → 0.3.0

package/dist/core/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { AnalysisCapability, ArtifactPublisher, ArtifactPublishInput, ArtifactRef, CompactionCheckpoint, InstallPreview, Message, ToolCall, ToolResult } from "@alisio/sdk";
+import type { AnalysisCapability, ArtifactPublisher, ArtifactPublishInput, ArtifactRef, CompactionCheckpoint, InstallPreview, Message, RunEventDataMap, ToolCall, ToolDecisions, ToolResult } from "@alisio/sdk";
 export interface Session {
     id: string;
     workspace: string;
@@ -275,6 +275,15 @@ export type ArtifactPublisherFactory = (call: {
     runId: string;
     callId: string;
 }, announce: (published: PublishedArtifactInfo) => void) => CoreArtifactPublisher | undefined;
+/**
+ * Creates the `ToolContext.decisions` of one tool call; `announce` emits the decision event of
+ * the run (persisted and fanned out like any other). `undefined` leaves the context without it.
+ */
+export type DecisionsFactory = (call: {
+    sessionId: string;
+    runId: string;
+    callId: string;
+}, announce: <K extends "decision_completed" | "decision_fallback">(type: K, data: RunEventDataMap[K]) => void) => ToolDecisions | undefined;
 /** Optional interactive approval for write/process/external tools not pre-allowed by the Policy. */
 export type ApprovalHandler = (request: ApprovalRequest) => Promise<ApprovalDecision>;
 export interface HookFailure {

package/dist/core/human-wait.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Human waits: the moments a run is blocked on a PERSON (a tool approval, an external-directory
+ * approval, `ask_user_question`, the plan review) and not on work. The run's time limit does not
+ * count them (see `RunClock`).
+ *
+ * One registry per application. Each active run registers its clock under its session; anything
+ * that asks a person goes through `track`, which pauses the clocks involved until the answer
+ * arrives. A child session (a subagent) pauses its own clock AND its ancestors': a parent that
+ * waits for a child is doing real work, but when that child waits for a person nobody works.
+ */
+import type { RunClock } from "./run-clock.ts";
+export declare class HumanWaits {
+    private readonly parentOf;
+    private clocks;
+    constructor(parentOf?: (session: string) => string | undefined);
+    /** A run began: its clock follows the waits of its session. Returns the unregister function. */
+    register(session: string, clock: RunClock): () => void;
+    /**
+     * Opens a wait for `session` (the session asking; its ancestors are paused too). Without a
+     * session every active run is paused: somebody is being asked and nobody can say who for.
+     */
+    begin(session?: string): () => void;
+    /** Runs `wait` as a human wait: the clocks are paused until it settles, however it settles. */
+    track<T>(session: string | undefined, wait: () => Promise<T>): Promise<T>;
+}

package/dist/core/human-wait.js

@@ -0,0 +1,54 @@
+export class HumanWaits {
+    parentOf;
+    clocks = new Map();
+    constructor(parentOf = () => undefined) {
+        this.parentOf = parentOf;
+    }
+    /** A run began: its clock follows the waits of its session. Returns the unregister function. */
+    register(session, clock) {
+        this.clocks.set(session, clock);
+        return () => {
+            if (this.clocks.get(session) === clock)
+                this.clocks.delete(session);
+        };
+    }
+    /**
+     * Opens a wait for `session` (the session asking; its ancestors are paused too). Without a
+     * session every active run is paused: somebody is being asked and nobody can say who for.
+     */
+    begin(session) {
+        const releases = [];
+        if (session === undefined)
+            for (const clock of this.clocks.values())
+                releases.push(clock.pause());
+        else {
+            const seen = new Set();
+            for (let id = session; id !== undefined && !seen.has(id);) {
+                seen.add(id);
+                const clock = this.clocks.get(id);
+                if (clock)
+                    releases.push(clock.pause());
+                try {
+                    id = this.parentOf(id);
+                }
+                catch {
+                    id = undefined;
+                }
+            }
+        }
+        return () => {
+            for (const release of releases)
+                release();
+        };
+    }
+    /** Runs `wait` as a human wait: the clocks are paused until it settles, however it settles. */
+    async track(session, wait) {
+        const end = this.begin(session);
+        try {
+            return await wait();
+        }
+        finally {
+            end();
+        }
+    }
+}

package/dist/core/run-clock.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The run's time limit (`limits.timeoutMs`) as a PAUSABLE clock.
+ *
+ * The limit exists to stop runaway work (a stuck model, a looping tool), not to cap how long a
+ * person takes to read a plan or answer a question. So the clock counts ACTIVE time only: while at
+ * least one human wait is open (an approval, a question, a plan review) it is paused, and it
+ * resumes with the remaining time when the last wait ends.
+ *
+ * Waits nest and overlap (several tools can wait for approvals in parallel), so pausing is
+ * counted: the clock runs again only when every pause was released. A pause is released exactly
+ * once (the function `pause()` returns is idempotent), and a released or disposed clock ignores
+ * late calls, so an aborted run can never leave a timer behind.
+ */
+/** Time source and timers, replaceable in tests. */
+export interface ClockSource {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare class RunClock {
+    readonly limitMs: number;
+    private readonly controller;
+    private readonly source;
+    private consumed;
+    /** Start of the current running stretch (undefined while paused or finished). */
+    private since;
+    private timer;
+    private pauses;
+    private done;
+    constructor(limitMs: number, source?: ClockSource);
+    /** Aborts with a `TimeoutError` (the same reason `AbortSignal.timeout` uses) at the limit. */
+    get signal(): AbortSignal;
+    /** Whether at least one human wait is open. */
+    get paused(): boolean;
+    /** Time the run was really working: elapsed time minus every paused stretch. */
+    activeMs(): number;
+    remainingMs(): number;
+    /**
+     * Opens a human wait. Returns the function that closes it (idempotent). Pausing a clock that
+     * already ended (limit reached or disposed) does nothing.
+     */
+    pause(): () => void;
+    /** Stops the clock for good and frees its timer (call when the run ends, whatever the reason). */
+    dispose(): void;
+    private arm;
+    private disarm;
+}

package/dist/core/run-clock.js

@@ -0,0 +1,111 @@
+/**
+ * The run's time limit (`limits.timeoutMs`) as a PAUSABLE clock.
+ *
+ * The limit exists to stop runaway work (a stuck model, a looping tool), not to cap how long a
+ * person takes to read a plan or answer a question. So the clock counts ACTIVE time only: while at
+ * least one human wait is open (an approval, a question, a plan review) it is paused, and it
+ * resumes with the remaining time when the last wait ends.
+ *
+ * Waits nest and overlap (several tools can wait for approvals in parallel), so pausing is
+ * counted: the clock runs again only when every pause was released. A pause is released exactly
+ * once (the function `pause()` returns is idempotent), and a released or disposed clock ignores
+ * late calls, so an aborted run can never leave a timer behind.
+ */
+/** Longest delay a timer supports; a longer limit re-arms itself. */
+const MAX_TIMER_MS = 2_147_483_647;
+const realSource = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => {
+        const timer = setTimeout(fn, ms);
+        // Like `AbortSignal.timeout`: the limit alone never keeps the process alive.
+        timer.unref?.();
+        return timer;
+    },
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export class RunClock {
+    limitMs;
+    controller = new AbortController();
+    source;
+    consumed = 0;
+    /** Start of the current running stretch (undefined while paused or finished). */
+    since;
+    timer;
+    pauses = 0;
+    done = false;
+    constructor(limitMs, source = realSource) {
+        this.limitMs = limitMs;
+        this.source = source;
+        this.since = source.now();
+        this.arm();
+    }
+    /** Aborts with a `TimeoutError` (the same reason `AbortSignal.timeout` uses) at the limit. */
+    get signal() {
+        return this.controller.signal;
+    }
+    /** Whether at least one human wait is open. */
+    get paused() {
+        return this.pauses > 0;
+    }
+    /** Time the run was really working: elapsed time minus every paused stretch. */
+    activeMs() {
+        return (this.consumed + (this.since === undefined ? 0 : Math.max(0, this.source.now() - this.since)));
+    }
+    remainingMs() {
+        return Math.max(0, this.limitMs - this.activeMs());
+    }
+    /**
+     * Opens a human wait. Returns the function that closes it (idempotent). Pausing a clock that
+     * already ended (limit reached or disposed) does nothing.
+     */
+    pause() {
+        if (this.done)
+            return () => { };
+        if (this.pauses++ === 0) {
+            if (this.since !== undefined)
+                this.consumed += Math.max(0, this.source.now() - this.since);
+            this.since = undefined;
+            this.disarm();
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (this.done)
+                return;
+            if (--this.pauses === 0) {
+                this.since = this.source.now();
+                this.arm();
+            }
+        };
+    }
+    /** Stops the clock for good and frees its timer (call when the run ends, whatever the reason). */
+    dispose() {
+        if (this.done)
+            return;
+        this.consumed = this.activeMs();
+        this.done = true;
+        this.since = undefined;
+        this.disarm();
+    }
+    arm() {
+        this.disarm();
+        this.timer = this.source.setTimeout(() => {
+            this.timer = undefined;
+            if (this.done || this.pauses > 0)
+                return;
+            if (this.remainingMs() > 0)
+                return this.arm();
+            this.consumed = this.activeMs();
+            this.done = true;
+            this.since = undefined;
+            this.controller.abort(new DOMException("The operation timed out.", "TimeoutError"));
+        }, Math.min(this.remainingMs(), MAX_TIMER_MS));
+    }
+    disarm() {
+        if (this.timer !== undefined)
+            this.source.clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+}

package/dist/core/run-stats.d.ts

@@ -11,6 +11,8 @@ export interface RunStats {
         output: number;
     };
     toolCalls: number;
+    /** Active time of the run (waits for a person excluded). */
+    activeMs?: number;
 }
 export declare function attachRunStats(error: unknown, stats: RunStats): void;
 export declare function runStatsOf(error: unknown): RunStats | undefined;

package/dist/core/runner.d.ts

@@ -1,6 +1,7 @@
 import { type Attachment, type DatasetRef, type Message, type ModelProvider, type RunEvent, type ToolDefinition, type ToolResult } from "@alisio/sdk";
 import type { PathAccess } from "../runtime/access.ts";
-import type { ApprovalHandler, ArtifactPublisherFactory, CapabilityGate, ContextSource, Policy, RunnerExtensions, SessionStore } from "./contracts.ts";
+import type { ApprovalHandler, ArtifactPublisherFactory, CapabilityGate, ContextSource, DecisionsFactory, Policy, RunnerExtensions, SessionStore } from "./contracts.ts";
+import { HumanWaits } from "./human-wait.ts";
 import type { ToolRegistry } from "./registry.ts";
 export interface CompactionSettings {
     /** Compact automatically when context usage crosses `threshold` of a known window. */
@@ -62,6 +63,13 @@ export interface RunnerOptions {
     compaction?: CompactionSettings;
     /** When set, write/process tools not allowed by the policy are offered and ask first. */
     approve?: ApprovalHandler;
+    /**
+     * Registry of the waits for a person (approvals, questions, the plan review): the run's time
+     * limit does not count them. Share one with the plugin host and every other asking surface so a
+     * wait outside the runner (for example `ask_user_question`) pauses the same clocks. Without it
+     * the runner uses a private one, which still covers every approval it asks itself.
+     */
+    humanWaits?: HumanWaits;
     /**
      * Mediated path policy (workspace plus declared extra directories and external approval).
      * When set, declared tool paths outside the allowed roots ask before the effect gate runs.
@@ -73,6 +81,8 @@ export interface RunnerOptions {
     capabilities?: CapabilityGate;
     /** Artifact publisher of each tool call (`ToolContext.artifacts`). */
     artifacts?: ArtifactPublisherFactory;
+    /** Decision Intelligence bound to each tool call (`ToolContext.decisions`). */
+    decisions?: DecisionsFactory;
     /**
      * Provider-native tool definitions (for example a hosted `web_search` tool) appended to every
      * request's `tools` alongside the registry's function tools. Opt-in, set once for the whole
@@ -179,6 +189,8 @@ export declare class AgentRunner {
     private inbox;
     /** Last provider-reported context size per session and the history length it covered. */
     private reported;
+    /** Where human waits are opened; the clocks of the active runs listen to it. */
+    readonly humanWaits: HumanWaits;
     constructor(options: RunnerOptions);
     /** Current capability policy (may widen when the user approves an effect for the session). */
     get policy(): Readonly<Policy>;
@@ -284,5 +296,7 @@ export declare class AgentRunner {
         };
         /** Tool calls the model made during the run (the goal controller's no-progress breaker). */
         toolCalls: number;
+        /** Time the run was really working: wall time minus the waits for a person. */
+        activeMs: number;
     }>;
 }

package/dist/core/runner.js

@@ -1,7 +1,9 @@
 import { isEphemeralRunEventType, textProjection, textResult, } from "@alisio/sdk";
 import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { HumanWaits } from "./human-wait.js";
 import { EXIT_PLAN_TOOL, optInAllows } from "./opt-in.js";
 import { resolveMaxOutputTokens } from "./output-limit.js";
+import { RunClock } from "./run-clock.js";
 import { attachRunStats } from "./run-stats.js";
 import { isTimeoutReason, providerLabel, RunTimeoutError } from "./timeout.js";
 import { incompleteCalls, isOutputTruncationError, lowerEffort, RunTruncationError, TRUNCATION_NOTICE, } from "./truncation.js";
@@ -60,8 +62,20 @@ export class AgentRunner {
     inbox = new Map();
     /** Last provider-reported context size per session and the history length it covered. */
     reported = new Map();
+    /** Where human waits are opened; the clocks of the active runs listen to it. */
+    humanWaits;
     constructor(options) {
         this.options = options;
+        this.humanWaits =
+            options.humanWaits ??
+                new HumanWaits((session) => {
+                    try {
+                        return options.store.get(session).parentId ?? undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                });
     }
     /** Current capability policy (may widen when the user approves an effect for the session). */
     get policy() {
@@ -465,17 +479,20 @@ export class AgentRunner {
                     ...(options.label ? { label: options.label } : {}),
                     ...(capability ? { capability } : {}),
                 });
-                const decision = await o.approve({
+                const approve = o.approve;
+                const callInput = p.input;
+                // Waiting for the person is not work: the run's time limit does not count it.
+                const decision = await this.humanWaits.track(sessionId, () => approve({
                     call,
                     effect,
-                    input: p.input,
+                    input: callInput,
                     signal: combined,
                     session: sessionId,
                     ...(options.label ? { label: options.label } : {}),
                     ...(capability ? { capability } : {}),
                     ...(preview !== undefined ? { preview } : {}),
                     ...(capability && gate?.runtime ? { runtime: gate.runtime } : {}),
-                });
+                }));
                 combined.throwIfAborted();
                 const persisted = !!capability && !!gate && decision === "session";
                 if (capability && gate)
@@ -512,6 +529,7 @@ export class AgentRunner {
                 callId: call.id,
                 ...(published.executionId ? { executionId: published.executionId } : {}),
             }));
+            const decisions = o.decisions?.({ sessionId, runId, callId: call.id }, (type, data) => emit(type, data));
             /**
              * `analysis.install`: always asks, `once` only, and no flag or earlier grant covers it. Where
              * nobody can be asked (headless, no approval handler) the answer is `deny`.
@@ -530,7 +548,8 @@ export class AgentRunner {
                 });
                 let decision = "deny";
                 try {
-                    decision = await o.approve({
+                    const approve = o.approve;
+                    decision = await this.humanWaits.track(sessionId, () => approve({
                         call: installCall,
                         effect: "process",
                         input: { extras: install.extras },
@@ -539,7 +558,7 @@ export class AgentRunner {
                         ...(options.label ? { label: options.label } : {}),
                         capability: "analysis.install",
                         install,
-                    });
+                    }));
                 }
                 finally {
                     combined.throwIfAborted();
@@ -572,6 +591,7 @@ export class AgentRunner {
                 runId,
                 callId: call.id,
                 ...(publisher ? { artifacts: publisher } : {}),
+                ...(decisions ? { decisions } : {}),
                 approveInstall,
                 emit: (data) => emit("tool_progress", { id: call.id, data }),
                 // Only the built-in plan tool reports its durable events (never a plugin tool).
@@ -607,8 +627,12 @@ export class AgentRunner {
         }
         catch (error) {
             result = textResult(error instanceof Error ? error.message : String(error), true);
-            // A cancellation after execution may have left effects; journal remains pending.
-            if (!combined.aborted)
+            // A cancellation after execution may have left effects, so the journal stays pending for
+            // the user to inspect. A `read` call cannot have left any (and `exit_plan`, which is one,
+            // is exactly what a stop or the run limit interrupts while a person decides): it is closed
+            // with the cancellation, so the next message continues normally instead of asking to
+            // "recover" a call nobody needs to inspect.
+            if (!combined.aborted || p.tool?.effect === "read")
                 o.store.endCall(sessionId, call, result);
         }
         emit("tool_completed", {
@@ -649,10 +673,11 @@ export class AgentRunner {
             }
         };
         const runTimeoutMs = options.timeoutMs ?? o.timeoutMs ?? 300_000;
-        const timeout = AbortSignal.timeout(runTimeoutMs);
+        const clock = new RunClock(runTimeoutMs);
+        const unregisterClock = this.humanWaits.register(sessionId, clock);
         const combined = AbortSignal.any([
             controller.signal,
-            timeout,
+            clock.signal,
             ...(options.signal ? [options.signal] : []),
         ]);
         const workspace = options.workspace ?? o.workspace;
@@ -730,6 +755,8 @@ export class AgentRunner {
             throw error;
         }
         finally {
+            unregisterClock();
+            clock.dispose();
             if (acquired)
                 o.store.release(sessionId);
             this.active.delete(sessionId);
@@ -760,9 +787,14 @@ export class AgentRunner {
         /** Continuation notice and lowered effort for the request that follows a cut-off response. */
         let recoveryNotice;
         let recoveryEffort;
-        const runStartedAt = Date.now();
-        const timeout = AbortSignal.timeout(runTimeoutMs);
-        const combined = AbortSignal.any([controller.signal, timeout, ...(signal ? [signal] : [])]);
+        // Active time only: waits for a person pause it (see `RunClock`).
+        const clock = new RunClock(runTimeoutMs);
+        const unregisterClock = this.humanWaits.register(sessionId, clock);
+        const combined = AbortSignal.any([
+            controller.signal,
+            clock.signal,
+            ...(signal ? [signal] : []),
+        ]);
         // What the run was doing, so a timeout can say where it was stuck (see `RunTimeoutError`).
         let stage = "other";
         let stageTool;
@@ -1006,7 +1038,7 @@ export class AgentRunner {
                     }
                     // Do not start an attempt the whole-run limit could not let finish.
                     const retryPauseMs = FIRST_TOKEN_RETRY_PAUSE_MS;
-                    if (runTimeoutMs - (Date.now() - runStartedAt) < retryPauseMs + firstTokenMs) {
+                    if (clock.remainingMs() < retryPauseMs + firstTokenMs) {
                         if (failure !== undefined)
                             throw failure;
                         break;
@@ -1118,7 +1150,14 @@ export class AgentRunner {
                     }
                     emit("run_completed", final);
                     finish("completed");
-                    return { sessionId, text: lastText, status: "completed", usage: usageTotal, toolCalls };
+                    return {
+                        sessionId,
+                        text: lastText,
+                        status: "completed",
+                        usage: usageTotal,
+                        toolCalls,
+                        activeMs: clock.activeMs(),
+                    };
                 }
                 toolCalls += completion.calls.length;
                 const prepared = completion.calls.map((call) => {
@@ -1209,7 +1248,14 @@ export class AgentRunner {
             // token budget (`maxTokens`) and the timeout; the turn count is a safety rail.
             emit("run_turns_exceeded", { turns: maxTurns, maxTurns });
             finish("turns_exceeded");
-            return { sessionId, text: lastText, status: "turns-exceeded", usage: usageTotal, toolCalls };
+            return {
+                sessionId,
+                text: lastText,
+                status: "turns-exceeded",
+                usage: usageTotal,
+                toolCalls,
+                activeMs: clock.activeMs(),
+            };
         }
         catch (error) {
             const timedOut = silentTimedOut
@@ -1228,7 +1274,11 @@ export class AgentRunner {
                 });
                 emit("run_failed", { error: failure.message, code: "timeout", timeout: failure.info });
                 finish("failed", failure.message);
-                attachRunStats(failure, { usage: { ...usageTotal }, toolCalls });
+                attachRunStats(failure, {
+                    usage: { ...usageTotal },
+                    toolCalls,
+                    activeMs: clock.activeMs(),
+                });
                 throw failure;
             }
             if (error instanceof RunTruncationError) {
@@ -1238,7 +1288,7 @@ export class AgentRunner {
                     truncation: error.info,
                 });
                 finish("failed", error.message);
-                attachRunStats(error, { usage: { ...usageTotal }, toolCalls });
+                attachRunStats(error, { usage: { ...usageTotal }, toolCalls, activeMs: clock.activeMs() });
                 throw error;
             }
             // On cancellation report the abort reason, not the transport's secondary error.
@@ -1246,10 +1296,12 @@ export class AgentRunner {
             const message = cause instanceof Error ? cause.message : String(cause);
             emit(combined.aborted ? "run_cancelled" : "run_failed", { error: message });
             finish(combined.aborted ? "cancelled" : "failed", message);
-            attachRunStats(error, { usage: { ...usageTotal }, toolCalls });
+            attachRunStats(error, { usage: { ...usageTotal }, toolCalls, activeMs: clock.activeMs() });
             throw error;
         }
         finally {
+            unregisterClock();
+            clock.dispose();
             if (acquired)
                 o.store.release(sessionId);
             this.active.delete(sessionId);

package/dist/core/timeout.js

@@ -48,7 +48,7 @@ export function describeTimeout(info) {
         return info.firstRequest
             ? `${who} did not respond within ${limit}: no tokens were received. ` +
                 "Retry, switch to another model, or raise limits.timeoutMs."
-            : `The run reached its ${limit} limit while waiting for ${info.model ? `the model ${info.model}` : "the model"}` +
+            : `The run reached its limit of ${limit} of active time (time spent waiting for you is not counted) while waiting for ${info.model ? `the model ${info.model}` : "the model"}` +
                 `${info.provider ? ` (${info.provider})` : ""}. ` +
                 "Everything produced so far is kept: prompt again to continue, switch model, or raise limits.timeoutMs.";
     const doing = info.stage === "tool" && info.tool
@@ -56,6 +56,6 @@ export function describeTimeout(info) {
         : info.stage === "streaming"
             ? "while the model was answering"
             : "";
-    return (`The run reached its ${limit} limit${doing ? ` ${doing}` : ""}. ` +
+    return (`The run reached its limit of ${limit} of active time (time spent waiting for you is not counted)${doing ? ` ${doing}` : ""}. ` +
         "Everything produced so far is kept: prompt again to continue, or raise limits.timeoutMs.");
 }

package/dist/decisions/bound.d.ts

@@ -0,0 +1,23 @@
+import type { RunEventDataMap, ToolDecisions } from "@alisio/sdk";
+import type { DecisionOutcome, DecisionService } from "./service.ts";
+/** Reports one decision event of the run that owns the call (never persisted by the caller). */
+export type DecisionAnnouncer = <K extends "decision_completed" | "decision_fallback">(type: K, data: RunEventDataMap[K]) => void;
+/**
+ * The event of one outcome. Fields are copied one by one on purpose (ADR-7): the payload is
+ * metadata only, so nothing that rides along on the outcome can reach a persisted row.
+ */
+export declare function outcomeEvent(outcome: DecisionOutcome): {
+    type: "decision_completed";
+    data: RunEventDataMap["decision_completed"];
+} | {
+    type: "decision_fallback";
+    data: RunEventDataMap["decision_fallback"];
+};
+/**
+ * `ToolContext.decisions` of one tool call (ADR-8): the consumer surface of the service, bound to
+ * the run. Metrics are attributed to the session; the event is announced only while
+ * `decisions.telemetry` is on (read per call, so a live change applies at once).
+ */
+export declare function bindDecisions(service: DecisionService, telemetry: () => boolean, call: {
+    sessionId: string;
+}, announce: DecisionAnnouncer): ToolDecisions;

package/dist/decisions/bound.js

@@ -0,0 +1,48 @@
+/**
+ * The event of one outcome. Fields are copied one by one on purpose (ADR-7): the payload is
+ * metadata only, so nothing that rides along on the outcome can reach a persisted row.
+ */
+export function outcomeEvent(outcome) {
+    const identity = {
+        decisionId: outcome.decisionId,
+        ...(outcome.pack ? { pack: { id: outcome.pack.id, version: outcome.pack.version } } : {}),
+        provider: outcome.provider,
+        latencyMs: outcome.latencyMs,
+    };
+    if (outcome.status === "completed")
+        return {
+            type: "decision_completed",
+            data: {
+                ...identity,
+                decisionCount: outcome.decisionCount,
+                rejectedCount: outcome.rejectedCount,
+                confidenceMin: outcome.confidenceMin,
+            },
+        };
+    return { type: "decision_fallback", data: { ...identity, reason: outcome.reason } };
+}
+/**
+ * `ToolContext.decisions` of one tool call (ADR-8): the consumer surface of the service, bound to
+ * the run. Metrics are attributed to the session; the event is announced only while
+ * `decisions.telemetry` is on (read per call, so a live change applies at once).
+ */
+export function bindDecisions(service, telemetry, call, announce) {
+    return {
+        available: () => service.available(),
+        activeProvider: () => service.activeProvider(),
+        async tryDecide(req, opts) {
+            const { response, outcome } = await service.attempt(req, opts, { sessionId: call.sessionId });
+            if (outcome && telemetry()) {
+                const event = outcomeEvent(outcome);
+                // The observer path never invalidates a decision that already happened.
+                try {
+                    announce(event.type, event.data);
+                }
+                catch {
+                    /* The consumer still gets its answer. */
+                }
+            }
+            return response;
+        },
+    };
+}

package/dist/decisions/breaker.d.ts

@@ -0,0 +1,35 @@
+export type CircuitState = "closed" | "open" | "half-open";
+export interface CircuitBreakerOptions {
+    /** Consecutive counted failures that open the circuit. */
+    threshold?: number;
+    /** How long the circuit stays open before a single probe is allowed. */
+    openMs?: number;
+    now?: () => number;
+}
+/**
+ * Circuit breaker with an injected clock. The caller reports only the failures that count (the
+ * service maps provider errors to `failure()`, `success()` or `neutral()`):
+ * - `closed`: calls flow; `threshold` consecutive failures open it.
+ * - `open`: `allow()` answers "open" until `openMs` pass, then the next caller is the single probe.
+ * - `half-open`: one probe in flight; concurrent callers get "open". The probe's `success()`
+ *   closes the circuit and its `failure()` re-opens it for another `openMs`.
+ * `neutral()` ends a call that says nothing about the provider's health (a fast `not_ready`, a
+ * caller abort): it releases the probe without counting or resetting anything.
+ */
+export declare class CircuitBreaker {
+    private readonly threshold;
+    private readonly openMs;
+    private readonly now;
+    private failures;
+    private openedAt;
+    private probing;
+    constructor(options?: CircuitBreakerOptions);
+    /** Asks to run one call. "half-open" means the caller IS the single probe. */
+    allow(): CircuitState;
+    success(): void;
+    failure(): void;
+    neutral(): void;
+    reset(): void;
+    /** Read-only view for diagnostics; it never consumes the probe. */
+    state(): CircuitState;
+}