@kindgi/agents 0.0.0-bootstrap.0 → 0.1.1

package/src/guardrails-gate.ts

@@ -0,0 +1,342 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ProviderRegistry, TenantPolicy } from '@kindgi/capabilities';
+import type { ComplianceProvider } from '@kindgi/compliance';
+import {
+  type CheckRegistry,
+  type EvaluationBindings,
+  type EvaluationOutcome,
+  type EvaluationResult,
+  type Guardrail,
+  type ModelCallRecord,
+  type RunTrace,
+  type ToolCallRecord,
+  type ToolResultRecord,
+  evaluateAll,
+} from '@kindgi/guardrails';
+import type { AgentId, GuardrailId, ProjectId, Result, RunId, TenantId } from '@kindgi/types';
+
+import type { Agent, ConversationId, ConversationMessage } from './types.js';
+
+/**
+ * Turn usage snapshot passed into `buildRunTrace`. Local mirror of
+ * `AgentTurnUsage` (handlers/result-shape.ts) — kept here to avoid a
+ * circular import.
+ */
+interface TurnUsageSnapshot {
+  readonly steps: number;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly totalCostUsd: number;
+  readonly durationMs: number;
+}
+
+/**
+ * Bindings the guardrail gate consumes. All optional — if `guardrails`
+ * is empty or `checks` is undefined, `evaluateGate` is a no-op. An
+ * agent that references a guardrail id missing from `guardrails` fails
+ * its turn with `unresolved-guardrail`.
+ */
+export interface GuardrailsBindings {
+  /** Full guardrail definitions available for this run. Indexed by id. */
+  readonly guardrails?: readonly Guardrail[];
+  /** Check registry with built-ins + any adapter-registered custom checks. */
+  readonly checks?: CheckRegistry;
+  /** Optional compliance sink — every failed check emits an evidence record. */
+  readonly compliance?: ComplianceProvider;
+  /**
+   * Provider registry for llm-judge guardrails; the judge model is
+   * routed through it under the turn's tenant policy. If absent,
+   * llm-judge guardrails error with `judge-missing`; if no provider
+   * satisfies the judge's capability, with `judge-routing-failed`.
+   */
+  readonly providerRegistry?: ProviderRegistry;
+}
+
+/**
+ * Materialize a `RunTrace` from an agent turn's captured state. The
+ * guardrail engine reads only the trace — it doesn't touch memory,
+ * kernel journal, or provenance directly (keeps checks pure and
+ * dependency-free).
+ */
+export function buildRunTrace(input: {
+  /** The kernel run of the turn. */
+  readonly runId: RunId;
+  readonly tenantId: TenantId;
+  /** Lets the engine record compliance evidence for a failed check. */
+  readonly projectId: ProjectId;
+  readonly conversationId: ConversationId;
+  /** 1-based number of this turn in the conversation. */
+  readonly turnNumber: number;
+  readonly agent: Agent;
+  /** The user message that started the turn. */
+  readonly userMessage: string;
+  /** The turn's structured input (`InvokeAgentInput.input`), when it has one. */
+  readonly stepInput?: unknown;
+  /** The parsed answer, when the agent declares `output`. */
+  readonly structuredOutput?: unknown;
+  readonly appended: readonly ConversationMessage[];
+  readonly finalResponse: ConversationMessage;
+  readonly usage: TurnUsageSnapshot;
+}): RunTrace {
+  const toolCalls: ToolCallRecord[] = [];
+  const toolResults: ToolResultRecord[] = [];
+  const modelCalls: ModelCallRecord[] = [];
+
+  for (const msg of input.appended) {
+    if (msg.role === 'agent' && typeof msg.content === 'object' && msg.content !== null) {
+      const structured = msg.content as {
+        readonly toolCalls?: readonly {
+          readonly id: string;
+          readonly name: string;
+          readonly arguments: Readonly<Record<string, unknown>>;
+        }[];
+      };
+      if (structured.toolCalls !== undefined) {
+        for (const call of structured.toolCalls) {
+          toolCalls.push({
+            toolId: call.name as never,
+            toolName: call.name,
+            arguments: call.arguments,
+            at: msg.createdAt,
+          });
+        }
+      }
+    }
+    if (msg.role === 'tool' && msg.toolCall !== undefined) {
+      toolResults.push({
+        toolCallId: msg.toolCall.invocationId,
+        output: msg.content,
+        at: msg.createdAt,
+      });
+    }
+  }
+
+  // Approximate a model-call record for cost/latency guardrails — a
+  // more granular per-call breakdown would need an observability
+  // hook.
+  modelCalls.push({
+    providerId: 'runtime.picked',
+    model: 'runtime.picked',
+    promptTokens: input.usage.promptTokens,
+    completionTokens: input.usage.completionTokens,
+    at: input.finalResponse.createdAt,
+  });
+
+  const output =
+    typeof input.finalResponse.content === 'string'
+      ? input.finalResponse.content
+      : JSON.stringify(input.finalResponse.content);
+
+  return {
+    runId: input.runId,
+    tenantId: input.tenantId,
+    projectId: input.projectId,
+    agentId: input.agent.id as unknown as AgentId,
+    output,
+    toolCalls,
+    toolResults,
+    modelCalls,
+    mode: 'runtime',
+    userInput: input.userMessage,
+    conversationId: input.conversationId as unknown as string,
+    turnNumber: input.turnNumber,
+    totalCostUsd: input.usage.totalCostUsd,
+    durationMs: input.usage.durationMs,
+    attributes: {
+      steps: input.usage.steps,
+      ...(input.stepInput !== undefined && { stepInput: input.stepInput }),
+      ...(input.structuredOutput !== undefined && { structuredOutput: input.structuredOutput }),
+    },
+  };
+}
+
+/**
+ * Filter the bound guardrail list to those referenced by the agent's
+ * `guardrails: string[]` declaration. Missing references are collected
+ * into `missing` — the caller decides whether that's fatal.
+ */
+export function resolveGuardrails(
+  agent: Agent,
+  bindings: GuardrailsBindings,
+): { readonly resolved: readonly Guardrail[]; readonly missing: readonly string[] } {
+  const available = new Map<string, Guardrail>();
+  for (const inv of bindings.guardrails ?? []) available.set(inv.id, inv);
+  const resolved: Guardrail[] = [];
+  const missing: string[] = [];
+  for (const id of agent.guardrails) {
+    const inv = available.get(id);
+    if (inv !== undefined) resolved.push(inv);
+    else missing.push(id);
+  }
+  return { resolved, missing };
+}
+
+/**
+ * Evaluate every resolved guardrail against the turn's trace. Returns
+ * the raw outcomes so the caller can decide how to react — the gate
+ * doesn't halt on its own. `tenantPolicy` (the policy the turn was
+ * routed under) also governs which models llm-judge guardrails may use;
+ * `abortSignal` (the turn's) reaches every check, so a slow judge or
+ * pack check stops when the turn does.
+ */
+export async function evaluateGate(
+  guardrails: readonly Guardrail[],
+  trace: RunTrace,
+  bindings: GuardrailsBindings,
+  tenantPolicy?: TenantPolicy,
+  abortSignal?: AbortSignal,
+): Promise<readonly EvaluationOutcome[]> {
+  if (guardrails.length === 0 || bindings.checks === undefined) return [];
+  const evalBindings: EvaluationBindings = {
+    ...(bindings.providerRegistry !== undefined && { providerRegistry: bindings.providerRegistry }),
+    ...(bindings.compliance !== undefined && { compliance: bindings.compliance }),
+    ...(tenantPolicy !== undefined && { tenantPolicy }),
+    ...(abortSignal !== undefined && { abortSignal }),
+  };
+  return await evaluateAll(guardrails, bindings.checks, trace, evalBindings);
+}
+
+/**
+ * Sort evaluation outcomes by the failed guardrail's action. `halt` is
+ * blocking — the turn fails with `guardrail-violation`. `log-only` and
+ * `noop` are warnings; every other action (`retry`, `escalate`,
+ * `compensate`, or a custom action — actions are open strings) lands in
+ * `other`. Warnings and `other` are attached to the successful turn
+ * result under `result.violations`; the turn does not carry out those
+ * actions. Evaluation errors (a check that could not run) are collected
+ * in `errors`.
+ */
+export function categorizeOutcomes(outcomes: readonly EvaluationOutcome[]): {
+  readonly blocking: readonly EvaluationResult[];
+  readonly warnings: readonly EvaluationResult[];
+  readonly other: readonly EvaluationResult[];
+  readonly errors: readonly { readonly guardrailId: string; readonly message: string }[];
+} {
+  const blocking: EvaluationResult[] = [];
+  const warnings: EvaluationResult[] = [];
+  const other: EvaluationResult[] = [];
+  const errors: { guardrailId: string; message: string }[] = [];
+  for (const outcome of outcomes) {
+    if (outcome.kind === 'err') {
+      errors.push({
+        guardrailId:
+          'guardrailId' in outcome.error && typeof outcome.error.guardrailId === 'string'
+            ? outcome.error.guardrailId
+            : '<unknown>',
+        message: outcome.error.message,
+      });
+      continue;
+    }
+    if (outcome.kind === 'skip') continue;
+    const evalResult = outcome.value;
+    if (evalResult.result.passed) continue;
+    if (evalResult.action === 'halt') blocking.push(evalResult);
+    else if (evalResult.action === 'log-only' || evalResult.action === 'noop') {
+      warnings.push(evalResult);
+    } else other.push(evalResult);
+  }
+  return { blocking, warnings, other, errors };
+}
+
+/**
+ * Message for a turn stopped by blocking violations — names each
+ * guardrail that fired, with its check's reason when it gave one:
+ *
+ *   Turn blocked by guardrail 'no-pii': Response contains an email address
+ *   Turn blocked by 2 guardrails: 'no-pii' (Response contains …); 'max-length'
+ */
+export function describeBlockingViolations(blocking: readonly EvaluationResult[]): string {
+  const reasonOf = (v: EvaluationResult): string | undefined => {
+    const reason = v.result.reason?.trim();
+    return reason === undefined || reason === '' ? undefined : reason;
+  };
+  const [only] = blocking;
+  if (blocking.length === 1 && only !== undefined) {
+    const reason = reasonOf(only);
+    return `Turn blocked by guardrail '${only.guardrailId}'${reason !== undefined ? `: ${reason}` : ''}`;
+  }
+  const named = blocking.map((v) => {
+    const reason = reasonOf(v);
+    return `'${v.guardrailId}'${reason !== undefined ? ` (${reason})` : ''}`;
+  });
+  return `Turn blocked by ${blocking.length} guardrails: ${named.join('; ')}`;
+}
+
+/**
+ * Result of a session-gate check performed BEFORE running a turn:
+ * the HITL turn threshold (`conversationPolicy.hitl.afterTurns` or
+ * `conversationPolicy.hitlAfterTurns`).
+ */
+export type SessionGateResult =
+  | { readonly kind: 'ok' }
+  | { readonly kind: 'hitl-required'; readonly reason: string; readonly threshold: number };
+
+/**
+ * Evaluate session-level gates against the conversation state before
+ * running the next turn: the HITL threshold from
+ * `conversationPolicy.hitl.afterTurns` or `conversationPolicy.hitlAfterTurns`.
+ *
+ * Overloaded call shapes:
+ *   - `evaluateSessionGate(agent, turnCount)` — reads the agent's policy
+ *     directly.
+ *   - `evaluateSessionGate({ afterTurns? }, turnCount)` — reads a
+ *     pre-resolved effective policy (the setup handler passes
+ *     `resolveEffectiveHitlPolicy` output).
+ */
+export function evaluateSessionGate(
+  input: Agent | { readonly afterTurns?: number },
+  currentTurnCount: number,
+): SessionGateResult {
+  const asAgent = input as Agent;
+  const asPolicy = input as { readonly afterTurns?: number };
+  const threshold: number | undefined =
+    'conversationPolicy' in asAgent
+      ? (asAgent.conversationPolicy?.hitl?.afterTurns ?? asAgent.conversationPolicy?.hitlAfterTurns)
+      : asPolicy.afterTurns;
+  if (threshold !== undefined && currentTurnCount >= threshold) {
+    return {
+      kind: 'hitl-required',
+      reason: `Conversation reached HITL threshold: ${currentTurnCount} turns >= ${threshold}`,
+      threshold,
+    };
+  }
+  return { kind: 'ok' };
+}
+
+/** Discriminated error emitted when blocking guardrails fail. */
+export interface GuardrailViolationError {
+  readonly code: 'guardrail-violation';
+  readonly message: string;
+  readonly violations: readonly EvaluationResult[];
+  /** Errors from checks that couldn't even evaluate (missing check, bad config). */
+  readonly evaluationErrors: readonly { readonly guardrailId: string; readonly message: string }[];
+}
+
+/**
+ * Error shape for a turn blocked by the session HITL threshold.
+ * `approvalId` is set when the caller supplied a `bindings.hitl` sink and
+ * the enqueue succeeded — downstream code can poll or subscribe on that
+ * id. The agent turn itself does not return this code: it parks on a
+ * HITL waitpoint instead (`AgentTurnResult.status: 'suspended'`).
+ */
+export interface HitlRequiredError {
+  readonly code: 'hitl-required';
+  readonly message: string;
+  readonly threshold: number;
+  readonly approvalId?: string;
+}
+
+/** Emitted when the agent references guardrail IDs not in the registry. */
+export interface UnresolvedGuardrailError {
+  readonly code: 'unresolved-guardrail';
+  readonly message: string;
+  readonly guardrailIds: readonly string[];
+}
+
+// Silence unused-type lint (GuardrailId is used by callers via type inference).
+void 0 as unknown as GuardrailId;
+
+// Discriminated Result helper to keep call sites tidy.
+export type GateResult<T, E> = Result<T, E>;

