@kindgi/agents 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/agents",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Agent primitive for Kindgi. Composes capabilities (model routing), tools (execution), memory (facts + retrieval), guardrails (declarative guardrails), and provenance into a single declarative unit. Agents are data-as-code — a defineAgent() call produces a durable definition that runs on the kernel, with first-class multi-turn conversations, streaming output, and a provenance record per turn.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,20 +31,20 @@
     "type-manifest.json"
   ],
   "dependencies": {
-    "@kindgi/authz": "0.1.2",
-    "@kindgi/capabilities": "0.1.2",
-    "@kindgi/compliance": "0.1.2",
-    "@kindgi/embedding": "0.1.2",
-    "@kindgi/flow": "0.1.2",
-    "@kindgi/handler": "0.1.2",
-    "@kindgi/guardrails": "0.1.2",
-    "@kindgi/memory": "0.1.2",
-    "@kindgi/policy-contract": "0.1.2",
-    "@kindgi/provenance": "0.1.2",
-    "@kindgi/runtime": "0.1.2",
-    "@kindgi/schema": "0.1.2",
-    "@kindgi/tools": "0.1.2",
-    "@kindgi/types": "0.1.2",
+    "@kindgi/authz": "0.1.3",
+    "@kindgi/capabilities": "0.1.3",
+    "@kindgi/compliance": "0.1.3",
+    "@kindgi/embedding": "0.1.3",
+    "@kindgi/flow": "0.1.3",
+    "@kindgi/handler": "0.1.3",
+    "@kindgi/guardrails": "0.1.3",
+    "@kindgi/memory": "0.1.3",
+    "@kindgi/policy-contract": "0.1.3",
+    "@kindgi/provenance": "0.1.3",
+    "@kindgi/runtime": "0.1.3",
+    "@kindgi/schema": "0.1.3",
+    "@kindgi/tools": "0.1.3",
+    "@kindgi/types": "0.1.3",
     "drizzle-orm": "^0.45.3",
     "liquidjs": "^10.29.0"
   },

