@kindgi/agents 0.1.2 → 0.1.4-rc.0

package/src/handlers/gate-decision.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The reviewer's answer at an agent turn's approval gates: the tool-call
+ * gate (`dispatch-tools`) and the session gate (`setup`). A gate parks the
+ * turn on a waitpoint; the approvals route resumes it with the decision
+ * (`GateDecisionValue`): approve or reject, the reviewer's rationale, and
+ * who decided which approval.
+ *
+ * A gate fails closed. Only an explicit approve lets the tool run (or the
+ * session go on). Anything else blocks: a reject, and also a resume value
+ * that isn't a decision at all (a `value` that replaced it, a malformed
+ * payload), so no answer can be read as consent by omission.
+ */
+
+/** The approval subject an agent's tool-call gate parks on. */
+export const TOOL_CALL_GATE_SUBJECT = 'tool-call:pending';
+
+/** The approval subject an agent's session gate (`afterTurns`) parks on. */
+export const SESSION_GATE_SUBJECT = 'agent-turn:session-hitl-gate';
+
+/**
+ * The approval subjects an agent turn parks on. Their resume value is the
+ * reviewer's decision and nothing else, so the approvals route takes no
+ * `value` for them.
+ */
+export const AGENT_GATE_SUBJECTS: ReadonlySet<string> = new Set([
+  TOOL_CALL_GATE_SUBJECT,
+  SESSION_GATE_SUBJECT,
+]);
+
+/**
+ * A gate's resume value: the reviewer's decision, as the approvals route
+ * (and the runtime, delivering a decision whose delivery was lost) completes
+ * the gate's waitpoint with it. The run's journal keeps it as it came.
+ */
+export interface GateDecisionValue {
+  readonly decided: 'approve' | 'reject';
+  readonly rationale?: string;
+  /**
+   * Who decided, as an actor: `user:<userId>`, the reviewer's user. Absent
+   * from values written before it was recorded.
+   */
+  readonly decidedBy?: string;
+  /** The approval decided. Absent from values written before it was recorded. */
+  readonly approvalId?: string;
+}
+
+/** Who decided a gate, and which approval, when its value says. */
+interface GateDecider {
+  readonly decidedBy?: string;
+  readonly approvalId?: string;
+}
+
+/** What a gate's resume value decides. */
+export type GateDecision = GateDecider &
+  (
+    | { readonly approved: true }
+    | {
+        readonly approved: false;
+        /** `rejected`: the reviewer said no. `unreadable`: the answer wasn't a decision. */
+        readonly reason: 'rejected' | 'unreadable';
+        /** The reviewer's rationale, or why an unreadable answer blocks. */
+        readonly rationale: string | undefined;
+      }
+  );
+
+/** Why a gate blocks on an answer that isn't a decision. */
+export const UNREADABLE_DECISION =
+  "the approval's answer wasn't a decision (approve or reject), so it counts as a rejection";
+
+/**
+ * The decision in a gate's resume value. Fails closed: only
+ * `{ decided: 'approve' }` approves.
+ */
+export function readGateDecision(value: unknown): GateDecision {
+  if (typeof value !== 'object' || value === null) {
+    return { approved: false, reason: 'unreadable', rationale: UNREADABLE_DECISION };
+  }
+  const { decided, rationale, decidedBy, approvalId } = value as {
+    decided?: unknown;
+    rationale?: unknown;
+    decidedBy?: unknown;
+    approvalId?: unknown;
+  };
+  const decider: GateDecider = {
+    ...(typeof decidedBy === 'string' && { decidedBy }),
+    ...(typeof approvalId === 'string' && { approvalId }),
+  };
+  if (decided === 'approve') return { approved: true, ...decider };
+  if (decided === 'reject') {
+    return {
+      approved: false,
+      reason: 'rejected',
+      rationale: typeof rationale === 'string' ? rationale : undefined,
+      ...decider,
+    };
+  }
+  return { approved: false, reason: 'unreadable', rationale: UNREADABLE_DECISION };
+}

package/src/handlers/model-call.ts

