@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/dist/handlers/structured-output.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { compileInlineSchema } from '@kindgi/schema';
+/** Default number of repair attempts. */
+export const DEFAULT_MAX_REPAIRS = 1;
+/** Marks the messages this module adds, so they can be counted. */
+const REPAIR_MARKER = '[kindgi:output-repair]';
+/**
+ * The answer's text as JSON. Accepts a bare JSON value or one fenced
+ * as ```json … ``` (models often fence it).
+ */
+export function parseJsonAnswer(content) {
+    if (typeof content !== 'string') {
+        return { kind: 'invalid', errors: ['the answer is not text'] };
+    }
+    const text = unfence(content.trim());
+    if (text.length === 0)
+        return { kind: 'invalid', errors: ['the answer is empty'] };
+    try {
+        return { kind: 'ok', value: JSON.parse(text) };
+    }
+    catch (cause) {
+        return {
+            kind: 'invalid',
+            errors: [
+                `the answer is not valid JSON (${cause instanceof Error ? cause.message : String(cause)})`,
+            ],
+        };
+    }
+}
+function unfence(text) {
+    const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n?```$/i.exec(text);
+    return fenced?.[1]?.trim() ?? text;
+}
+export function outputChecker(spec) {
+    const compiled = compileInlineSchema(spec.schema);
+    if (compiled.kind === 'err') {
+        // `defineAgent` compiles the schema, so this is an agent built by hand.
+        const reason = compiled.error.message;
+        return {
+            check: () => ({ kind: 'invalid', errors: [`the output schema is invalid: ${reason}`] }),
+        };
+    }
+    const validator = compiled.value;
+    return {
+        check(content) {
+            const parsed = parseJsonAnswer(content);
+            if (parsed.kind === 'invalid')
+                return parsed;
+            const validated = validator.validate(parsed.value);
+            if (validated.kind === 'ok')
+                return parsed;
+            return { kind: 'invalid', errors: describeErrors(validated.error.errors) };
+        },
+    };
+}
+/** Ajv errors as `path message` lines the model can act on. */
+function describeErrors(errors) {
+    const list = errors.map((raw) => {
+        const e = raw;
+        const where = e.instancePath === undefined || e.instancePath === '' ? '(root)' : e.instancePath;
+        return `${where} ${e.message ?? 'is invalid'}`;
+    });
+    return list.length > 0 ? list : ['the answer does not match the schema'];
+}
+/** Whether a message is one of this module's repair requests. */
+export function isRepairMessage(m) {
+    return m.role === 'user' && typeof m.content === 'string' && m.content.startsWith(REPAIR_MARKER);
+}
+/** How many repairs this turn has asked for so far. */
+export function repairsSoFar(messages) {
+    return messages.filter(isRepairMessage).length;
+}
+/** The message asking the model to fix its answer. */
+export function repairMessage(spec, errors) {
+    const name = spec.name ?? 'output';
+    return {
+        role: 'user',
+        content: [
+            REPAIR_MARKER,
+            `Your answer must be the ${name} as JSON matching this JSON Schema, and nothing else:`,
+            JSON.stringify(spec.schema),
+            'It did not fit:',
+            ...errors.map((e) => `- ${e}`),
+            `Reply again with only the corrected ${name} JSON.`,
+        ].join('\n'),
+    };
+}
+//# sourceMappingURL=structured-output.js.map

package/dist/handlers/structured-output.js.map

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

package/dist/handlers/tool-errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Retrying failed tool calls. A failure the turn's policy retries goes
+ * back to the model as the call's result — what failed and why — and
+ * the turn continues; the model can correct the call. Each retry costs a
+ * step, so `budget.maxSteps` still bounds the turn. A failure the policy
+ * doesn't retry, or one past `maxRetries`, fails the turn as before.
+ *
+ * Retries are counted from the turn's messages (the results this module
+ * writes carry a marker), so a replayed turn counts the same.
+ */
+import type { ModelMessage } from '@kindgi/capabilities';
+import { type ToolErrorKind, type ToolErrorsSpec } from '@kindgi/policy-contract';
+/** Without an agent setting: one retry, for failures where nothing ran. */
+export declare const DEFAULT_TOOL_ERRORS: Required<ToolErrorsSpec>;
+/** The policy a turn applies. */
+export interface ToolErrorPolicy {
+    readonly maxRetries: number;
+    readonly retryOn: ReadonlySet<ToolErrorKind>;
+}
+/**
+ * The agent's setting (or the default), capped by the tenant's
+ * `tool-errors` policy: the fewer retries, and only the kinds both
+ * allow — like every tenant policy, it can only make the turn stricter.
+ */
+export declare function effectiveToolErrorPolicy(agent: ToolErrorsSpec | undefined, tenantCap: ToolErrorsSpec | undefined): ToolErrorPolicy;
+/**
+ * Which kind of failure a tool call's error is: arguments that failed
+ * the input schema, a tool the agent doesn't have, or a tool that ran
+ * and failed.
+ */
+export declare function toolErrorKindOf(error: {
+    readonly code: string;
+    readonly cause?: unknown;
+}): ToolErrorKind;
+/** Marks the results this module writes, so they can be counted. */
+declare const RETRY_MARKER = "tool-error-retry";
+/** What the model sees for a failed call it may retry. */
+export interface ToolErrorResult {
+    readonly kindgi: typeof RETRY_MARKER;
+    readonly status: 'failed';
+    readonly error: {
+        readonly kind: ToolErrorKind;
+        readonly message: string;
+        readonly issues?: readonly unknown[];
+    };
+    readonly instruction: string;
+}
+export declare function toolErrorResult(kind: ToolErrorKind, message: string, issues: readonly unknown[] | undefined): ToolErrorResult;
+/**
+ * Retries this turn has taken: the marked tool results after the turn's
+ * user message. Earlier turns' results come back as history; they don't
+ * count.
+ */
+export declare function toolRetriesSoFar(messages: readonly ModelMessage[]): number;
+export {};
+//# sourceMappingURL=tool-errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-errors.d.ts","sourceRoot":"","sources":["../../src/handlers/tool-errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAoB,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAIpG,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,cAAc,CAGxD,CAAC;AAEF,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,cAAc,GAAG,SAAS,EACjC,SAAS,EAAE,cAAc,GAAG,SAAS,GACpC,eAAe,CAQjB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,aAAa,CAIhB;AAED,oEAAoE;AACpE,QAAA,MAAM,YAAY,qBAAqB,CAAC;AAExC,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAQD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GACrC,eAAe,CAOjB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAU1E"}

package/dist/handlers/tool-errors.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { TOOL_ERROR_KINDS } from '@kindgi/policy-contract';
+import { isRepairMessage } from './structured-output.js';
+/** Without an agent setting: one retry, for failures where nothing ran. */
+export const DEFAULT_TOOL_ERRORS = {
+    maxRetries: 1,
+    retryOn: ['invalid-arguments', 'unknown-tool'],
+};
+/**
+ * The agent's setting (or the default), capped by the tenant's
+ * `tool-errors` policy: the fewer retries, and only the kinds both
+ * allow — like every tenant policy, it can only make the turn stricter.
+ */
+export function effectiveToolErrorPolicy(agent, tenantCap) {
+    const maxRetries = Math.min(agent?.maxRetries ?? DEFAULT_TOOL_ERRORS.maxRetries, tenantCap?.maxRetries ?? Number.POSITIVE_INFINITY);
+    const allowed = new Set(tenantCap?.retryOn ?? TOOL_ERROR_KINDS);
+    const retryOn = (agent?.retryOn ?? DEFAULT_TOOL_ERRORS.retryOn).filter((k) => allowed.has(k));
+    return { maxRetries, retryOn: new Set(retryOn) };
+}
+/**
+ * Which kind of failure a tool call's error is: arguments that failed
+ * the input schema, a tool the agent doesn't have, or a tool that ran
+ * and failed.
+ */
+export function toolErrorKindOf(error) {
+    if (error.code === 'unresolved-tool')
+        return 'unknown-tool';
+    const inner = error.cause?.code;
+    return inner === 'input-validation-failed' ? 'invalid-arguments' : 'tool-error';
+}
+/** Marks the results this module writes, so they can be counted. */
+const RETRY_MARKER = 'tool-error-retry';
+const INSTRUCTIONS = {
+    'invalid-arguments': "Fix the arguments to match the tool's input schema and call it again.",
+    'unknown-tool': 'Call one of the tools you were given instead.',
+    'tool-error': 'The tool failed. Call it again if a retry makes sense, or answer without it.',
+};
+export function toolErrorResult(kind, message, issues) {
+    return {
+        kindgi: RETRY_MARKER,
+        status: 'failed',
+        error: { kind, message, ...(issues !== undefined && { issues }) },
+        instruction: INSTRUCTIONS[kind],
+    };
+}
+/**
+ * Retries this turn has taken: the marked tool results after the turn's
+ * user message. Earlier turns' results come back as history; they don't
+ * count.
+ */
+export function toolRetriesSoFar(messages) {
+    let start = 0;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m !== undefined && m.role === 'user' && !isRepairMessage(m)) {
+            start = i + 1;
+            break;
+        }
+    }
+    return messages.slice(start).filter(isRetryResult).length;
+}
+function isRetryResult(m) {
+    if (m.role !== 'tool')
+        return false;
+    try {
+        return JSON.parse(m.content).kindgi === RETRY_MARKER;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=tool-errors.js.map

package/dist/handlers/tool-errors.js.map

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

package/dist/handlers/tool-hitl.d.ts

@@ -0,0 +1,45 @@
+import type { Tool } from '@kindgi/tools';
+import type { Agent, ToolHitlMode } from '../types.js';
+export interface ResolvedToolHitl {
+    readonly mode: ToolHitlMode;
+    readonly requiredRole: 'standard' | 'senior' | 'admin';
+}
+export declare function resolveToolHitl(agent: Agent, tool: Tool): ResolvedToolHitl;
+/**
+ * Deterministic hash of tool arguments — used as the cache key for
+ * `ask_on_first_use`. Sorted-key JSON so reordered args don't produce
+ * a different hash.
+ */
+export declare function hashToolArgs(args: unknown): string;
+/**
+ * Deterministic waitpoint token for a tool-call gate. Includes both
+ * the model-generated call id (unique per iteration) AND the args hash
+ * so kernel flow replay lands on the same token, and a re-issued
+ * tool-call in a later iteration gets its own gate.
+ */
+export declare function computeToolCallWaitToken(input: {
+    readonly runId: string;
+    readonly callId: string;
+    readonly argsHash: string;
+}): string;
+/**
+ * Shape the tool-level waitpoint resolves to when the reviewer decides.
+ * Same shape as session-gate decisions — the approvals-complete route
+ * materializes it identically.
+ */
+export interface ToolHitlDecision {
+    readonly decided: 'approve' | 'reject';
+    readonly rationale?: string;
+}
+/**
+ * In-conversation cache of decisions for `ask_on_first_use`. Persisted
+ * on `agent_conversations.metadata.hitlToolDecisions` — a flat map of
+ * `${toolId}:${argsHash}` → decision. Read/write goes through the
+ * conversation row's metadata via the standard update path.
+ */
+export interface ToolDecisionCacheKey {
+    readonly toolId: string;
+    readonly argsHash: string;
+}
+export declare function cacheKeyFor(key: ToolDecisionCacheKey): string;
+//# sourceMappingURL=tool-hitl.d.ts.map

package/dist/handlers/tool-hitl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hitl.d.ts","sourceRoot":"","sources":["../../src/handlers/tool-hitl.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAgB,MAAM,aAAa,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;CACxD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAkC1E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAElD;AAWD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAKT;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,QAAQ,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAE7D"}

package/dist/handlers/tool-hitl.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+//
+// Tool-level HITL — resolves the effective `ToolHitlMode` for a given
+// (agent, tool) pair. Consumed by `dispatch-tools.ts` to
+// decide whether a tool call parks the run on a kernel waitpoint before
+// dispatch.
+//
+// Resolution order (narrower wins, framework default is fail-open):
+//   1. `agent.conversationPolicy.hitl.tools.overrides[toolId]` — exact match
+//   2. `agent.conversationPolicy.hitl.tools.default` — agent-wide default
+//   3. per-tool default from `Tool.mutating` — safe fallback
+//        - `mutating: false`  → `never_ask`
+//        - `mutating: true` or absent → `ask_on_first_use` (defaults safer)
+//
+// The effective-policy resolver (`hitl-policy.ts`) layers the tenant
+// cap on top.
+//
+import { createHash } from 'node:crypto';
+export function resolveToolHitl(agent, tool) {
+    const hitl = agent.conversationPolicy?.hitl;
+    const toolsPolicy = hitl?.tools;
+    const defaultRole = hitl?.defaultReviewerRole ?? 'standard';
+    // Opt-in: agents that don't declare `hitl.tools` get no tool-level
+    // gates. Matches the design's "fail-open" default — HITL is opt-in
+    // at the agent level, not implicit.
+    if (toolsPolicy === undefined) {
+        return { mode: 'never_ask', requiredRole: defaultRole };
+    }
+    // 1. Explicit override for this toolId.
+    const rawOverride = toolsPolicy.overrides?.[tool.id];
+    if (rawOverride !== undefined) {
+        const rule = typeof rawOverride === 'string' ? { mode: rawOverride } : rawOverride;
+        return {
+            mode: rule.mode,
+            requiredRole: rule.requiredRole ?? defaultRole,
+        };
+    }
+    // 2. Agent-wide default.
+    if (toolsPolicy.default !== undefined) {
+        return { mode: toolsPolicy.default, requiredRole: defaultRole };
+    }
+    // 3. Per-tool default from Tool.mutating — only reached when
+    // `hitl.tools` is present (opt-in) but neither an override nor a
+    // default matches. Read-only tools skip the gate; mutating tools
+    // ask on first use.
+    const mode = tool.mutating === false ? 'never_ask' : 'ask_on_first_use';
+    return { mode, requiredRole: defaultRole };
+}
+/**
+ * Deterministic hash of tool arguments — used as the cache key for
+ * `ask_on_first_use`. Sorted-key JSON so reordered args don't produce
+ * a different hash.
+ */
+export function hashToolArgs(args) {
+    return createHash('sha256').update(canonicalStringify(args)).digest('hex').slice(0, 40);
+}
+function canonicalStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalStringify).join(',')}]`;
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalStringify(v)}`).join(',')}}`;
+}
+/**
+ * Deterministic waitpoint token for a tool-call gate. Includes both
+ * the model-generated call id (unique per iteration) AND the args hash
+ * so kernel flow replay lands on the same token, and a re-issued
+ * tool-call in a later iteration gets its own gate.
+ */
+export function computeToolCallWaitToken(input) {
+    return createHash('sha256')
+        .update(`tool-call:${input.runId}:${input.callId}:${input.argsHash}`)
+        .digest('hex')
+        .slice(0, 40);
+}
+export function cacheKeyFor(key) {
+    return `${key.toolId}:${key.argsHash}`;
+}
+//# sourceMappingURL=tool-hitl.js.map

