qlogicagent 2.13.3 → 2.13.5

package/dist/skills/tools/edit-tool.js

@@ -0,0 +1,72 @@
+// ============================================================
+// File Edit Tool — surgical text replacement in files.
+// Category: coding
+// ============================================================
+export const EDIT_TOOL_NAME = "edit";
+export const EDIT_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "Path to the file to edit (relative or absolute).",
+        },
+        oldText: {
+            type: "string",
+            description: "Exact text to find and replace (must match exactly, including whitespace).",
+        },
+        newText: {
+            type: "string",
+            description: "New text to replace the old text with.",
+        },
+    },
+    required: ["path", "oldText", "newText"],
+};
+export function createEditTool(deps) {
+    return {
+        name: EDIT_TOOL_NAME,
+        label: "Edit File",
+        description: "Edit a file by replacing exact text. The oldText must match exactly (including whitespace). " +
+            "Use this for precise, surgical edits. For multiple edits, call this tool multiple times. " +
+            "ALWAYS use this tool to modify existing files — never use sed/awk/shell commands for text replacement. " +
+            "Preferred over shell redirection for creating/modifying files.",
+        parameters: EDIT_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            const resolved = deps.resolvePath(params.path);
+            // Concurrent modification check
+            if (deps.checkConcurrentModification) {
+                const conflict = deps.checkConcurrentModification(resolved);
+                if (conflict) {
+                    return {
+                        content: [{ type: "text", text: `Concurrent modification detected: ${conflict}. Re-read the file first.` }],
+                        details: { type: "edit", path: resolved, success: false, reason: "concurrent_modification" },
+                    };
+                }
+            }
+            const content = await deps.readFile(resolved);
+            const index = content.indexOf(params.oldText);
+            if (index === -1) {
+                return {
+                    content: [{ type: "text", text: `Error: oldText not found in ${resolved}. Ensure it matches exactly.` }],
+                    details: { type: "edit", path: resolved, success: false, reason: "not_found" },
+                };
+            }
+            // Check for multiple matches
+            const secondIndex = content.indexOf(params.oldText, index + 1);
+            if (secondIndex !== -1) {
+                return {
+                    content: [{ type: "text", text: `Error: oldText matches multiple locations in ${resolved}. Include more context to make the match unique.` }],
+                    details: { type: "edit", path: resolved, success: false, reason: "ambiguous" },
+                };
+            }
+            const newContent = content.slice(0, index) + params.newText + content.slice(index + params.oldText.length);
+            await deps.writeFile(resolved, newContent);
+            // Compute first changed line
+            const preLines = content.slice(0, index).split("\n");
+            const firstChangedLine = preLines.length;
+            return {
+                content: [{ type: "text", text: `Edited ${resolved} (line ${firstChangedLine})` }],
+                details: { type: "edit", path: resolved, success: true, firstChangedLine },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,117 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { BashTaskHandle } from "../../runtime/infra/background-tasks.js";
+import type { CommandClassification } from "./shell/command-classification.js";
+import type { SandboxConfig } from "./shell/sandbox/sandbox-types.js";
+export declare const EXEC_TOOL_NAME: "exec";
+export interface ExecToolParams {
+    command: string;
+    description?: string;
+    workdir?: string;
+    timeout?: number;
+    /** Explicit background request (cc: run_in_background). */
+    background?: boolean;
+}
+export declare const EXEC_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly command: {
+            readonly type: "string";
+            readonly description: "Shell command to execute in PowerShell." | "Shell command to execute in bash. Use Unix-style commands (ls, cat, mkdir -p, etc.).";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly workdir: {
+            readonly type: "string";
+            readonly description: "Working directory for the command.";
+        };
+        readonly timeout: {
+            readonly type: "number";
+            readonly description: string;
+        };
+        readonly background: {
+            readonly type: "boolean";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["command"];
+};
+export interface ExecToolOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    interrupted: boolean;
+    rawOutputPath?: string;
+    backgroundTaskId?: string;
+    assistantAutoBackgrounded?: boolean;
+    returnCodeInterpretation?: string;
+    noOutputExpected?: boolean;
+    persistedOutputPath?: string;
+    persistedOutputSize?: number;
+    classification?: CommandClassification;
+}
+export interface ExecProgress {
+    type: "exec_progress";
+    output: string;
+    fullOutput: string;
+    elapsedTimeSeconds: number;
+    totalLines: number;
+    totalBytes: number;
+    taskId?: string;
+}
+/**
+ * Minimal host dependency — ONLY for permission checking.
+ * The tool owns everything else (spawn, lifecycle, output).
+ *
+ * This replaces the old ExecToolDeps which required the host to
+ * implement the entire exec() pipeline. Now the tool owns the
+ * process directly (cc architecture).
+ */
+export interface ExecToolHost {
+    /**
+     * Validate a command before execution.
+     * Returns null/undefined if allowed, or an error message if blocked.
+     */
+    validateCommand?(command: string): Promise<string | null | undefined>;
+    /**
+     * Resolve the OS-sandbox context for this exec (snapshot of the permission
+     * single-source: mode + active workdir + approved dirs + helper availability).
+     * Returns undefined to disable the OS sandbox (degrade to prompt-only).
+     */
+    resolveSandbox?(): SandboxConfig | undefined;
+    /**
+     * Interpret a non-zero exit code.
+     * E.g. 127 → "command not found", 137 → "killed by SIGKILL".
+     */
+    interpretExitCode?(exitCode: number, stderr: string): string | undefined;
+    /**
+     * Called during foreground execution with incremental progress.
+     * The host can forward these to the UI for real-time output display.
+     */
+    onProgress?(progress: ExecProgress): void;
+    /**
+     * Register a backgrounded command in the host's unified task registry
+     * (lifecycle tracking + output queries + cancellation).
+     * Returns false when the host has no registry — background mode is then refused.
+     */
+    registerBackgroundTask?(info: {
+        command: string;
+        cwd: string;
+        description?: string;
+        pid?: number;
+        handle: BashTaskHandle;
+    }): boolean;
+}
+/**
+ * Auto-background trigger threshold (assistant mode).
+ * cc: ASSISTANT_BLOCKING_BUDGET_MS = 15_000
+ */
+export declare const ASSISTANT_BLOCKING_BUDGET_MS = 15000;
+/**
+ * Create the exec tool with direct process ownership (cc architecture).
+ *
+ * @param host Minimal host interface — only permission checking.
+ *             Pass `{}` for unrestricted mode (tests only).
+ */
+export declare function createExecTool(host?: ExecToolHost): PortableTool<ExecToolParams>;

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

@@ -0,0 +1,354 @@
+// ============================================================
+// Exec Tool — shell command execution with direct process ownership.
+// Ported from: claude-code-haha/src/tools/BashTool/BashTool.tsx
+//
+// Architecture (aligned with cc):
+//   exec-tool.execute()
+//     → runShellCommand()  [AsyncGenerator, yields progress]
+//       → Shell.exec()     [build command, spawn, return ShellCommand]
+//         → ShellCommandImpl  [owns lifecycle: timeout/abort/background]
+//
+// The tool OWNS the process. No DI for exec — only permission
+// checking is delegated to the host via ExecToolHost.
+// ============================================================
+import { isAbsolute, resolve } from "node:path";
+import { classifyCommand } from "./shell/command-classification.js";
+import { interpretCommandResult } from "./shell/command-semantics.js";
+import { detectBlockedSleepPattern } from "./shell/exec-permissions.js";
+import { exec, getCwd } from "./shell/shell-exec.js";
+import { isPowerShellToolEnabled } from "./shell/shell-provider.js";
+export const EXEC_TOOL_NAME = "exec";
+export const EXEC_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        command: {
+            type: "string",
+            description: isPowerShellToolEnabled()
+                ? "Shell command to execute in PowerShell."
+                : "Shell command to execute in bash. Use Unix-style commands (ls, cat, mkdir -p, etc.).",
+        },
+        description: {
+            type: "string",
+            description: "Clear, concise description of what this command does (e.g. \"Install dependencies\", " +
+                "\"Run unit tests\"). Used for UI display and permission logging. " +
+                "For simple commands keep it 5-10 words; " +
+                "for complex piped/flagged commands add enough context to clarify intent.",
+        },
+        workdir: {
+            type: "string",
+            description: "Working directory for the command.",
+        },
+        timeout: {
+            type: "number",
+            description: "Timeout in milliseconds (default: 120000). Only applies to foreground commands. " +
+                "Max allowed: 600000 (10 min).",
+        },
+        background: {
+            type: "boolean",
+            description: "If true, start the command in the background and return immediately " +
+                "with a task id. Check live output with task(action=\"output\", taskId=...); " +
+                "stop it with task(action=\"cancel\", taskId=...). " +
+                "Good for dev servers, watchers, long builds. Default: false.",
+        },
+    },
+    required: ["command"],
+};
+// ── Constants (aligned with cc) ───────────────────────────────
+/** Default foreground timeout in ms. cc uses 120_000. */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Max timeout (10 min). cc caps via getMaxTimeoutMs(). */
+const MAX_TIMEOUT_MS = 600_000;
+/**
+ * Max output chars before truncation + persistence.
+ * cc uses 30_000. We kept 30_000 for parity.
+ */
+const MAX_OUTPUT_CHARS = 30_000;
+/**
+ * Auto-background trigger threshold (assistant mode).
+ * cc: ASSISTANT_BLOCKING_BUDGET_MS = 15_000
+ */
+export const ASSISTANT_BLOCKING_BUDGET_MS = 15_000;
+function truncateOutput(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const half = Math.floor(limit / 2) - 50;
+    return `${text.slice(0, half)}\n\n... [truncated ${text.length - limit} chars] ...\n\n${text.slice(-half)}`;
+}
+/**
+ * Clamp + validate timeout parameter.
+ * cc does `Math.min(timeout, getMaxTimeoutMs())`.
+ */
+function resolveTimeout(raw) {
+    if (raw == null || raw <= 0)
+        return DEFAULT_TIMEOUT_MS;
+    return Math.min(raw, MAX_TIMEOUT_MS);
+}
+// ── AsyncGenerator — ported from cc's runShellCommand() ───────
+/**
+ * Execute a shell command and yield progress updates.
+ * Ported from cc's BashTool.runShellCommand().
+ *
+ * The caller iterates with `for await` to receive progress:
+ *   for await (const progress of runShellCommand(...)) { ... }
+ *   // generator returns ExecResult when done
+ */
+async function* runShellCommand(opts) {
+    const { command, abortController, timeout, shouldAutoBackground, cwd: cwdOverride, sandbox } = opts;
+    let fullOutput = "";
+    let lastTotalLines = 0;
+    let lastTotalBytes = 0;
+    const startTime = Date.now();
+    // Progress signal: wakes the generator when new output arrives
+    let resolveProgress = null;
+    function createProgressSignal() {
+        return new Promise((resolve) => {
+            resolveProgress = () => resolve(null);
+        });
+    }
+    const shellCommand = await exec(command, abortController.signal, undefined, // default shell type
+    {
+        timeout,
+        onProgress(_lastLines, allLines, totalLines, totalBytes, _isIncomplete) {
+            fullOutput = allLines;
+            lastTotalLines = totalLines;
+            lastTotalBytes = totalBytes;
+            if (resolveProgress) {
+                resolveProgress();
+                resolveProgress = null;
+            }
+        },
+        shouldAutoBackground,
+        cwd: cwdOverride,
+        sandbox,
+    });
+    // Auto-background on timeout — single id per process (the TaskOutput id)
+    if (shellCommand.onTimeout && shouldAutoBackground) {
+        shellCommand.onTimeout((backgroundFn) => {
+            const taskId = shellCommand.taskOutput.taskId;
+            if (backgroundFn(taskId)) {
+                opts.onAutoBackground?.(shellCommand, taskId);
+            }
+        });
+    }
+    // Yield progress while running
+    while (shellCommand.status === "running") {
+        const progressOrResult = await Promise.race([
+            createProgressSignal(),
+            shellCommand.result,
+        ]);
+        if (progressOrResult !== null)
+            break; // result resolved
+        yield {
+            type: "exec_progress",
+            output: fullOutput.slice(-4096),
+            fullOutput,
+            elapsedTimeSeconds: (Date.now() - startTime) / 1000,
+            totalLines: lastTotalLines,
+            totalBytes: lastTotalBytes,
+        };
+    }
+    const result = await shellCommand.result;
+    shellCommand.cleanup();
+    return result;
+}
+// ── Tool factory ──────────────────────────────────────────────
+/**
+ * Create the exec tool with direct process ownership (cc architecture).
+ *
+ * @param host Minimal host interface — only permission checking.
+ *             Pass `{}` for unrestricted mode (tests only).
+ */
+export function createExecTool(host = {}) {
+    return {
+        name: EXEC_TOOL_NAME,
+        label: "Execute Command",
+        description: "Execute a shell command. Supports foreground (blocking, returns output) " +
+            "and background (non-blocking, returns task ID) modes. " +
+            (isPowerShellToolEnabled() ? "Uses PowerShell. " : "Uses bash. ") +
+            "Commands are classified for safety: search/read commands may run " +
+            "in parallel; silent commands (mv, cp, rm) show 'Done' instead of " +
+            "empty output. Output is truncated and persisted if too long.\n" +
+            "IMPORTANT: Do NOT use this tool for file operations when dedicated tools exist. " +
+            "Use the 'write' tool instead of echo/cat/heredoc for creating files. " +
+            "Use the 'edit' tool instead of sed/awk for modifying files. " +
+            "Use the 'read' tool instead of cat/head/tail for reading files. " +
+            "Reserve this tool exclusively for system commands, builds, tests, " +
+            "and terminal operations that require shell execution. " +
+            "For creating or editing files, prefer the write/edit tools over shell redirection.",
+        searchHint: "execute shell commands",
+        parameters: EXEC_TOOL_SCHEMA,
+        maxResultSizeChars: MAX_OUTPUT_CHARS,
+        execute: async (_toolCallId, params) => {
+            // ── Classify command ────────────────────────────────
+            const classification = classifyCommand(params.command);
+            // ── Block sleep/infinite-loop patterns ──────────────
+            if (!params.background) {
+                const sleepBlock = detectBlockedSleepPattern(params.command);
+                if (sleepBlock) {
+                    return {
+                        content: [{ type: "text", text: `Command blocked: ${sleepBlock}` }],
+                        details: { type: "exec", error: "blocked_sleep_pattern", classification },
+                    };
+                }
+            }
+            // ── Permission check (only DI point) ────────────────
+            if (host.validateCommand) {
+                const blocked = await host.validateCommand(params.command);
+                if (blocked) {
+                    return {
+                        content: [{ type: "text", text: `Command blocked: ${blocked}` }],
+                        details: { type: "exec", error: "blocked_by_guard", reason: blocked, classification },
+                    };
+                }
+            }
+            // ── Sandbox context (cut7c): snapshot of permission single-source ──
+            const sandbox = host.resolveSandbox?.();
+            const abortController = new AbortController();
+            const timeoutMs = resolveTimeout(params.timeout);
+            // Resolve per-call CWD override (CC: BashTool uses getCwd())
+            const execCwd = params.workdir
+                ? (isAbsolute(params.workdir) ? params.workdir : resolve(getCwd(), params.workdir))
+                : undefined;
+            // ── Background mode ─────────────────────────────────
+            if (params.background) {
+                if (!host.registerBackgroundTask) {
+                    return {
+                        content: [{ type: "text", text: "Error: background execution is not available in this host (no task registry). Run the command in the foreground instead." }],
+                        details: { type: "exec", error: "background_unavailable", classification },
+                    };
+                }
+                const shellCommand = await exec(params.command, abortController.signal, undefined, { shouldAutoBackground: false, cwd: execCwd, sandbox });
+                // Single id per process: reuse the TaskOutput id created at spawn time.
+                const taskId = shellCommand.taskOutput.taskId;
+                const backgrounded = shellCommand.background(taskId);
+                if (backgrounded) {
+                    const registered = host.registerBackgroundTask({
+                        command: params.command,
+                        cwd: execCwd ?? getCwd(),
+                        description: params.description,
+                        handle: shellCommand,
+                    });
+                    if (!registered) {
+                        shellCommand.kill();
+                        return {
+                            content: [{ type: "text", text: "Error: background execution is not available in this host (no task registry). The process was stopped. Run the command in the foreground instead." }],
+                            details: { type: "exec", error: "background_unavailable", classification },
+                        };
+                    }
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Background task started (id: ${taskId}).\n` +
+                                    `Check output with task(action="output", taskId="${taskId}"); stop with task(action="cancel", taskId="${taskId}").`,
+                            }],
+                        details: {
+                            type: "exec_background",
+                            backgroundTaskId: taskId,
+                            description: params.description,
+                            classification,
+                        },
+                    };
+                }
+                // backgrounding failed — fall through to foreground
+            }
+            // ── Foreground: run via AsyncGenerator ──────────────
+            const generator = runShellCommand({
+                command: params.command,
+                abortController,
+                timeout: timeoutMs,
+                shouldAutoBackground: !!host.registerBackgroundTask,
+                cwd: execCwd,
+                sandbox,
+                onAutoBackground: (handle) => {
+                    host.registerBackgroundTask?.({
+                        command: params.command,
+                        cwd: execCwd ?? getCwd(),
+                        description: params.description,
+                        handle,
+                    });
+                },
+            });
+            // Consume generator — collect progress, get final result
+            let generatorResult;
+            do {
+                generatorResult = await generator.next();
+                if (!generatorResult.done && host.onProgress) {
+                    host.onProgress(generatorResult.value);
+                }
+            } while (!generatorResult.done);
+            const result = generatorResult.value;
+            // ── Build output ────────────────────────────────────
+            const parts = [];
+            // Auto-backgrounded
+            if (result.backgroundTaskId) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Command auto-backgrounded after timeout (task: ${result.backgroundTaskId}).\n` +
+                                `Check output with task(action="output", taskId="${result.backgroundTaskId}").`,
+                        }],
+                    details: {
+                        type: "exec_background",
+                        backgroundTaskId: result.backgroundTaskId,
+                        assistantAutoBackgrounded: result.assistantAutoBackgrounded,
+                        classification,
+                    },
+                };
+            }
+            // Large output file
+            if (result.outputFilePath) {
+                parts.push(truncateOutput(result.stdout, MAX_OUTPUT_CHARS));
+                parts.push(`[full output: ${result.outputFilePath} (${result.outputFileSize} bytes)]`);
+            }
+            else if (result.stdout) {
+                parts.push(truncateOutput(result.stdout, MAX_OUTPUT_CHARS));
+            }
+            if (result.stderr) {
+                parts.push(`[stderr]\n${truncateOutput(result.stderr, Math.floor(MAX_OUTPUT_CHARS / 4))}`);
+            }
+            if (result.interrupted) {
+                parts.push(`[interrupted — exit code ${result.code}]`);
+            }
+            // Command semantics: interpret non-zero exit codes for known commands
+            // (e.g. grep exit 1 = "No matches found", not an error)
+            const commandSemantic = result.code !== 0
+                ? interpretCommandResult(params.command, result.code, result.stdout, result.stderr)
+                : undefined;
+            if (commandSemantic && !commandSemantic.isError && commandSemantic.message) {
+                // Non-error exit code — add semantic note instead of generic error marker
+                parts.push(`[exit ${result.code}: ${commandSemantic.message}]`);
+            }
+            // Exit code interpretation (host-level, for signals etc.)
+            let returnCodeInterpretation;
+            if (result.code !== 0 && host.interpretExitCode && (!commandSemantic || commandSemantic.isError)) {
+                returnCodeInterpretation = host.interpretExitCode(result.code, result.stderr);
+                if (returnCodeInterpretation) {
+                    parts.push(`[exit ${result.code}: ${returnCodeInterpretation}]`);
+                }
+            }
+            // Silent command → show "Done"
+            if (parts.length === 0) {
+                parts.push(classification.isSilent && result.code === 0
+                    ? "Done"
+                    : `(exit code ${result.code}, no output)`);
+            }
+            return {
+                content: [{ type: "text", text: parts.join("\n") }],
+                details: {
+                    type: "exec",
+                    exitCode: result.code,
+                    interrupted: result.interrupted,
+                    stdout: truncateOutput(result.stdout, 8_000),
+                    stderr: truncateOutput(result.stderr, 4_000),
+                    description: params.description,
+                    returnCodeInterpretation: returnCodeInterpretation ?? commandSemantic?.message,
+                    noOutputExpected: classification.isSilent,
+                    outputFilePath: result.outputFilePath,
+                    // Semantic non-error: mark result as ok despite non-zero exit code
+                    semanticNonError: commandSemantic ? !commandSemantic.isError : undefined,
+                    classification,
+                },
+            };
+        },
+    };
+}