package/src/handlers/budget-check.ts

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ModelMessage } from '@kindgi/capabilities';
+import type { NodeHandler } from '@kindgi/handler';
+
+import type { AgentOutputSpec } from '../types.js';
+import { DEFAULT_MAX_STEPS } from './constants.js';
+import type { AgentTurnIterationOutput, TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+import {
+  DEFAULT_MAX_REPAIRS,
+  type OutputChecker,
+  outputChecker,
+  repairMessage,
+  repairsSoFar,
+} from './structured-output.js';
+
+/**
+ * Loop-body node #3. The final gate before `$loop-end`. Decides
+ * whether the iteration finalizes the turn based on:
+ *
+ *   - The model's `finishReason` (anything other than `tool-use` with
+ *     calls terminates).
+ *   - `agent.budget.maxSteps` — enforced against `ctx.usage.steps`.
+ *   - `agent.budget.maxCostUsd` — enforced against cumulative cost.
+ *   - Cooperative abort from `ctx.turnAbort`.
+ *   - `agent.output` — a final answer that isn't JSON matching the
+ *     schema keeps the turn going with a repair message, while repairs
+ *     (and steps) are left; after that the turn fails with
+ *     `output-schema-violation`. Skipped on a dry run.
+ *
+ * Returns the fully-shaped `AgentTurnIterationOutput` — this is the
+ * iteration's `$loop-end` output that the loop node's `outputSchema`
+ * validates against.
+ */
+export function buildBudgetCheckHandler(ctx: TurnContext): NodeHandler {
+  let checker: OutputChecker | undefined;
+  return async (input: unknown, kctx) => {
+    if (ctx.turnAbort.signal.aborted) {
+      throwAgentTurnFailure({
+        code: 'agent-turn-aborted',
+        message: 'Agent turn aborted before budget-check',
+        reason: ctx.abortReason ?? 'timeout',
+      });
+    }
+
+    const partial = input as {
+      readonly step: number;
+      readonly finishReason: AgentTurnIterationOutput['finishReason'];
+      readonly message: ModelMessage;
+      readonly iterationAppended: readonly AgentTurnIterationOutput['iterationAppended'][number][];
+      readonly iterationUsage: AgentTurnIterationOutput['iterationUsage'];
+      readonly provider: AgentTurnIterationOutput['provider'];
+      readonly nextMessages: readonly ModelMessage[];
+      readonly hasToolCalls: boolean;
+    };
+
+    const maxSteps = ctx.input.agent.budget?.maxSteps ?? DEFAULT_MAX_STEPS;
+    const maxCostUsd = ctx.input.agent.budget?.maxCostUsd;
+
+    // Cost cap is a hard failure — the caller sees `budget-exceeded`
+    // before the turn tries another iteration.
+    if (maxCostUsd !== undefined && ctx.usage.totalCostUsd > maxCostUsd) {
+      throwAgentTurnFailure({
+        code: 'budget-exceeded',
+        message: `Agent turn cost budget exceeded (limit ${maxCostUsd}, observed ${ctx.usage.totalCostUsd})`,
+        kind: 'cost',
+        limit: maxCostUsd,
+        observed: ctx.usage.totalCostUsd,
+      });
+    }
+
+    // Step cap — if the model still wants another tool call but we've
+    // used the allotted steps, fail the run.
+    if (partial.hasToolCalls && ctx.usage.steps >= maxSteps) {
+      throwAgentTurnFailure({
+        code: 'budget-exceeded',
+        message: `Agent turn steps budget exceeded (limit ${maxSteps}, observed ${ctx.usage.steps})`,
+        kind: 'steps',
+        limit: maxSteps,
+        observed: ctx.usage.steps,
+      });
+    }
+
+    // `finishedTurn` semantics: true when the model's finishReason is
+    // terminal (i.e. not a live tool-use) — the current iteration's
+    // assistant message is the final answer.
+    let finishedTurn = !partial.hasToolCalls;
+    let nextMessages = partial.nextMessages;
+
+    const spec = ctx.input.agent.output;
+    if (finishedTurn && spec !== undefined && !kctx.dryRun) {
+      checker ??= outputChecker(spec);
+      const repair = outputRepair(spec, checker, partial.message, partial.nextMessages, {
+        stepsLeft: ctx.usage.steps < maxSteps,
+      });
+      if (repair !== undefined) {
+        finishedTurn = false;
+        nextMessages = repair;
+      }
+    }
+
+    const output: AgentTurnIterationOutput = {
+      finishReason: partial.finishReason,
+      message: partial.message,
+      iterationAppended: partial.iterationAppended,
+      iterationUsage: partial.iterationUsage,
+      provider: partial.provider,
+      finishedTurn,
+      nextMessages,
+    };
+    return output;
+  };
+}
+
+/**
+ * Check a final answer against the agent's output schema. A valid
+ * answer returns `undefined` (the turn finishes). An invalid one with
+ * repairs and steps left returns the next model call's messages: the
+ * answer, then a repair message listing what's wrong. Otherwise the
+ * turn fails with `output-schema-violation`.
+ */
+function outputRepair(
+  spec: AgentOutputSpec,
+  checker: OutputChecker,
+  answer: ModelMessage,
+  sent: readonly ModelMessage[],
+  budget: { readonly stepsLeft: boolean },
+): readonly ModelMessage[] | undefined {
+  const checked = checker.check(answer.content);
+  if (checked.kind === 'ok') return undefined;
+  const repairs = repairsSoFar(sent);
+  if (repairs < (spec.maxRepairs ?? DEFAULT_MAX_REPAIRS) && budget.stepsLeft) {
+    return [...sent, answer, repairMessage(spec, checked.errors)];
+  }
+  throwAgentTurnFailure({
+    code: 'output-schema-violation',
+    message: `The agent's answer does not match its ${spec.name ?? 'output'} schema after ${repairs} repair${repairs === 1 ? '' : 's'}: ${checked.errors.join('; ')}`,
+    errors: checked.errors,
+    attempts: repairs + 1,
+  });
+}

package/src/handlers/build-initial-messages.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ModelMessage, ModelToolCall } from '@kindgi/capabilities';
+import type { NodeHandler } from '@kindgi/handler';
+
+import { formatRetrievedForPrompt } from '../retrieval.js';
+import type { ConversationMessage } from '../types.js';
+
+import type { TurnContext } from './context.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: TurnContext): NodeHandler {
+  return async (input: unknown) => {
+    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: ModelMessage | undefined =
+      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: ModelMessage[] = [
+      { role: 'system', content: rendered },
+      ...(contextMessage !== undefined ? [contextMessage] : []),
+      ...history.map(conversationToModelMessage),
+      { role: 'user', content: ctx.input.userMessage },
+    ];
+
+    return { nextMessages: modelMessages };
+  };
+}
+
+function conversationToModelMessage(msg: ConversationMessage): ModelMessage {
+  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 as {
+      readonly text?: string;
+      readonly toolCalls?: readonly ModelToolCall[];
+    };
+    return {
+      role: 'assistant',
+      content: structured.text ?? '',
+      ...(structured.toolCalls !== undefined && { toolCalls: structured.toolCalls }),
+    };
+  }
+  const role: ModelMessage['role'] = msg.role === 'agent' ? 'assistant' : msg.role;
+  return {
+    role,
+    content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+  };
+}

package/src/handlers/compose-result.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { NodeHandler } from '@kindgi/handler';
+
+import { emitTurnEvent } from '../streaming.js';
+import type { AgentTurnResult, AgentTurnUsage } from './result-shape.js';
+
+import type { TurnContext } from './context.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: unknown): unknown {
+  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: TurnContext): NodeHandler {
+  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: AgentTurnUsage = {
+      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: AgentTurnResult = {
+      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 };
+  };
+}

package/src/handlers/constants.ts

@@ -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;