@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/dist/handlers/build-initial-messages.d.ts

@@ -0,0 +1,17 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Compose the initial `modelMessages` array the loop's first iteration
+ * feeds to the model:
+ *
+ *   [ system: rendered prompt,
+ *     system: retrieved context (if any),
+ *     ...history,
+ *     user: current message ]
+ *
+ * Output shape: `{ nextMessages: ModelMessage[] }` — matches the loop
+ * iteration output's `nextMessages` field so the loop body can treat
+ * iteration 0's input identically to subsequent iterations'.
+ */
+export declare function buildBuildInitialMessagesHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=build-initial-messages.d.ts.map

package/dist/handlers/build-initial-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-initial-messages.d.ts","sourceRoot":"","sources":["../../src/handlers/build-initial-messages.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAmD9E"}

package/dist/handlers/build-initial-messages.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { formatRetrievedForPrompt } from '../retrieval.js';
+import { throwAgentTurnFailure } from './errors.js';
+/**
+ * Compose the initial `modelMessages` array the loop's first iteration
+ * feeds to the model:
+ *
+ *   [ system: rendered prompt,
+ *     system: retrieved context (if any),
+ *     ...history,
+ *     user: current message ]
+ *
+ * Output shape: `{ nextMessages: ModelMessage[] }` — matches the loop
+ * iteration output's `nextMessages` field so the loop body can treat
+ * iteration 0's input identically to subsequent iterations'.
+ */
+export function buildBuildInitialMessagesHandler(ctx) {
+    return async (input) => {
+        if (ctx.conversation === undefined || ctx.retrieved === undefined) {
+            throwAgentTurnFailure({
+                code: 'model-invocation-failed',
+                message: 'build-initial-messages invoked before setup / retrievals completed',
+                cause: null,
+            });
+        }
+        // `input` is `run-retrievals`'s output; discarded — the rendered
+        // prompt is read from setup's sibling output via ctx (retained on
+        // the closure by render-prompt through the local field `renderedPrompt`).
+        void input;
+        const historyLimit = ctx.input.agent.conversationPolicy?.historyLimit;
+        const messages = await ctx.bindings.conversationBinding.readMessages({
+            tenantId: ctx.input.tenantId,
+            conversationId: ctx.input.conversationId,
+        });
+        if (messages.kind === 'err')
+            throwAgentTurnFailure(messages.error);
+        // The user message just appended is included in the history read;
+        // drop it because the composer adds it explicitly as the last
+        // element.
+        const historyRaw = messages.value.filter((m) => m.sequence !== ctx.userMessage?.sequence);
+        const history = historyLimit === undefined
+            ? historyRaw
+            : historyRaw.slice(Math.max(0, historyRaw.length - historyLimit));
+        const contextBlock = formatRetrievedForPrompt(ctx.retrieved);
+        const contextMessage = contextBlock.length > 0 ? { role: 'system', content: contextBlock } : undefined;
+        const rendered = ctx.renderedPrompt;
+        if (rendered === undefined) {
+            throwAgentTurnFailure({
+                code: 'model-invocation-failed',
+                message: 'build-initial-messages invoked before render-prompt completed',
+                cause: null,
+            });
+        }
+        const modelMessages = [
+            { role: 'system', content: rendered },
+            ...(contextMessage !== undefined ? [contextMessage] : []),
+            ...history.map(conversationToModelMessage),
+            { role: 'user', content: ctx.input.userMessage },
+        ];
+        return { nextMessages: modelMessages };
+    };
+}
+function conversationToModelMessage(msg) {
+    if (msg.role === 'tool') {
+        return {
+            role: 'tool',
+            content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+            ...(msg.toolCall !== undefined && { toolCallId: msg.toolCall.invocationId }),
+        };
+    }
+    if (msg.role === 'agent' && typeof msg.content === 'object' && msg.content !== null) {
+        const structured = msg.content;
+        return {
+            role: 'assistant',
+            content: structured.text ?? '',
+            ...(structured.toolCalls !== undefined && { toolCalls: structured.toolCalls }),
+        };
+    }
+    const role = msg.role === 'agent' ? 'assistant' : msg.role;
+    return {
+        role,
+        content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+    };
+}
+//# sourceMappingURL=build-initial-messages.js.map