package/src/conversation-binding.ts

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { RunBinding } from '@kindgi/runtime';
-import type { Result, Semver, TenantId } from '@kindgi/types';
+import type { ListScope, ProjectId, Result, Semver, TenantId } from '@kindgi/types';
 
 import type { AgentError } from './errors.js';
 import type {
@@ -21,6 +21,8 @@ export interface OpenConversationInput {
   readonly agentVersion: Semver;
   readonly title: string;
   readonly participantId?: string;
+  /** The project the conversation is in: its turns' project. Lists filter by it. */
+  readonly projectId?: ProjectId;
   readonly scope: Readonly<Record<string, unknown>>;
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
@@ -72,6 +74,12 @@ export interface ConversationPageCursor {
 
 export interface ListConversationsPageInput {
   readonly tenantId: TenantId;
+  /**
+   * Only one project's conversations, or every project's in an org.
+   * Absent: the tenant's. A conversation opened without a project is
+   * listed only without a scope.
+   */
+  readonly scope?: ListScope;
   readonly agentId?: AgentId;
   /** When set, filter to open (no closedAt) or closed (closedAt set) rows only. */
   readonly status?: 'open' | 'closed';

package/src/define.ts

@@ -448,6 +448,7 @@ function validateConversationPolicy(policy?: ConversationPolicy): Issue[] {
         message: 'hitl.timeoutMs must be a positive integer (ms)',
       });
     }
+    out.push(...validateOnTimeout(h.onTimeout));
     const ROLES: ReadonlySet<string> = new Set(['standard', 'senior', 'admin']);
     if (
       h.defaultReviewerRole !== undefined &&
@@ -490,6 +491,25 @@ function validateConversationPolicy(policy?: ConversationPolicy): Issue[] {
   return out;
 }
 
+/**
+ * `hitl.onTimeout`: only `'escalate'`, what the runtime does when an
+ * approval's time runs out. `'auto-approve'` / `'auto-reject'` aren't
+ * implemented, so they're refused instead of accepted and ignored.
+ */
+function validateOnTimeout(onTimeout: unknown): Issue[] {
+  if (onTimeout === undefined || onTimeout === 'escalate') return [];
+  const path = '/conversationPolicy/hitl/onTimeout';
+  if (onTimeout === 'auto-approve' || onTimeout === 'auto-reject') {
+    return [
+      {
+        path,
+        message: `hitl.onTimeout '${onTimeout}' isn't supported: an approval that times out escalates one reviewer tier, and at admin it expires (the turn fails with hitl-cancelled). Use 'escalate', or leave it out.`,
+      },
+    ];
+  }
+  return [{ path, message: "hitl.onTimeout must be 'escalate'" }];
+}
+
 type OutputOutcome =
   | { readonly kind: 'none' }
   | { readonly kind: 'ok'; readonly value: AgentOutputSpec }

package/src/guardrails-gate.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { ProviderRegistry, TenantPolicy } from '@kindgi/capabilities';
+import type { ProviderRegistry, TenantPolicy, UsageSink } from '@kindgi/capabilities';
 import type { ComplianceProvider } from '@kindgi/compliance';
 import {
   type CheckRegistry,
@@ -15,7 +15,15 @@ import {
   type ToolResultRecord,
   evaluateAll,
 } from '@kindgi/guardrails';
-import type { AgentId, GuardrailId, ProjectId, Result, RunId, TenantId } from '@kindgi/types';
+import type {
+  AgentId,
+  GuardrailId,
+  OrgId,
+  ProjectId,
+  Result,
+  RunId,
+  TenantId,
+} from '@kindgi/types';
 
 import type { Agent, ConversationId, ConversationMessage } from './types.js';
 
@@ -66,6 +74,8 @@ export function buildRunTrace(input: {
   readonly tenantId: TenantId;
   /** Lets the engine record compliance evidence for a failed check. */
   readonly projectId: ProjectId;
+  /** The project's org, when it has one. */
+  readonly orgId?: OrgId;
   readonly conversationId: ConversationId;
   /** 1-based number of this turn in the conversation. */
   readonly turnNumber: number;
@@ -133,6 +143,7 @@ export function buildRunTrace(input: {
     runId: input.runId,
     tenantId: input.tenantId,
     projectId: input.projectId,
+    ...(input.orgId !== undefined && { orgId: input.orgId }),
     agentId: input.agent.id as unknown as AgentId,
     output,
     toolCalls,
@@ -179,7 +190,8 @@ export function resolveGuardrails(
  * doesn't halt on its own. `tenantPolicy` (the policy the turn was
  * routed under) also governs which models llm-judge guardrails may use;
  * `abortSignal` (the turn's) reaches every check, so a slow judge or
- * pack check stops when the turn does.
+ * pack check stops when the turn does. `usage` (the turn's sink) records
+ * every llm-judge call, as the turn's own model calls are.
  */
 export async function evaluateGate(
   guardrails: readonly Guardrail[],
@@ -187,6 +199,7 @@ export async function evaluateGate(
   bindings: GuardrailsBindings,
   tenantPolicy?: TenantPolicy,
   abortSignal?: AbortSignal,
+  usage?: UsageSink,
 ): Promise<readonly EvaluationOutcome[]> {
   if (guardrails.length === 0 || bindings.checks === undefined) return [];
   const evalBindings: EvaluationBindings = {
@@ -194,6 +207,7 @@ export async function evaluateGate(
     ...(bindings.compliance !== undefined && { compliance: bindings.compliance }),
     ...(tenantPolicy !== undefined && { tenantPolicy }),
     ...(abortSignal !== undefined && { abortSignal }),
+    ...(usage !== undefined && { usage }),
   };
   return await evaluateAll(guardrails, bindings.checks, trace, evalBindings);
 }

package/src/handlers/context.ts

@@ -143,6 +143,20 @@ export interface TurnContext {
    * Present only when the builder was wired AND persistence succeeded.
    */
   persistedProvenance?: import('@kindgi/provenance').Provenance;
+  /**
+   * This turn's tool results so far, by invocation id: a model call read
+   * them all (they're in its input), so its provenance node is
+   * `influenced-by` each. Filled by `dispatch-tools`, and by the rebuild
+   * of a resumed turn.
+   */
+  toolResultIds?: string[];
+  /**
+   * The tool-call approvals this turn's journal shows decided, by
+   * invocation id: each call's provenance shows the approval it waited on.
+   * Populated by `rehydrateTurnContext` (a decision only reaches a turn
+   * that parked, and resumes).
+   */
+  toolApprovals?: ReadonlyMap<string, import('./turn-provenance.js').ToolApproval>;
   /**
    * The tenant policy this turn's model was routed under (bound policy
    * merged with the policy registry's). Populated by `setup`; guardrail

package/src/handlers/dispatch-tools.ts

@@ -19,13 +19,15 @@ import {
   type UnresolvedToolError,
   throwAgentTurnFailure,
 } from './errors.js';
+import { TOOL_CALL_GATE_SUBJECT, readGateDecision } from './gate-decision.js';
 import {
   effectiveToolErrorPolicy,
   toolErrorKindOf,
   toolErrorResult,
   toolRetriesSoFar,
 } from './tool-errors.js';
-import { type ToolHitlDecision, computeToolCallWaitToken, hashToolArgs } from './tool-hitl.js';
+import { TOOL_GATE_RECORD_PREFIX, computeToolCallWaitToken, hashToolArgs } from './tool-hitl.js';
+import { addStepToolNodes } from './turn-provenance.js';
 
 /**
  * Resolves the effective HITL mode + reviewer role for a specific
@@ -111,7 +113,7 @@ async function decideToolGate(
       cause: null,
     });
   }
-  return kctx.record(`tool-hitl-gate:${call.id}`, (): ToolGateRecord | undefined => {
+  return kctx.record(`${TOOL_GATE_RECORD_PREFIX}${call.id}`, (): ToolGateRecord | undefined => {
     const resolved = resolveEffectiveToolHitl(effectiveHitl, tool);
     if (resolved.mode === 'never_ask') return undefined;
     const argsHash = hashToolArgs(call.arguments);
@@ -251,7 +253,8 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
           try {
             await ctx.bindings.hitl.enqueue({
               tenantId: ctx.input.tenantId,
-              subjectKind: 'tool-call:pending',
+              projectId: ctx.input.projectId,
+              subjectKind: TOOL_CALL_GATE_SUBJECT,
               subjectRef: {
                 conversationId: ctx.input.conversationId,
                 agentId: ctx.input.agent.id,
@@ -275,14 +278,16 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
         }
 
         try {
-          const decision = await kctx.waitForToken<ToolHitlDecision>(waitTokenId, {
-            timeoutMs,
-          });
-          if (decision.decided === 'reject') {
+          // Fails closed: only an explicit approve runs the tool. A reject,
+          // or an answer that isn't a decision at all, gives the model a
+          // rejected result instead.
+          const decision = readGateDecision(
+            await kctx.waitForToken<unknown>(waitTokenId, { timeoutMs }),
+          );
+          if (!decision.approved) {
             toolRejectionPayload =
               decision.rationale !== undefined ? { rationale: decision.rationale } : {};
           }
-          // approve → fall through to dispatch
         } catch (cause) {
           if (cause instanceof WaitpointCancelledError) {
             throwAgentTurnFailure({
@@ -372,43 +377,13 @@ export function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler {
         output: dispatched.value.persisted.content,
         durationMs: Date.now() - toolStarted,
       });
-
-      if (ctx.provenance !== undefined) {
-        const modelCallNodeId = `model-call:${partial.step}`;
-        const toolCallNodeId = `tool-call:${call.id}`;
-        const toolResultNodeId = `tool-result:${call.id}`;
-        ctx.provenance.addNode({
-          id: toolCallNodeId,
-          kind: 'tool-call',
-          timestamp: dispatched.value.persisted.createdAt,
-          attributes: {
-            toolId: call.name,
-            invocationId: call.id,
-            // Capture the exact version the
-            // registry picked at run start + the range the agent asked
-            // for, so a replay can pin against the same version.
-            toolVersion: resolvedVersion,
-            toolVersionRange: requestedRange,
-          },
-        });
-        ctx.provenance.addNode({
-          id: toolResultNodeId,
-          kind: 'tool-result',
-          timestamp: dispatched.value.persisted.createdAt,
-        });
-        ctx.provenance.addEdge({
-          from: toolCallNodeId,
-          to: modelCallNodeId,
-          kind: 'invoked',
-        });
-        ctx.provenance.addEdge({
-          from: toolResultNodeId,
-          to: toolCallNodeId,
-          kind: 'produced',
-        });
-      }
     }
 
+    // Every call's nodes, once the step has all its results: the ones it
+    // ran, the rejected and failed ones, and those it took from before a
+    // park in this step.
+    addStepToolNodes(ctx, partial.step, iterationAppended);
+
     const forwarded: Partial<AgentTurnIterationOutput> & {
       readonly step: number;
       readonly hasToolCalls: true;
@@ -573,6 +548,9 @@ async function dispatchOne(
   const toolCtx: ToolContext = {
     tenantId: ctx.input.tenantId,
     runId,
+    // The run's own project and org, never the model's arguments.
+    projectId: ctx.input.projectId,
+    ...(ctx.input.orgId !== undefined && { orgId: ctx.input.orgId }),
     requestId: call.id,
     abortSignal: ctx.turnAbort.signal,
     // HTTP tools built via defineTool({spec: {kind: 'http'}}) resolve declared

package/src/handlers/evaluate-guardrails.ts

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { NodeHandler } from '@kindgi/handler';
+import type { UsageSink } from '@kindgi/capabilities';
+import type { EvaluationOutcome } from '@kindgi/guardrails';
+import type { NodeContext, NodeHandler } from '@kindgi/handler';
 import type { Timestamp } from '@kindgi/types';
 
 import {
@@ -77,6 +79,7 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
       runId: kctx.runId,
       tenantId: ctx.input.tenantId,
       projectId: ctx.input.projectId,
+      ...(ctx.input.orgId !== undefined && { orgId: ctx.input.orgId }),
       conversationId: ctx.input.conversationId,
       turnNumber: (ctx.conversation?.turnCount ?? 0) + 1,
       agent: ctx.input.agent,
@@ -93,7 +96,9 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
       ctx.bindings,
       ctx.tenantPolicy,
       ctx.turnAbort.signal,
+      judgeUsageSink(ctx, kctx),
     );
+    throwIfJudgeCallsUnrecorded(outcomes);
     const categorized = categorizeOutcomes(outcomes);
 
     const allViolations = [...categorized.blocking, ...categorized.warnings, ...categorized.other];
@@ -151,3 +156,36 @@ export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
     };
   };
 }
+
+/**
+ * The turn's usage sink for its llm-judge calls, adding what only the
+ * turn knows: the step that made them and the agent's version.
+ */
+function judgeUsageSink(ctx: TurnContext, kctx: NodeContext): UsageSink | undefined {
+  const sink = ctx.bindings.usage;
+  if (sink === undefined) return undefined;
+  return {
+    record: (call) =>
+      sink.record({
+        nodeId: kctx.nodeId as unknown as string,
+        agentVersion: ctx.input.agent.version,
+        ...call,
+      }),
+  };
+}
+
+/**
+ * A judge call that answered but couldn't be recorded fails the step, as
+ * the turn's own model calls do: no answered call is left unrecorded.
+ */
+function throwIfJudgeCallsUnrecorded(outcomes: readonly EvaluationOutcome[]): void {
+  for (const outcome of outcomes) {
+    if (outcome.kind === 'err' && outcome.error.code === 'judge-usage-unrecorded') {
+      throwAgentTurnFailure({
+        code: 'persistence-error',
+        message: outcome.error.message,
+        cause: outcome.error,
+      });
+    }
+  }
+}

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 };
+}