qlogicagent 2.13.4 → 2.13.5

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

@@ -0,0 +1,202 @@
+// ============================================================
+// Shell.exec() — command execution with direct spawn.
+// Ported from: claude-code-haha/src/utils/Shell.ts
+//
+// Flow: resolve provider → buildExecCommand → spawn → wrapSpawn
+// The tool owns the process lifecycle — no DI for exec.
+// ============================================================
+import { spawn } from "node:child_process";
+import { constants as fsConstants, readFileSync, unlinkSync } from "node:fs";
+import { mkdir, open, realpath } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { generateCommandId, getDefaultShellType } from "./shell-provider.js";
+import { wrapSpawn, createAbortedCommand, createFailedCommand, } from "./shell-command.js";
+import { TaskOutput, getTaskOutputDir, } from "./task-output.js";
+import { generateTaskId } from "../../../runtime/infra/task-runtime.js";
+import { subprocessEnv } from "./subprocess-env.js";
+import { applySandboxToSpawn } from "./sandbox/sandbox-launcher.js";
+import { currentPlatform } from "./sandbox/platform.js";
+const DEFAULT_TIMEOUT = 30 * 60 * 1000; // 30 minutes
+// ── CWD state (session-scoped) ────────────────────────────────
+let _cwd = process.cwd();
+let _originalCwd = process.cwd();
+export function getCwd() {
+    return _cwd;
+}
+export function setCwd(path, relativeTo) {
+    const resolved = isAbsolute(path)
+        ? path
+        : resolve(relativeTo || _cwd, path);
+    _cwd = resolved;
+}
+export function getOriginalCwd() {
+    return _originalCwd;
+}
+export function initCwd(cwd) {
+    _cwd = cwd;
+    _originalCwd = cwd;
+}
+// ── Shell config (memoized per session) ───────────────────────
+let _shellConfig = null;
+/**
+ * Set the shell provider for this session.
+ * Must be called once at startup by the host.
+ */
+export function setShellProvider(provider) {
+    _shellConfig = { provider };
+}
+/**
+ * Get the current shell provider, or throw if not configured.
+ */
+export function getShellProvider() {
+    if (!_shellConfig) {
+        throw new Error("Shell provider not configured. Call setShellProvider() at startup.");
+    }
+    return _shellConfig.provider;
+}
+// ── exec() — ported from cc's Shell.ts exec() ────────────────
+/**
+ * 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 async function exec(command, abortSignal, shellType, options) {
+    const { timeout, onProgress, preventCwdChanges, shouldAutoBackground, onStdout, cwd: cwdOverride, } = options ?? {};
+    const commandTimeout = timeout || DEFAULT_TIMEOUT;
+    const resolvedType = shellType ?? getDefaultShellType();
+    const provider = getShellProvider();
+    const id = generateCommandId();
+    // ── Sandbox decision (cut7c) ──────────────────────────────
+    // useSandbox/sandboxTmpDir are argv-independent, so decide them early:
+    // buildExecCommand must place the CWD temp file inside the sandbox-writable
+    // tmp dir. The actual bin/args wrap happens after getSpawnArgs (below).
+    const sandboxCfg = options?.sandbox;
+    const sandboxPre = sandboxCfg
+        ? applySandboxToSpawn(currentPlatform(), sandboxCfg, provider.shellPath, [])
+        : undefined;
+    const { commandString: builtCommand, cwdFilePath } = await provider.buildExecCommand(command, {
+        id,
+        useSandbox: sandboxPre?.useSandbox ?? false,
+        sandboxTmpDir: sandboxPre?.useSandbox ? sandboxPre.sandboxTmpDir : undefined,
+    });
+    let commandString = builtCommand;
+    let cwd = cwdOverride ?? getCwd();
+    // Recover if CWD no longer exists
+    try {
+        await realpath(cwd);
+    }
+    catch {
+        const fallback = getOriginalCwd();
+        try {
+            await realpath(fallback);
+            setCwd(fallback);
+            cwd = fallback;
+        }
+        catch {
+            return createFailedCommand(`Working directory "${cwd}" no longer exists.`);
+        }
+    }
+    // If already aborted, don't spawn
+    if (abortSignal.aborted) {
+        return createAbortedCommand();
+    }
+    let binShell = provider.shellPath;
+    let shellArgs = provider.getSpawnArgs(commandString);
+    if (sandboxCfg && sandboxPre?.useSandbox) {
+        const wrapped = applySandboxToSpawn(currentPlatform(), sandboxCfg, binShell, shellArgs);
+        binShell = wrapped.bin;
+        shellArgs = wrapped.args;
+        if (wrapped.sandboxTmpDir)
+            await mkdir(wrapped.sandboxTmpDir, { recursive: true });
+    }
+    const envOverrides = await provider.getEnvironmentOverrides(command);
+    // Pipe mode when onStdout is provided
+    const usePipeMode = !!onStdout;
+    const taskId = generateTaskId("local_bash");
+    const taskOutput = new TaskOutput(taskId, onProgress ?? null, !usePipeMode);
+    await mkdir(getTaskOutputDir(), { recursive: true });
+    // In file mode, both stdout and stderr go to the same file fd.
+    // SECURITY: O_NOFOLLOW prevents symlink-following attacks.
+    let outputHandle;
+    if (!usePipeMode) {
+        const O_NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0;
+        outputHandle = await open(taskOutput.path, process.platform === "win32"
+            ? "w"
+            : fsConstants.O_WRONLY |
+                fsConstants.O_CREAT |
+                fsConstants.O_APPEND |
+                O_NOFOLLOW);
+    }
+    try {
+        const childProcess = spawn(binShell, shellArgs, {
+            env: {
+                ...subprocessEnv(),
+                GIT_EDITOR: "true",
+                QLOGICAGENT: "1",
+                ...envOverrides,
+            },
+            cwd,
+            stdio: usePipeMode
+                ? ["pipe", "pipe", "pipe"]
+                : ["pipe", outputHandle?.fd, outputHandle?.fd],
+            detached: provider.detached,
+            windowsHide: true,
+        });
+        const shellCommand = wrapSpawn(childProcess, abortSignal, commandTimeout, taskOutput, shouldAutoBackground);
+        // Close our copy of the fd — child has its own dup.
+        if (outputHandle !== undefined) {
+            try {
+                await outputHandle.close();
+            }
+            catch {
+                // fd may already be closed
+            }
+        }
+        // Pipe mode: attach caller's stdout callback
+        if (childProcess.stdout && onStdout) {
+            childProcess.stdout.on("data", (chunk) => {
+                onStdout(typeof chunk === "string" ? chunk : chunk.toString());
+            });
+        }
+        // CWD tracking: read the temp file after command completes
+        if (cwdFilePath) {
+            void shellCommand.result.then((result) => {
+                if (result && !preventCwdChanges && !result.backgroundTaskId) {
+                    try {
+                        const newCwd = readFileSync(cwdFilePath, { encoding: "utf8" }).trim();
+                        if (newCwd && newCwd.normalize("NFC") !== cwd) {
+                            setCwd(newCwd, cwd);
+                        }
+                    }
+                    catch {
+                        // CWD file may not exist if command failed before pwd ran
+                    }
+                    // Cleanup temp file
+                    try {
+                        unlinkSync(cwdFilePath);
+                    }
+                    catch {
+                        // Already cleaned up
+                    }
+                }
+            });
+        }
+        return shellCommand;
+    }
+    catch (error) {
+        if (outputHandle !== undefined) {
+            try {
+                await outputHandle.close();
+            }
+            catch {
+                // Already closed
+            }
+        }
+        taskOutput.clear();
+        return createAbortedCommand(undefined, {
+            code: 126,
+            stderr: error instanceof Error ? error.message : String(error),
+        });
+    }
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Discriminated shell type identifier.
+ */
+export type ShellType = "bash" | "powershell";
+/**
+ * Options passed to `buildExecCommand`.
+ */
+export interface BuildCommandOpts {
+    /** Unique command invocation ID (for CWD temp-file naming). */
+    id: string;
+    /** If set, sandbox TMPDIR root. */
+    sandboxTmpDir?: string;
+    /** Whether sandbox mode is active. */
+    useSandbox: boolean;
+}
+/**
+ * Result of `buildExecCommand` — the final command string
+ * and the path where the shell will write its post-command CWD.
+ */
+export interface BuiltCommand {
+    /** Fully-wrapped command string ready for spawn. */
+    commandString: string;
+    /**
+     * Temp file path where the shell writes its post-command CWD.
+     * Used by the host to track `cd` across invocations.
+     * undefined if CWD tracking is not supported / not needed.
+     */
+    cwdFilePath?: string;
+}
+/**
+ * Runtime-agnostic shell provider.
+ *
+ * Hosts (Gateway / Desktop / Hub) create a provider once, then
+ * use it for every `exec()` call. The tool itself never
+ * `spawn()`s — the host does, using args from this provider.
+ */
+export interface ShellProvider {
+    /** Shell type discriminator. */
+    readonly type: ShellType;
+    /** Absolute path to the shell binary. */
+    readonly shellPath: string;
+    /**
+     * Whether `spawn()` should use `detached: true`.
+     * Bash: true (allows job control / cleanup).
+     * PowerShell: false (no POSIX process groups on Windows).
+     */
+    readonly detached: boolean;
+    /**
+     * Wrap a raw user command into a full shell command string.
+     * Handles:
+     *   - Environment snapshots / session env sourcing (bash)
+     *   - UTF-16LE EncodedCommand wrapping (PowerShell)
+     *   - CWD tracking (`pwd -P > file` / `Get-Location | Out-File`)
+     *   - stdin redirect for interactive commands (bash)
+     */
+    buildExecCommand(command: string, opts: BuildCommandOpts): Promise<BuiltCommand>;
+    /**
+     * Return the argv array for `child_process.spawn()`.
+     * E.g. bash → `['-c', commandString]`
+     *      PS   → `['-NoProfile', '-NonInteractive', '-Command', cmd]`
+     */
+    getSpawnArgs(commandString: string): string[];
+    /**
+     * Return extra environment variables to merge into spawn env.
+     * E.g. `{ SHELL: '/bin/bash', GIT_EDITOR: 'true', CLAUDECODE: '1' }`
+     */
+    getEnvironmentOverrides(command: string): Promise<Record<string, string>>;
+}
+/**
+ * Check if PowerShell tool mode should be enabled.
+ * Mirrors cc's `isPowerShellToolEnabled()`.
+ *
+ * On Windows: enabled when `QLOGICAGENT_USE_POWERSHELL` is truthy.
+ * On non-Windows: always false.
+ */
+export declare function isPowerShellToolEnabled(): boolean;
+/**
+ * Default shell type for the current platform.
+ */
+export declare function getDefaultShellType(): ShellType;
+/**
+ * Generate a short random hex ID for CWD temp file naming.
+ * Matches cc's `Math.floor(Math.random() * 0x10000).toString(16)`.
+ */
+export declare function generateCommandId(): string;

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

