@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/src/run-snapshot-binding.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ProjectId, Result, RunId, Semver, TenantId, Timestamp } from '@kindgi/types';
+
+import type { PersistenceError } from './errors.js';
+import type { AgentId, ConversationId } from './types.js';
+
+/**
+ * Input for `RunSnapshotBinding.write` — the InvokeAgentInput envelope
+ * captured at run-start so `resumeAgentTurn(runId)` can rebuild the
+ * same TurnContext after a kernel waitpoint resolves. Idempotent under
+ * flow replay via the runId primary key.
+ */
+export interface RunSnapshotWriteInput {
+  readonly runId: RunId;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly agentId: AgentId;
+  readonly agentVersion: Semver;
+  readonly conversationId: ConversationId;
+  readonly userMessage: string;
+  /** The turn's prompt parameters — a resumed turn renders its instructions with them. */
+  readonly parameters?: Readonly<Record<string, string | number | boolean>>;
+  /** The turn's structured input (`InvokeAgentInput.input`); same persistence contract. */
+  readonly input?: unknown;
+  readonly participantId?: string;
+  readonly dryRun?: boolean;
+  /**
+   * Optional serialized Principal (authorization). Impls MUST persist
+   * unchanged and return it verbatim from `read` so resumed turns get
+   * the same enforcement context. Wire shape is opaque to this layer.
+   */
+  readonly principal?: unknown;
+  /**
+   * Optional authz config (`{ fgaApiUrl }`). Same persistence contract
+   * as `principal`.
+   */
+  readonly authz?: unknown;
+}
+
+/**
+ * Persisted run-snapshot row returned by `RunSnapshotBinding.read`.
+ * Field shape mirrors the `agent_run_snapshots` table but is expressed
+ * as a plain interface so alternative impls (non-Postgres) match the
+ * same contract.
+ */
+export interface RunSnapshotRecord {
+  readonly runId: RunId;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly agentId: AgentId;
+  readonly agentVersion: Semver;
+  readonly conversationId: ConversationId;
+  readonly userMessage: string;
+  readonly parameters?: Readonly<Record<string, string | number | boolean>>;
+  readonly input?: unknown;
+  readonly participantId?: string;
+  readonly dryRun: boolean;
+  readonly principal?: unknown;
+  readonly authz?: unknown;
+  readonly createdAt: Timestamp;
+}
+
+/**
+ * `RunSnapshotBinding` — the public seam between @kindgi/agents and
+ * whatever run-snapshot store a deployment plugs in (the Kindgi
+ * runtime ships a Postgres-backed one; alternatives possible).
+ *
+ * Ownership: @kindgi/agents (not the kernel). Kernel schemas stay
+ * generic across all flow runners; agent-specific reconstruction
+ * context lives at this layer.
+ *
+ * `write` is best-effort — a failure does NOT fail the turn (the run
+ * already started; snapshot-write hiccups shouldn't block execution).
+ * Callers of a resumed turn get `run-snapshot-missing` and know the
+ * run is unrecoverable. Impls MUST be idempotent under kernel replay
+ * (ON CONFLICT DO NOTHING on the runId PK, or equivalent).
+ */
+export interface RunSnapshotBinding {
+  write(input: RunSnapshotWriteInput): Promise<Result<void, PersistenceError>>;
+
+  read(
+    tenantId: TenantId,
+    runId: RunId,
+  ): Promise<Result<RunSnapshotRecord | null, PersistenceError>>;
+}

