@theokit/sdk 1.5.0

package/dist/task-store.js

@@ -0,0 +1,233 @@
+import { mkdirSync, readdirSync } from 'fs';
+import { readFile, unlink, mkdir, open, rename } from 'fs/promises';
+import { join, dirname } from 'path';
+
+// src/internal/task/store.ts
+
+// src/errors.ts
+var TheokitAgentError = class extends Error {
+  name = "TheokitAgentError";
+  isRetryable;
+  code;
+  protoErrorCode;
+  metadata;
+  constructor(message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.isRetryable = options.isRetryable ?? false;
+    if (options.code !== void 0) this.code = options.code;
+    if (options.protoErrorCode !== void 0) this.protoErrorCode = options.protoErrorCode;
+    if (options.metadata !== void 0) this.metadata = options.metadata;
+  }
+};
+var InvalidTaskIdError = class extends TheokitAgentError {
+  name = "InvalidTaskIdError";
+  taskId;
+  constructor(message, taskId, options = {}) {
+    super(message, {
+      ...options,
+      isRetryable: false,
+      code: "invalid_task_id"
+    });
+    this.taskId = taskId;
+  }
+};
+
+// src/types/task.ts
+var TASK_ID_GRAMMAR = /^[a-z0-9][a-z0-9_-]*$/;
+function isValidTaskId(id, allowReserved) {
+  if (!TASK_ID_GRAMMAR.test(id)) return false;
+  return true;
+}
+async function replaceFileAtomic(filePath, content) {
+  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  const handle = await open(tmp, "w");
+  try {
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(tmp, filePath);
+  } catch (cause) {
+    await unlink(tmp).catch(() => void 0);
+    throw cause;
+  }
+}
+async function atomicWriteText(filePath, content) {
+  await mkdir(dirname(filePath), { recursive: true });
+  await replaceFileAtomic(filePath, content);
+}
+
+// src/internal/task/store.ts
+var JSON_LOAD_CAP = 256;
+var DEFAULT_LIST_LIMIT = 100;
+function assertValidIdForStore(id) {
+  if (!isValidTaskId(
+    id)) {
+    throw new InvalidTaskIdError(`store rejects invalid task id: ${id}`, id);
+  }
+}
+function terminalTimestamp(h) {
+  if (h.state === "finished") return h.finishedAt;
+  if (h.state === "error") return h.erroredAt;
+  if (h.state === "cancelled") return h.cancelledAt;
+  return void 0;
+}
+function isTerminal(state) {
+  return state === "finished" || state === "error" || state === "cancelled";
+}
+function matchesState(h, filter) {
+  if (filter.state === void 0) return true;
+  const states = Array.isArray(filter.state) ? filter.state : [filter.state];
+  return states.includes(h.state);
+}
+function matchesKind(h, filter) {
+  if (filter.kind === void 0) return true;
+  const kinds = Array.isArray(filter.kind) ? filter.kind : [filter.kind];
+  return kinds.includes(h.kind);
+}
+function matchesTime(h, filter) {
+  if (filter.submittedAfter !== void 0 && h.submittedAt <= filter.submittedAfter) return false;
+  if (filter.submittedBefore !== void 0 && h.submittedAt >= filter.submittedBefore) return false;
+  return true;
+}
+function matchesFilter(h, filter) {
+  return matchesState(h, filter) && matchesKind(h, filter) && matchesTime(h, filter);
+}
+function applyFilter(values, filter) {
+  const limit = filter.limit ?? DEFAULT_LIST_LIMIT;
+  const out = [];
+  for (const h of values) {
+    if (matchesFilter(h, filter)) {
+      out.push(h);
+      if (out.length >= limit) break;
+    }
+  }
+  return out;
+}
+var InMemoryTaskStore = class {
+  map = /* @__PURE__ */ new Map();
+  async insert(handle) {
+    assertValidIdForStore(handle.id);
+    this.map.set(handle.id, handle);
+  }
+  async update(id, mutate) {
+    assertValidIdForStore(id);
+    const existing = this.map.get(id);
+    if (existing === void 0) return void 0;
+    const next = mutate(existing);
+    this.map.set(id, next);
+    return next;
+  }
+  async get(id) {
+    assertValidIdForStore(id);
+    return this.map.get(id);
+  }
+  async list(filter) {
+    return applyFilter(this.map.values(), filter);
+  }
+  async delete(id) {
+    assertValidIdForStore(id);
+    return this.map.delete(id);
+  }
+  async evictTerminalOlderThan(epochMs) {
+    let count = 0;
+    for (const [id, h] of this.map.entries()) {
+      if (!isTerminal(h.state)) continue;
+      const ts = terminalTimestamp(h);
+      if (ts !== void 0 && ts < epochMs) {
+        this.map.delete(id);
+        count++;
+      }
+    }
+    return count;
+  }
+};
+var JsonFileTaskStore = class {
+  constructor(dir) {
+    this.dir = dir;
+    try {
+      mkdirSync(dir, { recursive: true });
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+    }
+  }
+  dir;
+  filePath(id) {
+    return join(this.dir, `${id}.json`);
+  }
+  async insert(handle) {
+    assertValidIdForStore(handle.id);
+    await atomicWriteText(this.filePath(handle.id), JSON.stringify(handle));
+  }
+  async update(id, mutate) {
+    assertValidIdForStore(id);
+    const existing = await this.get(id);
+    if (existing === void 0) return void 0;
+    const next = mutate(existing);
+    await atomicWriteText(this.filePath(id), JSON.stringify(next));
+    return next;
+  }
+  async get(id) {
+    assertValidIdForStore(id);
+    try {
+      const raw = await readFile(this.filePath(id), "utf8");
+      return JSON.parse(raw);
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") return void 0;
+      process.stderr.write(`[task-store] failed to read ${id}: ${err.message}
+`);
+      return void 0;
+    }
+  }
+  async list(filter) {
+    let entries;
+    try {
+      entries = readdirSync(this.dir);
+    } catch (err) {
+      if (err.code === "ENOENT") return [];
+      throw err;
+    }
+    const candidates = entries.filter((name) => name.endsWith(".json") && !name.includes(".tmp")).slice(0, JSON_LOAD_CAP);
+    const loaded = await Promise.all(
+      candidates.map(async (name) => {
+        const id = name.slice(0, -".json".length);
+        if (!isValidTaskId(id)) return void 0;
+        return this.get(id);
+      })
+    );
+    const handles = loaded.filter((h) => h !== void 0);
+    return applyFilter(handles, filter);
+  }
+  async delete(id) {
+    assertValidIdForStore(id);
+    try {
+      await unlink(this.filePath(id));
+      return true;
+    } catch (err) {
+      if (err.code === "ENOENT") return false;
+      throw err;
+    }
+  }
+  async evictTerminalOlderThan(epochMs) {
+    const handles = await this.list({ state: ["finished", "error", "cancelled"], limit: 256 });
+    let count = 0;
+    for (const h of handles) {
+      const ts = terminalTimestamp(h);
+      if (ts !== void 0 && ts < epochMs) {
+        if (await this.delete(h.id)) count++;
+      }
+    }
+    return count;
+  }
+};
+function getTaskStoreFor(options) {
+  if (options.backend === "memory") return new InMemoryTaskStore();
+  return new JsonFileTaskStore(options.dir);
+}
+
+export { InMemoryTaskStore, JsonFileTaskStore, getTaskStoreFor };
+//# sourceMappingURL=task-store.js.map
+//# sourceMappingURL=task-store.js.map

