@theokit/sdk 2.3.0 → 2.5.0

package/dist/internal/runtime/compression/compression-decision.d.ts

@@ -0,0 +1,10 @@
+/**
+ * T2.2 step 4a/N — Compression decision logic (ADR D440).
+ *
+ * Pure function that determines whether the agent-loop should attempt
+ * context-window compression on a given error. Isolates the decision
+ * matrix from the loop.ts hot path so it's independently testable.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/compression/compression-helpers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Compression helpers (T2.3, ADR D92).
+ *
+ * Scaffold for future compression LLM integration:
+ *   - `selectCompressionWindow` — splits messages into compress/preserve halves
+ *   - `assertCompressionReduced` — 10% reduction floor to detect "compression placebo"
+ *
+ * The compression LLM call itself is out of scope for this plan (requires
+ * an auxiliary-model ADR). These helpers are used by `Agent.send` when a
+ * future iteration adds compression.
+ *
+ * @internal
+ */
+export interface CompressionCheck {
+    reduced: boolean;
+    reductionPct: number;
+    reason?: string;
+}

package/dist/internal/runtime/compression/compression-model-registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * T2.2 — Provider-agnostic compression-model registry (ADR D440).
+ *
+ * Resolves a cheaper-tier summarization model in the SAME vendor family
+ * as the agent's main model. Provider-agnostic by design: a consumer
+ * running on Anthropic-only / Ollama-only / Bedrock-only never needs
+ * to provision a second vendor's key for the compression aux-LLM.
+ *
+ * Resolution algorithm:
+ *
+ *   1. Exact match in `EXACT_REGISTRY` → cheaper-tier id (most cases).
+ *   2. Wildcard match in `WILDCARD_REGISTRY` (`*` suffix in key) →
+ *      swap matched suffix (Bedrock region-prefixed variants).
+ *   3. Provider in `NO_AUTH_PROVIDERS` (Ollama / LM Studio / llama.cpp)
+ *      → return SAME model id (local — cost N/A; running the same
+ *      model for summarization costs only the round-trip latency,
+ *      acceptable in dev/local mode).
+ *   4. No match → throw `CompressionModelUnresolvedError` with the
+ *      actionable message naming the model + override path + the
+ *      registry-PR remediation hint.
+ *
+ * Step 1 of T2.2 (compression-helpers wire). Step 2 wires this into
+ * `compression-config.ts`. Step 3 builds the OTel-instrumented aux
+ * client. Step 4 wires into `loop.ts` ContextWindowExceededError catch.
+ *
+ * @internal
+ */
+/**
+ * T2.2 — Typed error thrown when `resolveCompressionModel` cannot
+ * find a same-family-cheaper-tier mapping for `agentModel`. Surfaces
+ * the offending model id so operators can either (a) provide
+ * `Agent.create({compression: {model: ...}})` explicitly or (b) open
+ * a registry-PR adding the missing entry.
+ *
+ * @public
+ */
+export declare class CompressionModelUnresolvedError extends Error {
+    readonly name = "CompressionModelUnresolvedError";
+    readonly agentModel: string;
+    constructor(agentModel: string);
+}

package/dist/internal/runtime/compression/compression-summarizer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * T2.2 step 3/N — Compression summarizer (ADR D440).
+ *
+ * Takes a conversation window (messages to compress) + a resolved
+ * compression model + an injected LLM caller, and returns a single
+ * system-role summary message that replaces the compressed window.
+ *
+ * The `callLlm` parameter is dependency-injected so:
+ *   - Unit tests pass a deterministic fake (no real-LLM cost)
+ *   - The agent-loop passes a real LLM client bound to the resolved
+ *     compression config (step 4 wire)
+ *
+ * Failure mode per ADR D440: if the LLM call fails, throws
+ * `CompressionFailedError` — the caller (loop.ts) catches this,
+ * logs WARN with redacted metadata, and returns the ORIGINAL
+ * conversation unchanged (counter incremented toward cap 3).
+ *
+ * @internal
+ */
+/**
+ * Typed error thrown when the compression LLM call fails or returns
+ * an empty/ineffective summary. The caller catches and handles per
+ * ADR D440 failure mode (WARN + original conversation + counter).
+ *
+ * @public
+ */
+export declare class CompressionFailedError extends Error {
+    readonly name = "CompressionFailedError";
+}

