qlogicagent 2.13.3 → 2.13.5

package/dist/skills/tools/shell/sandbox/sandbox-launcher.js

@@ -0,0 +1,59 @@
+import { buildSeatbeltProfile } from "./seatbelt-profile.js";
+import { buildLandlockArgv } from "./landlock-argv.js";
+import { deriveWritableRoots } from "./sandbox-scope.js";
+function passthrough(bin, args, reason) {
+    return { wrapped: false, bin, args, useSandbox: false, reason };
+}
+/**
+ * 纯决策:平台 + 模式 + 可用性 → 包裹或降级。
+ * 降级永不抛、永不拒执行(spec「降级安全」)。
+ */
+export function decideSandbox(input) {
+    const { platform, config, bin, args, writableRoots } = input;
+    if (config.mode === "full_access") {
+        return passthrough(bin, args, "full_access: sandbox off by design");
+    }
+    if (platform === "win32" || platform === "other") {
+        return passthrough(bin, args, `sandbox unsupported on ${platform}; degrade to prompt-only`);
+    }
+    if (platform === "darwin") {
+        if (!config.sandboxExecAvailable) {
+            return passthrough(bin, args, "sandbox-exec unavailable; degrade");
+        }
+        const profile = buildSeatbeltProfile(writableRoots, config.netPolicy);
+        return {
+            wrapped: true,
+            bin: "sandbox-exec",
+            args: ["-p", profile, "--", bin, ...args],
+            useSandbox: true,
+            sandboxTmpDir: config.tmpDir,
+            reason: "macOS Seatbelt: read-all, write-scoped",
+        };
+    }
+    // linux
+    if (!config.helperPath) {
+        return passthrough(bin, args, "landlock helper missing; degrade to prompt-only");
+    }
+    const full = buildLandlockArgv(config.helperPath, writableRoots, config.netPolicy, bin, args);
+    return {
+        wrapped: true,
+        bin: config.helperPath,
+        args: full.slice(1), // 去掉重复的 argv[0](=helperPath),spawn(bin,args) 等价完整 argv
+        useSandbox: true,
+        sandboxTmpDir: config.tmpDir,
+        reason: "Linux Landlock: read-all, write-scoped",
+    };
+}
+/** shell-exec 单次入口:派生 scope → 决策 → 返回 spawn 应用的 bin/args + useSandbox。 */
+export function applySandboxToSpawn(platform, config, bin, args) {
+    const d = decideSandbox({
+        platform,
+        config,
+        bin,
+        args,
+        writableRoots: deriveWritableRoots(config),
+    });
+    return d.wrapped
+        ? { bin: d.bin, args: d.args, useSandbox: true, sandboxTmpDir: d.sandboxTmpDir, reason: d.reason }
+        : { bin, args, useSandbox: false, reason: d.reason };
+}

package/dist/skills/tools/shell/sandbox/sandbox-scope.d.ts

@@ -0,0 +1,6 @@
+import type { SandboxConfig } from "./sandbox-types.js";
+/**
+ * 沙箱可写根集 = active workdir + 批准/持久 allow 目录 + 工具记账目录 + 沙箱临时目录。
+ * 读全放开,故无读根。resolve + 去重。
+ */
+export declare function deriveWritableRoots(config: SandboxConfig): string[];

package/dist/skills/tools/shell/sandbox/sandbox-scope.js

@@ -0,0 +1,17 @@
+import { resolve } from "node:path";
+/**
+ * 沙箱可写根集 = active workdir + 批准/持久 allow 目录 + 工具记账目录 + 沙箱临时目录。
+ * 读全放开,故无读根。resolve + 去重。
+ */
+export function deriveWritableRoots(config) {
+    const seen = new Set();
+    const add = (p) => {
+        if (p && p.trim())
+            seen.add(resolve(p));
+    };
+    add(config.workdir);
+    config.allowedDirs.forEach(add);
+    config.bookkeepingDirs.forEach(add);
+    add(config.tmpDir);
+    return [...seen];
+}

package/dist/skills/tools/shell/sandbox/sandbox-types.d.ts

