@theokit/sdk 4.2.6 → 4.2.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.2.8
+
+### Patch Changes
+
+- feat(init-claude): the scaffolded `.claude/` template now covers **every public `@theokit/sdk` subpath**. Added 16 per-module skills — models, subagents (`/a2a` + tool-scope), retry, task-store, sandbox, compaction, messages, auth (`/server/auth` + errors-envelope), sanitize, skills, path-safety, concurrency, persistence, client, filesystem, project — each authored against the shipped type declarations (verified signatures: `Retry.create` executor, `Semaphore.create`, `SubAgent.create`, `Auth.create`, `sanitizeToolInput`, …). The `claude-template-no-drift` gate covers the expanded set.
+
+## 4.2.7
+
+### Patch Changes
+
+- fix(init-claude): the scaffolded `.claude/` template (`npx theokit-init-claude`) now teaches the current `X.create()` API instead of the pre-3.0 surface removed by SE36 (#139). `AGENTS.md` + the affected skills/rules were corrected: `defineTool`→`Tool.create`, `defineSubscription`→`Subscription.create`, `createAgentFactory`→`AgentFactory.create`; the tool spec field is `handler` (not `execute`); streaming events are `system`/`user`/`assistant`/`thinking`/`tool_call`/`status`/`task`/`request` (there is no `tool_use`/`tool_result`/`usage`/`error`); assistant text is `event.message.content`; `Agent.prompt(prompt, options)` (prompt first); built-in coding tools import from `@theokit/sdk-tools` (not a `@theokit/sdk/tools` subpath). The phantom `theokit-rag` skill and the non-existent `@theokit/sdk/rag` import were removed. A `tests/lint/claude-template-no-drift.test.ts` gate now fails CI if the scaffold teaches a removed factory, phantom subpath, or non-existent stream event.
+
 ## 4.2.6
 
 ### Patch Changes

package/claude-template/AGENTS.md

@@ -1,6 +1,6 @@
 # @theokit/sdk — TypeScript SDK for AI Agents
 
-Build AI agents that run locally or in the cloud. Same code, same API, pick your runtime.
+Build AI agents that run locally or in the cloud. Same code, same API, pick your runtime. The exported types are the canonical contract.
 
 ## Setup
 
@@ -13,24 +13,23 @@ Set your API key:
 export THEOKIT_API_KEY="your-key"
 ```
 
-## Import Map
+Node 22.12+ required.
+
+## Import Map (verified subpaths)
 
 ```typescript
-import { Agent } from "@theokit/sdk";                         // Core: Agent, Run, SDKMessage
-import { defineTool } from "@theokit/sdk";                     // Tool definitions
-import { TheokitAgentError } from "@theokit/sdk/errors";       // Error hierarchy
-import { Cron } from "@theokit/sdk/cron";                      // Scheduled jobs
-import { Eval } from "@theokit/sdk/eval";                      // Evaluation suite
-import { Workflow } from "@theokit/sdk/workflow";               // Multi-step workflows
-import { defineSubscription } from "@theokit/sdk/subscription"; // SSE/WebSocket subscriptions
-import { VectorRetriever } from "@theokit/sdk/rag";            // RAG: retrievers, rerankers, splitters
-import { defineSubAgent } from "@theokit/sdk/a2a";             // Agent-to-agent delegation
-import { SandboxBackend } from "@theokit/sdk/sandbox";         // Sandbox backends
-import { defineAuth } from "@theokit/sdk/server/auth";         // Authentication
-import { TaskStore } from "@theokit/sdk/task-store";           // Task persistence
-import { createClient } from "@theokit/sdk/client";            // HTTP client
+import { Agent, Cron, Tool } from "@theokit/sdk";              // core: Agent, Run, Cron, Tool, SDKMessage
+import { TheokitAgentError } from "@theokit/sdk/errors";       // error hierarchy
+import { Workflow } from "@theokit/sdk/workflow";              // multi-step workflows
+import { Eval } from "@theokit/sdk/eval";                      // evaluation suite
+import { Subscription } from "@theokit/sdk/subscription";      // SSE / WebSocket subscriptions
+import { SubAgent } from "@theokit/sdk/a2a";                   // agent-to-agent delegation
+import { Auth } from "@theokit/sdk/server/auth";              // authentication
+import { TaskStore } from "@theokit/sdk/task-store";           // task persistence
 ```
 
+Other public subpaths: `/messages`, `/models`, `/skills`, `/project`, `/subagents`, `/sandbox`, `/client`, `/persistence`, `/retry`, `/concurrency`, `/sanitize`. There is **no** `@theokit/sdk/rag` subpath. Never import from `@theokit/sdk/internal/*` or `@theokit/sdk/dist/*`.
+
 ## Quick Start
 
 ```typescript
@@ -42,90 +41,109 @@ const agent = await Agent.create({
 
 const run = await agent.send("Summarize this repository");
 for await (const event of run.stream()) {
-  if (event.type === "assistant") console.log(event.content);
+  if (event.type === "assistant") {
+    for (const block of event.message.content) {
+      if (block.type === "text") process.stdout.write(block.text);
+    }
+  }
 }
 
-agent.dispose(); // Always clean up
+await agent[Symbol.asyncDispose](); // or: await using agent = await Agent.create(...)
 ```
 
 ## Core Patterns
 
 ### Agent lifecycle
-- `Agent.create(options)` — create an agent (local or cloud)
-- `agent.send(prompt)` — send a message, get a Run
-- `run.stream()` — AsyncGenerator of SDKMessage events
-- `agent.dispose()` — clean up resources (or use `await using`)
-- `Agent.prompt(options, prompt)` — one-shot: create, send, dispose
-
-### Tool definition
+- `Agent.create(options)` — create an agent (local or cloud); returns immediately, `agent.agentId` is `agent-<uuid>` (local) or `bc-<uuid>` (cloud).
+- `agent.send(prompt)` — send a message, get a `Run` (context is retained across sends).
+- `run.stream()` — `AsyncGenerator` of `SDKMessage` events.
+- `run.wait()` — resolve to `{ status, result, model, durationMs, git? }` after the run ends.
+- `Agent.prompt(prompt, options)` — one-shot (create + send + dispose). **Prompt is the first argument.**
+- `Agent.resume(agentId, { apiKey })` — reattach; runtime auto-detected from the ID prefix.
+- Dispose with `await using`, `await agent[Symbol.asyncDispose]()`, or `agent.close()` (fire-and-forget).
+
+### Tool definition — `Tool.create` with a Zod schema
 ```typescript
-const searchTool = defineTool({
+import { z } from "zod";
+import { Tool } from "@theokit/sdk";
+
+const searchTool = Tool.create({
   name: "search",
   description: "Search the web",
   inputSchema: z.object({ query: z.string() }),
-  execute: async ({ query }) => ({ results: await search(query) }),
+  handler: async ({ query }) => JSON.stringify({ results: await search(query) }),
 });
 ```
 
-### Streaming events (SDKMessage)
-- `{ type: "assistant", content }` — text from the model
-- `{ type: "tool_use", name, input }` — tool call
-- `{ type: "tool_result", name, output }` — tool response
-- `{ type: "status", status }` — run status change
-- `{ type: "error", error }` — error event
-- `{ type: "usage", tokens }` — token usage update
+The tool spec field is `handler` (returns a string, or a typed value when you set `outputSchema`). Built-in coding tools (`createReadFileTool`, …) live in the separate `@theokit/sdk-tools` package, not a `@theokit/sdk/tools` subpath.
+
+`Tool.create` is the canonical factory (uniform `X.create()` API since v3.0). Every public factory follows it: `Provider.create`, `Plugin.create`, `Subscription.create`, `Auth.create`, `SubAgent.create`, `Squad.create`, `Retry.create`. There is **no** `defineTool` / `define*` export — those were removed at v3.0.
+
+### Streaming events (`SDKMessage`)
+Discriminate on `type`. All events carry `agent_id` and `run_id`.
+- `{ type: "system" }` — init metadata, once at start (`model?`, `tools?`)
+- `{ type: "user", message: { content } }` — echo of the prompt
+- `{ type: "assistant", message: { content } }` — model output; `content` is a `(TextBlock | ToolUseBlock)[]`
+- `{ type: "thinking", text }` — reasoning content
+- `{ type: "tool_call", call_id, name, status, args?, result? }` — tool lifecycle
+- `{ type: "status", status }` — cloud run lifecycle
+- `{ type: "task" }` / `{ type: "request", request_id }` — task milestones / awaiting input
+
+There is no `tool_use` / `tool_result` / `usage` / `error` event. Read assistant text from `event.message.content` (a block array), not `event.content`. Treat `tool_call` `args`/`result` as `unknown`.
 
 ### Error handling
 ```typescript
+import { TheokitAgentError } from "@theokit/sdk/errors";
+
 try {
   await agent.send("...");
 } catch (e) {
-  if (e instanceof TheokitAgentError) {
-    console.error(e.code, e.message); // typed error with code
-  }
+  if (e instanceof TheokitAgentError) console.error(e.code, e.isRetryable, e.message);
 }
 ```
+Subclasses: `AuthenticationError`, `RateLimitError`, `ConfigurationError`, `IntegrationNotConnectedError`, `NetworkError`, `UnknownAgentError`, `UnsupportedRunOperationError`.
 
-### DI decorators (`@theokit/di` + `@theokit/di-agent`)
+### Optional: DI decorators (`@theokit/di` + `@theokit/di-agent`)
+Decorators are an **optional** convenience layer in separate packages — the factory API above is canonical and never requires them.
 ```typescript
-import { Injectable, Container } from "@theokit/di";
-import { Tool, Workflow, Cron, InjectAgent } from "@theokit/di-agent";
+import { Injectable } from "@theokit/di";
+import { Tool as ToolDecorator, Cron as CronDecorator } from "@theokit/di-agent";
 
 @Injectable()
 class MyService {
-  @Tool({ name: "search", description: "Search" })
-  searchTool!: ToolOptions;
+  @ToolDecorator({ name: "search", description: "Search" })
+  searchTool!: unknown;
 
-  @Cron({ schedule: "*/5 * * * *" })
+  @CronDecorator({ schedule: "*/5 * * * *" })
   cleanup() { /* runs every 5 min */ }
 }
 ```
 
-### Gateways
+### Optional: Gateways
 ```typescript
 import { defineGateway } from "@theokit/gateway-telegram"; // or -slack, -discord, etc.
 const gateway = defineGateway({ token: process.env.BOT_TOKEN });
 ```
 
-Available: telegram, slack, discord, whatsapp, teams, email, sms, mattermost, line, matrix.
-
 ## Anti-patterns
 
-- NEVER import from `@theokit/sdk/internal/...` — internal paths are not public API
-- NEVER import from `@theokit/sdk/dist/...` — use the exports map above
-- NEVER forget `agent.dispose()` — causes resource leaks
-- NEVER use `new Agent()` — always use `Agent.create()`
-- NEVER use `any` for tool input schemas — use Zod schemas
+- NEVER `new Agent()` — always `await Agent.create()`.
+- NEVER author `defineTool` / `defineSubscription` / `defineAuth` / `defineSubAgent` — use `Tool.create` / `Subscription.create` / `Auth.create` / `SubAgent.create`.
+- NEVER switch on `tool_use` / `tool_result` / `usage` / `error` stream events — they don't exist; use `tool_call` / `assistant` / `thinking` / `status`.
+- NEVER read assistant text as `event.content` — it's `event.message.content`.
+- NEVER import from `@theokit/sdk/internal/*`, `@theokit/sdk/dist/*`, or `@theokit/sdk/rag` (no such subpath).
+- NEVER forget disposal (`await using` / `Symbol.asyncDispose` / `close()`) — it leaks the runtime.
+- NEVER use `any` for tool input schemas — use Zod schemas.
 
 ## Packages
 
 | Package | Purpose |
 |---------|---------|
-| `@theokit/sdk` | Core SDK (Agent, Run, Tools, Memory, Streaming) |
-| `@theokit/di` | Dependency injection container |
-| `@theokit/di-agent` | 15 agentic decorators for DI |
-| `@theokit/gateway-*` | Platform gateways (Telegram, Slack, etc.) |
-| `@theokit/react` | React hooks for agent UIs |
+| `@theokit/sdk` | Core SDK (Agent, Run, Tool, Cron, streaming, memory, workflows, eval, subscriptions) |
+| `@theokit/di` | Dependency injection container (optional) |
+| `@theokit/di-agent` | Agentic decorators for DI (optional) |
+| `@theokit/gateway-*` | Platform gateways — telegram, slack, discord, etc. (optional) |
+| `@theokit/react` | React hooks for agent UIs (optional) |
 
 ## Configuration
 

package/claude-template/CLAUDE.md

@@ -16,7 +16,6 @@ These skills inject TheoKit knowledge automatically when you edit files matching
 | `theokit-di` | `*container*`, `*inject*`, `*provider*`, `*module*` |
 | `theokit-di-agent` | `*decorator*`, `*Decorator*`, `di-agent*` |
 | `theokit-gateways` | `*gateway*`, `*telegram*`, `*slack*`, `*discord*` |
-| `theokit-rag` | `*retriev*`, `*rerank*`, `*splitter*`, `*rag*` |
 | `theokit-workflows` | `*workflow*`, `*Workflow*`, `*step*` |
 | `theokit-eval` | `*eval*`, `*Eval*`, `*scorer*` |
 | `theokit-cron` | `*cron*`, `*Cron*`, `*job*`, `*schedule*` |
@@ -25,6 +24,22 @@ These skills inject TheoKit knowledge automatically when you edit files matching
 | `theokit-config` | `.theokit/**`, `config.*`, `theo.config.*` |
 | `theokit-streaming` | `*stream*`, `*Stream*`, `*SDKMessage*` |
 | `theokit-budget` | `*budget*`, `*Budget*`, `*cost*`, `*token*` |
+| `theokit-models` | `*model*`, `*Model*` |
+| `theokit-subagents` | `*subagent*`, `*a2a*`, `*delegat*` |
+| `theokit-retry` | `*retry*`, `*Retry*` |
+| `theokit-task-store` | `*task-store*`, `*taskstore*`, `*TaskStore*` |
+| `theokit-sandbox` | `*sandbox*`, `*Sandbox*` |
+| `theokit-compaction` | `*compact*`, `*Compact*` |
+| `theokit-messages` | `*message*`, `*Message*` |
+| `theokit-auth` | `*auth*`, `*Auth*`, `*envelope*` |
+| `theokit-sanitize` | `*sanitize*`, `*Sanitize*` |
+| `theokit-skills` | `*skill*`, `*Skill*` |
+| `theokit-path-safety` | `*path-safety*`, `*pathsafety*` |
+| `theokit-concurrency` | `*concurren*`, `*semaphore*`, `*Semaphore*` |
+| `theokit-persistence` | `*persist*`, `*Persist*` |
+| `theokit-client` | `*client*`, `*Client*` |
+| `theokit-filesystem` | `*filesystem*`, `*Filesystem*` |
+| `theokit-project` | `*project*`, `*Project*` |
 
 ### Settings
 

package/claude-template/dot-claude/rules/theokit-conventions.md

@@ -6,10 +6,9 @@
 - Use `Agent.prompt()` for one-shot operations (auto-disposes)
 
 ## Imports
-- Use `@theokit/sdk` for core (Agent, defineTool, Memory)
+- Use `@theokit/sdk` for core (Agent, Tool, Cron, Memory)
 - Use `@theokit/sdk/errors` for error types
 - Use `@theokit/sdk/subscription` for SSE/WebSocket
-- Use `@theokit/sdk/rag` for retrievers, rerankers, splitters
 - Use `@theokit/sdk/cron` for scheduled jobs
 - Use `@theokit/sdk/eval` for evaluation
 - Use `@theokit/sdk/workflow` for workflows
@@ -18,7 +17,7 @@
 
 ## Tools
 - Tool `inputSchema` MUST use Zod schemas — NEVER `any` or untyped objects
-- Tool `execute` MUST return a serializable value
+- Tool `handler` MUST return a string (or a value matching `outputSchema` when set)
 
 ## DI
 - Use `@Injectable()` + `@Inject()` from `@theokit/di`

package/claude-template/dot-claude/skills/theokit-agent-core/SKILL.md

@@ -129,12 +129,12 @@ const { items, nextCursor } = await Agent.list({ runtime: "local", cwd: process.
 const { items: runs } = await Agent.listRuns(agentId);
 ```
 
-## createAgentFactory
+## AgentFactory.create
 
 ```typescript
-import { createAgentFactory } from "@theokit/sdk";
+import { AgentFactory } from "@theokit/sdk";
 
-const factory = createAgentFactory({
+const factory = AgentFactory.create({
   apiKey: process.env.THEOKIT_API_KEY!,
   model: { id: "claude-sonnet-4-6" },
   local: { cwd: process.cwd() },

package/claude-template/dot-claude/skills/theokit-auth/SKILL.md

@@ -0,0 +1,102 @@
+---
+user-invocable: false
+paths:
+  - "**/*auth*"
+  - "**/*Auth*"
+  - "**/*envelope*"
+description: TheoKit SDK server auth — Auth.create orchestrator, validateReturnTo, and the cross-layer error envelope
+---
+
+# TheoKit Server Auth
+
+Server-side auth orchestrator and the cross-layer error envelope. These live
+under the `@theokit/sdk/server/*` sub-paths (not the main barrel). Concrete
+OAuth/email providers ship in opt-in `@theokit/auth-*` packages — the SDK only
+defines the orchestrator contract.
+
+## `Auth.create` — session + provider orchestrator
+
+```typescript
+import {
+  Auth,
+  validateReturnTo,
+  AuthConfigError,
+  AuthProviderNotFoundError,
+  AuthCallbackError,
+  AuthCancelledError,
+  AuthSecretTooShortError,
+} from "@theokit/sdk/server/auth";
+import type {
+  AuthProvider,
+  SessionManager,
+  AuthOrchestrator,
+} from "@theokit/sdk/server/auth";
+```
+
+`Auth.create(opts)` returns an `AuthOrchestrator<TSession>` with 5 methods.
+`providers` is optional — an empty list is the manual-`signIn`-only escape hatch.
+
+```typescript
+const auth: AuthOrchestrator<Session> = Auth.create<Session>({
+  session,                 // your SessionManager<Session> implementation
+  providers: [githubProvider], // AuthProvider<Profile>[] from a @theokit/auth-* package
+  onSignIn: async ({ profile, provider }) => {
+    return toSession(profile, provider); // returns the TSession to persist
+  },
+  onSignOut: async (session) => {
+    /* revoke, audit, etc. */
+  },
+});
+
+// OAuth flow (node:http req/res):
+const redirect = await auth.startSignIn("github", req, { returnTo: "/dashboard" });
+const { session, returnTo } = await auth.finishSignIn("github", req, res); // rotates session id (OWASP A07)
+const current = await auth.getSession(req);
+await auth.signOut(res);
+
+// Escape hatch — persist a session directly, skipping the OAuth flow:
+const s = await auth.signIn(externalProfile, "github", req, res);
+```
+
+## `validateReturnTo` — open-redirect guard (OWASP A01)
+
+Returns a safe same-origin path. Cross-origin, protocol-relative (`//evil.com`),
+empty, and defensive cases all collapse to `"/"`.
+
+```typescript
+const safe = validateReturnTo(returnTo, new URL("https://app.example.com"));
+// "/dashboard" -> kept; "https://evil.com" -> "/"; undefined -> "/"
+```
+
+Typed errors: `AuthConfigError`, `AuthProviderNotFoundError`, `AuthCallbackError`,
+`AuthCancelledError`, `AuthSecretTooShortError`.
+
+## Error envelope — cross-layer boundary translation
+
+```typescript
+import {
+  toEnvelope,
+  fromEnvelope,
+  MemoryAdapterError,
+} from "@theokit/sdk/server/errors-envelope";
+import type {
+  TheokitErrorEnvelope,
+  TheokitErrorCode,
+} from "@theokit/sdk/server/errors-envelope";
+```
+
+`toEnvelope` translates any SDK error (or arbitrary thrown value) into the wire
+envelope at egress; `fromEnvelope` reconstructs SDK class identity at ingress so
+`instanceof` checks keep working across an IPC/serialization boundary.
+
+```typescript
+try {
+  await agent.send(prompt);
+} catch (err) {
+  const envelope: TheokitErrorEnvelope = toEnvelope(err); // { code, message, meta?, ext? }
+  send(envelope); // code is a TheokitErrorCode, e.g. "RATE_LIMITED"
+}
+
+// Inbound edge (e.g. worker receiving the envelope):
+const restored = fromEnvelope(envelope); // a TheokitAgentError subclass
+```

