qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/execution/forked-agent.js

@@ -0,0 +1,172 @@
+/**
+ * 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 { createProgressTracker, updateProgressFromUsage, recordToolUse, getProgressUpdate } from "./progress-tracker.js";
+import { getCurrentForkDepth, runAtForkDepth } from "./fork-context.js";
+import { randomUUID } from "node:crypto";
+// ── Forked Agent Runner ─────────────────────────────────────
+/**
+ * Create a child AbortController linked to a parent signal.
+ * Parent abort propagates to child, but child abort does NOT propagate to parent.
+ */
+function createChildAbortController(parentSignal) {
+    const child = new AbortController();
+    if (parentSignal) {
+        if (parentSignal.aborted) {
+            child.abort(parentSignal.reason);
+        }
+        else {
+            parentSignal.addEventListener("abort", () => {
+                child.abort(parentSignal.reason);
+            }, { once: true });
+        }
+    }
+    return child;
+}
+/**
+ * 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 async function runForkedAgent(params) {
+    const startTime = Date.now();
+    const events = [];
+    const totalUsage = { inputTokens: 0, outputTokens: 0 };
+    const tracker = createProgressTracker();
+    const { promptMessages, systemPrompt, tools, canUseTool, transport, toolInvoker, createAgentRunner, apiKey, model, log, hooks, forkLabel, maxTurns, temperature, parentSignal, onEvent, onProgress, budgetTokens, parentDepth, } = params;
+    // Create isolated abort controller
+    const abortController = createChildAbortController(parentSignal);
+    const turnId = `fork-${forkLabel}-${randomUUID().slice(0, 8)}`;
+    const sessionId = `fork-session-${randomUUID().slice(0, 8)}`;
+    // Child runs one level deeper than the caller. Explicit parentDepth wins;
+    // otherwise inherit the live ALS depth (nested forks through the tool loop).
+    const childDepth = (parentDepth ?? getCurrentForkDepth()) + 1;
+    log.info(`[fork:${forkLabel}] starting — ${promptMessages.length} initial messages, model=${model}, depth=${childDepth}`);
+    // Wrap toolInvoker to apply canUseTool restrictions
+    const restrictedInvoker = canUseTool
+        ? {
+            invoke: async (tid, name, args, signal) => {
+                let parsed = {};
+                try {
+                    parsed = JSON.parse(args);
+                }
+                catch { /* ignore */ }
+                const verdict = canUseTool(name, parsed);
+                if (!verdict.allowed) {
+                    log.info(`[fork:${forkLabel}] tool ${name} denied: ${verdict.reason}`);
+                    return { result: "", error: verdict.reason };
+                }
+                return toolInvoker.invoke(tid, name, args, signal);
+            },
+        }
+        : toolInvoker;
+    let ok = true;
+    let error;
+    try {
+        await runAtForkDepth(childDepth, async () => {
+            const agent = createAgentRunner({
+                transport,
+                apiKey,
+                toolInvoker: restrictedInvoker,
+                log,
+                hooks,
+                maxRounds: maxTurns,
+            });
+            for await (const event of agent.run({
+                turnId,
+                sessionId,
+                messages: promptMessages,
+                tools,
+                systemPrompt,
+                config: {
+                    model,
+                    apiKey,
+                    temperature,
+                    maxOutputTokens: params.maxOutputTokens,
+                    parentDepth: childDepth - 1,
+                },
+            }, abortController.signal)) {
+                events.push(event);
+                onEvent?.(event);
+                // Track progress
+                if (event.type === "end" && event.usage) {
+                    updateProgressFromUsage(tracker, {
+                        input_tokens: event.usage.inputTokens,
+                        output_tokens: event.usage.outputTokens,
+                    });
+                    totalUsage.inputTokens += event.usage.inputTokens;
+                    totalUsage.outputTokens += event.usage.outputTokens;
+                    if (event.usage.cacheRead) {
+                        totalUsage.cacheRead = (totalUsage.cacheRead ?? 0) + event.usage.cacheRead;
+                    }
+                    if (event.usage.cacheWrite) {
+                        totalUsage.cacheWrite = (totalUsage.cacheWrite ?? 0) + event.usage.cacheWrite;
+                    }
+                    // Sub-agent budget enforcement: abort if token budget exceeded
+                    if (budgetTokens && budgetTokens > 0) {
+                        const consumed = totalUsage.inputTokens + totalUsage.outputTokens + (totalUsage.reasoningTokens ?? 0);
+                        if (consumed >= budgetTokens) {
+                            log.info(`[fork:${forkLabel}] budget exceeded (${consumed} / ${budgetTokens} tokens), aborting`);
+                            abortController.abort("budget_exceeded");
+                        }
+                    }
+                }
+                if (event.type === "tool_call") {
+                    let parsed = {};
+                    try {
+                        parsed = JSON.parse(event.arguments ?? "{}");
+                    }
+                    catch { /* ignore */ }
+                    recordToolUse(tracker, event.name, parsed);
+                    onProgress?.(getProgressUpdate(tracker));
+                }
+                if (event.type === "error") {
+                    ok = false;
+                    error = event.error;
+                }
+            }
+        });
+    }
+    catch (err) {
+        ok = false;
+        error = err instanceof Error ? err.message : String(err);
+        log.warn(`[fork:${forkLabel}] error: ${error}`);
+    }
+    finally {
+        // Cleanup: abort child controller if still active
+        if (!abortController.signal.aborted) {
+            abortController.abort("fork_complete");
+        }
+    }
+    const durationMs = Date.now() - startTime;
+    log.info(`[fork:${forkLabel}] finished in ${durationMs}ms — ${events.length} events, ` +
+        `usage: prompt=${totalUsage.inputTokens} completion=${totalUsage.outputTokens}, ok=${ok}`);
+    return {
+        events,
+        totalUsage,
+        progress: getProgressUpdate(tracker),
+        durationMs,
+        ok,
+        error,
+    };
+}

