@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/dist/hitl-policy.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+//
+// Effective HITL policy resolver — computes the runtime policy that
+// gates + timeouts consult, merging in this order:
+//
+//   1. Framework defaults (session gate off, no tool gates, 24h timeout,
+//      standard reviewer, `escalate` on timeout).
+//   2. Agent's `conversationPolicy.hitl` (and `hitlAfterTurns`).
+//   3. The tenant's `hitl` policy (`HitlSpec`) — only stricter: it can
+//      shorten the timeout, raise the reviewer role, and set a floor
+//      under a tool's gate, never loosen.
+//
+// The agent turn resolves it once, at the start (see
+// `resolveTurnHitlPolicy`), instead of reading
+// `agent.conversationPolicy.hitl` directly.
+//
+import { higherRole, toolHitlRule } from '@kindgi/policy-contract';
+/**
+ * Framework defaults. Every field non-optional so the resolver's
+ * return type is fully-populated regardless of caller policy state.
+ */
+const FRAMEWORK_DEFAULTS = {
+    defaultReviewerRole: 'standard',
+    timeoutMs: 24 * 60 * 60 * 1000,
+    onTimeout: 'escalate',
+};
+/**
+ * Compute the effective HITL policy for a given (tenant, agent) pair:
+ * framework defaults overlaid with the agent's policy, then held to the
+ * tenant's `hitl` policy (only stricter). `tenant: undefined` — the
+ * tenant has none.
+ */
+export function resolveEffectiveHitlPolicy(input) {
+    const agentHitl = input.agent.conversationPolicy?.hitl;
+    const legacyAfterTurns = input.agent.conversationPolicy?.hitlAfterTurns;
+    const agentAfterTurns = agentHitl?.afterTurns ?? legacyAfterTurns;
+    const merged = {
+        defaultReviewerRole: agentHitl?.defaultReviewerRole ?? FRAMEWORK_DEFAULTS.defaultReviewerRole,
+        timeoutMs: agentHitl?.timeoutMs ?? FRAMEWORK_DEFAULTS.timeoutMs,
+        onTimeout: FRAMEWORK_DEFAULTS.onTimeout,
+    };
+    if (agentAfterTurns !== undefined) {
+        merged.turn = { afterTurns: agentAfterTurns };
+    }
+    const agentToolsPolicy = agentHitl?.tools;
+    if (agentToolsPolicy !== undefined) {
+        const overrides = new Map();
+        if (agentToolsPolicy.overrides !== undefined) {
+            for (const [k, v] of Object.entries(agentToolsPolicy.overrides)) {
+                overrides.set(k, typeof v === 'string' ? { mode: v } : v);
+            }
+        }
+        merged.tools = {
+            ...(agentToolsPolicy.default !== undefined && { default: agentToolsPolicy.default }),
+            overrides,
+        };
+    }
+    // The tenant's policy — only stricter.
+    const tenant = input.tenant;
+    if (tenant !== undefined) {
+        if (tenant.maxTimeoutMs !== undefined && merged.timeoutMs > tenant.maxTimeoutMs) {
+            merged.timeoutMs = tenant.maxTimeoutMs;
+        }
+        merged.defaultReviewerRole =
+            higherRole(merged.defaultReviewerRole, tenant.minReviewerRole) ?? merged.defaultReviewerRole;
+        const floors = Object.entries(tenant.tools ?? {});
+        if (floors.length > 0) {
+            merged.toolFloors = new Map(floors.map(([toolId, value]) => [toolId, toolHitlRule(value)]));
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=hitl-policy.js.map

package/dist/hitl-policy.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export type { AppendMessageInput, ConversationBinding, ConversationPage, ConversationPageCursor, ListConversationsInput, ListConversationsPageInput, OpenConversationInput, ReadMessagesInput, } from './conversation-binding.js';
+export type { RunSnapshotBinding, RunSnapshotRecord, RunSnapshotWriteInput, } from './run-snapshot-binding.js';
+export { defineAgent } from './define.js';
+export type { DefineAgentSpec } from './define.js';
+export { resolveEffectiveHitlPolicy } from './hitl-policy.js';
+export type { EffectiveHitlPolicy } from './hitl-policy.js';
+export { agentStepOutput, invokeAgent, resumeAgentTurn } from './invoke.js';
+export type { AgentStepOutput, AgentTurnAbortedError, AgentTurnResult, AgentTurnUsage, AgentTurnWarning, BudgetExceededError, CapabilityRoutingError, InvokeAgentBindings, InvokeAgentError, InvokeAgentInput, ModelInvocationError, OutputSchemaViolationError, ResumeAgentTurnInput, ToolInvocationError, UnresolvedToolError, } from './invoke.js';
+export { buildRunTrace, categorizeOutcomes, evaluateGate, evaluateSessionGate, resolveGuardrails, } from './guardrails-gate.js';
+export type { HitlRequiredError, GuardrailViolationError, GuardrailsBindings, SessionGateResult, UnresolvedGuardrailError, } from './guardrails-gate.js';
+export { persistProvenance } from './provenance-emit.js';
+export type { ProvenanceBindings } from './provenance-emit.js';
+export type { AgentMessageEvent, GuardrailViolatedEvent, ModelCallCompletedEvent, ModelCallStartedEvent, OnTurnEvent, RetrievalCompletedEvent, ToolCompletedEvent, ToolFailedEvent, ToolStartedEvent, TurnCompletedEvent, TurnEvent, TurnFailedEvent, TurnStartedEvent, } from './streaming.js';
+export { AUTO_INJECTED_VARS, renderInstructions } from './prompt.js';
+export { formatRetrievedForPrompt, runRetrievals } from './retrieval.js';
+export type { RetrievalBindings } from './retrieval.js';
+export type { MissingParameterError, PromptRenderError, RenderContext, RenderFailureError, RenderResult, } from './prompt.js';
+export { createAgentRegistry } from './registry.js';
+export type { AgentRegistry } from './registry.js';
+export { AGENTS_TENANT_SCOPED_TABLES, agentConversations, agentRunSnapshots, } from './schema.js';
+export type { AgentConversationRow, AgentRunSnapshotRow, NewAgentConversationRow, NewAgentRunSnapshotRow, } from './schema.js';
+export type { Agent, AgentBindings, AgentId, AgentOutputSpec, Conversation, ConversationId, ConversationMessage, ConversationPolicy, MessageRole, PromptParameter, RetrievalIntent, RetrievedFact, ToolRef, TurnBudget, } from './types.js';
+export { DEFAULT_TOOL_ERRORS, effectiveToolErrorPolicy } from './handlers/tool-errors.js';
+export type { ToolErrorPolicy, ToolErrorResult } from './handlers/tool-errors.js';
+export type { ToolErrorKind, ToolErrorsSpec } from '@kindgi/policy-contract';
+export type { AgentAlreadyRegisteredError, AgentError, AgentNotFoundError, AgentVersionMismatchError, ConversationClosedError, ConversationNotFoundError, InvalidAgentError, InvalidMessageError, PersistenceError, } from './errors.js';
+export { CURRENT_AGENTS_PAYLOAD_VERSION, unwrap, unwrapOrThrow, wrap } from './versioning.js';
+export type { EnvelopeError, MalformedEnvelopeError, UnsupportedPayloadVersionError, } from './versioning.js';
+export { AGENTS_MIGRATIONS_DIR } from './migrations-dir.js';
+export { AGENT_LOOP_NODE, AGENT_TURN_FLOW, AGENT_TURN_FLOW_ID, AGENT_TURN_FLOW_VERSION, AGENT_TURN_LOOP_MAX_ITERATIONS, 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export { defineAgent } from './define.js';
+export { resolveEffectiveHitlPolicy } from './hitl-policy.js';
+export { agentStepOutput, invokeAgent, resumeAgentTurn } from './invoke.js';
+export { buildRunTrace, categorizeOutcomes, evaluateGate, evaluateSessionGate, resolveGuardrails, } from './guardrails-gate.js';
+export { persistProvenance } from './provenance-emit.js';
+export { AUTO_INJECTED_VARS, renderInstructions } from './prompt.js';
+export { formatRetrievedForPrompt, runRetrievals } from './retrieval.js';
+export { createAgentRegistry } from './registry.js';
+export { AGENTS_TENANT_SCOPED_TABLES, agentConversations, agentRunSnapshots, } from './schema.js';
+export { DEFAULT_TOOL_ERRORS, effectiveToolErrorPolicy } from './handlers/tool-errors.js';
+export { CURRENT_AGENTS_PAYLOAD_VERSION, unwrap, unwrapOrThrow, wrap } from './versioning.js';
+export { AGENTS_MIGRATIONS_DIR } from './migrations-dir.js';
+// ============ Built-in agent-turn flow ============
+// The flow every agent turn runs on, plus its node IDs — the same IDs
+// that appear in run journals, exported so consumers can match on them.
+export { AGENT_LOOP_NODE, AGENT_TURN_FLOW, AGENT_TURN_FLOW_ID, AGENT_TURN_FLOW_VERSION, AGENT_TURN_LOOP_MAX_ITERATIONS, 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';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiBjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAkB5E,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAiBzD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AASzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAuBrB,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAc1F,OAAO,EAAE,8BAA8B,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAM9F,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,qDAAqD;AACrD,sEAAsE;AACtE,wEAAwE;AACxE,OAAO,EACL,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,8BAA8B,EAC9B,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,sBAAsB,CAAC"}

package/dist/invoke.d.ts

@@ -0,0 +1,36 @@
+import type { Result, RunId, TenantId } from '@kindgi/types';
+import { type InvokeAgentError } from './handlers/errors.js';
+import type { InvokeAgentBindings, InvokeAgentInput } from './handlers/public-types.js';
+import type { AgentTurnResult } from './handlers/result-shape.js';
+import type { Agent } from './types.js';
+/**
+ * Execute one agent turn end-to-end as a flow run: one `runGraph`
+ * invocation (through `bindings.runBinding`) against
+ * `AGENT_TURN_FLOW`; handler modules under `./handlers/` implement
+ * each node. The run's outcome is projected back to an
+ * `AgentTurnResult` or an `InvokeAgentError`.
+ *
+ * Budgets enforced (all optional, all take agent-declared defaults):
+ *   - `agent.budget.maxSteps`     — cap on model↔tool iterations (default 8).
+ *   - `agent.budget.maxCostUsd`   — cumulative USD across model calls.
+ *   - `agent.budget.maxWallMs`    — wall-clock cap; combined with abortSignal.
+ */
+export declare function invokeAgent(input: InvokeAgentInput, bindings: InvokeAgentBindings): Promise<Result<AgentTurnResult, InvokeAgentError>>;
+export interface ResumeAgentTurnInput {
+    readonly tenantId: TenantId;
+    readonly runId: RunId;
+    /**
+     * The agent spec resolved at the target version. Callers of
+     * `resumeAgentTurn` are responsible for resolving `agentId +
+     * agentVersion` from the run snapshot against their agent registry
+     * (replay must match the version the run started on — see the setup
+     * handler's agent-version-mismatch guard).
+     */
+    readonly agent: Agent;
+}
+export declare function resumeAgentTurn(input: ResumeAgentTurnInput, bindings: InvokeAgentBindings): Promise<Result<AgentTurnResult, InvokeAgentError>>;
+export type { AgentStepOutput, AgentTurnResult, AgentTurnUsage, AgentTurnWarning, } from './handlers/result-shape.js';
+export { agentStepOutput } from './handlers/result-shape.js';
+export type { AgentTurnAbortedError, BudgetExceededError, CapabilityRoutingError, InvokeAgentError, ModelInvocationError, OutputSchemaViolationError, ToolInvocationError, UnresolvedToolError, } from './handlers/errors.js';
+export type { HitlBindings, HitlEnqueueInput, HitlEnqueueResult, InvokeAgentBindings, InvokeAgentInput, } from './handlers/public-types.js';
+//# sourceMappingURL=invoke.d.ts.map

package/dist/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../src/invoke.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAK7D,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAExF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC,CA8DpD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAmDD,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC,CA2GpD;AAMD,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,4BAA4B,CAAC"}

package/dist/invoke.js

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { AGENT_TURN_FLOW } from './agent-turn-flow.js';
+import { DEFAULT_MAX_WALL_MS } from './handlers/constants.js';
+import { AgentTurnFailure } from './handlers/errors.js';
+import { buildHandlers } from './handlers/index.js';
+import { rehydrateTurnContext } from './handlers/rehydrate.js';
+import { projectRunResult } from './project-run-result.js';
+/**
+ * Execute one agent turn end-to-end as a flow run: one `runGraph`
+ * invocation (through `bindings.runBinding`) against
+ * `AGENT_TURN_FLOW`; handler modules under `./handlers/` implement
+ * each node. The run's outcome is projected back to an
+ * `AgentTurnResult` or an `InvokeAgentError`.
+ *
+ * Budgets enforced (all optional, all take agent-declared defaults):
+ *   - `agent.budget.maxSteps`     — cap on model↔tool iterations (default 8).
+ *   - `agent.budget.maxCostUsd`   — cumulative USD across model calls.
+ *   - `agent.budget.maxWallMs`    — wall-clock cap; combined with abortSignal.
+ */
+export async function invokeAgent(input, bindings) {
+    const started = Date.now();
+    const maxWallMs = input.agent.budget?.maxWallMs ?? DEFAULT_MAX_WALL_MS;
+    const controller = new AbortController();
+    const ctx = {
+        input,
+        bindings,
+        turnAbort: controller,
+        startedAt: started,
+        appended: [],
+        usage: {
+            steps: 0,
+            promptTokens: 0,
+            completionTokens: 0,
+            totalCostUsd: 0,
+        },
+        abortReason: undefined,
+    };
+    const timer = setTimeout(() => {
+        ctx.abortReason = 'timeout';
+        controller.abort(new Error('wall-clock budget exhausted'));
+    }, maxWallMs);
+    if (input.abortSignal !== undefined) {
+        const external = input.abortSignal;
+        if (external.aborted) {
+            ctx.abortReason = 'external';
+            controller.abort(external.reason);
+        }
+        else {
+            external.addEventListener('abort', () => {
+                ctx.abortReason = 'external';
+                controller.abort(external.reason);
+            });
+        }
+    }
+    try {
+        const handlers = buildHandlers(ctx);
+        if (bindings.runBinding === undefined) {
+            throw new Error('invokeAgent: bindings.runBinding is required — pass the RunBinding (from @kindgi/runtime) of the runtime that executes the turn.');
+        }
+        const runResult = await bindings.runBinding.runGraph({
+            tenantId: input.tenantId,
+            projectId: input.projectId,
+            flow: AGENT_TURN_FLOW,
+            handlers,
+            input: input.userMessage,
+            ...(input.parent !== undefined && { parent: input.parent }),
+            ...(input.dryRun === true && { options: { dryRun: true } }),
+            // Authorization — carry principal + authz into the run so every
+            // tool invocation inside the agent's turn is checked.
+            ...(input.principal !== undefined && { principal: input.principal }),
+            ...(input.authz !== undefined && { authz: input.authz }),
+        });
+        return await projectRunResult(runResult, ctx);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Resume a suspended agent turn — invoked after a kernel waitpoint
+ * resolves (e.g. a HITL approval completes). Loads the reconstruction
+ * snapshot written by the setup handler, rebuilds an equivalent
+ * `InvokeAgentInput` + `TurnContext`, then calls
+ * `bindings.runBinding.resumeRun`, which replays the flow from the
+ * journal.
+ *
+ * Same runId, same conversationId, same provenance record across the
+ * park-and-resume cycle. Any handler that was mid-execution when the
+ * wait suspended runs again from the top; `ctx.waitForToken` returns
+ * the resolved value from derived state instead of throwing another
+ * SuspensionSignal.
+ *
+ * Fails with `run-snapshot-missing` when no snapshot exists for the
+ * runId — this happens when the setup handler's snapshot write failed
+ * (the write is best-effort). Recovery: cancel the run explicitly;
+ * there is no way to reconstruct the InvokeAgentInput without the
+ * snapshot.
+ */
+/**
+ * Rebuild a resumed turn's context from its journal (see
+ * `rehydrateTurnContext`). Returns the turn's error when it can't be
+ * rebuilt; `undefined` to go on and resume.
+ */
+async function rehydrateFromJournal(ctx, runId, runBinding) {
+    const journal = await runBinding.readJournal(ctx.input.tenantId, runId);
+    if (journal.kind === 'err') {
+        return {
+            kind: 'err',
+            error: {
+                code: 'run-journal-unavailable',
+                message: `Failed to read the journal of run ${runId}: ${journal.error.message}`,
+            },
+        };
+    }
+    try {
+        await rehydrateTurnContext(ctx, runId, journal.value);
+        return undefined;
+    }
+    catch (cause) {
+        if (cause instanceof AgentTurnFailure)
+            return { kind: 'err', error: cause.payload };
+        throw cause;
+    }
+}
+export async function resumeAgentTurn(input, bindings) {
+    // 1. Load the snapshot via the run-snapshot binding.
+    const snapshotResult = await bindings.runSnapshotBinding.read(input.tenantId, input.runId);
+    if (snapshotResult.kind === 'err') {
+        return {
+            kind: 'err',
+            error: {
+                code: 'run-snapshot-missing',
+                message: `Failed to load run snapshot for run ${input.runId}: ${snapshotResult.error.message}`,
+            },
+        };
+    }
+    const snapshot = snapshotResult.value;
+    if (snapshot === null) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'run-snapshot-missing',
+                message: `No run snapshot for run ${input.runId} — resume-context unavailable.`,
+            },
+        };
+    }
+    // 2. Agent-version sanity check — the caller passes the Agent spec they
+    // resolved via the registry; we refuse if it doesn't match the pinned
+    // version in the snapshot. Mirrors the setup handler's guard.
+    if (snapshot.agentId !== input.agent.id ||
+        snapshot.agentVersion !== input.agent.version) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'agent-version-mismatch',
+                message: `Snapshot pinned to ${snapshot.agentId}@${snapshot.agentVersion}; resume called with ${input.agent.id}@${input.agent.version}`,
+                expectedVersion: snapshot.agentVersion,
+                actualVersion: input.agent.version,
+            },
+        };
+    }
+    // 3. Reconstruct the InvokeAgentInput envelope from the snapshot.
+    const reconstructedInput = {
+        tenantId: snapshot.tenantId,
+        projectId: snapshot.projectId,
+        agent: input.agent,
+        conversationId: snapshot.conversationId,
+        userMessage: snapshot.userMessage,
+        ...(snapshot.parameters !== undefined && { parameters: snapshot.parameters }),
+        ...(snapshot.input !== undefined && { input: snapshot.input }),
+        ...(snapshot.participantId !== undefined && { participantId: snapshot.participantId }),
+        ...(snapshot.dryRun && { dryRun: true }),
+        ...(snapshot.principal !== undefined &&
+            snapshot.principal !== null && {
+            principal: snapshot.principal,
+        }),
+        ...(snapshot.authz !== undefined &&
+            snapshot.authz !== null && {
+            authz: snapshot.authz,
+        }),
+    };
+    // 4. Build the same TurnContext + handlers as invokeAgent().
+    const started = Date.now();
+    const maxWallMs = input.agent.budget?.maxWallMs ?? DEFAULT_MAX_WALL_MS;
+    const controller = new AbortController();
+    const ctx = {
+        input: reconstructedInput,
+        bindings,
+        turnAbort: controller,
+        startedAt: started,
+        appended: [],
+        usage: {
+            steps: 0,
+            promptTokens: 0,
+            completionTokens: 0,
+            totalCostUsd: 0,
+        },
+        abortReason: undefined,
+    };
+    const timer = setTimeout(() => {
+        ctx.abortReason = 'timeout';
+        controller.abort(new Error('wall-clock budget exhausted'));
+    }, maxWallMs);
+    try {
+        const handlers = buildHandlers(ctx);
+        if (bindings.runBinding === undefined) {
+            throw new Error('resumeAgentTurn: bindings.runBinding is required.');
+        }
+        // The kernel won't re-run the steps that completed before the park,
+        // and they kept their state on the in-memory context: rebuild it.
+        const rehydrated = await rehydrateFromJournal(ctx, input.runId, bindings.runBinding);
+        if (rehydrated !== undefined)
+            return rehydrated;
+        const runResult = await bindings.runBinding.resumeRun({
+            tenantId: reconstructedInput.tenantId,
+            runId: input.runId,
+            flow: AGENT_TURN_FLOW,
+            handlers,
+        });
+        return await projectRunResult(runResult, ctx);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export { agentStepOutput } from './handlers/result-shape.js';
+//# sourceMappingURL=invoke.js.map

package/dist/invoke.js.map

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

package/dist/migrations-dir.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Absolute path to the SQL migrations shipped with `@kindgi/agents`.
+ *
+ * Resolved from this module's own URL, so it is correct in every layout
+ * the package can be installed in (workspace checkout, a workspace in
+ * another repository, `node_modules`, `pnpm deploy` output) — from both
+ * `src/` and `dist/`. Migration runners use this instead of computing
+ * package-relative paths themselves.
+ */
+export declare const AGENTS_MIGRATIONS_DIR: string;
+//# sourceMappingURL=migrations-dir.d.ts.map

package/dist/migrations-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations-dir.d.ts","sourceRoot":"","sources":["../src/migrations-dir.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAEnC,CAAC"}

package/dist/migrations-dir.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { fileURLToPath } from 'node:url';
+/**
+ * Absolute path to the SQL migrations shipped with `@kindgi/agents`.
+ *
+ * Resolved from this module's own URL, so it is correct in every layout
+ * the package can be installed in (workspace checkout, a workspace in
+ * another repository, `node_modules`, `pnpm deploy` output) — from both
+ * `src/` and `dist/`. Migration runners use this instead of computing
+ * package-relative paths themselves.
+ */
+export const AGENTS_MIGRATIONS_DIR = fileURLToPath(new URL('../migrations/', import.meta.url));
+//# sourceMappingURL=migrations-dir.js.map

package/dist/migrations-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations-dir.js","sourceRoot":"","sources":["../src/migrations-dir.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAW,aAAa,CACxD,IAAI,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAC3C,CAAC"}

package/dist/project-run-result.d.ts

@@ -0,0 +1,23 @@
+import type { KernelError, RunResult } from '@kindgi/runtime';
+import type { Result } from '@kindgi/types';
+import type { TurnContext } from './handlers/context.js';
+import type { InvokeAgentError } from './handlers/errors.js';
+import type { AgentTurnResult } from './handlers/result-shape.js';
+/**
+ * Translate a kernel `Result<RunResult, KernelError>` into the
+ * caller-facing `Result<AgentTurnResult, InvokeAgentError>`. Rules:
+ *
+ *   - Kernel-level errors (`handler-missing`, `flow-mismatch`,
+ *     `journal-error`, `stuck`, `run-not-found`, etc.) map to
+ *     `model-invocation-failed` with the KernelError as cause.
+ *   - Run status `completed` — output is the `AgentTurnResult`
+ *     composed by `compose-result`; unwrap and return `Result.ok`.
+ *   - Run status `failed` — `failureMessage` was serialized by
+ *     `AgentTurnFailure` on the throwing handler; parse back into
+ *     structured `InvokeAgentError`. Fall back to
+ *     `model-invocation-failed` if the message isn't ours.
+ *   - Run status `cancelled` — external abort. Use `ctx.abortReason`
+ *     to distinguish external vs timeout.
+ */
+export declare function projectRunResult(kernelResult: Result<RunResult<AgentTurnResult>, KernelError>, ctx: TurnContext): Promise<Result<AgentTurnResult, InvokeAgentError>>;
+//# sourceMappingURL=project-run-result.d.ts.map

package/dist/project-run-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-run-result.d.ts","sourceRoot":"","sources":["../src/project-run-result.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAGlE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC,EAAE,WAAW,CAAC,EAC7D,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC,CAmGpD"}

package/dist/project-run-result.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { parseFailureMessage } from './handlers/errors.js';
+import { emitTurnEvent } from './streaming.js';
+/**
+ * Translate a kernel `Result<RunResult, KernelError>` into the
+ * caller-facing `Result<AgentTurnResult, InvokeAgentError>`. Rules:
+ *
+ *   - Kernel-level errors (`handler-missing`, `flow-mismatch`,
+ *     `journal-error`, `stuck`, `run-not-found`, etc.) map to
+ *     `model-invocation-failed` with the KernelError as cause.
+ *   - Run status `completed` — output is the `AgentTurnResult`
+ *     composed by `compose-result`; unwrap and return `Result.ok`.
+ *   - Run status `failed` — `failureMessage` was serialized by
+ *     `AgentTurnFailure` on the throwing handler; parse back into
+ *     structured `InvokeAgentError`. Fall back to
+ *     `model-invocation-failed` if the message isn't ours.
+ *   - Run status `cancelled` — external abort. Use `ctx.abortReason`
+ *     to distinguish external vs timeout.
+ */
+export async function projectRunResult(kernelResult, ctx) {
+    if (kernelResult.kind === 'err') {
+        return {
+            kind: 'err',
+            error: {
+                code: 'model-invocation-failed',
+                message: `Kernel run failed: ${kernelResult.error.message}`,
+                cause: kernelResult.error,
+            },
+        };
+    }
+    const run = kernelResult.value;
+    if (run.status === 'completed') {
+        if (run.output === undefined) {
+            return {
+                kind: 'err',
+                error: {
+                    code: 'model-invocation-failed',
+                    message: 'Agent-turn run completed without emitting a result',
+                    cause: null,
+                },
+            };
+        }
+        return { kind: 'ok', value: { ...run.output, status: 'completed' } };
+    }
+    // Park-and-resume: the run suspended on a waitpoint (the setup
+    // handler's session-HITL gate or a tool-level gate in the
+    // dispatch-tools handler). Turn hasn't produced a response yet — the
+    // reviewer's decision will resume the flow, and the resumed run's
+    // completion produces the final AgentTurnResult in a follow-up call
+    // (via resumeAgentTurn). An HTTP caller surfaces status='suspended'
+    // to its client. Return a minimally-shaped AgentTurnResult so
+    // kind='ok' is honest — the parked run is a successful start, not a
+    // failure.
+    if (run.status === 'suspended') {
+        return {
+            kind: 'ok',
+            value: {
+                runId: run.runId,
+                conversationId: ctx.input.conversationId,
+                turnNumber: 0,
+                appended: [],
+                response: {
+                    role: 'assistant',
+                    content: '',
+                },
+                retrieved: [],
+                violations: [],
+                usage: {
+                    steps: 0,
+                    promptTokens: 0,
+                    completionTokens: 0,
+                    totalCostUsd: 0,
+                    durationMs: Date.now() - ctx.startedAt,
+                },
+                provider: { id: '', model: '' },
+                status: 'suspended',
+            },
+        };
+    }
+    if (run.status === 'cancelled') {
+        const err = {
+            code: 'agent-turn-aborted',
+            message: `Agent turn cancelled${run.failureMessage !== undefined ? `: ${run.failureMessage}` : ''}`,
+            reason: ctx.abortReason ?? 'external',
+        };
+        await emitTurnEvent(ctx.bindings.onEvent, {
+            kind: 'turn.failed',
+            conversationId: ctx.input.conversationId,
+            errorCode: err.code,
+            message: err.message,
+        });
+        return { kind: 'err', error: err };
+    }
+    // Failed
+    const parsed = parseFailureMessage(run.failureMessage);
+    if (parsed !== undefined) {
+        // For failed runs, `turn.failed` is emitted only for guardrail
+        // violations, by the evaluate-guardrails handler — nothing to emit
+        // here.
+        if (parsed.code === 'guardrail-violation') {
+            // Already emitted by the evaluate-guardrails handler — skip.
+        }
+        return { kind: 'err', error: parsed };
+    }
+    // Unstructured failure — a bare exception the handlers didn't wrap.
+    return {
+        kind: 'err',
+        error: {
+            code: 'model-invocation-failed',
+            message: run.failureMessage ?? 'Agent turn failed',
+            cause: null,
+        },
+    };
+}
+//# sourceMappingURL=project-run-result.js.map

package/dist/project-run-result.js.map

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