@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/dist/handlers/result-shape.d.ts

@@ -0,0 +1,94 @@
+import type { EvaluationResult } from '@kindgi/guardrails';
+import type { Provenance } from '@kindgi/provenance';
+import type { RunId } from '@kindgi/types';
+import type { ConversationId, ConversationMessage, RetrievedFact } from '../types.js';
+/**
+ * Public shape returned by `invokeAgent` on success. Extracted from
+ * `invoke.ts` into this module so handler code can import the type
+ * without pulling in the orchestration entrypoint (avoids circular
+ * deps).
+ */
+export interface AgentTurnUsage {
+    readonly steps: number;
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalCostUsd: number;
+    readonly durationMs: number;
+}
+/**
+ * Something about a completed turn its caller should know.
+ * `fallback-provider`: the turn ran on a fallback provider
+ * (`ProviderMetadata.fallback`, e.g. `dev-echo`) because no other
+ * registered provider satisfies the agent's capability.
+ */
+export interface AgentTurnWarning {
+    readonly code: 'fallback-provider';
+    readonly message: string;
+}
+export interface AgentTurnResult {
+    /** The kernel run of this turn. */
+    readonly runId: RunId;
+    readonly conversationId: ConversationId;
+    readonly turnNumber: number;
+    readonly appended: readonly ConversationMessage[];
+    readonly response: ConversationMessage;
+    readonly retrieved: readonly RetrievedFact[];
+    readonly violations: readonly EvaluationResult[];
+    readonly usage: AgentTurnUsage;
+    readonly provider: {
+        readonly id: string;
+        readonly model: string;
+    };
+    /** Present when there is something to warn about (see `AgentTurnWarning`). */
+    readonly warnings?: readonly AgentTurnWarning[];
+    /**
+     * The parsed, schema-valid answer, when the agent declares `output`.
+     * `null` on a dry run (the model call is skipped, so there is no
+     * answer to validate).
+     */
+    readonly output?: unknown;
+    readonly provenance?: Provenance;
+    /**
+     * `true` when the turn was executed with `InvokeAgentInput.dryRun: true`.
+     * On dry runs: `appended` messages are synthetic (never persisted);
+     * no provenance is emitted; retrievals still ran for real (reads are
+     * side-effect-free); the model call was skipped and returned a fixed
+     * mock. Consumers filter by this to distinguish plan previews from
+     * executed turns.
+     */
+    readonly dryRun?: boolean;
+    /**
+     * Terminal state of the run backing this turn (park-and-resume).
+     * Absent = 'completed'. `'suspended'` = the run parked on a HITL waitpoint;
+     * `response`/`appended`/`usage` are empty placeholders until the
+     * waitpoint resolves and the run resumes to completion. Callers that
+     * render the final response should branch on this before reading
+     * `response.content`.
+     */
+    readonly status?: 'completed' | 'suspended';
+}
+/**
+ * What an agent step in a flow outputs — the authoring contract for the
+ * nodes after it. They read the typed answer as
+ * `nodeOutputs.<step>.output.<field>` and the answer's text as
+ * `nodeOutputs.<step>.text`.
+ */
+export interface AgentStepOutput {
+    /** The parsed answer, when the agent declares `output`. */
+    readonly output?: unknown;
+    /** The final answer's text. */
+    readonly text: string;
+    /** The step's agent turn — a child run of the flow run. */
+    readonly runId: RunId;
+    readonly conversationId: ConversationId;
+    readonly usage: AgentTurnUsage;
+    /** Non-blocking guardrail findings on the answer. */
+    readonly violations: readonly {
+        readonly guardrailId: string;
+        readonly severity: string;
+        readonly action: string;
+    }[];
+}
+/** An agent step's output, from its turn's result. */
+export declare function agentStepOutput(result: AgentTurnResult): AgentStepOutput;
+//# sourceMappingURL=result-shape.d.ts.map

package/dist/handlers/result-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-shape.d.ts","sourceRoot":"","sources":["../../src/handlers/result-shape.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,SAAS;QAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,EAAE,CAAC;CACL;AAED,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAcxE"}