package/dist/runtime/execution/index.d.ts

@@ -0,0 +1,7 @@
+export { StreamingToolExecutor } from "./streaming-tool-executor.js";
+export { createContentReplacementState, enforceToolResultBudget, maybePersistLargeToolResult, type ContentReplacementState, type PersistedToolResult, } from "./tool-result-storage.js";
+export { resolveToolEligibility, type ToolEligibilityContext, type ToolEligibilityResult } from "./tool-eligibility.js";
+export { runForkedAgent, type ForkedAgentParams, type CanUseToolFn } from "./forked-agent.js";
+export { runDream, type DreamRunDeps } from "./dream-agent.js";
+export { runDecayCycle, shouldTriggerDecay, markDecayComplete, type DecayCycleDeps, type DecayCycleResult, type DecayConfig } from "./memory-decay.js";
+export { createProgressTracker, updateProgressFromUsage, recordToolUse, getProgressUpdate, type AgentProgress, } from "./progress-tracker.js";

package/dist/runtime/execution/index.js

@@ -0,0 +1,8 @@
+// runtime/execution — tool/agent execution subsystem
+export { StreamingToolExecutor } from "./streaming-tool-executor.js";
+export { createContentReplacementState, enforceToolResultBudget, maybePersistLargeToolResult, } from "./tool-result-storage.js";
+export { resolveToolEligibility } from "./tool-eligibility.js";
+export { runForkedAgent } from "./forked-agent.js";
+export { runDream } from "./dream-agent.js";
+export { runDecayCycle, shouldTriggerDecay, markDecayComplete } from "./memory-decay.js";
+export { createProgressTracker, updateProgressFromUsage, recordToolUse, getProgressUpdate, } from "./progress-tracker.js";

package/dist/runtime/execution/memory-decay.d.ts

