@theokit/sdk 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## 2.4.0
+
+### Minor Changes
+
+- a21949f: M1-5 — `@theokit/sdk/messages`: pure readers over the `SDKMessage` stream (plan `m1-sdkmessage-readers`).
+
+  Consumers reading the `SDKMessage` stream had to hand-roll a wire-event mapper. The SDK now ships three pure readers on a dedicated sub-path, promoting the proven first-party hand-roll onto the SDK's own types:
+
+  - `assistantText(msg)` — concatenates an assistant message's `text` blocks; `""` for any non-assistant message (or one with no text). `tool_use` blocks are ignored.
+  - `extractToolUses(msg)` — returns the assistant message's `ToolUseBlock`s; `[]` for non-assistant. Reads the assistant content blocks, NOT the separate `SDKToolUseMessage` (`type:"tool_call"`) lifecycle event.
+  - `costAmountUsd(cost)` — reads `RunResult.cost.amountUsd` preserving `number | undefined` verbatim. An unknown cost stays `undefined` (never coerced to `$0`), distinct from a real `$0` subscription-included route — the cost-honesty contract (ADR D377).
+
+  All three are pure (no I/O, inputs never mutated). Zero new dependencies.
+
+- fb268f9: M1-4 — fire the `stop` file-based hook + honor `feedback` as a bounded re-prompt (plan `m1-stop-hook-reflection`).
+
+  The `HookEvent "stop"` was declared but never dispatched. A local agent now fires `stop` once when it finishes a turn cleanly (not on an errored run or an iteration-ceiling truncation). A `stop` hook returning `{"decision":"feedback","feedback":"…"}` re-prompts the agent with that text and the loop continues — a bounded reflection ladder capped at `MAX_STOP_FEEDBACK_ATTEMPTS` (2), mirroring the existing nudge ceiling, so a hook cannot loop forever. `allow`/no-hook finish normally; `deny` at `stop` finishes (the answer already exists). Reuses the existing `HooksExecutor` — zero new dependencies. Hooks remain file-based (no programmatic callback).
+
+- 5b8c9e7: M2-1 — `@theokit/sdk/compaction`: public compaction / context-management helpers (plan `m2-compaction-public-api`).
+
+  Promotes the SDK's compaction capability to a public sub-path so consumers can manage the context window without reaching into `internal/`:
+
+  - `compactTranscript(messages, { keepRecent = 6, summarize? })` — keep the last `keepRecent` turns verbatim, preserve leading system turns, and either summarize the older window (via an optional `summarize` callback that can wire the SDK's internal LLM summarizer) or drop it. Reuses the internal `selectCompressionWindow` (no second algorithm). Never mutates its input.
+  - `buildCheckpoint(label?)` / `filterFromLatestCheckpoint(messages)` / `CHECKPOINT_MARKER` — a string-sentinel checkpoint: mark a point in a transcript and later filter back to the turns after the most recent marker.
+  - `isContextOverflowError(err)` — true iff `err` is a `TheokitAgentError` (or subclass) reporting the typed `context_too_long` code (reads both `err.code` and `err.metadata?.code`; no brittle message regex).
+
+  Operates on the SDK's own `CompressibleMessage` type (re-exported). Zero new dependencies.
+
+- 1cf9c16: M2-4 — per-model capability catalog public + OpenRouter slug-suffix fix (plan `m2-model-capabilities`).
+
+  - **New `@theokit/sdk/models` subpath.** `resolveModelCapabilities(modelId): ModelCapabilities` (previously dead `@internal`) is now public — returns a model's capability flags + `maxContextTokens`/`maxOutputTokens` from a static, OFFLINE catalog (pure, sync, no network). Pair `maxContextTokens` with `@theokit/sdk/compaction`'s `shouldCompact`.
+  - **Fix:** OpenRouter `:variant` suffixes (`:free`/`:nitro`/`:floor`/`:beta`) were not stripped before the catalog lookup, so `openrouter/openai/gpt-4o:free` fell back to conservative defaults (4096) instead of the real 128k window. The suffix is now stripped (alongside the existing routing-prefix strip); unknown models still get conservative defaults.
+
+  Zero new dependencies.
+
+- b31283c: M2-2 — pre-call token estimate + compaction decision (plan `m2-token-estimate`).
+
+  Two pure, zero-dependency helpers on the `@theokit/sdk/compaction` subpath (siblings of `compactTranscript`/`isContextOverflowError`):
+
+  - `estimateTokens(text)` — a tokenizer-free token estimate via the ~4-chars-per-token heuristic (`ceil(text.length / 4)`): `""` → 0, any non-empty text → ≥ 1. A cheap PRE-CALL gate, not exact tokenization.
+  - `shouldCompact({ estimated, contextWindow, buffer })` — decide BEFORE sending whether to compact: `true` when `estimated >= contextWindow - buffer`. Pure; the caller supplies the window (e.g. from `resolveModelCapabilities`), keeping it decoupled from any per-model catalog.
+
+  No tokenizer dependency.
+
+- 29b1c8c: M4-2 — hierarchical project-instruction reader/writer (plan `m4-project-instructions`).
+
+  New `@theokit/sdk/project` subpath:
+
+  - `readProjectInstructions(cwd, options?)` — walk up from `cwd` collecting `<dir>/<filename>` (default `THEO.md`; configurable) up to the filesystem root (or `options.stopDir`). Returns `{ files, content }`: `files` are the found files nearest-first (`{ path, content }[]`, read in full), `content` is a reduction chosen by `options.scope` — `"nearest"` (innermost) or `"merged"` (all joined root-first, nearest text last). NEVER throws — missing/unreadable/non-file paths are skipped.
+  - `writeProjectInstructions(cwd, content, options?)` — write `<cwd>/<filename>` atomically (temp + fsync + rename). Fails loud on write errors (unlike the best-effort reader).
+
+  Composes the SDK's hardened `walkUpForFile` discovery + the atomic `replaceFileAtomic` writer (Rule 9). Zero new dependencies.
+
+- f9be17a: M4-1 — first-party skill discovery + `<skills>` block (plan `m4-skills-discovery`).
+
+  New `@theokit/sdk/skills` subpath exposing two pure first-party primitives the SDK runtime already uses internally:
+
+  - `discoverSkills(dir, options?)` — discover `<dir>/<name>/SKILL.md` files under an ARBITRARY directory (not a hardcoded `.theokit/skills` root), parsing strict YAML frontmatter (`name`/`description` required; `category`/`dependencies` optional) and returning `Skill[]` (the skill BODY is never included). A subdirectory whose realpath escapes `dir` via symlink is skipped (symlink-escape guard, reusing `@theokit/sdk/path-safety`). NEVER throws — a missing/unreadable/non-directory path yields `[]`. A `SKILL.md` with malformed frontmatter is excluded and optionally reported via `options.onInvalidSkill`; a directory WITHOUT a `SKILL.md` is silently skipped.
+  - `buildSkillsBlock(skills)` — render the prompt-injection-safe `<skills>` system-prompt block (name + description XML-escaped); returns `undefined` for an empty list.
+
+  The internal `SkillsManager` (`.theokit/skills` discovery) and `SkillsPromptProvider` (`<skills>` injection) now delegate to these primitives — single source of truth, behavior preserved (golden + contract tests unchanged). Zero new dependencies.
+
+- f2265d7: M4-6 — sub-agent tool scoping via `AgentDefinition.tools` (plan `m4-tool-scoping`).
+
+  - `AgentDefinition` gains an optional `tools?: string[]` — a tool-name whitelist. When set, the sub-agent may ONLY call tools whose canonical (post-repair, lowercase) name is in the list; any other call is vetoed at dispatch. Absent/empty → unscoped (inherits the parent's full toolset). Backward-compatible.
+  - `.theokit/agents/*.md` subagents can declare it as a comma/space-separated frontmatter field (`tools: read_file, list_dir`).
+  - New `@theokit/sdk/subagents` subpath: `subagentToolWhitelist(definition): Set<string> | undefined` + `withSubagentToolScope(definition, fn)` enforce the whitelist via the SDK's existing `withToolWhitelist` dispatch veto — the same enforcement `Agent.fork`'s `allowedTools` uses, NOT `PermissionEngine`. A `tools: ["read_file"]` sub-agent provably cannot call `write_file`/`shell_exec`.
+
+  Zero new dependencies.
+
+- f1de451: M5-8 — public `parseModelId` + `humanizeModelName` + `toModelOption` on `@theokit/sdk/models` (plan `m5-model-option`).
+
+  - `parseModelId(modelId): { provider, name }` is now public (promoted from `@internal`) — splits the provider prefix from the model name, OpenRouter-routing + tag-suffix aware.
+  - `humanizeModelName(modelId): string` — a best-effort, deterministic human label: strips the routing/vendor prefix, title-cases the core model segment (known acronyms upper-cased), and appends an OpenRouter `:variant` in parens (`"openrouter/openai/gpt-4o:free"` → `"GPT 4o (free)"`). Not vendor-canonical marketing names.
+  - `toModelOption(modelId): { value, label, provider }` — a dropdown-ready entry composing the two.
+
+  Lets `@theokit/ui` model selectors + the `create-theokit` template stop hand-rolling slug→label. Zero new dependencies.
+
+### Patch Changes
+
+- 1abda16: M2-3 — `context_too_long` reaches the run boundary (plan `m2-context-overflow-boundary`).
+
+  Fixes a code-at-boundary bug: the loop captured the error code from the error's top-level `.code`, which the provider mappers set to a PROVIDER-PREFIXED string (`anthropic_context_too_long` / `${providerId}_context_too_long`), while the CANONICAL `ErrorCode` (`context_too_long`) lives on `metadata.code`. So `RunResult.error.code` surfaced the prefixed form and a consumer checking `result.error.code === "context_too_long"` missed it.
+
+  `registerLoopError` now prefers `cause.metadata?.code` over the top-level `.code`, so the canonical code reaches the boundary for every provider (verified by a 400-context-overflow contract test through the real `mapAnthropicError`/`mapOpenAICompatibleError`). The prefixed form remains on the thrown `TheokitAgentError.code` for telemetry. Set-once invariant preserved; top-level `.code` fallback unchanged when there is no `metadata.code`.
+
 ## 2.3.0
 
 ### Minor Changes
@@ -92,8 +178,19 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- **`context_too_long` reaches the run boundary (M2-3).** `registerLoopError` now prefers the canonical `cause.metadata?.code` over the provider-prefixed top-level `.code`, so `RunResult.error.code` is `context_too_long` (not `anthropic_context_too_long`) for every provider. Set-once + top-level fallback preserved.
+
+### Added
+
+- **Pre-call token estimate + compaction decision (M2-2).** `estimateTokens(text)` (tokenizer-free ~4-chars/token; `""`→0, non-empty→≥1) + `shouldCompact({estimated,contextWindow,buffer})` (`true` when `estimated >= contextWindow - buffer`; pure, caller supplies the window) on the `@theokit/sdk/compaction` subpath. No tokenizer dep.
+- **Per-model capability catalog public + OpenRouter slug-suffix fix (M2-4).** New `@theokit/sdk/models` subpath: `resolveModelCapabilities(modelId)` (was `@internal`) — pure/sync/offline capability flags + `maxContextTokens`/`maxOutputTokens`. Fixes an OpenRouter `:variant` suffix lookup miss (fell back to 4096 instead of the real window).
+
 ### Added
 
+- `@theokit/sdk/compaction` — public compaction / context-management helpers so you manage the context window without reaching into `internal/`. `compactTranscript(messages, { keepRecent = 6, summarize? })` keeps the last `keepRecent` turns, preserves leading system turns, and either summarizes the older window (via an optional callback wiring the internal LLM summarizer) or drops it — reusing the internal compaction window (no second algorithm), never mutating its input. `buildCheckpoint`/`filterFromLatestCheckpoint`/`CHECKPOINT_MARKER` give a string-sentinel checkpoint to bound replay to "since the last checkpoint". `isContextOverflowError(err)` is true for a `TheokitAgentError` reporting the typed `context_too_long` code (checks `code` + `metadata.code`; no message regex). Operates on the SDK's own `CompressibleMessage` (re-exported); zero new dependencies. (M2-1)
+- `@theokit/sdk/messages` — pure readers over the `SDKMessage` stream so you stop hand-rolling a wire-event mapper. `assistantText(msg)` concatenates an assistant message's text (`""` for non-assistant), `extractToolUses(msg)` returns its tool-use blocks (`[]` for non-assistant; reads the assistant content blocks, not the separate `tool_call` lifecycle event), and `costAmountUsd(cost)` reads `RunResult.cost.amountUsd` preserving `number | undefined` verbatim — an unknown cost stays `undefined`, never silently coerced to `$0` (cost-honesty, ADR D377). Zero new dependencies. (#34)
 - `createSquad({ agents })` — a thin convenience for sequential agent teams. Runs agents in order, threading each output into the next agent's prompt; returns `{ result, status, steps }`. Composes `Workflow` + `agentStep` internally (no new orchestration engine). `process: "hierarchical"` throws a guiding `ConfigurationError` (use subagents / `@theokit/sdk-handoff`); empty `agents` → `ConfigurationError(code: "invalid_squad")`.
 
 ### Fixed

package/dist/a2a/index.cjs

@@ -4922,6 +4922,8 @@ function parseSubagentMarkdown(raw, filename) {
   if (fields.model !== void 0) {
     definition.model = fields.model === "inherit" ? "inherit" : { id: fields.model };
   }
+  const tools = fields.tools?.split(/[\s,]+/).map((t) => t.trim()).filter((t) => t.length > 0);
+  if (tools !== void 0 && tools.length > 0) definition.tools = tools;
   return { name, definition };
 }
 function splitFrontmatter2(raw, filename) {
@@ -5125,25 +5127,33 @@ ${lines.join("\n")}
   }
 });
 