package/dist/task-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/types/task.ts","../src/internal/persistence/atomic-write.ts","../src/internal/task/store.ts"],"names":["unlink"],"mappings":"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","file":"task-store.js","sourcesContent":["import type { RunOperation } from \"./types/run.js\";\n\n/**\n * Finite, machine-readable error codes for provider-originated errors\n * (ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively\n * — adding a new variant is an explicit decision + test coverage.\n *\n * @public\n */\nexport type ErrorCode =\n  | \"rate_limit\"\n  | \"auth_failed\"\n  | \"invalid_request\"\n  | \"timeout\"\n  | \"server_error\"\n  | \"context_too_long\"\n  | \"content_filtered\"\n  | \"model_unavailable\"\n  | \"network\"\n  | \"unknown\";\n\n/**\n * Codes used by {@link AgentRunError} (Production-Readiness #3, ADR D311).\n *\n * Superset of {@link ErrorCode} extended with codes that do NOT originate\n * from a provider HTTP response:\n *\n * - `quota_exceeded` — billing limit hit (provider 402 or signalled error)\n * - `tool_runtime_error` — custom tool handler threw inside dispatch\n * - `aborted` — caller's `AbortSignal` fired (Phase 4)\n * - `invalid_model` — model id rejected by provider (400 \"model not found\")\n * - `safety_blocked` — provider safety filter blocked req or resp\n * - `provider_unreachable` — DNS/TCP/timeout/5xx at transport boundary\n *\n * The `& {}` tail keeps the literal-union ergonomics (autocomplete) while\n * accepting any string for forward compatibility with constructor calls\n * that pass arbitrary code values (legacy callers).\n *\n * @public\n */\nexport type AgentRunErrorCode =\n  | ErrorCode\n  | \"quota_exceeded\"\n  | \"tool_runtime_error\"\n  | \"aborted\"\n  | \"invalid_model\"\n  | \"safety_blocked\"\n  | \"provider_unreachable\"\n  | (string & {});\n\n/**\n * Structured context for errors that originated from a provider HTTP\n * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),\n * surface actionable diagnostics (`provider`, `endpoint`), and inspect the\n * raw response body when needed (`raw`, capped at ~2KB by the mapper).\n *\n * @public\n */\nexport interface ErrorMetadata {\n  /** Provider canonical name (e.g., `\"anthropic\"`, `\"openai\"`, `\"openrouter\"`, `\"gemini\"`). */\n  provider: string;\n  /** HTTP endpoint that failed (e.g., `\"/v1/messages\"`, `\"/v1/chat/completions\"`). */\n  endpoint: string;\n  /** Machine-readable error code (finite enum). */\n  code: ErrorCode;\n  /** HTTP status code if applicable. */\n  statusCode?: number;\n  /** Seconds to wait before retry, per provider's `retry-after` header (numeric form only). */\n  retryAfter?: number;\n  /** Raw response body for debugging (truncated to ~2KB by the mapper). */\n  raw?: unknown;\n}\n\n/**\n * Base class for all errors thrown by `@theokit/sdk`.\n *\n * Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`\n * are populated for server-originated errors when available. `metadata`\n * (ADR D65) carries structured `{ provider, endpoint, code, ... }` when\n * the error originated from a provider HTTP call.\n *\n * @public\n */\nexport class TheokitAgentError extends Error {\n  override readonly name: string = \"TheokitAgentError\";\n  readonly isRetryable: boolean;\n  readonly code?: string;\n  readonly protoErrorCode?: string;\n  readonly metadata?: ErrorMetadata;\n\n  constructor(\n    message: string,\n    options: {\n      isRetryable?: boolean;\n      code?: string;\n      protoErrorCode?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    } = {},\n  ) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    this.isRetryable = options.isRetryable ?? false;\n    if (options.code !== undefined) this.code = options.code;\n    if (options.protoErrorCode !== undefined) this.protoErrorCode = options.protoErrorCode;\n    if (options.metadata !== undefined) this.metadata = options.metadata;\n  }\n}\n\n/**\n * Invalid API key, not logged in, insufficient permissions.\n *\n * @public\n */\nexport class AuthenticationError extends TheokitAgentError {\n  override readonly name: string = \"AuthenticationError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Too many requests or usage limits exceeded.\n *\n * @public\n */\nexport class RateLimitError extends TheokitAgentError {\n  override readonly name: string = \"RateLimitError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: true });\n  }\n}\n\n/**\n * Invalid model, bad request parameters, malformed options.\n *\n * @public\n */\nexport class ConfigurationError extends TheokitAgentError {\n  override readonly name: string = \"ConfigurationError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Thrown when creating a cloud agent for a repo whose SCM provider is not\n * connected. Use `helpUrl` to point the user at the right reconnect flow.\n *\n * @public\n */\nexport class IntegrationNotConnectedError extends ConfigurationError {\n  override readonly name: string = \"IntegrationNotConnectedError\";\n  readonly provider: string;\n  readonly helpUrl: string;\n\n  constructor(\n    message: string,\n    options: {\n      provider: string;\n      helpUrl: string;\n      code?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, options);\n    this.provider = options.provider;\n    this.helpUrl = options.helpUrl;\n  }\n}\n\n/**\n * Service unavailable, timeout, transport-level failure.\n *\n * @public\n */\nexport class NetworkError extends TheokitAgentError {\n  override readonly name: string = \"NetworkError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: true });\n  }\n}\n\n/**\n * Catch-all for unclassified server or runtime errors.\n *\n * @public\n */\nexport class UnknownAgentError extends TheokitAgentError {\n  override readonly name: string = \"UnknownAgentError\";\n\n  constructor(\n    message: string,\n    options: { code?: string; cause?: unknown; metadata?: ErrorMetadata } = {},\n  ) {\n    super(message, { ...options, isRetryable: false });\n  }\n}\n\n/**\n * Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when\n * the option `{ throwOnError: true }` is set and the run terminates with\n * `status: 'error'`. Carries the structured `RunResult.error` fields so\n * callers can `catch` once and branch on `code` / `provider` instead of\n * unwrapping the run.\n *\n * Extends {@link TheokitAgentError} per ADR D65 — no new hierarchy.\n *\n * @example\n *   try {\n *     await Agent.prompt(msg, { apiKey, model, throwOnError: true });\n *   } catch (err) {\n *     if (err instanceof AgentRunError && err.code === 'auth_failed') {\n *       // bad key\n *     }\n *   }\n *\n * @public\n */\nexport class AgentRunError extends TheokitAgentError {\n  override readonly name: string = \"AgentRunError\";\n  readonly provider?: string;\n  readonly raw?: string;\n  /** Provider's request id (`x-request-id` / `request-id` header). Useful for support tickets. */\n  readonly requestId?: string;\n  /** SDK conversation id this error was raised inside. */\n  readonly conversationId?: string;\n\n  constructor(\n    message: string,\n    options: {\n      code: AgentRunErrorCode;\n      provider?: string;\n      raw?: string;\n      requestId?: string;\n      conversationId?: string;\n      retriable?: boolean;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      code: options.code,\n      cause: options.cause,\n      metadata: options.metadata,\n      // D311: most AgentRunErrors are not retriable (auth, validation, abort).\n      // Provider mappers (D314) override per-status — explicit `retriable` wins\n      // over the implicit default when supplied.\n      isRetryable: options.retriable ?? defaultRetriableForCode(options.code),\n    });\n    if (options.provider !== undefined) this.provider = options.provider;\n    if (options.raw !== undefined) this.raw = options.raw;\n    if (options.requestId !== undefined) this.requestId = options.requestId;\n    if (options.conversationId !== undefined) this.conversationId = options.conversationId;\n  }\n\n  /**\n   * Production-Readiness #3 (ADR D311): alias for `isRetryable` exposed as\n   * `retriable` to match the handoff contract. Future v2 will deprecate\n   * `isRetryable` in favor of this.\n   */\n  get retriable(): boolean {\n    return this.isRetryable;\n  }\n\n  /**\n   * D312: provider's `Retry-After` header in **milliseconds**. Mappers store\n   * the header value (seconds) in `metadata.retryAfter`; this getter\n   * multiplies by 1000 so the result composes with `Date.now()`/`setTimeout`.\n   *\n   * Returns `undefined` when no hint was provided. `0` is a legitimate value\n   * — use `=== undefined` check rather than truthy check.\n   */\n  get retryAfterMs(): number | undefined {\n    if (this.metadata?.retryAfter === undefined) return undefined;\n    return this.metadata.retryAfter * 1000;\n  }\n\n  /**\n   * D313: alias for `metadata.raw`. Provider response body for debugging.\n   * Available but NEVER serialized into `.message` (anti-leak invariant).\n   */\n  get providerError(): unknown {\n    return this.metadata?.raw;\n  }\n}\n\n/**\n * D311 helper: choose a sensible default `isRetryable` value when the\n * caller did not supply `retriable` explicitly. Conservative defaults —\n * provider mappers override per-status when they know better.\n *\n * @internal\n */\nfunction defaultRetriableForCode(code: AgentRunErrorCode): boolean {\n  switch (code) {\n    case \"rate_limit\":\n    case \"timeout\":\n    case \"server_error\":\n    case \"network\":\n    case \"provider_unreachable\":\n      return true;\n    default:\n      return false;\n  }\n}\n\n/**\n * Thrown when a {@link Run} or agent operation is not available on the current\n * runtime. Check first with `run.supports(operation)`.\n *\n * Extends {@link TheokitAgentError} (so error-catching code that branches on\n * `instanceof TheokitAgentError` continues to work) but is never retryable —\n * an unsupported operation will not become supported on retry.\n *\n * @public\n */\nexport class UnsupportedRunOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedRunOperationError\";\n  readonly operation: RunOperation;\n\n  constructor(\n    message: string,\n    operation: RunOperation,\n    options: { code?: string; cause?: unknown } = {},\n  ) {\n    super(message, {\n      ...options,\n      isRetryable: false,\n      code: options.code ?? \"unsupported_run_operation\",\n    });\n    this.operation = operation;\n  }\n}\n\n/**\n * Thrown when every credential in a per-provider pool is in cooldown\n * and no healthy key is available (ADR D133). The caller's\n * {@link import(\"./internal/llm/fallback-client.js\").FallbackLlmClient}\n * catches this and tries the next provider in the fallback chain.\n *\n * `metadata.nextRetryAt` (epoch ms) tells callers when the soonest\n * pool entry resumes — useful for manual retry scheduling.\n *\n * @public\n */\nexport class CredentialPoolExhaustedError extends TheokitAgentError {\n  override readonly name: string = \"CredentialPoolExhaustedError\";\n  readonly provider: string;\n  readonly nextRetryAt: number | undefined;\n\n  constructor(\n    message: string,\n    options: {\n      provider: string;\n      nextRetryAt?: number;\n      code?: string;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      ...options,\n      isRetryable: true,\n      code: options.code ?? \"credential_pool_exhausted\",\n    });\n    this.provider = options.provider;\n    this.nextRetryAt = options.nextRetryAt;\n  }\n}\n\n/**\n * Finite error codes specific to memory adapter operations (ADR D141).\n *\n * @public\n */\nexport type MemoryAdapterErrorCode =\n  | \"auth_failed\"\n  | \"rate_limited\"\n  | \"not_found\"\n  | \"network\"\n  | \"invalid_input\"\n  | \"unknown\";\n\n/**\n * Error raised by `@theokit-memory-*` adapters. Carries `adapterId`\n * so callers can branch on which provider failed (ADR D141).\n *\n * @public\n */\nexport class MemoryAdapterError extends TheokitAgentError {\n  override readonly name: string = \"MemoryAdapterError\";\n  readonly adapterId: string;\n\n  constructor(\n    message: string,\n    options: {\n      adapterId: string;\n      code: MemoryAdapterErrorCode;\n      cause?: unknown;\n      metadata?: ErrorMetadata;\n    },\n  ) {\n    super(message, {\n      isRetryable: options.code === \"rate_limited\" || options.code === \"network\",\n      code: options.code,\n      ...(options.cause !== undefined ? { cause: options.cause } : {}),\n      ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),\n    });\n    this.adapterId = options.adapterId;\n  }\n}\n\n/**\n * Thrown when a user-supplied task ID violates the grammar\n * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter\n * prefix (`wf-` / `b-` / `cron-`, EC-5).\n *\n * @public\n */\nexport class InvalidTaskIdError extends TheokitAgentError {\n  override readonly name: string = \"InvalidTaskIdError\";\n  readonly taskId: string;\n\n  constructor(message: string, taskId: string, options: { cause?: unknown } = {}) {\n    super(message, {\n      ...options,\n      isRetryable: false,\n      code: \"invalid_task_id\",\n    });\n    this.taskId = taskId;\n  }\n}\n\n/**\n * Thrown when `Task.subscribe(id)` is called for a task that has been\n * evicted, never submitted, or evicted after retention (D373).\n *\n * @public\n */\nexport class TaskNotFoundError extends TheokitAgentError {\n  override readonly name: string = \"TaskNotFoundError\";\n  readonly taskId: string;\n\n  constructor(taskId: string, options: { cause?: unknown } = {}) {\n    super(`Task not found: ${taskId}`, {\n      ...options,\n      isRetryable: false,\n      code: \"task_not_found\",\n    });\n    this.taskId = taskId;\n  }\n}\n\n/**\n * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud\n * task observability is deferred until Theo PaaS GA.\n *\n * @public\n */\nexport class UnsupportedTaskOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedTaskOperationError\";\n  readonly operation: string;\n\n  constructor(operation: string, options: { cause?: unknown } = {}) {\n    super(\n      `Task operation \"${operation}\" is not supported on CloudAgent (pre-release; see ADR D370)`,\n      {\n        ...options,\n        isRetryable: false,\n        code: \"task_op_unsupported\",\n      },\n    );\n    this.operation = operation;\n  }\n}\n\n/**\n * Thrown by `Budget` enforcement (ADR D386) when a `mode: \"block\"`\n * budget would be exceeded by the upcoming LLM call. Caller pega\n * tipado para retry-after-window-reset or surface to the user.\n *\n * @public\n */\nexport class BudgetExceededError extends TheokitAgentError {\n  override readonly name: string = \"BudgetExceededError\";\n  readonly budgetName: string;\n  readonly window: import(\"./types/budget.js\").BudgetWindow;\n  readonly spentUsd: number;\n  readonly limitUsd: number;\n  readonly mode: import(\"./types/budget.js\").BudgetMode;\n\n  constructor(args: {\n    budgetName: string;\n    window: import(\"./types/budget.js\").BudgetWindow;\n    spentUsd: number;\n    limitUsd: number;\n    mode: import(\"./types/budget.js\").BudgetMode;\n    cause?: unknown;\n  }) {\n    super(\n      `Budget \"${args.budgetName}\" exceeded for window ${args.window}: spent $${args.spentUsd.toFixed(4)} > limit $${args.limitUsd.toFixed(4)}`,\n      {\n        ...(args.cause !== undefined ? { cause: args.cause } : {}),\n        isRetryable: false,\n        code: \"budget_exceeded\",\n      },\n    );\n    this.budgetName = args.budgetName;\n    this.window = args.window;\n    this.spentUsd = args.spentUsd;\n    this.limitUsd = args.limitUsd;\n    this.mode = args.mode;\n  }\n}\n\n/**\n * Thrown when `CloudAgent.send({ budget })` is invoked (D388). Cloud\n * budget surface waits for Theo PaaS GA.\n *\n * @public\n */\nexport class UnsupportedBudgetOperationError extends TheokitAgentError {\n  override readonly name: string = \"UnsupportedBudgetOperationError\";\n  readonly operation: string;\n\n  constructor(operation: string, options: { cause?: unknown } = {}) {\n    super(\n      `Budget operation \"${operation}\" is not supported on CloudAgent (pre-release; see ADR D388)`,\n      {\n        ...options,\n        isRetryable: false,\n        code: \"budget_op_unsupported\",\n      },\n    );\n    this.operation = operation;\n  }\n}\n","/**\n * Public type contract for the Task observability registry (ADRs D361-D374).\n *\n * Tasks are an opt-in observability layer over async work in the SDK\n * (`Agent.send`, `Agent.batch`, `Workflow.run`, `Cron` fires). They have\n * a closed 5-state lifecycle (D362), discriminated events (D366), and a\n * pluggable store (D364). The `Task` facade in `task.ts` is the public\n * surface; consumers import these types from `@theokit/sdk`.\n *\n * @public\n */\n\n/**\n * Closed enum of the 5 lifecycle states (D362).\n *\n * Transitions are acyclic:\n *   queued → running → (finished | error | cancelled)\n *   queued → cancelled (direct, no run started)\n */\nexport type TaskState = \"queued\" | \"running\" | \"finished\" | \"error\" | \"cancelled\";\n\n/** Discriminator of the runtime that produced a task (D374). */\nexport type TaskKind = \"run\" | \"batch\" | \"workflow\" | \"cron\" | \"custom\";\n\n/** Discriminated union of task lifecycle events (D366). */\nexport type TaskEvent =\n  | {\n      readonly type: \"submitted\";\n      readonly taskId: string;\n      readonly kind: TaskKind;\n      readonly submittedAt: number;\n      readonly meta?: Record<string, unknown>;\n      /** D372 — flag set on the first yielded event when the ring buffer was at cap. */\n      readonly truncated?: boolean;\n    }\n  | { readonly type: \"started\"; readonly taskId: string; readonly startedAt: number }\n  | {\n      readonly type: \"progress\";\n      readonly taskId: string;\n      readonly at: number;\n      readonly payload: unknown;\n    }\n  | {\n      readonly type: \"finished\";\n      readonly taskId: string;\n      readonly finishedAt: number;\n      readonly result: unknown;\n    }\n  | {\n      readonly type: \"errored\";\n      readonly taskId: string;\n      readonly erroredAt: number;\n      readonly error: { readonly code: string; readonly message: string };\n    }\n  | {\n      readonly type: \"cancelled\";\n      readonly taskId: string;\n      readonly cancelledAt: number;\n      readonly reason?: string;\n    };\n\n/** Public read-only view of a task entry in the registry. */\nexport interface TaskHandle {\n  readonly id: string;\n  readonly kind: TaskKind;\n  readonly state: TaskState;\n  readonly submittedAt: number;\n  readonly startedAt?: number;\n  readonly finishedAt?: number;\n  readonly cancelledAt?: number;\n  readonly erroredAt?: number;\n  readonly result?: unknown;\n  readonly error?: { readonly code: string; readonly message: string };\n  readonly meta?: Record<string, unknown>;\n  /**\n   * EC-7 — cross-process best-effort cancel flag. Set by CLI\n   * `theokit tasks cancel` via JsonFileTaskStore. The owning process\n   * polls at checkpoints and honors via AbortController. Always\n   * `undefined` for in-process cancel paths (which go directly through\n   * AbortController).\n   */\n  readonly cancelRequested?: boolean;\n}\n\n/** Query filter for `Task.list`. */\nexport interface TaskFilter {\n  readonly state?: TaskState | readonly TaskState[];\n  readonly kind?: TaskKind | readonly TaskKind[];\n  readonly submittedAfter?: number;\n  readonly submittedBefore?: number;\n  /** Defaults to 100. JsonFileTaskStore hard-caps loaded entries at 256 (D364). */\n  readonly limit?: number;\n}\n\n/** Options for `Task.submit`. */\nexport interface TaskSubmitOptions {\n  /**\n   * Optional user-supplied ID. Must match grammar `^[a-z0-9][a-z0-9_-]*$`\n   * and MUST NOT start with the reserved prefixes `wf-` / `b-` / `cron-`\n   * (D368, EC-5). When omitted, `crypto.randomUUID()` is used.\n   */\n  readonly id?: string;\n  readonly meta?: Record<string, unknown>;\n  /**\n   * Optional caller-provided AbortSignal. If already aborted at submit\n   * time, the registry short-circuits to `cancelled` without acquiring\n   * a semaphore slot (EC-4).\n   */\n  readonly signal?: AbortSignal;\n}\n\n/** Options shape for `TaskStore` factory (D364). */\nexport type TaskStoreOptions =\n  | { readonly backend: \"memory\" }\n  | { readonly backend: \"json\"; readonly dir: string };\n\n/** Result of `Task.cancel` (D365 — idempotent). */\nexport interface TaskCancelResult {\n  readonly cancelled: boolean;\n  readonly alreadyTerminal: boolean;\n}\n\n/**\n * Grammar for user-supplied task IDs (D368).\n * `crypto.randomUUID()` outputs do NOT match this (UUIDs have dashes\n * AND uppercase letters in their canonical form on some Node versions),\n * but the registry normalizes auto-generated IDs to lowercase before\n * insertion, so they pass the same regex.\n */\nconst TASK_ID_GRAMMAR = /^[a-z0-9][a-z0-9_-]*$/;\n\n/** Reserved prefixes for adapter-generated IDs (D368, EC-5). */\nconst RESERVED_PREFIXES = [\"wf-\", \"b-\", \"cron-\"] as const;\n\n/**\n * Validates a task ID against the public grammar + reserved prefixes.\n * Throws `InvalidTaskIdError` from `../errors.js` on rejection.\n *\n * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`\n * to register their own IDs; user-facing surfaces (`Task.submit`,\n * `agent.send({ task: { id } })`) leave it false.\n */\nexport function isValidTaskId(id: string, allowReserved: boolean): boolean {\n  if (!TASK_ID_GRAMMAR.test(id)) return false;\n  if (allowReserved) return true;\n  for (const prefix of RESERVED_PREFIXES) {\n    if (id.startsWith(prefix)) return false;\n  }\n  return true;\n}\n\n/** Re-exported for adapter implementations + tests. */\nexport const TASK_RESERVED_PREFIXES: readonly string[] = RESERVED_PREFIXES;\n","import { mkdir, open, rename, unlink } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\n/**\n * Atomic file replacement: write content to a per-call unique tmp path,\n * fsync, then rename over the target. Crash mid-write leaves either the old\n * file intact or the new file complete — never a half-written file.\n *\n * The tmp suffix is `<pid>.<rand>.tmp` so parallel processes (and concurrent\n * burst writes within one process) never collide on the same tmp path — a\n * race that would manifest as `ENOENT` on `rename` after the rival process\n * already moved its tmp into place.\n *\n * Mirrors OpenClaw's `replaceFileAtomic` from\n * `referencia/openclaw/packages/memory-host-sdk/src/host/fs-utils.ts` with\n * the multi-writer robustness fix.\n *\n * @internal\n */\nexport async function replaceFileAtomic(filePath: string, content: string): Promise<void> {\n  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;\n  const handle = await open(tmp, \"w\");\n  try {\n    await handle.writeFile(content, \"utf8\");\n    await handle.sync();\n  } finally {\n    await handle.close();\n  }\n  try {\n    await rename(tmp, filePath);\n  } catch (cause) {\n    // Cleanup tmp on rename failure so we don't leak stale .tmp files.\n    await unlink(tmp).catch(() => undefined);\n    throw cause;\n  }\n}\n\n/**\n * Options for `atomicWriteJson`.\n *\n * @internal\n */\nexport interface AtomicWriteJsonOptions {\n  /** Indent passed to `JSON.stringify`. Default: 2. */\n  indent?: number;\n  /** Whether to append a trailing newline (POSIX convention). Default: true. */\n  trailingNewline?: boolean;\n}\n\n/**\n * Typed JSON atomic write helper.\n *\n * Serializes `data` to JSON, then delegates to `replaceFileAtomic`. The\n * parent directory is auto-created (recursive `mkdir`) to make this helper\n * safe for callers who haven't ensured the directory exists (EC-4 in the\n * persistence-state-hardening plan).\n *\n * Throws `TypeError` on circular refs or `undefined` data (propagates from\n * `JSON.stringify`).\n *\n * @internal\n */\nexport async function atomicWriteJson<T>(\n  filePath: string,\n  data: T,\n  options?: AtomicWriteJsonOptions,\n): Promise<void> {\n  const indent = options?.indent ?? 2;\n  const trailingNewline = options?.trailingNewline ?? true;\n  const json = JSON.stringify(data, null, indent);\n  if (json === undefined) {\n    throw new TypeError(\"atomicWriteJson: cannot serialize undefined\");\n  }\n  const content = trailingNewline ? `${json}\\n` : json;\n  await mkdir(dirname(filePath), { recursive: true });\n  await replaceFileAtomic(filePath, content);\n}\n\n/**\n * Atomic text write. Same crash-safety guarantees as `replaceFileAtomic` +\n * auto-mkdir of the parent directory. Used by `theokit-migrate-config`\n * (T4.1, EC-2 MUST FIX) so a crash mid-migration leaves previous MD files\n * intact rather than corrupting them.\n *\n * @internal\n */\nexport async function atomicWriteText(filePath: string, content: string): Promise<void> {\n  await mkdir(dirname(filePath), { recursive: true });\n  await replaceFileAtomic(filePath, content);\n}\n","/**\n * `TaskStore` interface + 2 implementations (ADR D364).\n *\n *   - `InMemoryTaskStore` — default, transient, single-process.\n *   - `JsonFileTaskStore` — opt-in, one JSON file per task under a\n *     dedicated dir; single-process invariant (EC-15 documented).\n *\n * Edge cases absorbed:\n *   - EC-1: constructor auto-creates dir (mkdirSync recursive idempotent).\n *   - EC-2: every method validates the task id against the public\n *     grammar (D368) BEFORE doing any path I/O — path-traversal defense.\n *   - EC-6: `list()` returns `[]` on ENOENT (fresh install path).\n *   - EC-8: `list()` skips `.tmp.*` orphan files left by interrupted\n *     atomic writes.\n *   - EC-14 (DOCUMENT): `list()` JSDoc documents the 256-row hard cap\n *     and the `submittedBefore` paging idiom.\n *   - EC-15 (DOCUMENT): `JsonFileTaskStore` JSDoc documents the\n *     single-process invariant; v0.2 SQLite covers cross-process.\n *\n * @internal\n */\n\nimport { mkdirSync, readdirSync } from \"node:fs\";\nimport { readFile, unlink } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { InvalidTaskIdError } from \"../../errors.js\";\nimport {\n  isValidTaskId,\n  type TaskFilter,\n  type TaskHandle,\n  type TaskState,\n  type TaskStoreOptions,\n} from \"../../types/task.js\";\nimport { atomicWriteText } from \"../persistence/atomic-write.js\";\n\nconst JSON_LOAD_CAP = 256;\nconst DEFAULT_LIST_LIMIT = 100;\n\n/** Storage interface used by `TaskRegistry`. */\nexport interface TaskStore {\n  insert(handle: TaskHandle): Promise<void>;\n  update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined>;\n  get(id: string): Promise<TaskHandle | undefined>;\n  /**\n   * Returns at most `filter.limit ?? 100` matching handles. JsonFile\n   * backend hard-caps loaded entries at 256 — callers needing larger\n   * pages must use `submittedBefore` to walk the timeline.\n   */\n  list(filter: TaskFilter): Promise<TaskHandle[]>;\n  delete(id: string): Promise<boolean>;\n  /** Removes terminal handles whose terminal-timestamp is older than `epochMs`. */\n  evictTerminalOlderThan(epochMs: number): Promise<number>;\n}\n\nfunction assertValidIdForStore(id: string): void {\n  if (!isValidTaskId(id, /* allowReserved */ true)) {\n    throw new InvalidTaskIdError(`store rejects invalid task id: ${id}`, id);\n  }\n}\n\nfunction terminalTimestamp(h: TaskHandle): number | undefined {\n  if (h.state === \"finished\") return h.finishedAt;\n  if (h.state === \"error\") return h.erroredAt;\n  if (h.state === \"cancelled\") return h.cancelledAt;\n  return undefined;\n}\n\nfunction isTerminal(state: TaskState): boolean {\n  return state === \"finished\" || state === \"error\" || state === \"cancelled\";\n}\n\nfunction matchesState(h: TaskHandle, filter: TaskFilter): boolean {\n  if (filter.state === undefined) return true;\n  const states = Array.isArray(filter.state) ? filter.state : [filter.state];\n  return states.includes(h.state);\n}\nfunction matchesKind(h: TaskHandle, filter: TaskFilter): boolean {\n  if (filter.kind === undefined) return true;\n  const kinds = Array.isArray(filter.kind) ? filter.kind : [filter.kind];\n  return kinds.includes(h.kind);\n}\nfunction matchesTime(h: TaskHandle, filter: TaskFilter): boolean {\n  if (filter.submittedAfter !== undefined && h.submittedAt <= filter.submittedAfter) return false;\n  if (filter.submittedBefore !== undefined && h.submittedAt >= filter.submittedBefore) return false;\n  return true;\n}\nfunction matchesFilter(h: TaskHandle, filter: TaskFilter): boolean {\n  return matchesState(h, filter) && matchesKind(h, filter) && matchesTime(h, filter);\n}\n\nfunction applyFilter(values: Iterable<TaskHandle>, filter: TaskFilter): TaskHandle[] {\n  const limit = filter.limit ?? DEFAULT_LIST_LIMIT;\n  const out: TaskHandle[] = [];\n  for (const h of values) {\n    if (matchesFilter(h, filter)) {\n      out.push(h);\n      if (out.length >= limit) break;\n    }\n  }\n  return out;\n}\n\n/* ─── InMemory ─── */\n\nexport class InMemoryTaskStore implements TaskStore {\n  private readonly map = new Map<string, TaskHandle>();\n\n  async insert(handle: TaskHandle): Promise<void> {\n    assertValidIdForStore(handle.id);\n    this.map.set(handle.id, handle);\n  }\n\n  async update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined> {\n    assertValidIdForStore(id);\n    const existing = this.map.get(id);\n    if (existing === undefined) return undefined;\n    const next = mutate(existing);\n    this.map.set(id, next);\n    return next;\n  }\n\n  async get(id: string): Promise<TaskHandle | undefined> {\n    assertValidIdForStore(id);\n    return this.map.get(id);\n  }\n\n  async list(filter: TaskFilter): Promise<TaskHandle[]> {\n    return applyFilter(this.map.values(), filter);\n  }\n\n  async delete(id: string): Promise<boolean> {\n    assertValidIdForStore(id);\n    return this.map.delete(id);\n  }\n\n  async evictTerminalOlderThan(epochMs: number): Promise<number> {\n    let count = 0;\n    for (const [id, h] of this.map.entries()) {\n      if (!isTerminal(h.state)) continue;\n      const ts = terminalTimestamp(h);\n      if (ts !== undefined && ts < epochMs) {\n        this.map.delete(id);\n        count++;\n      }\n    }\n    return count;\n  }\n}\n\n/* ─── JsonFile (opt-in) ───\n *\n * IMPORTANT (EC-15): `JsonFileTaskStore` is **single-process**.\n * Concurrent writers from multiple Node processes against the same\n * directory may corrupt entries (atomic-write protects per-file, but\n * the `list()` scan + `update()` read-modify-write cycle is not\n * serialised across processes). Use only when the `TaskRegistry`\n * runs in exactly one process. v0.2 will add a SQLite backend with\n * the same interface for cross-process scenarios (D364 + D61).\n */\nexport class JsonFileTaskStore implements TaskStore {\n  constructor(private readonly dir: string) {\n    // EC-1: idempotent mkdir; ignore EEXIST.\n    try {\n      mkdirSync(dir, { recursive: true });\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== \"EEXIST\") throw err;\n    }\n  }\n\n  private filePath(id: string): string {\n    return join(this.dir, `${id}.json`);\n  }\n\n  async insert(handle: TaskHandle): Promise<void> {\n    assertValidIdForStore(handle.id);\n    await atomicWriteText(this.filePath(handle.id), JSON.stringify(handle));\n  }\n\n  async update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined> {\n    assertValidIdForStore(id);\n    const existing = await this.get(id);\n    if (existing === undefined) return undefined;\n    const next = mutate(existing);\n    await atomicWriteText(this.filePath(id), JSON.stringify(next));\n    return next;\n  }\n\n  async get(id: string): Promise<TaskHandle | undefined> {\n    assertValidIdForStore(id);\n    try {\n      const raw = await readFile(this.filePath(id), \"utf8\");\n      return JSON.parse(raw) as TaskHandle;\n    } catch (err) {\n      const code = (err as NodeJS.ErrnoException).code;\n      if (code === \"ENOENT\") return undefined;\n      // Corrupt JSON or other I/O error — log + degrade gracefully (D50/EC-7 cache pattern).\n      process.stderr.write(`[task-store] failed to read ${id}: ${(err as Error).message}\\n`);\n      return undefined;\n    }\n  }\n\n  async list(filter: TaskFilter): Promise<TaskHandle[]> {\n    let entries: string[];\n    try {\n      entries = readdirSync(this.dir);\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return []; // EC-6\n      throw err;\n    }\n    // EC-8: skip orphan .tmp files left by interrupted atomic writes.\n    const candidates = entries\n      .filter((name) => name.endsWith(\".json\") && !name.includes(\".tmp\"))\n      .slice(0, JSON_LOAD_CAP);\n\n    const loaded = await Promise.all(\n      candidates.map(async (name) => {\n        const id = name.slice(0, -\".json\".length);\n        if (!isValidTaskId(id, true)) return undefined;\n        return this.get(id);\n      }),\n    );\n    const handles = loaded.filter((h): h is TaskHandle => h !== undefined);\n    return applyFilter(handles, filter);\n  }\n\n  async delete(id: string): Promise<boolean> {\n    assertValidIdForStore(id);\n    try {\n      await unlink(this.filePath(id));\n      return true;\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return false;\n      throw err;\n    }\n  }\n\n  async evictTerminalOlderThan(epochMs: number): Promise<number> {\n    const handles = await this.list({ state: [\"finished\", \"error\", \"cancelled\"], limit: 256 });\n    let count = 0;\n    for (const h of handles) {\n      const ts = terminalTimestamp(h);\n      if (ts !== undefined && ts < epochMs) {\n        if (await this.delete(h.id)) count++;\n      }\n    }\n    return count;\n  }\n}\n\n/** Factory used by `TaskRegistry.configure` (D364). */\nexport function getTaskStoreFor(options: TaskStoreOptions): TaskStore {\n  if (options.backend === \"memory\") return new InMemoryTaskStore();\n  return new JsonFileTaskStore(options.dir);\n}\n"]}

