@kindgi/agents 0.1.1 → 0.1.3

package/src/handlers/turn-provenance.ts

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * 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 function addInputNode(provenance: ProvenanceBuilder, message: ConversationMessage): void {
+  provenance.addNode({
+    id: `input:${message.sequence}`,
+    kind: 'input',
+    timestamp: message.createdAt,
+    ...(message.actor !== undefined && { actor: message.actor }),
+  });
+}
+
+/** The facts the turn retrieved for its user message. */
+export function addRetrievalNodes(
+  provenance: ProvenanceBuilder,
+  retrieved: readonly RetrievedFact[],
+  input: ConversationMessage,
+): void {
+  for (const r of retrieved) {
+    provenance.addNode({
+      id: `retrieval:${r.fact.id}`,
+      kind: 'retrieval',
+      timestamp: input.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 }),
+      },
+    });
+    provenance.addEdge({
+      from: `retrieval:${r.fact.id}`,
+      to: `input:${input.sequence}`,
+      kind: 'influenced-by',
+    });
+  }
+}
+
+/** 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 function addModelCallNode(
+  provenance: ProvenanceBuilder,
+  call: ModelCallFacts,
+  inputSequence: number,
+  toolResultIds: readonly string[],
+): void {
+  const id = `model-call:${call.step}`;
+  provenance.addNode({
+    id,
+    kind: 'model-call',
+    timestamp: call.at,
+    modelVersion: `${call.provider.id}/${call.provider.model}`,
+    attributes: {
+      step: call.step,
+      callId: call.callId,
+      providerId: call.provider.id,
+      model: call.provider.model,
+      finishReason: call.finishReason,
+    },
+  });
+  provenance.addEdge({ from: id, to: `input:${inputSequence}`, kind: 'caused-by' });
+  for (const invocationId of toolResultIds) {
+    provenance.addEdge({ from: id, to: `tool-result:${invocationId}`, kind: 'influenced-by' });
+  }
+}
+
+/**
+ * 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 function addToolNodes(
+  provenance: ProvenanceBuilder,
+  step: number,
+  result: ConversationMessage,
+  version: { readonly resolvedVersion: string; readonly requestedRange: string } | undefined,
+): void {
+  const call = result.toolCall;
+  if (call === undefined) return;
+  const callNodeId = `tool-call:${call.invocationId}`;
+  const resultNodeId = `tool-result:${call.invocationId}`;
+  provenance.addNode({
+    id: callNodeId,
+    kind: 'tool-call',
+    timestamp: result.createdAt,
+    attributes: {
+      toolId: call.toolId,
+      invocationId: call.invocationId,
+      // The version the registry picked for the turn and the range the
+      // agent asked for, so a replay can pin against the same version.
+      ...(version !== undefined && {
+        toolVersion: version.resolvedVersion,
+        toolVersionRange: version.requestedRange,
+      }),
+    },
+  });
+  provenance.addNode({ id: resultNodeId, kind: 'tool-result', timestamp: result.createdAt });
+  provenance.addEdge({ from: callNodeId, to: `model-call:${step}`, kind: 'invoked' });
+  provenance.addEdge({ from: resultNodeId, to: callNodeId, kind: 'produced' });
+}
+
+/**
+ * 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 function addStepToolNodes(
+  ctx: TurnContext,
+  step: number,
+  stored: readonly ConversationMessage[],
+): void {
+  for (const result of stored) {
+    if (result.role !== 'tool' || result.toolCall === undefined) continue;
+    const { invocationId, toolId } = result.toolCall;
+    if (ctx.provenance !== undefined) {
+      addToolNodes(ctx.provenance, step, result, versionOf(ctx, toolId));
+      const approval = ctx.toolApprovals?.get(invocationId);
+      if (approval !== undefined) {
+        addToolApprovalNodes(
+          ctx.provenance,
+          invocationId,
+          approval,
+          ctx.input.agent.id as unknown as string,
+        );
+      }
+    }
+    ctx.toolResultIds ??= [];
+    ctx.toolResultIds.push(invocationId);
+  }
+}
+
+/** 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 function addToolApprovalNodes(
+  provenance: ProvenanceBuilder,
+  invocationId: string,
+  approval: ToolApproval,
+  agentId: string,
+): void {
+  const waitId = `tool-hitl-gate-wait:${invocationId}`;
+  const resumeId = `tool-hitl-gate-resume:${invocationId}`;
+  const { decision } = approval;
+  provenance.addNode({
+    id: waitId,
+    kind: 'wait',
+    timestamp: approval.parkedAt,
+    actor: `agent:${agentId}`,
+    attributes: { gate: 'tool-call', invocationId, waitTokenId: approval.waitTokenId },
+  });
+  provenance.addNode({
+    id: resumeId,
+    kind: 'resume',
+    timestamp: approval.decidedAt,
+    ...(decision.decidedBy !== undefined && { actor: decision.decidedBy }),
+    attributes: {
+      gate: 'tool-call',
+      decision: decisionOf(decision),
+      ...(!decision.approved &&
+        decision.reason === 'rejected' &&
+        decision.rationale !== undefined && { rationale: decision.rationale }),
+      ...(decision.approvalId !== undefined && { approvalId: decision.approvalId }),
+    },
+  });
+  provenance.addEdge({ from: `tool-call:${invocationId}`, to: waitId, kind: 'waited-on' });
+  provenance.addEdge({ from: waitId, to: resumeId, kind: 'resumed-from' });
+  provenance.addEdge({ from: `tool-result:${invocationId}`, to: resumeId, kind: 'caused-by' });
+}
+
+/** A gate decision as a `resume` node records it. */
+export function decisionOf(decision: GateDecision): 'approve' | 'reject' | 'unreadable' {
+  if (decision.approved) return 'approve';
+  return decision.reason === 'rejected' ? 'reject' : 'unreadable';
+}
+
+/** The version the agent's binding of `toolId` resolved, if it has one. */
+function versionOf(
+  ctx: TurnContext,
+  toolId: string,
+): { readonly resolvedVersion: string; readonly requestedRange: string } | undefined {
+  const bindings = [...(ctx.tools?.byName.values() ?? [])];
+  const binding =
+    ctx.tools?.byName.get(toolId) ??
+    bindings.find((b) => (b.tool.id as unknown as string) === toolId);
+  return binding === undefined
+    ? undefined
+    : { resolvedVersion: binding.resolvedVersion, requestedRange: binding.requestedRange };
+}