@@ -0,0 +1,38 @@
+// ============================================================
+// Shell Provider — abstraction for bash/powershell/zsh execution.
+// Ported from: claude-code-haha/src/utils/Shell.ts
+//              claude-code-haha/src/utils/shell/shellToolUtils.ts
+//
+// The ShellProvider interface isolates shell-specific concerns
+// (command wrapping, spawn args, env overrides, CWD tracking)
+// from the exec-tool skeleton.
+// ============================================================
+// ── Shell detection helpers ───────────────────────────────────
+/**
+ * Check if PowerShell tool mode should be enabled.
+ * Mirrors cc's `isPowerShellToolEnabled()`.
+ *
+ * On Windows: enabled when `QLOGICAGENT_USE_POWERSHELL` is truthy.
+ * On non-Windows: always false.
+ */
+export function isPowerShellToolEnabled() {
+    if (process.platform !== "win32")
+        return false;
+    const env = process.env.QLOGICAGENT_USE_POWERSHELL;
+    return env === "1" || env === "true";
+}
+/**
+ * Default shell type for the current platform.
+ */
+export function getDefaultShellType() {
+    return isPowerShellToolEnabled() ? "powershell" : "bash";
+}
+/**
+ * Generate a short random hex ID for CWD temp file naming.
+ * Matches cc's `Math.floor(Math.random() * 0x10000).toString(16)`.
+ */
+export function generateCommandId() {
+    return Math.floor(Math.random() * 0x10000)
+        .toString(16)
+        .padStart(4, "0");
+}