package/dist/task.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `Task` — observable async work registry (Adoption Roadmap gap #2,
+ * ADRs D361-D374).
+ *
+ * Static facade delegating to the in-process `TaskRegistry` singleton.
+ * The lifecycle of any task is the 5-state machine `queued | running |
+ * finished | error | cancelled` (D362). Wrapping `Agent.send` /
+ * `Agent.batch` / `Workflow.run` / `Cron` fires is opt-in via the
+ * `{ task: true }` option on each (D363).
+ *
+ * @public
+ */
+import type { TaskCancelResult, TaskEvent, TaskFilter, TaskHandle, TaskKind, TaskStoreOptions, TaskSubmitOptions } from "./types/task.js";
+export interface TaskWorkContext {
+    readonly signal: AbortSignal;
+    emit(payload: unknown): void;
+}
+export type TaskWorkFn<T> = (ctx: TaskWorkContext) => Promise<T> | T;
+/**
+ * Registry-level configuration. May only be applied BEFORE the first
+ * `Task.submit` of the process — see EC-13. Subsequent calls emit a
+ * single stderr line and become no-ops.
+ */
+export interface TaskConfigureOptions {
+    readonly store?: TaskStoreOptions;
+    readonly maxConcurrent?: number;
+    readonly retentionMs?: number;
+}
+export declare class Task {
+    private constructor();
+    /**
+     * Configure the registry. **Must be called before the first `submit`**
+     * (EC-13). Available knobs: pluggable store (D364), concurrency cap
+     * (D369), and retention (D373).
+     */
+    static configure(opts: TaskConfigureOptions): void;
+    /**
+     * Submit a unit of asynchronous work to the registry.
+     *
+     * The `work` function receives `{ signal, emit }` — `signal` is the
+     * AbortSignal honored on cancel; `emit(payload)` produces a
+     * `progress` event observable via `Task.subscribe`.
+     *
+     * Returns a `TaskHandle` in `state: "queued"`. Subsequent state
+     * transitions are observable via `Task.subscribe(handle.id)` OR
+     * polled via `Task.get(handle.id)`.
+     *
+     * **Idempotency (D367):** submitting twice with the same `id` returns
+     * the existing handle without re-invoking work.
+     *
+     * **Grammar (D368):** user-supplied ids must match
+     * `^[a-z0-9][a-z0-9_-]*$` and must not start with reserved prefixes
+     * `wf-` / `b-` / `cron-`. Otherwise `InvalidTaskIdError` is thrown.
+     *
+     * **Pre-aborted signal (EC-4):** if `options.signal` is already
+     * aborted, the task short-circuits to `cancelled` without acquiring
+     * a semaphore slot and without invoking `work`.
+     */
+    static submit<T>(kind: TaskKind, work: TaskWorkFn<T>, options?: TaskSubmitOptions): Promise<TaskHandle>;
+    /** Returns matching handles, capped at `filter.limit ?? 100`. */
+    static list(filter?: TaskFilter): Promise<TaskHandle[]>;
+    /** Returns a single handle by id, or `undefined` if unknown / evicted. */
+    static get(id: string): Promise<TaskHandle | undefined>;
+    /**
+     * Idempotent cancel (D365). Returns:
+     *   - `{ cancelled: true, alreadyTerminal: false }` — transitioned
+     *     queued/running task to `cancelled`.
+     *   - `{ cancelled: false, alreadyTerminal: true }` — task already
+     *     terminal.
+     *   - `{ cancelled: false, alreadyTerminal: false }` — task unknown.
+     *
+     * Never throws.
+     */
+    static cancel(id: string, reason?: string): Promise<TaskCancelResult>;
+    /**
+     * Subscribe to a task's event stream. The returned `AsyncIterable<TaskEvent>`
+     * starts by replaying buffered events (ring buffer cap 64, D372) and
+     * then yields live events until a terminal event (finished / errored
+     * / cancelled) is emitted, at which point it closes automatically.
+     *
+     * Calling `.return()` on the iterator (or `break` in a `for await`)
+     * cleans up the subscriber callback (EC-10).
+     *
+     * Throws `TaskNotFoundError` if the id is unknown or has been evicted.
+     */
+    static subscribe(id: string): AsyncIterable<TaskEvent>;
+}

