agentfootprint 7.3.1 → 7.5.0

package/dist/esm/core/checkin.d.ts

@@ -0,0 +1,263 @@
+/**
+ * checkin — the evidence-carrying human-consent primitive.
+ *
+ * "OpenWorker-class agents check in; agentfootprint checks in WITH THE
+ * RECEIPTS." A tool declares `checkIn` (see `Tool.checkIn` in `core/tools.ts`); when
+ * it trips, the tool-dispatch loop pauses BEFORE executing and surfaces a
+ * {@link CheckInRequest} — a typed ask that carries an EVIDENCE PACK
+ * ({@link CheckInEvidence}): what the tool will do, what context the run
+ * consumed, which context drove the choice, and a compact run-so-far trail.
+ * A human answers with {@link checkInApproved} / {@link checkInDeclined};
+ * the {@link CheckInDecision} lands as a typed record.
+ *
+ * This is the LEAF that owns every check-in TYPE + the pure assembly logic.
+ * It has zero runtime/engine imports (only type-only imports of the message
+ * shape + the influence-core attribution unit), so it stays cheap to import
+ * and trivial to unit-test. The pause plumbing lives in
+ * `core/agent/stages/toolCalls.ts`; the events in `events/`; the store in
+ * `recorders/core/CheckInRecorder.ts`.
+ *
+ * NOT a policy engine (the `PermissionChecker` in `adapters/types.ts` is
+ * untouched, and runs BEFORE this gate) and NOT UI. This asks a person to
+ * CONSENT, with the receipts attached.
+ *
+ * Pattern: Strategy (pluggable evidence assembler + driver scorer) + pure
+ *          value types. Every value here survives `structuredClone` + JSON
+ *          (checkpoint discipline) — no functions, no class instances.
+ */
+import type { LLMMessage } from '../adapters/types.js';
+import type { AttributionUnit } from '../lib/influence-core/types.js';
+/**
+ * The typed pause payload for one check-in. Rides the existing pause
+ * machinery: it becomes the checkpoint's `pauseData` and is surfaced on
+ * surfaced on `RunnerPauseOutcome.checkIn` (`core/pause.ts`). JSON/clone-safe.
+ */
+export interface CheckInRequest {
+    /** The tool the agent wants to run (its name). */
+    readonly tool: string;
+    /** The arguments the model proposed for this call. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /**
+     * The model's stated reasoning for THIS call, when the assistant turn
+     * carried text alongside the tool call. Omitted when the turn was a bare
+     * tool call with no content.
+     */
+    readonly intent?: string;
+    /** The receipts riding the ask. */
+    readonly evidence: CheckInEvidence;
+}
+/**
+ * The evidence pack — the "receipts". The `'minimal'` assembler fills only
+ * {@link willDo} (zero cost); the `'standard'` assembler fills all four.
+ */
+export interface CheckInEvidence {
+    /** Plain-words claim of what will happen: the tool description + the
+     *  rendered arguments. Always present. */
+    readonly willDo: string;
+    /** What context this run consumed so far — one frame per context piece
+     *  (system rules, the user task, prior tool results). Absent under the
+     *  `'minimal'` assembler. */
+    readonly read?: readonly CheckInContextFrame[];
+    /** Which context drove THIS choice, ranked most-to-least. Produced by the
+     *  configured {@link CheckInScorer} (default: a zero-LLM lexical scorer).
+     *  Absent under the `'minimal'` assembler. */
+    readonly drivers?: readonly CheckInDriver[];
+    /** A compact grouped summary of the run so far. Absent under `'minimal'`. */
+    readonly trail?: CheckInTrail;
+}
+/** One piece of context the run consumed — role/channel + a compact summary. */
+export interface CheckInContextFrame {
+    /** Origin group: `'system' | 'task' | 'result'`. */
+    readonly channel: string;
+    /** A short, truncated summary of the piece (never the full payload). */
+    readonly summary: string;
+}
+/** One ranked driver — a context unit and how strongly it aligns with the pick. */
+export interface CheckInDriver {
+    /** The unit id (the citation, e.g. `'system-1'`). */
+    readonly id: string;
+    /** Origin group: `'system' | 'task' | 'result'`. */
+    readonly channel: string;
+    /** The unit text (quotable). */
+    readonly text: string;
+    /** Alignment score — higher means it drove the pick more. Scorer-defined
+     *  units; compare within one request, not across scorers. */
+    readonly score: number;
+}
+/** A compact grouped summary of the run so far. */
+export interface CheckInTrail {
+    /** Which ReAct iteration this check-in fired on. */
+    readonly iteration: number;
+    /** The tool calls already completed this run, oldest first. */
+    readonly toolCalls: readonly {
+        readonly name: string;
+        readonly ok: boolean;
+    }[];
+    /** One-line human summary, e.g. `"3 tools run over 2 iterations"`. */
+    readonly summary: string;
+}
+/**
+ * The human's answer to a check-in — the record that lands. Produced by
+ * {@link checkInApproved} / {@link checkInDeclined} and passed to
+ * `agent.resume(checkpoint, decision)`. JSON/clone-safe.
+ */
+export interface CheckInDecision {
+    /** True to run the tool, false to decline it. */
+    readonly approved: boolean;
+    /** Who decided (an operator id, an email, a queue name — your call). */
+    readonly by: string;
+    /** Optional note. On decline it is surfaced to the model so it can adapt. */
+    readonly note?: string;
+    /** When the decision was made (ms since epoch). */
+    readonly at: number;
+}
+/** Options for {@link checkInApproved} / {@link checkInDeclined}. */
+export interface CheckInDecisionInput {
+    /** Who decided. */
+    readonly by: string;
+    /** Optional free-text note. */
+    readonly note?: string;
+}
+/**
+ * Approve a pending check-in — the paused tool executes normally on resume.
+ *
+ * @example
+ *   const decision = checkInApproved({ by: 'alice@ops', note: 'verified with customer' });
+ *   const final = await agent.resume(outcome.checkpoint, decision);
+ */
+export declare function checkInApproved(input: CheckInDecisionInput): CheckInDecision;
+/**
+ * Decline a pending check-in — the tool is NOT executed; the model receives
+ * a `"declined by human: <note>"` tool result and adapts in-loop.
+ *
+ * @example
+ *   const decision = checkInDeclined({ by: 'alice@ops', note: 'amount too high' });
+ *   const final = await agent.resume(outcome.checkpoint, decision);
+ */
+export declare function checkInDeclined(input: CheckInDecisionInput): CheckInDecision;
+/**
+ * Type guard — is this resume input a {@link CheckInDecision}? Distinguishes
+ * a check-in answer from a plain `askHuman` tool-result value.
+ */
+export declare function isCheckInDecision(x: unknown): x is CheckInDecision;
+/**
+ * What a tool declares to demand a check-in. `'always'` trips on every call;
+ * a predicate trips selectively (e.g. only high-value refunds). A predicate
+ * that throws trips (fail toward asking the human — consequential actions
+ * should not silently proceed on a buggy predicate).
+ */
+export type CheckInDemand<TArgs = Readonly<Record<string, unknown>>> = 'always' | ((args: TArgs, ctx: CheckInPredicateContext) => boolean);
+/** Context handed to a {@link CheckInDemand} predicate. */
+export interface CheckInPredicateContext {
+    /** The current ReAct iteration. */
+    readonly iteration: number;
+    /** This tool invocation's id. */
+    readonly toolCallId: string;
+    /** The conversation so far (system, user, prior tool results). */
+    readonly history: readonly LLMMessage[];
+}
+/**
+ * Decide whether a tool's declared demand trips for this call. Returns false
+ * when the tool declared no `checkIn` (backward-compatible: byte-identical
+ * behavior for tools without the field).
+ */
+export declare function shouldCheckIn(demand: CheckInDemand<Readonly<Record<string, unknown>>> | undefined, args: Readonly<Record<string, unknown>>, ctx: CheckInPredicateContext): boolean;
+/** Input to a {@link CheckInScorer}. Mirrors `influence-core`'s attribution
+ *  shape so an embedding-backed scorer (wrapping `explainChoice`) drops in. */
+export interface CheckInScoreInput {
+    /** The chosen tool. `text` is what gets scored (name + description + args). */
+    readonly tool: {
+        readonly name: string;
+        readonly text: string;
+    };
+    /** The context units to rank against the tool. */
+    readonly units: readonly AttributionUnit[];
+    /** Abort signal for network-backed scorers. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Ranks context units by how strongly each drove one tool choice. The
+ * DEFAULT is {@link lexicalDriverScorer} — deterministic, zero LLM, zero
+ * network. Swap in a richer one via `.checkIn({ scorer })`, e.g. wrapping
+ * `explainChoice` from `agentfootprint` with your own embedder.
+ *
+ * @example a semantic scorer
+ *   const scorer: CheckInScorer = async ({ tool, units, signal }) => {
+ *     const ex = await explainChoice({ tool, units, embedder, signal });
+ *     return ex.units.map((u) => ({ id: u.id, channel: u.channel, text: u.text, score: u.score }));
+ *   };
+ */
+export type CheckInScorer = (input: CheckInScoreInput) => readonly CheckInDriver[] | Promise<readonly CheckInDriver[]>;
+/**
+ * The default drivers scorer: deterministic Jaccard token overlap between
+ * the tool text and each context unit. Zero LLM, zero network, structuredClone
+ * -safe output. Ties keep input order (stable sort).
+ */
+export declare const lexicalDriverScorer: CheckInScorer;
+/** Everything the assembler needs to build one evidence pack. */
+export interface CheckInAssemblerInput {
+    /** The chosen tool — `name` for citations, `description` for `willDo`. */
+    readonly tool: {
+        readonly name: string;
+        readonly description: string;
+    };
+    /** The proposed arguments. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** The model's stated reasoning, if any (assistant-turn text). */
+    readonly intent?: string;
+    /** The ReAct iteration this check-in fired on. */
+    readonly iteration: number;
+    /** The conversation so far — the raw material for `read`, `drivers`, `trail`. */
+    readonly history: readonly LLMMessage[];
+    /** The scorer to rank `drivers` with. */
+    readonly scorer: CheckInScorer;
+    /** Abort signal threaded to the scorer. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Builds the evidence pack for one check-in. Two are built in
+ * ({@link standardEvidenceAssembler}, {@link minimalEvidenceAssembler});
+ * pass your own to `.checkIn({ evidence })` for full control.
+ */
+export type CheckInAssembler = (input: CheckInAssemblerInput) => CheckInEvidence | Promise<CheckInEvidence>;
+/** Which built-in assembler to use, by name. */
+export type EvidencePreset = 'minimal' | 'standard';
+/**
+ * Derive attribution units from the run-so-far conversation: system rules
+ * (split into sentences), the user task, and prior tool results. These feed
+ * BOTH `read` (as frames) and `drivers` (scored). Ids are unique + stable.
+ */
+export declare function unitsFromHistory(history: readonly LLMMessage[]): AttributionUnit[];
+/**
+ * The `'standard'` assembler — fills all four evidence fields. The `drivers`
+ * ranking runs the configured scorer over the run-so-far context units; the
+ * default scorer is deterministic and makes zero LLM/network calls.
+ */
+export declare const standardEvidenceAssembler: CheckInAssembler;
+/** The `'minimal'` assembler — only `willDo`. Zero cost; no scorer call. */
+export declare const minimalEvidenceAssembler: CheckInAssembler;
+/** What `.checkIn({...})` accepts on the Agent builder. */
+export interface CheckInBuilderOptions {
+    /**
+     * How much evidence rides the ask. `'standard'` (default) fills all four
+     * fields; `'minimal'` fills only `willDo` (zero cost); or pass your own
+     * {@link CheckInAssembler}.
+     */
+    readonly evidence?: EvidencePreset | CheckInAssembler;
+    /**
+     * The scorer that ranks `drivers`. Default {@link lexicalDriverScorer}
+     * (deterministic, zero LLM). Only consulted by the `'standard'` assembler.
+     */
+    readonly scorer?: CheckInScorer;
+}
+/** The resolved config threaded into the tool-dispatch handler. */
+export interface ResolvedCheckInConfig {
+    readonly assembler: CheckInAssembler;
+    readonly scorer: CheckInScorer;
+}
+/**
+ * Resolve builder options (or nothing) into a runtime config. The default —
+ * `standard` evidence + `lexicalDriverScorer` — makes a tool that declares
+ * `checkIn` work even when the builder never called `.checkIn()`.
+ */
+export declare function resolveCheckInConfig(opts?: CheckInBuilderOptions): ResolvedCheckInConfig;

package/dist/esm/core/checkin.js

@@ -0,0 +1,254 @@
+/**
+ * checkin — the evidence-carrying human-consent primitive.
+ *
+ * "OpenWorker-class agents check in; agentfootprint checks in WITH THE
+ * RECEIPTS." A tool declares `checkIn` (see `Tool.checkIn` in `core/tools.ts`); when
+ * it trips, the tool-dispatch loop pauses BEFORE executing and surfaces a
+ * {@link CheckInRequest} — a typed ask that carries an EVIDENCE PACK
+ * ({@link CheckInEvidence}): what the tool will do, what context the run
+ * consumed, which context drove the choice, and a compact run-so-far trail.
+ * A human answers with {@link checkInApproved} / {@link checkInDeclined};
+ * the {@link CheckInDecision} lands as a typed record.
+ *
+ * This is the LEAF that owns every check-in TYPE + the pure assembly logic.
+ * It has zero runtime/engine imports (only type-only imports of the message
+ * shape + the influence-core attribution unit), so it stays cheap to import
+ * and trivial to unit-test. The pause plumbing lives in
+ * `core/agent/stages/toolCalls.ts`; the events in `events/`; the store in
+ * `recorders/core/CheckInRecorder.ts`.
+ *
+ * NOT a policy engine (the `PermissionChecker` in `adapters/types.ts` is
+ * untouched, and runs BEFORE this gate) and NOT UI. This asks a person to
+ * CONSENT, with the receipts attached.
+ *
+ * Pattern: Strategy (pluggable evidence assembler + driver scorer) + pure
+ *          value types. Every value here survives `structuredClone` + JSON
+ *          (checkpoint discipline) — no functions, no class instances.
+ */
+/**
+ * Approve a pending check-in — the paused tool executes normally on resume.
+ *
+ * @example
+ *   const decision = checkInApproved({ by: 'alice@ops', note: 'verified with customer' });
+ *   const final = await agent.resume(outcome.checkpoint, decision);
+ */
+export function checkInApproved(input) {
+    return { approved: true, by: input.by, at: Date.now(), ...(input.note && { note: input.note }) };
+}
+/**
+ * Decline a pending check-in — the tool is NOT executed; the model receives
+ * a `"declined by human: <note>"` tool result and adapts in-loop.
+ *
+ * @example
+ *   const decision = checkInDeclined({ by: 'alice@ops', note: 'amount too high' });
+ *   const final = await agent.resume(outcome.checkpoint, decision);
+ */
+export function checkInDeclined(input) {
+    return { approved: false, by: input.by, at: Date.now(), ...(input.note && { note: input.note }) };
+}
+/**
+ * Type guard — is this resume input a {@link CheckInDecision}? Distinguishes
+ * a check-in answer from a plain `askHuman` tool-result value.
+ */
+export function isCheckInDecision(x) {
+    return (typeof x === 'object' &&
+        x !== null &&
+        typeof x.approved === 'boolean' &&
+        typeof x.by === 'string');
+}
+/**
+ * Decide whether a tool's declared demand trips for this call. Returns false
+ * when the tool declared no `checkIn` (backward-compatible: byte-identical
+ * behavior for tools without the field).
+ */
+export function shouldCheckIn(demand, args, ctx) {
+    if (demand === undefined)
+        return false;
+    if (demand === 'always')
+        return true;
+    try {
+        return demand(args, ctx) === true;
+    }
+    catch {
+        // A buggy predicate must not let a consequential action slip through
+        // unreviewed — fail toward asking the human.
+        return true;
+    }
+}
+const WORD_RE = /[a-z0-9]+/g;
+const STOP = new Set([
+    'the',
+    'a',
+    'an',
+    'and',
+    'or',
+    'to',
+    'of',
+    'in',
+    'on',
+    'for',
+    'with',
+    'is',
+    'are',
+    'this',
+    'that',
+    'it',
+    'as',
+    'at',
+    'by',
+    'be',
+    'you',
+    'your',
+    'i',
+]);
+function tokenize(text) {
+    const out = new Set();
+    const lower = text.toLowerCase();
+    let m;
+    while ((m = WORD_RE.exec(lower))) {
+        if (m[0].length > 1 && !STOP.has(m[0]))
+            out.add(m[0]);
+    }
+    WORD_RE.lastIndex = 0;
+    return out;
+}
+/**
+ * The default drivers scorer: deterministic Jaccard token overlap between
+ * the tool text and each context unit. Zero LLM, zero network, structuredClone
+ * -safe output. Ties keep input order (stable sort).
+ */
+export const lexicalDriverScorer = ({ tool, units }) => {
+    const toolTokens = tokenize(tool.text);
+    const scored = units.map((u) => {
+        const unitTokens = tokenize(u.text);
+        let shared = 0;
+        for (const t of unitTokens)
+            if (toolTokens.has(t))
+                shared++;
+        const union = toolTokens.size + unitTokens.size - shared;
+        const score = union === 0 ? 0 : shared / union;
+        return { id: u.id, channel: u.channel, text: u.text, score };
+    });
+    // Stable descending sort — Array.prototype.sort is stable in modern engines.
+    return scored.sort((a, b) => b.score - a.score);
+};
+const MAX_SUMMARY = 160;
+function truncate(s, max = MAX_SUMMARY) {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+/** Render args as a compact `k=v, k=v` string (values truncated, clone-safe). */
+function renderArgs(args) {
+    const parts = Object.entries(args).map(([k, v]) => {
+        const val = typeof v === 'string' ? v : v === null || v === undefined ? String(v) : JSON.stringify(v);
+        return `${k}=${truncate(val, 60)}`;
+    });
+    return parts.join(', ');
+}
+/** Plain-words "what will happen" claim. */
+function buildWillDo(tool, args) {
+    const desc = tool.description.trim() || tool.name;
+    const rendered = renderArgs(args);
+    return rendered ? `${desc} — with ${rendered}` : desc;
+}
+/**
+ * Derive attribution units from the run-so-far conversation: system rules
+ * (split into sentences), the user task, and prior tool results. These feed
+ * BOTH `read` (as frames) and `drivers` (scored). Ids are unique + stable.
+ */
+export function unitsFromHistory(history) {
+    const units = [];
+    let sysN = 0;
+    let taskN = 0;
+    let resN = 0;
+    for (const m of history) {
+        const content = (m.content ?? '').trim();
+        if (!content)
+            continue;
+        if (m.role === 'system') {
+            // Split the system prompt into rule-sized units so a single rule can be
+            // cited. Sentence-ish split; keep non-empty pieces.
+            for (const piece of content.split(/(?<=[.!?])\s+|\n+/)) {
+                const t = piece.trim();
+                if (t)
+                    units.push({ id: `system-${++sysN}`, channel: 'system', text: t });
+            }
+        }
+        else if (m.role === 'user') {
+            units.push({ id: `task-${++taskN}`, channel: 'task', text: content });
+        }
+        else if (m.role === 'tool') {
+            units.push({
+                id: `result-${++resN}`,
+                channel: 'result',
+                text: m.toolName ? `${m.toolName}: ${content}` : content,
+            });
+        }
+    }
+    return units;
+}
+function framesFromUnits(units) {
+    return units.map((u) => ({ channel: u.channel, summary: truncate(u.text) }));
+}
+function buildTrail(history, iteration) {
+    const toolCalls = [];
+    for (const m of history) {
+        if (m.role === 'tool' && m.toolName) {
+            // A tool result whose content advertises an error is marked not-ok. The
+            // synthetic strings the loop writes ("[permission denied…]", "declined by
+            // human…", "credential error…") all read as failures here.
+            const c = (m.content ?? '').toLowerCase();
+            const ok = !(c.startsWith('[permission denied') ||
+                c.startsWith('declined by human') ||
+                c.startsWith('credential error') ||
+                c.startsWith('authorization required'));
+            toolCalls.push({ name: m.toolName, ok });
+        }
+    }
+    const summary = toolCalls.length === 0
+        ? `no tools run yet (iteration ${iteration})`
+        : `${toolCalls.length} tool${toolCalls.length === 1 ? '' : 's'} run over ${iteration} iteration${iteration === 1 ? '' : 's'}`;
+    return { iteration, toolCalls, summary };
+}
+/**
+ * The `'standard'` assembler — fills all four evidence fields. The `drivers`
+ * ranking runs the configured scorer over the run-so-far context units; the
+ * default scorer is deterministic and makes zero LLM/network calls.
+ */
+export const standardEvidenceAssembler = async (input) => {
+    const { tool, args, iteration, history, scorer, signal } = input;
+    const units = unitsFromHistory(history);
+    const willDo = buildWillDo(tool, args);
+    const read = framesFromUnits(units);
+    const trail = buildTrail(history, iteration);
+    let drivers = [];
+    if (units.length > 0) {
+        const toolText = `${tool.name} ${tool.description} ${renderArgs(args)}`.trim();
+        drivers = await scorer({
+            tool: { name: tool.name, text: toolText },
+            units,
+            ...(signal && { signal }),
+        });
+    }
+    return { willDo, read, drivers, trail };
+};
+/** The `'minimal'` assembler — only `willDo`. Zero cost; no scorer call. */
+export const minimalEvidenceAssembler = (input) => ({
+    willDo: buildWillDo(input.tool, input.args),
+});
+/**
+ * Resolve builder options (or nothing) into a runtime config. The default —
+ * `standard` evidence + `lexicalDriverScorer` — makes a tool that declares
+ * `checkIn` work even when the builder never called `.checkIn()`.
+ */
+export function resolveCheckInConfig(opts) {
+    const scorer = opts?.scorer ?? lexicalDriverScorer;
+    const evidence = opts?.evidence ?? 'standard';
+    const assembler = evidence === 'standard'
+        ? standardEvidenceAssembler
+        : evidence === 'minimal'
+            ? minimalEvidenceAssembler
+            : evidence;
+    return { assembler, scorer };
+}
+//# sourceMappingURL=checkin.js.map

package/dist/esm/core/checkin.js.map

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

package/dist/esm/core/pause.d.ts

@@ -16,6 +16,7 @@
  * the tool API clean (tools are pure-ish) while still supporting pause.
  */
 import type { FlowchartCheckpoint } from 'footprintjs';
+import type { CheckInRequest } from './checkin.js';
 /**
  * Outcome returned by `runner.run()` / `runner.resume()` when execution
  * has paused mid-flow. The shape mirrors footprintjs's `PausedResult` but
@@ -28,9 +29,32 @@ export interface RunnerPauseOutcome {
     readonly checkpoint: FlowchartCheckpoint;
     /** Data passed to `scope.$pause()` / `pauseHere()`. Consumer-typed. */
     readonly pauseData: unknown;
+    /**
+     * Present ONLY when this pause is an evidence-carrying check-in (a tool
+     * declared `checkIn`). Carries the typed ask + evidence pack. Absent for
+     * plain `askHuman` / `pauseHere` pauses — that's the clean discriminant
+     * between the two pause kinds. Resume with a `CheckInDecision`
+     * (`checkInApproved` / `checkInDeclined`).
+     */
+    readonly checkIn?: CheckInRequest;
 }
 /** Type guard — discriminates `RunnerPauseOutcome` from a normal `TOut`. */
 export declare function isPaused<T>(result: T | RunnerPauseOutcome): result is RunnerPauseOutcome;
+/**
+ * Type guard — is this a check-in pause (evidence-carrying human consent),
+ * as opposed to a plain `askHuman` pause? Narrows `checkIn` to present.
+ *
+ * @example
+ *   const out = await agent.run({ message });
+ *   if (isCheckInPause(out)) {
+ *     showToHuman(out.checkIn.evidence);       // the receipts
+ *     const decision = checkInApproved({ by: 'alice' });
+ *     await agent.resume(out.checkpoint, decision);
+ *   }
+ */
+export declare function isCheckInPause(result: unknown): result is RunnerPauseOutcome & {
+    readonly checkIn: CheckInRequest;
+};
 /**
  * Control-flow error raised by `pauseHere()` inside a tool's `execute()`.
  * Caught by the Agent's tool-call stage, which forwards to `scope.$pause()`.

package/dist/esm/core/pause.js

@@ -19,6 +19,21 @@
 export function isPaused(result) {
     return (typeof result === 'object' && result !== null && result.paused === true);
 }
+/**
+ * Type guard — is this a check-in pause (evidence-carrying human consent),
+ * as opposed to a plain `askHuman` pause? Narrows `checkIn` to present.
+ *
+ * @example
+ *   const out = await agent.run({ message });
+ *   if (isCheckInPause(out)) {
+ *     showToHuman(out.checkIn.evidence);       // the receipts
+ *     const decision = checkInApproved({ by: 'alice' });
+ *     await agent.resume(out.checkpoint, decision);
+ *   }
+ */
+export function isCheckInPause(result) {
+    return isPaused(result) && result.checkIn !== undefined;
+}
 /**
  * Control-flow error raised by `pauseHere()` inside a tool's `execute()`.
  * Caught by the Agent's tool-call stage, which forwards to `scope.$pause()`.

package/dist/esm/core/pause.js.map

@@ -1 +1 @@
-{"version":3,"file":"pause.js","sourceRoot":"","sources":["../../../src/core/pause.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAkBH,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAI,MAA8B;IACxD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAK,MAA6B,CAAC,MAAM,KAAK,IAAI,CAChG,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAU;IACvB,YAAY,IAAa;QACvB,KAAK,CAAC,cAAc,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,kEAAkE;QAClE,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,OAAO,CACL,GAAG,YAAY,YAAY;QAC3B,CAAC,GAAG,YAAY,KAAK;YACnB,GAAG,CAAC,IAAI,KAAK,cAAc;YAC3B,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CACrD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,CAAC"}
+{"version":3,"file":"pause.js","sourceRoot":"","sources":["../../../src/core/pause.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA2BH,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAI,MAA8B;IACxD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAK,MAA6B,CAAC,MAAM,KAAK,IAAI,CAChG,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAe;IAEf,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAK,MAA6B,CAAC,OAAO,KAAK,SAAS,CAAC;AAClF,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAU;IACvB,YAAY,IAAa;QACvB,KAAK,CAAC,cAAc,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,kEAAkE;QAClE,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,OAAO,CACL,GAAG,YAAY,YAAY;QAC3B,CAAC,GAAG,YAAY,KAAK;YACnB,GAAG,CAAC,IAAI,KAAK,cAAc;YAC3B,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CACrD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,CAAC"}

package/dist/esm/core/tools.d.ts

@@ -8,6 +8,7 @@
  */
 import type { LLMToolSchema } from '../adapters/types.js';
 import type { Credential, CredentialNeed, CredentialProvider } from '../identity/types.js';
+import type { CheckInDemand } from './checkin.js';
 /**
  * One executable tool the Agent can call.
  *
@@ -22,6 +23,21 @@ export interface Tool<TArgs = Record<string, unknown>, TResult = unknown> {
      *  BEFORE invoking and injects `ctx.credential`; it is NOT in `schema`, so the
      *  LLM never sees or fills it. */
     readonly needs?: CredentialNeed;
+    /**
+     * Declarative demand for a human check-in BEFORE this tool runs — consent
+     * for a consequential action, with an evidence pack riding the ask.
+     * `'always'` trips on every call; a `(args, ctx) => boolean` predicate trips
+     * selectively (e.g. only refunds over $1000). When it trips the tool-dispatch
+     * loop pauses BEFORE execute and surfaces a `CheckInRequest`; the human
+     * answers with `checkInApproved` / `checkInDeclined`. Omitted → byte-identical
+     * behavior (no gate, no events, no pause). See `.checkIn()` on the Agent
+     * builder to configure the evidence pack. Ordered AFTER the permission gate
+     * and arg-validation, BEFORE credential resolution.
+     *
+     * Non-generic here (a `Tool` widens into `Tool[]` registries); `defineTool`
+     * exposes a predicate typed to the tool's args at the CALL site.
+     */
+    readonly checkIn?: CheckInDemand;
     execute(args: TArgs, ctx: ToolExecutionContext): Promise<TResult> | TResult;
 }
 /** Runtime context passed to tool.execute(). */
@@ -69,6 +85,9 @@ export interface DefineToolOptions<TArgs, TResult> {
     /** Declare a credential this tool needs (declare-and-push). Resolved by the
      *  framework before `execute` and injected as `ctx.credential`. */
     readonly needs?: CredentialNeed;
+    /** Demand a human check-in before this tool runs (see {@link Tool.checkIn}).
+     *  `'always'` or a `(args, ctx) => boolean` predicate. */
+    readonly checkIn?: CheckInDemand<TArgs>;
     execute(args: TArgs, ctx: ToolExecutionContext): Promise<TResult> | TResult;
 }
 /**

package/dist/esm/core/tools.js

@@ -83,6 +83,9 @@ export function defineTool(options) {
             inputSchema: options.inputSchema ?? { type: 'object', properties: {} },
         },
         ...(options.needs && { needs: options.needs }),
+        // The call-site predicate is typed to TArgs; the stored Tool keeps the
+        // non-generic shape so it widens into `Tool[]` registries.
+        ...(options.checkIn !== undefined && { checkIn: options.checkIn }),
         execute: options.execute,
     };
 }

package/dist/esm/core/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAwExC;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,yDAAyD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,GAAG,EAAE;YACd,CAAC,CAAC,SAAS,IAAI,CAAC,MAAM,iBAAiB;YACvC,CAAC,CAAC,mFAAmF,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,MAAM,IAAI;YAC/C,sFAAsF;YACtF,wEAAwE;YACxE,0DAA0D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO;IACzB,IAAI,CAAC;QACH,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,4BAA6B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,OAA0C;IAE1C,qBAAqB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACvE;QACD,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC9C,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA2FxC;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,yDAAyD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,GAAG,EAAE;YACd,CAAC,CAAC,SAAS,IAAI,CAAC,MAAM,iBAAiB;YACvC,CAAC,CAAC,mFAAmF,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,MAAM,IAAI;YAC/C,sFAAsF;YACtF,wEAAwE;YACxE,0DAA0D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO;IACzB,IAAI,CAAC;QACH,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,4BAA6B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,OAA0C;IAE1C,qBAAqB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACvE;QACD,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC9C,uEAAuE;QACvE,2DAA2D;QAC3D,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAwB,EAAE,CAAC;QACnF,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC"}