package/dist/skills/tools/file-management-tool.d.ts

@@ -0,0 +1,90 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const FILE_UPLOAD_TOOL_NAME: "file_upload";
+export interface FileUploadToolParams {
+    file_path: string;
+    purpose?: string;
+}
+export declare const FILE_UPLOAD_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_path: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly purpose: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["file_path"];
+};
+export interface FileUploadResult {
+    fileId: string;
+    url?: string;
+    filename: string;
+    bytes: number;
+    provider: string;
+}
+export interface FileUploadToolDeps {
+    uploadFile(params: {
+        filePath: string;
+        purpose?: string;
+    }): Promise<FileUploadResult>;
+}
+export declare function createFileUploadTool(deps: FileUploadToolDeps): PortableTool<FileUploadToolParams>;
+export declare const FILE_QUERY_TOOL_NAME: "file_query";
+export interface FileQueryToolParams {
+    file_id?: string;
+    limit?: number;
+}
+export declare const FILE_QUERY_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_id: {
+            readonly type: "string";
+            readonly description: "Query a specific file by ID. If omitted, lists recent uploaded files.";
+        };
+        readonly limit: {
+            readonly type: "number";
+            readonly description: "Max number of files to list when file_id is omitted. Default: 10, max: 100.";
+        };
+    };
+    readonly required: readonly [];
+};
+export interface FileInfo {
+    id: string;
+    filename: string;
+    bytes: number;
+    status: string;
+    createdAt?: string;
+    url?: string;
+}
+export interface FileQueryToolDeps {
+    queryFile(params: {
+        fileId: string;
+    }): Promise<FileInfo>;
+    listFiles(params: {
+        limit?: number;
+    }): Promise<FileInfo[]>;
+}
+export declare function createFileQueryTool(deps: FileQueryToolDeps): PortableTool<FileQueryToolParams>;
+export declare const FILE_DELETE_TOOL_NAME: "file_delete";
+export interface FileDeleteToolParams {
+    file_id: string;
+}
+export declare const FILE_DELETE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly file_id: {
+            readonly type: "string";
+            readonly description: "ID of the uploaded file to delete.";
+        };
+    };
+    readonly required: readonly ["file_id"];
+};
+export interface FileDeleteToolDeps {
+    deleteFile(params: {
+        fileId: string;
+    }): Promise<void>;
+}
+export declare function createFileDeleteTool(deps: FileDeleteToolDeps): PortableTool<FileDeleteToolParams>;