+// src/internal/runtime/skills/skills-block.ts
+function buildSkillsBlock(skills) {
+  if (skills.length === 0) return void 0;
+  const lines = skills.map(
+    (skill) => `  - ${escapeBlockBody(skill.name)}: ${escapeBlockBody(skill.description)}`
+  );
+  return `<skills>
+${lines.join("\n")}
+</skills>`;
+}
+var init_skills_block = __esm({
+  "src/internal/runtime/skills/skills-block.ts"() {
+    init_escape();
+  }
+});
+
 // src/internal/runtime/system-prompt/sources/skills-provider.ts
 var SkillsPromptProvider;
 var init_skills_provider = __esm({
   "src/internal/runtime/system-prompt/sources/skills-provider.ts"() {
-    init_escape();
+    init_skills_block();
     SkillsPromptProvider = class {
       id = "skills";
       priority = 20;
       contribute(ctx) {
         if (ctx.skillsAutoInject === false) return Promise.resolve(void 0);
-        if (ctx.skills.length === 0) return Promise.resolve(void 0);
-        const lines = ctx.skills.map((skill) => {
-          const name = escapeBlockBody(skill.name);
-          const description = escapeBlockBody(skill.description);
-          return `  - ${name}: ${description}`;
-        });
-        return Promise.resolve(`<skills>
-${lines.join("\n")}
-</skills>`);
+        return Promise.resolve(buildSkillsBlock(ctx.skills));
       }
     };
   }
@@ -6399,36 +6409,71 @@ var init_skill_frontmatter = __esm({
     init_yaml_frontmatter();
   }
 });
-function tryParseSkill(raw, fallbackName, source) {
+async function discoverSkills(dir, options) {
+  let entries;
+  try {
+    entries = await readWorkspaceDir(dir, "skills_read_error", "skills directory");
+  } catch {
+    return [];
+  }
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    let skillDir;
+    try {
+      skillDir = safePathJoin(dir, entry.name);
+      assertNoSymlinkEscape(skillDir, dir);
+    } catch {
+      continue;
+    }
+    const skillPath = path.join(skillDir, "SKILL.md");
+    let raw;
+    try {
+      raw = await promises.readFile(skillPath, "utf8");
+    } catch {
+      continue;
+    }
+    const skill = tryParseSkill(raw, entry.name, skillPath, options);
+    if (skill !== void 0) skills.push(skill);
+  }
+  return skills;
+}
+function tryParseSkill(raw, fallbackName, source, options) {
   try {
     const frontmatter = parseSkillFrontmatter(raw, fallbackName);
-    const metadata = {
+    const skill = {
       name: frontmatter.name,
       description: frontmatter.description,
       source
     };
-    if (frontmatter.category !== void 0) metadata.category = frontmatter.category;
-    if (frontmatter.dependencies !== void 0) metadata.dependencies = frontmatter.dependencies;
-    return metadata;
+    if (frontmatter.category !== void 0) skill.category = frontmatter.category;
+    if (frontmatter.dependencies !== void 0) skill.dependencies = frontmatter.dependencies;
+    return skill;
   } catch (cause) {
     if (cause instanceof ConfigurationError) {
-      const code = cause.code ?? "unknown";
-      process.stderr.write(
-        `[theokit-sdk] skill ${fallbackName} skipped (${code}): ${cause.message}
-`
-      );
+      options?.onInvalidSkill?.({
+        name: fallbackName,
+        source,
+        code: cause.code ?? "unknown",
+        message: cause.message
+      });
       return void 0;
     }
     throw cause;
   }
 }
-var SkillsManager;
-var init_skills_manager = __esm({
-  "src/internal/runtime/skills/skills-manager.ts"() {
+var init_discover_skills = __esm({
+  "src/internal/runtime/skills/discover-skills.ts"() {
     init_errors();
     init_path_guard();
     init_workspace_dir();
     init_skill_frontmatter();
+  }
+});
+var SkillsManager;
+var init_skills_manager = __esm({
+  "src/internal/runtime/skills/skills-manager.ts"() {
+    init_discover_skills();
     SkillsManager = class {
       constructor(cwd, _enabled, settingSourcesIncludeProject) {
         this.cwd = cwd;
@@ -6445,28 +6490,15 @@ var init_skills_manager = __esm({
         await this.refresh();
       }
       async refresh() {
-        this.skills = [];
         const skillsRoot = path.join(this.cwd, ".theokit", "skills");
-        const entries = await readWorkspaceDir(skillsRoot, "skills_read_error", "skills directory");
-        for (const entry of entries) {
-          if (!entry.isDirectory()) continue;
-          let skillDir;
-          try {
-            skillDir = safePathJoin(skillsRoot, entry.name);
-            assertNoSymlinkEscape(skillDir, skillsRoot);
-          } catch {
-            continue;
-          }
-          const skillPath = path.join(skillDir, "SKILL.md");
-          let raw;
-          try {
-            raw = await promises.readFile(skillPath, "utf8");
-          } catch {
-            continue;
+        this.skills = await discoverSkills(skillsRoot, {
+          onInvalidSkill: (info) => {
+            process.stderr.write(
+              `[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
+`
+            );
           }
-          const metadata = tryParseSkill(raw, entry.name, skillPath);
-          if (metadata !== void 0) this.skills.push(metadata);
-        }
+        });
       }
       list() {
         return Promise.resolve(this.skills);
@@ -6928,6 +6960,7 @@ async function initLoopContext(inputs) {
     finalStatus: "finished",
     usage: new UsageAccumulator(),
     nudgeAttempts: 0,
+    stopFeedbackAttempts: 0,
     ...memoryProviderHandle !== void 0 ? { memoryProviderHandle } : {},
     ...memorySystemPromptAdditions !== void 0 ? { memorySystemPromptAdditions } : {}
   };
@@ -7083,8 +7116,9 @@ function registerLoopError(ctx, cause) {
   if (ctx.error !== void 0) return;
   const rawMessage = cause?.message;
   const message = typeof rawMessage === "string" ? rawMessage : cause instanceof Error ? cause.message : String(cause);
+  const metaCode = cause?.metadata?.code;
   const rawCode = cause?.code;
-  const code = typeof rawCode === "string" ? rawCode : void 0;
+  const code = typeof metaCode === "string" ? metaCode : typeof rawCode === "string" ? rawCode : void 0;
   ctx.error = code !== void 0 ? { message, code, cause } : { message, cause };
 }
 async function runCollectorLoop(generator, inputs, ctx) {
@@ -8167,6 +8201,28 @@ function shouldNudgeAndContinue(ctx, llmOutput) {
   });
   return true;
 }
+async function reflectAfterStop(inputs, ctx) {
+  const result = await inputs.hooks.run({
+    event: "stop",
+    agentId: inputs.agentId,
+    runId: inputs.runId
+  });
+  if (result.blocked) return false;
+  if (ctx.stopFeedbackAttempts >= MAX_STOP_FEEDBACK_ATTEMPTS) return false;
+  const feedback = result.decisions.find(
+    (d) => d.decision === "feedback" && (d.feedback ?? "").length > 0
+  )?.feedback;
+  if (feedback === void 0) return false;
+  ctx.stopFeedbackAttempts += 1;
+  ctx.messages.push({ role: "user", content: [{ type: "text", text: feedback }] });
+  return true;
+}
+async function finishOrReflect(inputs, ctx, llmOutput) {
+  if (shouldNudgeAndContinue(ctx, llmOutput)) return "continue";
+  if (await reflectAfterStop(inputs, ctx)) return "continue";
+  ctx.finalStatus = "finished";
+  return "done";
+}
 async function runIteration(inputs, ctx) {
   const llmOutput = await streamLlmTurn(inputs, ctx);
   accumulateUsage(ctx.usage, llmOutput);
@@ -8200,9 +8256,7 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
     await emitAssistantTextStep(inputs, ctx, llmOutput.text);
   }
   if (llmOutput.stopReason !== "tool_use" || llmOutput.toolCalls.length === 0) {
-    if (shouldNudgeAndContinue(ctx, llmOutput)) return "continue";
-    ctx.finalStatus = "finished";
-    return "done";
+    return finishOrReflect(inputs, ctx, llmOutput);
   }
   ctx.messages.push(buildAssistantTurn(llmOutput.text, llmOutput.toolCalls));
   const toolResults = await dispatchTools(inputs, ctx.tools, llmOutput.toolCalls, ctx.events);
@@ -8225,7 +8279,7 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
   pushToolConversationSteps(ctx, llmOutput.toolCalls, toolResults);
   return handleToolErrorContinuation(inputs, ctx, toolResults);
 }
-var MAX_NUDGE_ATTEMPTS;
+var MAX_NUDGE_ATTEMPTS, MAX_STOP_FEEDBACK_ATTEMPTS;
 var init_loop = __esm({
   "src/internal/agent-loop/loop.ts"() {
     init_budget();
@@ -8238,6 +8292,7 @@ var init_loop = __esm({
     init_tool_dispatch();
     init_usage_and_cost();
     MAX_NUDGE_ATTEMPTS = 2;
+    MAX_STOP_FEEDBACK_ATTEMPTS = 2;
   }
 });