package/src/schema.ts

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { sql } from 'drizzle-orm';
+import { index, integer, jsonb, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+
+/**
+ * Agents schema — first-class conversation primitive.
+ *
+ * A conversation is a durable thread grouping many agent invocations
+ * into one user-visible unit. Messages inside a conversation live as
+ * memory facts of type `agent-message`, scoped to
+ * `threadId = <conversation id>`. This split lets conversation
+ * lifecycle (open/close, list, cheap turn-count updates) use a real
+ * table while message content inherits memory's versioning +
+ * retention + RLS + search infrastructure.
+ *
+ * `tenant_id` on every table; implementations enable row-level
+ * security on `AGENTS_TENANT_SCOPED_TABLES` and run every statement in
+ * a tenant-scoped connection so the RLS predicate has context.
+ */
+
+export const agentConversations = pgTable(
+  'agent_conversations',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    tenantId: uuid('tenant_id').notNull(),
+    /**
+     * Agent id + version this conversation was opened with. Resuming
+     * with a different version is refused — the agent's semantics may
+     * have changed.
+     */
+    agentId: text('agent_id').notNull(),
+    agentVersion: text('agent_version').notNull(),
+    /**
+     * Human-facing title. Auto-generated on first turn (typically from
+     * the initial user message) or explicitly set. Not versioned — the
+     * latest string wins.
+     */
+    title: text('title').notNull(),
+    /**
+     * Optional identifier for the human participant (email, user id,
+     * SSO subject). Kept as text so the caller decides the shape.
+     */
+    participantId: text('participant_id'),
+    /**
+     * Structural scope — project id, matter id, etc. Persisted through
+     * the versioning envelope so shape evolution is migrate-on-read.
+     */
+    scope: jsonb('scope').notNull(),
+    openedAt: timestamp('opened_at', { withTimezone: true }).notNull().defaultNow(),
+    /** Set when the conversation is closed. Closed conversations are read-only. */
+    closedAt: timestamp('closed_at', { withTimezone: true }),
+    /**
+     * Denormalized turn counter — incremented by `appendMessage` for
+     * each turn's final (non-intermediate) agent message. Read by the
+     * session HITL gate and the UI conversation list.
+     */
+    turnCount: integer('turn_count').notNull().default(0),
+    /**
+     * Denormalized last-activity timestamp. Kept in sync by
+     * `appendMessage`. Enables cheap sort by recency in the UI list.
+     */
+    lastMessageAt: timestamp('last_message_at', { withTimezone: true }),
+    /**
+     * Free-form metadata (participant details, feature flags,
+     * conversation-level notes). Versioned envelope.
+     */
+    metadata: jsonb('metadata'),
+  },
+  (t) => ({
+    tenantAgentIdx: index('agent_conversations_tenant_agent_idx').on(t.tenantId, t.agentId),
+    tenantParticipantIdx: index('agent_conversations_tenant_participant_idx').on(
+      t.tenantId,
+      t.participantId,
+    ),
+    /** 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())
+      .where(sql`${t.closedAt} IS NULL`),
+  }),
+);
+
+export type AgentConversationRow = typeof agentConversations.$inferSelect;
+export type NewAgentConversationRow = typeof agentConversations.$inferInsert;
+
+/**
+ * `agent_run_snapshots` — reconstruction envelope for a suspended agent
+ * turn. Written by the setup handler on the FIRST execution of a run
+ * (idempotent via the runId primary key); used by
+ * `resumeAgentTurn(runId)` to rebuild the same `InvokeAgentInput` the
+ * turn was invoked with — so kernel replay after a HITL waitpoint
+ * resolution lands in an identical context.
+ *
+ * Owned by @kindgi/agents (not the kernel) so the kernel's
+ * schema stays generic — the kernel has no notion of agents,
+ * conversations, or participant identities.
+ *
+ * Idempotent insert: `runId` is the PK; implementations insert with
+ * `ON CONFLICT (id) DO NOTHING` (or equivalent) so a replay is a
+ * no-op. All fields are set at first execution and never modified.
+ */
+export const agentRunSnapshots = pgTable(
+  'agent_run_snapshots',
+  {
+    /** `runId` — the kernel run this snapshot reconstructs. Primary key. */
+    id: uuid('id').primaryKey(),
+    tenantId: uuid('tenant_id').notNull(),
+    projectId: uuid('project_id').notNull(),
+    /** Agent id + version pinned at turn start. Same as agent_conversations. */
+    agentId: text('agent_id').notNull(),
+    agentVersion: text('agent_version').notNull(),
+    /** Conversation this turn belongs to — required for the setup handler to load state. */
+    conversationId: uuid('conversation_id').notNull(),
+    /** The user message that started this turn. */
+    userMessage: text('user_message').notNull(),
+    /**
+     * The turn's prompt parameters and structured input, as given to
+     * `invokeAgent`. A resumed turn renders its instructions with the
+     * same values. Versioned envelopes, like `principal`.
+     */
+    parameters: jsonb('parameters'),
+    input: jsonb('input'),
+    /** Optional participant identifier — mirrors InvokeAgentInput.participantId. */
+    participantId: text('participant_id'),
+    /** dryRun marker from the original invocation. Affects handler side-effect behavior. */
+    dryRun: integer('dry_run').notNull().default(0),
+    /**
+     * Optional serialized Principal (authorization) from the original
+     * invocation. Threaded back into the resumed TurnContext so tool
+     * dispatch stays enforcement-consistent. Versioned envelope so shape
+     * evolution is migrate-on-read.
+     */
+    principal: jsonb('principal'),
+    /**
+     * Optional authz config (`{fgaApiUrl}`) from the original invocation.
+     * Threaded back into the resumed TurnContext.
+     */
+    authz: jsonb('authz'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    tenantIdx: index('agent_run_snapshots_tenant_idx').on(t.tenantId),
+  }),
+);
+
+export type AgentRunSnapshotRow = typeof agentRunSnapshots.$inferSelect;
+export type NewAgentRunSnapshotRow = typeof agentRunSnapshots.$inferInsert;
+
+/**
+ * Tables that carry `tenant_id`; register them with the migration
+ * runner so row-level security gets enabled on them.
+ */
+export const AGENTS_TENANT_SCOPED_TABLES = ['agent_conversations', 'agent_run_snapshots'] as const;

package/src/streaming.ts

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { EvaluationResult } from '@kindgi/guardrails';
+import type { Semver } from '@kindgi/types';
+
+import type { AgentId, ConversationId, ConversationMessage, RetrievedFact } from './types.js';
+
+/**
+ * Discriminated union of every event a turn emits during execution.
+ * Callers wire `bindings.onEvent` to their transport (SSE, WebSocket,
+ * background job queue, or nothing at all).
+ *
+ * Order is deterministic per turn: `turn.started` first, `turn.completed`
+ * or `turn.failed` last. Intermediate events fire in the order the
+ * corresponding action happens.
+ */
+export type TurnEvent =
+  | TurnStartedEvent
+  | RetrievalCompletedEvent
+  | ModelCallStartedEvent
+  | ModelCallCompletedEvent
+  | ToolStartedEvent
+  | ToolCompletedEvent
+  | ToolFailedEvent
+  | AgentMessageEvent
+  | GuardrailViolatedEvent
+  | TurnCompletedEvent
+  | TurnFailedEvent;
+
+export interface TurnStartedEvent {
+  readonly kind: 'turn.started';
+  readonly conversationId: ConversationId;
+  readonly turnNumber: number;
+  readonly agentId: AgentId;
+  readonly agentVersion: Semver;
+  readonly userMessage: string;
+}
+
+export interface RetrievalCompletedEvent {
+  readonly kind: 'retrieval.completed';
+  readonly count: number;
+  /** Fact ids retrieved this turn. Empty when no intents declared. */
+  readonly factIds: readonly string[];
+}
+
+export interface ModelCallStartedEvent {
+  readonly kind: 'model.call.started';
+  readonly step: number;
+  readonly providerId: string;
+  readonly model: string;
+}
+
+export interface ModelCallCompletedEvent {
+  readonly kind: 'model.call.completed';
+  readonly step: number;
+  readonly finishReason: 'stop' | 'length' | 'tool-use' | 'content-filter' | 'error';
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly costUsd: number;
+  readonly durationMs: number;
+}
+
+export interface ToolStartedEvent {
+  readonly kind: 'tool.started';
+  readonly step: number;
+  readonly toolId: string;
+  /**
+   * The exact version dispatched (picked at run start by `resolve(id,
+   * range)` on the tenant's tool registry) so subscribers can
+   * distinguish `kb-search@1.2.3` from `kb-search@2.0.0`.
+   */
+  readonly toolVersion: string;
+  /** The semver range the agent binding declared for this tool. */
+  readonly toolVersionRange: string;
+  readonly invocationId: string;
+  readonly arguments: Readonly<Record<string, unknown>>;
+}
+
+export interface ToolCompletedEvent {
+  readonly kind: 'tool.completed';
+  readonly step: number;
+  readonly toolId: string;
+  readonly toolVersion: string;
+  readonly toolVersionRange: string;
+  readonly invocationId: string;
+  readonly output: unknown;
+  readonly durationMs: number;
+}
+
+export interface ToolFailedEvent {
+  readonly kind: 'tool.failed';
+  readonly step: number;
+  readonly toolId: string;
+  readonly invocationId: string;
+  readonly error: { readonly code: string; readonly message: string };
+}
+
+export interface AgentMessageEvent {
+  readonly kind: 'agent.message';
+  readonly step: number;
+  /** True when this is the final message that closes the turn. */
+  readonly isFinal: boolean;
+  readonly message: ConversationMessage;
+}
+
+export interface GuardrailViolatedEvent {
+  readonly kind: 'guardrail.violated';
+  readonly action: EvaluationResult['action'];
+  readonly severity: EvaluationResult['severity'];
+  readonly guardrailId: string;
+  readonly reason?: string;
+}
+
+export interface TurnCompletedEvent {
+  readonly kind: 'turn.completed';
+  readonly conversationId: ConversationId;
+  readonly turnNumber: number;
+  readonly response: ConversationMessage;
+  readonly retrieved: readonly RetrievedFact[];
+  readonly durationMs: number;
+  readonly totalCostUsd: number;
+}
+
+export interface TurnFailedEvent {
+  readonly kind: 'turn.failed';
+  readonly conversationId: ConversationId;
+  readonly errorCode: string;
+  readonly message: string;
+}
+
+/**
+ * Adapter shape callers plug into `bindings.onEvent`. Sync + async both
+ * supported. Errors thrown inside the handler are caught by the runtime
+ * — a broken telemetry sink never breaks the turn.
+ */
+export type OnTurnEvent = (event: TurnEvent) => void | Promise<void>;
+
+/**
+ * Safe emit wrapper. Called by the turn's handlers at each observation
+ * point; catches handler throws so a broken sink can't break the run.
+ */
+export async function emitTurnEvent(
+  onEvent: OnTurnEvent | undefined,
+  event: TurnEvent,
+): Promise<void> {
+  if (onEvent === undefined) return;
+  try {
+    await onEvent(event);
+  } catch {
+    // Intentionally swallow — telemetry sinks must not affect run outcome.
+  }
+}

package/src/tenant-policy.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TenantPolicy } from '@kindgi/capabilities';
+
+type AllowDeny = { readonly allow?: readonly string[]; readonly deny?: readonly string[] };
+
+/**
+ * Combine two tenant policies (the statically bound one and one derived
+ * from the policy registry) so the result is at least as strict as each:
+ *
+ *   - allow lists (`providers.allow`, `models.allow`, `regionAllow`) →
+ *     INTERSECTION when both set one; a list set on one side only applies
+ *     as-is. An empty result allows nothing (the router fails closed).
+ *   - deny lists (`providers.deny`, `models.deny`) → UNION.
+ *   - `maxCostPerCallUsd` / `maxTokensPerCall` → the smaller value.
+ *
+ * Returns `undefined` when both are undefined (routing runs with no
+ * tenant policy).
+ */
+export function mergeTenantPolicies(
+  a: TenantPolicy | undefined,
+  b: TenantPolicy | undefined,
+): TenantPolicy | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  const providers = mergeAllowDeny(a.providers, b.providers);
+  const models = mergeAllowDeny(a.models, b.models);
+  const regionAllow = intersectStrings(a.regionAllow, b.regionAllow);
+  const maxCost = minDefined(a.maxCostPerCallUsd, b.maxCostPerCallUsd);
+  const maxTokens = minDefined(a.maxTokensPerCall, b.maxTokensPerCall);
+  const merged: { -readonly [K in keyof TenantPolicy]: TenantPolicy[K] } = {
+    tenantId: a.tenantId,
+  };
+  if (providers !== undefined) merged.providers = providers;
+  if (models !== undefined) merged.models = models;
+  if (regionAllow !== undefined) merged.regionAllow = regionAllow;
+  if (maxCost !== undefined) merged.maxCostPerCallUsd = maxCost;
+  if (maxTokens !== undefined) merged.maxTokensPerCall = maxTokens;
+  return merged;
+}
+
+function mergeAllowDeny(a: AllowDeny | undefined, b: AllowDeny | undefined): AllowDeny | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  const allow = intersectStrings(a.allow, b.allow);
+  const deny = unionStrings(a.deny, b.deny);
+  if (allow === undefined && deny === undefined) return undefined;
+  return {
+    ...(allow !== undefined && { allow }),
+    ...(deny !== undefined && { deny }),
+  };
+}
+
+function intersectStrings(
+  a: readonly string[] | undefined,
+  b: readonly string[] | undefined,
+): readonly string[] | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  const inB = new Set(b);
+  return Array.from(new Set(a)).filter((v) => inB.has(v));
+}
+
+function unionStrings(
+  a: readonly string[] | undefined,
+  b: readonly string[] | undefined,
+): readonly string[] | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return Array.from(new Set([...a, ...b]));
+}
+
+function minDefined(a: number | undefined, b: number | undefined): number | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return Math.min(a, b);
+}