package/dist/skills/tools/shell/subprocess-env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Return a copy of `process.env` with sensitive variables removed.
+ * The allowlist includes vars known to be safe for child shells
+ * (PATH, HOME, LANG, TERM, etc.).
+ */
+export declare function subprocessEnv(): NodeJS.ProcessEnv;

package/dist/skills/tools/shell/subprocess-env.js

@@ -0,0 +1,87 @@
+// ============================================================
+// Subprocess environment sanitization.
+// Ported from: claude-code-haha/src/utils/subprocessEnv.ts
+//
+// Strips sensitive secrets from the environment before passing
+// to child processes spawned by the exec/shell tool. Prevents
+// users from exfiltrating API keys, tokens, and credentials
+// via `echo $SECRET` style attacks.
+// ============================================================
+/**
+ * Exact-match env var names to always strip from subprocess env.
+ */
+const SENSITIVE_EXACT = new Set([
+    // qlogicagent / openclaw auth
+    "API_KEY",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "DOUBAO_API_KEY",
+    "MINIMAX_API_KEY",
+    "GLM_API_KEY",
+    "KIMI_API_KEY",
+    "QWEN_API_KEY",
+    "MOONSHOT_API_KEY",
+    "ZHIPU_API_KEY",
+    "BAICHUAN_API_KEY",
+    "VOLCENGINE_API_KEY",
+    // Cloud provider creds
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "GOOGLE_APPLICATION_CREDENTIALS",
+    "AZURE_CLIENT_SECRET",
+    "AZURE_CLIENT_ID",
+    "AZURE_TENANT_ID",
+    // GH Actions / CI tokens
+    "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+    "ACTIONS_RUNTIME_TOKEN",
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+    "GITLAB_TOKEN",
+    "CI_JOB_TOKEN",
+    // Generic auth
+    "DATABASE_URL",
+    "REDIS_URL",
+    "REDIS_PASSWORD",
+]);
+/**
+ * Substrings: if an env var name (upper-cased) contains any of these,
+ * it is treated as sensitive and stripped.
+ */
+const SENSITIVE_SUBSTRINGS = [
+    "_SECRET",
+    "_TOKEN",
+    "_PASSWORD",
+    "_CREDENTIAL",
+    "_API_KEY",
+    "SECRET_",
+    "TOKEN_",
+    "PASSWORD_",
+    "CREDENTIAL_",
+    "_AUTH_",
+    "PRIVATE_KEY",
+];
+/**
+ * Return a copy of `process.env` with sensitive variables removed.
+ * The allowlist includes vars known to be safe for child shells
+ * (PATH, HOME, LANG, TERM, etc.).
+ */
+export function subprocessEnv() {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (isSensitive(key)) {
+            delete env[key];
+        }
+    }
+    return env;
+}
+function isSensitive(name) {
+    if (SENSITIVE_EXACT.has(name))
+        return true;
+    const upper = name.toUpperCase();
+    for (const sub of SENSITIVE_SUBSTRINGS) {
+        if (upper.includes(sub))
+            return true;
+    }
+    return false;
+}

