@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

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

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

package/dist/handlers/errors.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Thrown by a node handler when a precondition fails or a runtime step
+ * short-circuits with a structured error. The kernel captures
+ * `Error.message` into `step.failed.payload.message`; we serialize the
+ * full structured error as JSON so `projectRunResult` can recover the
+ * discriminated union shape on the way out.
+ *
+ * Deliberately narrowed to `Error` subclass so `cause` becomes a plain
+ * property (JSON-round-trippable) instead of the native ErrorOptions
+ * behavior.
+ */
+export class AgentTurnFailure extends Error {
+    payload;
+    constructor(payload) {
+        super(serializeError(payload));
+        this.name = 'AgentTurnFailure';
+        this.payload = payload;
+    }
+}
+const FAILURE_SENTINEL = '__agent_turn_failure__';
+/**
+ * Encode an `InvokeAgentError` as a JSON string carried in an Error's
+ * message. The sentinel field lets `parseFailureMessage` distinguish
+ * our structured failures from other error messages that happen to be
+ * JSON-shaped.
+ *
+ * `cause` fields on inner errors are downgraded to their message form
+ * so the payload is JSON-safe.
+ */
+function serializeError(error) {
+    return JSON.stringify({
+        [FAILURE_SENTINEL]: true,
+        error: stripCauseFunctions(error),
+    }, (_key, value) => {
+        if (value instanceof Error) {
+            return { code: value.code, message: value.message };
+        }
+        return value;
+    });
+}
+function stripCauseFunctions(error) {
+    // JSON.stringify replacer above handles Error instances; nothing more
+    // to do here. A pass-through hook for error variants that embed
+    // callbacks.
+    return error;
+}
+/**
+ * Attempt to reconstruct a structured `InvokeAgentError` from a run's
+ * `failureMessage`. Returns `undefined` when the message is not one of
+ * ours (e.g. a raw kernel-level exception message).
+ */
+export function parseFailureMessage(raw) {
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    // Fast path: the raw message IS the single serialized failure (one
+    // step.failed for the whole turn, which is the common case).
+    const whole = tryParseChunk(raw);
+    if (whole !== undefined)
+        return whole;
+    // Fallback: the kernel joins multiple step.failed messages with '; '.
+    // Recover by extracting balanced-brace substrings and trying each.
+    for (const chunk of extractJsonCandidates(raw)) {
+        const parsed = tryParseChunk(chunk);
+        if (parsed !== undefined)
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * Extract substrings that look like well-formed JSON objects by
+ * scanning for balanced braces. Only single-level scan — inner strings
+ * are respected. Cheap parser used for the rare multi-failure case.
+ */
+function extractJsonCandidates(raw) {
+    const out = [];
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (ch === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (ch === '{') {
+            if (depth === 0)
+                start = i;
+            depth += 1;
+        }
+        else if (ch === '}') {
+            depth -= 1;
+            if (depth === 0 && start >= 0) {
+                out.push(raw.slice(start, i + 1));
+                start = -1;
+            }
+        }
+    }
+    return out;
+}
+function tryParseChunk(chunk) {
+    const trimmed = chunk.trim();
+    if (!trimmed.startsWith('{'))
+        return undefined;
+    try {
+        const doc = JSON.parse(trimmed);
+        if (typeof doc === 'object' &&
+            doc !== null &&
+            doc[FAILURE_SENTINEL] === true) {
+            return doc.error;
+        }
+    }
+    catch {
+        // Not our JSON — probably a raw JS Error.message. Fall through.
+    }
+    return undefined;
+}
+/** Helper for handlers to short-circuit with a structured error. */
+export function throwAgentTurnFailure(error) {
+    throw new AgentTurnFailure(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/handlers/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/handlers/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAsIjC;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,OAAO,CAAmB;IACnC,YAAY,OAAyB;QACnC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,gBAAgB,GAAG,wBAAiC,CAAC;AAO3D;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,KAAuB;IAC7C,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,CAAC,gBAAgB,CAAC,EAAE,IAAa;QACjC,KAAK,EAAE,mBAAmB,CAAC,KAAK,CAAC;KACN,EAC7B,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACd,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,OAAO,EAAE,IAAI,EAAG,KAA2B,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAC7E,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CACF,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAuB;IAClD,sEAAsE;IACtE,gEAAgE;IAChE,aAAa;IACb,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAuB;IACzD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5D,mEAAmE;IACnE,6DAA6D;IAC7D,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,sEAAsE;IACtE,mEAAmE;IACnE,KAAK,MAAM,KAAK,IAAI,qBAAqB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;IAC1C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,GAAW;IACxC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;IACf,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,GAAG,KAAK,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,OAAO,GAAG,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,QAAQ,GAAG,CAAC,QAAQ,CAAC;YACrB,SAAS;QACX,CAAC;QACD,IAAI,QAAQ;YAAE,SAAS;QACvB,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,IAAI,KAAK,KAAK,CAAC;gBAAE,KAAK,GAAG,CAAC,CAAC;YAC3B,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACtB,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC9B,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBAClC,KAAK,GAAG,CAAC,CAAC,CAAC;YACb,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgD,CAAC;QAC/E,IACE,OAAO,GAAG,KAAK,QAAQ;YACvB,GAAG,KAAK,IAAI;YACX,GAAyB,CAAC,gBAAgB,CAAC,KAAK,IAAI,EACrD,CAAC;YACD,OAAQ,GAAyB,CAAC,KAAK,CAAC;QAC1C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,qBAAqB,CAAC,KAAuB;IAC3D,MAAM,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/dist/handlers/evaluate-guardrails.d.ts

@@ -0,0 +1,14 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Guardrail gate on the turn's final response, before it is stored.
+ * Receives the agent loop's output. A failed guardrail whose action is
+ * `halt` throws, so the run fails and the response never reaches the
+ * conversation; failures with any other action are stashed on `ctx` for
+ * `compose-result` to surface in `AgentTurnResult.violations`. Every
+ * failure emits a `guardrail.violated` event. Also records the
+ * response's `model-output` provenance node, which the guardrail checks
+ * link to.
+ */
+export declare function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=evaluate-guardrails.d.ts.map

package/dist/handlers/evaluate-guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-guardrails.d.ts","sourceRoot":"","sources":["../../src/handlers/evaluate-guardrails.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAYnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA0H5E"}

package/dist/handlers/evaluate-guardrails.js

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { buildRunTrace, categorizeOutcomes, describeBlockingViolations, evaluateGate, } from '../guardrails-gate.js';
+import { emitTurnEvent } from '../streaming.js';
+import { throwAgentTurnFailure } from './errors.js';
+import { finalIteration } from './final-iteration.js';
+import { parseJsonAnswer } from './structured-output.js';
+/**
+ * Guardrail gate on the turn's final response, before it is stored.
+ * Receives the agent loop's output. A failed guardrail whose action is
+ * `halt` throws, so the run fails and the response never reaches the
+ * conversation; failures with any other action are stashed on `ctx` for
+ * `compose-result` to surface in `AgentTurnResult.violations`. Every
+ * failure emits a `guardrail.violated` event. Also records the
+ * response's `model-output` provenance node, which the guardrail checks
+ * link to.
+ */
+export function buildEvaluateGuardrailsHandler(ctx) {
+    return async (input, kctx) => {
+        if (ctx.guardrails === undefined) {
+            throwAgentTurnFailure({
+                code: 'model-invocation-failed',
+                message: 'evaluate-guardrails invoked before setup completed',
+                cause: null,
+            });
+        }
+        const final = finalIteration(input, 'evaluate-guardrails');
+        const evaluatedAt = new Date().toISOString();
+        // The response as it would be stored; not persisted yet.
+        const response = {
+            sequence: -1,
+            role: 'agent',
+            content: final.message.content ?? '',
+            createdAt: evaluatedAt,
+            actor: ctx.input.agent.id,
+        };
+        if (ctx.provenance !== undefined) {
+            ctx.provenance.addNode({
+                id: `model-output:${ctx.usage.steps}`,
+                kind: 'model-output',
+                timestamp: evaluatedAt,
+                modelVersion: `${final.provider.id}/${final.provider.model}`,
+            });
+            ctx.provenance.addEdge({
+                from: `model-output:${ctx.usage.steps}`,
+                to: `model-call:${ctx.usage.steps}`,
+                kind: 'produced',
+            });
+        }
+        const finalUsage = {
+            steps: ctx.usage.steps,
+            promptTokens: ctx.usage.promptTokens,
+            completionTokens: ctx.usage.completionTokens,
+            totalCostUsd: ctx.usage.totalCostUsd,
+            durationMs: Date.now() - ctx.startedAt,
+        };
+        const structured = ctx.input.agent.output !== undefined && !kctx.dryRun
+            ? parseJsonAnswer(final.message.content)
+            : undefined;
+        const trace = buildRunTrace({
+            runId: kctx.runId,
+            tenantId: ctx.input.tenantId,
+            projectId: ctx.input.projectId,
+            conversationId: ctx.input.conversationId,
+            turnNumber: (ctx.conversation?.turnCount ?? 0) + 1,
+            agent: ctx.input.agent,
+            userMessage: ctx.input.userMessage,
+            ...(ctx.input.input !== undefined && { stepInput: ctx.input.input }),
+            ...(structured?.kind === 'ok' && { structuredOutput: structured.value }),
+            appended: ctx.appended,
+            finalResponse: response,
+            usage: finalUsage,
+        });
+        const outcomes = await evaluateGate(ctx.guardrails, trace, ctx.bindings, ctx.tenantPolicy, ctx.turnAbort.signal);
+        const categorized = categorizeOutcomes(outcomes);
+        const allViolations = [...categorized.blocking, ...categorized.warnings, ...categorized.other];
+        for (const v of allViolations) {
+            await emitTurnEvent(ctx.bindings.onEvent, {
+                kind: 'guardrail.violated',
+                action: v.action,
+                severity: v.severity,
+                guardrailId: v.guardrailId,
+                ...(v.result.reason !== undefined && { reason: v.result.reason }),
+            });
+            if (ctx.provenance !== undefined) {
+                ctx.provenance.addNode({
+                    id: `guardrail-check:${v.guardrailId}`,
+                    kind: 'guardrail-check',
+                    timestamp: v.at,
+                    attributes: {
+                        guardrailId: v.guardrailId,
+                        action: v.action,
+                        severity: v.severity,
+                        passed: false,
+                        ...(v.result.reason !== undefined && { reason: v.result.reason }),
+                    },
+                });
+                ctx.provenance.addEdge({
+                    from: `guardrail-check:${v.guardrailId}`,
+                    to: `model-output:${ctx.usage.steps}`,
+                    kind: 'influenced-by',
+                });
+            }
+        }
+        if (categorized.blocking.length > 0) {
+            const message = describeBlockingViolations(categorized.blocking);
+            await emitTurnEvent(ctx.bindings.onEvent, {
+                kind: 'turn.failed',
+                conversationId: ctx.input.conversationId,
+                errorCode: 'guardrail-violation',
+                message,
+            });
+            throwAgentTurnFailure({
+                code: 'guardrail-violation',
+                message,
+                violations: categorized.blocking,
+                evaluationErrors: categorized.errors,
+            });
+        }
+        ctx.nonBlockingViolations = [...categorized.warnings, ...categorized.other];
+        return {
+            blocking: categorized.blocking.length,
+            warnings: categorized.warnings.length,
+            other: categorized.other.length,
+        };
+    };
+}
+//# sourceMappingURL=evaluate-guardrails.js.map

package/dist/handlers/evaluate-guardrails.js.map

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

package/dist/handlers/final-iteration.d.ts

@@ -0,0 +1,7 @@
+import type { AgentTurnIterationOutput } from './context.js';
+/**
+ * The agent loop's final iteration — the response the turn ends with.
+ * `nodeName` names the reading node in the failure message.
+ */
+export declare function finalIteration(loopOutput: unknown, nodeName: string): AgentTurnIterationOutput;
+//# sourceMappingURL=final-iteration.d.ts.map

package/dist/handlers/final-iteration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"final-iteration.d.ts","sourceRoot":"","sources":["../../src/handlers/final-iteration.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAG7D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,wBAAwB,CAiB9F"}

package/dist/handlers/final-iteration.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { throwAgentTurnFailure } from './errors.js';
+/**
+ * The agent loop's final iteration — the response the turn ends with.
+ * `nodeName` names the reading node in the failure message.
+ */
+export function finalIteration(loopOutput, nodeName) {
+    const output = loopOutput;
+    if (output === undefined) {
+        throwAgentTurnFailure({
+            code: 'model-invocation-failed',
+            message: `${nodeName} received undefined loop output`,
+            cause: null,
+        });
+    }
+    if (output.finalOutput === undefined) {
+        throwAgentTurnFailure({
+            code: 'model-invocation-failed',
+            message: `${nodeName} received loop output without finalOutput`,
+            cause: null,
+        });
+    }
+    return output.finalOutput;
+}
+//# sourceMappingURL=final-iteration.js.map

package/dist/handlers/final-iteration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"final-iteration.js","sourceRoot":"","sources":["../../src/handlers/final-iteration.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAKjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,UAAmB,EAAE,QAAgB;IAClE,MAAM,MAAM,GAAG,UAAkE,CAAC;IAClF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,qBAAqB,CAAC;YACpB,IAAI,EAAE,yBAAyB;YAC/B,OAAO,EAAE,GAAG,QAAQ,iCAAiC;YACrD,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;IACL,CAAC;IACD,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACrC,qBAAqB,CAAC;YACpB,IAAI,EAAE,yBAAyB;YAC/B,OAAO,EAAE,GAAG,QAAQ,2CAA2C;YAC/D,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CAAC;AAC5B,CAAC"}

package/dist/handlers/index.d.ts

@@ -0,0 +1,5 @@
+import type { HandlerRegistry } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+export declare function buildHandlers(ctx: TurnContext): HandlerRegistry;
+export type { TurnContext };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,iBAAiB,CAAC;AAsBpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAahD,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,eAAe,CAsB/D;AAED,YAAY,EAAE,WAAW,EAAE,CAAC"}

package/dist/handlers/index.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { AGENT_LOOP_NODE, BUDGET_CHECK_NODE, BUILD_INITIAL_MESSAGES_NODE, COMPOSE_RESULT_NODE, DISPATCH_TOOLS_NODE, EVALUATE_GUARDRAILS_NODE, MODEL_CALL_NODE, PERSIST_FINAL_MESSAGE_NODE, PERSIST_PROVENANCE_NODE, PERSIST_USER_MESSAGE_NODE, RENDER_PROMPT_NODE, RUN_RETRIEVALS_NODE, SETUP_NODE, } from '../agent-turn-flow.js';
+import { buildBudgetCheckHandler } from './budget-check.js';
+import { buildBuildInitialMessagesHandler } from './build-initial-messages.js';
+import { buildComposeResultHandler } from './compose-result.js';
+import { buildDispatchToolsHandler } from './dispatch-tools.js';
+import { buildEvaluateGuardrailsHandler } from './evaluate-guardrails.js';
+import { buildModelCallHandler } from './model-call.js';
+import { buildPersistFinalMessageHandler } from './persist-final-message.js';
+import { buildPersistProvenanceHandler } from './persist-provenance.js';
+import { buildPersistUserMessageHandler } from './persist-user-message.js';
+import { buildRenderPromptHandler } from './render-prompt.js';
+import { buildRunRetrievalsHandler } from './run-retrievals.js';
+import { buildSetupHandler } from './setup.js';
+// `agent-loop` is a kernel loop node — the executor dispatches it
+// internally; only body-node handlers are registered.
+export function buildHandlers(ctx) {
+    const entries = [
+        [SETUP_NODE, buildSetupHandler(ctx)],
+        [RENDER_PROMPT_NODE, buildRenderPromptHandler(ctx)],
+        [PERSIST_USER_MESSAGE_NODE, buildPersistUserMessageHandler(ctx)],
+        [RUN_RETRIEVALS_NODE, buildRunRetrievalsHandler(ctx)],
+        [BUILD_INITIAL_MESSAGES_NODE, buildBuildInitialMessagesHandler(ctx)],
+        [MODEL_CALL_NODE, buildModelCallHandler(ctx)],
+        [DISPATCH_TOOLS_NODE, buildDispatchToolsHandler(ctx)],
+        [BUDGET_CHECK_NODE, buildBudgetCheckHandler(ctx)],
+        [PERSIST_FINAL_MESSAGE_NODE, buildPersistFinalMessageHandler(ctx)],
+        [EVALUATE_GUARDRAILS_NODE, buildEvaluateGuardrailsHandler(ctx)],
+        [PERSIST_PROVENANCE_NODE, buildPersistProvenanceHandler(ctx)],
+        [COMPOSE_RESULT_NODE, buildComposeResultHandler(ctx)],
+    ];
+    // Assert `agent-loop` isn't accidentally registered — the runtime's
+    // flow executor rejects handlers for internal-dispatch nodes at load
+    // time. Sanity check for regressions.
+    if (entries.some(([id]) => id === AGENT_LOOP_NODE)) {
+        throw new Error('agent-loop must not have a handler — it is dispatched by the kernel');
+    }
+    return new Map(entries);
+}
+//# sourceMappingURL=index.js.map

package/dist/handlers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAKjC,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,2BAA2B,EAC3B,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,0BAA0B,EAC1B,uBAAuB,EACvB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,GACX,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,gCAAgC,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,kEAAkE;AAClE,sDAAsD;AACtD,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,MAAM,OAAO,GAA4B;QACvC,CAAC,UAAoB,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;QAC9C,CAAC,kBAA4B,EAAE,wBAAwB,CAAC,GAAG,CAAC,CAAC;QAC7D,CAAC,yBAAmC,EAAE,8BAA8B,CAAC,GAAG,CAAC,CAAC;QAC1E,CAAC,mBAA6B,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC;QAC/D,CAAC,2BAAqC,EAAE,gCAAgC,CAAC,GAAG,CAAC,CAAC;QAC9E,CAAC,eAAyB,EAAE,qBAAqB,CAAC,GAAG,CAAC,CAAC;QACvD,CAAC,mBAA6B,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC;QAC/D,CAAC,iBAA2B,EAAE,uBAAuB,CAAC,GAAG,CAAC,CAAC;QAC3D,CAAC,0BAAoC,EAAE,+BAA+B,CAAC,GAAG,CAAC,CAAC;QAC5E,CAAC,wBAAkC,EAAE,8BAA8B,CAAC,GAAG,CAAC,CAAC;QACzE,CAAC,uBAAiC,EAAE,6BAA6B,CAAC,GAAG,CAAC,CAAC;QACvE,CAAC,mBAA6B,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC;KAChE,CAAC;IACF,oEAAoE;IACpE,qEAAqE;IACrE,sCAAsC;IACtC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,KAAM,eAA0B,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC"}

package/dist/handlers/model-call.d.ts

@@ -0,0 +1,13 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Loop-body node #1. Invoke the model with the current
+ * `nextMessages` accumulator. Emits `model.call.started` +
+ * `model.call.completed`, records provenance for the model-call node,
+ * and accumulates usage on `ctx.usage`.
+ *
+ * Output is a partial `AgentTurnIterationOutput` — `dispatch-tools`
+ * receives it and finishes composing the iteration output.
+ */
+export declare function buildModelCallHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=model-call.d.ts.map

package/dist/handlers/model-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-call.d.ts","sourceRoot":"","sources":["../../src/handlers/model-call.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,OAAO,KAAK,EAA4B,WAAW,EAAE,MAAM,cAAc,CAAC;AAG1E;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAwHnE"}

package/dist/handlers/model-call.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { emitTurnEvent } from '../streaming.js';
+import { throwAgentTurnFailure } from './errors.js';
+/**
+ * Loop-body node #1. Invoke the model with the current
+ * `nextMessages` accumulator. Emits `model.call.started` +
+ * `model.call.completed`, records provenance for the model-call node,
+ * and accumulates usage on `ctx.usage`.
+ *
+ * Output is a partial `AgentTurnIterationOutput` — `dispatch-tools`
+ * receives it and finishes composing the iteration output.
+ */
+export function buildModelCallHandler(ctx) {
+    return async (input, kctx) => {
+        if (ctx.provider === undefined || ctx.model === undefined || ctx.tools === undefined) {
+            throwAgentTurnFailure({
+                code: 'model-invocation-failed',
+                message: 'model-call invoked before setup completed',
+                cause: null,
+            });
+        }
+        const shaped = input;
+        const nextMessages = shaped?.nextMessages ?? [];
+        ctx.usage.steps += 1;
+        await emitTurnEvent(ctx.bindings.onEvent, {
+            kind: 'model.call.started',
+            step: ctx.usage.steps,
+            providerId: ctx.provider.metadata.id,
+            model: ctx.model.name,
+        });
+        let callResult;
+        if (kctx.dryRun) {
+            // Dry-run: skip the network call. Return a schema-conformant
+            // mock indicating the model would have terminated cleanly. The
+            // mock requests no tools, so a dry run does not preview tool
+            // planning.
+            callResult = {
+                finishReason: 'stop',
+                message: { role: 'assistant', content: '[dry-run: model call skipped]' },
+                usage: { promptTokens: 0, completionTokens: 0 },
+                costUsd: 0,
+                durationMs: 0,
+                provider: { id: ctx.provider.metadata.id, model: ctx.model.name },
+            };
+        }
+        else {
+            const callInput = {
+                model: ctx.model.name,
+                messages: nextMessages,
+                ...(ctx.tools.definitions.length > 0 && {
+                    tools: ctx.tools.definitions,
+                }),
+                abortSignal: ctx.turnAbort.signal,
+            };
+            try {
+                callResult = await ctx.provider.invoke(callInput);
+            }
+            catch (cause) {
+                if (ctx.turnAbort.signal.aborted) {
+                    throwAgentTurnFailure({
+                        code: 'agent-turn-aborted',
+                        message: `Agent turn aborted: ${cause instanceof Error ? cause.message : String(cause)}`,
+                        reason: ctx.abortReason ?? 'timeout',
+                    });
+                }
+                // The provider's own words (a 401's "invalid x-api-key", a 429)
+                // are what the caller needs; they're in `cause` too, but callers
+                // show `message`.
+                throwAgentTurnFailure({
+                    code: 'model-invocation-failed',
+                    message: `Model call to ${ctx.provider.metadata.id} (${ctx.model.name}) failed: ${describeCause(cause)}`,
+                    cause,
+                });
+            }
+        }
+        ctx.usage.promptTokens += callResult.usage.promptTokens;
+        ctx.usage.completionTokens += callResult.usage.completionTokens;
+        ctx.usage.totalCostUsd += callResult.costUsd;
+        ctx.lastProvider = callResult.provider;
+        await emitTurnEvent(ctx.bindings.onEvent, {
+            kind: 'model.call.completed',
+            step: ctx.usage.steps,
+            finishReason: callResult.finishReason,
+            promptTokens: callResult.usage.promptTokens,
+            completionTokens: callResult.usage.completionTokens,
+            costUsd: callResult.costUsd,
+            durationMs: callResult.durationMs,
+        });
+        if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
+            const modelCallNodeId = `model-call:${ctx.usage.steps}`;
+            ctx.provenance.addNode({
+                id: modelCallNodeId,
+                kind: 'model-call',
+                timestamp: new Date().toISOString(),
+                modelVersion: `${callResult.provider.id}/${callResult.provider.model}`,
+                attributes: {
+                    step: ctx.usage.steps,
+                    promptTokens: callResult.usage.promptTokens,
+                    completionTokens: callResult.usage.completionTokens,
+                    costUsd: callResult.costUsd,
+                    finishReason: callResult.finishReason,
+                },
+            });
+            ctx.provenance.addEdge({
+                from: modelCallNodeId,
+                to: `input:${ctx.userMessage.sequence}`,
+                kind: 'caused-by',
+            });
+        }
+        // Partial iteration output — `dispatch-tools` finishes it.
+        const partial = {
+            step: ctx.usage.steps,
+            finishReason: callResult.finishReason,
+            message: callResult.message,
+            iterationUsage: {
+                promptTokens: callResult.usage.promptTokens,
+                completionTokens: callResult.usage.completionTokens,
+                costUsd: callResult.costUsd,
+            },
+            provider: callResult.provider,
+            nextMessages,
+        };
+        return partial;
+    };
+}
+/** Longest cause text a failure message carries. */
+const MAX_CAUSE_CHARS = 500;
+/** A thrown value's message on one line, at most `MAX_CAUSE_CHARS` long. */
+function describeCause(cause) {
+    const text = (cause instanceof Error ? cause.message : String(cause)).replace(/\s+/g, ' ').trim();
+    if (text.length === 0)
+        return cause instanceof Error ? cause.name : 'no detail';
+    return text.length > MAX_CAUSE_CHARS ? `${text.slice(0, MAX_CAUSE_CHARS - 1)}…` : text;
+}
+//# sourceMappingURL=model-call.js.map

package/dist/handlers/model-call.js.map

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

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

@@ -0,0 +1,14 @@
+import type { NodeHandler } from '@kindgi/handler';
+import type { TurnContext } from './context.js';
+/**
+ * Persist the turn's terminal assistant message (non-intermediate —
+ * increments `turnCount`). Runs after `evaluate-guardrails`, so only a
+ * response that no `halt` guardrail rejected is stored. Reads the
+ * response from the agent loop's output.
+ *
+ * Dry-run branch: skips the DB write; builds a synthetic
+ * `ConversationMessage` with `sequence: -1`. `turnCount` is NOT
+ * incremented (no persistence happened).
+ */
+export declare function buildPersistFinalMessageHandler(ctx: TurnContext): NodeHandler;
+//# sourceMappingURL=persist-final-message.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persist-final-message.d.ts","sourceRoot":"","sources":["../../src/handlers/persist-final-message.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAOnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhD;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CA0C7E"}

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

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { AGENT_LOOP_NODE } from '../agent-turn-flow.js';
+import { emitTurnEvent } from '../streaming.js';
+import { throwAgentTurnFailure } from './errors.js';
+import { finalIteration } from './final-iteration.js';
+/**
+ * Persist the turn's terminal assistant message (non-intermediate —
+ * increments `turnCount`). Runs after `evaluate-guardrails`, so only a
+ * response that no `halt` guardrail rejected is stored. Reads the
+ * response from the agent loop's output.
+ *
+ * Dry-run branch: skips the DB write; builds a synthetic
+ * `ConversationMessage` with `sequence: -1`. `turnCount` is NOT
+ * incremented (no persistence happened).
+ */
+export function buildPersistFinalMessageHandler(ctx) {
+    return async (_input, kctx) => {
+        const final = finalIteration(kctx.nodeOutputs.get(AGENT_LOOP_NODE), 'persist-final-message');
+        const assistantMsg = final.message;
+        let finalMessage;
+        if (kctx.dryRun) {
+            finalMessage = {
+                sequence: -1,
+                role: 'agent',
+                content: assistantMsg.content ?? '',
+                createdAt: new Date().toISOString(),
+                actor: ctx.input.agent.id,
+            };
+        }
+        else {
+            const persist = await ctx.bindings.conversationBinding.appendMessage({
+                tenantId: ctx.input.tenantId,
+                conversationId: ctx.input.conversationId,
+                role: 'agent',
+                content: assistantMsg.content ?? '',
+                actor: ctx.input.agent.id,
+            });
+            if (persist.kind === 'err')
+                throwAgentTurnFailure(persist.error);
+            finalMessage = persist.value;
+        }
+        ctx.appended.push(finalMessage);
+        ctx.finalMessage = finalMessage;
+        await emitTurnEvent(ctx.bindings.onEvent, {
+            kind: 'agent.message',
+            step: ctx.usage.steps,
+            isFinal: true,
+            message: finalMessage,
+        });
+        return { sequence: finalMessage.sequence };
+    };
+}
+//# sourceMappingURL=persist-final-message.js.map