package/dist/internal/runtime/context/project-instructions.d.ts

@@ -0,0 +1,66 @@
+/** How discovered instruction files are reduced to a single `content` string. */
+export type ProjectInstructionScope = "nearest" | "merged";
+/** One discovered project-instruction file. */
+export interface ProjectInstructionFile {
+    /** Absolute path to the file. */
+    path: string;
+    /** Full file content (never truncated — the caller bounds it). */
+    content: string;
+}
+/** Result of {@link readProjectInstructions}. */
+export interface ProjectInstructions {
+    /** Found files, nearest-first (innermost directory first). Empty if none. */
+    files: ProjectInstructionFile[];
+    /**
+     * The `scope`-selected reduction: `nearest` → the innermost file's content;
+     * `merged` → all files joined root-first (nearest content last). `undefined`
+     * when no file was found.
+     */
+    content: string | undefined;
+}
+/** Options for {@link readProjectInstructions}. */
+export interface ReadProjectInstructionsOptions {
+    /** Instruction filename to discover. Default `"THEO.md"`. */
+    filename?: string;
+    /** How to reduce the found files to `content`. Default `"nearest"`. */
+    scope?: ProjectInstructionScope;
+    /** Stop the upward walk at this directory (inclusive). Default: filesystem root. */
+    stopDir?: string;
+}
+/** Options for {@link writeProjectInstructions}. */
+export interface WriteProjectInstructionsOptions {
+    /** Instruction filename to write. Default `"THEO.md"`. */
+    filename?: string;
+}
+/**
+ * Read hierarchical project instructions by walking up from `cwd`.
+ *
+ * Discovers every `<dir>/<filename>` from `cwd` up to the filesystem root (or
+ * `stopDir`), reads each, and returns them nearest-first in `files` plus a
+ * `content` reduction chosen by `scope`. Composes the hardened internal
+ * `walkUpForFile` (64-level cap, realpath dedup, FS-race tolerant).
+ *
+ * NEVER throws: a missing/unreadable directory or a path that exists but is not
+ * a readable file is skipped; no instruction file → `{ files: [], content: undefined }`.
+ *
+ * Public via `@theokit/sdk/project`.
+ *
+ * @public
+ */
+export declare function readProjectInstructions(cwd: string, options?: ReadProjectInstructionsOptions): Promise<ProjectInstructions>;
+/**
+ * Write project instructions to `<cwd>/<filename>` atomically (temp + fsync +
+ * rename, via the shipped `replaceFileAtomic`).
+ *
+ * Unlike the reader, this FAILS LOUD: an unsafe `filename` (path traversal,
+ * separators, absolute) is rejected with `ConfigurationError`
+ * (`code: "unsafe_filename"`) — symmetric with the reader, whose `filename`
+ * flows through the same `isSafePattern` guard — and a write error (e.g. the
+ * parent directory does not exist) propagates to the caller. A failed mutation
+ * is a real error, never silently swallowed.
+ *
+ * Public via `@theokit/sdk/project`.
+ *
+ * @public
+ */
+export declare function writeProjectInstructions(cwd: string, content: string, options?: WriteProjectInstructionsOptions): Promise<void>;