@@ -0,0 +1,47 @@
+import type { PermissionMode } from "../../../../runtime/ports/permission-contracts.js";
+import type { SandboxPlatform } from "./platform.js";
+/** 网络出站策略:allow=放开;deny=禁非回环出站(细粒度留后)。 */
+export type NetPolicy = "allow" | "deny";
+/**
+ * Host 在每次 exec 前注入的沙箱上下文(权限单一真相的快照)。
+ * undefined 表示 host 不启用沙箱(由调用方决定)。
+ */
+export interface SandboxConfig {
+    mode: PermissionMode;
+    /** active workdir(pathService.getActiveWorkdir()),恒为可写根。 */
+    workdir: string;
+    /** 已批准/持久 allow 的目录(rule-engine.getAllowedWriteDirectories())。 */
+    allowedDirs: string[];
+    /** 工具记账可写目录(taskOutputDir + snapshot 目录),恒可写。 */
+    bookkeepingDirs: string[];
+    /** 沙箱内 cwd/snapshot 临时目录(可写;= sandboxTmpDir)。 */
+    tmpDir: string;
+    /** Linux landlock helper 路径(null=不可用→降级)。 */
+    helperPath: string | null;
+    /** sandbox-exec 是否可用(macOS;由 host 探测)。 */
+    sandboxExecAvailable: boolean;
+    netPolicy: NetPolicy;
+}
+/** decideSandbox 的输出:是否包裹 + 最终 spawn 的 bin/args。 */
+export interface SandboxDecision {
+    /** 是否实际包裹(false=降级,直接用原 bin/args)。 */
+    wrapped: boolean;
+    bin: string;
+    args: string[];
+    /** 传给 provider.buildExecCommand 的 useSandbox。 */
+    useSandbox: boolean;
+    /** 包裹时的可写临时目录(cwdFile 落点);未包裹=undefined。 */
+    sandboxTmpDir?: string;
+    /** 决策原因(日志/可观测;降级时写 warn)。 */
+    reason: string;
+}
+/** decideSandbox 的纯输入(平台/可用性显式传入以便跨平台单测)。 */
+export interface DecideSandboxInput {
+    platform: SandboxPlatform;
+    config: SandboxConfig;
+    /** 原始 spawn 目标。 */
+    bin: string;
+    args: string[];
+    /** 派生好的可写根(deriveWritableRoots 结果)。 */
+    writableRoots: string[];
+}

package/dist/skills/tools/shell/sandbox/sandbox-types.js

@@ -0,0 +1 @@
+export {};

package/dist/skills/tools/shell/sandbox/seatbelt-profile.d.ts

@@ -0,0 +1,6 @@
+import type { NetPolicy } from "./sandbox-types.js";
+/**
+ * 生成 macOS Seatbelt profile:读放开、写限 roots(+设备/tmp)、网络按策略。
+ * 路径保留(在真实路径上 allow/deny,无 remap)。
+ */
+export declare function buildSeatbeltProfile(writableRoots: string[], netPolicy: NetPolicy): string;

package/dist/skills/tools/shell/sandbox/seatbelt-profile.js