package/src/index.ts

@@ -19,6 +19,13 @@ export type {
 export { defineAgent } from './define.js';
 export type { DefineAgentSpec } from './define.js';
 export { resolveEffectiveHitlPolicy } from './hitl-policy.js';
+export {
+  AGENT_GATE_SUBJECTS,
+  SESSION_GATE_SUBJECT,
+  TOOL_CALL_GATE_SUBJECT,
+  readGateDecision,
+} from './handlers/gate-decision.js';
+export type { GateDecision, GateDecisionValue } from './handlers/gate-decision.js';
 export type { EffectiveHitlPolicy } from './hitl-policy.js';
 export { agentStepOutput, invokeAgent, resumeAgentTurn } from './invoke.js';
 export type {
@@ -35,6 +42,7 @@ export type {
   ModelInvocationError,
   OutputSchemaViolationError,
   ResumeAgentTurnInput,
+  RunSnapshotError,
   ToolInvocationError,
   UnresolvedToolError,
 } from './invoke.js';

package/src/invoke.ts

@@ -3,7 +3,7 @@
 
 import type { Principal } from '@kindgi/authz';
 import type { KernelError, RunResult } from '@kindgi/runtime';
-import type { Result, RunId, TenantId } from '@kindgi/types';
+import type { OrgId, Result, RunId, TenantId } from '@kindgi/types';
 
 import { AGENT_TURN_FLOW } from './agent-turn-flow.js';
 import { DEFAULT_MAX_WALL_MS } from './handlers/constants.js';
@@ -14,6 +14,7 @@ import type { InvokeAgentBindings, InvokeAgentInput } from './handlers/public-ty
 import { rehydrateTurnContext } from './handlers/rehydrate.js';
 import type { AgentTurnResult } from './handlers/result-shape.js';
 import { projectRunResult } from './project-run-result.js';
+import type { RunSnapshotRecord } from './run-snapshot-binding.js';
 import type { Agent } from './types.js';
 
 /**
@@ -82,6 +83,12 @@ export async function invokeAgent(
       flow: AGENT_TURN_FLOW,
       handlers,
       input: input.userMessage,
+      // The run's record names the agent, its version and the conversation.
+      agent: {
+        id: input.agent.id,
+        version: input.agent.version,
+        conversationId: input.conversationId,
+      },
       ...(input.parent !== undefined && { parent: input.parent }),
       ...(input.dryRun === true && { options: { dryRun: true } }),
       // Authorization — carry principal + authz into the run so every
@@ -106,6 +113,12 @@ export interface ResumeAgentTurnInput {
    * handler's agent-version-mismatch guard).
    */
   readonly agent: Agent;
+  /**
+   * The org of the run's project (the snapshot's `projectId`), when it has
+   * one. The caller resolves it from the project, as for `invokeAgent`'s
+   * `orgId`, so the resumed turn's tools and guardrails see it too.
+   */
+  readonly orgId?: OrgId;
 }
 
 /**
@@ -126,7 +139,8 @@ export interface ResumeAgentTurnInput {
  * runId — this happens when the setup handler's snapshot write failed
  * (the write is best-effort). Recovery: cancel the run explicitly;
  * there is no way to reconstruct the InvokeAgentInput without the
- * snapshot.
+ * snapshot. Fails with `run-snapshot-unreadable` when reading it failed;
+ * resuming again may work.
  */
 /**
  * Rebuild a resumed turn's context from its journal (see
@@ -167,9 +181,9 @@ export async function resumeAgentTurn(
     return {
       kind: 'err',
       error: {
-        code: 'run-snapshot-missing',
-        message: `Failed to load run snapshot for run ${input.runId as unknown as string}: ${snapshotResult.error.message}`,
-      } as never,
+        code: 'run-snapshot-unreadable',
+        message: `Could not read the run snapshot of run ${input.runId as unknown as string}: ${snapshotResult.error.message}`,
+      },
     };
   }
   const snapshot = snapshotResult.value;
@@ -179,7 +193,7 @@ export async function resumeAgentTurn(
       error: {
         code: 'run-snapshot-missing',
         message: `No run snapshot for run ${input.runId as unknown as string} — resume-context unavailable.`,
-      } as never,
+      },
     };
   }
 
@@ -202,25 +216,7 @@ export async function resumeAgentTurn(
   }
 
   // 3. Reconstruct the InvokeAgentInput envelope from the snapshot.
-  const reconstructedInput: InvokeAgentInput = {
-    tenantId: snapshot.tenantId,
-    projectId: snapshot.projectId,
-    agent: input.agent,
-    conversationId: snapshot.conversationId,
-    userMessage: snapshot.userMessage,
-    ...(snapshot.parameters !== undefined && { parameters: snapshot.parameters }),
-    ...(snapshot.input !== undefined && { input: snapshot.input }),
-    ...(snapshot.participantId !== undefined && { participantId: snapshot.participantId }),
-    ...(snapshot.dryRun && { dryRun: true }),
-    ...(snapshot.principal !== undefined &&
-      snapshot.principal !== null && {
-        principal: snapshot.principal as Principal,
-      }),
-    ...(snapshot.authz !== undefined &&
-      snapshot.authz !== null && {
-        authz: snapshot.authz as { readonly fgaApiUrl: string },
-      }),
-  };
+  const reconstructedInput = turnInputFromSnapshot(snapshot, input);
 
   // 4. Build the same TurnContext + handlers as invokeAgent().
   const started = Date.now();
@@ -287,6 +283,7 @@ export type {
   InvokeAgentError,
   ModelInvocationError,
   OutputSchemaViolationError,
+  RunSnapshotError,
   ToolInvocationError,
   UnresolvedToolError,
 } from './handlers/errors.js';
@@ -297,3 +294,34 @@ export type {
   InvokeAgentBindings,
   InvokeAgentInput,
 } from './handlers/public-types.js';
+
+/**
+ * The `InvokeAgentInput` a resumed turn runs with: the one captured in its
+ * snapshot at run start, the agent the caller resolved, and the org of the
+ * run's project, which the caller resolves as for `invokeAgent`.
+ */
+export function turnInputFromSnapshot(
+  snapshot: RunSnapshotRecord,
+  input: Pick<ResumeAgentTurnInput, 'agent' | 'orgId'>,
+): InvokeAgentInput {
+  return {
+    tenantId: snapshot.tenantId,
+    projectId: snapshot.projectId,
+    ...(input.orgId !== undefined && { orgId: input.orgId }),
+    agent: input.agent,
+    conversationId: snapshot.conversationId,
+    userMessage: snapshot.userMessage,
+    ...(snapshot.parameters !== undefined && { parameters: snapshot.parameters }),
+    ...(snapshot.input !== undefined && { input: snapshot.input }),
+    ...(snapshot.participantId !== undefined && { participantId: snapshot.participantId }),
+    ...(snapshot.dryRun && { dryRun: true }),
+    ...(snapshot.principal !== undefined &&
+      snapshot.principal !== null && {
+        principal: snapshot.principal as Principal,
+      }),
+    ...(snapshot.authz !== undefined &&
+      snapshot.authz !== null && {
+        authz: snapshot.authz as { readonly fgaApiUrl: string },
+      }),
+  };
+}

package/src/provenance-emit.ts

@@ -6,6 +6,7 @@ import type {
   Provenance,
   ProvenanceBuilder,
   ProvenanceEmitBinding,
+  ProvenanceEmitContext,
 } from '@kindgi/provenance';
 import { signProvenance } from '@kindgi/provenance';
 import type { Result } from '@kindgi/types';
@@ -55,6 +56,8 @@ export interface ProvenanceBindings {
 export async function persistProvenance(
   builder: ProvenanceBuilder,
   bindings: ProvenanceBindings,
+  /** Stored beside the record (the turn's project); see `ProvenanceEmitContext`. */
+  context?: ProvenanceEmitContext,
 ): Promise<Result<Provenance, PersistenceError>> {
   let provenance: Provenance = builder.snapshot();
   if (bindings.keyProvider !== undefined) {
@@ -84,7 +87,7 @@ export async function persistProvenance(
         },
       };
     }
-    const emitted = await bindings.emitBinding.emit(provenance);
+    const emitted = await bindings.emitBinding.emit(provenance, context);
     if (emitted.kind === 'err') {
       return {
         kind: 'err',

package/src/schema.ts

@@ -43,6 +43,13 @@ export const agentConversations = pgTable(
      * SSO subject). Kept as text so the caller decides the shape.
      */
     participantId: text('participant_id'),
+    /**
+     * The project the conversation is in, set when it is opened (a run
+     * opens it in the run's project). Null when opened without one, and
+     * on conversations from before the column (nothing is backfilled).
+     * No foreign key: `projects` belongs to the runtime's schema.
+     */
+    projectId: uuid('project_id'),
     /**
      * Structural scope — project id, matter id, etc. Persisted through
      * the versioning envelope so shape evolution is migrate-on-read.
@@ -74,6 +81,10 @@ export const agentConversations = pgTable(
       t.tenantId,
       t.participantId,
     ),
+    /** One project's conversations, newest first (`listConversationsPage({ scope })`). */
+    tenantProjectOpenedIdx: index('agent_conversations_tenant_project_opened_idx')
+      .on(t.tenantId, t.projectId, t.openedAt.desc())
+      .where(sql`${t.projectId} IS NOT NULL`),
     /** Partial index: open conversations sorted by recency. Used by the UI list. */
     openRecentIdx: index('agent_conversations_open_recent_idx')
       .on(t.tenantId, t.lastMessageAt.desc())

package/src/types.ts

@@ -4,7 +4,7 @@
 import type { Capability } from '@kindgi/capabilities';
 import type { Fact, MemoryScope } from '@kindgi/memory';
 import type { ToolErrorsSpec, ToolHitlMode, ToolHitlRule } from '@kindgi/policy-contract';
-import type { Brand, ConversationId, Semver, TenantId, Timestamp } from '@kindgi/types';
+import type { Brand, ConversationId, ProjectId, Semver, TenantId, Timestamp } from '@kindgi/types';
 
 /**
  * Branded agent id. Convention: dotted namespace under the tenant's
@@ -204,6 +204,14 @@ export interface ConversationHitlPolicy {
    * (see `resolveEffectiveHitlPolicy`).
    */
   readonly timeoutMs?: number;
+  /**
+   * What happens when an approval's time runs out: it escalates one
+   * reviewer tier, and at `admin` it expires (the turn fails with
+   * `hitl-cancelled`). `'escalate'` is the only behavior today, and the
+   * default; `'auto-approve'` and `'auto-reject'` are refused rather than
+   * accepted and ignored.
+   */
+  readonly onTimeout?: 'escalate';
 }
 
 /**
@@ -416,6 +424,12 @@ export interface Conversation {
   readonly title: string;
   /** UUID or free-form identifier for the human participant. */
   readonly participantId?: string;
+  /**
+   * The project the conversation is in, set when it is opened (by a run,
+   * from the run's project). Absent on conversations opened without one,
+   * and on those from before it was stored.
+   */
+  readonly projectId?: ProjectId;
   /** Additional attributes (project id, matter id, etc.). */
   readonly scope: MemoryScope;
   readonly openedAt: Timestamp;