@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/dist/handlers/persist-final-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-final-message.js","sourceRoot":"","sources":["../../src/handlers/persist-final-message.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAKjC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,UAAU,+BAA+B,CAAC,GAAgB;IAC9D,OAAO,KAAK,EAAE,MAAe,EAAE,IAAI,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,cAAc,CAC1B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,eAAyB,CAAC,EAC/C,uBAAuB,CACxB,CAAC;QAEF,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC;QAEnC,IAAI,YAAiC,CAAC;QACtC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,YAAY,GAAG;gBACb,QAAQ,EAAE,CAAC,CAAC;gBACZ,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,YAAY,CAAC,OAAO,IAAI,EAAE;gBACnC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAe;gBAChD,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;aAC1B,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,mBAAmB,CAAC,aAAa,CAAC;gBACnE,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ;gBAC5B,cAAc,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc;gBACxC,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,YAAY,CAAC,OAAO,IAAI,EAAE;gBACnC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;aAC1B,CAAC,CAAC;YACH,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK;gBAAE,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACjE,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC;QAC/B,CAAC;QAED,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChC,GAAG,CAAC,YAAY,GAAG,YAAY,CAAC;QAEhC,MAAM,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE;YACxC,IAAI,EAAE,eAAe;YACrB,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK;YACrB,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,YAAY;SACtB,CAAC,CAAC;QAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,CAAC;IAC7C,CAAC,CAAC;AACJ,CAAC"}

package/dist/handlers/persist-provenance.d.ts

@@ -0,0 +1,12 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Persist the completed provenance DAG. Best-effort: a persistence
+ * failure here does NOT fail the run (the turn already succeeded and
+ * the DAG was built in memory); the result then carries no
+ * `provenance`.
+ *
+ * Skipped entirely when no provenance builder was wired.
+ */
+export declare function buildPersistProvenanceHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=persist-provenance.d.ts.map

package/dist/handlers/persist-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-provenance.d.ts","sourceRoot":"","sources":["../../src/handlers/persist-provenance.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAqB3E"}

package/dist/handlers/persist-provenance.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { persistProvenance } from '../provenance-emit.js';
+/**
+ * Persist the completed provenance DAG. Best-effort: a persistence
+ * failure here does NOT fail the run (the turn already succeeded and
+ * the DAG was built in memory); the result then carries no
+ * `provenance`.
+ *
+ * Skipped entirely when no provenance builder was wired.
+ */
+export function buildPersistProvenanceHandler(ctx) {
+    return async (_input, kctx) => {
+        if (ctx.provenance === undefined || ctx.provenanceBindings === undefined) {
+            return { persisted: false };
+        }
+        if (kctx.dryRun) {
+            // Dry-run: DAG was built in-memory; skip the write. The
+            // returned `AgentTurnResult.provenance` is left undefined
+            // (unpersisted provenance is not surfaced on the result —
+            // callers can inspect the in-memory builder via bindings if they
+            // want).
+            return { persisted: false };
+        }
+        const persisted = await persistProvenance(ctx.provenance, ctx.provenanceBindings);
+        if (persisted.kind === 'ok') {
+            ctx.persistedProvenance = persisted.value;
+            return { persisted: true };
+        }
+        // Silently swallow — persistence is best-effort (see above).
+        return { persisted: false };
+    };
+}
+//# sourceMappingURL=persist-provenance.js.map

package/dist/handlers/persist-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-provenance.js","sourceRoot":"","sources":["../../src/handlers/persist-provenance.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI1D;;;;;;;GAOG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAAgB;IAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QAC5B,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;YACzE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,wDAAwD;YACxD,0DAA0D;YAC1D,0DAA0D;YAC1D,iEAAiE;YACjE,SAAS;YACT,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAClF,IAAI,SAAS,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAC5B,GAAG,CAAC,mBAAmB,GAAG,SAAS,CAAC,KAAK,CAAC;YAC1C,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QACD,6DAA6D;QAC7D,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC,CAAC;AACJ,CAAC"}

package/dist/handlers/persist-user-message.d.ts

