qlogicagent 2.13.3 → 2.13.5

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

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

@@ -0,0 +1,226 @@
+// ============================================================
+// 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

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

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

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

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

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

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

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

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

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