package/dist/handlers/result-shape.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/** An agent step's output, from its turn's result. */
+export function agentStepOutput(result) {
+    const content = result.response.content;
+    return {
+        ...(result.output !== undefined && { output: result.output }),
+        text: typeof content === 'string' ? content : JSON.stringify(content),
+        runId: result.runId,
+        conversationId: result.conversationId,
+        usage: result.usage,
+        violations: result.violations.map((v) => ({
+            guardrailId: v.guardrailId,
+            severity: v.severity,
+            action: v.action,
+        })),
+    };
+}
+//# sourceMappingURL=result-shape.js.map

package/dist/handlers/result-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-shape.js","sourceRoot":"","sources":["../../src/handlers/result-shape.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAgGjC,sDAAsD;AACtD,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;IACxC,OAAO;QACL,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7D,IAAI,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QACrE,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACxC,WAAW,EAAE,CAAC,CAAC,WAAgC;YAC/C,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,MAAM,EAAE,CAAC,CAAC,MAAM;SACjB,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/handlers/run-retrievals.d.ts

@@ -0,0 +1,10 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Execute the agent's declared retrieval intents. Populates
+ * `ctx.retrieved` for downstream prompt building + emits
+ * `retrieval.completed`. Adds provenance nodes + edges when a builder
+ * is wired.
+ */
+export declare function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=run-retrievals.d.ts.map

package/dist/handlers/run-retrievals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-retrievals.d.ts","sourceRoot":"","sources":["../../src/handlers/run-retrievals.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA2DvE"}

package/dist/handlers/run-retrievals.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { runRetrievals } from '../retrieval.js';
+import { emitTurnEvent } from '../streaming.js';
+import { throwAgentTurnFailure } from './errors.js';
+/**
+ * Execute the agent's declared retrieval intents. Populates
+ * `ctx.retrieved` for downstream prompt building + emits
+ * `retrieval.completed`. Adds provenance nodes + edges when a builder
+ * is wired.
+ */
+export function buildRunRetrievalsHandler(ctx) {
+    return async () => {
+        if (ctx.conversation === undefined || ctx.userMessage === undefined) {
+            throwAgentTurnFailure({
+                code: 'model-invocation-failed',
+                message: 'run-retrievals invoked before setup + persist-user-message completed',
+                cause: null,
+            });
+        }
+        const retrieved = await runRetrievals(ctx.input.agent, ctx.conversation, ctx.input.conversationId, ctx.input.userMessage, {
+            memory: ctx.bindings.memoryBinding,
+            ...(ctx.bindings.embeddingRegistry !== undefined && {
+                embeddingRegistry: ctx.bindings.embeddingRegistry,
+            }),
+            ...(ctx.bindings.embeddingModel !== undefined && {
+                embeddingModel: ctx.bindings.embeddingModel,
+            }),
+        });
+        if (retrieved.kind === 'err')
+            throwAgentTurnFailure(retrieved.error);
+        ctx.retrieved = retrieved.value;
+        await emitTurnEvent(ctx.bindings.onEvent, {
+            kind: 'retrieval.completed',
+            count: retrieved.value.length,
+            factIds: retrieved.value.map((r) => r.fact.id),
+        });
+        if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
+            for (const r of retrieved.value) {
+                ctx.provenance.addNode({
+                    id: `retrieval:${r.fact.id}`,
+                    kind: 'retrieval',
+                    timestamp: ctx.userMessage.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 }),
+                    },
+                });
+                ctx.provenance.addEdge({
+                    from: `retrieval:${r.fact.id}`,
+                    to: `input:${ctx.userMessage.sequence}`,
+                    kind: 'influenced-by',
+                });
+            }
+        }
+        // The facts go in the journal: a resumed turn restores them from it
+        // (`rehydrateTurnContext`) rather than retrieving again.
+        return { count: retrieved.value.length, retrieved: retrieved.value };
+    };
+}
+//# sourceMappingURL=run-retrievals.js.map

package/dist/handlers/run-retrievals.js.map

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

package/dist/handlers/run-snapshot.d.ts

@@ -0,0 +1,4 @@
+import type { NodeContext } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+export declare function writeRunSnapshot(ctx: TurnContext, kctx: NodeContext): Promise<void>;
+//# sourceMappingURL=run-snapshot.d.ts.map

