@theokit/sdk 4.53.1 → 4.55.0

package/dist/sandbox/types.d.cts

@@ -8,12 +8,37 @@
  * @public
  */
 import type { EnvPolicy } from "../types/env-policy.js";
+/**
+ * What a {@link SandboxBackend} returns for one command.
+ *
+ * `exitCode` is a coarse signal rather than the child's real exit status: the backends in this
+ * package report `0` on success, `124` on timeout, and `1` for everything else — including a command
+ * that exited with its own non-zero code. Read `timedOut` to tell a killed command from a failed one,
+ * and `stderr` for the reason; branching on a specific exit code will not work here.
+ *
+ * `stdout` and `stderr` are truncated independently at `SandboxConfig.maxOutputBytes`, with a
+ * trailing `...(truncated)` marker. Neither is safe to parse as a complete document without checking
+ * for it.
+ */
 export interface ExecuteResult {
     stdout: string;
     stderr: string;
     exitCode: number;
     timedOut: boolean;
 }
+/**
+ * Construction-time settings shared by every {@link SandboxBackend}. All fields are optional and the
+ * base constructor fills them in, so `{}` is a valid config: `workDir` `/tmp`, `timeoutMs` 30000,
+ * `maxOutputBytes` 5 MiB, `env` `"inherit-scrubbed"`.
+ *
+ * `workDir` is the child process's cwd and the base a relative `uploadFile` path resolves against. It
+ * is not a boundary — under `LocalSandbox` nothing stops a command, or an absolute path, from leaving
+ * it. Only `LinuxSandbox` makes it enforceable.
+ *
+ * `timeoutMs` is the default for every call; `execute(command, { timeoutMs })` overrides it per
+ * command. On expiry the child is killed and the result carries `timedOut: true` with `exitCode`
+ * 124 — the partial output collected so far is still returned.
+ */
 export interface SandboxConfig {
     workDir?: string;
     timeoutMs?: number;
@@ -26,14 +51,53 @@ export interface SandboxConfig {
      */
     env?: EnvPolicy;
 }
+/**
+ * A backend refused a command on policy grounds — the environment works, and it said no. Carries a
+ * stable `code: "sandbox_security"` for callers that prefer not to match on the class.
+ *
+ * Nothing in this package throws it, which is worth knowing before you write a `catch` for it:
+ * `LocalSandbox` and `LinuxSandbox` report a refusal through {@link ExecuteResult} (non-zero
+ * `exitCode`, reason on `stderr`), and a write blocked under confinement surfaces as a plain `Error`
+ * from `uploadFile`. This type exists so a custom backend that must reject a command BEFORE spawning
+ * anything — a container or VM runner enforcing its own policy — can do so in the protocol's
+ * vocabulary instead of inventing an error of its own.
+ */
 export declare class SandboxSecurityError extends Error {
     readonly code: "sandbox_security";
     constructor(message: string);
 }
+/**
+ * A backend cannot be used at all: its runtime is missing or unusable. The distinction from
+ * {@link SandboxSecurityError} is which side failed — there the sandbox worked and denied the
+ * command, here there is no sandbox. Carries `code: "sandbox_not_available"`.
+ *
+ * Nothing in this package throws it either, and that is a position rather than an oversight:
+ * `createSandboxBackend` treats a missing bubblewrap as a degradation, warns once, and hands back an
+ * unconfined `LocalSandbox`. Throw this instead from a backend that must never silently run outside
+ * its isolation.
+ */
 export declare class SandboxNotAvailableError extends Error {
     readonly code: "sandbox_not_available";
     constructor(message: string);
 }
+/**
+ * The execution capability handed to an agent tool, and the extension point for new environments.
+ *
+ * A backend implements exactly two methods, `execute` and `uploadFile`. Everything else here —
+ * `readFile`, `glob`, `grep`, `listDir` — is derived from `execute` by shelling out `cat`, `find`,
+ * `grep` and `ls`, so a subclass that overrides `execute` alone inherits confined reads, searches and
+ * listings for free. It does not inherit confined writes: `writeFile` delegates to `uploadFile`, and
+ * that is the second override `LinuxSandbox` needs.
+ *
+ * Choosing one: `LocalSandbox` runs the command on the host with no isolation and suits code you
+ * already trust; `LinuxSandbox` adds kernel confinement where bubblewrap is available;
+ * `createSandboxBackend` probes and picks between them, and is the right entry point unless you have
+ * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this
+ * package does not ship — write it against these two methods.
+ *
+ * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a
+ * backend whose `execute` is not a POSIX shell must override them as well.
+ */
 export declare abstract class SandboxBackend {
     protected config: SandboxConfig;
     constructor(config?: SandboxConfig);

package/dist/sandbox/types.d.ts

@@ -8,12 +8,37 @@
  * @public
  */
 import type { EnvPolicy } from "../types/env-policy.js";
+/**
+ * What a {@link SandboxBackend} returns for one command.
+ *
+ * `exitCode` is a coarse signal rather than the child's real exit status: the backends in this
+ * package report `0` on success, `124` on timeout, and `1` for everything else — including a command
+ * that exited with its own non-zero code. Read `timedOut` to tell a killed command from a failed one,
+ * and `stderr` for the reason; branching on a specific exit code will not work here.
+ *
+ * `stdout` and `stderr` are truncated independently at `SandboxConfig.maxOutputBytes`, with a
+ * trailing `...(truncated)` marker. Neither is safe to parse as a complete document without checking
+ * for it.
+ */
 export interface ExecuteResult {
     stdout: string;
     stderr: string;
     exitCode: number;
     timedOut: boolean;
 }
+/**
+ * Construction-time settings shared by every {@link SandboxBackend}. All fields are optional and the
+ * base constructor fills them in, so `{}` is a valid config: `workDir` `/tmp`, `timeoutMs` 30000,
+ * `maxOutputBytes` 5 MiB, `env` `"inherit-scrubbed"`.
+ *
+ * `workDir` is the child process's cwd and the base a relative `uploadFile` path resolves against. It
+ * is not a boundary — under `LocalSandbox` nothing stops a command, or an absolute path, from leaving
+ * it. Only `LinuxSandbox` makes it enforceable.
+ *
+ * `timeoutMs` is the default for every call; `execute(command, { timeoutMs })` overrides it per
+ * command. On expiry the child is killed and the result carries `timedOut: true` with `exitCode`
+ * 124 — the partial output collected so far is still returned.
+ */
 export interface SandboxConfig {
     workDir?: string;
     timeoutMs?: number;
@@ -26,14 +51,53 @@ export interface SandboxConfig {
      */
     env?: EnvPolicy;
 }
+/**
+ * A backend refused a command on policy grounds — the environment works, and it said no. Carries a
+ * stable `code: "sandbox_security"` for callers that prefer not to match on the class.
+ *
+ * Nothing in this package throws it, which is worth knowing before you write a `catch` for it:
+ * `LocalSandbox` and `LinuxSandbox` report a refusal through {@link ExecuteResult} (non-zero
+ * `exitCode`, reason on `stderr`), and a write blocked under confinement surfaces as a plain `Error`
+ * from `uploadFile`. This type exists so a custom backend that must reject a command BEFORE spawning
+ * anything — a container or VM runner enforcing its own policy — can do so in the protocol's
+ * vocabulary instead of inventing an error of its own.
+ */
 export declare class SandboxSecurityError extends Error {
     readonly code: "sandbox_security";
     constructor(message: string);
 }
+/**
+ * A backend cannot be used at all: its runtime is missing or unusable. The distinction from
+ * {@link SandboxSecurityError} is which side failed — there the sandbox worked and denied the
+ * command, here there is no sandbox. Carries `code: "sandbox_not_available"`.
+ *
+ * Nothing in this package throws it either, and that is a position rather than an oversight:
+ * `createSandboxBackend` treats a missing bubblewrap as a degradation, warns once, and hands back an
+ * unconfined `LocalSandbox`. Throw this instead from a backend that must never silently run outside
+ * its isolation.
+ */
 export declare class SandboxNotAvailableError extends Error {
     readonly code: "sandbox_not_available";
     constructor(message: string);
 }
+/**
+ * The execution capability handed to an agent tool, and the extension point for new environments.
+ *
+ * A backend implements exactly two methods, `execute` and `uploadFile`. Everything else here —
+ * `readFile`, `glob`, `grep`, `listDir` — is derived from `execute` by shelling out `cat`, `find`,
+ * `grep` and `ls`, so a subclass that overrides `execute` alone inherits confined reads, searches and
+ * listings for free. It does not inherit confined writes: `writeFile` delegates to `uploadFile`, and
+ * that is the second override `LinuxSandbox` needs.
+ *
+ * Choosing one: `LocalSandbox` runs the command on the host with no isolation and suits code you
+ * already trust; `LinuxSandbox` adds kernel confinement where bubblewrap is available;
+ * `createSandboxBackend` probes and picks between them, and is the right entry point unless you have
+ * a reason to pin one. For genuinely untrusted code you want a container or VM backend, which this
+ * package does not ship — write it against these two methods.
+ *
+ * Because the derived helpers assemble shell command lines (arguments escaped for POSIX `sh`), a
+ * backend whose `execute` is not a POSIX shell must override them as well.
+ */
 export declare abstract class SandboxBackend {
     protected config: SandboxConfig;
     constructor(config?: SandboxConfig);

package/dist/scorers.d.ts

@@ -61,6 +61,36 @@ interface JsonShapeOptions {
     /** Include Zod's error message in the failure reason. Default: false. */
     strict?: boolean;
 }
+/**
+ * The built-in scorer factories for {@link Eval}. Each call returns a fresh
+ * `NamedScorer` (`{ name, score }`) to drop into `EvalOptions.scorers`; the
+ * result is stateless and safe to reuse across runs.
+ *
+ *   import { Eval, Scorers } from "@theokit/sdk/eval";
+ *   scorers: [Scorers.exactMatch(), Scorers.jsonShape(MySchema)]
+ *
+ * How they fail: a scorer does not throw for a bad row. A mismatch, an unusable
+ * `expected`, or an output that cannot be parsed all come back as
+ * `{ score: 0, reason: "<why>" }` — `expected_not_string`, `expected_empty`,
+ * `mismatch`, `not_found`, `regex_no_match`, `input_too_large`,
+ * `output_not_numeric`, `expected_not_numeric`, `invalid_json`, `schema_invalid`,
+ * `output_too_large`, `embed_failed`, `verify_gate_empty_command`. When a run
+ * scores 0 across the board, `reason` usually says the dataset is wrong rather
+ * than the model.
+ *
+ * Three of these are NOT pure and NOT free: `llmJudge` and `embeddingSimilarity`
+ * each make one network call PER ROW and need their own credentials, and
+ * `verifyGate` runs a shell command through a `SandboxBackend` — defaulting to
+ * `LocalSandbox`, which is not an isolation boundary. The rest — `exactMatch`,
+ * `containsExpected`, `regex`, `levenshtein`, `numericDiff`, `jsonShape` — are
+ * deterministic, offline, and safe in CI.
+ *
+ * Trap: the default case-sensitivity is NOT uniform. `exactMatch` defaults to
+ * case-SENSITIVE; `containsExpected` and `levenshtein` default to
+ * case-INSENSITIVE. Pass `caseSensitive` explicitly whenever it matters.
+ *
+ * @public
+ */
 export declare const Scorers: {
     /**
      * `output.trim() === expected.trim()`. Refuses empty `expected` (EC-1
@@ -104,13 +134,6 @@ export declare const Scorers: {
      * deterministically. Each scored row costs one embeddings call.
      */
     embeddingSimilarity(opts: EmbeddingSimilarityOptions): NamedScorer;
-    /**
-     * Parse `output` as JSON and validate against a Zod schema.
-     *
-     * - EC-2 fix: output is bounded by `JSON_SHAPE_MAX_BYTES` (1 MB)
-     *   BEFORE `JSON.parse` to avoid OOM on runaway LLM responses.
-     * - `strict: true` includes Zod's first error message in `reason`.
-     */
     /**
      * LLM-as-judge scorer (ADR D205).
      *
@@ -145,6 +168,14 @@ export declare const Scorers: {
      * that rejects shell metacharacters in `execute` is unsupported for this scorer.
      */
     verifyGate(opts: VerifyGateOptions): NamedScorer;
+    /**
+     * Parse `output` as JSON and validate against a Zod schema.
+     *
+     * - EC-2 fix: output is bounded by `JSON_SHAPE_MAX_BYTES` (1e6) BEFORE
+     *   `JSON.parse` to avoid OOM on runaway LLM responses. The bound is applied to
+     *   `output.length` — UTF-16 code units, not bytes, despite the constant's name.
+     * - `strict: true` includes Zod's first error message in `reason`.
+     */
     jsonShape<T extends ZodType>(schema: T, opts?: JsonShapeOptions): NamedScorer;
 };
 export {};