@oscharko-dev/keiko-tools 0.2.0

package/dist/browser/types.d.ts

@@ -0,0 +1,49 @@
+export interface NormalizedNavigateUrl {
+    readonly url: string;
+    readonly host: string;
+    readonly originOnly: string;
+    readonly port: number;
+}
+export interface BrowserViewportPx {
+    readonly width: number;
+    readonly height: number;
+}
+export type BrowserSessionStatus = "open" | "closed";
+export interface BrowserSessionMeta {
+    readonly sessionId: string;
+    readonly cdpPort: number;
+    readonly targetId: string;
+    readonly status: BrowserSessionStatus;
+    readonly createdAt: number;
+}
+export interface BrowserNavigateResult {
+    readonly originOnly: string;
+    readonly httpStatus: number | null;
+}
+export interface BrowserScreenshotPreview {
+    readonly seq: number;
+    readonly viewportPx: BrowserViewportPx;
+    readonly dataBase64: string;
+    readonly persisted: false;
+}
+export interface BrowserScreenshotPersisted {
+    readonly seq: number;
+    readonly viewportPx: BrowserViewportPx;
+    readonly persisted: true;
+    readonly path: string;
+    readonly sha256: string;
+    readonly bytes: number;
+}
+export type BrowserScreenshotResult = BrowserScreenshotPreview | BrowserScreenshotPersisted;
+export interface BrowserContentResult {
+    readonly seq: number;
+    readonly byteLength: number;
+    readonly redactedHtml: string;
+}
+export interface CdpReachability {
+    readonly reachable: boolean;
+    readonly userAgent: string | null;
+    readonly browserVersion: string | null;
+    readonly webSocketDebuggerUrl: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/browser/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/browser/types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IAIpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IAEvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IAEzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,uBAAuB,GAAG,wBAAwB,GAAG,0BAA0B,CAAC;AAE5F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C"}

package/dist/browser/types.js

@@ -0,0 +1,2 @@
+// Data shapes for the browser tool (ADR-0017). Pure types: no runtime imports.
+export {};

package/dist/browser/validators.d.ts

@@ -0,0 +1,6 @@
+import type { NormalizedNavigateUrl } from "./types.js";
+export declare function normalizeCdpPort(value: unknown): number;
+export declare function normalizeNavigateUrl(raw: unknown): NormalizedNavigateUrl;
+export declare function isLoopbackHost(host: string): boolean;
+export declare function isLoopbackUrl(raw: string): boolean;
+//# sourceMappingURL=validators.d.ts.map

package/dist/browser/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/browser/validators.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AASxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcvD;AAKD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CA6BxE;AA8BD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAMD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUlD"}

package/dist/browser/validators.js

@@ -0,0 +1,97 @@
+// ADR-0017 D2 — pure URL validation. NO filesystem, NO network. The localhost→127.0.0.1 rewrite
+// happens here so that downstream code never hands `localhost` to the OS resolver, eliminating the
+// /etc/hosts attack surface even if a downstream caller forgets the rule.
+import { BrowserToolError } from "./errors.js";
+const MIN_PORT = 1024;
+const MAX_PORT = 65535;
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+// Strict literal-host policy: IPv4-mapped IPv6 forms like `::ffff:127.0.0.1` are
+// REJECTED on purpose. ADR-0017 D2 normalises only `localhost`/`127.0.0.1`/`::1`.
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1"]);
+export function normalizeCdpPort(value) {
+    if (typeof value !== "number") {
+        throw new BrowserToolError("BAD_PORT", "CDP port must be a number.");
+    }
+    if (!Number.isInteger(value)) {
+        throw new BrowserToolError("BAD_PORT", "CDP port must be an integer.");
+    }
+    if (value < MIN_PORT || value > MAX_PORT) {
+        throw new BrowserToolError("BAD_PORT", `CDP port must be in the range ${String(MIN_PORT)}-${String(MAX_PORT)}.`);
+    }
+    return value;
+}
+// Parses the URL with the WHATWG parser, rejects non-http(s) schemes, rewrites `localhost` to its
+// literal IP before any further use, then enforces literal-IP loopback + bounded-port. Returns the
+// canonical {url, originOnly, host, port} struct the CDP layer consumes.
+export function normalizeNavigateUrl(raw) {
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new BrowserToolError("BAD_URL", "Navigate URL must be a non-empty string.");
+    }
+    const parsed = parseUrlOrThrow(raw);
+    if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+        throw new BrowserToolError("SCHEME_NOT_ALLOWED", "Navigate URL must use the http or https scheme.");
+    }
+    const rewritten = rewriteLocalhost(parsed);
+    const host = bareHost(rewritten);
+    if (!LOOPBACK_HOSTS.has(host)) {
+        throw new BrowserToolError("ORIGIN_NOT_ALLOWED", "Navigate URL host must be a loopback literal (127.0.0.1 or ::1).");
+    }
+    if (rewritten.port === "") {
+        throw new BrowserToolError("BAD_PORT", "Navigate URL must include an explicit port.");
+    }
+    const port = normalizeCdpPort(Number.parseInt(rewritten.port, 10));
+    return {
+        url: rewritten.toString(),
+        host,
+        originOnly: rewritten.origin,
+        port,
+    };
+}
+function parseUrlOrThrow(raw) {
+    try {
+        return new URL(raw);
+    }
+    catch {
+        throw new BrowserToolError("BAD_URL", "Navigate URL is not a valid URL.");
+    }
+}
+// `URL.hostname` returns `localhost` unchanged; we rewrite to 127.0.0.1 and rebuild the URL so the
+// canonical .url field handed to CDP never contains `localhost`.
+function rewriteLocalhost(parsed) {
+    if (parsed.hostname !== "localhost")
+        return parsed;
+    const clone = new URL(parsed.toString());
+    clone.hostname = "127.0.0.1";
+    return clone;
+}
+// URL.hostname returns `[::1]` for IPv6 input; strip brackets so the LOOPBACK_HOSTS set comparison
+// is performed against the bare literal `::1`.
+function bareHost(parsed) {
+    const h = parsed.hostname;
+    if (h.startsWith("[") && h.endsWith("]"))
+        return h.slice(1, -1);
+    return h;
+}
+// Narrow host-string check: takes a bare hostname (no scheme, no port, no brackets stripped)
+// and returns true if it is a loopback literal. Used by session.ts to validate the host
+// component of webSocketDebuggerUrl returned by /json/version (ADR-0017 D2 H1).
+export function isLoopbackHost(host) {
+    return LOOPBACK_HOSTS.has(host);
+}
+// Re-check after a navigation completes (ADR-0017 D2 layer 2). The CDP `frameNavigated` event
+// reports the effective URL; if it drifted to a non-loopback origin (server-side redirect), the
+// session manager must stop loading and refuse subsequent capture. Pure: takes the post-navigate
+// URL string and returns the typed result.
+export function isLoopbackUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (!ALLOWED_SCHEMES.has(parsed.protocol))
+        return false;
+    const host = bareHost(parsed);
+    return LOOPBACK_HOSTS.has(host);
+}

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+export { TOOL_CODES, ToolError, ToolArgumentError, UnknownToolError, CommandDeniedError, CommandTimeoutError, CommandCancelledError, OutputLimitError, PatchValidationError, PatchApplyDisabledError, PatchApplyError, } from "@oscharko-dev/keiko-security/errors/tools";
+export type { ToolCode } from "@oscharko-dev/keiko-security/errors/tools";
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,GAChB,MAAM,2CAA2C,CAAC;AACnD,YAAY,EAAE,QAAQ,EAAE,MAAM,2CAA2C,CAAC"}