package/claude-template/dot-claude/skills/theokit-client/SKILL.md

@@ -0,0 +1,58 @@
+---
+user-invocable: false
+paths:
+  - "**/*client*"
+  - "**/*Client*"
+description: TheoKit SDK low-level HTTP client — TheoKitClient (DEPRECATED; prefer the Agent façade)
+---
+
+# TheoKit Client
+
+`TheoKitClient` is a browser-safe, zero-Node-dependency HTTP client (native
+`fetch` + manual SSE parsing) for a legacy server-adapter contract.
+
+> DEPRECATED since 2.x — the `@theokit/sdk/client` sub-path consumes a legacy
+> server-adapter HTTP contract (`POST /agent/send`, `GET /agent/stream`) that the
+> ecosystem no longer produces, and will be removed in the next major. For
+> in-process runs use the `Agent` façade (`@theokit/sdk`); for HTTP, use the
+> framework's typed `POST /api/agents/<name>` client. Reach for this only when
+> maintaining an existing integration against the old contract.
+
+```ts
+import { TheoKitClient } from "@theokit/sdk/client";
+import type { ClientOptions, SendResponse, StreamEvent } from "@theokit/sdk/client";
+```
+
+## Construct
+
+The constructor takes `ClientOptions` — `baseUrl` (required), optional `basePath`
+and `headers`.
+
+```ts
+const client = new TheoKitClient({
+  baseUrl: "https://adapter.example.com",
+  basePath: "/agent",                      // optional
+  headers: { authorization: "Bearer …" },  // optional
+});
+```
+
+## Send (one-shot)
+
+`send(input)` POSTs and resolves a `SendResponse` (`{ status, output?, error? }`).
+
+```ts
+const res: SendResponse = await client.send("summarize the repo");
+if (res.error) throw new Error(res.error);
+console.log(res.status, res.output);
+```
+
+## Stream (SSE)
+
+`stream(input)` returns an `AsyncGenerator<StreamEvent>`; each `StreamEvent` has a
+`type` and an optional `text` (plus arbitrary extra fields).
+
+```ts
+for await (const event of client.stream("build the changelog")) {
+  if (event.type === "text" && event.text) process.stdout.write(event.text);
+}
+```

