@kindgi/agents 0.1.1 → 0.1.3

package/dist/handlers/rehydrate.js

@@ -2,7 +2,10 @@
 // Copyright (C) 2026 Kindgi Inc.
 import { bodyStepKey } from '@kindgi/runtime';
 import { throwAgentTurnFailure } from './errors.js';
+import { readGateDecision } from './gate-decision.js';
+import { TOOL_GATE_RECORD_PREFIX } from './tool-hitl.js';
 import { loadTurnConversation, resolveTurnEnvironment, resolveTurnHitlPolicy, } from './turn-environment.js';
+import { addInputNode, addModelCallNode, addRetrievalNodes, addStepToolNodes, } from './turn-provenance.js';
 /** Each step's last completion — a step at one loop iteration counts once. */
 function completedSteps(journal) {
     const byStep = new Map();
@@ -18,6 +21,7 @@ function completedSteps(journal) {
             nodeId: e.nodeId,
             output: payload.output,
             inLoop: payload.loopContext !== undefined,
+            at: e.timestamp,
         });
     }
     return [...byStep.values()];
@@ -59,8 +63,89 @@ export async function rehydrateTurnContext(ctx, runId, journal) {
         if (out.provider !== undefined)
             ctx.lastProvider = out.provider;
     }
+    ctx.toolApprovals = toolApprovalsOf(journal);
+    rebuildProvenance(ctx, steps, retrievals?.retrieved);
     return true;
 }
