@irogane/kaji 0.2.0-beta.11 → 0.3.0

package/README.md

@@ -1,598 +1,159 @@
-# Kaji (TypeScript)
+# Kaji
 
-`kaji` is an embeddable SDK for building agents in TypeScript: import
-the pieces you need and compose them. The core is infra-free (no database,
-server, or environment configured). It mirrors the runtime core of the Python
-`kaji` SDK.
+Kaji is an embedded execution layer for safely turning agent-requested
+application actions into real state changes.
 
-<!-- canonical-status-links:start -->
-> Canonical documentation: https://github.com/enkyuan/alloy/blob/main/docs/kaji/README.md
-> Release status and evidence: https://github.com/enkyuan/alloy/blob/main/kaji/RELEASE_MATRIX.md
-<!-- canonical-status-links:end -->
-
-OpenAI is the sole beta-supported primary provider. Anthropic, Gemini, Kimi,
-and OpenRouter are opt-in experimental/WIP adapters with no beta compatibility
-or publication-proof commitment. Use `MockProvider` as the deterministic
-local/test default.
-
-See [**Kaji MVP**](https://github.com/enkyuan/alloy/blob/main/docs/MVP.md) for
-the full five-step developer path and scope definition.
-
-## Install
-
-```bash
-npm install @irogane/kaji@0.2.0-beta.11 zod openai        # OpenAI
-# or
-npm install @irogane/kaji@0.2.0-beta.11 zod @anthropic-ai/sdk  # Anthropic (experimental/WIP)
-# or: bun add @irogane/kaji@0.2.0-beta.11 zod openai
-```
-
-`zod` is a required peer dependency (Zod 4). `openai` and `@anthropic-ai/sdk`
-are optional peers -- install only the one you use. Anthropic is not in the
-beta support tier. The package metadata declares Node `22.x || 24.x`, but the
-protected beta onboarding evidence is deliberately narrower: it proves npm and
-Bun on GitHub-hosted Linux/x64, with Node 22 on `ubuntu-22.04` and Node 24 on
-`ubuntu-24.04`. It makes no broader runtime or platform claim, including for
-macOS/arm64, Windows, or fully offline dependency installation. The protected
-compiler cells use TypeScript 5.7.3 and 6.0.3.
-
-## Quick start
-
-First prove a text-only turn without credentials. No principal is required
-because this runtime has no enabled tools. Save this example as
-`quickstart.mts` so top-level await runs as ESM, including from npm's default
-CommonJS project:
-
-```ts
-import { AgentBuilder } from "@irogane/kaji";
-import { MockProvider } from "@irogane/kaji/testing";
-
-const runtime = new AgentBuilder().provider(new MockProvider({ reply: "hello" })).build();
-const result = await runtime.turn("Say hello.");
-console.log(result.text, result.accounting);
+```text
+agent / framework / direct caller
+            ↓
+           Kaji
+            ↓
+   application capability
+            ↓
+ application / external system
 ```
 
-## Privileged event journal and disposal
+Your application already has functions like `refundPayment()` or
+`cancelBooking()`. When something outside your direct control — an
+agent, an automation, an MCP tool call — can trigger one of those
+functions, it needs caller identity, input validation, authorization,
+approval, and protection against duplicate or ambiguous side effects.
+Kaji standardizes that boundary once, inside your application, instead
+of once per caller.
 
-> **Security boundary:** `TurnResult.events` and `AgentRuntime.history()` are a
-> privileged full-fidelity journal. They can contain user prompts,
-> provider-derived text and deltas, tool arguments, tool results, and arbitrary
-> metadata. They are not redaction-safe; never log, attach, or export them
-> wholesale.
+Kaji is a TypeScript library with zero runtime dependencies. It runs in
+your process — no server, database, or control plane.
 
-`MetricsSink` and `TraceSink` are best-effort timing and correlation surfaces,
-not complete business or audit records. Sink failures are swallowed so
-observability cannot change turn behavior. Traces still contain access-controlled
-correlation identifiers even though they omit full event payloads.
-
-Failed turns throw: failed turns have no `TurnResult` and therefore no
-`TurnResult.events` or successful-turn `TurnAccounting` aggregate. Applications
-that need failure evidence must choose a preselected session ID, retain the
-caught error separately for live control flow, page history with an
-exclusive `afterSequence` cursor until an empty page, and reduce to an allowlist
-before export; generic provider failures have no durable recovery code today. Use the
-caught typed provider error and `normalizeProviderError()` where applicable.
-Always page until an empty page; a short page is not proof of exhaustion.
+## Install
 
-```ts
-import type { AgentRuntime, StoredKajiEvent } from "@irogane/kaji";
-
-async function pageHistory(runtime: AgentRuntime, sessionId: string, limit = 128) {
-  const events: StoredKajiEvent[] = [];
-  let afterSequence = 0;
-  for (;;) {
-    const page = await runtime.history(sessionId, { afterSequence, limit });
-    if (page.length === 0) return events;
-    const nextSequence = page.at(-1)!.sequence;
-    if (nextSequence <= afterSequence) throw new Error("history cursor did not advance");
-    events.push(...page);
-    afterSequence = nextSequence;
-  }
-}
-
-const SAFE_FIELDS = [
-  "tool_name",
-  "tool_call_id",
-  "error_code",
-  "phase",
-  "retryable",
-  "outcome",
-  "reason_code",
-  "recovery_code",
-  "doc_url",
-] as const;
-
-function safeJournalEvidence(event: StoredKajiEvent): Record<string, unknown> {
-  const safe: Record<string, unknown> = { sequence: event.sequence, type: event.type };
-  if (event.turn_id !== undefined) safe.turn_id = event.turn_id;
-  for (const field of SAFE_FIELDS) {
-    const value = Reflect.get(event, field);
-    if (value !== undefined) safe[field] = value;
-  }
-  return safe; // never content, delta, tool_args, result, metadata, or raw session_id
-}
-
-const sessionId = crypto.randomUUID();
-let failure: { error: unknown } | undefined;
-try {
-  await runtime.turn("Investigate the failure.", { sessionId });
-} catch (error) {
-  failure = { error }; // retain separately; never add this value to safe evidence
-}
-
-if (failure !== undefined) {
-  stopIngress(sessionId);
-  await runtime.drainTools(10_000);
-  await runtime.drainProviders(10_000);
-  try {
-    const privilegedHistory = await pageHistory(runtime, sessionId);
-    const exportableEvidence = privilegedHistory.map(safeJournalEvidence);
-    sendToYourIncidentStore(exportableEvidence);
-  } catch (evidenceError) {
-    handleEvidenceExportError(evidenceError); // report separately; original failure stays authoritative
-  } finally {
-    await runtime.purgeSession(sessionId);
-  }
-  handleOriginalError(failure.error); // cleanup finished; preserve original control flow
-}
-```
+Kaji v0 is not yet published to npm. Publishing an install command now
+would resolve to the previously published agent SDK under this name
+(0.2.0-beta.11), so the command is enabled only when the v0 artifact
+is published.
 
-Before disposal, stop ingress for the named session so another caller cannot
-race the drain-to-purge interval. On a live runtime, drain tools and providers,
-page and reduce any required evidence, then call `purgeSession(sessionId)` while
-leaving other sessions running. For whole-runtime shutdown, `close()` may run
-first to reject future turn APIs; history and purge remain callable afterward.
-`close()` does not delete retained history and does not cancel already-active
-work.
-
-This lifecycle is identical to Python's supported in-memory path. The bounded
-store never evicts a retained session implicitly: a full store raises
-`EventStoreCapacityError` until the host explicitly purges one. Runtime purge
-closes its old subscribers, removes the event and ID indexes, and clears every
-runtime owner sharing the store; a standalone raw listener must be closed by
-its caller. Reset cursors to `0` before reuse; the next generation begins at
-sequence `1`.
-
-`PurgeableEventStore.purgeSession(sessionId)` is the public one-argument
-store-only capability, detected by `supportsSessionPurge()`. Runtime purge also
-requires Kaji's internal opaque coordinated capability, so a custom store that
-implements only the public method fails closed at the runtime boundary. Direct
-store operations and new owners remain fenced throughout purge. Split delivery
-is unsupported because its outbox cannot cross a reused generation.
-
-TypeScript's embedded defaults are bounded, in-memory, and process-local. This
-beta ships no persistent event store or distributed coordinator and does not
-release-certify host implementations; durability, deletion, and cross-process
-correctness are host responsibilities. `purgeSession()` removes SDK-owned
-retained indexes and caches but cannot promise VM string zeroization or erase
-copies already sent to logs, sinks, providers, custom stores, crash dumps, or
-caller-owned objects.
-
-A custom `ToolIdempotencyLedger` must implement optional `releaseSettled()` to
-participate in purge. The event store and SDK caches are already cleared before
-host ledger cleanup is awaited. If that cleanup rejects, deletion cannot be
-rolled back; repair the host ledger and retry the named purge. If it never
-settles, the strong `cleanup_pending` tombstone keeps turns, direct store
-operations, subscriptions, and new owners fenced. A later runtime purge retries
-cleanup without repeating physical deletion. Kaji cannot force hostile
-in-process host code to settle. `TurnAccounting` remains TypeScript-only and is
-separate from the cross-SDK purge contract.
-
-Then set an API key and add a risk-classified tool with explicit caller
-identity, deadline, and cancellation:
-
-```bash
-export OPENAI_API_KEY=sk-...
-# Experimental/WIP alternative: export ANTHROPIC_API_KEY=sk-ant-...
-```
+## Minimal example
 
 ```ts
-import { AgentBuilder, OpenAIProvider, Integration, deadlineAfter, tool } from "@irogane/kaji";
+import { capability, createKaji, knownFailure, memoryStore } from "@irogane/kaji";
 import { z } from "zod";
 
-class WeatherIntegration extends Integration {
-  readonly namespace = "weather";
-
-  readonly getWeather = tool(
-    {
-      description: "Return weather for a city.",
-      parameters: z.object({ city: z.string() }),
-      risk: "read",
-    },
-    async (args, _context) => ({ city: args.city, tempF: 68 }),
-  );
-}
-
-const runtime = new AgentBuilder()
-  .provider(new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }))
-  .integration(new WeatherIntegration())
-  .systemPrompt("You are a weather assistant.")
-  .build();
-
-const result = await runtime.turn("Weather in Seattle?", {
-  context: {
-    principalId: "weather-app",
-    deadlineAtMs: deadlineAfter(30_000),
-  },
+const RefundInput = z.object({
+  paymentId: z.string().min(1),
+  amount: z.number().positive(),
 });
-console.log(result.text, result.accounting);
-```
-
-Swap `OpenAIProvider` for `AnthropicProvider` (and `OPENAI_API_KEY` for
-`ANTHROPIC_API_KEY`) to use the experimental/WIP Anthropic adapter.
 
-`AgentBuilder` wires a scoped `ToolRegistry` into `ToolPlanner` so integration
-tools are both visible to the model and executable.
+const refund = capability({
+  name: "payments.refund",
+  input: RefundInput,
 
-### GitHub integration
-
-The experimental TypeScript package subpath exposes a fixed-origin GitHub
-integration without copying its source into your application. For an
-investigation agent, opt into read-only exposure so the two mutation tools are
-not registered or sent to the model.
+  authorize: async ({ principalId, input }) => {
+    return canRefund(principalId, input.paymentId);
+  },
 
-```ts
-import { AgentBuilder, OpenAIProvider, deadlineAfter } from "@irogane/kaji";
-import { createGithubIntegration } from "@irogane/kaji/integrations/github";
-
-const principalId = "github-investigator";
-const github = createGithubIntegration({
-  repositories: ["owner/repo"],
-  toolExposure: "read-only",
-  tokenFor: async (context) => {
-    if (context.signal.aborted) throw context.signal.reason;
-    if (context.principalId !== principalId) throw new Error("GitHub credential unavailable");
-    const token = process.env.GITHUB_TOKEN;
-    if (!token) throw new Error("GITHUB_TOKEN is required");
-    return token;
+  approval: ({ input }) => input.amount >= 500,
+
+  execute: async (input, context) => {
+    try {
+      return await payments.refund({
+        ...input,
+        idempotencyKey: context.idempotencyKey,
+        signal: context.signal,
+      });
+    } catch (cause) {
+      if (isDefinitiveProviderRejection(cause)) throw knownFailure(cause);
+      throw cause; // anything else stays unknown: the side effect may have committed
+    }
   },
 });
 
-const runtime = new AgentBuilder()
-  .provider(new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }))
-  .integration(github)
-  .defaultContext({ principalId })
-  .systemPrompt("Use GitHub evidence from owner/repo and cite immutable refs.")
-  .build();
-
-const result = await runtime.turn("Inspect the latest failed checks.", {
-  context: { deadlineAtMs: deadlineAfter(30_000) },
+const kaji = createKaji({
+  store: memoryStore(),
+  approve: async () => ({ approved: true }),
 });
-console.log(result.text);
-github.close();
-```
-
-`toolExposure` controls which tools reach the model; it does not reduce token
-permissions. Keep the repository allowlist narrow and use a fine-grained token
-with only the read permissions needed by the selected tools. The callback is
-lazy, receives the tool execution context, and returns the raw token; Kaji
-validates it and adds the `Bearer` header. `AgentBuilder` does not own the
-integration, so close it only after active tool work has settled. See the
-[GitHub integration guide](https://github.com/enkyuan/alloy/blob/main/apps/docs/content/integrations/github.mdx)
-for the 15-tool catalog, mutation policy, limits, and unsupported surfaces.
-
-### Gmail integration (experimental)
-
-Gmail ships as an **experimental** catalog entry. Unlike `github`, it has no
-`@irogane/kaji/integrations/gmail` package subpath. You copy its source into your
-project and own it:
 
-```bash
-npm exec -- kaji add gmail --allow-experimental --out ./integrations/gmail
-```
-
-The copied `index.ts` exports `createGmailIntegration({ tokenFor })`, where
-`tokenFor` is a lazy callback that returns the OAuth access token for the
-`gmail.readonly` and `gmail.send` scopes. Wire it into `AgentBuilder` exactly
-like the GitHub integration:
-
-```ts
-import { createGmailIntegration } from "./integrations/gmail";
-
-const gmail = createGmailIntegration({
-  tokenFor: async (context) => {
-    if (context.signal.aborted) throw context.signal.reason;
-    const token = process.env.GMAIL_ACCESS_TOKEN;
-    if (!token) throw new Error("GMAIL_ACCESS_TOKEN is required");
-    return token;
-  },
+const result = await kaji.execute(refund, {
+  input: { paymentId: "pay_123", amount: 750 },
+  principalId: "user_123",
+  idempotencyKey: "refund_req_123",
 });
-// ...builder.integration(gmail)... then gmail.close() after tool work settles.
-```
-
-It exposes three tools: `list_messages` (with `page_token`/`next_page_token`
-pagination), `get_message` (first `text/plain` body, decoded and bounded), and
-`send_message`, an external-effect write whose ambiguous failures surface the
-`gmail_mutation_unknown` recovery reason rather than risking a silent double
-send. The client is fixed to `https://gmail.googleapis.com`, rejects redirects,
-and bounds every response. See the
-[Gmail integration guide](https://github.com/enkyuan/alloy/blob/main/apps/docs/content/integrations/index.mdx)
-for scopes, the `kaji connect gmail` grant flow, and limits.
-
-`deadlineAtMs` is an absolute Unix epoch value; use `deadlineAfter()` when the
-caller has a duration. An earlier caller deadline can tighten, but never extend,
-the configured 120-second whole-turn default covering queue wait, provider open
-and streaming, approval, and tool work. Cooperative provider shutdown may use
-the additional configured cancellation grace.
-
-Catch a Kaji `ProviderError`, then call `normalizeProviderError(error)` for the
-redaction-safe `type`, `code`, `service`, `action`, `status`, and `retryable`
-fields. The normalizer accepts Kaji provider errors, not arbitrary vendor
-exceptions.
-
-See [`docs/kaji/production-beta.md`](https://github.com/enkyuan/alloy/blob/main/docs/kaji/production-beta.md) for
-the installed-package version of both first-success examples and exact default
-limits. Operating details are in
-[`concurrency-and-ordering.md`](https://github.com/enkyuan/alloy/blob/main/docs/kaji/concurrency-and-ordering.md),
-[`tool-contracts.md`](https://github.com/enkyuan/alloy/blob/main/docs/kaji/tool-contracts.md), and
-[`troubleshooting.md`](https://github.com/enkyuan/alloy/blob/main/docs/kaji/troubleshooting.md).
-Call `runtime.effectiveLimits()` to inspect the immutable
-`EffectiveRuntimeLimits` resolved for one runtime.
-
-Runtimes that share the same `EventStore` also share a default per-store turn
-coordinator within the current process, so same-session turns serialize even
-when separate builders create the runtimes. Different stores do not block one
-another. This is not a distributed lock: multi-process deployments must inject
-a `SessionTurnCoordinator` backed by shared infrastructure.
-
-## Prove it with a model
-
-OpenAI with `gpt-5.4-mini` is the recommended first live check because it is
-cost-effective and exercises the SDK's Chat Completions tool path.
-
-```bash
-bun --filter kaji test:quickstart
-OPENAI_API_KEY=... KAJI_LIVE_OPENAI_MODEL=gpt-5.4-mini \
-  bun --filter kaji test:integration tests/integration/openai-tools.test.ts
 ```
 
-The live test registers a read-only probe tool, verifies the model calls it,
-and verifies the runtime emits final assistant text using the tool result.
-Keyed OpenAI proof requires protected tool loops in both SDKs on one exact
-commit. A missing `OPENAI_API_KEY` blocks that release evidence. Anthropic,
-Kimi, Gemini, and OpenRouter are experimental/WIP; the latter three are
-OpenAI-compatible factories rather than native provider implementations.
+`canRefund()` and `payments.refund()` are your own application code.
+Kaji never sees your domain logic — it only governs when `execute` runs.
 
-For the cross-SDK release gate, run from the repository root:
+## Why Kaji
 
-```bash
-uv run --project kaji/packages/py python kaji/scripts/beta_release_check.py
-```
+- **Explicit identity.** Every execution requires a caller-supplied
+  `principalId`. Kaji never infers one from process state.
+- **Validation before anything else.** Invalid input never reaches
+  `authorize`, `approval`, or `execute`.
+- **Duplicate suppression.** A caller-supplied `idempotencyKey` claims
+  one intended operation; a repeated request with the same key replays
+  the recorded result instead of running `execute` again.
+- **Fail-closed approval.** A capability declares when approval is
+  required; the host application supplies how a decision is obtained;
+  a missing, rejected, or failed decision prevents execution.
+- **Explicit failure semantics.** `succeeded`, `failed`, and `unknown`
+  are distinct outcomes — see below.
 
-This wraps Python unit/static checks, Python wheel smoke, TS unit/static/build
-checks, TS package smoke, mandatory pinned ast-grep boundary checks, and no-key
-live-gate hygiene. The ast-grep step guards the Python SDK/service boundary, core package dependency direction, removed tool-model imports, TypeScript optional provider imports, and cancellation error shape.
+## Execution outcomes
 
-For the live-gate credential modes specifically:
+`kaji.execute()` resolves with an explicit `status` for every governed
+execution; it does not throw for expected outcomes.
 
-```bash
-uv run --project kaji/packages/py python kaji/scripts/verify_openai_loop.py
-KAJI_REQUIRE_LIVE_KEYS=1 uv run --project kaji/packages/py python kaji/scripts/verify_openai_loop.py
-```
+```text
+execute() resolves
+  → succeeded
 
-Without `OPENAI_API_KEY`, the first command proves missing-key hygiene only.
-It is not provider evidence. The protected release mode requires
-`OPENAI_API_KEY` and fails when it is absent.
+execute() throws knownFailure(cause)
+  → failed
 
-```bash
-OPENAI_API_KEY=... KAJI_LIVE_OPENAI_MODEL=gpt-5.4-mini uv run --project kaji/packages/py python kaji/scripts/verify_openai_loop.py
+execute() throws or rejects with anything else
+  → unknown
 ```
 
-`KAJI_RUN_KEYED_LIVE=1` is the fail-closed two-cell OpenAI proof (Python and
-TypeScript). It requires the OpenAI key, frozen artifact set, and exact
-40-character release commit:
+`unknown` means the side effect may have committed, but Kaji cannot
+prove the final result — a thrown error, a timeout, or a cancellation
+after `execute()` has started all settle `unknown`, never `failed`.
+Kaji never infers a known failure from an error's class, message, or
+status code; only application code that can prove no side effect
+committed may throw `knownFailure()`. See the
+[execution outcomes guide](https://kaji.build/docs/concepts/outcomes)
+for the full model.
 
-```bash
-OPENAI_API_KEY=... \
-KAJI_RELEASE_ARTIFACTS_DIR="$PWD/.artifacts/kaji-release" \
-KAJI_RELEASE_COMMIT=<40-character-commit> KAJI_RUN_KEYED_LIVE=1 \
-uv run --project kaji/packages/py python kaji/scripts/beta_release_check.py
-```
+## memoryStore()
 
-The protected rehearsal and publish workflows are authoritative release
-evidence. Their required-reviewer environments are purpose-specific:
-`kaji-onboarding` protects deterministic TypeScript onboarding,
-`kaji-release` protects keyed OpenAI proof, and `kaji-publish` protects
-publisher identity and the sole npm write. The single-provider command above
-is only a local paid smoke test.
-
-## Stability tiers
-
-- **Stable core:** `AgentBuilder`, `AgentRuntime`, `ToolRegistry`,
-  `ToolPlanner`, session replay, the OpenAI provider, and the in-memory
-  event store/committer form the supported embedded-agent surface.
-- **Experimental providers:** Anthropic, Gemini, Kimi, and OpenRouter remain
-  opt-in WIP surfaces without a beta compatibility or publication-proof
-  commitment.
-- **Experimental Python-only:** Redis realtime/history, voice/TTS,
-  `DocumentRAG`, native Gemini/Kimi providers, tool retrieval, and text/voice
-  modalities exist in Python but are not production-hardened.
-- **TS not ported:** Redis realtime, voice/TTS, and RAG are not implemented in
-  TypeScript. TS Gemini/Kimi remain OpenAI-compatible factories rather than
-  native provider implementations.
-
-See https://github.com/enkyuan/alloy/blob/main/kaji/RELEASE_MATRIX.md for the
-cross-SDK release matrix and the exact distinction between stable core,
-experimental Python-only surfaces, and TypeScript surfaces that are not ported.
-
-The beta promise is the core agent loop. Redis realtime/history, voice/TTS,
-`DocumentRAG`, native Gemini/Kimi, and tool retrieval remain outside the beta
-gate until the promotion criteria in `kaji/RELEASE_MATRIX.md` are met.
-Gemini and Kimi are OpenAI-compatible factories in TypeScript, not native
-provider implementations.
-
-## Approval handler
-
-Tools whose risk exceeds your policy threshold pause for approval before the
-runtime executes them. All hosts use `TypedApprovalHandler` and return an
-`ApprovalDecision`. `cliApprovalHandler` is a typed dev/REPL implementation
-that prints the tool name, risk, and arguments, then reads `y` / `N` on stdin:
+`createKaji()` needs an `ExecutionStore`. `memoryStore()` is the
+built-in reference implementation:
 
 ```ts
-import { AgentBuilder, cliApprovalHandler, openai } from "@irogane/kaji";
-
-const agent = new AgentBuilder()
-  .provider(openai())
-  .approvalHandler(cliApprovalHandler({ label: "agent-a" }))
-  .build();
-```
+import { memoryStore } from "@irogane/kaji";
 
-Custom hosts implement `TypedApprovalHandler.request(call, context)` and return
-an `ApprovalDecision`, for example
-`{ granted: true, code: "approved" }` or a rejected decision with an explicit
-code and safe reason. See
-[`tool-contracts.md`](https://github.com/enkyuan/alloy/blob/main/docs/kaji/tool-contracts.md) for the lifecycle.
-
-`EventApprovalHandler` requires a non-empty turn ID and accepts a decision only
-when `turn_id`, `tool_call_id`, and `tool_name` all match the pending request.
-Unscoped or stale backlog decisions are ignored.
-
-## CLI
-
-```
-kaji --help                            # list subcommands
-kaji add <integration>                 # copy an integration into your project
-kaji add <integration> --allow-experimental  # explicitly copy a non-beta template
-kaji init [path] --provider mock --yes # no-key TypeScript scaffold
-kaji list-integrations                 # enumerate the registry catalog
-kaji replay <session.jsonl>            # render a stored JSONL session log
+const kaji = createKaji({ store: memoryStore() });
 ```
 
-This is the embedded `kaji` CLI. The standalone cross-language
-`@irogane/kaji/cli` scaffold has its own `--lang`/`--provider` options; Python's `kaji`
-package also exposes additional Python-only maintenance commands.
-Generated projects pin dotenvx and load `.env` from their `start` script after
-you copy `.env.example` to `.env`.
+`memoryStore()` is process-local and in-memory. It is useful for local
+development, tests, and examples — it is not durable and does not
+coordinate across processes or instances. A production deployment needs
+an `ExecutionStore` backed by durable, atomic storage; see
+[custom store](https://kaji.build/docs/guides/custom-store).
 
-`echo` and `github` are beta catalog entries. `--allow-experimental` is
-required only for catalog entries still marked experimental.
+## What Kaji is not
 
-## Global tool registry (advanced)
-
-For simple setups you can use the process-level registry:
-
-```ts
-import { executeTool, registerTool, toolSpecFromSchema } from "@irogane/kaji";
-import { z } from "zod";
-
-registerTool(
-  toolSpecFromSchema("get_weather", "Look up weather", z.object({ city: z.string() }), "read"),
-  async (args, context) => ({
-    principalId: context.principalId,
-    city: args.city,
-    tempF: 68,
-  }),
-);
-
-const result = await executeTool(
-  "get_weather",
-  { city: "Seattle" },
-  {
-    principalId: "user-1",
-    sessionId: "session-1",
-    turnId: "turn-1",
-    requestId: "request-1",
-    traceId: "trace-1",
-    toolCallId: "call-1",
-    idempotencyKey: "session-1:call-1",
-    signal: new AbortController().signal,
-    metadata: {},
-  },
-);
-```
-
-## What's exported
-
-| Export                                                                                      | What it is                                                                                                                                 |
-| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `EventType`, `KajiEvent`                                                                    | Event discriminants and Zod-validated event union                                                                                          |
-| `EventStore`, `InMemoryEventStore`                                                          | Event log that is append-only while retained; explicit session purge is an optional lifecycle capability                                   |
-| `EventBus`                                                                                  | In-memory pub/sub per session                                                                                                              |
-| `replaySession`, `SessionManager`, session store types                                      | Session projection and management                                                                                                          |
-| `registerTool`, `ToolRegistry`, `toolSpecFromSchema`, `executeTool`, `listToolSpecs`        | Tool registry (global + scoped)                                                                                                            |
-| `ToolPolicy`, `ToolPlanner`                                                                 | Allow/deny and approval-gated execution                                                                                                    |
-| `TypedApprovalHandler`, `cliApprovalHandler`, `EventApprovalHandler`, `AutoApprovalHandler` | Structured approval handlers: stdin, event-driven (publishes `TOOL_APPROVAL_REQUESTED` for a host UI to answer), and auto-decide by policy |
-| `OpenAIProvider`, `AnthropicProvider`                                                       | LLM providers; Anthropic is experimental/WIP                                                                                               |
-| `normalizeProviderError`, `NormalizedProviderError`                                         | Redaction-safe semantic classification for Kaji provider errors                                                                            |
-| `openai`, `anthropic`, `kimi`, `gemini`, `openrouter`                                       | One-line provider factories; only OpenAI is beta-supported                                                                                 |
-| `getProvider`, `registerProvider`                                                           | Name-keyed provider registry, for host code that resolves a provider by config string                                                      |
-| `generateText`, `streamText`                                                                | One-shot provider calls without a full `AgentRuntime`: a single request/response or stream, no event log                                   |
-| `AgentRuntime`, `AgentBuilder`, `CancellationToken`                                         | ReAct loop and fluent builder                                                                                                              |
-| `EffectiveRuntimeLimits`                                                                    | Immutable values returned by `AgentRuntime.effectiveLimits()` after overrides                                                              |
-| `Integration`, `tool`                                                                       | Integration helper for scoped tools                                                                                                        |
-| `EnvSecretSource`                                                                           | Reads a named secret from `process.env`; the default `SecretSource` implementation                                                         |
-
-Events use snake_case field names (`session_id`, `tool_name`) as the wire format
-shared with the Python SDK.
-
-## Python vs TypeScript parity
-
-| Feature                               | Python SDK             | TS SDK                                              |
-| ------------------------------------- | ---------------------- | --------------------------------------------------- |
-| Event-sourced runtime                 | Yes                    | Yes                                                 |
-| Tool registry + planner + policy      | Yes                    | Yes                                                 |
-| `AgentBuilder` + integrations         | Yes                    | Yes                                                 |
-| OpenAI provider                       | Yes                    | Yes                                                 |
-| Anthropic provider (experimental/WIP) | Yes                    | Yes                                                 |
-| Kimi / Gemini providers               | Yes (experimental/WIP) | Yes (experimental/WIP, OpenAI-compatible factories) |
-| Document RAG / vector store           | Yes (non-MVP)          | No                                                  |
-| Tool retriever                        | Yes (non-MVP)          | No                                                  |
-| Text modality adapter                 | Yes (non-MVP)          | No                                                  |
-| Voice / TTS                           | Yes (non-MVP)          | No                                                  |
-| Redis realtime bus                    | Yes (non-MVP)          | No (in-memory only)                                 |
-| CLI scaffold                          | Yes                    | Yes                                                 |
-
-## Testing without API keys
-
-Unit and integration tests mock the provider HTTP client -- no keys needed for
-the default test suite:
-
-```bash
-bun run test
-```
-
-Live provider tests are opt-in and skip automatically when keys are absent.
-OpenAI is the beta-supported live path; the Anthropic command remains a WIP
-adapter check:
-
-```bash
-OPENAI_API_KEY=... bun run test:integration
-OPENAI_API_KEY=... KAJI_LIVE_OPENAI_MODEL=gpt-5.4-mini \
-  bun run test:integration tests/integration/openai-tools.test.ts
-ANTHROPIC_API_KEY=... bun run test:integration
-```
-
-`MockProvider` is a deterministic stub that exercises the full tool loop. It is
-available from `@irogane/kaji/testing` for unit tests, not from the main package
-entrypoint used to build real agents.
-
-```ts
-import { MockProvider } from "@irogane/kaji/testing";
-```
-
-## Development
-
-```bash
-# from the repository root
-bun install
-bun --filter kaji typecheck
-bun --filter kaji format:check
-bun --filter kaji test
-bun --filter kaji build
-```
+Kaji does not provide an agent framework, model SDK, workflow engine,
+MCP runtime, tool registry, identity provider, queue, scheduler, retry
+engine, or event-sourcing system. Your application supplies identity,
+authorization policy, and domain logic; Kaji only governs how a request
+to run one action is validated, authorized, approved, executed once,
+and recorded.
 
-## Relation to the Python SDK
+## Documentation
 
-This package ports the **runtime core** of the Python `kaji` SDK: events,
-sessions, tools, providers, and the ReAct loop. Python's Redis realtime bus,
-RAG, and text/voice modalities are not yet ported. The Python bus can be
-Redis-backed for multi-process deployments; the TS `EventBus` is in-memory only.
+Full documentation, guides, and the API reference are at
+[kaji.build](https://kaji.build). A complete runnable proof example
+lives in [`examples/refund`](https://github.com/enkyuan/kaji/tree/main/examples/refund)
+in the repository.
 
 ## License
 
-Kaji is source-available under the
-[Functional Source License 1.1, ALv2 Future License](https://spdx.org/licenses/FSL-1.1-ALv2.html).
-It permits internal commercial use, modification, and redistribution for
-permitted purposes, but excludes competing commercial products and services;
-each version becomes Apache-2.0 after two years. FSL is not an OSI-approved
-open-source license.
+FSL-1.1-ALv2. See [LICENSE](https://github.com/enkyuan/kaji/blob/main/LICENSE).