package/claude-template/dot-claude/skills/theokit-compaction/SKILL.md

@@ -0,0 +1,102 @@
+---
+user-invocable: false
+paths:
+  - "**/*compact*"
+  - "**/*Compact*"
+description: TheoKit SDK compaction reference — compactTranscript, shouldCompact, checkpoints, context-overflow
+---
+
+# TheoKit Compaction
+
+Public context-management helpers. Every function is pure and never mutates its
+input. A `CompressibleMessage` is `{ role: "user" | "assistant" | "system"; content: string }`.
+
+```typescript
+import {
+  compactTranscript,
+  shouldCompact,
+  estimateTokens,
+  buildCheckpoint,
+  filterFromLatestCheckpoint,
+  isContextOverflowError,
+  CHECKPOINT_MARKER,
+  SUMMARY_TEMPLATE,
+  type CompactTranscriptOptions,
+  type ShouldCompactInput,
+  type CompressibleMessage,
+} from "@theokit/sdk/compaction";
+```
+
+## Pre-call gate — `estimateTokens` + `shouldCompact`
+
+`estimateTokens` is a tokenizer-free `ceil(text.length / 4)` heuristic — a cheap
+gate, NOT exact tokenization. `shouldCompact` is pure: the caller supplies the
+model's window.
+
+```typescript
+const estimated = estimateTokens(transcript.map((m) => m.content).join("\n"));
+
+const input: ShouldCompactInput = {
+  estimated,
+  contextWindow: 200_000,
+  buffer: 8_000,     // headroom to reserve (output + safety margin)
+  maxOutput: 4_000,  // optional; separate response reservation (default 0)
+};
+
+if (shouldCompact(input)) {
+  // compact before sending — see below
+}
+```
+
+## `compactTranscript` — summarize the older window
+
+Default `keepRecent` mode keeps the last N turns verbatim (default 6) and
+preserves leading system prompts. The older window is summarized via the
+caller-supplied `summarize` callback (or dropped if omitted). With `failSafe`, a
+thrown summarizer returns the ORIGINAL transcript instead of propagating.
+
+```typescript
+const opts: CompactTranscriptOptions = {
+  keepRecent: 6,        // OR keepTokens: 40_000 (token-budget mode, takes precedence)
+  failSafe: true,
+  summarize: async (older: CompressibleMessage[], template: string) => {
+    // template is SUMMARY_TEMPLATE unless overridden via summaryTemplate
+    const summary = await callYourModel(template, older);
+    return { role: "system", content: summary };
+  },
+};
+
+const compacted = await compactTranscript(transcript, opts);
+```
+
+## Checkpoints — mark and filter
+
+`buildCheckpoint` produces a `system` turn whose content starts with
+`CHECKPOINT_MARKER`. `filterFromLatestCheckpoint` returns turns relative to the
+most recent marker (`include: "after"` excludes it — the default; `"from"`
+includes it).
+
+```typescript
+const marked = [...transcript, buildCheckpoint("milestone: tests green")];
+
+const recent = filterFromLatestCheckpoint(marked);              // after (exclusive)
+const withHead = filterFromLatestCheckpoint(marked, { include: "from" });
+```
+
+## Context-overflow detection
+
+`isContextOverflowError` is `true` only for a `TheokitAgentError` reporting the
+typed `context_too_long` code — never a brittle message regex.
+
+```typescript
+try {
+  await agent.send(prompt);
+} catch (err) {
+  if (isContextOverflowError(err)) {
+    const compacted = await compactTranscript(transcript, { keepRecent: 4 });
+    // retry with the compacted transcript
+  } else {
+    throw err;
+  }
+}
+```