package/dist/handlers/build-initial-messages.js.map

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

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

@@ -0,0 +1,10 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * The terminal node — builds the caller-facing `AgentTurnResult` from
+ * accumulated `TurnContext` state, emits `turn.completed`, and returns
+ * the fully-shaped result as the flow's output. `projectRunResult`
+ * unwraps this on the way out.
+ */
+export declare function buildComposeResultHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=compose-result.d.ts.map

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

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

package/dist/handlers/compose-result.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { emitTurnEvent } from '../streaming.js';
+import { throwAgentTurnFailure } from './errors.js';
+import { parseJsonAnswer } from './structured-output.js';
+/** The final answer as JSON — `budget-check` already validated it against the schema. */
+function structuredAnswer(content) {
+    const parsed = parseJsonAnswer(content);
+    return parsed.kind === 'ok' ? parsed.value : null;
+}
+/**
+ * The terminal node — builds the caller-facing `AgentTurnResult` from
+ * accumulated `TurnContext` state, emits `turn.completed`, and returns
+ * the fully-shaped result as the flow's output. `projectRunResult`
+ * unwraps this on the way out.
+ */
+export function buildComposeResultHandler(ctx) {
+    return async (_input, kctx) => {
+        if (ctx.finalMessage === undefined || ctx.conversation === undefined) {
+            throwAgentTurnFailure({
+                code: 'model-invocation-failed',
+                message: 'compose-result invoked before final message + conversation ready',
+                cause: null,
+            });
+        }
+        const durationMs = Date.now() - ctx.startedAt;
+        const usage = {
+            steps: ctx.usage.steps,
+            promptTokens: ctx.usage.promptTokens,
+            completionTokens: ctx.usage.completionTokens,
+            totalCostUsd: ctx.usage.totalCostUsd,
+            durationMs,
+        };
+        const provider = ctx.lastProvider ?? {
+            id: ctx.provider?.metadata.id ?? 'unknown',
+            model: ctx.model?.name ?? 'unknown',
+        };
+        const result = {
+            runId: kctx.runId,
+            conversationId: ctx.input.conversationId,
+            // Dry-run must not advance the conversation's turn counter (no
+            // persistence happened). Real runs report the next turn number.
+            turnNumber: kctx.dryRun ? ctx.conversation.turnCount : ctx.conversation.turnCount + 1,
+            appended: ctx.appended,
+            response: ctx.finalMessage,
+            retrieved: ctx.retrieved ?? [],
+            violations: ctx.nonBlockingViolations ?? [],
+            usage,
+            provider,
+            ...(ctx.provider?.metadata.fallback === true && {
+                warnings: [
+                    {
+                        code: 'fallback-provider',
+                        message: `Answered by "${provider.id}", a fallback provider: no other registered provider satisfies agent "${ctx.input.agent.id}".`,
+                    },
+                ],
+            }),
+            ...(ctx.input.agent.output !== undefined && {
+                output: kctx.dryRun ? null : structuredAnswer(ctx.finalMessage.content),
+            }),
+            ...(ctx.persistedProvenance !== undefined && { provenance: ctx.persistedProvenance }),
+            ...(kctx.dryRun && { dryRun: true }),
+        };
+        await emitTurnEvent(ctx.bindings.onEvent, {
+            kind: 'turn.completed',
+            conversationId: ctx.input.conversationId,
+            turnNumber: ctx.conversation.turnCount + 1,
+            response: ctx.finalMessage,
+            retrieved: ctx.retrieved ?? [],
+            durationMs,
+            totalCostUsd: ctx.usage.totalCostUsd,
+        });
+        // Wrapped explicitly: the runtime reads a returned object with an
+        // `output` key as `{ output, stateDelta }`, and a typed turn's
+        // result has one.
+        return { output: result };
+    };
+}
+//# sourceMappingURL=compose-result.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose-result.js","sourceRoot":"","sources":["../../src/handlers/compose-result.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,yFAAyF;AACzF,SAAS,gBAAgB,CAAC,OAAgB;IACxC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAgB;IACxD,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QAC5B,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACrE,qBAAqB,CAAC;gBACpB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,kEAAkE;gBAC3E,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;QACL,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC;QAC9C,MAAM,KAAK,GAAmB;YAC5B,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK;YACtB,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY;YACpC,gBAAgB,EAAE,GAAG,CAAC,KAAK,CAAC,gBAAgB;YAC5C,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY;YACpC,UAAU;SACX,CAAC;QAEF,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,IAAI;YACnC,EAAE,EAAE,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,IAAI,SAAS;YAC1C,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,IAAI,SAAS;SACpC,CAAC;QAEF,MAAM,MAAM,GAAoB;YAC9B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,cAAc,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc;YACxC,+DAA+D;YAC/D,gEAAgE;YAChE,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,GAAG,CAAC;YACrF,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,QAAQ,EAAE,GAAG,CAAC,YAAY;YAC1B,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE;YAC9B,UAAU,EAAE,GAAG,CAAC,qBAAqB,IAAI,EAAE;YAC3C,KAAK;YACL,QAAQ;YACR,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,KAAK,IAAI,IAAI;gBAC9C,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,mBAAmB;wBACzB,OAAO,EAAE,gBAAgB,QAAQ,CAAC,EAAE,yEAAyE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI;qBACpI;iBACF;aACF,CAAC;YACF,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI;gBAC1C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC;aACxE,CAAC;YACF,GAAG,CAAC,GAAG,CAAC,mBAAmB,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,mBAAmB,EAAE,CAAC;YACrF,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;SACrC,CAAC;QAEF,MAAM,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE;YACxC,IAAI,EAAE,gBAAgB;YACtB,cAAc,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc;YACxC,UAAU,EAAE,GAAG,CAAC,YAAY,CAAC,SAAS,GAAG,CAAC;YAC1C,QAAQ,EAAE,GAAG,CAAC,YAAY;YAC1B,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,EAAE;YAC9B,UAAU;YACV,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY;SACrC,CAAC,CAAC;QAEH,kEAAkE;QAClE,+DAA+D;QAC/D,kBAAkB;QAClB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC,CAAC;AACJ,CAAC"}