package/dist/theokit.d.ts

@@ -0,0 +1,84 @@
+import type { SDKProvider } from "./types/providers.js";
+import type { SDKModel, SDKRepository, SDKUser } from "./types/theokit.js";
+/**
+ * Options shared by every `Theokit.*` request.
+ *
+ * @public
+ */
+export interface TheokitRequestOptions {
+    /** Override the `THEOKIT_API_KEY` env var for this call. */
+    apiKey?: string;
+    /**
+     * Target a specific provider for catalog reads. When set to a provider
+     * with `authType: "none"` (e.g. `"ollama"`, `"lmstudio"`, `"llamacpp"`),
+     * `Theokit.models.list({ provider })` reads from the provider's local
+     * `/v1/models` endpoint instead of the TheoCloud catalog. ADR D184.
+     *
+     * @public
+     */
+    provider?: string;
+}
+/**
+ * Account-level and catalog reads. All methods accept an optional `apiKey`
+ * and otherwise fall back to the `THEOKIT_API_KEY` environment variable.
+ *
+ * @public
+ */
+export declare class Theokit {
+    private constructor();
+    /**
+     * Return the user behind the current API key.
+     *
+     * @public
+     */
+    static me(options?: TheokitRequestOptions): Promise<SDKUser>;
+    /**
+     * Model catalog reads.
+     *
+     * @public
+     */
+    static readonly models: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKModel[]>;
+    };
+    /**
+     * Connected GitHub repositories for the calling user's team. Cloud only.
+     *
+     * @public
+     */
+    static readonly repositories: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKRepository[]>;
+    };
+    /**
+     * Provider catalog. Lists every provider known to the platform, including
+     * plugin-registered ones, with capability and availability metadata.
+     *
+     * @public
+     */
+    static readonly providers: {
+        list: (options?: TheokitRequestOptions) => Promise<SDKProvider[]>;
+    };
+    /**
+     * Local introspection of bundled SDK assets (ADR D201). Unlike the
+     * cloud-catalog `providers.list()` (which hits the TheoCloud HTTP API),
+     * `inspect.*` reads the SDK's own bundled registries — useful for
+     * tooling (e.g. `@theokit/cli`'s `theokit inspect`) that needs to know
+     * what's available WITHOUT a network round-trip.
+     *
+     * @public
+     */
+    static readonly inspect: {
+        builtinProviders: () => Array<{
+            readonly name: string;
+            readonly apiMode: string;
+            readonly authType: string;
+            readonly baseUrl: string;
+            readonly aliases?: ReadonlyArray<string>;
+            readonly envVars: ReadonlyArray<string>;
+        }>;
+        embeddingAdapters: () => Array<{
+            readonly id: string;
+            readonly transport: string;
+            readonly defaultModel: string;
+        }>;
+    };
+}

