qlogicagent 2.13.5 → 2.13.7

package/dist/runtime/execution/dream-category-context.d.ts

@@ -1,47 +0,0 @@
-import type { QMemoryCategory } from "../memory/categories.js";
-/** A memory file with its inferred category and metadata. */
-export interface CategorizedMemoryFile {
-    filename: string;
-    category: QMemoryCategory | "uncategorized";
-    /** First line description. */
-    description: string;
-    /** File size bytes. */
-    sizeBytes: number;
-    /** Count of entries/bullets in the file. */
-    entryCount: number;
-}
-/** Category statistics for the dream prompt. */
-export interface CategoryManifest {
-    /** Per-category file groups. */
-    categories: Record<string, CategorizedMemoryFile[]>;
-    /** Total files scanned. */
-    totalFiles: number;
-    /** Files that couldn't be classified. */
-    uncategorizedCount: number;
-}
-/**
- * Scan MEMDIR and classify all topic files by category.
- *
- * @param memoryRoot - The MEMDIR root directory
- * @returns Category manifest with grouped files
- */
-export declare function scanCategoryManifest(memoryRoot: string): Promise<CategoryManifest>;
-/**
- * Category-specific merge/conflict rules for the dream prompt.
- *
- * These rules tell the dream agent how to handle each category:
- * - facts: supersede (newer replaces older when same topic)
- * - lessons: accumulate (append new insights, don't delete old)
- * - preferences: overwrite (latest preference wins)
- * - patterns: merge (consolidate duplicates into one authoritative entry)
- * - decisions: update (add "update" section if decision changed)
- */
-export declare const CATEGORY_MERGE_RULES: Record<QMemoryCategory | "uncategorized", string>;
-/**
- * Format the category manifest and merge rules as an injection block
- * for the dream consolidation prompt.
- *
- * This replaces the blind "grep transcripts" approach with structured
- * guidance about what exists and how to handle each category.
- */
-export declare function formatCategoryContextBlock(manifest: CategoryManifest): string;

package/dist/runtime/execution/dream-category-context.js