package/dist/handlers/run-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-snapshot.d.ts","sourceRoot":"","sources":["../../src/handlers/run-snapshot.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBzF"}

package/dist/handlers/run-snapshot.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export async function writeRunSnapshot(ctx, kctx) {
+    // Snapshot write is best-effort: if it fails, the turn still proceeds.
+    // Resume paths will just get `run-snapshot-missing` and the caller
+    // knows to surface the run as unrecoverable. The alternative (throw
+    // and fail the turn) is worse — a snapshot-write hiccup shouldn't
+    // block a fresh turn from running. The RunSnapshotBinding impl must be
+    // idempotent under kernel replay (e.g. ON CONFLICT DO NOTHING on runId).
+    await ctx.bindings.runSnapshotBinding.write({
+        runId: kctx.runId,
+        tenantId: ctx.input.tenantId,
+        projectId: ctx.input.projectId,
+        agentId: ctx.input.agent.id,
+        agentVersion: ctx.input.agent.version,
+        conversationId: ctx.input.conversationId,
+        userMessage: ctx.input.userMessage,
+        ...(ctx.input.parameters !== undefined && { parameters: ctx.input.parameters }),
+        ...(ctx.input.input !== undefined && { input: ctx.input.input }),
+        ...(ctx.input.participantId !== undefined && { participantId: ctx.input.participantId }),
+        ...(ctx.input.dryRun === true && { dryRun: true }),
+        ...(ctx.input.principal !== undefined && { principal: ctx.input.principal }),
+        ...(ctx.input.authz !== undefined && { authz: ctx.input.authz }),
+    });
+}
+//# sourceMappingURL=run-snapshot.js.map

package/dist/handlers/run-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-snapshot.js","sourceRoot":"","sources":["../../src/handlers/run-snapshot.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAoBjC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAgB,EAAE,IAAiB;IACxE,uEAAuE;IACvE,mEAAmE;IACnE,oEAAoE;IACpE,kEAAkE;IAClE,uEAAuE;IACvE,yEAAyE;IACzE,MAAM,GAAG,CAAC,QAAQ,CAAC,kBAAkB,CAAC,KAAK,CAAC;QAC1C,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ;QAC5B,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,SAAS;QAC9B,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QAC3B,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO;QACrC,cAAc,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc;QACxC,WAAW,EAAE,GAAG,CAAC,KAAK,CAAC,WAAW;QAClC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;QAC/E,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QACxF,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAC5E,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;KACjE,CAAC,CAAC;AACL,CAAC"}

package/dist/handlers/setup.d.ts

@@ -0,0 +1,25 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * The first node in the flow. Runs every precondition check in one
+ * gate so the run either commits to a full turn or fails fast before
+ * the user message is stored in the conversation (only the run
+ * snapshot is written first):
+ *
+ *   1. Load + validate conversation (open, not closed, matches agent version).
+ *   2. Session-level HITL gate (`conversationPolicy.hitl.afterTurns` /
+ *      `hitlAfterTurns`).
+ *   3. Resolve declared guardrails against the guardrails bound for the run.
+ *   4. Resolve declared tools against the tenant's tool registry
+ *      (`ToolRegistry.forTenant`).
+ *   5. Merge the tenant policy (bound policy + policy registry), then
+ *      route the agent's first capability through the provider registry.
+ *
+ * Populates `ctx.conversation`, `ctx.guardrails`, `ctx.tools`,
+ * `ctx.tenantPolicy`, `ctx.provider` and `ctx.model` for downstream
+ * handlers. Emits `turn.started` on success. Any failure surfaces as an `AgentTurnFailure` — the run
+ * fails and `projectRunResult` translates it back into the caller's
+ * `InvokeAgentError`.
+ */
+export declare function buildSetupHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=setup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/handlers/setup.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAmChD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAyM/D"}