package/claude-template/dot-claude/skills/theokit-concurrency/SKILL.md

@@ -0,0 +1,68 @@
+---
+user-invocable: false
+description: Bound in-process parallelism with Semaphore.create and mapWithConcurrency from @theokit/sdk/concurrency.
+paths:
+  - "**/*concurren*"
+  - "**/*semaphore*"
+  - "**/*Semaphore*"
+---
+
+# TheoKit SDK -- Concurrency
+
+In-house concurrency helpers (no `p-limit`/`p-map` dependency). `Semaphore.create(permits)` builds an N-permit async counting gate; `mapWithConcurrency` runs an async mapper over items with bounded parallelism while preserving input order.
+
+## Import
+
+```typescript
+import { Semaphore, mapWithConcurrency } from "@theokit/sdk/concurrency";
+import type { AsyncSemaphore } from "@theokit/sdk/concurrency";
+```
+
+## Signatures
+
+```typescript
+class Semaphore {
+  static create(permits: number): AsyncSemaphore; // canonical factory (ADR 0015)
+}
+
+interface AsyncSemaphore {
+  acquire(): Promise<() => void>; // returns a release fn; call it exactly once
+  inFlight(): number;             // permits currently held
+  pending(): number;              // in-flight + queued waiters
+}
+
+function mapWithConcurrency<T, R>(
+  items: ReadonlyArray<T>,
+  concurrency: number,                                     // positive integer; validated
+  fn: (item: T, index: number, signal: AbortSignal) => Promise<R>,
+  options?: { signal?: AbortSignal },
+): Promise<R[]>; // ordered; fail-fast; throws ConfigurationError on bad concurrency
+```
+
+## Semaphore -- release in a finally
+
+```typescript
+const sem = Semaphore.create(4); // at most 4 in flight
+
+async function guarded<T>(task: () => Promise<T>): Promise<T> {
+  const release = await sem.acquire();
+  try {
+    return await task();
+  } finally {
+    release(); // release exactly once (idempotent, but leaking it consumes a permit)
+  }
+}
+```
+
+## mapWithConcurrency -- ordered bounded map
+
+```typescript
+const controller = new AbortController();
+const results = await mapWithConcurrency(
+  ["a", "b", "c"],
+  2, // max 2 concurrent fetches
+  async (url, _index, signal) => (await fetch(url, { signal })).json(),
+  { signal: controller.signal },
+);
+// results align with input order; rejects on the first task error
+```