qlogicagent 2.13.5 → 2.13.6

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

@@ -1,522 +0,0 @@
-/**
- * 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

@@ -1,5 +0,0 @@
-/**
- * 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

@@ -1,4 +0,0 @@
-// ── 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

@@ -1,70 +0,0 @@
-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;