@@ -1,226 +0,0 @@
-// ============================================================
-// P5: Dream Category Context — category-aware merge/conflict rules
-// for dream consolidation.
-//
-// Bridges the write gate's category taxonomy into the dream agent's
-// consolidation prompt. Instead of blind full-text grep, dream now:
-//   1. Knows which categories exist in MEMDIR files
-//   2. Uses category-specific merge rules (facts supersede, lessons accumulate)
-//   3. Can classify new signal using the same extractCandidates() logic
-//
-// Reference: memory-write-gate.ts (category signals)
-//            dream-agent.ts (consolidation prompt)
-// ============================================================
-import { readFile, readdir } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-// ── Category Inference ──────────────────────────────────────
-/**
- * Category inference from filename prefix convention.
- * Aligns with P2 write gate categories.
- */
-const FILENAME_CATEGORY_MAP = {
-    "lesson": "lesson",
-    "debug": "lesson",
-    "gotcha": "lesson",
-    "fix": "lesson",
-    "preference": "preference",
-    "style": "preference",
-    "pattern": "pattern",
-    "convention": "pattern",
-    "practice": "pattern",
-    "fact": "fact",
-    "config": "fact",
-    "architecture": "fact",
-    "env": "fact",
-    "deploy": "fact",
-    "decision": "decision",
-    "choice": "decision",
-    "tradeoff": "decision",
-    "skill": "skill-learning",
-    "workflow": "skill-learning",
-};
-/**
- * Content-based category signals (same patterns as write gate).
- */
-const CONTENT_CATEGORY_SIGNALS = {
-    lesson: [
-        /(?:原来|root cause|turns out|the issue was|问题出在|踩坑|gotcha|pitfall)/i,
-        /(?:以后|下次|remember to|don't forget|务必|切记)/i,
-    ],
-    preference: [
-        /(?:我(?:喜欢|偏好|习惯)|I (?:prefer|like|always))/i,
-        /(?:请(?:用|使用)|please use|always use)/i,
-    ],
-    pattern: [
-        /(?:每次|always|whenever|pattern|惯例|convention|best practice)/i,
-    ],
-    fact: [
-        /(?:架构|architecture|port|version|部署|deployed|环境|配置|config)/i,
-    ],
-    decision: [
-        /(?:决定|decided|选择|chosen|采用|因为|because|rationale|trade-?off)/i,
-    ],
-    "skill-learning": [
-        /(?:skill|workflow|tool|command|命令|工具)/i,
-    ],
-};
-/**
- * Infer category from filename prefix.
- */
-function inferCategoryFromFilename(filename) {
-    const name = filename.replace(/\.md$/, "").toLowerCase();
-    for (const [prefix, category] of Object.entries(FILENAME_CATEGORY_MAP)) {
-        if (name.startsWith(prefix + "-") || name.startsWith(prefix + "_") || name === prefix) {
-            return category;
-        }
-    }
-    return null;
-}
-/**
- * Infer category from file content (first 500 chars).
- */
-function inferCategoryFromContent(content) {
-    const sample = content.slice(0, 500);
-    let bestCategory = null;
-    let bestScore = 0;
-    for (const [category, patterns] of Object.entries(CONTENT_CATEGORY_SIGNALS)) {
-        const matchCount = patterns.filter(p => p.test(sample)).length;
-        if (matchCount > bestScore) {
-            bestScore = matchCount;
-            bestCategory = category;
-        }
-    }
-    return bestCategory;
-}
-// ── Scanning ────────────────────────────────────────────────
-/**
- * Scan MEMDIR and classify all topic files by category.
- *
- * @param memoryRoot - The MEMDIR root directory
- * @returns Category manifest with grouped files
- */
-export async function scanCategoryManifest(memoryRoot) {
-    const categories = {};
-    let totalFiles = 0;
-    let uncategorizedCount = 0;
-    if (!existsSync(memoryRoot)) {
-        return { categories, totalFiles: 0, uncategorizedCount: 0 };
-    }
-    let entries;
-    try {
-        entries = await readdir(memoryRoot);
-    }
-    catch {
-        return { categories, totalFiles: 0, uncategorizedCount: 0 };
-    }
-    const mdFiles = entries.filter(f => f.endsWith(".md") && f !== "INDEX.md");
-    for (const filename of mdFiles) {
-        const filePath = join(memoryRoot, filename);
-        try {
-            const content = await readFile(filePath, "utf-8");
-            totalFiles++;
-            // Infer category (filename takes priority)
-            let category = inferCategoryFromFilename(filename)
-                ?? inferCategoryFromContent(content)
-                ?? "uncategorized";
-            if (category === "uncategorized")
-                uncategorizedCount++;
-            // Extract description (first non-heading, non-empty line)
-            const lines = content.split("\n");
-            let description = "";
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("---"))
-                    continue;
-                description = trimmed.slice(0, 120);
-                break;
-            }
-            // Count entries (bullets or numbered items)
-            const entryCount = lines.filter(l => /^\s*[-*+]\s|^\s*\d+[.)]\s/.test(l)).length;
-            if (!categories[category])
-                categories[category] = [];
-            categories[category].push({
-                filename,
-                category,
-                description,
-                sizeBytes: Buffer.byteLength(content, "utf-8"),
-                entryCount,
-            });
-        }
-        catch { /* skip */ }
-    }
-    return { categories, totalFiles, uncategorizedCount };
-}
-// ── Category-Aware Merge Rules ──────────────────────────────
-/**
- * Category-specific merge/conflict rules for the dream prompt.
- *
- * These rules tell the dream agent how to handle each category:
- * - facts: supersede (newer replaces older when same topic)
- * - lessons: accumulate (append new insights, don't delete old)
- * - preferences: overwrite (latest preference wins)
- * - patterns: merge (consolidate duplicates into one authoritative entry)
- * - decisions: update (add "update" section if decision changed)
- */
-export const CATEGORY_MERGE_RULES = {
-    fact: "SUPERSEDE: If a newer fact contradicts an older one (e.g. port changed, version updated), " +
-        "update the existing entry in-place. Do not keep both — stale facts cause confusion. " +
-        "Convert relative dates to absolute. Mark the update date.",
-    lesson: "ACCUMULATE: Lessons learned are valuable even when old. Append new insights to " +
-        "existing lesson files. Only remove a lesson if it's provably wrong (not just outdated). " +
-        "Group related lessons under the same topic file.",
-    preference: "OVERWRITE: User preferences evolve. If a newer statement contradicts an older " +
-        "preference, the newer one wins. Remove the old entry and write the current preference. " +
-        "Keep preferences concise (one line each).",
-    pattern: "MERGE: If multiple entries describe the same pattern, merge them into one " +
-        "authoritative entry with examples. Remove redundant duplicates. " +
-        "A pattern that's been superseded by a better practice should be removed.",
-    decision: "UPDATE: Decisions have context and rationale. When a decision changes, don't " +
-        "delete the old one — add an 'Updated (date):' section explaining what changed and why. " +
-        "This preserves the decision history.",
-    "skill-learning": "CONSOLIDATE: Group related skill entries by tool/workflow. Remove " +
-        "entries for skills that are now obvious or well-documented elsewhere. " +
-        "Keep the most actionable version of each skill note.",
-    uncategorized: "CLASSIFY: Try to infer a category from the content. If it matches " +
-        "lesson/preference/pattern/fact/decision, rename the file with the appropriate prefix. " +
-        "If truly uncategorizable, leave as-is but ensure it has a clear description.",
-};
-// ── Dream Prompt Enhancement ────────────────────────────────
-/**
- * Format the category manifest and merge rules as an injection block
- * for the dream consolidation prompt.
- *
- * This replaces the blind "grep transcripts" approach with structured
- * guidance about what exists and how to handle each category.
- */
-export function formatCategoryContextBlock(manifest) {
-    if (manifest.totalFiles === 0) {
-        return `\n## Category Context\n\nNo existing memory files found. Create new files using the naming convention: \`<category>-<topic>.md\` (e.g. \`lesson-docker.md\`, \`fact-ports.md\`, \`decision-framework.md\`).\n`;
-    }
-    const sections = [];
-    sections.push(`\n## Category Context (${manifest.totalFiles} files)\n`);
-    sections.push("Use category-specific merge rules when updating files:\n");
-    for (const [category, files] of Object.entries(manifest.categories)) {
-        if (files.length === 0)
-            continue;
-        const rule = CATEGORY_MERGE_RULES[category] ?? "";
-        const totalEntries = files.reduce((sum, f) => sum + f.entryCount, 0);
-        sections.push(`### ${category} (${files.length} files, ~${totalEntries} entries)`);
-        sections.push(`**Merge rule**: ${rule}`);
-        sections.push("Files:");
-        for (const f of files.slice(0, 10)) { // Cap listing at 10 per category
-            const desc = f.description ? ` — ${f.description}` : "";
-            sections.push(`- \`${f.filename}\` (${f.entryCount} entries, ${Math.ceil(f.sizeBytes / 1024)}KB)${desc}`);
-        }
-        if (files.length > 10) {
-            sections.push(`- ... and ${files.length - 10} more files`);
-        }
-        sections.push("");
-    }
-    sections.push("### File naming convention");
-    sections.push("New files MUST use category prefix: `<category>-<topic>.md`");
-    sections.push("Valid prefixes: lesson-, preference-, pattern-, fact-, decision-, skill-");
-    sections.push("");
-    return sections.join("\n");
-}

