@kindgi/agents 0.1.1 → 0.1.3

package/src/handlers/public-types.ts

@@ -2,13 +2,13 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { Principal } from '@kindgi/authz';
-import type { ProviderRegistry, TenantPolicy } from '@kindgi/capabilities';
+import type { ProviderRegistry, TenantPolicy, UsageSink } from '@kindgi/capabilities';
 import type { EmbeddingProviderRegistry } from '@kindgi/embedding';
 import type { MemoryQueryBinding } from '@kindgi/memory';
 import type { PolicyRegistry } from '@kindgi/policy-contract';
 import type { ParentRunRef, RunBinding } from '@kindgi/runtime';
 import type { ToolRegistry, ToolSecretRef } from '@kindgi/tools';
-import type { ProjectId, ProvenanceId, RunId, TenantId, Timestamp } from '@kindgi/types';
+import type { OrgId, ProjectId, ProvenanceId, RunId, TenantId, Timestamp } from '@kindgi/types';
 
 import type { ConversationBinding } from '../conversation-binding.js';
 import type { GuardrailsBindings } from '../guardrails-gate.js';
@@ -32,6 +32,12 @@ export interface InvokeAgentInput {
    * at the caller layer.
    */
   readonly projectId: ProjectId;
+  /**
+   * The project's org, when it belongs to one: the runtime resolves it
+   * from the project, never from input. The turn's tools get it as
+   * `ToolContext.orgId`, its guardrails as `trace.orgId`.
+   */
+  readonly orgId?: OrgId;
   readonly agent: Agent;
   readonly conversationId: ConversationId;
   readonly userMessage: string;
@@ -153,6 +159,12 @@ export interface InvokeAgentBindings extends GuardrailsBindings {
   readonly onEvent?: OnTurnEvent;
   readonly provenance?: ProvenanceBindings;
   readonly hitl?: HitlBindings;
+  /**
+   * Where the turn records each model call (the runtime's cost ledger):
+   * its usage, provider, model, run, agent and step, before the step
+   * that made it goes on. Absent: calls aren't recorded.
+   */
+  readonly usage?: UsageSink;
   /**
    * Declarative HTTP tools: optional secret resolver populated
    * from the deployment's tenant-scoped `SecretBinding`. When present,
@@ -171,6 +183,8 @@ export interface HitlBindings {
 
 export interface HitlEnqueueInput {
   readonly tenantId: TenantId;
+  /** The turn's project: approval lists filter by it. */
+  readonly projectId?: ProjectId;
   readonly subjectKind: string;
   readonly subjectRef: Readonly<Record<string, unknown>>;
   readonly requiredRole?: 'standard' | 'senior' | 'admin';

package/src/handlers/rehydrate.ts

@@ -27,26 +27,45 @@
  * A turn parked inside `setup` (the session gate) re-runs `setup`, and
  * nothing here applies.
  *
- * Not restored: provenance nodes recorded before the park. The resumed
- * turn's provenance covers what happens from the resume on.
+ *   - the provenance nodes of the steps that ran before the park are
+ *     added again from what they left (`turn-provenance.ts`), so a
+ *     resumed turn's DAG is whole: its user message, its retrievals, each
+ *     model call, and the tool calls of each completed step. The step the
+ *     turn parked in adds its own when it runs again;
+ *   - the tool-call approvals decided so far come from the journal (the
+ *     waitpoint each gate recorded, when the call parked, the decision
+ *     and when it came), so each call's provenance shows the approval it
+ *     waited on and who decided it.
  */
 
 import type { LoopContext } from '@kindgi/handler';
-import { type JournalEntry, bodyStepKey } from '@kindgi/runtime';
+import { type JournalEntry, type ValueRecordedPayload, bodyStepKey } from '@kindgi/runtime';
+import type { Timestamp } from '@kindgi/types';
 
 import type { ConversationMessage, RetrievedFact } from '../types.js';
 import type { TurnContext } from './context.js';
 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';
+import type { ToolApproval } from './turn-provenance.js';
 
 interface StepRecord {
   readonly nodeId: string;
   readonly output: unknown;
   readonly inLoop: boolean;
+  /** When the step completed. */
+  readonly at: Timestamp;
 }
 
 /** Each step's last completion — a step at one loop iteration counts once. */
@@ -67,6 +86,7 @@ function completedSteps(journal: readonly JournalEntry[]): readonly StepRecord[]
       nodeId: e.nodeId as unknown as string,
       output: payload.output,
       inLoop: payload.loopContext !== undefined,
+      at: e.timestamp,
     });
   }
   return [...byStep.values()];