package/dist/handlers/tool-hitl.js.map

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

package/dist/handlers/turn-environment.d.ts

@@ -0,0 +1,26 @@
+import { type EffectiveHitlPolicy } from '../hitl-policy.js';
+import type { Conversation } from '../types.js';
+import type { TurnContext } from './context.js';
+/** The conversation the turn runs in: open, and opened with this agent version. */
+export declare function loadTurnConversation(ctx: TurnContext): Promise<Conversation>;
+/** The model a turn was routed to, as `setup` journals it. */
+export interface PinnedRoute {
+    readonly providerId: string;
+    readonly model: string;
+}
+/**
+ * Resolve the turn's guardrails, tools, tenant policy, tool-error policy
+ * and model onto `ctx`. With `pinned`, the route is that provider and
+ * model, still under the tenant's current policy; one no longer
+ * registered or allowed fails the turn.
+ */
+export declare function resolveTurnEnvironment(ctx: TurnContext, pinned?: PinnedRoute): Promise<PinnedRoute & {
+    readonly toolCount: number;
+}>;
+/**
+ * The turn's approval rules: the agent's, held to the tenant's `hitl`
+ * policy. A policy that can't be evaluated fails the turn — running
+ * without it would skip the tenant's approvals.
+ */
+export declare function resolveTurnHitlPolicy(ctx: TurnContext): Promise<EffectiveHitlPolicy>;
+//# sourceMappingURL=turn-environment.d.ts.map