@@ -0,0 +1,15 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Persist the caller's user message BEFORE the model is called. A
+ * crash mid-turn leaves the question intact for a later replay. Also
+ * seeds the provenance DAG with the `input:<sequence>` node — every
+ * subsequent model/tool node ties back through that root.
+ *
+ * Dry-run branch: skips the DB write; builds a synthetic
+ * `ConversationMessage` with `sequence: -1` (sentinel — real sequences
+ * are always ≥ 0). Provenance node is still seeded so downstream
+ * dry-run handlers can build a plausible plan DAG.
+ */
+export declare function buildPersistUserMessageHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=persist-user-message.d.ts.map

package/dist/handlers/persist-user-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-user-message.d.ts","sourceRoot":"","sources":["../../src/handlers/persist-user-message.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA+C5E"}

package/dist/handlers/persist-user-message.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { throwAgentTurnFailure } from './errors.js';
+/**
+ * Persist the caller's user message BEFORE the model is called. A
+ * crash mid-turn leaves the question intact for a later replay. Also
+ * seeds the provenance DAG with the `input:<sequence>` node — every
+ * subsequent model/tool node ties back through that root.
+ *
+ * Dry-run branch: skips the DB write; builds a synthetic
+ * `ConversationMessage` with `sequence: -1` (sentinel — real sequences
+ * are always ≥ 0). Provenance node is still seeded so downstream
+ * dry-run handlers can build a plausible plan DAG.
+ */
+export function buildPersistUserMessageHandler(ctx) {
+    return async (_input, kctx) => {
+        if (kctx.dryRun) {
+            const synthetic = {
+                sequence: -1,
+                role: 'user',
+                content: ctx.input.userMessage,
+                createdAt: new Date().toISOString(),
+                ...(ctx.input.participantId !== undefined && { actor: ctx.input.participantId }),
+            };
+            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 }),
+                });
+            }
+            return { sequence: synthetic.sequence };
+        }
+        const persisted = await ctx.bindings.conversationBinding.appendMessage({
+            tenantId: ctx.input.tenantId,
+            conversationId: ctx.input.conversationId,
+            role: 'user',
+            content: ctx.input.userMessage,
+            ...(ctx.input.participantId !== undefined && { actor: ctx.input.participantId }),
+        });
+        if (persisted.kind === 'err')
+            throwAgentTurnFailure(persisted.error);
+        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 }),
+            });
+        }
+        return { sequence: persisted.value.sequence };
+    };
+}
+//# sourceMappingURL=persist-user-message.js.map

package/dist/handlers/persist-user-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-user-message.js","sourceRoot":"","sources":["../../src/handlers/persist-user-message.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAQjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,8BAA8B,CAAC,GAAgB;IAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QAC5B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,SAAS,GAAwB;gBACrC,QAAQ,EAAE,CAAC,CAAC;gBACZ,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW;gBAC9B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAe;gBAChD,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;aACjF,CAAC;YACF,GAAG,CAAC,WAAW,GAAG,SAAS,CAAC;YAC5B,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAE7B,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;gBACjC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;oBACrB,EAAE,EAAE,SAAS,SAAS,CAAC,QAAQ,EAAE;oBACjC,IAAI,EAAE,OAAO;oBACb,SAAS,EAAE,SAAS,CAAC,SAAS;oBAC9B,GAAG,CAAC,SAAS,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;iBACjE,CAAC,CAAC;YACL,CAAC;YACD,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC;QAC1C,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,mBAAmB,CAAC,aAAa,CAAC;YACrE,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ;YAC5B,cAAc,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc;YACxC,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW;YAC9B,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;SACjF,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,IAAI,KAAK,KAAK;YAAE,qBAAqB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAErE,GAAG,CAAC,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC;QAClC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAEnC,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACjC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;gBACrB,EAAE,EAAE,SAAS,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE;gBACvC,IAAI,EAAE,OAAO;gBACb,SAAS,EAAE,SAAS,CAAC,KAAK,CAAC,SAAS;gBACpC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;aAC7E,CAAC,CAAC;QACL,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC"}

package/dist/handlers/public-types.d.ts