package/dist/handlers/setup.js

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { createHash } from 'node:crypto';
+import { WaitpointCancelledError } from '@kindgi/handler';
+import { evaluateSessionGate } from '../guardrails-gate.js';
+import { emitTurnEvent } from '../streaming.js';
+import { throwAgentTurnFailure } from './errors.js';
+import { writeRunSnapshot } from './run-snapshot.js';
+import { loadTurnConversation, resolveTurnEnvironment, resolveTurnHitlPolicy, } from './turn-environment.js';
+/**
+ * Deterministic waitpoint token — must produce the same value on every
+ * flow replay so the kernel's `waitForToken(tokenId)` resolves against
+ * the correct suspended state. Not sensitive to time or approval id;
+ * driven only by (runId, gate scope, turnCount).
+ */
+function computeSessionGateWaitToken(input) {
+    return createHash('sha256')
+        .update(`agent-turn:session-hitl-gate:${input.runId}:${input.turnCount}`)
+        .digest('hex')
+        .slice(0, 40);
+}
+/**
+ * The first node in the flow. Runs every precondition check in one
+ * gate so the run either commits to a full turn or fails fast before
+ * the user message is stored in the conversation (only the run
+ * snapshot is written first):
+ *
+ *   1. Load + validate conversation (open, not closed, matches agent version).
+ *   2. Session-level HITL gate (`conversationPolicy.hitl.afterTurns` /
+ *      `hitlAfterTurns`).
+ *   3. Resolve declared guardrails against the guardrails bound for the run.
+ *   4. Resolve declared tools against the tenant's tool registry
+ *      (`ToolRegistry.forTenant`).
+ *   5. Merge the tenant policy (bound policy + policy registry), then
+ *      route the agent's first capability through the provider registry.
+ *
+ * Populates `ctx.conversation`, `ctx.guardrails`, `ctx.tools`,
+ * `ctx.tenantPolicy`, `ctx.provider` and `ctx.model` for downstream
+ * handlers. Emits `turn.started` on success. Any failure surfaces as an `AgentTurnFailure` — the run
+ * fails and `projectRunResult` translates it back into the caller's
+ * `InvokeAgentError`.
+ */
+export function buildSetupHandler(ctx) {
+    return async (_input, kctx) => {
+        // Write the run's reconstruction snapshot on FIRST
+        // execution (idempotent via PK on runId). resumeAgentTurn(runId)
+        // reads this to rebuild the same InvokeAgentInput when a parked
+        // waitpoint resolves — kernel replay lands in an identical context.
+        // The binding write is tenant-scoped and idempotent on runId, so it
+        // is safe under handler replay.
+        await writeRunSnapshot(ctx, kctx);
+        // Create the provenance builder BEFORE the session-HITL
+        // gate so we can emit wait/resume nodes around the park boundary.
+        // The builder is fresh on every replay (kernel replays the flow
+        // from scratch); nodes emitted before the first suspend are
+        // discarded (persist-provenance runs only on run.completed). On the
+        // final replay, both wait AND resume nodes get emitted and
+        // persisted — the DAG shows the whole cycle.
+        if (ctx.bindings.provenance?.newBuilder !== undefined) {
+            ctx.provenance = ctx.bindings.provenance.newBuilder({
+                runId: kctx.runId,
+                tenantId: ctx.input.tenantId,
+            });
+            ctx.provenanceBindings = ctx.bindings.provenance;
+        }
+        const conversation = await loadTurnConversation(ctx);
+        // Session HITL gate — checked BEFORE tool/guardrail resolution so
+        // callers with a HITL block don't waste routing work.
+        //
+        // Park-and-resume: instead of failing the turn with
+        // `hitl-required`, we PARK the run on a kernel waitpoint. A reviewer's
+        // decision (via POST /v1/approvals/:id/complete) resolves the
+        // waitpoint; the kernel replays this handler; `waitForToken` returns
+        // the reviewer's decision object; the handler branches on it and
+        // continues (approve) or fails cleanly (reject / cancelled / timeout).
+        //
+        // Same run, same conversationId, same provenance record — the audit
+        // trail stays coherent across the human-in-the-loop cycle.
+        //
+        // Enqueue is idempotent on `waitTokenId` (see
+        // `HitlEnqueueInput.waitTokenId`) — safe under handler replay.
+        // The turn's approval rules — the agent's, held to the tenant's
+        // `hitl` policy — before the gate that may park on them.
+        const effectiveHitl = await resolveTurnHitlPolicy(ctx);
+        ctx.hitlPolicy = effectiveHitl;
+        const sessionGate = evaluateSessionGate({ ...(effectiveHitl.turn !== undefined && { afterTurns: effectiveHitl.turn.afterTurns }) }, conversation.turnCount);
+        if (sessionGate.kind === 'hitl-required') {
+            const waitTokenId = computeSessionGateWaitToken({
+                runId: kctx.runId,
+                turnCount: conversation.turnCount,
+            });
+            const timeoutMs = effectiveHitl.timeoutMs;
+            const expiresAt = new Date(Date.now() + timeoutMs).toISOString();
+            if (ctx.bindings.hitl?.enqueue !== undefined) {
+                try {
+                    await ctx.bindings.hitl.enqueue({
+                        tenantId: ctx.input.tenantId,
+                        subjectKind: 'agent-turn:session-hitl-gate',
+                        subjectRef: {
+                            conversationId: ctx.input.conversationId,
+                            agentId: ctx.input.agent.id,
+                            agentVersion: ctx.input.agent.version,
+                            turnCount: conversation.turnCount,
+                            threshold: sessionGate.threshold,
+                        },
+                        requiredRole: effectiveHitl.defaultReviewerRole,
+                        title: `HITL review required for ${ctx.input.agent.name}`,
+                        description: sessionGate.reason,
+                        waitTokenId,
+                        provenanceRef: { runId: kctx.runId },
+                        expiresAt: expiresAt,
+                    });
+                }
+                catch {
+                    // Failing sink must not affect turn outcome — swallow. The
+                    // waitForToken below will still park; if no reviewer sees the
+                    // approval row, the kernel timeout cancels the wait per policy.
+                }
+            }
+            // Provenance: emit `wait` node right before the park. On first
+            // execution (park), persist-provenance never runs so this node is
+            // lost — that's fine. On the FINAL replay after resume, this node
+            // AND the `resume` node below both emit and get persisted.
+            const waitNodeId = `session-hitl-gate-wait:${conversation.turnCount}`;
+            const resumeNodeId = `session-hitl-gate-resume:${conversation.turnCount}`;
+            if (ctx.provenance !== undefined) {
+                ctx.provenance.addNode({
+                    id: waitNodeId,
+                    kind: 'wait',
+                    timestamp: new Date().toISOString(),
+                    actor: `agent:${ctx.input.agent.id}`,
+                    attributes: {
+                        gate: 'session-hitl',
+                        turnCount: conversation.turnCount,
+                        threshold: sessionGate.threshold,
+                        waitTokenId,
+                    },
+                });
+            }
+            try {
+                const decision = await kctx.waitForToken(waitTokenId, {
+                    timeoutMs,
+                });
+                // Post-resume: emit the resume node + resumed-from edge. Only
+                // runs on the REPLAY path — the first execution throws
+                // SuspensionSignal inside waitForToken and never gets here.
+                if (ctx.provenance !== undefined) {
+                    ctx.provenance.addNode({
+                        id: resumeNodeId,
+                        kind: 'resume',
+                        timestamp: new Date().toISOString(),
+                        actor: `agent:${ctx.input.agent.id}`,
+                        attributes: {
+                            gate: 'session-hitl',
+                            decision: decision.decided,
+                            ...(decision.rationale !== undefined && { rationale: decision.rationale }),
+                        },
+                    });
+                    ctx.provenance.addEdge({
+                        from: waitNodeId,
+                        to: resumeNodeId,
+                        kind: 'resumed-from',
+                    });
+                }
+                if (decision.decided === 'reject') {
+                    throwAgentTurnFailure({
+                        code: 'hitl-rejected',
+                        message: `Reviewer rejected the session-HITL gate${decision.rationale !== undefined ? `: ${decision.rationale}` : ''}`,
+                        ...(decision.rationale !== undefined && { rationale: decision.rationale }),
+                    });
+                }
+                // decision.decided === 'approve' → fall through, turn proceeds
+                // normally through the rest of setup.
+            }
+            catch (cause) {
+                if (cause instanceof WaitpointCancelledError) {
+                    // Emit resume node with cancelled attribute so the DAG still
+                    // shows the resolution — even for terminal cancellations the
+                    // flow reached the resume boundary before the failure.
+                    if (ctx.provenance !== undefined) {
+                        ctx.provenance.addNode({
+                            id: resumeNodeId,
+                            kind: 'resume',
+                            timestamp: new Date().toISOString(),
+                            actor: `agent:${ctx.input.agent.id}`,
+                            attributes: {
+                                gate: 'session-hitl',
+                                decision: 'cancelled',
+                                reason: cause.reason,
+                            },
+                        });
+                        ctx.provenance.addEdge({
+                            from: waitNodeId,
+                            to: resumeNodeId,
+                            kind: 'resumed-from',
+                        });
+                    }
+                    throwAgentTurnFailure({
+                        code: 'hitl-cancelled',
+                        message: `Session-HITL gate cancelled: ${cause.reason}`,
+                        reason: cause.reason,
+                    });
+                }
+                // SuspensionSignal or anything else — let it propagate. The
+                // kernel executor's dispatch catch handles SuspensionSignal by
+                // suspending the run; other errors become step.failed.
+                throw cause;
+            }
+        }
+        const environment = await resolveTurnEnvironment(ctx);
+        // Provenance builder was created earlier (before the session-HITL
+        // gate) so wait/resume nodes could bracket the park boundary. Kept
+        // here as a documentation anchor — see the block above `getConversation`.
+        await emitTurnEvent(ctx.bindings.onEvent, {
+            kind: 'turn.started',
+            conversationId: ctx.input.conversationId,
+            turnNumber: conversation.turnCount + 1,
+            agentId: ctx.input.agent.id,
+            agentVersion: ctx.input.agent.version,
+            userMessage: ctx.input.userMessage,
+        });
+        // Kernel output — kept minimal + JSON-safe. Real state lives on ctx.
+        return {
+            turnNumber: conversation.turnCount + 1,
+            providerId: environment.providerId,
+            providerModel: environment.model,
+            toolCount: environment.toolCount,
+        };
+    };
+}
+//# sourceMappingURL=setup.js.map