package/dist/skills/tools/shell/task-output.d.ts

@@ -0,0 +1,44 @@
+/** Progress callback — matches cc's signature. */
+export type ProgressCallback = (lastLines: string, allLines: string, totalLines: number, totalBytes: number, isIncomplete: boolean) => void;
+/** Max output file on disk (background tasks). */
+export declare const MAX_TASK_OUTPUT_BYTES: number;
+export declare const MAX_TASK_OUTPUT_BYTES_DISPLAY = "5GB";
+/** Lazily generate session-scoped task output directory. */
+export declare function getTaskOutputDir(): string;
+/** Set the task output directory (for embedding hosts to override). */
+export declare function setTaskOutputDir(dir: string): void;
+export declare function getTaskOutputPath(taskId: string): string;
+/**
+ * Single source of truth for a shell command's output.
+ * Ported from cc's TaskOutput.
+ *
+ * For bash commands (file mode): both stdout/stderr go to file fd.
+ * For hooks (pipe mode): data flows through writeStdout/writeStderr.
+ */
+export declare class TaskOutput {
+    #private;
+    readonly taskId: string;
+    readonly path: string;
+    readonly stdoutToFile: boolean;
+    constructor(taskId: string, onProgress: ProgressCallback | null, stdoutToFile?: boolean, maxMemory?: number);
+    /** Write stdout data (pipe mode). */
+    writeStdout(data: string): void;
+    /** Write stderr data (pipe mode). */
+    writeStderr(data: string): void;
+    /** Get captured stdout. For file mode, reads from disk. */
+    getStdout(): Promise<string>;
+    /** Get captured stderr. In file mode stderr is interleaved with stdout. */
+    getStderr(): string;
+    get outputFileSize(): number;
+    /**
+     * Whether the output file content is fully contained in getStdout().
+     * If true, the file can be deleted.
+     */
+    get outputFileRedundant(): boolean;
+    /** Write in-memory buffer to disk file. */
+    spillToDisk(): void;
+    /** Delete the output file on disk. */
+    deleteOutputFile(): Promise<void>;
+    /** Clean up all resources. */
+    clear(): void;
+}

package/dist/skills/tools/shell/task-output.js

