@irogane/kaji 0.2.0-beta.11

package/README.md

@@ -0,0 +1,598 @@
+# Kaji (TypeScript)
+
+`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.
+
+<!-- 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);
+```
+
+## Privileged event journal and disposal
+
+> **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.
+
+`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.
+
+```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
+}
+```
+
+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-...
+```
+
+```ts
+import { AgentBuilder, OpenAIProvider, Integration, deadlineAfter, tool } 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),
+  },
+});
+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.
+
+### 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.
+
+```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;
+  },
+});
+
+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) },
+});
+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;
+  },
+});
+// ...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.
+
+For the cross-SDK release gate, run from the repository root:
+
+```bash
+uv run --project kaji/packages/py python kaji/scripts/beta_release_check.py
+```
+
+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.
+
+For the live-gate credential modes specifically:
+
+```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
+```
+
+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.
+
+```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
+```
+
+`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:
+
+```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
+```
+
+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:
+
+```ts
+import { AgentBuilder, cliApprovalHandler, openai } from "@irogane/kaji";
+
+const agent = new AgentBuilder()
+  .provider(openai())
+  .approvalHandler(cliApprovalHandler({ label: "agent-a" }))
+  .build();
+```
+
+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
+```
+
+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`.
+
+`echo` and `github` are beta catalog entries. `--allow-experimental` is
+required only for catalog entries still marked experimental.
+
+## 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
+```
+
+## Relation to the Python SDK
+
+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.
+
+## 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.

package/contracts/README.md

@@ -0,0 +1,14 @@
+# Kaji beta contracts
+
+These files define the behavior shared by the Python and TypeScript SDK beta.
+
+- `beta-core-v1.json` pins public defaults and stability boundaries.
+- `feature-tiers-v1.json` is the machine-readable stable/experimental surface.
+- `events/` separates event drafts from sequenced stored events.
+- `tools/` contains the tool-spec schema and shared validation fixtures.
+- `errors/error-codes.json` is the normalized public failure vocabulary;
+  `errors/provider-normalization.json` pins cross-SDK status classification.
+
+Canonical files live in `kaji/contracts`. Package copies are generated and
+checked by `kaji/scripts/sync_beta_contracts.py`; do not edit package copies
+directly.

package/contracts/beta-core-v1.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kaji.dev/contracts/beta-core-v1.json",
+  "contractVersion": "1.0.0",
+  "runtime": {
+    "sameSessionTurns": "serialized",
+    "crossSessionTurns": "concurrent",
+    "maxToolIterations": 5,
+    "contextWindowTurns": 32,
+    "contextWindowCharacters": 100000,
+    "turnTimeoutMs": 120000,
+    "providerCancellationGraceMs": 5000,
+    "providerTextMaxBytes": 262144,
+    "providerToolArgumentsMaxBytes": 65536,
+    "providerResponseMaxBytes": 524288,
+    "providerToolCallsMax": 64
+  },
+  "tools": {
+    "schemaDraft": "2020-12",
+    "validateFormats": true,
+    "maxConcurrency": 4,
+    "timeoutMs": 30000,
+    "approvalTimeoutMs": 300000,
+    "riskRequired": true,
+    "idempotencyKey": "session_id:tool_call_id",
+    "idempotencyMaxEntries": 10000,
+    "idempotencyCompletedTtlSeconds": 86400
+  },
+  "events": {
+    "ordering": "store_sequence",
+    "draftSchema": "new-kaji-event-v1.schema.json",
+    "storedSchema": "stored-kaji-event-v1.schema.json",
+    "warmProjection": "cursor_suffix",
+    "subscriberQueueCapacity": 1024,
+    "maxDurableToolArgumentBytes": 65536,
+    "maxDurableToolResultBytes": 65536,
+    "maxDurableEventBytes": 1048576,
+    "inMemoryStoreMaxSessions": 1000,
+    "inMemoryStoreMaxEventsPerSession": 10000,
+    "inMemorySessionAdmission": "fail_closed_until_explicit_purge",
+    "purgedSessionReuse": "fresh_sequence",
+    "purgeClosesExistingSubscribers": true,
+    "purgeFencesDirectStoreOperations": true,
+    "postDeleteCleanup": "tombstone_until_converged",
+    "splitDeliveryPurge": "unsupported",
+    "overflow": "typed_error"
+  },
+  "integrations": {
+    "stable": ["echo", "github", "gmail"],
+    "experimentalRequiresOptIn": true
+  }
+}