@@ -0,0 +1,69 @@
+/** Options for triggering a decay cycle. */
+export interface DecayOptions {
+    temporalExpiry?: boolean;
+    stalenessDecay?: boolean;
+    noiseArchival?: boolean;
+}
+/** Result of a decay cycle. */
+export interface DecayResult {
+    decayed: number;
+    archived: number;
+}
+export interface DecayConfig {
+    /** Minimum hours between decay cycles. Default: 24. */
+    minIntervalHours: number;
+    /** Enable temporal expiry (event/plan memories past grace period). Default: true. */
+    temporalExpiry: boolean;
+    /** Enable staleness decay (reduce importance of unaccessed memories). Default: true. */
+    stalenessDecay: boolean;
+    /** Enable noise archival (archive memories below threshold). Default: true. */
+    noiseArchival: boolean;
+}
+export declare const DEFAULT_DECAY_CONFIG: DecayConfig;
+/**
+ * Check whether enough time has elapsed since last decay.
+ * Returns true if decay should run.
+ */
+export declare function shouldTriggerDecay(memoryRoot: string, config?: Partial<DecayConfig>): Promise<boolean>;
+/**
+ * Mark decay as having just run (persist timestamp).
+ */
+export declare function markDecayComplete(memoryRoot: string): Promise<void>;
+export interface DecayCycleDeps {
+    /** Memory provider with triggerDecay method. */
+    adapter: {
+        triggerDecay(userId: string, maxAgeDays?: number): Promise<{
+            decayed: number;
+        }>;
+    };
+    /** User ID for memory operations. */
+    userId: string;
+    /** Memory root directory (for gate marker). */
+    memoryRoot: string;
+    /** Decay configuration overrides. */
+    config?: Partial<DecayConfig>;
+    /** Logger. */
+    log?: {
+        info(msg: string): void;
+        debug?(msg: string): void;
+    };
+}
+export interface DecayCycleResult {
+    /** Whether decay actually ran (false = skipped by gate). */
+    ran: boolean;
+    /** Number of memories whose importance was reduced. */
+    decayed: number;
+    /** Number of memories archived (below threshold). */
+    archived: number;
+    /** Duration in ms. */
+    durationMs: number;
+}
+/**
+ * Run a full decay cycle with gate check.
+ *
+ * Lifecycle:
+ *   1. Check time gate (24h default)
+ *   2. Call local memory provider decay
+ *   3. Mark completion timestamp
+ */
+export declare function runDecayCycle(deps: DecayCycleDeps): Promise<DecayCycleResult>;

package/dist/runtime/execution/memory-decay.js

@@ -0,0 +1,80 @@
+// ============================================================
+// Memory Importance Decay — triggers QMemory's decay cycle
+// to archive stale/low-importance memories automatically.
+//
+// Design: Runs after Dream consolidation (natural pairing).
+// Gate: 24h cooldown since last decay, configurable.
+// ============================================================
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+export const DEFAULT_DECAY_CONFIG = {
+    minIntervalHours: 24,
+    temporalExpiry: true,
+    stalenessDecay: true,
+    noiseArchival: true,
+};
+// ── Gate ────────────────────────────────────────────────────
+const DECAY_MARKER_FILE = ".last-decay";
+/**
+ * Check whether enough time has elapsed since last decay.
+ * Returns true if decay should run.
+ */
+export async function shouldTriggerDecay(memoryRoot, config = {}) {
+    const minIntervalMs = (config.minIntervalHours ?? DEFAULT_DECAY_CONFIG.minIntervalHours) * 3600_000;
+    const markerPath = path.join(memoryRoot, DECAY_MARKER_FILE);
+    try {
+        const content = await fs.readFile(markerPath, "utf-8");
+        const lastDecayMs = parseInt(content.trim(), 10);
+        if (isNaN(lastDecayMs))
+            return true;
+        return Date.now() - lastDecayMs >= minIntervalMs;
+    }
+    catch {
+        // No marker = never ran → should run
+        return true;
+    }
+}
+/**
+ * Mark decay as having just run (persist timestamp).
+ */
+export async function markDecayComplete(memoryRoot) {
+    const markerPath = path.join(memoryRoot, DECAY_MARKER_FILE);
+    await fs.writeFile(markerPath, String(Date.now()), "utf-8");
+}
+/**
+ * Run a full decay cycle with gate check.
+ *
+ * Lifecycle:
+ *   1. Check time gate (24h default)
+ *   2. Call local memory provider decay
+ *   3. Mark completion timestamp
+ */
+export async function runDecayCycle(deps) {
+    const startTime = Date.now();
+    const cfg = { ...DEFAULT_DECAY_CONFIG, ...deps.config };
+    // Gate check
+    const shouldRun = await shouldTriggerDecay(deps.memoryRoot, cfg);
+    if (!shouldRun) {
+        deps.log?.debug?.("[decay] Skipped — cooldown not elapsed");
+        return { ran: false, decayed: 0, archived: 0, durationMs: Date.now() - startTime };
+    }
+    deps.log?.info("[decay] Starting importance decay cycle");
+    try {
+        const result = await deps.adapter.triggerDecay(deps.userId);
+        await markDecayComplete(deps.memoryRoot);
+        const durationMs = Date.now() - startTime;
+        deps.log?.info(`[decay] Completed — decayed=${result.decayed}, ${durationMs}ms`);
+        return {
+            ran: true,
+            decayed: result.decayed,
+            archived: 0,
+            durationMs,
+        };
+    }
+    catch (err) {
+        const durationMs = Date.now() - startTime;
+        deps.log?.info(`[decay] Failed — ${err instanceof Error ? err.message : String(err)}`);
+        // Non-fatal: decay failure should never break dream or agent
+        return { ran: false, decayed: 0, archived: 0, durationMs };
+    }
+}