package/dist/handlers/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Defaults shared across handler modules. Kept in a single tiny module
+ * so the loop-body handlers can import them without pulling in the
+ * whole invoke.ts orchestration surface.
+ */
+export declare const DEFAULT_MAX_STEPS = 8;
+export declare const DEFAULT_MAX_WALL_MS = 120000;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/handlers/constants.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,mBAAmB,SAAU,CAAC"}

package/dist/handlers/constants.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Defaults shared across handler modules. Kept in a single tiny module
+ * so the loop-body handlers can import them without pulling in the
+ * whole invoke.ts orchestration surface.
+ */
+export const DEFAULT_MAX_STEPS = 8;
+export const DEFAULT_MAX_WALL_MS = 120_000;
+//# sourceMappingURL=constants.js.map

package/dist/handlers/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/handlers/constants.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC"}

package/dist/handlers/context.d.ts

@@ -0,0 +1,210 @@
+import type { ModelInfo, ModelMessage, ModelProvider, ModelToolDefinition, TenantPolicy } from '@kindgi/capabilities';
+import type { Guardrail } from '@kindgi/guardrails';
+import type { ProvenanceBuilder } from '@kindgi/provenance';
+import type { Tool } from '@kindgi/tools';
+import type { EvaluationResult } from '@kindgi/guardrails';
+import type { EffectiveHitlPolicy } from '../hitl-policy.js';
+import type { ProvenanceBindings } from '../provenance-emit.js';
+import type { Agent, Conversation, ConversationMessage, RetrievedFact } from '../types.js';
+import type { HitlBindings, InvokeAgentBindings, InvokeAgentInput } from './public-types.js';
+import type { ToolErrorPolicy } from './tool-errors.js';
+/**
+ * Per-invocation closure state shared across every node handler. This is
+ * a mutable container populated by earlier nodes and read by later
+ * nodes. Kernel journal entries record the coarse node-level inputs and
+ * outputs; this object carries the finer-grained runtime state that is
+ * either not JSON-serializable (functions, ModelProvider instances,
+ * ProvenanceBuilder) or expensive to reserialize per node.
+ *
+ * One `TurnContext` lives for the duration of one `invokeAgent` call.
+ */
+export interface TurnContext {
+    readonly input: InvokeAgentInput;
+    readonly bindings: InvokeAgentBindings;
+    /**
+     * Composed abort signal: fires when the wall-clock timer expires OR
+     * when the caller-provided abortSignal fires. Handlers pass this into
+     * long-running I/O.
+     */
+    readonly turnAbort: AbortController;
+    /**
+     * Millisecond timestamp when `invokeAgent` was called. Used to
+     * compute `usage.durationMs` inside `compose-result`.
+     */
+    readonly startedAt: number;
+    /**
+     * Populated by `setup` — the loaded conversation row.
+     */
+    conversation?: Conversation;
+    /**
+     * Populated by `setup` — resolved tools (per-name map + model
+     * definitions).
+     */
+    tools?: {
+        readonly definitions: readonly ModelToolDefinition[];
+        /**
+         * Per-tool resolved binding: the exact `Tool` instance the runtime
+         * dispatches, the `resolvedVersion` picked by `resolve` on the
+         * tenant's registry (`toolRegistry.forTenant`)
+         * (captured for provenance + telemetry so a replay can pin against
+         * the same version), and the `requestedRange` the agent binding
+         * declared.
+         */
+        readonly byName: ReadonlyMap<string, {
+            readonly tool: Tool;
+            readonly resolvedVersion: string;
+            readonly requestedRange: string;
+        }>;
+    };
+    /**
+     * Populated by `setup` — the provider the router picked for the
+     * agent's first capability.
+     */
+    provider?: ModelProvider;
+    /**
+     * Populated by `setup` alongside `provider` — the specific
+     * `ModelInfo` within that provider the router picked. Threaded into
+     * `ModelCallInput.model` on every invocation this turn.
+     */
+    model?: ModelInfo;
+    /**
+     * Populated by `setup` — resolved guardrails for the final-response gate.
+     */
+    guardrails?: readonly Guardrail[];
+    /**
+     * Populated by `persist-user-message` — the persisted user message row.
+     */
+    userMessage?: ConversationMessage;
+    /**
+     * Populated by `render-prompt` — the rendered system-instructions
+     * string that seeds the first model call.
+     */
+    renderedPrompt?: string;
+    /**
+     * Populated by `run-retrievals` — facts pulled by declared intents.
+     */
+    retrieved?: readonly RetrievedFact[];
+    /**
+     * Populated by `persist-final-message` — the terminal assistant
+     * message. `compose-result` reads it back for the returned
+     * `AgentTurnResult.response`.
+     */
+    finalMessage?: ConversationMessage;
+    /**
+     * Populated by `dispatch-tools` and `persist-final-message` — the
+     * ordered list of every message appended during this turn. Starts
+     * with the user message; then intermediate assistant + tool
+     * messages; then the final assistant message.
+     */
+    appended: ConversationMessage[];
+    /**
+     * Cumulative usage across all model calls this turn. Updated by
+     * `model-call`; read by `budget-check` and `compose-result`.
+     */
+    usage: {
+        steps: number;
+        promptTokens: number;
+        completionTokens: number;
+        totalCostUsd: number;
+    };
+    /**
+     * Provider + model of the most recent model call (the one that
+     * produced the final response). Set by `model-call`; `compose-result`
+     * surfaces it as `AgentTurnResult.provider`.
+     */
+    lastProvider?: {
+        readonly id: string;
+        readonly model: string;
+    };
+    /**
+     * Provenance builder — undefined when the caller didn't wire one.
+     */
+    provenance?: ProvenanceBuilder;
+    /**
+     * Provenance bindings kept for reference (needed by
+     * `persist-provenance` for `emit` + `keyProvider` details).
+     */
+    provenanceBindings?: ProvenanceBindings;
+    /**
+     * The persisted provenance snapshot (post `persist-provenance`).
+     * Present only when the builder was wired AND persistence succeeded.
+     */
+    persistedProvenance?: import('@kindgi/provenance').Provenance;
+    /**
+     * The tenant policy this turn's model was routed under (bound policy
+     * merged with the policy registry's). Populated by `setup`; guardrail
+     * judges route under it too.
+     */
+    tenantPolicy?: TenantPolicy;
+    /**
+     * How this turn retries failed tool calls: the agent's `toolErrors`
+     * (or the default) capped by the tenant's `tool-errors` policy.
+     * Populated by `setup`.
+     */
+    toolErrorPolicy?: ToolErrorPolicy;
+    /**
+     * The turn's approval (HITL) rules: the agent's, held to the tenant's
+     * `hitl` policy. Populated at the start of the turn (`setup`, or the
+     * rebuild of a resumed turn) by `resolveTurnHitlPolicy`.
+     */
+    hitlPolicy?: EffectiveHitlPolicy;
+    /**
+     * Set when the turn resumes after a park in `dispatch-tools` (a
+     * tool-call approval): the messages that step stored before it parked.
+     * The step runs again, and takes its assistant message and the results
+     * of calls that already ran from here instead of storing (and running)
+     * them again. Populated by `rehydrateTurnContext`.
+     */
+    storedBeforePark?: ConversationMessage[];
+    /**
+     * Warnings + other (non-halt) guardrail violations from the
+     * final-response gate. Read by `compose-result` to populate
+     * `AgentTurnResult.violations`.
+     */
+    nonBlockingViolations?: readonly EvaluationResult[];
+    /**
+     * Reason recorded when `turnAbort` fires. Used to distinguish
+     * external cancellation from wall-clock timeout in the projected
+     * error.
+     */
+    abortReason: 'external' | 'timeout' | undefined;
+}
+/**
+ * Iteration output shape produced by the loop body's `budget-check`
+ * node (and by extension, the loop's `$loop-end` output). Mirrors the
+ * `iterationOutputSchema` declared in `agent-turn-flow.ts`.
+ */
+export interface AgentTurnIterationOutput {
+    readonly finishReason: 'stop' | 'length' | 'tool-use' | 'content-filter' | 'error';
+    readonly message: ModelMessage;
+    readonly iterationAppended: readonly ConversationMessage[];
+    readonly iterationUsage: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+        readonly costUsd: number;
+    };
+    readonly provider: {
+        readonly id: string;
+        readonly model: string;
+    };
+    readonly finishedTurn: boolean;
+    readonly nextMessages: readonly ModelMessage[];
+    /**
+     * Set by `dispatch-tools` when a tool invocation surfaces an
+     * `unresolved-tool` / `tool-invocation-failed`, or by
+     * `budget-check` when the cost cap is exceeded. `compose-result`
+     * inspects it and short-circuits the run into an error result.
+     */
+    readonly errorPayload?: {
+        readonly code: 'unresolved-tool' | 'tool-invocation-failed' | 'budget-exceeded' | 'agent-turn-aborted' | 'model-invocation-failed';
+        readonly message: string;
+        readonly extra?: Readonly<Record<string, unknown>>;
+    };
+}
+/**
+ * Public re-export helper for callers building test doubles. Kept in
+ * this module to avoid making `context.ts` a circular hub — everything
+ * a handler needs is imported through here.
+ */
+export type { Agent, HitlBindings, InvokeAgentBindings, InvokeAgentInput, TenantPolicy };
+//# sourceMappingURL=context.d.ts.map

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

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

package/dist/handlers/context.js

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

package/dist/handlers/context.js.map

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

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

@@ -0,0 +1,15 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Loop-body node #2. If the model returned `finishReason='tool-use'`
+ * with a non-empty tool-call list, persist the assistant tool-call
+ * message + dispatch every tool + persist every tool result. Update
+ * `nextMessages` so the next iteration's model call sees the tool
+ * outputs.
+ *
+ * When the model returned a terminal `finishReason` (or `tool-use`
+ * with no calls), pass through unchanged so
+ * `budget-check` marks the iteration finished.
+ */
+export declare function buildDispatchToolsHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=dispatch-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-tools.d.ts","sourceRoot":"","sources":["../../src/handlers/dispatch-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAWhE,OAAO,KAAK,EAA4B,WAAW,EAAE,MAAM,cAAc,CAAC;AAkE1E;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAySvE"}