package/dist/tools/_path-scope.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Shared `safePathJoin + assertNoSymlinkEscape` helper for built-in coding
+ * tools (git-diff, run-vitest, list-dir, read-file, search-text). Returns a
+ * pre-formatted `path_traversal` JSON string on failure or `null` on pass.
+ *
+ * @internal
+ */
+export declare function checkPathScope(path: string | undefined, projectRoot: string): string | null;

package/dist/tools/_path-scope.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared `safePathJoin + assertNoSymlinkEscape` helper for built-in coding
+ * tools (git-diff, run-vitest, list-dir, read-file, search-text). Returns a
+ * pre-formatted `path_traversal` JSON string on failure or `null` on pass.
+ *
+ * @internal
+ */
+export declare function checkPathScope(path: string | undefined, projectRoot: string): string | null;

package/dist/tools/_subprocess.d.cts

@@ -0,0 +1,28 @@
+/**
+ * Shared subprocess-watch helpers for built-in coding tools (git-diff,
+ * run-vitest). Wires the on(close)/on(error) settle pattern in a single
+ * place to eliminate the cross-file clone flagged by jscpd.
+ *
+ * @internal
+ */
+/**
+ * Settle gate — guarantees the supplied callback fires exactly once across
+ * the close/error/timeout race. Clears the timer on settle.
+ */
+interface SettleGate {
+    /** True after first settle; subsequent calls are no-ops. */
+    settled: () => boolean;
+    /** Settle the gate, clear the timer, and call `onSettle()`. */
+    fire: (onSettle: () => void) => void;
+}
+/**
+ * Wire SIGKILL-on-timeout for a detached process group. Returns the settle
+ * gate so caller listeners can short-circuit when the timeout already fired.
+ */
+export declare function armTimeoutKill<T>(child: ChildProcess, timeoutMs: number, onTimeout: () => T, resolve: (value: T) => void): SettleGate;
+/**
+ * Attach a close+error pair of listeners that resolve via the supplied
+ * callbacks. Honors the gate so timeout-vs-close races settle exactly once.
+ */
+export declare function attachChildSettlers<T>(child: ChildProcess, gate: SettleGate, onClose: (code: number | null) => T, onError: (err: Error) => T, resolve: (value: T) => void): void;
+export {};