package/dist/internal/runtime/context/replay-history.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Stateless continuation-history rebuild (M1-3 — plan m1-continuation-history).
+ *
+ * `buildReplayHistory` serializes `SDKMessage[]` stream events into a bounded
+ * `StoredMessage[]` replay history for the STATELESS continuation path: a server
+ * (or serverless handler) that re-runs an agent on a fresh request reconstructs
+ * the working memory from persisted events rather than a live session. The
+ * replayed history is the ONLY working memory the continued model has, so it
+ * MUST carry tool-result content and be bounded against the context window.
+ *
+ * Complements M1 Phase 3 `runToCompletion` (the STATEFUL path, where the session
+ * preserves history). Pure, sync, dependency-free; reuses the SDK's own
+ * `truncateWithMarker` for per-item caps (Rule 9). Design: blueprint
+ * `m1-continuation-history` ADRs D1-D5; first-party baseline
+ * `theocode/server/lib/continuation-history.ts`.
+ *
+ * @public
+ */
+import type { StoredMessage } from "../../../types/conversation-storage.js";
+import type { SDKMessage } from "../../../types/messages.js";
+/**
+ * Options for {@link buildReplayHistory}.
+ *
+ * @public
+ */
+export interface ReplayHistoryOptions {
+    /** The continued model's context window, in tokens. Drives the char budget. */
+    contextWindowTokens: number;
+    /** Tokens held back for system + continuation prompt + reply. Default 8000. */
+    reserveTokens?: number;
+    /**
+     * Max characters for a single oversized turn before it is truncated (never
+     * dropped). Default `floor(budgetChars / 2)`. Guarded to ≥ 0.
+     */
+    perItemCap?: number;
+}
+/**
+ * Rebuild a bounded replay history from `base` (prior durable turns) plus the
+ * `events` of the latest round. Returns a NEW array; never mutates inputs.
+ *
+ * @public
+ */
+export declare function buildReplayHistory(base: readonly StoredMessage[], events: readonly SDKMessage[], options: ReplayHistoryOptions): StoredMessage[];

package/dist/internal/runtime/hooks/hooks-frontmatter.d.ts

@@ -11,11 +11,11 @@
 export declare const HOOK_EVENTS: readonly ["preRun", "postRun", "preToolUse", "postToolUse", "stop"];
 export declare const HookFrontmatterSchema: z.ZodObject<{
     event: z.ZodEnum<{
-        stop: "stop";
         preRun: "preRun";
         postRun: "postRun";
         preToolUse: "preToolUse";
         postToolUse: "postToolUse";
+        stop: "stop";
     }>;
     matcher: z.ZodString;
     command: z.ZodString;

package/dist/internal/runtime/skills/discover-skills.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A discovered skill's metadata. The skill BODY is never included — only the
+ * strict frontmatter fields plus the resolved `source` path.
+ *
+ * Public via `@theokit/sdk/skills`.
+ *
+ * @public
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    /** Absolute path to the discovered `SKILL.md`. */
+    source: string;
+    category?: string;
+    dependencies?: string[];
+}
+/**
+ * Information passed to `onInvalidSkill` when a `SKILL.md` is present but its
+ * frontmatter is malformed (missing required field or invalid YAML).
+ *
+ * @public
+ */
+export interface InvalidSkillInfo {
+    /** The skill directory name (used as the fallback skill name). */
+    name: string;
+    /** Absolute path to the offending `SKILL.md`. */
+    source: string;
+    /** Typed reason: `missing_frontmatter` or `schema_invalid`. */
+    code: string;
+    message: string;
+}
+/**
+ * Options for {@link discoverSkills}.
+ *
+ * @public
+ */
+export interface DiscoverSkillsOptions {
+    /**
+     * Called once per directory that contains a `SKILL.md` with malformed
+     * frontmatter. The skill is excluded from the result; discovery continues
+     * (strict-frontmatter ADR / EC-5). A directory WITHOUT a `SKILL.md` is NOT a
+     * malformed skill and does not trigger this callback.
+     *
+     * Default: no-op (a library primitive must not write to the consumer's
+     * stderr by default).
+     */
+    onInvalidSkill?: (info: InvalidSkillInfo) => void;
+}
+/**
+ * Discover `SKILL.md` skills under an arbitrary directory.
+ *
+ * For each immediate subdirectory `<dir>/<name>/` containing a `SKILL.md`, the
+ * file's strict YAML frontmatter is parsed (`name`/`description` required;
+ * `category`/`dependencies` optional). Malformed skills are skipped (optionally
+ * reported via {@link DiscoverSkillsOptions.onInvalidSkill}); a subdirectory
+ * whose realpath escapes `dir` (via symlink) is skipped (symlink-escape guard,
+ * reusing `@theokit/sdk/path-safety`).
+ *
+ * NEVER throws: a missing, unreadable, or non-directory `dir` yields `[]`.
+ *
+ * Discovery order follows the filesystem `readdir` order (OS-dependent). Sort
+ * the result before {@link buildSkillsBlock} if a stable block order matters.
+ *
+ * Public via `@theokit/sdk/skills`.
+ *
+ * @public
+ */
+export declare function discoverSkills(dir: string, options?: DiscoverSkillsOptions): Promise<Skill[]>;