package/dist/runtime/execution/progress-tracker.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Progress Tracker — CC ProgressTracker / AgentProgress parity.
+ *
+ * Tracks tool use count, token consumption (input/output split),
+ * and recent tool activities for UI display.
+ *
+ * Reference: claude-code src/tasks/LocalAgentTask/LocalAgentTask.tsx
+ */
+/**
+ * Describes a single tool use activity — for UI previews and progress display.
+ */
+export interface ToolActivity {
+    toolName: string;
+    input: Record<string, unknown>;
+    /** Pre-computed activity description, e.g. "Reading src/foo.ts" */
+    activityDescription?: string;
+    /** True if this is a search operation (grep, glob, etc.) */
+    isSearch?: boolean;
+    /** True if this is a read operation (read_file, cat, etc.) */
+    isRead?: boolean;
+}
+/**
+ * UI-facing progress snapshot — sent to host via JSON-RPC notifications.
+ */
+export interface AgentProgress {
+    toolUseCount: number;
+    tokenCount: number;
+    lastActivity?: ToolActivity;
+    recentActivities?: ToolActivity[];
+    summary?: string;
+}
+/**
+ * Internal mutable state for tracking progress across a query loop.
+ *
+ * Token tracking note:
+ *   - input_tokens in the API is cumulative per turn (includes all previous context),
+ *     so we keep the latest value.
+ *   - output_tokens is per-turn, so we sum those.
+ */
+export interface ProgressTracker {
+    toolUseCount: number;
+    latestInputTokens: number;
+    cumulativeOutputTokens: number;
+    recentActivities: ToolActivity[];
+}
+export declare function createProgressTracker(): ProgressTracker;
+export declare function getTokenCountFromTracker(tracker: ProgressTracker): number;
+/**
+ * Resolver function that returns a human-readable activity description
+ * for a given tool name and input.
+ */
+export type ActivityDescriptionResolver = (toolName: string, input: Record<string, unknown>) => string | undefined;
+/**
+ * Default activity description resolver — extracts meaningful preview
+ * from tool input for UI display.
+ */
+export declare function defaultActivityDescription(toolName: string, input: Record<string, unknown>): string | undefined;
+/**
+ * Update tracker from an assistant message's usage and tool calls.
+ *
+ * CC equivalent: updateProgressFromMessage()
+ */
+export declare function updateProgressFromUsage(tracker: ProgressTracker, usage: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}): void;
+/**
+ * Record a tool use in the tracker.
+ */
+export declare function recordToolUse(tracker: ProgressTracker, toolName: string, input: Record<string, unknown>, resolver?: ActivityDescriptionResolver): void;
+/**
+ * Get a UI-facing progress snapshot from the tracker.
+ *
+ * CC equivalent: getProgressUpdate()
+ */
+export declare function getProgressUpdate(tracker: ProgressTracker): AgentProgress;