@@ -1,13 +1,25 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { ModelCallInput, ModelMessage } from '@kindgi/capabilities';
-import type { NodeHandler } from '@kindgi/handler';
+import { randomUUID } from 'node:crypto';
+
+import {
+  type ModelCallInput,
+  type ModelMessage,
+  type ModelProvider,
+  type ModelUsageRecord,
+  recordModelUsage,
+} from '@kindgi/capabilities';
+import { attemptsOf } from '@kindgi/capabilities/attempts';
+import type { NodeContext, NodeHandler } from '@kindgi/handler';
+import type { Timestamp } from '@kindgi/types';
 
 import { emitTurnEvent } from '../streaming.js';
 
 import type { AgentTurnIterationOutput, TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { replayTag } from './replay.js';
+import { addModelCallNode } from './turn-provenance.js';
 
 /**
  * Loop-body node #1. Invoke the model with the current
@@ -15,6 +27,16 @@ import { throwAgentTurnFailure } from './errors.js';
  * `model.call.completed`, records provenance for the model-call node,
  * and accumulates usage on `ctx.usage`.
  *
+ * Every call is recorded in the usage sink (`InvokeAgentBindings.usage`,
+ * the runtime's cost ledger) before the step goes on, a call that threw
+ * included. A sink that fails is tried again (a record is idempotent by
+ * call id); one that still fails fails the step when the call succeeded,
+ * so no answered call is left unrecorded. A call that failed keeps its
+ * own failure, which says it couldn't be recorded too. The call's id goes into
+ * the step's output and its provenance node, which keeps the call's
+ * identity (provider, model) while its usage lives in the ledger. A dry
+ * run spends nothing and records nothing.
+ *
  * Output is a partial `AgentTurnIterationOutput` — `dispatch-tools`
  * receives it and finishes composing the iteration output.
  */
@@ -31,6 +53,8 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
     const nextMessages: readonly ModelMessage[] = shaped?.nextMessages ?? [];
 
     ctx.usage.steps += 1;
+    const step = ctx.usage.steps;
+    const callId = randomUUID();
 
     await emitTurnEvent(ctx.bindings.onEvent, {
       kind: 'model.call.started',
@@ -60,28 +84,17 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
         ...(ctx.tools.definitions.length > 0 && {
           tools: ctx.tools.definitions,
         }),
+        ...modelSettingsOf(ctx),
         abortSignal: ctx.turnAbort.signal,
       };
 
+      const startedAt = Date.now();
       try {
         callResult = await ctx.provider.invoke(callInput);
       } catch (cause) {
-        if (ctx.turnAbort.signal.aborted) {
-          throwAgentTurnFailure({
-            code: 'agent-turn-aborted',
-            message: `Agent turn aborted: ${cause instanceof Error ? cause.message : String(cause)}`,
-            reason: ctx.abortReason ?? 'timeout',
-          });
-        }
-        // The provider's own words (a 401's "invalid x-api-key", a 429)
-        // are what the caller needs; they're in `cause` too, but callers
-        // show `message`.
-        throwAgentTurnFailure({
-          code: 'model-invocation-failed',
-          message: `Model call to ${ctx.provider.metadata.id} (${ctx.model.name}) failed: ${describeCause(cause)}`,
-          cause,
-        });
+        return await failCall(ctx, kctx, { callId, step, cause, startedAt });
       }
+      await recordAnswer(ctx, kctx, callId, step, callResult);
     }
 
     ctx.usage.promptTokens += callResult.usage.promptTokens;
@@ -100,32 +113,27 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
     });
 
     if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
-      const modelCallNodeId = `model-call:${ctx.usage.steps}`;
-      ctx.provenance.addNode({
-        id: modelCallNodeId,
-        kind: 'model-call',
-        timestamp: new Date().toISOString() as never,
-        modelVersion: `${callResult.provider.id}/${callResult.provider.model}`,
-        attributes: {
+      addModelCallNode(
+        ctx.provenance,
+        {
           step: ctx.usage.steps,
-          promptTokens: callResult.usage.promptTokens,
-          completionTokens: callResult.usage.completionTokens,
-          costUsd: callResult.costUsd,
+          callId,
+          provider: callResult.provider,
           finishReason: callResult.finishReason,
+          at: new Date().toISOString() as Timestamp,
         },
-      });
-      ctx.provenance.addEdge({
-        from: modelCallNodeId,
-        to: `input:${ctx.userMessage.sequence}`,
-        kind: 'caused-by',
-      });
+        ctx.userMessage.sequence,
+        ctx.toolResultIds ?? [],
+      );
     }
 
     // Partial iteration output — `dispatch-tools` finishes it.
     const partial: Omit<AgentTurnIterationOutput, 'iterationAppended' | 'finishedTurn'> & {
       readonly step: number;
+      readonly callId: string;
     } = {
       step: ctx.usage.steps,
+      callId,
       finishReason: callResult.finishReason,
       message: callResult.message,
       iterationUsage: {
@@ -140,6 +148,117 @@ export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
   };
 }
 