@@ -0,0 +1,201 @@
+import type { Principal } from '@kindgi/authz';
+import type { ProviderRegistry, TenantPolicy } 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 { ToolRegistry, ToolSecretRef } from '@kindgi/tools';
+import type { ProjectId, ProvenanceId, RunId, TenantId, Timestamp } from '@kindgi/types';
+import type { ConversationBinding } from '../conversation-binding.js';
+import type { GuardrailsBindings } from '../guardrails-gate.js';
+import type { ProvenanceBindings } from '../provenance-emit.js';
+import type { RunSnapshotBinding } from '../run-snapshot-binding.js';
+import type { OnTurnEvent } from '../streaming.js';
+import type { Agent, ConversationId } from '../types.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
+ * orchestration entrypoint (would cause a circular import).
+ */
+export interface InvokeAgentInput {
+    readonly tenantId: TenantId;
+    /**
+     * Content-scope anchor. REQUIRED — every
+     * agent turn is a run bound to exactly one project inside the
+     * tenant. Callers without a natural project id resolve to the tenant's
+     * Default via `projectBinding.getDefault(tenantId)` (`@kindgi/api`)
+     * at the caller layer.
+     */
+    readonly projectId: ProjectId;
+    readonly agent: Agent;
+    readonly conversationId: ConversationId;
+    readonly userMessage: string;
+    readonly parameters?: Readonly<Record<string, string | number | boolean>>;
+    /**
+     * Structured input for this turn — what a flow step hands its agent.
+     * Available to the instructions as `{{ input.* }}`, kept in the run
+     * snapshot for resume, and passed to guardrails as
+     * `trace.attributes.stepInput`.
+     */
+    readonly input?: unknown;
+    /**
+     * The flow run and node that started this turn, when it is a flow
+     * step. Recorded on the turn's run, so the flow can find its child.
+     */
+    readonly parent?: ParentRunRef;
+    readonly participantId?: string;
+    readonly abortSignal?: AbortSignal;
+    /**
+     * When `true`, executes the turn as a plan preview: no side effects
+     * to the conversation, memory, or provenance. Retrievals + guardrails
+     * still run for real (pure reads); the model call is skipped and
+     * returns a fixed mock response with no tool calls, so no tools run;
+     * every `persist-*` node skips its write. The returned
+     * `AgentTurnResult` carries `dryRun: true`, and the underlying run is
+     * journaled as a dry run.
+     */
+    readonly dryRun?: boolean;
+    /**
+     * Authorization — the Principal on whose authority this agent turn
+     * runs. When set together with `authz`, the underlying run checks
+     * every tool invocation (and subgraph dispatch, if any) against this
+     * principal at its enforcement point.
+     *
+     * Typical caller construction:
+     *   principal = delegate(
+     *     { kind: 'agent', id: input.agent.id, tenantId },
+     *     userPrincipalFromSession
+     *   )
+     * — establishes the confused-deputy-safe intersection semantic.
+     *
+     * Absent = tool invocations are not authorization-checked.
+     */
+    readonly principal?: Principal;
+    readonly authz?: {
+        readonly fgaApiUrl: string;
+    };
+}
+export interface InvokeAgentBindings extends GuardrailsBindings {
+    /**
+     * Model providers. Setup hydrates the tenant's providers (when the
+     * registry supports it) and routes the agent's first capability over
+     * `list(tenantId)` under the merged tenant policy; llm-judge
+     * guardrails route through it too.
+     */
+    readonly providerRegistry: ProviderRegistry;
+    /**
+     * Tools. Setup calls `forTenant(tenantId)` and resolves the agent's
+     * tool refs on the returned tenant-bound registry, so a turn never
+     * sees another tenant's tools.
+     */
+    readonly toolRegistry: ToolRegistry;
+    /**
+     * Caller-plugged data-access surface for memory reads.
+     * The Kindgi runtime supplies a Postgres-backed implementation;
+     * any object satisfying the interface works (tests, custom stores).
+     * Retrieval (listFacts / searchByKeyword / searchBySemantic) inside
+     * the agent runtime routes through this binding — the runtime never
+     * touches a database client directly for memory operations.
+     */
+    readonly memoryBinding: MemoryQueryBinding;
+    /**
+     * Caller-plugged conversation store. Every open / get / list /
+     * close / delete / appendMessage / readMessages inside the agent
+     * runtime routes through this binding — the runtime never touches
+     * a database client directly for conversation ops. The Kindgi runtime
+     * supplies a Postgres-backed implementation; any conforming object
+     * works. Required.
+     */
+    readonly conversationBinding: ConversationBinding;
+    /**
+     * Caller-plugged run-snapshot store. Writes the reconstruction
+     * envelope on run-start (idempotent under replay); reads it
+     * on `resumeAgentTurn` to rebuild the suspended TurnContext.
+     * The Kindgi runtime supplies a
+     * Postgres-backed implementation; any conforming object works. Required.
+     */
+    readonly runSnapshotBinding: RunSnapshotBinding;
+    /**
+     * Run-lifecycle binding (`RunBinding` from `@kindgi/runtime`). Every
+     * agent turn spawns a `runGraph` (or `resumeRun`) through it. The
+     * Kindgi runtime supplies an implementation; a bespoke one can be
+     * plugged in.
+     *
+     * Optional in the type, but `invokeAgent` and `resumeAgentTurn`
+     * throw when it is missing — every caller MUST supply it.
+     */
+    readonly runBinding?: RunBinding;
+    /**
+     * Statically-injected tenant policy for model routing. When a
+     * `policyRegistry` also yields a policy, the two are MERGED so the
+     * result is at least as strict as each: allow lists intersect, deny
+     * lists union, cost/token caps take the smaller value.
+     *
+     * Absent-and-registry-absent = router runs without any tenant policy.
+     */
+    readonly tenantPolicy?: TenantPolicy;
+    /**
+     * Optional policy registry. When present, the agent setup step calls
+     * `policyRegistry.evaluate('model-routing', {tenantId})` and merges
+     * the result with `tenantPolicy` before routing. Without a registry
+     * (or without an executor for that kind), `tenantPolicy` applies
+     * alone.
+     */
+    readonly policyRegistry?: PolicyRegistry;
+    readonly embeddingRegistry?: EmbeddingProviderRegistry;
+    readonly embeddingModel?: string;
+    readonly onEvent?: OnTurnEvent;
+    readonly provenance?: ProvenanceBindings;
+    readonly hitl?: HitlBindings;
+    /**
+     * Declarative HTTP tools: optional secret resolver populated
+     * from the deployment's tenant-scoped `SecretBinding`. When present,
+     * `dispatch-tools` threads it into every `ToolContext` so
+     * declarative HTTP tools (spec kind 'http') can resolve declared `secret_ref`s at
+     * invoke time. Absent → HTTP tools that declare `authorization`
+     * throw a clear "resolveSecret is not wired" error; native tools
+     * unaffected.
+     */
+    readonly resolveSecret?: (ref: ToolSecretRef) => Promise<string>;
+}
+export interface HitlBindings {
+    readonly enqueue: (input: HitlEnqueueInput) => Promise<HitlEnqueueResult>;
+}
+export interface HitlEnqueueInput {
+    readonly tenantId: TenantId;
+    readonly subjectKind: string;
+    readonly subjectRef: Readonly<Record<string, unknown>>;
+    readonly requiredRole?: 'standard' | 'senior' | 'admin';
+    readonly title?: string;
+    readonly description?: string;
+    readonly context?: Readonly<Record<string, unknown>>;
+    /**
+     * Waitpoint token this approval resolves on approve/reject
+     * (park-and-resume). The session gate (setup handler) and the tool
+     * gate (dispatch-tools handler) compute it as a deterministic hash —
+     * of (runId, gate scope, turnCount) and of (runId, callId, argsHash)
+     * respectively. Enqueue is idempotent on this — handler replay is
+     * safe.
+     */
+    readonly waitTokenId?: string;
+    /**
+     * Provenance reference for the parent run. Required for the
+     * approvals-complete route to invoke `completeToken(runId, ...)` +
+     * `resumeRun(runId)` on decision. Absent = the approval decides in
+     * place, no waitpoint resolution.
+     */
+    readonly provenanceRef?: {
+        readonly runId: RunId;
+        readonly provenanceId?: ProvenanceId;
+    };
+    /**
+     * Absolute deadline surfaced to reviewers; an approval still pending
+     * after it can be expired. Materialized at enqueue time from the
+     * effective HITL policy's `timeoutMs`.
+     */
+    readonly expiresAt?: Timestamp;
+}
+export interface HitlEnqueueResult {
+    readonly approvalId: string;
+}
+//# sourceMappingURL=public-types.d.ts.map

