@theokit/sdk 4.19.4 → 4.21.0

package/dist/sandbox/linux-sandbox.d.ts

@@ -0,0 +1,115 @@
+import type { BwrapDetection, SandboxMode } from "./bwrap.js";
+import { LocalSandbox } from "./local-sandbox.js";
+import type { SandboxBackend, SandboxConfig } from "./types.js";
+/**
+ * M57 — the single source of truth for the sandbox command wrap. Turns `command` into
+ * `<bin> <bwrap flags> [--seccomp 3] -- /bin/sh -c '<command>' [3< <bpf>]`, or `null` when the policy
+ * skips the sandbox (`danger-full-access`). Extracted from `LinuxSandbox.wrapCommand` so the interactive
+ * PTY backend (M57) can reuse the EXACT wrap the one-shot `run_shell` already uses (DRY) — faithful to
+ * Codex, where the sandbox transforms the argv before the PTY spawns it (`sandboxing/src/manager.rs:321`).
+ */
+export declare function wrapCommandForSandbox(mode: SandboxMode, opts: {
+    cwd: string;
+    network?: boolean;
+    env?: Record<string, string>;
+    bin?: string;
+    seccompPath?: string;
+}, command: string): string | null;
+export declare function allowlistedEnv(source?: NodeJS.ProcessEnv): Record<string, string>;
+export declare class LinuxSandbox extends LocalSandbox {
+    private readonly mode;
+    private readonly network;
+    private readonly cwd;
+    private readonly bin;
+    private readonly env;
+    /** M63 — path to the cBPF seccomp program written host-side; passed to `bwrap --seccomp 3` via a
+     * shell redirect. `undefined` when the network is unrestricted OR generation failed (honest fallback). */
+    private readonly seccompPath;
+    constructor(config: SandboxConfig, opts: {
+        mode: SandboxMode;
+        network?: boolean;
+        bin?: string;
+        env?: Record<string, string>;
+    });
+    /** Extracted for test visibility — delegates to the pure `wrapCommandForSandbox` (M57, single wrap SoT). */
+    wrapCommand(command: string): string | null;
+    execute(command: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<import("./types.js").ExecuteResult>;
+}
+/**
+ * M63 — the restricted-network seccomp program is DETERMINISTIC, so write it ONCE per process and
+ * reuse the path across every LinuxSandbox (no per-instance temp accumulation).
+ *
+ * ARCH GUARD (review HIGH): `buildSeccompFilter` emits an x86_64 program whose arch guard KILLs every
+ * syscall whose `seccomp_data.arch != AUDIT_ARCH_X86_64`. On a non-x86_64 host that would brick EVERY
+ * sandboxed command (the first execve is killed) — and silently, because generation succeeds and bwrap
+ * accepts it. So we REFUSE to install on non-x64 and WARN through the honest-downgrade channel (bwrap
+ * FS/network confinement still applies), exactly like the bwrap-missing fallback. `arch` is injectable
+ * for tests. Cleaned on exit AND on SIGINT/SIGTERM (TUI Ctrl+C would otherwise leak the temp dir).
+ */
+export declare function seccompPathForArch(arch: string, warn: (m: string) => void): string | undefined;
+/** M57 — exported so the interactive PTY backend reuses the SAME memoized x64-gated seccomp program. */
+export declare function restrictedSeccompPath(): string | undefined;
+/** Test seam: reset the WARN-once latch. */
+export declare function resetSandboxWarnLatch(): void;
+/** Durable sandbox posture for the UI — the honest answer to "am I kernel-enforced right now?". */
+export interface SandboxPosture {
+    mode: SandboxMode;
+    enforced: boolean;
+    detail: string;
+}
+/**
+ * MEDIUM-2: compute the posture so a surface (TUI footer) can show enforcement DURABLY instead of a
+ * one-shot warn. `danger-full-access` is honestly reported as unenforced; an unavailable bwrap reports
+ * the downgrade reason so the user never believes they are confined when they are not.
+ */
+export declare function resolveSandboxPosture(opts: {
+    mode: SandboxMode;
+    detect?: () => BwrapDetection;
+}): SandboxPosture;
+export interface CreateSandboxBackendOptions {
+    mode: SandboxMode;
+    workDir?: string;
+    network?: boolean;
+    timeoutMs?: number;
+    /** Injectable for tests; defaults to the real 3-probe detection. */
+    detect?: () => BwrapDetection;
+    /** Injectable for tests; defaults to console.warn. */
+    warn?: (message: string) => void;
+}
+/**
+ * Honest factory: bwrap available + mode wants confinement → `LinuxSandbox` (kernel enforcement,
+ * running the VALIDATED absolute bin); `danger-full-access` → plain `LocalSandbox` silently (explicit
+ * opt-out, `bwrap.rs:245-252`); bwrap unavailable → WARN once + `LocalSandbox` (the declarative M23
+ * gating remains the guard). NEVER pretends to sandbox — the fallback is loud, mirroring Codex's
+ * MISSING_BWRAP_WARNING. The durable posture lives in `resolveSandboxPosture` for the UI.
+ */
+export declare function createSandboxBackend(opts: CreateSandboxBackendOptions): SandboxBackend;
+/** Reset para testes — o latch é estado de módulo e testes precisam de isolamento. */
+export declare function resetInteractiveWarnLatch(): void;
+export interface InteractiveWrapOptions {
+    mode: SandboxMode;
+    /** `true` mantém a rede. Default `false`, igual ao `run_shell` não-interativo. */
+    network?: boolean;
+    /** Injetável para testes; default é a detecção real memoizada. */
+    detect?: () => BwrapDetection;
+    /** Injetável para testes; default é `console.warn` com redação. */
+    warn?: (message: string) => void;
+}
+/**
+ * A composição que o caminho interativo precisa — o par de `createSandboxBackend`.
+ *
+ * `createSandboxBackend` resolve isto para o caminho não-interativo devolvendo um BACKEND pronto. O
+ * PTY não aceita um backend: ele é dono do spawn e só admite transformar o comando. Esta função
+ * entrega a MESMA decisão na forma que o PTY aceita — `(command, cwd) => string | null` —, pronta
+ * para `new PtyInteractiveBackend({ wrapCommand: interactiveWrapCommand({ mode }) })`.
+ *
+ * A detecção é consultada **a cada wrap**, não congelada na construção: uma sessão interativa vive
+ * por horas, e uma detecção positiva obsoleta continuaria afirmando confinamento depois de o binário
+ * sumir (a revalidação por `existsSync` vive dentro de `detectBwrapMemoizado`).
+ *
+ * As duas rotas que devolvem `null` são semanticamente diferentes e o código não as funde:
+ * `danger-full-access` é opt-out explícito e NÃO avisa; bwrap indisponível é falha e avisa uma vez.
+ */
+export declare function interactiveWrapCommand(opts: InteractiveWrapOptions): (command: string, cwd: string) => string | null;

package/dist/sandbox/seccomp.d.cts

@@ -0,0 +1,10 @@
+export interface SeccompOptions {
+    /** When true (network off), also deny the socket set + non-AF_UNIX socket(). */
+    networkRestricted: boolean;
+}
+/**
+ * Build the cBPF seccomp program as a `Buffer` (each `sock_filter` = 8 bytes). Jump targets are
+ * expressed against labels and back-patched to relative offsets, so the layout is deterministic and
+ * unit-testable against the authoritative syscall list.
+ */
+export declare function buildSeccompFilter(opts: SeccompOptions): Buffer;

package/dist/sandbox/seccomp.d.ts

@@ -0,0 +1,10 @@
+export interface SeccompOptions {
+    /** When true (network off), also deny the socket set + non-AF_UNIX socket(). */
+    networkRestricted: boolean;
+}
+/**
+ * Build the cBPF seccomp program as a `Buffer` (each `sock_filter` = 8 bytes). Jump targets are
+ * expressed against labels and back-patched to relative offsets, so the layout is deterministic and
+ * unit-testable against the authoritative syscall list.
+ */
+export declare function buildSeccompFilter(opts: SeccompOptions): Buffer;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.19.4",
-  "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
+  "version": "4.21.0",
+  "description": "TypeScript SDK for the Theo agent harness \u2014 same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheodev/theokit-sdk#readme",
   "bugs": "https://github.com/usetheodev/theokit-sdk/issues",