package/dist/internal/runtime/skills/skills-block.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Render the `<skills>` system-prompt block from a skill list.
+ *
+ * Input is the structural subset `{ name, description }` — the skill BODY is
+ * NOT in the type, so it cannot leak into the prompt. Both fields are passed
+ * through `escapeBlockBody` to neutralise prompt-injection vectors hidden in
+ * user-controlled SKILL.md frontmatter (injection-escape ADR).
+ *
+ * Returns `undefined` for an empty list so the caller can omit the block.
+ *
+ * Public via `@theokit/sdk/skills`.
+ *
+ * @public
+ */
+export declare function buildSkillsBlock(skills: ReadonlyArray<{
+    name: string;
+    description: string;
+}>): string | undefined;

package/dist/internal/runtime/skills/subagent-tool-scope.d.ts

@@ -0,0 +1,25 @@
+import type { AgentDefinition } from "../../../types/agent.js";
+/**
+ * Resolve a sub-agent's tool whitelist from its {@link AgentDefinition.tools}
+ * (M4-6). Returns a `Set` of allowed tool names when `tools` is a non-empty
+ * array, else `undefined` (unscoped — the sub-agent inherits the parent's full
+ * toolset). The `Set` is the exact shape `withToolWhitelist` /
+ * `ForkOptions.allowedTools` consume.
+ *
+ * @public
+ */
+export declare function subagentToolWhitelist(definition: AgentDefinition): Set<string> | undefined;
+/**
+ * Run `fn` under the sub-agent's tool whitelist (M4-6). When the definition
+ * declares `tools`, the run executes inside `withToolWhitelist(set, fn)` — so
+ * every tool call the sub-agent makes is vetoed at dispatch (`checkToolWhitelist`,
+ * the same enforcement forks use) unless its canonical name is whitelisted: a
+ * `tools: ["read_file"]` sub-agent provably cannot call `write_file`/`shell_exec`.
+ * Enforcement is `withToolWhitelist`, NOT `PermissionEngine`.
+ *
+ * An unscoped definition (no/empty `tools`) runs `fn` directly — the parent's
+ * full toolset is preserved.
+ *
+ * @public
+ */
+export declare function withSubagentToolScope<T>(definition: AgentDefinition, fn: () => Promise<T>): Promise<T>;

package/dist/messages.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+// src/messages.ts
+function assistantText(msg) {
+  if (msg.type !== "assistant") {
+    return "";
+  }
+  return msg.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+}
+function extractToolUses(msg) {
+  if (msg.type !== "assistant") {
+    return [];
+  }
+  return msg.message.content.filter((block) => block.type === "tool_use");
+}
+function costAmountUsd(cost) {
+  return cost?.amountUsd;
+}
+
+exports.assistantText = assistantText;
+exports.costAmountUsd = costAmountUsd;
+exports.extractToolUses = extractToolUses;
+//# sourceMappingURL=messages.cjs.map
+//# sourceMappingURL=messages.cjs.map

