@theokit/sdk 1.5.0 → 1.6.1

package/dist/path-safety.d.cts

@@ -1,15 +0,0 @@
-/**
- * Public path-safety primitives.
- *
- * Thin re-export of the canonical implementation in
- * `internal/security/path-guard.ts`. Splitting this into its own
- * top-level module gives `rollup-plugin-dts` a clean boundary when
- * bundling declarations — without it, including the path-guard module
- * via the main barrel propagates a cascade of transitive imports that
- * surface a known-spurious "ForkOptions not exported" error from
- * `types/agent.ts` (dynamic-import-type quirk in rollup-plugin-dts).
- *
- * See `docs.md → Security — path traversal + TOCTOU` for the full
- * primitive reference. Public from v1.x.
- */
-export { assertNoSymlinkEscape, ForbiddenPathError, isForbiddenPath, PathTraversalError, safePathJoin, } from "./internal/security/path-guard.js";

package/dist/task-store.d.cts

@@ -1,8 +0,0 @@
-/**
- * Public sub-export for the Task store interface + JSON-backed
- * implementation. Used by `@theokit/cli` to read the registry
- * cross-process from disk (ADR D364 + EC-7 best-effort cancel).
- *
- * @public
- */
-export { getTaskStoreFor, InMemoryTaskStore, JsonFileTaskStore, type TaskStore, } from "./internal/task/store.js";

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

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,28 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * `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

@@ -1,29 +0,0 @@
-/**
- * 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";

package/dist/tools/list-dir.d.cts

@@ -1,26 +0,0 @@
-/**
- * `list_dir` — built-in tool for coding agents.
- *
- * Returns the direct entries of a project-relative directory. Hardened
- * against the same four bug families as `read_file` plus the
- * **EC-6 unbounded output** failure mode: in a project with 10k files,
- * a naive listing returns a 5 MB JSON payload that freezes the browser
- * and (more importantly) blows past the LLM context window.
- *
- * Defaults:
- *   - `max = 500` entries (override via factory option `{ max }`)
- *   - Result includes `{ truncated: boolean, totalCount: number }` so the
- *     agent can decide whether to drill deeper or call `search_text` instead
- *
- * Result shape (always a JSON string):
- *   - `{ ok: true, entries: Array<{ name, type }>, truncated, totalCount }`
- *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' | 'not_found' }`
- */
-import type { CustomTool } from "../types/agent.js";
-export interface CreateListDirToolOptions {
-    /** Absolute path to the project root. Every listing is gated against this boundary. */
-    projectRoot: string;
-    /** Maximum number of entries returned per call. Default 500. */
-    max?: number;
-}
-export declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;

package/dist/tools/read-file.d.cts

@@ -1,31 +0,0 @@
-/**
- * `read_file` — built-in tool for coding agents.
- *
- * Reads a project-relative file as UTF-8 and returns its contents.
- * Hardened against the four bug families a coding agent normally hits:
- *
- *   1. **Path traversal** — `safePathJoin` rejects literal `..`,
- *      normalised escape, absolute segments, null-byte injection.
- *   2. **Symlink escape** — `assertNoSymlinkEscape` follows the full
- *      chain (and any intermediate symlinks; defence-in-depth fix v1.x).
- *   3. **Sensitive files** — `isForbiddenPath` blocks `.env*` (except
- *      `.env.example`), `.git/`, `node_modules/`, `.theo/`, lock files.
- *   4. **Binary files** — null-byte check on the first 8 KB. PNG/JPEG/
- *      compiled binaries return a structured `binary_file` error
- *      instead of garbled UTF-8 (EC-5 from the TheoKit Studio review).
- *
- * Return shape (always a JSON string the LLM consumes):
- *   - `{ ok: true, content: string }` on success
- *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' |
- *        'binary_file' | 'not_found' | 'too_large' }` on refusal
- *
- * The handler intentionally never throws on a "user mistake"
- * (traversal / forbidden / not found). Throwing reserved for SDK-side
- * mistakes that should crash the agent loop (input parse errors).
- */
-import type { CustomTool } from "../types/agent.js";
-export interface CreateReadFileToolOptions {
-    /** Absolute path to the project root. Every read is gated against this boundary. */
-    projectRoot: string;
-}
-export declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;

