@kindgi/agents 0.1.1 → 0.1.3

package/migrations/meta/0003_snapshot.json

@@ -0,0 +1,321 @@
+{
+  "id": "39c9de18-7608-4826-84f7-af1dda0ba078",
+  "prevId": "2769ef0e-69b4-4a4d-ab47-044e2f11945e",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.agent_conversations": {
+      "name": "agent_conversations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "tenant_id": {
+          "name": "tenant_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "agent_id": {
+          "name": "agent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "agent_version": {
+          "name": "agent_version",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "participant_id": {
+          "name": "participant_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scope": {
+          "name": "scope",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "opened_at": {
+          "name": "opened_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "closed_at": {
+          "name": "closed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "turn_count": {
+          "name": "turn_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_message_at": {
+          "name": "last_message_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "agent_conversations_tenant_agent_idx": {
+          "name": "agent_conversations_tenant_agent_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "agent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "agent_conversations_tenant_participant_idx": {
+          "name": "agent_conversations_tenant_participant_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "participant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "agent_conversations_tenant_project_opened_idx": {
+          "name": "agent_conversations_tenant_project_opened_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "project_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "opened_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"agent_conversations\".\"project_id\" IS NOT NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "agent_conversations_open_recent_idx": {
+          "name": "agent_conversations_open_recent_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "last_message_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"agent_conversations\".\"closed_at\" IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.agent_run_snapshots": {
+      "name": "agent_run_snapshots",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "tenant_id": {
+          "name": "tenant_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "agent_id": {
+          "name": "agent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "agent_version": {
+          "name": "agent_version",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "conversation_id": {
+          "name": "conversation_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_message": {
+          "name": "user_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "parameters": {
+          "name": "parameters",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "input": {
+          "name": "input",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "participant_id": {
+          "name": "participant_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dry_run": {
+          "name": "dry_run",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "principal": {
+          "name": "principal",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "authz": {
+          "name": "authz",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "agent_run_snapshots_tenant_idx": {
+          "name": "agent_run_snapshots_tenant_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/migrations/meta/_journal.json

@@ -22,6 +22,13 @@
       "when": 1790813765675,
       "tag": "0002_violet_ezekiel",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1791208016784,
+      "tag": "0003_hesitant_captain_cross",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/agents",
-  "version": "0.1.1",
+  "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": {
@@ -18,7 +18,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -30,21 +31,21 @@
     "type-manifest.json"
   ],
   "dependencies": {
-    "@kindgi/authz": "0.1.1",
-    "@kindgi/capabilities": "0.1.1",
-    "@kindgi/compliance": "0.1.1",
-    "@kindgi/embedding": "0.1.1",
-    "@kindgi/flow": "0.1.1",
-    "@kindgi/handler": "0.1.1",
-    "@kindgi/guardrails": "0.1.1",
-    "@kindgi/memory": "0.1.1",
-    "@kindgi/policy-contract": "0.1.1",
-    "@kindgi/provenance": "0.1.1",
-    "@kindgi/runtime": "0.1.1",
-    "@kindgi/schema": "0.1.1",
-    "@kindgi/tools": "0.1.1",
-    "@kindgi/types": "0.1.1",
-    "drizzle-orm": "^0.36.4",
+    "@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"
   },
   "peerDependencies": {
@@ -63,7 +64,7 @@
     "zod": "^4.6.5"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

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