package/dist/errors.js

@@ -0,0 +1,4 @@
+// Re-export shim: the tools error taxonomy now lives in @oscharko-dev/keiko-security
+// (issue #159, ADR-0019). All existing import sites (`from "./errors.js"`) keep resolving
+// unchanged via this barrel.
+export { TOOL_CODES, ToolError, ToolArgumentError, UnknownToolError, CommandDeniedError, CommandTimeoutError, CommandCancelledError, OutputLimitError, PatchValidationError, PatchApplyDisabledError, PatchApplyError, } from "@oscharko-dev/keiko-security/errors/tools";

package/dist/exec.d.ts

@@ -0,0 +1,45 @@
+import type { ChildProcess } from "node:child_process";
+import { type BackendAvailability } from "@oscharko-dev/keiko-sandbox";
+import { type WorkspaceFs, type WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import type { CommandResult, CommandRule, SandboxPolicy } from "./types.js";
+export interface SpawnOptions {
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+    readonly shell: false;
+    readonly detached: boolean;
+}
+export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+export interface ExecutableResolverDeps {
+    readonly workspace: WorkspaceInfo;
+    readonly processEnv: NodeJS.ProcessEnv;
+    readonly fs?: WorkspaceFs | undefined;
+}
+export type ExecutableResolver = (command: string, deps: ExecutableResolverDeps) => string;
+export declare const nodeSpawnFn: SpawnFn;
+export interface HomeProvider {
+    readonly make: () => string;
+    readonly cleanup: (dir: string) => void;
+}
+export declare const nodeHomeProvider: HomeProvider;
+export interface RunCommandDeps {
+    readonly workspace: WorkspaceInfo;
+    readonly policy: SandboxPolicy;
+    readonly commandRules: readonly CommandRule[];
+    readonly spawn: SpawnFn;
+    readonly resolveExecutable?: ExecutableResolver | undefined;
+    readonly processEnv: NodeJS.ProcessEnv;
+    readonly now: () => number;
+    readonly fs?: WorkspaceFs | undefined;
+    readonly home?: HomeProvider | undefined;
+    readonly sandboxAvailability?: BackendAvailability | undefined;
+    readonly platform?: NodeJS.Platform | undefined;
+}
+export interface RunCommandInput {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string | undefined;
+    readonly timeoutMs: number | undefined;
+    readonly signal: AbortSignal;
+}
+export declare function runCommand(input: RunCommandInput, deps: RunCommandDeps): Promise<CommandResult>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKvD,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAsB,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,YAAY,KAClB,YAAY,CAAC;AAElB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IACvC,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,KAAK,MAAM,CAAC;AAE3F,eAAO,MAAM,WAAW,EAAE,OACc,CAAC;AAKzC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,eAAO,MAAM,gBAAgB,EAAE,YAM9B,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAE3B,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAEtC,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAKzC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;CACjD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AA6bD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA2B/F"}

package/dist/exec.js

@@ -0,0 +1,372 @@
+// Command execution — the spawn boundary. Deny-by-default allowlist is checked BEFORE any
+// spawn; the child runs with a clean name-allowlisted env, no shell, and a resolved-in-workspace
+// cwd. Timeout and abort both kill the process group (SIGTERM→SIGKILL after the grace period).
+// stdout/stderr are byte-capped and redacted before they leave this layer (ADR-0006 D3/D5).
+//
+// node:child_process is imported ONLY for the default SpawnFn adapter; all decision logic lives
+// in sandbox.ts (pure). Tests inject a fake SpawnFn for the allowlist/timeout/cancel paths and a
+// real `node`-spawn for the env-isolation / no-shell / real-cancellation integration cases.
+import { spawn as nodeSpawn } from "node:child_process";
+import { accessSync, constants, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join, resolve as resolvePath } from "node:path";
+import { redact } from "@oscharko-dev/keiko-security";
+import { planIsolatedRun, probeBackends, } from "@oscharko-dev/keiko-sandbox";
+import { containedRealPathInfo, isDenied, isWithinWorkspace, PathDeniedError, resolveWithinWorkspace, } from "@oscharko-dev/keiko-workspace";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+import { CommandCancelledError, CommandDeniedError, CommandTimeoutError } from "./errors.js";
+import { buildSandboxEnv, collectSensitiveEnvValues, isCommandAllowed } from "./sandbox.js";
+export const nodeSpawnFn = (command, args, options) => nodeSpawn(command, [...args], options);
+export const nodeHomeProvider = {
+    make: () => mkdtempSync(join(tmpdir(), "keiko-home-")),
+    cleanup: (dir) => {
+        // Best-effort: a leftover temp dir is not worth failing or rejecting the command over.
+        rmSync(dir, { recursive: true, force: true });
+    },
+};
+const POSIX = process.platform !== "win32";
+// Kills the whole process group on POSIX (negative pid) so orphaned grandchildren die too;
+// on Windows, best-effort child.kill() (a tree-kill needs a dependency we cannot add).
+function killGroup(child, sig) {
+    const pid = child.pid;
+    if (pid === undefined) {
+        return;
+    }
+    try {
+        if (POSIX) {
+            process.kill(-pid, sig);
+        }
+        else {
+            child.kill(sig);
+        }
+    }
+    catch {
+        // The child already exited; nothing to signal. Swallowing here keeps termination idempotent.
+    }
+}
+const TRUNCATED_OUTPUT_MARKER = "[TRUNCATED OUTPUT REDACTED]";
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function hasNul(value) {
+    return value.includes("\u0000");
+}
+function realRoot(fs, root) {
+    try {
+        return fs.realPath(root);
+    }
+    catch {
+        return root;
+    }
+}
+function assertBareExecutable(command) {
+    if (command.length === 0 || hasNul(command) || hasPathSeparator(command)) {
+        throw new CommandDeniedError("executable must be a bare PATH-resolved name", command);
+    }
+}
+function pathEntries(processEnv) {
+    const pathValue = processEnv.PATH ?? "";
+    return pathValue.length === 0 ? [] : pathValue.split(delimiter).filter(Boolean);
+}
+function executableExtensions(processEnv) {
+    if (process.platform !== "win32") {
+        return [""];
+    }
+    return (processEnv.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+        .split(";")
+        .filter((value) => value.length > 0);
+}
+function candidateExecutable(command, rawEntry, ext) {
+    const candidate = resolvePath(resolvePath(rawEntry), command + ext);
+    try {
+        accessSync(candidate, constants.X_OK);
+        return { path: candidate, real: realpathSync(candidate) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function assertExecutableOutsideWorkspace(command, lexicalWorkspaceRoot, realWorkspaceRoot, candidate) {
+    if (isWithinWorkspace(lexicalWorkspaceRoot, candidate.path) ||
+        isWithinWorkspace(realWorkspaceRoot, candidate.real)) {
+        throw new CommandDeniedError(`executable resolves inside workspace: ${command}`, command);
+    }
+}
+function defaultResolveExecutable(command, deps) {
+    assertBareExecutable(command);
+    const fs = deps.fs ?? nodeWorkspaceFs;
+    const lexicalWorkspaceRoot = deps.workspace.root;
+    const realWorkspaceRoot = realRoot(fs, lexicalWorkspaceRoot);
+    for (const rawEntry of pathEntries(deps.processEnv)) {
+        for (const ext of executableExtensions(deps.processEnv)) {
+            const candidate = candidateExecutable(command, rawEntry, ext);
+            if (candidate === undefined) {
+                continue;
+            }
+            assertExecutableOutsideWorkspace(command, lexicalWorkspaceRoot, realWorkspaceRoot, candidate);
+            return candidate.real;
+        }
+    }
+    throw new CommandDeniedError(`executable not found on PATH: ${command}`, command);
+}
+// Resolves the isolation wrapper binary (e.g. bwrap) to a real absolute path through the same
+// resolver as the inner command, so the wrapper is PATH-resolved and proven to live outside the
+// workspace before it is ever spawned.
+function resolveWrapperExecutable(name, deps) {
+    const resolver = deps.resolveExecutable ?? defaultResolveExecutable;
+    return resolver(name, { workspace: deps.workspace, processEnv: deps.processEnv, fs: deps.fs });
+}
+// Decides what to spawn. Inherited network → run the executable directly. network:"none" → ask
+// keiko-sandbox for an enforcing wrapper; a fail-closed decision throws (the command never spawns),
+// so untrusted code is never executed without an enforced egress boundary.
+function resolveSpawnTarget(input, deps, executable, cwd) {
+    if (deps.policy.network !== "none") {
+        return { command: executable, args: input.args, attestation: undefined };
+    }
+    const platform = deps.platform ?? process.platform;
+    const availability = deps.sandboxAvailability ?? probeBackends(deps.processEnv, platform);
+    const decision = planIsolatedRun({
+        command: executable,
+        args: input.args,
+        cwd,
+        network: "none",
+        filesystem: deps.policy.filesystem ?? "inherit",
+    }, availability, platform);
+    if (decision.kind === "fail-closed") {
+        throw new CommandDeniedError(decision.reason, input.command);
+    }
+    if (decision.kind === "passthrough") {
+        return { command: executable, args: input.args, attestation: decision.attestation };
+    }
+    return {
+        command: resolveWrapperExecutable(decision.command, deps),
+        args: decision.args,
+        attestation: decision.attestation,
+    };
+}
+function appendCapped(buffers, sink, chunk, max) {
+    if (buffers.truncated) {
+        return false;
+    }
+    const remaining = max - buffers.total;
+    if (chunk.length <= remaining) {
+        sink.push(chunk);
+        buffers.total += chunk.length;
+        return false;
+    }
+    if (remaining > 0) {
+        sink.push(chunk.subarray(0, remaining));
+        buffers.total = max;
+    }
+    buffers.truncated = true;
+    return true; // signals the caller to kill the child (flood protection)
+}
+// Resolves the validated cwd. Lexical containment first, then symlink containment via realpath
+// (S-H1): a cwd that is a symlink escaping the root or resolving into an always-denied path must
+// not become the spawn cwd. Both cases surface as workspace path errors, which the host maps to a
+// tool error — the command never spawns.
+function resolveCwd(deps, cwd) {
+    const lexical = resolveWithinWorkspace(deps.workspace.root, cwd ?? ".");
+    const fs = deps.fs ?? nodeWorkspaceFs;
+    const rel = lexical.slice(deps.workspace.root.length).replace(/^[/\\]/, "");
+    if (isDenied(rel === "" ? (cwd ?? ".") : rel)) {
+        throw new PathDeniedError("path matches an always-on deny pattern", cwd ?? ".");
+    }
+    const info = containedRealPathInfo(fs, deps.workspace.root, lexical);
+    if (isDenied(info.realRelative)) {
+        throw new PathDeniedError("path matches an always-on deny pattern", cwd ?? ".");
+    }
+    return lexical;
+}
+function buildResult(input, buffers, state, exitCode, termSignal, deps, startedAt, attestation) {
+    const secrets = collectSensitiveEnvValues(deps.processEnv, deps.policy.envAllowlist);
+    const attest = attestation === undefined ? {} : { attestation };
+    if (buffers.truncated) {
+        return {
+            command: input.command,
+            args: input.args,
+            exitCode,
+            signal: termSignal,
+            stdout: TRUNCATED_OUTPUT_MARKER,
+            stderr: TRUNCATED_OUTPUT_MARKER,
+            durationMs: deps.now() - startedAt,
+            timedOut: state.timedOut,
+            truncated: true,
+            ...attest,
+        };
+    }
+    return {
+        command: input.command,
+        args: input.args,
+        exitCode,
+        signal: termSignal,
+        stdout: redact(Buffer.concat(buffers.out).toString("utf8"), secrets),
+        stderr: redact(Buffer.concat(buffers.err).toString("utf8"), secrets),
+        durationMs: deps.now() - startedAt,
+        timedOut: state.timedOut,
+        truncated: buffers.truncated,
+        ...attest,
+    };
+}
+function cleanup(state, signal) {
+    if (state.timer !== undefined) {
+        clearTimeout(state.timer);
+    }
+    if (state.graceTimer !== undefined) {
+        clearTimeout(state.graceTimer);
+    }
+    if (state.onAbort !== undefined) {
+        signal.removeEventListener("abort", state.onAbort);
+    }
+    // Remove the ephemeral HOME exactly once, on whichever settle path fires first (C5).
+    if (!state.homeCleaned && state.home !== undefined && state.homeDir !== undefined) {
+        state.homeCleaned = true;
+        state.home.cleanup(state.homeDir);
+    }
+}
+// Escalates from SIGTERM to SIGKILL after the grace period so a child ignoring SIGTERM is still
+// guaranteed to terminate within terminationGraceMs of the trigger.
+function terminate(child, policy, state) {
+    killGroup(child, "SIGTERM");
+    state.graceTimer = setTimeout(() => {
+        killGroup(child, "SIGKILL");
+    }, policy.terminationGraceMs);
+    state.graceTimer.unref();
+}
+function wireStreams(child, buffers, policy, state) {
+    const onData = (sink) => (chunk) => {
+        if (appendCapped(buffers, sink, chunk, policy.maxOutputBytes)) {
+            terminate(child, policy, state); // output flood → kill
+        }
+    };
+    child.stdout?.on("data", onData(buffers.out));
+    child.stderr?.on("data", onData(buffers.err));
+}
+function settleOnClose(ctx, resolve, reject) {
+    ctx.child.on("close", (code, signalName) => {
+        if (ctx.state.settled) {
+            return;
+        }
+        ctx.state.settled = true;
+        cleanup(ctx.state, ctx.input.signal);
+        if (ctx.state.timedOut) {
+            reject(new CommandTimeoutError("command timed out", timeoutOf(ctx)));
+            return;
+        }
+        if (ctx.input.signal.aborted) {
+            reject(new CommandCancelledError("command cancelled"));
+            return;
+        }
+        resolve(buildResult(ctx.input, ctx.buffers, ctx.state, code, signalName, ctx.deps, ctx.startedAt, ctx.attestation));
+    });
+    ctx.child.on("error", (error) => {
+        if (ctx.state.settled) {
+            return;
+        }
+        ctx.state.settled = true;
+        cleanup(ctx.state, ctx.input.signal);
+        reject(error);
+    });
+}
+function timeoutOf(ctx) {
+    return ctx.input.timeoutMs ?? ctx.deps.policy.defaultTimeoutMs;
+}
+function armTimersAndAbort(ctx) {
+    const ms = timeoutOf(ctx);
+    ctx.state.timer = setTimeout(() => {
+        ctx.state.timedOut = true;
+        terminate(ctx.child, ctx.deps.policy, ctx.state);
+    }, ms);
+    ctx.state.timer.unref();
+    const onAbort = () => {
+        terminate(ctx.child, ctx.deps.policy, ctx.state);
+    };
+    ctx.state.onAbort = onAbort;
+    if (ctx.input.signal.aborted) {
+        onAbort();
+    }
+    else {
+        ctx.input.signal.addEventListener("abort", onAbort, { once: true });
+    }
+}
+function asError(error, fallback) {
+    return error instanceof Error ? error : new Error(fallback);
+}
+function validateRunCommandInput(input, deps) {
+    if (!Array.isArray(deps.policy.envAllowlist) || deps.policy.envAllowlist.length === 0) {
+        throw new CommandDeniedError("sandbox envAllowlist must be a non-empty array", input.command);
+    }
+    const decision = isCommandAllowed(deps.commandRules, input.command, input.args);
+    if (!decision.allowed) {
+        throw new CommandDeniedError(decision.reason ?? "command denied", input.command);
+    }
+}
+function resolveExecutable(input, deps) {
+    const resolver = deps.resolveExecutable ?? defaultResolveExecutable;
+    return resolver(input.command, {
+        workspace: deps.workspace,
+        processEnv: deps.processEnv,
+        fs: deps.fs,
+    });
+}
+function createRunState(home, homeDir) {
+    return {
+        settled: false,
+        timedOut: false,
+        timer: undefined,
+        graceTimer: undefined,
+        onAbort: undefined,
+        home,
+        homeDir,
+        homeCleaned: false,
+    };
+}
+function spawnChild(input, deps, target, cwd, env, state) {
+    try {
+        return deps.spawn(target.command, target.args, { cwd, env, shell: false, detached: POSIX });
+    }
+    catch (error) {
+        cleanup(state, input.signal);
+        throw asError(error, "spawn failed");
+    }
+}
+function runSpawnedChild(ctx) {
+    return new Promise((resolve, reject) => {
+        wireStreams(ctx.child, ctx.buffers, ctx.deps.policy, ctx.state);
+        settleOnClose(ctx, resolve, reject);
+        armTimersAndAbort(ctx);
+    });
+}
+// Runs an allowlisted command. Rejects with CommandDeniedError (before spawn) for a denied
+// command or a workspace-escaping cwd (PathEscapeError), CommandTimeoutError on timeout, and
+// CommandCancelledError on abort; otherwise resolves a redacted, byte-capped CommandResult. All
+// failure paths are Promise rejections — the function never throws synchronously.
+export function runCommand(input, deps) {
+    try {
+        validateRunCommandInput(input, deps);
+        const executable = resolveExecutable(input, deps);
+        const cwd = resolveCwd(deps, input.cwd);
+        const target = resolveSpawnTarget(input, deps, executable, cwd);
+        const env = buildSandboxEnv(deps.processEnv, deps.policy.envAllowlist);
+        const home = deps.home ?? nodeHomeProvider;
+        const homeDir = home.make();
+        env.HOME = homeDir;
+        env.USERPROFILE = homeDir;
+        const state = createRunState(home, homeDir);
+        const child = spawnChild(input, deps, target, cwd, env, state);
+        const buffers = { out: [], err: [], total: 0, truncated: false };
+        const ctx = {
+            child,
+            input,
+            deps,
+            buffers,
+            state,
+            startedAt: deps.now(),
+            attestation: target.attestation,
+        };
+        return runSpawnedChild(ctx);
+    }
+    catch (error) {
+        return Promise.reject(asError(error, "command execution failed"));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export type { CommandResult, CommandRule, CommandRunInput, FilesystemPolicy, NetworkPolicy, PatchApplyResult, PatchChangeKind, PatchConflict, PatchFileChange, PatchHunk, PatchLimits, PatchRejection, PatchRejectionCode, PatchValidation, SandboxPolicy, ToolHostConfig, ToolHostConfigInput, } from "./types.js";
+export { DEFAULT_COMMAND_RULES, DEFAULT_ENV_ALLOWLIST, DEFAULT_PATCH_LIMITS, DEFAULT_SANDBOX_POLICY, DEFAULT_TOOL_HOST_CONFIG, resolveToolHostConfig, } from "./types.js";
+export { CommandCancelledError, CommandDeniedError, CommandTimeoutError, OutputLimitError, PatchApplyDisabledError, PatchApplyError, PatchValidationError, TOOL_CODES, ToolArgumentError, ToolError, UnknownToolError, type ToolCode, } from "./errors.js";
+export { buildSandboxEnv, collectSensitiveEnvValues, isCommandAllowed, type CommandDecision, } from "./sandbox.js";
+export type { WorkspaceWriter } from "./writer.js";
+export { runCommand, type ExecutableResolver, type ExecutableResolverDeps, type HomeProvider, type RunCommandDeps, type RunCommandInput, type SpawnFn, type SpawnOptions, } from "./exec.js";
+export { applyPatch, buildRestorePatch, invertPatch, renderDryRun, validatePatch, type ApplyDeps, type ValidateDeps, } from "./patch.js";
+export { normalizeUnifiedDiffHunks } from "./patch-normalize.js";
+export { parseUnifiedDiff, PatchParseError, type ParsedPatch } from "./patch-parse.js";
+export { computeFileContent, type ApplyOutcome, type HunkConflict } from "./patch-content.js";
+export { TOOL_DEFINITIONS } from "./schemas.js";
+export { WorkspaceToolHost } from "./registry.js";
+export * from "./terminal-policy.js";
+export { BROWSER_ERROR_CODES, BrowserToolError, type BrowserErrorCode } from "./browser/errors.js";
+export { isLoopbackHost, isLoopbackUrl, normalizeCdpPort, normalizeNavigateUrl, } from "./browser/validators.js";
+export type { BrowserContentResult, BrowserNavigateResult, BrowserScreenshotPersisted, BrowserScreenshotPreview, BrowserScreenshotResult, BrowserSessionMeta, BrowserSessionStatus, BrowserViewportPx, CdpReachability, NormalizedNavigateUrl, } from "./browser/types.js";
+export { CdpClient, PERMITTED_CDP_METHODS, type CdpCloseListener, type CdpClientOptions, type CdpEventListener, } from "./browser/cdp-client.js";
+export { createBrowserSessionManager, type BrowserEventEmitter, type BrowserEventEnvelope, type BrowserEventKind, type BrowserSessionManager, type BrowserSessionManagerOptions, type BrowserSideFileWriter, } from "./browser/session.js";
+export { KEIKO_TOOLS_VERSION } from "./version.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,YAAY,EACV,aAAa,EACb,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,eAAe,EACf,SAAS,EACT,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EACL,UAAU,EACV,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,YAAY,GAClB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,KAAK,SAAS,EACd,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG9F,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAKlD,cAAc,sBAAsB,CAAC;AAGrC,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EACL,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,SAAS,EACT,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}