package/dist/tools/run-vitest.d.cts

@@ -1,46 +0,0 @@
-/**
- * `run_vitest` — built-in tool for coding agents.
- *
- * Runs vitest against an optional file/pattern scope and returns the
- * parsed JSON report. Hardened against the same subprocess failure
- * modes as `git_diff`:
- *
- *   - 120s wall clock timeout (vitest can be slow on first run)
- *   - Process group kill on timeout (EC-7 — defeats vitest workers as
- *     grandchildren of the spawned shell)
- *   - **EC-12**: vitest stdout may contain deprecation warnings BEFORE
- *     the JSON payload. The parser scans line-by-line and extracts the
- *     LAST valid JSON object, not the first.
- *
- * Result shape (always a JSON string):
- *   - `{ ok: true, summary: { numTotalTests, numPassedTests, numFailedTests, success } }`
- *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' | 'timeout' |
- *        'no_vitest' | 'unparseable_output' }`
- *
- * Implementation note: invokes vitest via `npx --no-install vitest`. The
- * `--no-install` avoids the agent triggering a multi-megabyte download
- * mid-turn if vitest is missing — the tool fails cleanly with
- * `no_vitest` instead.
- */
-import type { CustomTool } from "../types/agent.js";
-export interface CreateRunVitestToolOptions {
-    projectRoot: string;
-    timeoutMs?: number;
-    maxStdoutBytes?: number;
-}
-export interface VitestSummary {
-    numTotalTests?: number;
-    numPassedTests?: number;
-    numFailedTests?: number;
-    success?: boolean;
-}
-export declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTool;
-/**
- * Find the LAST line in `stdout` that parses as a JSON object. Vitest
- * prepends node deprecation warnings to its JSON reporter output — if
- * we naively `JSON.parse(stdout)` we get a SyntaxError. Workaround: walk
- * lines bottom-up and return the first one that parses.
- *
- * Exported for direct unit testing without spawning vitest.
- */
-export declare function extractTrailingJson(stdout: string): unknown;

package/dist/tools/search-text.d.cts

@@ -1,32 +0,0 @@
-/**
- * `search_text` — built-in tool for coding agents.
- *
- * Literal text search across the project tree (recursive). Sensible
- * defaults:
- *
- *   - Skips forbidden directories (`.env`, `.git/`, `node_modules/`,
- *     `.theo/`) so the agent never wastes context on dependency soup
- *     or VCS internals.
- *   - Skips files larger than `maxFileSize` (default 1 MB) and binary
- *     files (null-byte detection on first 8 KB) so a megabyte of
- *     minified JS never blows up the result.
- *   - Caps total matches at `maxMatches` (default 100) — the agent
- *     should refine the query if it gets close to the cap.
- *
- * Result shape (always a JSON string):
- *   - `{ ok: true, matches: Array<{ file, line, preview }>, truncated, totalMatches }`
- *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' | 'not_found' }`
- *
- * Implementation note: this is a plain JS recursive walk. For very
- * large repos a future iteration can shell out to `rg` (ripgrep) when
- * present, but the JS path stays as the dependency-free fallback.
- */
-import type { CustomTool } from "../types/agent.js";
-export interface CreateSearchTextToolOptions {
-    projectRoot: string;
-    /** Cap on total matches returned. Default 100. */
-    maxMatches?: number;
-    /** Skip files larger than this (bytes). Default 1 MB. */
-    maxFileSize?: number;
-}
-export declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;

package/dist/workflow.d.cts