@@ -0,0 +1,137 @@
+// ============================================================
+// TaskOutput — single source of truth for a command's output.
+// Ported from: claude-code-haha/src/utils/task/TaskOutput.ts
+//
+// Modes:
+//   File mode (bash): stdout/stderr via file fd, progress via polling
+//   Pipe mode (hooks): data flows through writeStdout/writeStderr
+// ============================================================
+import { mkdir, readFile, writeFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+/** Max output that can be held in memory before spilling to disk. */
+const DEFAULT_MAX_MEMORY = 8 * 1024 * 1024; // 8MB
+/** Max output file on disk (background tasks). */
+export const MAX_TASK_OUTPUT_BYTES = 5 * 1024 * 1024 * 1024; // 5GB
+export const MAX_TASK_OUTPUT_BYTES_DISPLAY = "5GB";
+let _taskOutputDir;
+/** Lazily generate session-scoped task output directory. */
+export function getTaskOutputDir() {
+    if (!_taskOutputDir) {
+        const sessionId = Math.random().toString(36).slice(2, 10);
+        _taskOutputDir = join(tmpdir(), "qla-tasks", sessionId);
+    }
+    return _taskOutputDir;
+}
+/** Set the task output directory (for embedding hosts to override). */
+export function setTaskOutputDir(dir) {
+    _taskOutputDir = dir;
+}
+export function getTaskOutputPath(taskId) {
+    return join(getTaskOutputDir(), `${taskId}.output`);
+}
+/**
+ * Single source of truth for a shell command's output.
+ * Ported from cc's TaskOutput.
+ *
+ * For bash commands (file mode): both stdout/stderr go to file fd.
+ * For hooks (pipe mode): data flows through writeStdout/writeStderr.
+ */
+export class TaskOutput {
+    taskId;
+    path;
+    stdoutToFile;
+    #stdoutBuffer = "";
+    #stderrBuffer = "";
+    #totalLines = 0;
+    #totalBytes = 0;
+    #maxMemory;
+    #onProgress;
+    #outputFileSize = 0;
+    #cleared = false;
+    constructor(taskId, onProgress, stdoutToFile = false, maxMemory = DEFAULT_MAX_MEMORY) {
+        this.taskId = taskId;
+        this.path = getTaskOutputPath(taskId);
+        this.stdoutToFile = stdoutToFile;
+        this.#maxMemory = maxMemory;
+        this.#onProgress = onProgress;
+    }
+    /** Write stdout data (pipe mode). */
+    writeStdout(data) {
+        this.#stdoutBuffer += data;
+        this.#totalBytes += data.length;
+        this.#totalLines += countNewlines(data);
+        this.#checkSpill();
+    }
+    /** Write stderr data (pipe mode). */
+    writeStderr(data) {
+        this.#stderrBuffer += data;
+    }
+    /** Get captured stdout. For file mode, reads from disk. */
+    async getStdout() {
+        if (this.stdoutToFile) {
+            try {
+                const content = await readFile(this.path, "utf-8");
+                this.#outputFileSize = Buffer.byteLength(content);
+                return content;
+            }
+            catch {
+                return "";
+            }
+        }
+        return this.#stdoutBuffer;
+    }
+    /** Get captured stderr. In file mode stderr is interleaved with stdout. */
+    getStderr() {
+        return this.#stderrBuffer;
+    }
+    get outputFileSize() {
+        return this.#outputFileSize;
+    }
+    /**
+     * Whether the output file content is fully contained in getStdout().
+     * If true, the file can be deleted.
+     */
+    get outputFileRedundant() {
+        return this.#outputFileSize <= this.#maxMemory;
+    }
+    /** Spill in-memory buffer to disk when too large. */
+    #checkSpill() {
+        if (this.#stdoutBuffer.length > this.#maxMemory) {
+            this.spillToDisk();
+        }
+    }
+    /** Write in-memory buffer to disk file. */
+    spillToDisk() {
+        if (this.#stdoutBuffer.length === 0)
+            return;
+        void mkdir(getTaskOutputDir(), { recursive: true }).then(() => writeFile(this.path, this.#stdoutBuffer).catch(() => { }));
+    }
+    /** Delete the output file on disk. */
+    async deleteOutputFile() {
+        try {
+            await unlink(this.path);
+        }
+        catch {
+            // File may not exist
+        }
+    }
+    /** Clean up all resources. */
+    clear() {
+        if (this.#cleared)
+            return;
+        this.#cleared = true;
+        this.#stdoutBuffer = "";
+        this.#stderrBuffer = "";
+        this.#onProgress = null;
+        void this.deleteOutputFile();
+    }
+}
+function countNewlines(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (s.charCodeAt(i) === 10)
+            n++;
+    }
+    return n;
+}