package/dist/runtime/execution/progress-tracker.js

@@ -0,0 +1,107 @@
+/**
+ * Progress Tracker — CC ProgressTracker / AgentProgress parity.
+ *
+ * Tracks tool use count, token consumption (input/output split),
+ * and recent tool activities for UI display.
+ *
+ * Reference: claude-code src/tasks/LocalAgentTask/LocalAgentTask.tsx
+ */
+const MAX_RECENT_ACTIVITIES = 5;
+export function createProgressTracker() {
+    return {
+        toolUseCount: 0,
+        latestInputTokens: 0,
+        cumulativeOutputTokens: 0,
+        recentActivities: [],
+    };
+}
+export function getTokenCountFromTracker(tracker) {
+    return tracker.latestInputTokens + tracker.cumulativeOutputTokens;
+}
+// ── Tool Classification ─────────────────────────────────────
+const SEARCH_TOOLS = new Set([
+    "grep", "glob", "search", "Grep", "Glob",
+    "list_dir", "find_files",
+]);
+const READ_TOOLS = new Set([
+    "read_file", "file_read", "cat", "head", "tail",
+    "FileRead",
+]);
+function classifyTool(toolName) {
+    return {
+        isSearch: SEARCH_TOOLS.has(toolName) || undefined,
+        isRead: READ_TOOLS.has(toolName) || undefined,
+    };
+}
+/**
+ * Default activity description resolver — extracts meaningful preview
+ * from tool input for UI display.
+ */
+export function defaultActivityDescription(toolName, input) {
+    // File tools
+    const filePath = input.file_path ?? input.path ?? input.filePath;
+    if (typeof filePath === "string") {
+        const verb = READ_TOOLS.has(toolName) ? "Reading" :
+            toolName.includes("write") || toolName.includes("edit") ? "Editing" : "Using";
+        return `${verb} ${filePath}`;
+    }
+    // Command tools
+    const command = input.command ?? input.cmd;
+    if (typeof command === "string") {
+        const truncated = command.length > 60 ? command.slice(0, 60) + "…" : command;
+        return `Running: ${truncated}`;
+    }
+    // Search tools
+    const query = input.query ?? input.pattern ?? input.search;
+    if (typeof query === "string") {
+        return `Searching: ${query}`;
+    }
+    return undefined;
+}
+// ── Update from Turn Event ──────────────────────────────────
+/**
+ * Update tracker from an assistant message's usage and tool calls.
+ *
+ * CC equivalent: updateProgressFromMessage()
+ */
+export function updateProgressFromUsage(tracker, usage) {
+    // Keep latest input (it's cumulative in the API), sum outputs
+    tracker.latestInputTokens =
+        (usage.input_tokens ?? 0) +
+            (usage.cache_creation_input_tokens ?? 0) +
+            (usage.cache_read_input_tokens ?? 0);
+    tracker.cumulativeOutputTokens += usage.output_tokens ?? 0;
+}
+/**
+ * Record a tool use in the tracker.
+ */
+export function recordToolUse(tracker, toolName, input, resolver) {
+    tracker.toolUseCount++;
+    const classification = classifyTool(toolName);
+    const activity = {
+        toolName,
+        input,
+        activityDescription: resolver?.(toolName, input) ?? defaultActivityDescription(toolName, input),
+        isSearch: classification.isSearch,
+        isRead: classification.isRead,
+    };
+    tracker.recentActivities.push(activity);
+    while (tracker.recentActivities.length > MAX_RECENT_ACTIVITIES) {
+        tracker.recentActivities.shift();
+    }
+}
+/**
+ * Get a UI-facing progress snapshot from the tracker.
+ *
+ * CC equivalent: getProgressUpdate()
+ */
+export function getProgressUpdate(tracker) {
+    return {
+        toolUseCount: tracker.toolUseCount,
+        tokenCount: getTokenCountFromTracker(tracker),
+        lastActivity: tracker.recentActivities.length > 0
+            ? tracker.recentActivities[tracker.recentActivities.length - 1]
+            : undefined,
+        recentActivities: [...tracker.recentActivities],
+    };
+}