@@ -129,9 +149,106 @@ export async function rehydrateTurnContext(
     ctx.usage.totalCostUsd += out.iterationUsage?.costUsd ?? 0;
     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: readonly JournalEntry[]): ReadonlyMap<string, ToolApproval> {
+  const callOf = new Map<string, string>();
+  const parkedAt = new Map<string, Timestamp>();
+  const resumed = new Map<string, { readonly at: Timestamp; readonly value: unknown }>();
+  for (const e of journal) {
+    const gate = toolGateOf(e);
+    if (gate !== undefined) callOf.set(gate.waitTokenId, gate.invocationId);
+    const p = (e.payload ?? {}) as { readonly tokenId?: unknown; readonly value?: unknown };
+    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<string, ToolApproval>();
+  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: JournalEntry,
+): { readonly waitTokenId: string; readonly invocationId: string } | undefined {
+  if (e.kind !== 'value.recorded') return undefined;
+  const p = (e.payload ?? {}) as Partial<ValueRecordedPayload>;
+  if (typeof p.key !== 'string' || !p.key.startsWith(TOOL_GATE_RECORD_PREFIX)) return undefined;
+  const waitTokenId = (p.value as { readonly waitTokenId?: unknown } | undefined)?.waitTokenId;
+  return typeof waitTokenId === 'string'
+    ? { waitTokenId, invocationId: p.key.slice(TOOL_GATE_RECORD_PREFIX.length) }
+    : undefined;
+}
+
+/** A completed model-call step's output, as far as provenance reads it. */
+interface ModelCallStepOutput {
+  readonly step?: number;
+  readonly callId?: string;
+  readonly finishReason?: string;
+  readonly provider?: { readonly id: string; readonly model: string };
+}
+
+/**
+ * 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: TurnContext,
+  steps: readonly StepRecord[],
+  retrieved: readonly RetrievedFact[] | undefined,
+): void {
+  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<number, readonly ConversationMessage[]>();
+  for (const s of steps.filter((s) => s.nodeId === 'dispatch-tools' && s.inLoop)) {
+    const out = s.output as {
+      readonly step?: number;
+      readonly iterationAppended?: readonly ConversationMessage[];
+    };
+    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 as ModelCallStepOutput }))
+    .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/src/handlers/run-retrievals.ts

@@ -8,6 +8,7 @@ import { emitTurnEvent } from '../streaming.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { addRetrievalNodes } from './turn-provenance.js';
 
 /**
  * Execute the agent's declared retrieval intents. Populates
@@ -49,25 +50,7 @@ export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
     });
 
     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

package/src/handlers/setup.ts

@@ -11,12 +11,14 @@ import { emitTurnEvent } from '../streaming.js';
 
 import type { TurnContext } from './context.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
@@ -34,14 +36,21 @@ function computeSessionGateWaitToken(input: {
     .slice(0, 40);
 }
 
+/** The `record` key of the session gate's decision. */
+const SESSION_GATE_RECORD = 'session-hitl-gate';
+
 /**
- * Shape the setup handler expects when a session-gate waitpoint
- * resolves. Approvals-complete route materializes this from the
- * reviewer's decision (see packages/api/src/routes/approvals.ts).
+ * The session gate's decision, as `setup` records it the first time
+ * the gate asks for a review: the wait it parks on, and the review it asks
+ * for. A turn resumed after the park reads it back instead of deciding again.
  */
-interface SessionGateDecision {
-  readonly decided: 'approve' | 'reject';
-  readonly rationale?: string;
+interface SessionGateRecord {
+  readonly waitTokenId: string;
+  readonly turnCount: number;
+  readonly threshold: number;
+  readonly reason: string;
+  readonly requiredRole: 'standard' | 'senior' | 'admin';
+  readonly timeoutMs: number;
 }
 
 /**
@@ -111,33 +120,46 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
     // `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 as unknown as string,
+    // 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, (): SessionGateRecord | undefined => {
+      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 as unknown as string,
+          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 as never,
@@ -153,8 +175,8 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
       // 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,
@@ -163,17 +185,19 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
           actor: `agent:${ctx.input.agent.id as unknown as string}`,
           attributes: {
             gate: 'session-hitl',
-            turnCount: conversation.turnCount,
-            threshold: sessionGate.threshold,
+            turnCount: gate.turnCount,
+            threshold: gate.threshold,
             waitTokenId,
           },
         });
       }
 
       try {
-        const decision = await kctx.waitForToken<SessionGateDecision>(waitTokenId, {
-          timeoutMs,
-        });
+        // Fails closed: only an explicit approve lets the turn go on
+        // (`readGateDecision`).
+        const decision = readGateDecision(
+          await kctx.waitForToken<unknown>(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.
@@ -182,11 +206,14 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
             id: resumeNodeId,
             kind: 'resume',
             timestamp: new Date().toISOString() as never,
-            actor: `agent:${ctx.input.agent.id as unknown as string}`,
+            // Whoever decided; a decision recorded before it named them, the agent.
+            actor: decision.decidedBy ?? `agent:${ctx.input.agent.id as unknown as string}`,
             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({
@@ -196,7 +223,7 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
           });
         }
 
-        if (decision.decided === 'reject') {
+        if (!decision.approved) {
           throwAgentTurnFailure({
             code: 'hitl-rejected',
             message: `Reviewer rejected the session-HITL gate${
@@ -205,8 +232,7 @@ export function buildSetupHandler(ctx: TurnContext): NodeHandler {
             ...(decision.rationale !== undefined && { rationale: decision.rationale }),
           } as never);
         }
-        // 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) {
           // Emit resume node with cancelled attribute so the DAG still

package/src/handlers/tool-hitl.ts

@@ -83,6 +83,12 @@ function canonicalStringify(value: unknown): string {
   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
@@ -100,16 +106,6 @@ export function computeToolCallWaitToken(input: {
     .slice(0, 40);
 }
 
-/**
- * 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