+/**
+ * The tool-call approvals the journal shows decided, by invocation id: the
+ * waitpoint each call's gate recorded (`dispatch-tools`), when the call
+ * parked on it (`wait.suspended`, the first), and the decision that
+ * resolved it (`wait.resumed`).
+ */
+function toolApprovalsOf(journal) {
+    const callOf = new Map();
+    const parkedAt = new Map();
+    const resumed = new Map();
+    for (const e of journal) {
+        const gate = toolGateOf(e);
+        if (gate !== undefined)
+            callOf.set(gate.waitTokenId, gate.invocationId);
+        const p = (e.payload ?? {});
+        if (typeof p.tokenId !== 'string')
+            continue;
+        if (e.kind === 'wait.suspended' && !parkedAt.has(p.tokenId)) {
+            parkedAt.set(p.tokenId, e.timestamp);
+        }
+        if (e.kind === 'wait.resumed')
+            resumed.set(p.tokenId, { at: e.timestamp, value: p.value });
+    }
+    const approvals = new Map();
+    for (const [waitTokenId, decided] of resumed) {
+        const invocationId = callOf.get(waitTokenId);
+        if (invocationId === undefined)
+            continue;
+        approvals.set(invocationId, {
+            waitTokenId,
+            parkedAt: parkedAt.get(waitTokenId) ?? decided.at,
+            decidedAt: decided.at,
+            decision: readGateDecision(decided.value),
+        });
+    }
+    return approvals;
+}
+/** The waitpoint a tool call's gate recorded (`dispatch-tools`), if `e` is that record. */
+function toolGateOf(e) {
+    if (e.kind !== 'value.recorded')
+        return undefined;
+    const p = (e.payload ?? {});
+    if (typeof p.key !== 'string' || !p.key.startsWith(TOOL_GATE_RECORD_PREFIX))
+        return undefined;
+    const waitTokenId = p.value?.waitTokenId;
+    return typeof waitTokenId === 'string'
+        ? { waitTokenId, invocationId: p.key.slice(TOOL_GATE_RECORD_PREFIX.length) }
+        : undefined;
+}
+/**
+ * The provenance of the steps that ran before the park, in the order
+ * they ran: the user message, the retrievals, then each model call with
+ * the tool calls its completed step stored.
+ */
+function rebuildProvenance(ctx, steps, retrieved) {
+    const input = ctx.userMessage;
+    if (ctx.provenance === undefined || input === undefined)
+        return;
+    addInputNode(ctx.provenance, input);
+    if (retrieved !== undefined)
+        addRetrievalNodes(ctx.provenance, retrieved, input);
+    const storedByStep = new Map();
+    for (const s of steps.filter((s) => s.nodeId === 'dispatch-tools' && s.inLoop)) {
+        const out = s.output;
+        if (out.step !== undefined)
+            storedByStep.set(out.step, out.iterationAppended ?? []);
+    }
+    const calls = steps
+        .filter((s) => s.nodeId === 'model-call' && s.inLoop)
+        .map((s) => ({ at: s.at, out: s.output }))
+        .sort((a, b) => (a.out.step ?? 0) - (b.out.step ?? 0));
+    for (const { at, out } of calls) {
+        const { step, callId, provider, finishReason } = out;
+        if (step === undefined || callId === undefined || provider === undefined)
+            continue;
+        addModelCallNode(ctx.provenance, { step, callId, provider, finishReason: finishReason ?? 'stop', at }, input.sequence, [...(ctx.toolResultIds ?? [])]);
+        addStepToolNodes(ctx, step, storedByStep.get(step) ?? []);
+    }
+}
 /**
  * The messages no completed step accounts for: those the step the turn
  * parked in stored before it parked.

package/dist/handlers/rehydrate.js.map

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

package/dist/handlers/run-retrievals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-retrievals.d.ts","sourceRoot":"","sources":["../../src/handlers/run-retrievals.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA2DvE"}
+{"version":3,"file":"run-retrievals.d.ts","sourceRoot":"","sources":["../../src/handlers/run-retrievals.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAyCvE"}

package/dist/handlers/run-retrievals.js

@@ -3,6 +3,7 @@
 import { runRetrievals } from '../retrieval.js';
 import { emitTurnEvent } from '../streaming.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { addRetrievalNodes } from './turn-provenance.js';
 /**
  * Execute the agent's declared retrieval intents. Populates
  * `ctx.retrieved` for downstream prompt building + emits
@@ -36,25 +37,7 @@ export function buildRunRetrievalsHandler(ctx) {
             factIds: retrieved.value.map((r) => r.fact.id),
         });
         if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
-            for (const r of retrieved.value) {
-                ctx.provenance.addNode({
-                    id: `retrieval:${r.fact.id}`,
-                    kind: 'retrieval',
-                    timestamp: ctx.userMessage.createdAt,
-                    ...(r.fact.contentHash !== undefined && { contentHash: r.fact.contentHash }),
-                    attributes: {
-                        factId: r.fact.id,
-                        factType: r.fact.type,
-                        intentScope: r.intent.scope,
-                        ...(r.score !== undefined && { score: r.score }),
-                    },
-                });
-                ctx.provenance.addEdge({
-                    from: `retrieval:${r.fact.id}`,
-                    to: `input:${ctx.userMessage.sequence}`,
-                    kind: 'influenced-by',
-                });
-            }
+            addRetrievalNodes(ctx.provenance, retrieved.value, ctx.userMessage);
         }
         // The facts go in the journal: a resumed turn restores them from it
         // (`rehydrateTurnContext`) rather than retrieving again.

package/dist/handlers/run-retrievals.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-retrievals.js","sourceRoot":"","sources":["../../src/handlers/run-retrievals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-retrievals.js","sourceRoot":"","sources":["../../src/handlers/run-retrievals.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAgB;IACxD,OAAO,KAAK,IAAI,EAAE;QAChB,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACpE,qBAAqB,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,sEAAsE;gBAC/E,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;QACL,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,aAAa,CACnC,GAAG,CAAC,KAAK,CAAC,KAAK,EACf,GAAG,CAAC,YAAY,EAChB,GAAG,CAAC,KAAK,CAAC,cAAc,EACxB,GAAG,CAAC,KAAK,CAAC,WAAW,EACrB;YACE,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,aAAa;YAClC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,iBAAiB,KAAK,SAAS,IAAI;gBAClD,iBAAiB,EAAE,GAAG,CAAC,QAAQ,CAAC,iBAAiB;aAClD,CAAC;YACF,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,KAAK,SAAS,IAAI;gBAC/C,cAAc,EAAE,GAAG,CAAC,QAAQ,CAAC,cAAc;aAC5C,CAAC;SACH,CACF,CAAC;QACF,IAAI,SAAS,CAAC,IAAI,KAAK,KAAK;YAAE,qBAAqB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACrE,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC;QAEhC,MAAM,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE;YACxC,IAAI,EAAE,qBAAqB;YAC3B,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,MAAM;YAC7B,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;SAC/C,CAAC,CAAC;QAEH,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YAClE,iBAAiB,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;QACtE,CAAC;QAED,oEAAoE;QACpE,yDAAyD;QACzD,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;IACvE,CAAC,CAAC;AACJ,CAAC"}

package/dist/handlers/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/handlers/setup.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAmChD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAyM/D"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/handlers/setup.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AA4ChD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA0N/D"}

package/dist/handlers/setup.js

@@ -5,8 +5,10 @@ import { WaitpointCancelledError } from '@kindgi/handler';
 import { evaluateSessionGate } from '../guardrails-gate.js';
 import { emitTurnEvent } from '../streaming.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { SESSION_GATE_SUBJECT, readGateDecision } from './gate-decision.js';
 import { writeRunSnapshot } from './run-snapshot.js';
 import { loadTurnConversation, resolveTurnEnvironment, resolveTurnHitlPolicy, } from './turn-environment.js';
+import { decisionOf } from './turn-provenance.js';
 /**
  * Deterministic waitpoint token — must produce the same value on every
  * flow replay so the kernel's `waitForToken(tokenId)` resolves against
@@ -19,6 +21,8 @@ function computeSessionGateWaitToken(input) {
         .digest('hex')
         .slice(0, 40);
 }
+/** The `record` key of the session gate's decision. */
+const SESSION_GATE_RECORD = 'session-hitl-gate';
 /**
  * The first node in the flow. Runs every precondition check in one
  * gate so the run either commits to a full turn or fails fast before
@@ -83,29 +87,43 @@ export function buildSetupHandler(ctx) {
         // `hitl` policy — before the gate that may park on them.
         const effectiveHitl = await resolveTurnHitlPolicy(ctx);
         ctx.hitlPolicy = effectiveHitl;
-        const sessionGate = evaluateSessionGate({ ...(effectiveHitl.turn !== undefined && { afterTurns: effectiveHitl.turn.afterTurns }) }, conversation.turnCount);
-        if (sessionGate.kind === 'hitl-required') {
-            const waitTokenId = computeSessionGateWaitToken({
-                runId: kctx.runId,
+        // Decided once: a turn that parked here resumes on the gate it parked
+        // on, whatever the policy or the conversation's turn count say by then.
+        const gate = await kctx.record(SESSION_GATE_RECORD, () => {
+            const evaluated = evaluateSessionGate({ ...(effectiveHitl.turn !== undefined && { afterTurns: effectiveHitl.turn.afterTurns }) }, conversation.turnCount);
+            if (evaluated.kind !== 'hitl-required')
+                return undefined;
+            return {
+                waitTokenId: computeSessionGateWaitToken({
+                    runId: kctx.runId,
+                    turnCount: conversation.turnCount,
+                }),
                 turnCount: conversation.turnCount,
-            });
-            const timeoutMs = effectiveHitl.timeoutMs;
+                threshold: evaluated.threshold,
+                reason: evaluated.reason,
+                requiredRole: effectiveHitl.defaultReviewerRole,
+                timeoutMs: effectiveHitl.timeoutMs,
+            };
+        });
+        if (gate !== undefined) {
+            const { waitTokenId, timeoutMs } = gate;
             const expiresAt = new Date(Date.now() + timeoutMs).toISOString();
             if (ctx.bindings.hitl?.enqueue !== undefined) {
                 try {
                     await ctx.bindings.hitl.enqueue({
                         tenantId: ctx.input.tenantId,
-                        subjectKind: 'agent-turn:session-hitl-gate',
+                        projectId: ctx.input.projectId,
+                        subjectKind: SESSION_GATE_SUBJECT,
                         subjectRef: {
                             conversationId: ctx.input.conversationId,
                             agentId: ctx.input.agent.id,
                             agentVersion: ctx.input.agent.version,
-                            turnCount: conversation.turnCount,
-                            threshold: sessionGate.threshold,
+                            turnCount: gate.turnCount,
+                            threshold: gate.threshold,
                         },
-                        requiredRole: effectiveHitl.defaultReviewerRole,
+                        requiredRole: gate.requiredRole,
                         title: `HITL review required for ${ctx.input.agent.name}`,
-                        description: sessionGate.reason,
+                        description: gate.reason,
                         waitTokenId,
                         provenanceRef: { runId: kctx.runId },
                         expiresAt: expiresAt,
@@ -121,8 +139,8 @@ export function buildSetupHandler(ctx) {
             // execution (park), persist-provenance never runs so this node is
             // lost — that's fine. On the FINAL replay after resume, this node
             // AND the `resume` node below both emit and get persisted.
-            const waitNodeId = `session-hitl-gate-wait:${conversation.turnCount}`;
-            const resumeNodeId = `session-hitl-gate-resume:${conversation.turnCount}`;
+            const waitNodeId = `session-hitl-gate-wait:${gate.turnCount}`;
+            const resumeNodeId = `session-hitl-gate-resume:${gate.turnCount}`;
             if (ctx.provenance !== undefined) {
                 ctx.provenance.addNode({
                     id: waitNodeId,
@@ -131,16 +149,16 @@ export function buildSetupHandler(ctx) {
                     actor: `agent:${ctx.input.agent.id}`,
                     attributes: {
                         gate: 'session-hitl',
-                        turnCount: conversation.turnCount,
-                        threshold: sessionGate.threshold,
+                        turnCount: gate.turnCount,
+                        threshold: gate.threshold,
                         waitTokenId,
                     },
                 });
             }
             try {
-                const decision = await kctx.waitForToken(waitTokenId, {
-                    timeoutMs,
-                });
+                // Fails closed: only an explicit approve lets the turn go on
+                // (`readGateDecision`).
+                const decision = readGateDecision(await kctx.waitForToken(waitTokenId, { timeoutMs }));
                 // Post-resume: emit the resume node + resumed-from edge. Only
                 // runs on the REPLAY path — the first execution throws
                 // SuspensionSignal inside waitForToken and never gets here.
@@ -149,11 +167,14 @@ export function buildSetupHandler(ctx) {
                         id: resumeNodeId,
                         kind: 'resume',
                         timestamp: new Date().toISOString(),
-                        actor: `agent:${ctx.input.agent.id}`,
+                        // Whoever decided; a decision recorded before it named them, the agent.
+                        actor: decision.decidedBy ?? `agent:${ctx.input.agent.id}`,
                         attributes: {
                             gate: 'session-hitl',
-                            decision: decision.decided,
-                            ...(decision.rationale !== undefined && { rationale: decision.rationale }),
+                            decision: decisionOf(decision),
+                            ...(!decision.approved &&
+                                decision.rationale !== undefined && { rationale: decision.rationale }),
+                            ...(decision.approvalId !== undefined && { approvalId: decision.approvalId }),
                         },
                     });
                     ctx.provenance.addEdge({
@@ -162,15 +183,14 @@ export function buildSetupHandler(ctx) {
                         kind: 'resumed-from',
                     });
                 }
-                if (decision.decided === 'reject') {
+                if (!decision.approved) {
                     throwAgentTurnFailure({
                         code: 'hitl-rejected',
                         message: `Reviewer rejected the session-HITL gate${decision.rationale !== undefined ? `: ${decision.rationale}` : ''}`,
                         ...(decision.rationale !== undefined && { rationale: decision.rationale }),
                     });
                 }
-                // decision.decided === 'approve' → fall through, turn proceeds
-                // normally through the rest of setup.
+                // Approved: the turn proceeds through the rest of setup.
             }
             catch (cause) {
                 if (cause instanceof WaitpointCancelledError) {

package/dist/handlers/setup.js.map

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

package/dist/handlers/tool-hitl.d.ts

@@ -11,6 +11,11 @@ export declare function resolveToolHitl(agent: Agent, tool: Tool): ResolvedToolH
  * a different hash.
  */
 export declare function hashToolArgs(args: unknown): string;