package/dist/handlers/turn-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-environment.d.ts","sourceRoot":"","sources":["../../src/handlers/turn-environment.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,mBAAmB,EAA8B,MAAM,mBAAmB,CAAC;AAEzF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,mFAAmF;AACnF,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CA4BlF;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,WAAW,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAkFvD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiB1F"}

package/dist/handlers/turn-environment.js

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * What a turn runs against: its conversation, and the guardrails, tools,
+ * policies and model it resolves at the start. `setup` resolves them
+ * once per turn; a resumed turn resolves them again (see
+ * `rehydrateTurnContext`), pinned to the model `setup` routed to, since
+ * the kernel doesn't re-run a step that already completed and these live
+ * on the in-memory `TurnContext`.
+ */
+import { route } from '@kindgi/capabilities';
+import { resolveGuardrails } from '../guardrails-gate.js';
+import { resolveEffectiveHitlPolicy } from '../hitl-policy.js';
+import { mergeTenantPolicies } from '../tenant-policy.js';
+import { throwAgentTurnFailure } from './errors.js';
+import { resolveTurnTools } from './resolve-tools.js';
+import { effectiveToolErrorPolicy } from './tool-errors.js';
+/** The conversation the turn runs in: open, and opened with this agent version. */
+export async function loadTurnConversation(ctx) {
+    const conv = await ctx.bindings.conversationBinding.getConversation(ctx.input.tenantId, ctx.input.conversationId);
+    if (conv.kind === 'err')
+        throwAgentTurnFailure(conv.error);
+    if (conv.value.closedAt !== undefined) {
+        const err = {
+            code: 'conversation-closed',
+            message: `Conversation "${ctx.input.conversationId}" is closed`,
+            conversationId: ctx.input.conversationId,
+        };
+        throwAgentTurnFailure(err);
+    }
+    if (conv.value.agentId !== ctx.input.agent.id ||
+        conv.value.agentVersion !== ctx.input.agent.version) {
+        throwAgentTurnFailure({
+            code: 'agent-version-mismatch',
+            message: `Conversation opened with ${conv.value.agentId}@${conv.value.agentVersion}; invoked with ${ctx.input.agent.id}@${ctx.input.agent.version}`,
+            conversationId: ctx.input.conversationId,
+            expectedVersion: conv.value.agentVersion,
+            actualVersion: ctx.input.agent.version,
+        });
+    }
+    ctx.conversation = conv.value;
+    return conv.value;
+}
+/**
+ * Resolve the turn's guardrails, tools, tenant policy, tool-error policy
+ * and model onto `ctx`. With `pinned`, the route is that provider and
+ * model, still under the tenant's current policy; one no longer
+ * registered or allowed fails the turn.
+ */
+export async function resolveTurnEnvironment(ctx, pinned) {
+    const invResolution = resolveGuardrails(ctx.input.agent, ctx.bindings);
+    if (invResolution.missing.length > 0) {
+        throwAgentTurnFailure({
+            code: 'unresolved-guardrail',
+            message: `Agent "${ctx.input.agent.id}" references guardrails not in the registry: ${invResolution.missing.join(', ')}`,
+            guardrailIds: invResolution.missing,
+        });
+    }
+    ctx.guardrails = invResolution.resolved;
+    // This turn's tools come from the tenant's own registry — never a
+    // registry shared across concurrent turns of other tenants.
+    const tenantTools = await ctx.bindings.toolRegistry.forTenant(ctx.input.tenantId);
+    ctx.tools = resolveTurnTools(tenantTools, ctx.input.agent);
+    const capability = ctx.input.agent.capabilities[0];
+    if (capability === undefined) {
+        throwAgentTurnFailure({
+            code: 'capability-routing-failed',
+            message: `Agent "${ctx.input.agent.id}" has no capabilities declared`,
+            cause: null,
+        });
+    }
+    // Merge the static tenant policy with the one derived from the
+    // policy registry (if wired); the result is at least as strict as
+    // each (see `mergeTenantPolicies`).
+    const derivedPolicy = ctx.bindings.policyRegistry !== undefined
+        ? await ctx.bindings.policyRegistry.evaluate('model-routing', { tenantId: ctx.input.tenantId })
+        : undefined;
+    const effectivePolicy = mergeTenantPolicies(ctx.bindings.tenantPolicy, derivedPolicy);
+    if (effectivePolicy !== undefined)
+        ctx.tenantPolicy = effectivePolicy;
+    ctx.toolErrorPolicy = await resolveToolErrorPolicy(ctx);
+    // Storage-backed registries need an async hydration
+    // step before the sync `list(tenantId)` call — they read persisted
+    // providers from `ProviderRegistryBinding` and instantiate each via
+    // its adapter factory. In-memory implementations (dev-echo,
+    // tests) leave `hydrate` undefined and this is a no-op.
+    if (ctx.bindings.providerRegistry.hydrate !== undefined) {
+        await ctx.bindings.providerRegistry.hydrate(ctx.input.tenantId);
+    }
+    // A pinned route narrows the policy to exactly that provider and model.
+    const routingPolicy = pinned === undefined
+        ? effectivePolicy
+        : mergeTenantPolicies(effectivePolicy, {
+            tenantId: ctx.input.tenantId,
+            providers: { allow: [pinned.providerId] },
+            models: { allow: [pinned.model] },
+        });
+    const routed = route({
+        capability,
+        providers: ctx.bindings.providerRegistry.list(ctx.input.tenantId),
+        ...(routingPolicy !== undefined && { tenantPolicy: routingPolicy }),
+        ...(ctx.input.agent.preferredProvider !== undefined && {
+            preferredProvider: ctx.input.agent.preferredProvider,
+        }),
+        ...(ctx.input.agent.preferredModel !== undefined && {
+            preferredModel: ctx.input.agent.preferredModel,
+        }),
+    });
+    if (routed.kind === 'err') {
+        throwAgentTurnFailure({
+            code: 'capability-routing-failed',
+            message: pinned === undefined
+                ? routed.error.message
+                : `The turn was routed to ${pinned.providerId}/${pinned.model}, which is no longer registered or allowed: ${routed.error.message}`,
+            cause: routed.error,
+        });
+    }
+    ctx.provider = routed.value.provider;
+    ctx.model = routed.value.model;
+    return {
+        providerId: routed.value.provider.metadata.id,
+        model: routed.value.model.name,
+        toolCount: ctx.tools.definitions.length,
+    };
+}
+/**
+ * The turn's approval rules: the agent's, held to the tenant's `hitl`
+ * policy. A policy that can't be evaluated fails the turn — running
+ * without it would skip the tenant's approvals.
+ */
+export async function resolveTurnHitlPolicy(ctx) {
+    let tenant;
+    if (ctx.bindings.policyRegistry !== undefined) {
+        try {
+            tenant = await ctx.bindings.policyRegistry.evaluate('hitl', { tenantId: ctx.input.tenantId });
+        }
+        catch (cause) {
+            throwAgentTurnFailure({
+                code: 'tenant-policy-unavailable',
+                message: `The tenant's hitl policy could not be applied: ${cause instanceof Error ? cause.message : String(cause)}`,
+                policyKind: 'hitl',
+            });
+        }
+    }
+    return resolveEffectiveHitlPolicy({ tenant, agent: ctx.input.agent });
+}
+/** The agent's `toolErrors`, capped by the tenant's `tool-errors` policy. */
+async function resolveToolErrorPolicy(ctx) {
+    const cap = ctx.bindings.policyRegistry !== undefined
+        ? await ctx.bindings.policyRegistry.evaluate('tool-errors', { tenantId: ctx.input.tenantId })
+        : undefined;
+    return effectiveToolErrorPolicy(ctx.input.agent.toolErrors, cap);
+}
+//# sourceMappingURL=turn-environment.js.map

