@kindgi/agents 0.0.0-bootstrap.0 → 0.1.1

package/src/index.ts

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+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';
+
+// ============ 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';

package/src/invoke.ts

@@ -0,0 +1,299 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Principal } from '@kindgi/authz';
+import type { KernelError, RunResult } from '@kindgi/runtime';
+import type { Result, RunId, TenantId } from '@kindgi/types';
+
+import { AGENT_TURN_FLOW } from './agent-turn-flow.js';
+import { DEFAULT_MAX_WALL_MS } from './handlers/constants.js';
+import type { TurnContext } from './handlers/context.js';
+import { AgentTurnFailure, type InvokeAgentError } from './handlers/errors.js';
+import { buildHandlers } from './handlers/index.js';
+import type { InvokeAgentBindings, InvokeAgentInput } from './handlers/public-types.js';
+import { rehydrateTurnContext } from './handlers/rehydrate.js';
+import type { AgentTurnResult } from './handlers/result-shape.js';
+import { projectRunResult } from './project-run-result.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 async function invokeAgent(
+  input: InvokeAgentInput,
+  bindings: InvokeAgentBindings,
+): Promise<Result<AgentTurnResult, InvokeAgentError>> {
+  const started = Date.now();
+  const maxWallMs = input.agent.budget?.maxWallMs ?? DEFAULT_MAX_WALL_MS;
+  const controller = new AbortController();
+  const ctx: TurnContext = {
+    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: Result<
+      RunResult<AgentTurnResult>,
+      KernelError
+    > = await bindings.runBinding.runGraph<AgentTurnResult>({
+      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);
+  }
+}
+
+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;
+}
+
+/**
+ * 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: TurnContext,
+  runId: RunId,
+  runBinding: NonNullable<InvokeAgentBindings['runBinding']>,
+): Promise<Result<AgentTurnResult, InvokeAgentError> | undefined> {
+  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 as unknown as string}: ${journal.error.message}`,
+      } as never,
+    };
+  }
+  try {
+    await rehydrateTurnContext(ctx, runId as unknown as string, journal.value);
+    return undefined;
+  } catch (cause) {
+    if (cause instanceof AgentTurnFailure) return { kind: 'err', error: cause.payload };
+    throw cause;
+  }
+}
+
+export async function resumeAgentTurn(
+  input: ResumeAgentTurnInput,
+  bindings: InvokeAgentBindings,
+): Promise<Result<AgentTurnResult, InvokeAgentError>> {
+  // 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 as unknown as string}: ${snapshotResult.error.message}`,
+      } as never,
+    };
+  }
+  const snapshot = snapshotResult.value;
+  if (snapshot === null) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'run-snapshot-missing',
+        message: `No run snapshot for run ${input.runId as unknown as string} — resume-context unavailable.`,
+      } as never,
+    };
+  }
+
+  // 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 as unknown as string) !== (input.agent.id as unknown as string) ||
+    snapshot.agentVersion !== input.agent.version
+  ) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'agent-version-mismatch',
+        message: `Snapshot pinned to ${snapshot.agentId as unknown as string}@${snapshot.agentVersion}; resume called with ${input.agent.id as unknown as string}@${input.agent.version as unknown as string}`,
+        expectedVersion: snapshot.agentVersion,
+        actualVersion: input.agent.version,
+      } as never,
+    };
+  }
+
+  // 3. Reconstruct the InvokeAgentInput envelope from the snapshot.
+  const reconstructedInput: InvokeAgentInput = {
+    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 as Principal,
+      }),
+    ...(snapshot.authz !== undefined &&
+      snapshot.authz !== null && {
+        authz: snapshot.authz as { readonly fgaApiUrl: string },
+      }),
+  };
+
+  // 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: TurnContext = {
+    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: Result<
+      RunResult<AgentTurnResult>,
+      KernelError
+    > = await bindings.runBinding.resumeRun<AgentTurnResult>({
+      tenantId: reconstructedInput.tenantId,
+      runId: input.runId,
+      flow: AGENT_TURN_FLOW,
+      handlers,
+    });
+    return await projectRunResult(runResult, ctx);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ============ public API re-exports ============
+// The public types live under `./handlers/`; index.ts re-exports them
+// from here.
+
+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';

package/src/migrations-dir.ts

@@ -0,0 +1,17 @@
+// 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: string = fileURLToPath(
+  new URL('../migrations/', import.meta.url),
+);

package/src/project-run-result.ts

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { KernelError, RunResult } from '@kindgi/runtime';
+import type { Result } from '@kindgi/types';
+
+import type { TurnContext } from './handlers/context.js';
+import { parseFailureMessage } from './handlers/errors.js';
+import type { InvokeAgentError } from './handlers/errors.js';
+import type { AgentTurnResult } from './handlers/result-shape.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: Result<RunResult<AgentTurnResult>, KernelError>,
+  ctx: TurnContext,
+): Promise<Result<AgentTurnResult, InvokeAgentError>> {
+  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: '',
+        } as never,
+        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: InvokeAgentError = {
+      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,
+    },
+  };
+}