@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/src/handlers/tool-errors.ts

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * 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 { TOOL_ERROR_KINDS, type ToolErrorKind, type ToolErrorsSpec } 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: Required<ToolErrorsSpec> = {
+  maxRetries: 1,
+  retryOn: ['invalid-arguments', 'unknown-tool'],
+};
+
+/** 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 function effectiveToolErrorPolicy(
+  agent: ToolErrorsSpec | undefined,
+  tenantCap: ToolErrorsSpec | undefined,
+): ToolErrorPolicy {
+  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: {
+  readonly code: string;
+  readonly cause?: unknown;
+}): ToolErrorKind {
+  if (error.code === 'unresolved-tool') return 'unknown-tool';
+  const inner = (error.cause as { readonly code?: unknown } | undefined)?.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';
+
+/** 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;
+}
+
+const INSTRUCTIONS: Readonly<Record<ToolErrorKind, string>> = {
+  '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: ToolErrorKind,
+  message: string,
+  issues: readonly unknown[] | undefined,
+): ToolErrorResult {
+  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: readonly ModelMessage[]): number {
+  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: ModelMessage): boolean {
+  if (m.role !== 'tool') return false;
+  try {
+    return (JSON.parse(m.content) as { readonly kindgi?: unknown }).kindgi === RETRY_MARKER;
+  } catch {
+    return false;
+  }
+}

package/src/handlers/tool-hitl.ts

@@ -0,0 +1,126 @@
+// 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';
+
+import type { Tool } from '@kindgi/tools';
+
+import type { Agent, ToolHitlMode, ToolHitlRule } from '../types.js';
+
+export interface ResolvedToolHitl {
+  readonly mode: ToolHitlMode;
+  readonly requiredRole: 'standard' | 'senior' | 'admin';
+}
+
+export function resolveToolHitl(agent: Agent, tool: Tool): ResolvedToolHitl {
+  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 as unknown as string];
+  if (rawOverride !== undefined) {
+    const rule: ToolHitlRule =
+      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: ToolHitlMode = 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: unknown): string {
+  return createHash('sha256').update(canonicalStringify(args)).digest('hex').slice(0, 40);
+}
+
+function canonicalStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalStringify).join(',')}]`;
+  const entries = Object.entries(value as Record<string, unknown>).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: {
+  readonly runId: string;
+  readonly callId: string;
+  readonly argsHash: string;
+}): string {
+  return createHash('sha256')
+    .update(`tool-call:${input.runId}:${input.callId}:${input.argsHash}`)
+    .digest('hex')
+    .slice(0, 40);
+}
+
+/**
+ * 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 function cacheKeyFor(key: ToolDecisionCacheKey): string {
+  return `${key.toolId}:${key.argsHash}`;
+}

package/src/handlers/turn-environment.ts

@@ -0,0 +1,191 @@
+// 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 type { TenantPolicy } from '@kindgi/capabilities';
+import type { HitlSpec, ToolErrorsSpec } from '@kindgi/policy-contract';
+
+import type { ConversationClosedError } from '../errors.js';
+import { resolveGuardrails } from '../guardrails-gate.js';
+import { type EffectiveHitlPolicy, resolveEffectiveHitlPolicy } from '../hitl-policy.js';
+import { mergeTenantPolicies } from '../tenant-policy.js';
+import type { Conversation } from '../types.js';
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+import { resolveTurnTools } from './resolve-tools.js';
+import { type ToolErrorPolicy, effectiveToolErrorPolicy } from './tool-errors.js';
+
+/** The conversation the turn runs in: open, and opened with this agent version. */
+export async function loadTurnConversation(ctx: TurnContext): Promise<Conversation> {
+  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: ConversationClosedError = {
+      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;
+}
+
+/** 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 async function resolveTurnEnvironment(
+  ctx: TurnContext,
+  pinned?: PinnedRoute,
+): Promise<PinnedRoute & { readonly toolCount: number }> {
+  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<
+          { readonly tenantId: typeof ctx.input.tenantId },
+          TenantPolicy | undefined
+        >('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: TurnContext): Promise<EffectiveHitlPolicy> {
+  let tenant: HitlSpec | undefined;
+  if (ctx.bindings.policyRegistry !== undefined) {
+    try {
+      tenant = await ctx.bindings.policyRegistry.evaluate<
+        { readonly tenantId: typeof ctx.input.tenantId },
+        HitlSpec | undefined
+      >('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: TurnContext): Promise<ToolErrorPolicy> {
+  const cap =
+    ctx.bindings.policyRegistry !== undefined
+      ? await ctx.bindings.policyRegistry.evaluate<
+          { readonly tenantId: typeof ctx.input.tenantId },
+          ToolErrorsSpec | undefined
+        >('tool-errors', { tenantId: ctx.input.tenantId })
+      : undefined;
+  return effectiveToolErrorPolicy(ctx.input.agent.toolErrors, cap);
+}

package/src/hitl-policy.ts

@@ -0,0 +1,128 @@
+// 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 { type HitlSpec, higherRole, toolHitlRule } from '@kindgi/policy-contract';
+
+import type { Agent, ConversationHitlPolicy, 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';
+}
+
+/**
+ * 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' as const,
+  timeoutMs: 24 * 60 * 60 * 1000,
+  onTimeout: 'escalate' as const,
+} as const;
+
+/**
+ * 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: {
+  readonly tenant: HitlSpec | undefined;
+  readonly agent: Agent;
+}): EffectiveHitlPolicy {
+  const agentHitl: ConversationHitlPolicy | undefined = input.agent.conversationPolicy?.hitl;
+  const legacyAfterTurns = input.agent.conversationPolicy?.hitlAfterTurns;
+  const agentAfterTurns = agentHitl?.afterTurns ?? legacyAfterTurns;
+
+  const merged: {
+    turn?: { afterTurns: number };
+    tools?: {
+      default?: ToolHitlMode;
+      overrides: ReadonlyMap<string, ToolHitlRule>;
+    };
+    toolFloors?: ReadonlyMap<string, ToolHitlRule>;
+    defaultReviewerRole: 'standard' | 'senior' | 'admin';
+    timeoutMs: number;
+    onTimeout: 'auto-approve' | 'auto-reject' | 'escalate';
+  } = {
+    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<string, ToolHitlRule>();
+    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 as EffectiveHitlPolicy;
+}