package/dist/messages.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/messages.ts"],"names":[],"mappings":";;;AAmBO,SAAS,cAAc,GAAA,EAAyB;AACrD,EAAA,IAAI,GAAA,CAAI,SAAS,WAAA,EAAa;AAC5B,IAAA,OAAO,EAAA;AAAA,EACT;AACA,EAAA,OAAO,IAAI,OAAA,CAAQ,OAAA,CAChB,MAAA,CAAO,CAAC,UAA4D,KAAA,CAAM,IAAA,KAAS,MAAM,CAAA,CACzF,IAAI,CAAC,KAAA,KAAU,MAAM,IAAI,CAAA,CACzB,KAAK,EAAE,CAAA;AACZ;AASO,SAAS,gBAAgB,GAAA,EAAiC;AAC/D,EAAA,IAAI,GAAA,CAAI,SAAS,WAAA,EAAa;AAC5B,IAAA,OAAO,EAAC;AAAA,EACV;AACA,EAAA,OAAO,GAAA,CAAI,QAAQ,OAAA,CAAQ,MAAA,CAAO,CAAC,KAAA,KAAiC,KAAA,CAAM,SAAS,UAAU,CAAA;AAC/F;AAQO,SAAS,cAAc,IAAA,EAAqD;AACjF,EAAA,OAAO,IAAA,EAAM,SAAA;AACf","file":"messages.cjs","sourcesContent":["/**\n * Pure readers over the `SDKMessage` stream (M1-5).\n *\n * Promotes the proven first-party hand-roll (`../theocode/server/lib/sdk-mappers.ts`)\n * onto the SDK's own types so consumers stop re-implementing a wire-event mapper.\n * Every reader is pure: no I/O, no mutation of its input, deterministic.\n *\n * Public from the `@theokit/sdk/messages` sub-path. See `docs.md → Message readers`.\n */\n\nimport type { SDKMessage, ToolUseBlock } from \"./types/messages.js\";\nimport type { CostBreakdown } from \"./types/usage.js\";\n\n/**\n * Concatenate the text of an assistant message's `TextBlock`s.\n *\n * Returns `\"\"` for any non-assistant message (or an assistant with no text\n * blocks). `tool_use` blocks are ignored — only `text` blocks contribute.\n */\nexport function assistantText(msg: SDKMessage): string {\n  if (msg.type !== \"assistant\") {\n    return \"\";\n  }\n  return msg.message.content\n    .filter((block): block is Extract<typeof block, { type: \"text\" }> => block.type === \"text\")\n    .map((block) => block.text)\n    .join(\"\");\n}\n\n/**\n * Extract the `ToolUseBlock`s from an assistant message's content.\n *\n * Returns `[]` for any non-assistant message. This reads the assistant\n * message's content blocks — NOT the separate `SDKToolUseMessage`\n * (`type:\"tool_call\"`) lifecycle event, which is a different stream (ADR D2).\n */\nexport function extractToolUses(msg: SDKMessage): ToolUseBlock[] {\n  if (msg.type !== \"assistant\") {\n    return [];\n  }\n  return msg.message.content.filter((block): block is ToolUseBlock => block.type === \"tool_use\");\n}\n\n/**\n * Read the cost amount from a `CostBreakdown`, preserving the honesty contract\n * (repo ADR `D377-cost-status-closed-enum.md`): `amountUsd` is `number | undefined`\n * where `undefined` means \"cost unknown\" — distinct from a real `$0` (e.g. a\n * subscription-included route). NEVER coerced to 0.\n */\nexport function costAmountUsd(cost: CostBreakdown | undefined): number | undefined {\n  return cost?.amountUsd;\n}\n"]}

package/dist/messages.d.cts