package/dist/handlers/public-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-types.d.ts","sourceRoot":"","sources":["../../src/handlers/public-types.ts"],"names":[],"mappings":"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"}

package/dist/handlers/public-types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=public-types.js.map

package/dist/handlers/public-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-types.js","sourceRoot":"","sources":["../../src/handlers/public-types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/handlers/rehydrate.d.ts

@@ -0,0 +1,8 @@
+import { type JournalEntry } from '@kindgi/runtime';
+import type { TurnContext } from './context.js';
+/**
+ * Restore `ctx` for a turn being resumed. Returns `false` when `setup`
+ * hasn't completed (it will run, and resolve everything itself).
+ */
+export declare function rehydrateTurnContext(ctx: TurnContext, runId: string, journal: readonly JournalEntry[]): Promise<boolean>;
+//# sourceMappingURL=rehydrate.d.ts.map

package/dist/handlers/rehydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.d.ts","sourceRoot":"","sources":["../../src/handlers/rehydrate.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,iBAAiB,CAAC;AAGjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AA0ChD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,OAAO,CAAC,OAAO,CAAC,CA6ClB"}

package/dist/handlers/rehydrate.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { bodyStepKey } from '@kindgi/runtime';
+import { throwAgentTurnFailure } from './errors.js';
+import { loadTurnConversation, resolveTurnEnvironment, resolveTurnHitlPolicy, } from './turn-environment.js';
+/** Each step's last completion — a step at one loop iteration counts once. */
+function completedSteps(journal) {
+    const byStep = new Map();
+    for (const e of journal) {
+        if (e.kind !== 'step.completed' || e.nodeId === undefined)
+            continue;
+        const payload = (e.payload ?? {});
+        const key = payload.loopContext === undefined
+            ? e.nodeId
+            : bodyStepKey(e.nodeId, payload.loopContext);
+        byStep.delete(key);
+        byStep.set(key, {
+            nodeId: e.nodeId,
+            output: payload.output,
+            inLoop: payload.loopContext !== undefined,
+        });
+    }
+    return [...byStep.values()];
+}
+/** The output of an outer step that completed, if it did. */
+function outputOf(steps, nodeId) {
+    return steps.find((s) => s.nodeId === nodeId && !s.inLoop)?.output;
+}
+/**
+ * Restore `ctx` for a turn being resumed. Returns `false` when `setup`
+ * hasn't completed (it will run, and resolve everything itself).
+ */
+export async function rehydrateTurnContext(ctx, runId, journal) {
+    const steps = completedSteps(journal);
+    const setup = outputOf(steps, 'setup');
+    if (setup === undefined)
+        return false;
+    if (ctx.bindings.provenance?.newBuilder !== undefined) {
+        ctx.provenance = ctx.bindings.provenance.newBuilder({ runId, tenantId: ctx.input.tenantId });
+        ctx.provenanceBindings = ctx.bindings.provenance;
+    }
+    await loadTurnConversation(ctx);
+    ctx.hitlPolicy = await resolveTurnHitlPolicy(ctx);
+    await resolveTurnEnvironment(ctx, { providerId: setup.providerId, model: setup.providerModel });
+    const userMessage = outputOf(steps, 'persist-user-message');
+    if (userMessage !== undefined) {
+        await restoreAppended(ctx, userMessage.sequence);
+        ctx.storedBeforePark = storedBeforePark(ctx, steps);
+    }
+    const retrievals = outputOf(steps, 'run-retrievals');
+    if (retrievals?.retrieved !== undefined)
+        ctx.retrieved = retrievals.retrieved;
+    for (const s of steps.filter((s) => s.nodeId === 'model-call' && s.inLoop)) {
+        const out = s.output;
+        ctx.usage.steps = Math.max(ctx.usage.steps, out.step ?? 0);
+        ctx.usage.promptTokens += out.iterationUsage?.promptTokens ?? 0;
+        ctx.usage.completionTokens += out.iterationUsage?.completionTokens ?? 0;
+        ctx.usage.totalCostUsd += out.iterationUsage?.costUsd ?? 0;
+        if (out.provider !== undefined)
+            ctx.lastProvider = out.provider;
+    }
+    return true;
+}
+/**
+ * The messages no completed step accounts for: those the step the turn
+ * parked in stored before it parked.
+ */
+function storedBeforePark(ctx, steps) {
+    const accounted = new Set();
+    if (ctx.userMessage !== undefined)
+        accounted.add(ctx.userMessage.sequence);
+    for (const s of steps.filter((s) => s.nodeId === 'dispatch-tools' && s.inLoop)) {
+        const out = s.output;
+        for (const m of out.iterationAppended ?? [])
+            accounted.add(m.sequence);
+    }
+    return ctx.appended.filter((m) => !accounted.has(m.sequence));
+}
+/** The messages the turn stored before the park, from its user message on. */
+async function restoreAppended(ctx, fromSequence) {
+    const read = await ctx.bindings.conversationBinding.readMessages({
+        tenantId: ctx.input.tenantId,
+        conversationId: ctx.input.conversationId,
+        sinceSequence: fromSequence - 1,
+    });
+    if (read.kind === 'err')
+        throwAgentTurnFailure(read.error);
+    const turnMessages = read.value.filter((m) => m.sequence >= fromSequence);
+    ctx.appended.push(...turnMessages);
+    const user = turnMessages.find((m) => m.sequence === fromSequence && m.role === 'user');
+    if (user !== undefined)
+        ctx.userMessage = user;
+}
+//# sourceMappingURL=rehydrate.js.map