+/**
+ * A call that answered: record it before the step goes on. A sink that
+ * still fails after its retries fails the step: an answered call isn't
+ * left unrecorded.
+ */
+async function recordAnswer(
+  ctx: TurnContext,
+  kctx: NodeContext,
+  callId: string,
+  step: number,
+  answer: Awaited<ReturnType<ModelProvider['invoke']>>,
+): Promise<void> {
+  const { message: _answer, ...result } = answer;
+  const unrecorded = await recordCall(ctx, kctx, {
+    callId,
+    step,
+    status: 'ok',
+    result,
+    durationMs: answer.durationMs,
+  });
+  if (unrecorded !== undefined) {
+    throwAgentTurnFailure({
+      code: 'persistence-error',
+      message: `The model call couldn't be recorded: ${describeCause(unrecorded)}`,
+      cause: unrecorded,
+    });
+  }
+}
+
+/**
+ * A call that threw: record it, then fail the step with the call's own
+ * failure (aborted, or the provider's words). A record that failed too
+ * is said after it.
+ */
+async function failCall(
+  ctx: TurnContext,
+  kctx: NodeContext,
+  failed: {
+    readonly callId: string;
+    readonly step: number;
+    readonly cause: unknown;
+    readonly startedAt: number;
+  },
+): Promise<never> {
+  const { cause } = failed;
+  const attempts = attemptsOf(cause);
+  const unrecorded = await recordCall(ctx, kctx, {
+    callId: failed.callId,
+    step: failed.step,
+    status: 'failed',
+    error: { message: describeCause(cause), ...(attempts !== undefined && { attempts }) },
+    durationMs: Date.now() - failed.startedAt,
+  });
+  const andUnrecorded =
+    unrecorded === undefined
+      ? ''
+      : ` (and the failed call couldn't be recorded: ${describeCause(unrecorded)})`;
+  if (ctx.turnAbort.signal.aborted) {
+    throwAgentTurnFailure({
+      code: 'agent-turn-aborted',
+      message: `Agent turn aborted: ${cause instanceof Error ? cause.message : String(cause)}${andUnrecorded}`,
+      reason: ctx.abortReason ?? 'timeout',
+    });
+  }
+  // The provider's own words (a 401's "invalid x-api-key", a 429) are
+  // what the caller needs; they're in `cause` too, but callers show
+  // `message`.
+  throwAgentTurnFailure({
+    code: 'model-invocation-failed',
+    message: `Model call to ${ctx.provider?.metadata.id} (${ctx.model?.name}) failed: ${describeCause(cause)}${andUnrecorded}`,
+    cause,
+  });
+}
+
+/** What the call came to, for `recordCall`. */
+type CallOutcome = Pick<
+  ModelUsageRecord,
+  'callId' | 'step' | 'status' | 'result' | 'error' | 'durationMs'
+>;
+
+/**
+ * Record a model call in the usage sink, when the turn has one, trying
+ * a failing sink again. Resolves with the sink's last failure when it
+ * couldn't record; the caller decides what that means for the step.
+ */
+async function recordCall(
+  ctx: TurnContext,
+  kctx: NodeContext,
+  call: CallOutcome,
+): Promise<unknown | undefined> {
+  const sink = ctx.bindings.usage;
+  if (sink === undefined || ctx.provider === undefined || ctx.model === undefined) return;
+  const { input } = ctx;
+  const recorded = await recordModelUsage(sink, {
+    ...call,
+    tenantId: input.tenantId,
+    projectId: input.projectId,
+    runId: kctx.runId,
+    agentId: input.agent.id as unknown as string,
+    agentVersion: input.agent.version,
+    conversationId: input.conversationId as unknown as string,
+    nodeId: kctx.nodeId as unknown as string,
+    providerId: ctx.provider.metadata.id,
+    model: ctx.model.name,
+    ...(ctx.provider.metadata.fallback === true && { fallback: true }),
+    ...(input.replay !== undefined && { replay: replayTag(input.replay) }),
+    occurredAt: new Date().toISOString(),
+  });
+  return recorded.kind === 'err' ? (recorded.error ?? new Error('no detail')) : undefined;
+}
+
 /** Longest cause text a failure message carries. */
 const MAX_CAUSE_CHARS = 500;
 
@@ -149,3 +268,14 @@ function describeCause(cause: unknown): string {
   if (text.length === 0) return cause instanceof Error ? cause.name : 'no detail';
   return text.length > MAX_CAUSE_CHARS ? `${text.slice(0, MAX_CAUSE_CHARS - 1)}…` : text;
 }
+
+/** The pinned model-settings block's values, as model-call fields; none when it has none. */
+function modelSettingsOf(
+  ctx: TurnContext,
+): Pick<ModelCallInput, 'temperature' | 'maxOutputTokens'> {
+  const settings = ctx.blocks?.modelSettings;
+  return {
+    ...(settings?.temperature !== undefined && { temperature: settings.temperature }),
+    ...(settings?.maxOutputTokens !== undefined && { maxOutputTokens: settings.maxOutputTokens }),
+  };
+}

package/src/handlers/persist-provenance.ts