+/**
+ * The `NodeContext.record` key of a tool call's gate, before its call id:
+ * the journal names the waitpoint a call parked on under this key.
+ */
+export declare const TOOL_GATE_RECORD_PREFIX = "tool-hitl-gate:";
 /**
  * Deterministic waitpoint token for a tool-call gate. Includes both
  * the model-generated call id (unique per iteration) AND the args hash
@@ -22,15 +27,6 @@ export declare function computeToolCallWaitToken(input: {
     readonly callId: string;
     readonly argsHash: string;
 }): string;
-/**
- * Shape the tool-level waitpoint resolves to when the reviewer decides.
- * Same shape as session-gate decisions — the approvals-complete route
- * materializes it identically.
- */
-export interface ToolHitlDecision {
-    readonly decided: 'approve' | 'reject';
-    readonly rationale?: string;
-}
 /**
  * In-conversation cache of decisions for `ask_on_first_use`. Persisted
  * on `agent_conversations.metadata.hitlToolDecisions` — a flat map of

package/dist/handlers/tool-hitl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-hitl.d.ts","sourceRoot":"","sources":["../../src/handlers/tool-hitl.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAgB,MAAM,aAAa,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;CACxD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAkC1E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAElD;AAWD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAKT;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,QAAQ,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAE7D"}
+{"version":3,"file":"tool-hitl.d.ts","sourceRoot":"","sources":["../../src/handlers/tool-hitl.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAgB,MAAM,aAAa,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;CACxD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAkC1E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAElD;AAWD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAKT;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAE7D"}

package/dist/handlers/tool-hitl.js

@@ -63,6 +63,11 @@ function canonicalStringify(value) {
     const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
     return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalStringify(v)}`).join(',')}}`;
 }
+/**
+ * The `NodeContext.record` key of a tool call's gate, before its call id:
+ * the journal names the waitpoint a call parked on under this key.
+ */
+export const TOOL_GATE_RECORD_PREFIX = 'tool-hitl-gate:';
 /**
  * Deterministic waitpoint token for a tool-call gate. Includes both
  * the model-generated call id (unique per iteration) AND the args hash

package/dist/handlers/tool-hitl.js.map

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

package/dist/handlers/turn-provenance.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The provenance nodes and edges an agent turn records, in one place:
+ * the steps add them as they run, and a turn resumed after a park
+ * (`rehydrate.ts`) adds those of the steps that ran before it from what
+ * they left durable (the conversation, the journal). Either way the DAG
+ * is the same.
+ */
+import type { ProvenanceBuilder } from '@kindgi/provenance';
+import type { Timestamp } from '@kindgi/types';
+import type { ConversationMessage, RetrievedFact } from '../types.js';
+import type { TurnContext } from './context.js';
+import type { GateDecision } from './gate-decision.js';
+/** The turn's user message. */
+export declare function addInputNode(provenance: ProvenanceBuilder, message: ConversationMessage): void;
+/** The facts the turn retrieved for its user message. */
+export declare function addRetrievalNodes(provenance: ProvenanceBuilder, retrieved: readonly RetrievedFact[], input: ConversationMessage): void;
+/** One model call: its identity; its usage is the cost ledger's, by `callId`. */
+export interface ModelCallFacts {
+    readonly step: number;
+    readonly callId: string;
+    readonly provider: {
+        readonly id: string;
+        readonly model: string;
+    };
+    readonly finishReason: string;
+    readonly at: Timestamp;
+}
+/**
+ * A model call, `caused-by` the turn's user message and `influenced-by`
+ * each of this turn's tool results it read: all of them so far, since
+ * the call's input holds every message of the turn before it.
+ */
+export declare function addModelCallNode(provenance: ProvenanceBuilder, call: ModelCallFacts, inputSequence: number, toolResultIds: readonly string[]): void;
+/**
+ * A tool call the model at `step` made, and its result: the stored tool
+ * message (a tool's output, a rejected approval's, or a failed call's).
+ * `version` is the tool the agent's binding resolved, when it has one.
+ */
+export declare function addToolNodes(provenance: ProvenanceBuilder, step: number, result: ConversationMessage, version: {
+    readonly resolvedVersion: string;
+    readonly requestedRange: string;
+} | undefined): void;
+/**
+ * The tool calls of one model step: a node pair for each result the step
+ * stored, and their invocation ids added to the turn's tool results.
+ */
+export declare function addStepToolNodes(ctx: TurnContext, step: number, stored: readonly ConversationMessage[]): void;
+/** A tool call's approval, decided: the wait it parked on and the answer. */
+export interface ToolApproval {
+    readonly waitTokenId: string;
+    /** When the call parked on the approval. */
+    readonly parkedAt: Timestamp;
+    /** When the decision reached the run. */
+    readonly decidedAt: Timestamp;
+    readonly decision: GateDecision;
+}
+/**
+ * The approval a tool call waited on, as the session gate records its own:
+ * a `wait` node (the agent parked) `resumed-from` a `resume` node (the
+ * decision, its actor whoever decided). The call `waited-on` the wait, and
+ * its result was `caused-by` the decision: the tool's output when approved,
+ * the rejection when not.
+ */
+export declare function addToolApprovalNodes(provenance: ProvenanceBuilder, invocationId: string, approval: ToolApproval, agentId: string): void;
+/** A gate decision as a `resume` node records it. */
+export declare function decisionOf(decision: GateDecision): 'approve' | 'reject' | 'unreadable';
+//# sourceMappingURL=turn-provenance.d.ts.map

package/dist/handlers/turn-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-provenance.d.ts","sourceRoot":"","sources":["../../src/handlers/turn-provenance.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,+BAA+B;AAC/B,wBAAgB,YAAY,CAAC,UAAU,EAAE,iBAAiB,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAO9F;AAED,yDAAyD;AACzD,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,iBAAiB,EAC7B,SAAS,EAAE,SAAS,aAAa,EAAE,EACnC,KAAK,EAAE,mBAAmB,GACzB,IAAI,CAoBN;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,iBAAiB,EAC7B,IAAI,EAAE,cAAc,EACpB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,IAAI,CAmBN;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,iBAAiB,EAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE;IAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GACzF,IAAI,CAuBN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,mBAAmB,EAAE,GACrC,IAAI,CAmBN;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,iBAAiB,EAC7B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,MAAM,GACd,IAAI,CA4BN;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,CAGtF"}