@@ -0,0 +1,28 @@
+function sb(path) {
+    return `"${path.replaceAll('"', '\\"')}"`;
+}
+/**
+ * 生成 macOS Seatbelt profile:读放开、写限 roots(+设备/tmp)、网络按策略。
+ * 路径保留(在真实路径上 allow/deny,无 remap)。
+ */
+export function buildSeatbeltProfile(writableRoots, netPolicy) {
+    const writeRules = writableRoots.map((r) => `  (subpath ${sb(r)})`).join("\n");
+    return [
+        "(version 1)",
+        "(deny default)",
+        "(allow process-fork)",
+        "(allow process-exec*)",
+        "(allow signal (target self))",
+        "(allow sysctl-read)",
+        "(allow mach-lookup)",
+        "(allow file-read*)", // 读放开(整机可读)
+        '(allow file-write-data (literal "/dev/null") (literal "/dev/dtracehelper"))',
+        '(allow file-write* (subpath "/dev/tty"))',
+        '(allow file-write* (subpath "/private/tmp") (subpath "/private/var/tmp"))',
+        writableRoots.length ? `(allow file-write*\n${writeRules})` : "",
+        netPolicy === "deny" ? "(deny network*)" : "(allow network*)",
+        "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/skills/tools/shell/shell-command.d.ts

@@ -0,0 +1,54 @@
+import type { ChildProcess } from "node:child_process";
+import { TaskOutput } from "./task-output.js";
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    /** Exit code. 137 = SIGKILL, 143 = SIGTERM, 145 = aborted. */
+    code: number;
+    /** Whether the process was interrupted (killed or timed out). */
+    interrupted: boolean;
+    /** Set when backgrounded. */
+    backgroundTaskId?: string;
+    /** Set when the user explicitly backgrounded. */
+    backgroundedByUser?: boolean;
+    /** Set when assistant mode auto-backgrounded. */
+    assistantAutoBackgrounded?: boolean;
+    /** Path to raw output file for large outputs. */
+    outputFilePath?: string;
+    /** Total output file size in bytes. */
+    outputFileSize?: number;
+    /** Error message when command failed before spawning. */
+    preSpawnError?: string;
+}
+export interface ShellCommand {
+    /** Move the process to background. Returns true if successful. */
+    background(taskId: string): boolean;
+    /** Promise resolving when the process exits. */
+    result: Promise<ExecResult>;
+    /** Kill the process immediately. */
+    kill(): void;
+    /** Current lifecycle status. */
+    status: "running" | "backgrounded" | "completed" | "killed";
+    /** Clean up stream resources and listeners. */
+    cleanup(): void;
+    /** Register timeout callback (for auto-backgrounding). */
+    onTimeout?: (callback: (backgroundFn: (taskId: string) => boolean) => void) => void;
+    /** Output container. */
+    taskOutput: TaskOutput;
+}
+/**
+ * Wrap a child process with lifecycle management.
+ * Ported from cc's wrapSpawn().
+ */
+export declare function wrapSpawn(childProcess: ChildProcess, abortSignal: AbortSignal, timeout: number, taskOutput: TaskOutput, shouldAutoBackground?: boolean, maxOutputBytes?: number): ShellCommand;
+/**
+ * Create a ShellCommand for commands that were aborted before execution.
+ */
+export declare function createAbortedCommand(backgroundTaskId?: string, opts?: {
+    stderr?: string;
+    code?: number;
+}): ShellCommand;
+/**
+ * Create a ShellCommand for commands that failed before spawn.
+ */
+export declare function createFailedCommand(preSpawnError: string): ShellCommand;

package/dist/skills/tools/shell/shell-command.js

@@ -0,0 +1,347 @@
+// ============================================================
+// ShellCommand — process lifecycle manager.
+// Ported from: claude-code-haha/src/utils/ShellCommand.ts
+//
+// Owns: timeout, abort, backgrounding, kill, output streaming.
+// cc uses tree-kill for SIGKILL; we use process.kill() on Windows
+// and tree-kill where available.
+// ============================================================
+var _a;
+import { TaskOutput } from "./task-output.js";
+import { generateTaskId } from "../../../runtime/infra/task-runtime.js";
+const SIGKILL_CODE = 137;
+const SIGTERM_CODE = 143;
+/** Size watchdog interval for background tasks. */
+const SIZE_WATCHDOG_INTERVAL_MS = 5_000;
+/** Max background output (5GB — mirrors cc). */
+const MAX_TASK_OUTPUT_BYTES = 5 * 1024 * 1024 * 1024;
+// ── StreamWrapper ─────────────────────────────────────────────
+/**
+ * Thin pipe from child process stream into TaskOutput.
+ * Ported from cc's StreamWrapper.
+ */
+class StreamWrapper {
+    #stream;
+    #taskOutput;
+    #isStderr;
+    #isCleanedUp = false;
+    constructor(stream, taskOutput, isStderr) {
+        this.#stream = stream;
+        this.#taskOutput = taskOutput;
+        this.#isStderr = isStderr;
+        stream.setEncoding("utf-8");
+        stream.on("data", this.#onData);
+    }
+    #onData = (data) => {
+        const str = typeof data === "string" ? data : data.toString();
+        if (this.#isStderr) {
+            this.#taskOutput.writeStderr(str);
+        }
+        else {
+            this.#taskOutput.writeStdout(str);
+        }
+    };
+    cleanup() {
+        if (this.#isCleanedUp)
+            return;
+        this.#isCleanedUp = true;
+        this.#stream.removeListener("data", this.#onData);
+        this.#stream = null;
+        this.#taskOutput = null;
+    }
+}
+// ── ShellCommandImpl ──────────────────────────────────────────
+/**
+ * Process lifecycle manager. Ported from cc's ShellCommandImpl.
+ *
+ * File mode (bash): stdout/stderr go to file fd, no JS involvement.
+ * Pipe mode (hooks): StreamWrappers funnel data to TaskOutput.
+ */
+class ShellCommandImpl {
+    #status = "running";
+    #backgroundTaskId;
+    #stdoutWrapper;
+    #stderrWrapper;
+    #childProcess;
+    #timeoutId = null;
+    #sizeWatchdog = null;
+    #killedForSize = false;
+    #maxOutputBytes;
+    #abortSignal;
+    #onTimeoutCallback;
+    #timeout;
+    #shouldAutoBackground;
+    #resultResolver = null;
+    #exitCodeResolver = null;
+    #boundAbortHandler = null;
+    taskOutput;
+    result;
+    onTimeout;
+    constructor(childProcess, abortSignal, timeout, taskOutput, shouldAutoBackground = false, maxOutputBytes = MAX_TASK_OUTPUT_BYTES) {
+        this.#childProcess = childProcess;
+        this.#abortSignal = abortSignal;
+        this.#timeout = timeout;
+        this.#shouldAutoBackground = shouldAutoBackground;
+        this.#maxOutputBytes = maxOutputBytes;
+        this.taskOutput = taskOutput;
+        // Pipe mode: wrap streams to funnel data into TaskOutput
+        this.#stderrWrapper = childProcess.stderr
+            ? new StreamWrapper(childProcess.stderr, taskOutput, true)
+            : null;
+        this.#stdoutWrapper = childProcess.stdout
+            ? new StreamWrapper(childProcess.stdout, taskOutput, false)
+            : null;
+        if (shouldAutoBackground) {
+            this.onTimeout = (callback) => {
+                this.#onTimeoutCallback = callback;
+            };
+        }
+        this.result = this.#createResultPromise();
+    }
+    get status() {
+        return this.#status;
+    }
+    // ── Timeout handling (ported from cc) ──────────────────────
+    static #handleTimeout(self) {
+        if (self.#shouldAutoBackground && self.#onTimeoutCallback) {
+            self.#onTimeoutCallback(self.background.bind(self));
+        }
+        else {
+            self.#doKill(SIGTERM_CODE);
+        }
+    }
+    // ── Abort handling ─────────────────────────────────────────
+    #abortHandler() {
+        // On 'interrupt' (user submitted new message), don't kill —
+        // let the caller background the process.
+        if (this.#abortSignal.reason === "interrupt")
+            return;
+        this.kill();
+    }
+    // ── Exit/error handling ────────────────────────────────────
+    #exitHandler(code, signal) {
+        const exitCode = code !== null && code !== undefined
+            ? code
+            : signal === "SIGTERM"
+                ? 144
+                : 1;
+        this.#resolveExitCode(exitCode);
+    }
+    #errorHandler() {
+        this.#resolveExitCode(1);
+    }
+    #resolveExitCode(code) {
+        if (this.#exitCodeResolver) {
+            this.#exitCodeResolver(code);
+            this.#exitCodeResolver = null;
+        }
+    }
+    // ── Listener management ────────────────────────────────────
+    #cleanupListeners() {
+        this.#clearSizeWatchdog();
+        if (this.#timeoutId) {
+            clearTimeout(this.#timeoutId);
+            this.#timeoutId = null;
+        }
+        if (this.#boundAbortHandler) {
+            this.#abortSignal.removeEventListener("abort", this.#boundAbortHandler);
+            this.#boundAbortHandler = null;
+        }
+    }
+    #clearSizeWatchdog() {
+        if (this.#sizeWatchdog) {
+            clearInterval(this.#sizeWatchdog);
+            this.#sizeWatchdog = null;
+        }
+    }
+    #startSizeWatchdog() {
+        this.#sizeWatchdog = setInterval(() => {
+            void import("node:fs/promises").then(({ stat }) => stat(this.taskOutput.path).then((s) => {
+                if (s.size > this.#maxOutputBytes &&
+                    this.#status === "backgrounded" &&
+                    this.#sizeWatchdog !== null) {
+                    this.#killedForSize = true;
+                    this.#clearSizeWatchdog();
+                    this.#doKill(SIGKILL_CODE);
+                }
+            }, () => {
+                // ENOENT before first write — skip this tick
+            }));
+        }, SIZE_WATCHDOG_INTERVAL_MS);
+        this.#sizeWatchdog.unref?.();
+    }
+    // ── Result promise ─────────────────────────────────────────
+    #createResultPromise() {
+        this.#boundAbortHandler = this.#abortHandler.bind(this);
+        this.#abortSignal.addEventListener("abort", this.#boundAbortHandler, {
+            once: true,
+        });
+        // Use 'exit' not 'close': 'close' waits for grandchild fds.
+        this.#childProcess.once("exit", this.#exitHandler.bind(this));
+        this.#childProcess.once("error", this.#errorHandler.bind(this));
+        this.#timeoutId = setTimeout(_a.#handleTimeout, this.#timeout, this);
+        const exitPromise = new Promise((resolve) => {
+            this.#exitCodeResolver = resolve;
+        });
+        return new Promise((resolve) => {
+            this.#resultResolver = resolve;
+            void exitPromise.then(this.#handleExit.bind(this));
+        });
+    }
+    async #handleExit(code) {
+        this.#cleanupListeners();
+        if (this.#status === "running" || this.#status === "backgrounded") {
+            this.#status = "completed";
+        }
+        const stdout = await this.taskOutput.getStdout();
+        const result = {
+            code,
+            stdout,
+            stderr: this.taskOutput.getStderr(),
+            interrupted: code === SIGKILL_CODE,
+            backgroundTaskId: this.#backgroundTaskId,
+        };
+        // Large output file handling
+        if (this.taskOutput.stdoutToFile && !this.#backgroundTaskId) {
+            if (this.taskOutput.outputFileRedundant) {
+                void this.taskOutput.deleteOutputFile();
+            }
+            else {
+                result.outputFilePath = this.taskOutput.path;
+                result.outputFileSize = this.taskOutput.outputFileSize;
+            }
+        }
+        if (this.#killedForSize) {
+            result.stderr = `Background command killed: output file exceeded ${MAX_TASK_OUTPUT_BYTES} bytes. ${result.stderr}`;
+        }
+        else if (code === SIGTERM_CODE) {
+            result.stderr = `Command timed out after ${this.#timeout}ms. ${result.stderr}`;
+        }
+        if (this.#resultResolver) {
+            this.#resultResolver(result);
+            this.#resultResolver = null;
+        }
+    }
+    // ── Kill / Background ──────────────────────────────────────
+    #doKill(code) {
+        this.#status = "killed";
+        const pid = this.#childProcess.pid;
+        if (pid) {
+            // Try tree-kill if available, fall back to process.kill
+            try {
+                // Use platform-appropriate kill
+                if (process.platform === "win32") {
+                    // Windows: taskkill /T kills process tree
+                    import("node:child_process").then(({ execSync }) => {
+                        try {
+                            execSync(`taskkill /PID ${pid} /T /F`, { stdio: "ignore" });
+                        }
+                        catch {
+                            // Process may already be dead
+                        }
+                    });
+                }
+                else {
+                    // Unix: kill the process group
+                    try {
+                        process.kill(-pid, "SIGKILL");
+                    }
+                    catch {
+                        try {
+                            process.kill(pid, "SIGKILL");
+                        }
+                        catch {
+                            // Process already dead
+                        }
+                    }
+                }
+            }
+            catch {
+                // Fallback
+                try {
+                    this.#childProcess.kill("SIGKILL");
+                }
+                catch {
+                    // Already dead
+                }
+            }
+        }
+        this.#resolveExitCode(code ?? SIGKILL_CODE);
+    }
+    kill() {
+        this.#doKill();
+    }
+    background(taskId) {
+        if (this.#status === "running") {
+            this.#backgroundTaskId = taskId;
+            this.#status = "backgrounded";
+            this.#cleanupListeners();
+            if (this.taskOutput.stdoutToFile) {
+                this.#startSizeWatchdog();
+            }
+            else {
+                this.taskOutput.spillToDisk();
+            }
+            return true;
+        }
+        return false;
+    }
+    cleanup() {
+        this.#stdoutWrapper?.cleanup();
+        this.#stderrWrapper?.cleanup();
+        this.taskOutput.clear();
+        this.#cleanupListeners();
+        this.#childProcess = null;
+        this.#abortSignal = null;
+        this.#onTimeoutCallback = undefined;
+    }
+}
+_a = ShellCommandImpl;
+// ── Factory functions ─────────────────────────────────────────
+/**
+ * Wrap a child process with lifecycle management.
+ * Ported from cc's wrapSpawn().
+ */
+export function wrapSpawn(childProcess, abortSignal, timeout, taskOutput, shouldAutoBackground = false, maxOutputBytes = MAX_TASK_OUTPUT_BYTES) {
+    return new ShellCommandImpl(childProcess, abortSignal, timeout, taskOutput, shouldAutoBackground, maxOutputBytes);
+}
+/**
+ * Create a ShellCommand for commands that were aborted before execution.
+ */
+export function createAbortedCommand(backgroundTaskId, opts) {
+    const taskOutput = new TaskOutput(generateTaskId("local_bash"), null);
+    return {
+        status: "killed",
+        result: Promise.resolve({
+            code: opts?.code ?? 145,
+            stdout: "",
+            stderr: opts?.stderr ?? "Command aborted before execution",
+            interrupted: true,
+            backgroundTaskId,
+        }),
+        taskOutput,
+        background: () => false,
+        kill: () => { },
+        cleanup: () => { },
+    };
+}
+/**
+ * Create a ShellCommand for commands that failed before spawn.
+ */
+export function createFailedCommand(preSpawnError) {
+    const taskOutput = new TaskOutput(generateTaskId("local_bash"), null);
+    return {
+        status: "completed",
+        result: Promise.resolve({
+            code: 1,
+            stdout: "",
+            stderr: preSpawnError,
+            interrupted: false,
+            preSpawnError,
+        }),
+        taskOutput,
+        background: () => false,
+        kill: () => { },
+        cleanup: () => { },
+    };
+}

