@theokit/sdk 1.5.0

package/dist/internal/runtime/local-agent-memory-direct.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agent.memory` direct API implementation (T2.2, ADR D141 / D142).
+ *
+ * Builds an `AgentMemory` impl over whichever third-party adapters
+ * the `PluginManager` aggregated. Lazy-resolves the adapter list on
+ * first access (EC-I: `initialize()` fires exactly once on first
+ * write/recall). Multi-adapter fan-out for writes; merge + dedupe by
+ * content for recalls.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/local-agent-memory-hooks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Memory hook wiring for `LocalAgent.sendLocked` (T2.1, ADRs D141 / D145).
+ *
+ * Two helpers extracted to keep `local-agent.ts` under G8 (≤400 LoC):
+ *  - `applyPreUserSendHook` — fires `pre_user_send`, caps recalled context
+ *    at `maxRecallContextBytes` (EC-A), injects `<memory-context>` fence.
+ *  - `wrapRunWithPostReplyHook` — Proxy-wraps the Run so
+ *    `post_assistant_reply` fires once after `wait()` (fire-and-forget,
+ *    errors → stderr per EC-O).
+ *
+ * @internal
+ */
+import type { Run, SDKUserMessage, SendOptions } from "../../types/run.js";
+import type { PluginManager } from "../plugins/manager.js";
+/**
+ * EC-A + EC-G + EC-H: fire `pre_user_send` hooks, cap recalled context,
+ * and prepend it as a `<memory-context>` fence around the original
+ * user text. Returns the (possibly wrapped) message preserving the
+ * `string | SDKUserMessage` shape the caller passed in.
+ */
+export declare function applyPreUserSendHook(args: {
+    pluginManager: PluginManager;
+    agentId: string;
+    options: AgentOptions;
+    original: string | SDKUserMessage;
+    userText: string;
+    sendOptions: SendOptions;
+}): Promise<string | SDKUserMessage>;
+/**
+ * Wrap a `Run` so `post_assistant_reply` fires once after `wait()`.
+ * Fire-and-forget — errors are surfaced to stderr (EC-O) so the caller
+ * never blocks on memory sync. Returns a Proxy preserving all other
+ * Run methods (stream, cancel, conversation).
+ */
+export declare function wrapRunWithPostReplyHook(args: {
+    pluginManager: PluginManager;
+    agentId: string;
+    options: AgentOptions;
+    run: Run;
+    userText: string;
+}): Run;

package/dist/internal/runtime/local-agent-memory.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/local-agent-personality-extensions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Personality-preset runtime extensions for {@link LocalAgent}.
+ *
+ * Extracted from `local-agent.ts` to keep that file under the 400-LoC
+ * guard (G8). The functions here implement the personality-related
+ * behaviour declared by ADRs D160-D168:
+ *
+ * - `resolveActivePersonalityPreset` — read the active preset honoring
+ *   the fork ALS snapshot (D168 / EC-A).
+ * - `ensurePersonalityRegistryIfNeeded` — lazy-load registry when ANY
+ *   slug is active.
+ * - `applyPersonalityOverlay` — overlay preset body on the base prompt.
+ * - `localAgentUsePersonality` — the full `Agent.usePersonality` flow:
+ *   fork-scope no-op, registry lazy-load, then delegate to
+ *   `performPersonalitySwitch` under the per-agent send mutex (EC-E).
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/local-agent-plugins.d.ts

@@ -0,0 +1,13 @@
+/**
+ * EC-1 (edge-case review): runtime discrimination between legacy plugin
+ * metadata `{ enabled: string[] }` (v1.2 shape) and the new code Plugin
+ * objects (v1.3+ Plugin discriminated union).
+ *
+ * Telegram-pro + 7 examples pass `plugins: { enabled: ["openrouter"] }`
+ * — an OBJECT, not an array. The new Plugin[] is an ARRAY. We discriminate
+ * by `Array.isArray` first, then by shape per-kind.
+ *
+ * @internal
+ */
+export declare function isCodePlugin(p: unknown): p is Plugin;
+export declare function extractCodePlugins(value: unknown): Plugin[];

package/dist/internal/runtime/local-agent-runtime-extensions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Background-work runtime extensions for {@link LocalAgent} (T4.2 + T4.3).
+ *
+ * Extracted from `local-agent.ts` to keep that file under the 400-LoC
+ * guard (G8). The two helpers below implement
+ * `LocalAgent.runUntil(goal, options)` and `LocalAgent.fork(options)`
+ * by lazy-importing the implementation modules and resolving
+ * `Agent.create` through the DI registry (see
+ * `agent-factory-registry.ts` for the cycle-avoidance rationale).
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/local-agent-task-wrap.d.ts

@@ -0,0 +1,11 @@
+/**
+ * T3.2 — register a `Run` from `LocalAgent.send({ task: ... })` as a
+ * Task in the observable registry. Extracted from `local-agent.ts`
+ * to keep that file under the 400-LoC quality gate (G8).
+ *
+ * @internal
+ */
+export declare function registerRunAsTask(run: Run, agentId: string, taskOpt: true | {
+    id?: string;
+    meta?: Record<string, unknown>;
+}, userText: string): void;

package/dist/internal/runtime/local-agent.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/local-run.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/memory-store.d.ts

@@ -0,0 +1,4 @@
+import { type MemoryConfig, type MemoryFact, redactSecrets } from "../memory/types.js";
+export { redactSecrets };
+export declare function readMemoryFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;
+export declare function appendMemoryFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;

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

@@ -0,0 +1,17 @@
+/**
+ * Plugin manifest frontmatter schema (ADR D76).
+ *
+ * Used by the markdown plugin loader (`plugins/<name>/PLUGIN.md`). Matches
+ * the legacy `plugin.json` shape consumed by `plugins-manager.ts`:
+ * `{ name, version, capabilities, entry }`. Frontmatter is flat — no
+ * nested provider object (parseSimpleYaml doesn't support nesting).
+ *
+ * @internal
+ */
+export declare const PluginFrontmatterSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    entry: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginFrontmatter = z.infer<typeof PluginFrontmatterSchema>;

package/dist/internal/runtime/plugins-manager.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/post-run-lifecycle.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/providers-manager.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/real-cloud-run.d.ts

@@ -0,0 +1,2 @@
+import type { Run } from "../../types/run.js";
+export declare function createRealCloudRun(options: CreateRealCloudRunOptions): Run;

package/dist/internal/runtime/real-local-run.d.ts

@@ -0,0 +1,2 @@
+import type { Run } from "../../types/run.js";
+export declare function createRealLocalRun(options: CreateRealLocalRunOptions): Run;

package/dist/internal/runtime/run-registry.d.ts

@@ -0,0 +1,5 @@
+import type { Run } from "../../types/run.js";
+export declare function registerRun(run: Run): void;
+export declare function getRun(runId: string): Run | undefined;
+export declare function listRunsByAgent(agentId: string): Run[];
+export declare function clearRunRegistry(): void;

package/dist/internal/runtime/run-until.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Goal-driven Ralph loop (T3.2, ADRs D115-D121).
+ *
+ * `runUntilImpl` is an `AsyncGenerator<GoalEvent, GoalResult, void>`:
+ * yields events as the loop progresses, returns the final result when
+ * the goal completes, fails, or is paused. The auxiliary judge model is
+ * injected via `deps.judge` so the generator stays free of the `Agent`
+ * façade import.
+ *
+ * EC-C fix: pre-aborted signals emit only `[paused]`, not `[active, paused]`.
+ * EC-D: `maxTurns: 0` is supported (vacuous yield active → failed).
+ *
+ * @internal
+ */
+import type { GoalEvent, GoalOptions, GoalResult } from "../../types/goal-events.js";
+import type { JudgeContext, JudgeOptions } from "../judge/judge-call.js";
+import type { JudgeResult } from "../judge/types.js";
+/** DI contract: the judge is the only external touchpoint. */
+export interface RunUntilDeps {
+    judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;
+}
+export declare function runUntilImpl(agent: SDKAgent, goal: string, options: GoalOptions | undefined, deps: RunUntilDeps): AsyncGenerator<GoalEvent, GoalResult, void>;

package/dist/internal/runtime/shell-tool.d.ts

@@ -0,0 +1,7 @@
+export interface ShellExecuteResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+}
+export declare function runShell(options: ShellExecuteOptions): Promise<ShellExecuteResult>;

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

@@ -0,0 +1 @@
+export type SkillFrontmatterErrorCode = "missing_frontmatter" | "schema_invalid";

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

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/spawn-collect.d.ts

@@ -0,0 +1,8 @@
+export interface SpawnCollectResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    spawnError?: Error;
+}
+export declare function spawnAndCollect(options: SpawnCollectOptions): Promise<SpawnCollectResult>;

package/dist/internal/runtime/subagents-loader.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/escape.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/local-assembly.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/pipeline.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/providers/active-memory-provider.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/providers/base-provider.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/providers/context-provider.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/providers/memory-provider.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/providers/skills-provider.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/safe-call.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/system-prompt/types.d.ts

@@ -0,0 +1,5 @@
+export interface ContextSourceForAssembly {
+    name: string;
+    status: "included" | "excluded" | "summarized";
+    tokens: ReadonlyArray<string>;
+}

package/dist/internal/runtime/system-prompt.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/validate-agent-options.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/runtime/workspace-dir.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Entry returned by `readWorkspaceDir`. Mirrors the subset of
+ * `fs.Dirent` the file-based loaders use.
+ */
+export interface WorkspaceDirEntry {
+    name: string;
+    isDirectory(): boolean;
+    isFile(): boolean;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Tiny YAML-frontmatter parser shared by the file-based loaders (skills,
+ * subagents, hooks, context, plugins). Supports four scalar shapes:
+ *
+ *   key: bar              → "bar"        (string)
+ *   key: 42               → 42           (number)
+ *   key: true             → true         (boolean)
+ *   key: [a, b, c]        → ["a","b","c"](string[])
+ *   key:                  → undefined    (caller's Zod default kicks in)
+ *
+ * Limitations (intentional — keep parser tiny, no dep):
+ * - No nested objects (use flat keys like `providerId` not `provider.id`).
+ * - No quoted strings — `match: "1"` becomes the literal 3-char string `"1"`.
+ * - List values cannot contain a literal comma inside an element; the
+ *   `tags: [a,b, c]` splitter is greedy on `,`. Use multi-line lists or
+ *   reword if you need this.
+ *
+ * @internal
+ */
+export declare function parseSimpleYaml(text: string): Record<string, FrontmatterValue | undefined>;

package/dist/internal/scorers/llm-judge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * LLM-as-judge scorer implementation (ADR D205).
+ *
+ * Builds a transient agent with the judge model + apiKey, calls
+ * `Agent.prompt` with a structured judge prompt, parses score from
+ * the response. Returns 0 (with diagnostic reason) on any parse failure.
+ *
+ * @internal
+ */
+import type { ModelSelection } from "../../types/agent.js";
+import type { Score } from "../../types/eval.js";
+import type { ProviderRoutingSettings } from "../../types/providers.js";
+export interface LlmJudgeOptions {
+    readonly model: ModelSelection;
+    readonly apiKey: string;
+    readonly criteria: string;
+    /** "continuous" → [0, 1] real number. "discrete" → 0 or 1 only. Default: continuous. */
+    readonly rubric?: "continuous" | "discrete";
+    readonly providers?: ProviderRoutingSettings;
+}
+export declare function llmJudgeScore(options: LlmJudgeOptions & {
+    output: string;
+    expected?: unknown;
+}): Promise<Score>;

package/dist/internal/security/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Barrel for the canonical secret-redaction module (ADRs D68-D73).
+ *
+ * Consumers across the SDK output boundaries import from here:
+ * `internal/errors/mappers/shared.ts`, `internal/telemetry/tracer.ts`,
+ * `internal/runtime/agent-session-store.ts`,
+ * `internal/memory/migrate-sqlite-to-lance.ts`.
+ *
+ * @internal
+ */
+export { addPattern, maskToken, redactSecrets } from "./redact.js";

package/dist/internal/security/path-guard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Canonical path-guard module (ADRs D79-D81).
+ *
+ * Three primitives + one typed error:
+ *   - `safePathJoin(base, ...parts)` — resolve THEN prefix-check (ADR D80).
+ *   - `assertNoSymlinkEscape(path, base)` — `realpathSync` resolves entire
+ *     symlink chain (EC-1 fix; Hermes v0.2 #386, #61).
+ *   - `sanitizeIdentifier(input, { maxLen })` — strict grammar
+ *     `^[a-z0-9][a-z0-9-_]*$` (ADR D81; case-insensitive on input,
+ *     lowercase on output).
+ *   - `PathTraversalError` — extends ConfigurationError with code
+ *     `path_traversal` (ADR D65: no new hierarchy).
+ *
+ * Wire at all sites where user input becomes a path. CI lint gate
+ * `tests/lint/no-unguarded-path-input.test.ts` prevents regression
+ * (ADR D85).
+ *
+ * @internal
+ */
+import { ConfigurationError } from "../../errors.js";
+/**
+ * Thrown when an agent tool is asked to read or write a sensitive path
+ * that the blocklist forbids (`.env`, `.git/`, `node_modules/`, `.theo/`,
+ * lock files). Distinct from `PathTraversalError` because the path is
+ * lexically inside the project — it is just sensitive.
+ *
+ * Extends `ConfigurationError` (no new error hierarchy per ADR D65).
+ *
+ * @public
+ */
+export declare class ForbiddenPathError extends ConfigurationError {
+    readonly name: string;
+    constructor(path: string);
+}
+/**
+ * Decide whether a project-relative path points to a known-sensitive file
+ * that a coding agent must not read or write.
+ *
+ * Universal blocklist (works for any agent operating on a project tree):
+ *
+ *   - `.env`, `.env.<anything>` — except `.env.example` (template safe to read)
+ *   - `.git/` — version control internals
+ *   - `node_modules/` — dependency cache (changes don't belong to the user)
+ *   - `.theo/` — TheoKit build artefacts / state
+ *   - Lock files at any depth: `pnpm-lock.yaml`, `package-lock.json`,
+ *     `yarn.lock`, `bun.lockb`
+ *
+ * Operates on path segments (forward-slash normalized). Cross-platform safe.
+ *
+ * Use together with `safePathJoin` + `assertNoSymlinkEscape`: the former two
+ * defeat traversal, this one defeats reading a file that is lexically inside
+ * the project but should not be agent-visible.
+ *
+ * @public
+ */
+export declare function isForbiddenPath(input: string): boolean;

package/dist/internal/security/redact.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Canonical secret redaction module (ADRs D68-D73).
+ *
+ * Single source of truth for credential pattern masking across the SDK.
+ * Wired at output boundaries: `ErrorMetadata.raw` (mappers/shared.ts),
+ * telemetry span attributes (telemetry/tracer.ts), transcript JSONL
+ * appends (agent-session-store.ts), migration logger output
+ * (memory/migrate-sqlite-to-lance.ts).
+ *
+ * - D68: central module, single source of truth (replaces 2 duplicates)
+ * - D69: env snapshot at module init (prompt-injection defense)
+ * - D70: ON by default, warn on opt-out
+ * - D71: two-bucket masking — short fully masked, long preserves prefix+suffix
+ * - D72: `codeFile` opt-out for legitimate prefix-shaped content
+ * - D73: redact at OUTPUT boundaries, not at storage
+ *
+ * @internal
+ */
+export declare function redactSecrets(text: unknown, opts?: {
+    codeFile?: boolean;
+}): string;

package/dist/internal/structured-output-helpers.d.ts

@@ -0,0 +1,54 @@
+import type { z as ZodNamespace, ZodType } from "zod";
+import type { AgentOptions, CustomTool, LocalOptions, ModelSelection } from "../types/agent.js";
+import type { ProviderRoutingSettings } from "../types/providers.js";
+/**
+ * Load Zod via createRequire (it's an optional peer dep). Throws a typed
+ * ConfigurationError if Zod isn't installed.
+ */
+export declare function requireZod(): typeof ZodNamespace;
+/**
+ * Build the synthetic `output` tool used by both `generateObject` and
+ * `streamObject`. The handler captures the raw input on first call only
+ * (EC-D10 / EC-6: parallel tool use in Claude 3.5+ may invoke `output`
+ * twice; later calls are ignored).
+ */
+export declare function makeOutputTool(jsonSchema: Record<string, unknown>, onCapture: (input: unknown) => string | Promise<string> | undefined): CustomTool;
+/**
+ * Assemble the AgentOptions for the transient agent. Shared shape:
+ * model + local + tools[output] + systemPrompt + apiKey.
+ */
+export declare function buildTransientAgentOptions(params: {
+    model: ModelSelection;
+    local: LocalOptions;
+    outputTool: CustomTool;
+    systemPrompt?: string;
+    apiKey?: string;
+    providers?: ProviderRoutingSettings;
+}): AgentOptions;
+/**
+ * Best-effort extraction of token usage from a run result. Local runtimes
+ * may not expose it; default to zeros.
+ */
+export declare function extractUsage(result: unknown): {
+    inputTokens: number;
+    outputTokens: number;
+};
+/**
+ * Build the user-message prompt that instructs the model to call the
+ * `output` tool with a schema-matched structured answer.
+ */
+export declare function buildToolPrompt(prompt: string): string;
+/**
+ * One-shot setup shared by both `generateObject` and `streamObject`. Loads
+ * Zod, computes the JSON schema, primes the captured-raw / usage / retry
+ * state. Returns the values needed by the caller's loop.
+ */
+export declare function setupStructuredOutput<T extends ZodType>(schema: T, maxRetries: number | undefined): {
+    z: typeof ZodNamespace;
+    jsonSchema: Record<string, unknown>;
+    maxRetries: number;
+    initialUsage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+};

package/dist/internal/task/registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `TaskRegistry` — the singleton coordinating Task submit/list/get/cancel/
+ * subscribe. Wraps the pluggable `TaskStore` (D364), the `AsyncSemaphore`
+ * (D135 / D369) and a per-task `RingBuffer<TaskEvent>` (D372) for
+ * late-attach replay.
+ *
+ * Edge cases absorbed:
+ *   - EC-3: work-fn invocation goes through `Promise.resolve().then(...)`
+ *     so synchronous throws become rejected promises.
+ *   - EC-4: pre-aborted signal short-circuits to `cancelled` without
+ *     acquiring a semaphore slot.
+ *   - EC-7: cross-process cancel via the `cancelRequested` flag on
+ *     `TaskHandle`. Registry polls at start + each progress event.
+ *   - EC-9: store-update failures are caught + logged; the event is
+ *     still emitted so subscribers always observe a terminal event.
+ *   - EC-10: subscribe iterator implements `return()` for leak-free
+ *     cleanup.
+ *   - EC-11: reentrant submit (work-fn calling `Task.submit`) uses an
+ *     ALS marker to bypass the semaphore queue, avoiding deadlock under
+ *     low concurrency caps.
+ *
+ * @internal
+ */
+import { type TaskCancelResult, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskStoreOptions } from "../../types/task.js";
+export interface TaskRegistryOptions {
+    readonly store?: TaskStoreOptions;
+    readonly maxConcurrent?: number;
+    readonly retentionMs?: number;
+}
+export interface TaskWorkContext {
+    readonly signal: AbortSignal;
+    emit(payload: unknown): void;
+}
+type WorkFn<T> = (ctx: TaskWorkContext) => Promise<T> | T;
+export declare function __resetTaskRegistryForTests(): void;
+export declare function __getSubscribersCountForTests(taskId: string): number;
+export declare function __getCancelRequestedForTests(_taskId: string): boolean | undefined;
+export declare function configure(opts: TaskRegistryOptions): void;
+interface SubmitInternal<T> {
+    readonly kind: TaskKind;
+    readonly work: WorkFn<T>;
+    readonly id?: string;
+    readonly meta?: Record<string, unknown>;
+    readonly signal?: AbortSignal;
+    /** When true (adapter-internal), the validator allows reserved prefixes. */
+    readonly allowReservedPrefix?: boolean;
+}
+/**
+ * Submit a task. Validates id (D368, EC-5 via allowReservedPrefix),
+ * handles pre-aborted signals (EC-4), enforces single-flight by id
+ * (D367), runs work under semaphore (D369/EC-11 reentrant bypass),
+ * and produces the canonical event stream (D366).
+ */
+export declare function submit<T>(internal: SubmitInternal<T>): Promise<TaskHandle>;
+export declare function list(filter?: TaskFilter): Promise<TaskHandle[]>;
+export declare function get(id: string): Promise<TaskHandle | undefined>;
+export declare function cancel(id: string, reason?: string): Promise<TaskCancelResult>;
+export declare const subscribe: (id: string) => AsyncIterable<TaskEvent>;
+/** Manual trigger for tests. */
+export declare function evictNow(now?: number): Promise<number>;
+export {};

package/dist/internal/task/ring-buffer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bounded FIFO ring buffer for late-attach replay (ADR D372).
+ *
+ * Push always succeeds; when the buffer is at capacity the oldest
+ * entry is dropped and the `truncated` flag flips to `true`. Drain
+ * returns a snapshot + the current truncated flag.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/task/store.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `TaskStore` interface + 2 implementations (ADR D364).
+ *
+ *   - `InMemoryTaskStore` — default, transient, single-process.
+ *   - `JsonFileTaskStore` — opt-in, one JSON file per task under a
+ *     dedicated dir; single-process invariant (EC-15 documented).
+ *
+ * Edge cases absorbed:
+ *   - EC-1: constructor auto-creates dir (mkdirSync recursive idempotent).
+ *   - EC-2: every method validates the task id against the public
+ *     grammar (D368) BEFORE doing any path I/O — path-traversal defense.
+ *   - EC-6: `list()` returns `[]` on ENOENT (fresh install path).
+ *   - EC-8: `list()` skips `.tmp.*` orphan files left by interrupted
+ *     atomic writes.
+ *   - EC-14 (DOCUMENT): `list()` JSDoc documents the 256-row hard cap
+ *     and the `submittedBefore` paging idiom.
+ *   - EC-15 (DOCUMENT): `JsonFileTaskStore` JSDoc documents the
+ *     single-process invariant; v0.2 SQLite covers cross-process.
+ *
+ * @internal
+ */
+import { type TaskFilter, type TaskHandle, type TaskStoreOptions } from "../../types/task.js";
+/** Storage interface used by `TaskRegistry`. */
+export interface TaskStore {
+    insert(handle: TaskHandle): Promise<void>;
+    update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined>;
+    get(id: string): Promise<TaskHandle | undefined>;
+    /**
+     * Returns at most `filter.limit ?? 100` matching handles. JsonFile
+     * backend hard-caps loaded entries at 256 — callers needing larger
+     * pages must use `submittedBefore` to walk the timeline.
+     */
+    list(filter: TaskFilter): Promise<TaskHandle[]>;
+    delete(id: string): Promise<boolean>;
+    /** Removes terminal handles whose terminal-timestamp is older than `epochMs`. */
+    evictTerminalOlderThan(epochMs: number): Promise<number>;
+}
+export declare class InMemoryTaskStore implements TaskStore {
+    private readonly map;
+    insert(handle: TaskHandle): Promise<void>;
+    update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined>;
+    get(id: string): Promise<TaskHandle | undefined>;
+    list(filter: TaskFilter): Promise<TaskHandle[]>;
+    delete(id: string): Promise<boolean>;
+    evictTerminalOlderThan(epochMs: number): Promise<number>;
+}
+export declare class JsonFileTaskStore implements TaskStore {
+    private readonly dir;
+    constructor(dir: string);
+    private filePath;
+    insert(handle: TaskHandle): Promise<void>;
+    update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined>;
+    get(id: string): Promise<TaskHandle | undefined>;
+    list(filter: TaskFilter): Promise<TaskHandle[]>;
+    delete(id: string): Promise<boolean>;
+    evictTerminalOlderThan(epochMs: number): Promise<number>;
+}
+/** Factory used by `TaskRegistry.configure` (D364). */
+export declare function getTaskStoreFor(options: TaskStoreOptions): TaskStore;

package/dist/internal/task/subscribe.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `subscribe(id)` — emits the per-task event stream (D372 ring buffer
+ * + live tail). The returned AsyncIterable implements `return()` for
+ * leak-free cleanup (EC-10).
+ *
+ * @internal
+ */
+import { type TaskEvent } from "../../types/task.js";
+import type { RingBuffer } from "./ring-buffer.js";
+export interface SubscribeDeps {
+    getBuffer(id: string): RingBuffer<TaskEvent> | undefined;
+    getOrCreateSubscriberSet(id: string): Set<(e: TaskEvent) => void>;
+    removeSubscriber(id: string, cb: (e: TaskEvent) => void): void;
+}
+export declare function buildSubscribe(deps: SubscribeDeps): (id: string) => AsyncIterable<TaskEvent>;