agentfootprint 7.3.1 → 7.5.0

package/dist/types/recorders/core/CheckInRecorder.d.ts

@@ -0,0 +1,91 @@
+/**
+ * CheckInRecorder — the audit record for evidence-carrying human consent.
+ *
+ * Two exports, both for `agentfootprint.checkin.*`:
+ *
+ *   • `checkInEventsBridge(...)` — an {@link EmitBridge} factory (same shape as
+ *     `costRecorder` / `permissionRecorder`). Forwards `checkin.request` /
+ *     `checkin.decision` `$emit`s to the EventDispatcher so
+ *     `agent.on('agentfootprint.checkin.*')` fires. Attached ALWAYS by the
+ *     Agent (zero-cost until a `checkIn`-declaring tool trips) — this is pure
+ *     wiring, not a store.
+ *
+ *   • `CheckInRecorder` — a compose-a-STORE recorder (no base class). Attach it
+ *     with `agent.attach(new CheckInRecorder())` to CAPTURE every ask + decision
+ *     as a queryable record — the "the decision is a record" pillar. It reads
+ *     the same `$emit` stream (footprintjs calls `onEmit` for every emit), so it
+ *     works whether or not any `agent.on(...)` listener is attached.
+ *
+ * Pattern: Factory over EmitBridge (wiring) + compose-a-store CombinedRecorder
+ *          (capture). Telemetry rides the EMIT channel — never CommitBundle.
+ */
+import type { CombinedRecorder, EmitEvent } from 'footprintjs';
+import { EmitBridge, type EmitBridgeOptions } from './EmitBridge.js';
+import type { CheckInRequest } from '../../core/checkin.js';
+export type CheckInRecorderBridgeOptions = Omit<EmitBridgeOptions, 'id' | 'prefix'> & {
+    readonly id?: string;
+};
+/**
+ * The always-on dispatcher bridge for `agentfootprint.checkin.*`. Wiring only:
+ * forwards the emits so typed `agent.on(...)` listeners fire.
+ */
+export declare function checkInEventsBridge(options: CheckInRecorderBridgeOptions): EmitBridge;
+/** One captured check-in ask. */
+export interface CheckInRequestRecord {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly iteration: number;
+    /** The typed ask + evidence pack. */
+    readonly request: CheckInRequest;
+}
+/** One captured human decision. */
+export interface CheckInDecisionRecord {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly iteration: number;
+    readonly approved: boolean;
+    readonly by: string;
+    readonly note?: string;
+}
+/** Roll-up counts across a run (or the recorder's lifetime). */
+export interface CheckInStats {
+    readonly requested: number;
+    readonly approved: number;
+    readonly declined: number;
+    /** Asks with no decision yet (paused, awaiting a human). */
+    readonly pending: number;
+}
+/**
+ * A queryable store of every check-in ask + decision. Attach once; read after
+ * the run (or between runs — it accumulates across `agent.run()` calls until
+ * you detach or make a fresh one).
+ *
+ * @example
+ *   const checkins = new CheckInRecorder();
+ *   agent.attach(checkins);
+ *   await agent.run({ message });
+ *   // ...human approves...
+ *   await agent.resume(outcome.checkpoint, checkInApproved({ by: 'alice' }));
+ *   checkins.getStats();     // { requested: 1, approved: 1, declined: 0, pending: 0 }
+ *   checkins.getDecisions(); // [{ toolName, approved: true, by: 'alice', ... }]
+ */
+export declare class CheckInRecorder implements CombinedRecorder {
+    readonly id: string;
+    private readonly requests;
+    private readonly decisions;
+    /**
+     * @param id Stable recorder id for idempotent attach/detach. Give distinct
+     *           ids if you attach more than one to the same agent.
+     */
+    constructor(id?: string);
+    onEmit(event: EmitEvent): void;
+    /** Every check-in ask captured, oldest first. */
+    getRequests(): readonly CheckInRequestRecord[];
+    /** Every human decision captured, oldest first. */
+    getDecisions(): readonly CheckInDecisionRecord[];
+    /** Roll-up counts. `pending` = asks still awaiting a decision. */
+    getStats(): CheckInStats;
+    /** Drop all captured records (e.g. between runs when reusing the recorder). */
+    reset(): void;
+}
+//# sourceMappingURL=CheckInRecorder.d.ts.map

package/dist/types/recorders/core/CheckInRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckInRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/core/CheckInRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,MAAM,MAAM,4BAA4B,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IACpF,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,4BAA4B,GAAG,UAAU,CAOrF;AAED,iCAAiC;AACjC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;CAClC;AAED,mCAAmC;AACnC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IAEzD;;;OAGG;gBACS,EAAE,SAAoC;IAIlD,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAsB9B,iDAAiD;IACjD,WAAW,IAAI,SAAS,oBAAoB,EAAE;IAI9C,mDAAmD;IACnD,YAAY,IAAI,SAAS,qBAAqB,EAAE;IAIhD,kEAAkE;IAClE,QAAQ,IAAI,YAAY;IAYxB,+EAA+E;IAC/E,KAAK,IAAI,IAAI;CAId"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "7.3.1",
+  "version": "7.5.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",