package/dist/skills/tools/shell/shell-exec.d.ts

@@ -0,0 +1,38 @@
+import type { ShellProvider, ShellType } from "./shell-provider.js";
+import { type ShellCommand } from "./shell-command.js";
+import { type ProgressCallback } from "./task-output.js";
+import type { SandboxConfig } from "./sandbox/sandbox-types.js";
+export type { ExecResult } from "./shell-command.js";
+export declare function getCwd(): string;
+export declare function setCwd(path: string, relativeTo?: string): void;
+export declare function getOriginalCwd(): string;
+export declare function initCwd(cwd: string): void;
+export interface ExecOptions {
+    timeout?: number;
+    onProgress?: ProgressCallback;
+    /** When true, `cd` in the command does NOT update the session CWD. */
+    preventCwdChanges?: boolean;
+    shouldAutoBackground?: boolean;
+    /** When provided, stdout is piped and this callback fires per chunk. */
+    onStdout?: (data: string) => void;
+    /** Per-call CWD override. When set, spawn uses this instead of the session CWD. */
+    cwd?: string;
+    /** Sandbox context injected by the host; absent = no OS sandbox (degrade). */
+    sandbox?: SandboxConfig;
+}
+/**
+ * Set the shell provider for this session.
+ * Must be called once at startup by the host.
+ */
+export declare function setShellProvider(provider: ShellProvider): void;
+/**
+ * Get the current shell provider, or throw if not configured.
+ */
+export declare function getShellProvider(): ShellProvider;
+/**
+ * Execute a shell command using the configured provider.
+ * Creates a new child process for each invocation.
+ *
+ * Ported from cc's Shell.ts — the tool owns process lifecycle.
+ */
+export declare function exec(command: string, abortSignal: AbortSignal, shellType?: ShellType, options?: ExecOptions): Promise<ShellCommand>;