package/dist/runtime/execution/streaming-tool-executor.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Streaming Tool Executor — CC StreamingToolExecutor parity.
+ *
+ * Executes tools as they stream in with concurrency control:
+ *   - Concurrent-safe tools execute in parallel with other concurrent-safe tools
+ *   - Non-concurrent tools execute alone (exclusive access)
+ *   - Results are buffered and emitted in the order tools were received
+ *   - Bash errors cascade to abort sibling tools
+ *   - Progress messages are yielded immediately
+ *
+ * Reference: claude-code src/services/tools/StreamingToolExecutor.ts
+ */
+import type { ToolInvoker, AgentLogger, HookRegistry } from "../ports/agent-execution-contracts.js";
+import { type OpenAiToolCall } from "../ports/tool-call-contracts.js";
+export type ToolStatus = "queued" | "executing" | "completed" | "yielded";
+export interface ToolExecutionResult {
+    callId: string;
+    toolName: string;
+    ok: boolean;
+    error?: string;
+    blocked?: boolean;
+    blockReason?: string;
+    durationMs?: number;
+    details?: Record<string, unknown>;
+    message: unknown;
+}
+export interface StreamingToolExecutorConfig {
+    toolInvoker: ToolInvoker;
+    hooks?: HookRegistry;
+    sessionId: string;
+    turnId: string;
+    log: AgentLogger;
+    signal?: AbortSignal;
+    /** Tool names that are considered concurrency-safe */
+    concurrencySafeTools?: Set<string>;
+    /** Hard ceiling on simultaneous tool executions (0 = unlimited). CC parity. */
+    maxConcurrentTools?: number;
+}
+/**
+ * Executes tools with concurrency control and streaming progress.
+ *
+ * Usage:
+ *   1. Call addTool() for each tool call as they arrive from the LLM stream
+ *   2. Call getCompletedResults() to drain completed results (non-blocking)
+ *   3. Call getRemainingResults() to wait for all remaining tools
+ */
+export declare class StreamingToolExecutor {
+    private tools;
+    private hasErrored;
+    private erroredToolDescription;
+    private discarded;
+    private siblingAbortController;
+    private progressResolve?;
+    private readonly config;
+    private readonly concurrencySafe;
+    constructor(config: StreamingToolExecutorConfig);
+    /**
+     * Discard all pending and in-progress tools.
+     * Queued tools won't start, and in-progress tools receive synthetic errors.
+     */
+    discard(): void;
+    /**
+     * Add a tool to the execution queue. Starts executing immediately if conditions allow.
+     */
+    addTool(toolCall: OpenAiToolCall): void;
+    /**
+     * Check if a tool can execute based on current concurrency state.
+     */
+    private canExecuteTool;
+    /**
+     * Process the queue, starting tools when concurrency conditions allow.
+     */
+    private processQueue;
+    /**
+     * Get abort reason for a tool.
+     */
+    private getAbortReason;
+    /**
+     * Get a human-readable description of a tool for error messages.
+     */
+    private getToolDescription;
+    /**
+     * Create a synthetic error result for an aborted tool.
+     */
+    private createSyntheticError;
+    /**
+     * Execute a single tool.
+     */
+    private executeTool;
+    /**
+     * Get completed results that haven't been yielded yet (non-blocking).
+     * Maintains order where necessary.
+     */
+    getCompletedResults(): Generator<ToolExecutionResult>;
+    /**
+     * Wait for remaining tools and yield results as they complete.
+     */
+    getRemainingResults(): AsyncGenerator<ToolExecutionResult>;
+    private hasCompletedResults;
+    private hasExecutingTools;
+    private hasUnfinishedTools;
+}