package/dist/runtime/execution/dream-lock.test.d.ts

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

package/dist/runtime/execution/dream-lock.test.js

@@ -1,54 +0,0 @@
-/**
- * Dream consolidation lock: liveness must be decoupled from the gate marker,
- * a crashed holder must be reclaimable, and a successful run advances the gate
- * without leaving the lock behind.
- */
-import { mkdtempSync, rmSync, writeFileSync, existsSync, utimesSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { tryAcquireConsolidationLock, releaseConsolidationLock, markConsolidationComplete, rollbackConsolidationLock, } from "./dream-agent.js";
-const LOCK_FILE = ".consolidate-lock";
-const LAST_CONSOLIDATED_FILE = ".last-consolidated";
-let root;
-beforeEach(() => { root = mkdtempSync(join(tmpdir(), "qla-dream-lock-")); });
-afterEach(() => rmSync(root, { recursive: true, force: true }));
-describe("dream consolidation lock", () => {
-    it("acquires when no lock exists", async () => {
-        expect(await tryAcquireConsolidationLock(root)).toBe(0);
-        expect(existsSync(join(root, LOCK_FILE))).toBe(true);
-    });
-    it("blocks a second acquisition while the lock is fresh and held by THIS live process", async () => {
-        expect(await tryAcquireConsolidationLock(root)).toBe(0);
-        // Lock holds our own (live) pid with a fresh mtime → blocked.
-        expect(await tryAcquireConsolidationLock(root)).toBeNull();
-    });
-    it("reclaims a stale lock (crash + possible PID reuse) past the run ceiling", async () => {
-        // A live pid (ours) but an mtime far in the past → presumed crashed, reclaim.
-        writeFileSync(join(root, LOCK_FILE), String(process.pid));
-        const old = Date.now() / 1000 - 30 * 60; // 30 min ago > 15 min ceiling
-        utimesSync(join(root, LOCK_FILE), old, old);
-        expect(await tryAcquireConsolidationLock(root)).toBe(0);
-    });
-    it("reclaims a lock held by a dead pid even when fresh", async () => {
-        writeFileSync(join(root, LOCK_FILE), "999999999"); // unlikely-live pid, fresh mtime
-        expect(await tryAcquireConsolidationLock(root)).toBe(0);
-    });
-    it("markConsolidationComplete advances the gate marker and releases the lock", async () => {
-        await tryAcquireConsolidationLock(root);
-        await markConsolidationComplete(root);
-        expect(existsSync(join(root, LOCK_FILE))).toBe(false);
-        expect(existsSync(join(root, LAST_CONSOLIDATED_FILE))).toBe(true);
-        // Lock is free again.
-        expect(await tryAcquireConsolidationLock(root)).toBe(0);
-    });
-    it("rollback releases the lock WITHOUT advancing the gate marker", async () => {
-        await tryAcquireConsolidationLock(root);
-        await rollbackConsolidationLock(root, 0);
-        expect(existsSync(join(root, LOCK_FILE))).toBe(false);
-        expect(existsSync(join(root, LAST_CONSOLIDATED_FILE))).toBe(false); // gate untouched
-    });
-    it("releaseConsolidationLock is safe when no lock exists", async () => {
-        await expect(releaseConsolidationLock(root)).resolves.toBeUndefined();
-    });
-});

package/dist/runtime/execution/fork-context.d.ts

@@ -1,14 +0,0 @@
-/**
- * Fork execution context — AsyncLocalStorage-based depth tracking.
- *
- * runForkedAgent() enters a child context at depth = parent + 1. Any tool
- * executed inside that fork (including a nested `agent` tool call) reads the
- * live depth via getCurrentForkDepth(), so the MAX_FORK_DEPTH guard operates
- * on real values instead of a hardcoded 0.
- *
- * Top-level (no fork active) → depth 0.
- */
-/** Current fork depth: 0 at top level, N inside an N-deep forked agent. */
-export declare function getCurrentForkDepth(): number;
-/** Run fn inside a fork context at the given depth. */
-export declare function runAtForkDepth<T>(depth: number, fn: () => T): T;

package/dist/runtime/execution/fork-context.js

@@ -1,20 +0,0 @@
-/**
- * Fork execution context — AsyncLocalStorage-based depth tracking.
- *
- * runForkedAgent() enters a child context at depth = parent + 1. Any tool
- * executed inside that fork (including a nested `agent` tool call) reads the
- * live depth via getCurrentForkDepth(), so the MAX_FORK_DEPTH guard operates
- * on real values instead of a hardcoded 0.
- *
- * Top-level (no fork active) → depth 0.
- */
-import { AsyncLocalStorage } from "node:async_hooks";
-const storage = new AsyncLocalStorage();
-/** Current fork depth: 0 at top level, N inside an N-deep forked agent. */
-export function getCurrentForkDepth() {
-    return storage.getStore()?.depth ?? 0;
-}
-/** Run fn inside a fork context at the given depth. */
-export function runAtForkDepth(depth, fn) {
-    return storage.run({ depth }, fn);
-}

package/dist/runtime/execution/fork-context.test.d.ts

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

package/dist/runtime/execution/fork-context.test.js

@@ -1,101 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { getCurrentForkDepth, runAtForkDepth } from "./fork-context.js";
-import { runForkedAgent } from "./forked-agent.js";
-const log = {
-    info: () => { },
-    warn: () => { },
-    error: () => { },
-    debug: () => { },
-};
-const noopTransport = {};
-const noopInvoker = { invoke: async () => ({ result: "" }) };
-/** Fake runner: invokes the provided body once and emits an end event. */
-function fakeRunnerFactory(body) {
-    return (() => ({
-        run: (async function* () {
-            await body();
-            yield { type: "end", content: "done", usage: { inputTokens: 1, outputTokens: 1 } };
-        }),
-    }));
-}
-describe("fork-context depth tracking", () => {
-    it("is 0 at top level and nests via runAtForkDepth", () => {
-        expect(getCurrentForkDepth()).toBe(0);
-        runAtForkDepth(2, () => {
-            expect(getCurrentForkDepth()).toBe(2);
-        });
-        expect(getCurrentForkDepth()).toBe(0);
-    });
-    it("runForkedAgent executes its loop at parent depth + 1 (live for nested tools)", async () => {
-        let depthInsideFork = -1;
-        await runForkedAgent({
-            promptMessages: [{ role: "user", content: "go" }],
-            tools: [],
-            transport: noopTransport,
-            toolInvoker: noopInvoker,
-            createAgentRunner: fakeRunnerFactory(() => {
-                depthInsideFork = getCurrentForkDepth();
-            }),
-            apiKey: "k",
-            model: "m",
-            log,
-            forkLabel: "depth-test",
-        });
-        expect(depthInsideFork).toBe(1);
-    });
-    it("nested forks inherit the live ALS depth without explicit parentDepth", async () => {
-        let innerDepth = -1;
-        await runForkedAgent({
-            promptMessages: [{ role: "user", content: "outer" }],
-            tools: [],
-            transport: noopTransport,
-            toolInvoker: noopInvoker,
-            createAgentRunner: fakeRunnerFactory(async () => {
-                // Simulates a child agent invoking the agent tool, which forks again.
-                await runForkedAgent({
-                    promptMessages: [{ role: "user", content: "inner" }],
-                    tools: [],
-                    transport: noopTransport,
-                    toolInvoker: noopInvoker,
-                    createAgentRunner: fakeRunnerFactory(() => {
-                        innerDepth = getCurrentForkDepth();
-                    }),
-                    apiKey: "k",
-                    model: "m",
-                    log,
-                    forkLabel: "inner",
-                });
-            }),
-            apiKey: "k",
-            model: "m",
-            log,
-            forkLabel: "outer",
-        });
-        expect(innerDepth).toBe(2);
-    });
-    it("propagates parent abort into the fork's signal", async () => {
-        const parent = new AbortController();
-        let forkSignalAborted;
-        const runnerFactory = (() => ({
-            run: (async function* (_req, signal) {
-                parent.abort("turn cancelled");
-                // Parent abort must propagate synchronously to the child's controller
-                forkSignalAborted = signal.aborted;
-                yield { type: "end", content: "", usage: { inputTokens: 0, outputTokens: 0 } };
-            }),
-        }));
-        await runForkedAgent({
-            promptMessages: [{ role: "user", content: "go" }],
-            tools: [],
-            transport: noopTransport,
-            toolInvoker: noopInvoker,
-            createAgentRunner: runnerFactory,
-            apiKey: "k",
-            model: "m",
-            log,
-            forkLabel: "abort-test",
-            parentSignal: parent.signal,
-        });
-        expect(forkSignalAborted).toBe(true);
-    });
-});

package/dist/runtime/execution/forked-agent.d.ts

@@ -1,111 +0,0 @@
-/**
- * Forked Agent — CC forkedAgent.ts parity.
- *
- * Runs an isolated agent query loop with:
- *   - Independent AbortController (parent abort propagates)
- *   - Independent message history (no mutation of parent conversation)
- *   - Shared LLM config for prompt cache sharing
- *   - Tool restriction via canUseTool function
- *   - Usage tracking across all API calls
- *   - Optional transcript recording
- *
- * This is the execution engine for all sub-agent types:
- *   - Dream consolidation
- *   - Background memory extraction
- *   - Skill/command forking
- *   - AgentTool async agents
- *
- * Reference: claude-code src/utils/forkedAgent.ts
- */
-import type { AgentLogger, ChatMessage, ToolDefinition, ToolInvoker, TokenUsage, TurnEvent, HookRegistry, ForkedAgentRunnerFactory } from "../ports/agent-execution-contracts.js";
-import type { LLMTransport } from "../ports/index.js";
-import type { AgentProgress } from "./progress-tracker.js";
-/**
- * Tool permission check function — CC canUseTool parity.
- *
- * Returns allow/deny for each tool invocation.
- * Used by dream agent (read-only bash + memory writes only),
- * session memory (full read, no write), etc.
- */
-export type CanUseToolFn = (toolName: string, input: Record<string, unknown>) => {
-    allowed: true;
-} | {
-    allowed: false;
-    reason: string;
-};
-/**
- * Parameters for running a forked agent.
- */
-export interface ForkedAgentParams {
-    /** Initial messages for the forked query loop */
-    promptMessages: ChatMessage[];
-    /** System prompt for the forked agent */
-    systemPrompt?: string;
-    /** Available tools */
-    tools: ToolDefinition[];
-    /** Tool permission check (restricts tool access) */
-    canUseTool?: CanUseToolFn;
-    /** LLM transport for API calls */
-    transport: LLMTransport;
-    /** Tool invoker for tool execution */
-    toolInvoker: ToolInvoker;
-    /** Factory for the concrete agent runner. Injected to keep runtime independent from agent/. */
-    createAgentRunner: ForkedAgentRunnerFactory;
-    /** API key */
-    apiKey: string;
-    /** Model name */
-    model: string;
-    /** Logger */
-    log: AgentLogger;
-    /** Hook registry (optional) */
-    hooks?: HookRegistry;
-    /** Label for analytics/debugging */
-    forkLabel: string;
-    /** Source identifier for tracking */
-    querySource?: string;
-    /** Optional cap on number of turns */
-    maxTurns?: number;
-    /** Optional cap on output tokens */
-    maxOutputTokens?: number;
-    /** Temperature override */
-    temperature?: number;
-    /** Parent AbortController (child will be created) */
-    parentSignal?: AbortSignal;
-    /** Callback invoked for each event as it arrives */
-    onEvent?: (event: TurnEvent) => void;
-    /** Callback for progress updates */
-    onProgress?: (progress: AgentProgress) => void;
-    /** Skip transcript recording */
-    skipTranscript?: boolean;
-    /** Token budget for this sub-agent. 0 or undefined = no limit. */
-    budgetTokens?: number;
-    /** Parent fork depth (propagated to child tool loop) */
-    parentDepth?: number;
-}
-/**
- * Result of a forked agent run.
- */
-export interface ForkedAgentResult {
-    /** All events yielded during the query loop */
-    events: TurnEvent[];
-    /** Accumulated token usage across all API calls */
-    totalUsage: TokenUsage;
-    /** Progress tracker final state */
-    progress: AgentProgress;
-    /** Duration of the fork in ms */
-    durationMs: number;
-    /** Whether it completed successfully */
-    ok: boolean;
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Run a forked agent query loop with full isolation.
- *
- * This function:
- *   1. Creates an isolated context (own AbortController, message history)
- *   2. Runs the agent loop with tool restrictions
- *   3. Tracks usage across all API calls
- *   4. Returns accumulated results
- */
-export declare function runForkedAgent(params: ForkedAgentParams): Promise<ForkedAgentResult>;