@@ -0,0 +1,33 @@
+/**
+ * Pure readers over the `SDKMessage` stream (M1-5).
+ *
+ * Promotes the proven first-party hand-roll (`../theocode/server/lib/sdk-mappers.ts`)
+ * onto the SDK's own types so consumers stop re-implementing a wire-event mapper.
+ * Every reader is pure: no I/O, no mutation of its input, deterministic.
+ *
+ * Public from the `@theokit/sdk/messages` sub-path. See `docs.md → Message readers`.
+ */
+import type { SDKMessage, ToolUseBlock } from "./types/messages.js";
+import type { CostBreakdown } from "./types/usage.js";
+/**
+ * Concatenate the text of an assistant message's `TextBlock`s.
+ *
+ * Returns `""` for any non-assistant message (or an assistant with no text
+ * blocks). `tool_use` blocks are ignored — only `text` blocks contribute.
+ */
+export declare function assistantText(msg: SDKMessage): string;
+/**
+ * Extract the `ToolUseBlock`s from an assistant message's content.
+ *
+ * Returns `[]` for any non-assistant message. This reads the assistant
+ * message's content blocks — NOT the separate `SDKToolUseMessage`
+ * (`type:"tool_call"`) lifecycle event, which is a different stream (ADR D2).
+ */
+export declare function extractToolUses(msg: SDKMessage): ToolUseBlock[];
+/**
+ * Read the cost amount from a `CostBreakdown`, preserving the honesty contract
+ * (repo ADR `D377-cost-status-closed-enum.md`): `amountUsd` is `number | undefined`
+ * where `undefined` means "cost unknown" — distinct from a real `$0` (e.g. a
+ * subscription-included route). NEVER coerced to 0.
+ */
+export declare function costAmountUsd(cost: CostBreakdown | undefined): number | undefined;

package/dist/messages.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure readers over the `SDKMessage` stream (M1-5).
+ *
+ * Promotes the proven first-party hand-roll (`../theocode/server/lib/sdk-mappers.ts`)
+ * onto the SDK's own types so consumers stop re-implementing a wire-event mapper.
+ * Every reader is pure: no I/O, no mutation of its input, deterministic.
+ *
+ * Public from the `@theokit/sdk/messages` sub-path. See `docs.md → Message readers`.
+ */
+import type { SDKMessage, ToolUseBlock } from "./types/messages.js";
+import type { CostBreakdown } from "./types/usage.js";
+/**
+ * Concatenate the text of an assistant message's `TextBlock`s.
+ *
+ * Returns `""` for any non-assistant message (or an assistant with no text
+ * blocks). `tool_use` blocks are ignored — only `text` blocks contribute.
+ */
+export declare function assistantText(msg: SDKMessage): string;
+/**
+ * Extract the `ToolUseBlock`s from an assistant message's content.
+ *
+ * Returns `[]` for any non-assistant message. This reads the assistant
+ * message's content blocks — NOT the separate `SDKToolUseMessage`
+ * (`type:"tool_call"`) lifecycle event, which is a different stream (ADR D2).
+ */
+export declare function extractToolUses(msg: SDKMessage): ToolUseBlock[];
+/**
+ * Read the cost amount from a `CostBreakdown`, preserving the honesty contract
+ * (repo ADR `D377-cost-status-closed-enum.md`): `amountUsd` is `number | undefined`
+ * where `undefined` means "cost unknown" — distinct from a real `$0` (e.g. a
+ * subscription-included route). NEVER coerced to 0.
+ */
+export declare function costAmountUsd(cost: CostBreakdown | undefined): number | undefined;

package/dist/messages.js