@@ -1,97 +0,0 @@
-/**
- * Public `Workflow` class — declarative multi-step orchestration over
- * `Agent.send`, `Handoff`, `Agent.batch` and friends (Adoption Roadmap #5;
- * ADRs D230-D248).
- *
- * Usage:
- *
- *   import { Agent } from "@theokit/sdk";
- *   import { Workflow, fn, agentStep } from "@theokit/sdk/workflow";
- *
- *   const classifier = await Agent.create({ ... });
- *   const wf = Workflow.create({ name: "demo" })
- *     .then(fn("validate", (input: { id: string }) => {
- *       if (!input.id) throw new Error("missing id");
- *       return input;
- *     }))
- *     .then(agentStep("classify", classifier, (i) => `Classify: ${JSON.stringify(i)}`))
- *     .commit();
- *
- *   const run = await wf.run({ id: "x" });
- *   console.log(run.status, run.output);
- *
- * @public
- */
-import type { ZodType } from "zod";
-import type { SDKAgent } from "./types/agent.js";
-import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions } from "./types/workflow.js";
-export declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
-    private readonly options;
-    private readonly _steps;
-    private _committed;
-    then<TO = unknown>(step: Step): WorkflowBuilder<TInput, TO>;
-    parallel(branches: ReadonlyArray<ReadonlyArray<Step>>, opts?: {
-        id?: string;
-        concurrency?: number;
-        errorPolicy?: "fail-fast" | "collect";
-    }): WorkflowBuilder<TInput, unknown[]>;
-    branch(predicates: BranchStep["predicates"], opts?: {
-        id?: string;
-        fallback?: ReadonlyArray<Step>;
-    }): WorkflowBuilder<TInput, unknown>;
-    foreach(iterableFrom: string, step: Step, opts?: {
-        id?: string;
-        concurrency?: number;
-    }): WorkflowBuilder<TInput, unknown[]>;
-    dowhile(step: Step, condFn: DowhileStep["condFn"], opts?: {
-        id?: string;
-        maxIterations?: number;
-    }): WorkflowBuilder<TInput, unknown>;
-    sleep(durationMs: number, id?: string): WorkflowBuilder<TInput, TOutput>;
-    suspend(opts?: {
-        id?: string;
-        payloadSchema?: ZodType;
-    }): WorkflowBuilder<TInput, unknown>;
-    commit(): Workflow<TInput, TOutput>;
-    private validateUniqueIds;
-    private assertNotCommitted;
-}
-export declare class Workflow<TInput = unknown, TOutput = unknown> {
-    private readonly _options;
-    private readonly _steps;
-    /**
-     * Construct a workflow builder. Validate options via Zod and return a
-     * `WorkflowBuilder` for fluent chaining. Call `.commit()` to obtain the
-     * immutable `Workflow`.
-     */
-    static create<TI = unknown, TO = unknown>(options: WorkflowOptions): WorkflowBuilder<TI, TO>;
-    /**
-     * Run this workflow with the given input. Returns a populated
-     * `WorkflowRun`. Errors inside a step DO NOT throw — they propagate via
-     * `run.status === "failed"`.
-     */
-    run(input: TInput, opts?: WorkflowRunOptions): Promise<WorkflowRun<TOutput>>;
-    /**
-     * Resume a suspended workflow from its snapshot. Throws
-     * `WorkflowSnapshotNotFoundError` if `runId` is unknown.
-     */
-    static resume<TO = unknown>(opts: WorkflowResumeOptions): Promise<WorkflowRun<TO>>;
-}
-/**
- * Build a `FnStep`. `id` must match `^[a-z0-9][a-z0-9_-]*$`.
- */
-export declare function fn<I = unknown, O = unknown>(id: string, step: (input: I, ctx: StepContext) => Promise<O> | O, opts?: {
-    inputSchema?: ZodType;
-    outputSchema?: ZodType;
-    retry?: RetryPolicy;
-}): FnStep;
-/**
- * Build an `AgentStep`. The `promptTemplate` can be a static string or a
- * function that receives the input and returns the prompt.
- */
-export declare function agentStep(id: string, agent: SDKAgent, promptTemplate: string | ((input: unknown) => string), opts?: {
-    retry?: RetryPolicy;
-}): AgentStep;
-export { __resetSnapshotStoresForTests } from "./internal/workflow/snapshot-store.js";
-export type * from "./types/workflow.js";
-export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, } from "./types/workflow.js";