@@ -28,7 +28,9 @@ export function buildPersistProvenanceHandler(ctx: TurnContext): NodeHandler {
       // want).
       return { persisted: false };
     }
-    const persisted = await persistProvenance(ctx.provenance, ctx.provenanceBindings);
+    const persisted = await persistProvenance(ctx.provenance, ctx.provenanceBindings, {
+      projectId: ctx.input.projectId,
+    });
     if (persisted.kind === 'ok') {
       ctx.persistedProvenance = persisted.value;
       return { persisted: true };

package/src/handlers/persist-user-message.ts

@@ -8,6 +8,7 @@ import type { ConversationMessage } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { addInputNode } from './turn-provenance.js';
 
 /**
  * Persist the caller's user message BEFORE the model is called. A
@@ -33,14 +34,7 @@ export function buildPersistUserMessageHandler(ctx: TurnContext): NodeHandler {
       ctx.userMessage = synthetic;
       ctx.appended.push(synthetic);
 
-      if (ctx.provenance !== undefined) {
-        ctx.provenance.addNode({
-          id: `input:${synthetic.sequence}`,
-          kind: 'input',
-          timestamp: synthetic.createdAt,
-          ...(synthetic.actor !== undefined && { actor: synthetic.actor }),
-        });
-      }
+      if (ctx.provenance !== undefined) addInputNode(ctx.provenance, synthetic);
       return { sequence: synthetic.sequence };
     }
 
@@ -56,14 +50,7 @@ export function buildPersistUserMessageHandler(ctx: TurnContext): NodeHandler {
     ctx.userMessage = persisted.value;
     ctx.appended.push(persisted.value);
 
-    if (ctx.provenance !== undefined) {
-      ctx.provenance.addNode({
-        id: `input:${persisted.value.sequence}`,
-        kind: 'input',
-        timestamp: persisted.value.createdAt,
-        ...(persisted.value.actor !== undefined && { actor: persisted.value.actor }),
-      });
-    }
+    if (ctx.provenance !== undefined) addInputNode(ctx.provenance, persisted.value);
 
     return { sequence: persisted.value.sequence };
   };

package/src/handlers/public-types.ts

@@ -2,14 +2,15 @@
 // 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 { ParentRunRef, RunBinding, RunReplayRef } 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 { BlockReader } from '../blocks.js';
 import type { ConversationBinding } from '../conversation-binding.js';
 import type { GuardrailsBindings } from '../guardrails-gate.js';
 import type { ProvenanceBindings } from '../provenance-emit.js';
@@ -17,6 +18,8 @@ import type { RunSnapshotBinding } from '../run-snapshot-binding.js';
 import type { OnTurnEvent } from '../streaming.js';
 import type { Agent, ConversationId } from '../types.js';
 
+import type { ReplayBinding } from './replay.js';
+
 /**
  * The user-facing input to `invokeAgent`. Split out from `invoke.ts` so
  * the handler modules can depend on the shape without pulling in the
@@ -32,6 +35,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;
@@ -48,6 +57,13 @@ export interface InvokeAgentInput {
    * step. Recorded on the turn's run, so the flow can find its child.
    */
   readonly parent?: ParentRunRef;
+  /**
+   * Marks the turn as a replay: an eval run re-running a past run (`of`)
+   * on this agent version. Recorded on the turn's run and in its snapshot.
+   * Its tool calls are decided by `InvokeAgentBindings.replay` (every call
+   * is refused when that isn't wired), and only a read-only tool can run.
+   */
+  readonly replay?: RunReplayRef;
   readonly participantId?: string;
   readonly abortSignal?: AbortSignal;
   /**
@@ -95,6 +111,12 @@ export interface InvokeAgentBindings extends GuardrailsBindings {
    * sees another tenant's tools.
    */
   readonly toolRegistry: ToolRegistry;
+  /**
+   * Data blocks (prompts and settings). Setup loads the blocks the agent
+   * references at their pinned versions. Optional: an agent that
+   * references blocks fails its turn (`block-unresolvable`) without it.
+   */
+  readonly blockReader?: BlockReader;
   /**
    * Caller-plugged data-access surface for memory reads.
    * The Kindgi runtime supplies a Postgres-backed implementation;
@@ -153,6 +175,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,
@@ -163,6 +191,11 @@ export interface InvokeAgentBindings extends GuardrailsBindings {
    * unaffected.
    */
   readonly resolveSecret?: (ref: ToolSecretRef) => Promise<string>;
+  /**
+   * How replay turns (`InvokeAgentInput.replay`) decide their tool calls,
+   * retrievals and session approval. Consulted only for a replay turn.
+   */
+  readonly replay?: ReplayBinding;
 }
 
 export interface HitlBindings {
@@ -171,6 +204,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';