atabey-shared 0.0.23 → 0.0.25

package/dist/resilience.js

@@ -0,0 +1,217 @@
+/**
+ * Polly-style resilience primitives — no external deps.
+ *
+ * - withRetry: exponential backoff + jitter for transient failures
+ * - CircuitBreaker: closed → open → half-open state machine
+ * - withResilience: compose retry + circuit breaker
+ *
+ * Typical use: LLM provider rate limits, timeouts, 5xx, network blips.
+ */
+export class CircuitOpenError extends Error {
+    circuit;
+    retryAfterMs;
+    constructor(circuit, retryAfterMs) {
+        super(`[CircuitBreaker:${circuit}] Circuit is OPEN — rejecting call. Retry after ~${retryAfterMs}ms`);
+        this.name = "CircuitOpenError";
+        this.circuit = circuit;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class CircuitBreaker {
+    state = "closed";
+    failures = 0;
+    successes = 0;
+    openedAt = 0;
+    failureThreshold;
+    successThreshold;
+    openMs;
+    name;
+    constructor(options = {}) {
+        this.failureThreshold = options.failureThreshold ?? 5;
+        this.successThreshold = options.successThreshold ?? 2;
+        this.openMs = options.openMs ?? 30_000;
+        this.name = options.name ?? "default";
+    }
+    getState() {
+        this.maybeTransitionToHalfOpen();
+        return this.state;
+    }
+    getStats() {
+        return {
+            state: this.getState(),
+            failures: this.failures,
+            successes: this.successes,
+            name: this.name,
+        };
+    }
+    /** Manual reset (e.g. after operator intervention). */
+    reset() {
+        this.state = "closed";
+        this.failures = 0;
+        this.successes = 0;
+        this.openedAt = 0;
+    }
+    async exec(fn) {
+        this.maybeTransitionToHalfOpen();
+        if (this.state === "open") {
+            const retryAfterMs = Math.max(0, this.openMs - (Date.now() - this.openedAt));
+            throw new CircuitOpenError(this.name, retryAfterMs);
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (err) {
+            this.onFailure();
+            throw err;
+        }
+    }
+    maybeTransitionToHalfOpen() {
+        if (this.state === "open" && Date.now() - this.openedAt >= this.openMs) {
+            this.state = "half-open";
+            this.successes = 0;
+        }
+    }
+    onSuccess() {
+        if (this.state === "half-open") {
+            this.successes++;
+            if (this.successes >= this.successThreshold) {
+                this.state = "closed";
+                this.failures = 0;
+                this.successes = 0;
+            }
+            return;
+        }
+        // closed: decay failure count on success
+        this.failures = 0;
+    }
+    onFailure() {
+        this.failures++;
+        this.successes = 0;
+        if (this.state === "half-open") {
+            this.trip();
+            return;
+        }
+        if (this.failures >= this.failureThreshold) {
+            this.trip();
+        }
+    }
+    trip() {
+        this.state = "open";
+        this.openedAt = Date.now();
+    }
+}
+export function computeBackoffDelay(attempt, options = {}) {
+    const base = options.baseDelayMs ?? 100;
+    const max = options.maxDelayMs ?? 10_000;
+    const factor = options.factor ?? 2;
+    const jitter = options.jitter !== false;
+    // attempt is 1-based for first retry after failure → attempt 1 => base * factor^0
+    const exp = Math.max(0, attempt - 1);
+    let delay = Math.min(max, base * Math.pow(factor, exp));
+    if (jitter) {
+        delay = Math.floor(Math.random() * delay);
+    }
+    return delay;
+}
+export async function withRetry(fn, options = {}) {
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+    const retryIf = options.retryIf ?? (() => true);
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (options.signal?.aborted) {
+            throw options.signal.reason ?? new Error("Aborted");
+        }
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            lastError = err;
+            const isLast = attempt >= maxAttempts;
+            if (isLast || !retryIf(err, attempt)) {
+                throw err;
+            }
+            const delay = computeBackoffDelay(attempt, options);
+            options.onRetry?.(err, attempt, delay);
+            await sleep(delay, options.signal);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Execute `fn` through optional circuit breaker + retry with exponential backoff.
+ */
+export async function withResilience(fn, options = {}) {
+    const breaker = options.circuitBreaker;
+    const skipOpen = options.skipRetryOnOpenCircuit !== false;
+    const retryOpts = {
+        ...options.retry,
+        retryIf: (err, attempt) => {
+            if (skipOpen && err instanceof CircuitOpenError)
+                return false;
+            return options.retry?.retryIf ? options.retry.retryIf(err, attempt) : true;
+        },
+    };
+    return withRetry(async (attempt) => {
+        if (breaker) {
+            return breaker.exec(() => fn(attempt));
+        }
+        return fn(attempt);
+    }, retryOpts);
+}
+/** Heuristic: retry rate limits, timeouts, and common transient network errors. */
+export function isTransientError(error) {
+    if (error instanceof CircuitOpenError)
+        return false;
+    if (!error)
+        return false;
+    const msg = error instanceof Error ? error.message : String(error);
+    const lower = msg.toLowerCase();
+    const code = error.code;
+    const status = error.status;
+    if (status === 429 || status === 502 || status === 503 || status === 504)
+        return true;
+    if (code === "ETIMEDOUT" || code === "ECONNRESET" || code === "EAI_AGAIN" || code === "ENOTFOUND") {
+        return true;
+    }
+    if (lower.includes("rate limit") ||
+        lower.includes("too many requests") ||
+        lower.includes("timeout") ||
+        lower.includes("temporar") ||
+        lower.includes("econnreset") ||
+        lower.includes("socket hang up")) {
+        return true;
+    }
+    return false;
+}
+/** Shared breakers for common services (lazy). */
+const breakers = new Map();
+export function getCircuitBreaker(name, options) {
+    let b = breakers.get(name);
+    if (!b) {
+        b = new CircuitBreaker({ name, ...options });
+        breakers.set(name, b);
+    }
+    return b;
+}
+export function resetAllCircuitBreakers() {
+    for (const b of breakers.values())
+        b.reset();
+    breakers.clear();
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error("Aborted"));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new Error("Aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=resilience.js.map

package/dist/resilience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.js","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"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"}

package/dist/sandbox-fs.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sandboxed filesystem mutations — Phase 1.2.
+ *
+ * - Always holds AtomicFileLock (try/finally).
+ * - When runtime=container: write via container stdin → /workspace/<path>
+ * - When runtime=uid|none: write on host under projectRoot (safePath caller responsibility)
+ * - ATABEY_SANDBOX_REQUIRED=true rejects writes if isolation is none
+ */
+import { type SandboxRuntimeConfig } from "./sandbox-runtime.js";
+export interface SandboxFsWriteResult {
+    absolutePath: string;
+    relativePath: string;
+    runtime: SandboxRuntimeConfig["effectiveMode"];
+    isolationLabel: string;
+    bytes: number;
+}
+/**
+ * Normalize user path to a project-relative POSIX path.
+ * Absolute paths are accepted only if they resolve inside projectRoot.
+ */
+export declare function assertSafeRelativePath(userPath: string, projectRoot?: string): string;
+/**
+ * Write file content under project root using the active sandbox runtime.
+ */
+export declare function writeFileInSandbox(projectRoot: string, userPath: string, content: string, options?: {
+    ownerId?: string;
+    timeoutMs?: number;
+}): Promise<SandboxFsWriteResult>;

package/dist/sandbox-fs.js

@@ -0,0 +1,148 @@
+/**
+ * Sandboxed filesystem mutations — Phase 1.2.
+ *
+ * - Always holds AtomicFileLock (try/finally).
+ * - When runtime=container: write via container stdin → /workspace/<path>
+ * - When runtime=uid|none: write on host under projectRoot (safePath caller responsibility)
+ * - ATABEY_SANDBOX_REQUIRED=true rejects writes if isolation is none
+ */
+import fs from "fs";
+import path from "path";
+import { AtomicFileLock } from "./file-lock.js";
+import { resolveSandboxRuntimeConfig, runInSandbox, SandboxRequiredError, } from "./sandbox-runtime.js";
+/**
+ * Normalize user path to a project-relative POSIX path.
+ * Absolute paths are accepted only if they resolve inside projectRoot.
+ */
+export function assertSafeRelativePath(userPath, projectRoot) {
+    if (!userPath || !userPath.trim()) {
+        throw new Error("[SANDBOX_FS] Empty path is not allowed");
+    }
+    const trimmed = userPath.trim();
+    if (trimmed.includes("\0")) {
+        throw new Error("[SANDBOX_FS] Illegal null byte in path");
+    }
+    let rel = trimmed.replace(/\\/g, "/");
+    // Absolute path → must live under projectRoot
+    if (path.isAbsolute(trimmed) || rel.startsWith("/")) {
+        if (!projectRoot) {
+            throw new Error(`[SANDBOX_FS] Absolute paths require projectRoot: "${userPath}"`);
+        }
+        const root = path.resolve(projectRoot);
+        const abs = path.resolve(trimmed);
+        if (!abs.startsWith(root + path.sep) && abs !== root) {
+            throw new Error(`[SANDBOX_FS] Absolute path escapes project root: "${userPath}"`);
+        }
+        rel = path.relative(root, abs).replace(/\\/g, "/");
+        if (!rel || rel === ".") {
+            throw new Error("[SANDBOX_FS] Path resolves to project root; refuse write");
+        }
+        if (rel.startsWith("..")) {
+            throw new Error(`[SANDBOX_FS] Path traversal denied: "${userPath}"`);
+        }
+        return rel;
+    }
+    // Relative: reject .. segments
+    const parts = [];
+    for (const seg of rel.split("/")) {
+        if (!seg || seg === ".")
+            continue;
+        if (seg === "..") {
+            throw new Error(`[SANDBOX_FS] Path traversal denied: "${userPath}"`);
+        }
+        parts.push(seg);
+    }
+    if (parts.length === 0) {
+        throw new Error("[SANDBOX_FS] Path resolves to project root; refuse write");
+    }
+    return parts.join("/");
+}
+function shellSingleQuote(s) {
+    // Safe for sh single-quoted strings
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function createLock(projectRoot) {
+    return new AtomicFileLock({
+        projectRoot,
+        locksDir: path.join(projectRoot, ".atabey", "locks"),
+        ttlMs: 5 * 60 * 1000,
+        timeoutMs: 15_000,
+    });
+}
+function hostWriteAtomic(absolutePath, content) {
+    const dir = path.dirname(absolutePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Write exact bytes (callers decide trailing newline — patch/replace need fidelity)
+    const tempPath = `${absolutePath}.${Math.random().toString(36).slice(2, 9)}.tmp`;
+    try {
+        fs.writeFileSync(tempPath, content, "utf8");
+        fs.renameSync(tempPath, absolutePath);
+    }
+    catch (err) {
+        try {
+            if (fs.existsSync(tempPath))
+                fs.unlinkSync(tempPath);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+/**
+ * Write file content under project root using the active sandbox runtime.
+ */
+export async function writeFileInSandbox(projectRoot, userPath, content, options) {
+    const root = path.resolve(projectRoot);
+    const relativePath = assertSafeRelativePath(userPath, root);
+    const absolutePath = path.resolve(root, relativePath);
+    // Belt-and-suspenders: stay inside root
+    if (!absolutePath.startsWith(root + path.sep) && absolutePath !== root) {
+        throw new Error(`[SANDBOX_FS] Resolved path escapes project root: "${userPath}"`);
+    }
+    const cfg = resolveSandboxRuntimeConfig(root, options?.timeoutMs);
+    if (cfg.required && cfg.effectiveMode === "none") {
+        throw new SandboxRequiredError("[SANDBOX_REQUIRED] File write blocked: no sandbox isolation available. " +
+            "Set ATABEY_SANDBOX_RUNTIME=container (Podman/Docker) or uid, or disable ATABEY_SANDBOX_REQUIRED.");
+    }
+    const owner = options?.ownerId || process.env.ATABEY_ACTIVE_AGENT || "mcp-writer";
+    const lock = createLock(root);
+    const posixRel = relativePath.split(path.sep).join("/");
+    return lock.withLock(relativePath, owner, async () => {
+        if (cfg.effectiveMode === "container" && cfg.engine !== "none") {
+            const dir = path.posix.dirname(posixRel);
+            const script = dir === "."
+                ? `cat > ${shellSingleQuote(posixRel)}`
+                : `mkdir -p ${shellSingleQuote(dir)} && cat > ${shellSingleQuote(posixRel)}`;
+            const result = await runInSandbox({
+                command: "sh",
+                args: ["-c", script],
+                projectRoot: root,
+                timeoutMs: options?.timeoutMs ?? cfg.timeoutMs,
+                stdin: content,
+            });
+            if (result.code !== 0) {
+                throw new Error(`[SANDBOX_FS] Container write failed (code ${result.code}): ${result.stderr || result.stdout}`.trim());
+            }
+            return {
+                absolutePath,
+                relativePath,
+                runtime: "container",
+                isolationLabel: result.isolationLabel,
+                bytes: Buffer.byteLength(content, "utf8"),
+            };
+        }
+        // uid | none — host write confined to project root
+        hostWriteAtomic(absolutePath, content);
+        return {
+            absolutePath,
+            relativePath,
+            runtime: cfg.effectiveMode,
+            isolationLabel: cfg.effectiveMode === "uid"
+                ? "uid host write (project-bound)"
+                : "host write (project-bound)",
+            bytes: Buffer.byteLength(content, "utf8"),
+        };
+    });
+}
+//# sourceMappingURL=sandbox-fs.js.map

package/dist/sandbox-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-fs.js","sourceRoot":"","sources":["../src/sandbox-fs.ts"],"names":[],"mappings":"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"}

package/dist/sandbox-runtime.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Sandbox Runtime — Phase 1.1 execution isolation for agent shell commands.
+ *
+ * Modes (ATABEY_SANDBOX_RUNTIME):
+ *   none      — host spawn (legacy; allow-list only)
+ *   uid       — host spawn with uid/gid drop (see sandbox.ts)
+ *   container — Docker/Podman run with network=none, resource limits, project mount
+ *   auto      — container if engine available, else uid if configured, else none
+ *
+ * Enterprise hardening:
+ *   ATABEY_SANDBOX_REQUIRED=true  → deny execution when isolation is effectively "none"
+ *
+ * Container defaults:
+ *   ATABEY_SANDBOX_ENGINE=podman|docker|auto  (prefer podman, then docker)
+ *   ATABEY_SANDBOX_IMAGE=node:20-bookworm-slim
+ *   ATABEY_SANDBOX_MEMORY=512m
+ *   ATABEY_SANDBOX_CPUS=1
+ *   ATABEY_SANDBOX_PIDS=256
+ *   ATABEY_SANDBOX_NETWORK=none
+ */
+import { resolveSandboxIdentity } from "./sandbox.js";
+export type SandboxRuntimeMode = "none" | "uid" | "container" | "auto";
+export type SandboxEngine = "podman" | "docker" | "none";
+export interface SandboxRuntimeConfig {
+    mode: SandboxRuntimeMode;
+    /** Resolved effective mode after auto detection. */
+    effectiveMode: "none" | "uid" | "container";
+    engine: SandboxEngine;
+    image: string;
+    memory: string;
+    cpus: string;
+    pidsLimit: number;
+    network: string;
+    required: boolean;
+    projectRoot: string;
+    timeoutMs: number;
+}
+export interface RunInSandboxRequest {
+    command: string;
+    args: string[];
+    projectRoot: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    /** Optional stdin payload (e.g. file content for container-mediated writes). */
+    stdin?: string | Buffer;
+}
+export interface RunInSandboxResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    runtime: SandboxRuntimeConfig["effectiveMode"];
+    engine: SandboxEngine;
+    /** Human-readable isolation description for logs/errors. */
+    isolationLabel: string;
+}
+export declare class SandboxRequiredError extends Error {
+    constructor(message: string);
+}
+/**
+ * Detect available container engine (cached).
+ */
+export declare function detectContainerEngine(): SandboxEngine;
+/** Test helper */
+export declare function clearSandboxRuntimeCache(): void;
+/**
+ * Resolve full runtime configuration for a project.
+ */
+export declare function resolveSandboxRuntimeConfig(projectRoot: string, timeoutMs?: number): SandboxRuntimeConfig;
+/**
+ * Build docker/podman argv for an isolated run.
+ * Project is mounted at /workspace; command runs with -w /workspace.
+ */
+export declare function buildContainerArgs(cfg: SandboxRuntimeConfig, command: string, args: string[]): string[];
+/**
+ * Run a command under the configured sandbox runtime.
+ */
+export declare function runInSandbox(req: RunInSandboxRequest): Promise<RunInSandboxResult>;
+/**
+ * Diagnostic snapshot for dashboard / CLI.
+ */
+export declare function getSandboxRuntimeStatus(projectRoot?: string): {
+    config: SandboxRuntimeConfig;
+    isolationLabel: string;
+    identity: ReturnType<typeof resolveSandboxIdentity>;
+};