package/dist/tools/_subprocess.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared subprocess-watch helpers for built-in coding tools (git-diff,
+ * run-vitest). Wires the on(close)/on(error) settle pattern in a single
+ * place to eliminate the cross-file clone flagged by jscpd.
+ *
+ * @internal
+ */
+/**
+ * Settle gate — guarantees the supplied callback fires exactly once across
+ * the close/error/timeout race. Clears the timer on settle.
+ */
+interface SettleGate {
+    /** True after first settle; subsequent calls are no-ops. */
+    settled: () => boolean;
+    /** Settle the gate, clear the timer, and call `onSettle()`. */
+    fire: (onSettle: () => void) => void;
+}
+/**
+ * Wire SIGKILL-on-timeout for a detached process group. Returns the settle
+ * gate so caller listeners can short-circuit when the timeout already fired.
+ */
+export declare function armTimeoutKill<T>(child: ChildProcess, timeoutMs: number, onTimeout: () => T, resolve: (value: T) => void): SettleGate;
+/**
+ * Attach a close+error pair of listeners that resolve via the supplied
+ * callbacks. Honors the gate so timeout-vs-close races settle exactly once.
+ */
+export declare function attachChildSettlers<T>(child: ChildProcess, gate: SettleGate, onClose: (code: number | null) => T, onError: (err: Error) => T, resolve: (value: T) => void): void;
+export {};