package/dist/handlers/rehydrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.js","sourceRoot":"","sources":["../../src/handlers/rehydrate.ts"],"names":[],"mappings":"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"}

package/dist/handlers/render-prompt.d.ts

@@ -0,0 +1,12 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Render the agent's instructions template with caller-supplied
+ * parameters + framework auto-vars. Fails the run with a
+ * `model-invocation-failed` (surfaced through `AgentTurnFailure`) if
+ * required parameters are missing or the template throws.
+ *
+ * Setup must have run first — `ctx.conversation` is required.
+ */
+export declare function buildRenderPromptHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=render-prompt.d.ts.map

package/dist/handlers/render-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-prompt.d.ts","sourceRoot":"","sources":["../../src/handlers/render-prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA2BtE"}

package/dist/handlers/render-prompt.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { renderInstructions } from '../prompt.js';
+import { throwAgentTurnFailure } from './errors.js';
+/**
+ * Render the agent's instructions template with caller-supplied
+ * parameters + framework auto-vars. Fails the run with a
+ * `model-invocation-failed` (surfaced through `AgentTurnFailure`) if
+ * required parameters are missing or the template throws.
+ *
+ * Setup must have run first — `ctx.conversation` is required.
+ */
+export function buildRenderPromptHandler(ctx) {
+    return async () => {
+        if (ctx.conversation === undefined) {
+            throwAgentTurnFailure({
+                code: 'model-invocation-failed',
+                message: 'render-prompt invoked before setup completed',
+                cause: null,
+            });
+        }
+        const rendered = renderInstructions(ctx.input.agent, {
+            parameters: ctx.input.parameters ?? {},
+            ...(ctx.input.input !== undefined && { input: ctx.input.input }),
+            conversation: {
+                id: ctx.input.conversationId,
+                turn: ctx.conversation.turnCount + 1,
+            },
+        });
+        if (!rendered.ok) {
+            throwAgentTurnFailure({
+                code: 'model-invocation-failed',
+                message: `Prompt render failed: ${rendered.error.message}`,
+                cause: rendered.error,
+            });
+        }
+        ctx.renderedPrompt = rendered.value.rendered;
+        return { rendered: rendered.value.rendered };
+    };
+}
+//# sourceMappingURL=render-prompt.js.map