package/dist/handlers/setup.js.map

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

package/dist/handlers/structured-output.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Typed agent output: reading the model's final answer as JSON and
+ * checking it against the agent's `output.schema`, and the repair
+ * message sent back when it doesn't fit.
+ *
+ * The repair loop lives in `budget-check`: an invalid answer with
+ * repairs left keeps the turn going, with the answer and a repair
+ * message appended to the conversation sent to the model. Repairs are
+ * counted from those messages, so a replayed turn counts the same.
+ */
+import type { ModelMessage } from '@kindgi/capabilities';
+import type { AgentOutputSpec } from '../types.js';
+/** Default number of repair attempts. */
+export declare const DEFAULT_MAX_REPAIRS = 1;
+export type OutputCheck = {
+    readonly kind: 'ok';
+    readonly value: unknown;
+} | {
+    readonly kind: 'invalid';
+    readonly errors: readonly string[];
+};
+/**
+ * The answer's text as JSON. Accepts a bare JSON value or one fenced
+ * as ```json … ``` (models often fence it).
+ */
+export declare function parseJsonAnswer(content: unknown): OutputCheck;
+/** Compiled once per turn — see `outputChecker`. */
+export interface OutputChecker {
+    check(content: unknown): OutputCheck;
+}
+export declare function outputChecker(spec: AgentOutputSpec): OutputChecker;
+/** Whether a message is one of this module's repair requests. */
+export declare function isRepairMessage(m: ModelMessage): boolean;
+/** How many repairs this turn has asked for so far. */
+export declare function repairsSoFar(messages: readonly ModelMessage[]): number;
+/** The message asking the model to fix its answer. */
+export declare function repairMessage(spec: AgentOutputSpec, errors: readonly string[]): ModelMessage;
+//# sourceMappingURL=structured-output.d.ts.map

package/dist/handlers/structured-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../../src/handlers/structured-output.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,yCAAyC;AACzC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAKrC,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAErE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAgB7D;AAOD,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAAC;CACtC;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,aAAa,CAmBlE;AAYD,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAExD;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAEtE;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,CAa5F"}