package/dist/tools/git-diff.d.cts

@@ -0,0 +1,22 @@
+/**
+ * `git_diff` — built-in tool for coding agents.
+ *
+ * Returns the unified diff of the working tree (or staged changes when
+ * `cached=true`). Implemented as a thin `git diff` subprocess wrapper
+ * with a couple of hard limits:
+ *
+ *   - 30s wall clock timeout (kills the process group on expiry)
+ *   - 5 MB stdout cap (truncate + flag `truncated=true`)
+ *   - Path scope validated through `safePathJoin` + `assertNoSymlinkEscape`
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, diff: string, truncated?: boolean }`
+ *   - `{ ok: false, error: 'not_a_repo' | 'path_traversal' | 'timeout' }`
+ */
+import type { CustomTool } from "../types/agent.js";
+export interface CreateGitDiffToolOptions {
+    projectRoot: string;
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+}
+export declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;

package/dist/tools/git-diff.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `git_diff` — built-in tool for coding agents.
+ *
+ * Returns the unified diff of the working tree (or staged changes when
+ * `cached=true`). Implemented as a thin `git diff` subprocess wrapper
+ * with a couple of hard limits:
+ *
+ *   - 30s wall clock timeout (kills the process group on expiry)
+ *   - 5 MB stdout cap (truncate + flag `truncated=true`)
+ *   - Path scope validated through `safePathJoin` + `assertNoSymlinkEscape`
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, diff: string, truncated?: boolean }`
+ *   - `{ ok: false, error: 'not_a_repo' | 'path_traversal' | 'timeout' }`
+ */
+import type { CustomTool } from "../types/agent.js";
+export interface CreateGitDiffToolOptions {
+    projectRoot: string;
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+}
+export declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;

package/dist/tools/index.d.cts

@@ -0,0 +1,29 @@
+/**
+ * Built-in tools for `@theokit/sdk` agents (`@theokit/sdk/tools`).
+ *
+ * Each factory returns a `CustomTool` ready to drop into `Agent.create`
+ * or `createAgentFactory({ tools: [...] })`. All five share three
+ * design rules:
+ *
+ *   1. **Project-scoped**. Every factory takes `{ projectRoot }` and
+ *      gates every I/O call against that boundary via the SDK's
+ *      `safePathJoin` + `assertNoSymlinkEscape` primitives.
+ *
+ *   2. **Sensitive files refused**. `.env*` (except `.env.example`),
+ *      `.git/`, `node_modules/`, `.theo/`, and lock files are blocked
+ *      via `isForbiddenPath`.
+ *
+ *   3. **JSON returns, never throws on user mistakes**. Handlers return
+ *      `{ ok: true, ... }` or `{ ok: false, error: '...' }`. Real
+ *      exceptions are reserved for SDK-side bugs (input parse errors,
+ *      unexpected fs failures).
+ *
+ * Consumers: TheoKit Studio (the embedded coding agent), `cli-bot`
+ * (the SDK's reference example), and any future coding-agent built on
+ * `@theokit/sdk`.
+ */
+export { type CreateGitDiffToolOptions, createGitDiffTool } from "./git-diff.js";
+export { type CreateListDirToolOptions, createListDirTool } from "./list-dir.js";
+export { type CreateReadFileToolOptions, createReadFileTool } from "./read-file.js";
+export { type CreateRunVitestToolOptions, createRunVitestTool, type VitestSummary, } from "./run-vitest.js";
+export { type CreateSearchTextToolOptions, createSearchTextTool } from "./search-text.js";