@@ -0,0 +1,20 @@
+// src/messages.ts
+function assistantText(msg) {
+  if (msg.type !== "assistant") {
+    return "";
+  }
+  return msg.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+}
+function extractToolUses(msg) {
+  if (msg.type !== "assistant") {
+    return [];
+  }
+  return msg.message.content.filter((block) => block.type === "tool_use");
+}
+function costAmountUsd(cost) {
+  return cost?.amountUsd;
+}
+
+export { assistantText, costAmountUsd, extractToolUses };
+//# sourceMappingURL=messages.js.map
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/messages.ts"],"names":[],"mappings":";AAmBO,SAAS,cAAc,GAAA,EAAyB;AACrD,EAAA,IAAI,GAAA,CAAI,SAAS,WAAA,EAAa;AAC5B,IAAA,OAAO,EAAA;AAAA,EACT;AACA,EAAA,OAAO,IAAI,OAAA,CAAQ,OAAA,CAChB,MAAA,CAAO,CAAC,UAA4D,KAAA,CAAM,IAAA,KAAS,MAAM,CAAA,CACzF,IAAI,CAAC,KAAA,KAAU,MAAM,IAAI,CAAA,CACzB,KAAK,EAAE,CAAA;AACZ;AASO,SAAS,gBAAgB,GAAA,EAAiC;AAC/D,EAAA,IAAI,GAAA,CAAI,SAAS,WAAA,EAAa;AAC5B,IAAA,OAAO,EAAC;AAAA,EACV;AACA,EAAA,OAAO,GAAA,CAAI,QAAQ,OAAA,CAAQ,MAAA,CAAO,CAAC,KAAA,KAAiC,KAAA,CAAM,SAAS,UAAU,CAAA;AAC/F;AAQO,SAAS,cAAc,IAAA,EAAqD;AACjF,EAAA,OAAO,IAAA,EAAM,SAAA;AACf","file":"messages.js","sourcesContent":["/**\n * Pure readers over the `SDKMessage` stream (M1-5).\n *\n * Promotes the proven first-party hand-roll (`../theocode/server/lib/sdk-mappers.ts`)\n * onto the SDK's own types so consumers stop re-implementing a wire-event mapper.\n * Every reader is pure: no I/O, no mutation of its input, deterministic.\n *\n * Public from the `@theokit/sdk/messages` sub-path. See `docs.md → Message readers`.\n */\n\nimport type { SDKMessage, ToolUseBlock } from \"./types/messages.js\";\nimport type { CostBreakdown } from \"./types/usage.js\";\n\n/**\n * Concatenate the text of an assistant message's `TextBlock`s.\n *\n * Returns `\"\"` for any non-assistant message (or an assistant with no text\n * blocks). `tool_use` blocks are ignored — only `text` blocks contribute.\n */\nexport function assistantText(msg: SDKMessage): string {\n  if (msg.type !== \"assistant\") {\n    return \"\";\n  }\n  return msg.message.content\n    .filter((block): block is Extract<typeof block, { type: \"text\" }> => block.type === \"text\")\n    .map((block) => block.text)\n    .join(\"\");\n}\n\n/**\n * Extract the `ToolUseBlock`s from an assistant message's content.\n *\n * Returns `[]` for any non-assistant message. This reads the assistant\n * message's content blocks — NOT the separate `SDKToolUseMessage`\n * (`type:\"tool_call\"`) lifecycle event, which is a different stream (ADR D2).\n */\nexport function extractToolUses(msg: SDKMessage): ToolUseBlock[] {\n  if (msg.type !== \"assistant\") {\n    return [];\n  }\n  return msg.message.content.filter((block): block is ToolUseBlock => block.type === \"tool_use\");\n}\n\n/**\n * Read the cost amount from a `CostBreakdown`, preserving the honesty contract\n * (repo ADR `D377-cost-status-closed-enum.md`): `amountUsd` is `number | undefined`\n * where `undefined` means \"cost unknown\" — distinct from a real `$0` (e.g. a\n * subscription-included route). NEVER coerced to 0.\n */\nexport function costAmountUsd(cost: CostBreakdown | undefined): number | undefined {\n  return cost?.amountUsd;\n}\n"]}