qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/infra/worktree-backend.js

@@ -0,0 +1,522 @@
+/**
+ * Worktree Backend — git command implementation for WorktreeToolDeps.
+ *
+ * CC reference: claude-code-haha/src/utils/worktree.ts
+ *
+ * Implements the host-provided git worktree backend:
+ *   - enterWorktree(): git worktree add -B <branch> <path> HEAD
+ *   - exitWorktree(): git worktree remove / keep
+ *   - listWorktrees(): git worktree listporcelain
+ *   - isInWorktree(): check if cwd is inside a worktree
+ *   - currentWorktree(): get current worktree info
+ *
+ * State management:
+ *   - Tracks current worktree session in memory
+ *   - CWD switching via process.chdir()
+ *   - Safety checks: uncommitted changes, unpushed commits
+ *
+ * Security: validateWorktreeSlug() prevents path traversal.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { join, resolve, basename } from "node:path";
+import { mkdir, rm, symlink, readdir, stat } from "node:fs/promises";
+import { getGitRootHooksDir } from "./agent-paths.js";
+const execFileAsync = promisify(execFile);
+// ── Slug Validation (CC worktree.ts parity) ─────────────────
+const VALID_SLUG_SEGMENT = /^[a-zA-Z0-9._-]+$/;
+const MAX_SLUG_LENGTH = 64;
+function validateWorktreeSlug(slug) {
+    if (slug.length > MAX_SLUG_LENGTH) {
+        throw new Error(`Invalid worktree name: must be ${MAX_SLUG_LENGTH} characters or fewer (got ${slug.length})`);
+    }
+    for (const segment of slug.split("/")) {
+        if (segment === "." || segment === "..") {
+            throw new Error(`Invalid worktree name "${slug}": must not contain "." or ".." path segments`);
+        }
+        if (!VALID_SLUG_SEGMENT.test(segment)) {
+            throw new Error(`Invalid worktree name "${slug}": segment must contain only letters, digits, dots, underscores, and dashes`);
+        }
+    }
+}
+function flattenSlug(slug) {
+    return slug.replaceAll("/", "+");
+}
+function worktreeBranchName(slug) {
+    return `worktree-${flattenSlug(slug)}`;
+}
+let currentSession = null;
+/** Get the current worktree session (CC getCurrentWorktreeSession parity). */
+export function getCurrentWorktreeSession() {
+    return currentSession;
+}
+/** Restore session on resume (CC restoreWorktreeSession parity). */
+export function restoreWorktreeSession(session) {
+    currentSession = session;
+}
+// ── Git Helpers ─────────────────────────────────────────────
+async function gitExec(args, cwd) {
+    try {
+        const { stdout, stderr } = await execFileAsync("git", args, {
+            cwd: cwd ?? process.cwd(),
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: "0",
+                GIT_ASKPASS: "",
+            },
+            timeout: 30_000,
+        });
+        return { stdout, stderr, code: 0 };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            stdout: e.stdout ?? "",
+            stderr: e.stderr ?? String(err),
+            code: e.code ?? 1,
+        };
+    }
+}
+export async function findGitRoot(cwd) {
+    const { stdout, code } = await gitExec(["rev-parse", "--show-toplevel"], cwd);
+    return code === 0 ? stdout.trim() : null;
+}
+async function countUncommittedChanges(cwd) {
+    const { stdout, code } = await gitExec(["status", "--porcelain"], cwd);
+    if (code !== 0)
+        return -1; // fail-closed
+    return stdout.trim().split("\n").filter(Boolean).length;
+}
+async function countUnpushedCommits(cwd, branch) {
+    const { stdout, code } = await gitExec(["rev-list", `origin/${branch}..${branch}`, "--count"], cwd);
+    if (code !== 0)
+        return 0; // no remote tracking = 0 unpushed
+    return parseInt(stdout.trim(), 10) || 0;
+}
+// ── Symlink Directories (CC symlinkDirectories parity) ──────
+/**
+ * Symlink directories from the main repo to avoid duplication (e.g. node_modules).
+ * CC reference: worktree.ts symlinkDirectories()
+ */
+async function symlinkDirectories(repoRootPath, worktreePath, dirsToSymlink, log) {
+    for (const dir of dirsToSymlink) {
+        if (dir.includes("..") || dir.startsWith("/") || dir.startsWith("\\")) {
+            log?.warn(`[worktree] skipping symlink for "${dir}": path traversal detected`);
+            continue;
+        }
+        const sourcePath = join(repoRootPath, dir);
+        const destPath = join(worktreePath, dir);
+        try {
+            await symlink(sourcePath, destPath, "dir");
+            log?.info(`[worktree] symlinked ${dir} from main repo to worktree`);
+        }
+        catch (err) {
+            const code = err.code;
+            // ENOENT: source doesn't exist (expected); EEXIST: dest exists (expected)
+            if (code !== "ENOENT" && code !== "EEXIST") {
+                log?.warn(`[worktree] failed to symlink ${dir} (${code ?? "unknown"}): ${err}`);
+            }
+        }
+    }
+}
+// ── Sparse Checkout (CC getOrCreateWorktree sparse parity) ──
+/**
+ * Apply sparse-checkout in a worktree (cone mode).
+ * Requires the worktree to have been created withno-checkout.
+ */
+async function applySparseCheckout(worktreePath, gitRoot, sparsePaths) {
+    const { code: sparseCode, stderr: sparseErr } = await gitExec(["sparse-checkout", "set", "--cone", "--", ...sparsePaths], worktreePath);
+    if (sparseCode !== 0) {
+        // Tear down broken worktree
+        await gitExec(["worktree", "remove", "--force", worktreePath], gitRoot);
+        throw new Error(`Failed to configure sparse-checkout: ${sparseErr}`);
+    }
+    const { code: coCode, stderr: coErr } = await gitExec(["checkout", "HEAD"], worktreePath);
+    if (coCode !== 0) {
+        await gitExec(["worktree", "remove", "--force", worktreePath], gitRoot);
+        throw new Error(`Failed to checkout sparse worktree: ${coErr}`);
+    }
+    return true;
+}
+// ── Tmux Integration (CC tmux parity) ───────────────────────
+/** Check whether tmux is available on the system. */
+export async function isTmuxAvailable() {
+    try {
+        await execFileAsync("tmux", ["-V"], { timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Generate a tmux session name from repo path and branch (CC parity). */
+export function generateTmuxSessionName(repoPath, branch) {
+    const repoName = basename(repoPath);
+    return `${repoName}_${branch}`.replace(/[/.]/g, "_");
+}
+/**
+ * Create a tmux session for a worktree (CC createTmuxSessionForWorktree parity).
+ * Returns the session name, or null if tmux is not available.
+ */
+export async function createTmuxSession(worktreePath, sessionName) {
+    if (!(await isTmuxAvailable()))
+        return null;
+    try {
+        await execFileAsync("tmux", [
+            "new-session",
+            "-d",
+            "-s", sessionName,
+            "-c", worktreePath,
+        ], { timeout: 10_000 });
+        return sessionName;
+    }
+    catch {
+        return null;
+    }
+}
+/** Kill a tmux session (CC killTmuxSession parity). */
+export async function killTmuxSession(sessionName) {
+    try {
+        await execFileAsync("tmux", ["kill-session", "-t", sessionName], { timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Worktree Hooks (CC executeWorktreeCreateHook/RemoveHook parity) ──
+/**
+ * Execute a user-defined worktree hook script if present.
+ * CC looks for hooks via the HookRegistry; we look for executable scripts
+ * in `.qlogicagent/hooks/` within the repo root.
+ */
+async function executeWorktreeHook(hookName, gitRoot, env, log) {
+    const hookDir = getGitRootHooksDir(gitRoot);
+    const hookPath = join(hookDir, hookName);
+    try {
+        const s = await stat(hookPath);
+        if (!s.isFile())
+            return null;
+    }
+    catch {
+        return null; // No hook script
+    }
+    try {
+        const { stdout, stderr } = await execFileAsync(hookPath, [], {
+            cwd: gitRoot,
+            env: { ...process.env, ...env },
+            timeout: 30_000,
+        });
+        log?.info(`[worktree] hook ${hookName} succeeded: ${stdout.trim()}`);
+        return stdout.trim() || null;
+    }
+    catch (err) {
+        log?.warn(`[worktree] hook ${hookName} failed: ${err}`);
+        return null;
+    }
+}
+// ── Agent Worktree (CC createAgentWorktree parity) ──────────
+/**
+ * Create a lightweight worktree for a sub-agent without modifying the
+ * global session. CC reference: createAgentWorktree().
+ */
+export async function createAgentWorktree(gitRoot, slug, log) {
+    validateWorktreeSlug(slug);
+    const flat = flattenSlug(slug);
+    const branch = worktreeBranchName(slug);
+    const wDir = join(gitRoot, ".worktrees");
+    const worktreePath = join(wDir, flat);
+    await mkdir(wDir, { recursive: true });
+    const { code, stderr } = await gitExec(["worktree", "add", "-B", branch, worktreePath, "HEAD"], gitRoot);
+    if (code !== 0) {
+        log?.warn(`[worktree] agent worktree creation failed: ${stderr}`);
+        return null;
+    }
+    // Symlink node_modules to save disk
+    await symlinkDirectories(gitRoot, worktreePath, ["node_modules"], log);
+    log?.info(`[worktree] agent worktree created: ${slug} at ${worktreePath}`);
+    return { worktreePath, branch };
+}
+/** Remove an agent worktree (CC removeAgentWorktree parity). */
+export async function removeAgentWorktree(gitRoot, worktreePath, branch, log) {
+    const { code } = await gitExec(["worktree", "remove", "--force", worktreePath], gitRoot);
+    if (code !== 0) {
+        await rm(worktreePath, { recursive: true, force: true }).catch(() => { });
+        await gitExec(["worktree", "prune"], gitRoot);
+    }
+    await gitExec(["branch", "-D", branch], gitRoot);
+    log?.info(`[worktree] agent worktree removed: ${worktreePath}`);
+    return true;
+}
+/**
+ * Clean up stale agent worktrees older than maxAgeDays (CC cleanupStaleAgentWorktrees parity).
+ */
+export async function cleanupStaleAgentWorktrees(gitRoot, maxAgeDays = 30, log) {
+    const wDir = join(gitRoot, ".worktrees");
+    let entries;
+    try {
+        entries = await readdir(wDir);
+    }
+    catch {
+        return 0;
+    }
+    const cutoff = Date.now() - maxAgeDays * 86_400_000;
+    let cleaned = 0;
+    for (const entry of entries) {
+        const fullPath = join(wDir, entry);
+        try {
+            const s = await stat(fullPath);
+            if (s.isDirectory() && s.mtimeMs < cutoff) {
+                await gitExec(["worktree", "remove", "--force", fullPath], gitRoot).catch(() => { });
+                await rm(fullPath, { recursive: true, force: true }).catch(() => { });
+                cleaned++;
+                log?.info(`[worktree] cleaned stale agent worktree: ${entry}`);
+            }
+        }
+        catch { /* skip */ }
+    }
+    if (cleaned > 0) {
+        await gitExec(["worktree", "prune"], gitRoot);
+    }
+    return cleaned;
+}
+export function createWorktreeBackend(opts) {
+    const { log, symlinkDirs = ["node_modules"], sparsePaths } = opts;
+    return {
+        async enterWorktree(name) {
+            try {
+                const startMs = Date.now();
+                const gitRoot = await findGitRoot();
+                if (!gitRoot) {
+                    return { success: false, error: "Not in a git repository" };
+                }
+                // Try user-defined worktree-create hook first (CC hookBased parity)
+                const hookResult = await executeWorktreeHook("worktree-create", gitRoot, { WORKTREE_NAME: name ?? "" }, log);
+                if (hookResult) {
+                    const prevCwd = process.cwd();
+                    process.chdir(hookResult);
+                    currentSession = {
+                        originalCwd: prevCwd,
+                        worktreePath: hookResult,
+                        worktreeName: name ?? basename(hookResult),
+                        worktreeBranch: "",
+                        hookBased: true,
+                        creationDurationMs: Date.now() - startMs,
+                    };
+                    return {
+                        success: true,
+                        worktree: {
+                            name: currentSession.worktreeName,
+                            path: hookResult,
+                            branch: "",
+                            isCurrent: true,
+                            hasChanges: false,
+                            unpushedCommits: 0,
+                        },
+                    };
+                }
+                // Generate name if not provided
+                const slug = name ?? `agent-${Date.now().toString(36)}`;
+                validateWorktreeSlug(slug);
+                const flat = flattenSlug(slug);
+                const branch = worktreeBranchName(slug);
+                const worktreeDir = join(gitRoot, ".worktrees");
+                const worktreePath = join(worktreeDir, flat);
+                await mkdir(worktreeDir, { recursive: true });
+                // Check if worktree already exists (resume path — CC fast resume parity)
+                const { stdout: listOut } = await gitExec(["worktree", "list", "--porcelain"], gitRoot);
+                const existingPath = listOut.split("\n").find(l => l.startsWith("worktree ") && l.includes(flat));
+                if (existingPath) {
+                    const resolvedPath = existingPath.replace("worktree ", "").trim();
+                    const prevCwd = process.cwd();
+                    process.chdir(resolvedPath);
+                    currentSession = {
+                        originalCwd: prevCwd,
+                        worktreePath: resolvedPath,
+                        worktreeName: slug,
+                        worktreeBranch: branch,
+                    };
+                    log.info(`[worktree] resumed existing worktree: ${slug} at ${resolvedPath}`);
+                    return {
+                        success: true,
+                        worktree: {
+                            name: slug,
+                            path: resolvedPath,
+                            branch,
+                            isCurrent: true,
+                            hasChanges: false,
+                            unpushedCommits: 0,
+                        },
+                    };
+                }
+                // Create new worktree
+                const useNoCheckout = sparsePaths && sparsePaths.length > 0;
+                const addArgs = ["worktree", "add"];
+                if (useNoCheckout)
+                    addArgs.push("--no-checkout");
+                addArgs.push("-B", branch, worktreePath, "HEAD");
+                const { code, stderr } = await gitExec(addArgs, gitRoot);
+                if (code !== 0) {
+                    return { success: false, error: `git worktree add failed: ${stderr.trim()}` };
+                }
+                // Apply sparse-checkout if configured (CC parity)
+                let appliedSparse = false;
+                if (useNoCheckout && sparsePaths) {
+                    await applySparseCheckout(worktreePath, gitRoot, sparsePaths);
+                    appliedSparse = true;
+                }
+                // Post-creation setup: symlink directories (CC performPostCreationSetup parity)
+                await symlinkDirectories(gitRoot, worktreePath, symlinkDirs, log);
+                // Switch CWD
+                const prevCwd = process.cwd();
+                process.chdir(worktreePath);
+                // Attempt tmux session (CC parity — non-blocking)
+                const tmuxName = generateTmuxSessionName(gitRoot, branch);
+                const tmuxResult = await createTmuxSession(worktreePath, tmuxName);
+                currentSession = {
+                    originalCwd: prevCwd,
+                    worktreePath,
+                    worktreeName: slug,
+                    worktreeBranch: branch,
+                    tmuxSessionName: tmuxResult ?? undefined,
+                    creationDurationMs: Date.now() - startMs,
+                    usedSparsePaths: appliedSparse,
+                };
+                log.info(`[worktree] entered: ${slug} at ${worktreePath}`);
+                return {
+                    success: true,
+                    worktree: {
+                        name: slug,
+                        path: worktreePath,
+                        branch,
+                        isCurrent: true,
+                        hasChanges: false,
+                        unpushedCommits: 0,
+                    },
+                };
+            }
+            catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+        async exitWorktree(action, discardChanges) {
+            if (!currentSession) {
+                return { success: false, error: "Not in a worktree" };
+            }
+            try {
+                const session = currentSession;
+                const gitRoot = await findGitRoot(session.originalCwd);
+                if (!gitRoot) {
+                    return { success: false, error: "Original git root not found" };
+                }
+                if (action === "remove") {
+                    // Safety check: uncommitted changes
+                    const changes = await countUncommittedChanges(session.worktreePath);
+                    const unpushed = await countUnpushedCommits(session.worktreePath, session.worktreeBranch);
+                    if ((changes > 0 || unpushed > 0) && !discardChanges) {
+                        return {
+                            success: false,
+                            error: `Worktree has ${changes} uncommitted change(s) and ${unpushed} unpushed commit(s). Set discardChanges=true to confirm.`,
+                        };
+                    }
+                    // Restore CWD first (can't remove a dir we're in)
+                    process.chdir(session.originalCwd);
+                    currentSession = null;
+                    // Kill tmux session if active (CC parity)
+                    if (session.tmuxSessionName) {
+                        await killTmuxSession(session.tmuxSessionName);
+                    }
+                    // Fire worktree-remove hook (CC executeWorktreeRemoveHook parity)
+                    await executeWorktreeHook("worktree-remove", gitRoot, { WORKTREE_PATH: session.worktreePath }, log);
+                    // Remove worktree
+                    const args = ["worktree", "remove"];
+                    if (discardChanges)
+                        args.push("--force");
+                    args.push(session.worktreePath);
+                    const { code, stderr } = await gitExec(args, gitRoot);
+                    if (code !== 0) {
+                        log.warn(`[worktree] git worktree remove failed: ${stderr.trim()}, cleaning up manually`);
+                        // Fallback: force remove directory and prune
+                        await rm(session.worktreePath, { recursive: true, force: true }).catch(() => { });
+                        await gitExec(["worktree", "prune"], gitRoot);
+                    }
+                    // Clean up the branch (CC parity)
+                    await gitExec(["branch", "-D", session.worktreeBranch], gitRoot);
+                    log.info(`[worktree] removed: ${session.worktreeName}`);
+                }
+                else {
+                    // Keep worktree, just restore CWD
+                    process.chdir(session.originalCwd);
+                    // Kill tmux session even when keeping (CC keepWorktree parity)
+                    if (session.tmuxSessionName) {
+                        await killTmuxSession(session.tmuxSessionName);
+                    }
+                    currentSession = null;
+                    log.info(`[worktree] exited (kept): ${session.worktreeName}`);
+                }
+                return {
+                    success: true,
+                    previousCwd: session.originalCwd,
+                };
+            }
+            catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+        async listWorktrees() {
+            try {
+                const { stdout, code } = await gitExec(["worktree", "list", "--porcelain"]);
+                if (code !== 0) {
+                    return { success: true, worktrees: [] };
+                }
+                const worktrees = [];
+                const cwd = process.cwd();
+                // Parse porcelain output
+                const blocks = stdout.split("\n\n").filter(Boolean);
+                for (const block of blocks) {
+                    const lines = block.split("\n");
+                    let path = "";
+                    let branch = "";
+                    for (const line of lines) {
+                        if (line.startsWith("worktree "))
+                            path = line.slice(9).trim();
+                        if (line.startsWith("branch "))
+                            branch = line.slice(7).trim().replace("refs/heads/", "");
+                    }
+                    if (!path)
+                        continue;
+                    const isCurrent = resolve(path) === resolve(cwd);
+                    const changes = await countUncommittedChanges(path);
+                    const unpushed = await countUnpushedCommits(path, branch);
+                    worktrees.push({
+                        name: branch.startsWith("worktree-") ? branch.slice(9) : basename(path),
+                        path,
+                        branch,
+                        isCurrent,
+                        hasChanges: changes > 0,
+                        unpushedCommits: unpushed,
+                    });
+                }
+                return { success: true, worktrees };
+            }
+            catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+        isInWorktree() {
+            return currentSession !== null;
+        },
+        currentWorktree() {
+            if (!currentSession)
+                return null;
+            return {
+                name: currentSession.worktreeName,
+                path: currentSession.worktreePath,
+                branch: currentSession.worktreeBranch,
+                isCurrent: true,
+                hasChanges: false, // Lazy — checked on exit
+                unpushedCommits: 0,
+            };
+        },
+    };
+}

package/dist/runtime/memory/categories.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Memory categories for QMemory writes.
+ * Each has different value thresholds and retention policies.
+ */
+export type QMemoryCategory = "lesson" | "preference" | "pattern" | "fact" | "decision" | "skill-learning";

package/dist/runtime/memory/categories.js

@@ -0,0 +1,4 @@
+// ── Memory Categories ────────────────────────────────────────
+// Shared type for QMemory entry classification.
+// Used by dream consolidation, recall filters, and memory hooks.
+export {};

package/dist/runtime/memory/find-relevant-memories.d.ts

@@ -0,0 +1,70 @@
+export declare const RELEVANT_MEMORIES_CONFIG: {
+    /** Max topic files to consider during scan. */
+    readonly MAX_SCAN_FILES: 100;
+    /** Max files to surface per turn. */
+    readonly MAX_SELECTED: 5;
+    /** Max bytes per surfaced file (CC: 4096). */
+    readonly MAX_FILE_BYTES: 4096;
+    /** Max total bytes for all surfaced files combined. */
+    readonly MAX_TOTAL_BYTES: number;
+    /** Minimum score to be selected (0.0-1.0). */
+    readonly MIN_SCORE: 0.2;
+    /** Lines to read for header/description extraction. */
+    readonly HEADER_LINES: 10;
+    /** Recency boost: files modified within this many days get a bonus. */
+    readonly RECENCY_DAYS: 7;
+    /** Recency boost amount. */
+    readonly RECENCY_BOOST: 0.15;
+};
+/** Scanned memory file header (CC MemoryHeader parity). */
+export interface MemoryFileHeader {
+    /** Filename (e.g. "lesson-docker.md") */
+    filename: string;
+    /** Absolute path */
+    filePath: string;
+    /** Last modified timestamp (ms since epoch) */
+    mtimeMs: number;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Description extracted from first non-heading line */
+    description: string | null;
+    /** Category inferred from filename prefix */
+    category: string | null;
+}
+/** A selected relevant memory with content loaded. */
+export interface RelevantMemory {
+    /** Filename */
+    filename: string;
+    /** Full file path */
+    filePath: string;
+    /** Last modified timestamp */
+    mtimeMs: number;
+    /** Relevance score (0.0 - 1.0) */
+    score: number;
+    /** Content (possibly truncated) */
+    content: string;
+    /** Whether content was truncated */
+    truncated: boolean;
+}
+/**
+ * Find memory files relevant to a user query.
+ *
+ * CC parity: scans topic files, scores by keyword + filename + recency,
+ * selects top-N, loads content. No LLM needed (unlike CC's Sonnet call).
+ *
+ * @param query - User query text
+ * @param memoryDir - Root of the MEMDIR directory (~/.qlogicagent/memory/)
+ * @param alreadySurfaced - Paths already shown in prior turns (for dedup)
+ * @returns Relevant memories with content, sorted by score
+ */
+export declare function findRelevantMemories(query: string, memoryDir: string, alreadySurfaced?: ReadonlySet<string>): Promise<RelevantMemory[]>;
+/**
+ * Scan memory directory for topic files (excludes INDEX.md).
+ * Returns headers sorted by modification time (newest first).
+ */
+export declare function scanMemoryHeaders(memoryDir: string): Promise<MemoryFileHeader[]>;
+/**
+ * Format relevant memories as a single block for system prompt injection.
+ * CC parity: includes freshness header per file.
+ */
+export declare function formatRelevantMemoriesBlock(memories: RelevantMemory[]): string;