package/dist/handlers/render-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-prompt.js","sourceRoot":"","sources":["../../src/handlers/render-prompt.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAgB;IACvD,OAAO,KAAK,IAAI,EAAE;QAChB,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACnC,qBAAqB,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,8CAA8C;gBACvD,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE;YACnD,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE;YACtC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAChE,YAAY,EAAE;gBACZ,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc;gBAC5B,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,SAAS,GAAG,CAAC;aACrC;SACF,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,qBAAqB,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,yBAAyB,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE;gBAC1D,KAAK,EAAE,QAAQ,CAAC,KAAK;aACtB,CAAC,CAAC;QACL,CAAC;QACD,GAAG,CAAC,cAAc,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC7C,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC"}

package/dist/handlers/resolve-tools.d.ts

@@ -0,0 +1,10 @@
+import type { ToolRegistry } from '@kindgi/tools';
+import type { Agent } from '../types.js';
+import type { TurnContext } from './context.js';
+/**
+ * Resolve the agent's tool references against one tenant's registry
+ * (`ToolRegistry.forTenant`). Throws the turn failure for an unknown
+ * tool or an unsatisfiable version range.
+ */
+export declare function resolveTurnTools(registry: ToolRegistry, agent: Agent): NonNullable<TurnContext['tools']>;
+//# sourceMappingURL=resolve-tools.d.ts.map