package/dist/handlers/turn-environment.js.map

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

package/dist/hitl-policy.d.ts

@@ -0,0 +1,45 @@
+import { type HitlSpec } from '@kindgi/policy-contract';
+import type { Agent, ToolHitlMode, ToolHitlRule } from './types.js';
+export interface EffectiveHitlPolicy {
+    /**
+     * Session-turn count gate. Absent = no session gate.
+     * Merged from `agent.conversationPolicy.hitl.afterTurns` and
+     * `agent.conversationPolicy.hitlAfterTurns` (either fires;
+     * `hitl.afterTurns` wins when both are set).
+     */
+    readonly turn?: {
+        readonly afterTurns: number;
+    };
+    /**
+     * Tool-level policy. Absent = no tool gates (agents opt in
+     * explicitly). Same shape as `agent.conversationPolicy.hitl.tools`,
+     * with string overrides normalized to rules and tenant overrides
+     * applied; the per-tool default (from `Tool.mutating`) is applied at
+     * dispatch time.
+     */
+    readonly tools?: {
+        readonly default?: ToolHitlMode;
+        readonly overrides: ReadonlyMap<string, ToolHitlRule>;
+    };
+    /**
+     * The tenant's per-tool rules: a floor under the agent's gate for
+     * that tool. A tool's gate is the stricter of the two; tools the
+     * tenant names nothing for keep the agent's.
+     */
+    readonly toolFloors?: ReadonlyMap<string, ToolHitlRule>;
+    readonly defaultReviewerRole: 'standard' | 'senior' | 'admin';
+    /** Millisecond timeout used at enqueue time. */
+    readonly timeoutMs: number;
+    readonly onTimeout: 'auto-approve' | 'auto-reject' | '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 declare function resolveEffectiveHitlPolicy(input: {
+    readonly tenant: HitlSpec | undefined;
+    readonly agent: Agent;
+}): EffectiveHitlPolicy;
+//# sourceMappingURL=hitl-policy.d.ts.map

package/dist/hitl-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl-policy.d.ts","sourceRoot":"","sources":["../src/hitl-policy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,QAAQ,EAA4B,MAAM,yBAAyB,CAAC;AAElF,OAAO,KAAK,EAAE,KAAK,EAA0B,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5F,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;QAChC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;KACvD,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACxD,QAAQ,CAAC,mBAAmB,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC9D,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,aAAa,GAAG,UAAU,CAAC;CACjE;AAYD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB,GAAG,mBAAmB,CAsDtB"}