package/dist/handlers/resolve-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-tools.d.ts","sourceRoot":"","sources":["../../src/handlers/resolve-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAQ,YAAY,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,KAAK,GACX,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAgDnC"}

package/dist/handlers/resolve-tools.js

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { throwAgentTurnFailure } from './errors.js';
+/**
+ * Resolve the agent's tool references against one tenant's registry
+ * (`ToolRegistry.forTenant`). Throws the turn failure for an unknown
+ * tool or an unsatisfiable version range.
+ */
+export function resolveTurnTools(registry, agent) {
+    const definitions = [];
+    const byName = new Map();
+    for (const ref of agent.tools) {
+        // Agent references tools by (id, range).
+        // Resolve at run start via `resolve` on the tenant-bound registry
+        // (npm-compatible semver, backed by `maxSatisfying`); capture `resolvedVersion` in
+        // the byName map so `dispatch-tools` can emit it in provenance +
+        // telemetry — a replay can then pin against the same version.
+        const resolved = registry.resolve(ref.id, ref.version);
+        if (resolved.kind === 'err') {
+            const err = resolved.error;
+            if (err.code === 'tool-not-found') {
+                throwAgentTurnFailure({
+                    code: 'unresolved-tool',
+                    message: `Tool "${ref.id}" declared by agent "${agent.id}" is not registered`,
+                    toolId: ref.id,
+                });
+            }
+            if (err.code === 'invalid-version-range' || err.code === 'tool-version-unresolvable') {
+                throwAgentTurnFailure({
+                    code: 'tool-version-unresolvable',
+                    message: err.message,
+                    toolId: ref.id,
+                    requestedRange: ref.version,
+                    ...(err.code === 'tool-version-unresolvable' && {
+                        availableVersions: err.availableVersions,
+                    }),
+                });
+            }
+            throwAgentTurnFailure({
+                code: 'unresolved-tool',
+                message: err.message,
+                toolId: ref.id,
+            });
+        }
+        const { tool, resolvedVersion } = resolved.value;
+        definitions.push({
+            name: tool.id,
+            description: tool.description,
+            inputSchema: tool.input,
+        });
+        byName.set(tool.id, { tool, resolvedVersion, requestedRange: ref.version });
+    }
+    return { definitions, byName };
+}
+//# sourceMappingURL=resolve-tools.js.map

package/dist/handlers/resolve-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-tools.js","sourceRoot":"","sources":["../../src/handlers/resolve-tools.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAQjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAsB,EACtB,KAAY;IAEZ,MAAM,WAAW,GAA0B,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,GAAG,EAGnB,CAAC;IACJ,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC9B,yCAAyC;QACzC,kEAAkE;QAClE,mFAAmF;QACnF,iEAAiE;QACjE,8DAA8D;QAC9D,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,EAAW,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QAChE,IAAI,QAAQ,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC;YAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;gBAClC,qBAAqB,CAAC;oBACpB,IAAI,EAAE,iBAAiB;oBACvB,OAAO,EAAE,SAAS,GAAG,CAAC,EAAE,wBAAwB,KAAK,CAAC,EAAE,qBAAqB;oBAC7E,MAAM,EAAE,GAAG,CAAC,EAAE;iBACf,CAAC,CAAC;YACL,CAAC;YACD,IAAI,GAAG,CAAC,IAAI,KAAK,uBAAuB,IAAI,GAAG,CAAC,IAAI,KAAK,2BAA2B,EAAE,CAAC;gBACrF,qBAAqB,CAAC;oBACpB,IAAI,EAAE,2BAA2B;oBACjC,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,MAAM,EAAE,GAAG,CAAC,EAAE;oBACd,cAAc,EAAE,GAAG,CAAC,OAAO;oBAC3B,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,2BAA2B,IAAI;wBAC9C,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;qBACzC,CAAC;iBACH,CAAC,CAAC;YACL,CAAC;YACD,qBAAqB,CAAC;gBACpB,IAAI,EAAE,iBAAiB;gBACvB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,MAAM,EAAE,GAAG,CAAC,EAAE;aACf,CAAC,CAAC;QACL,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC;QACjD,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,IAAI,CAAC,EAAE;YACb,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,KAA0C;SAC7D,CAAC,CAAC;QACH,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,cAAc,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACjC,CAAC"}