qlogicagent 0.5.2 → 0.5.3

package/dist/types/runtime/execution/dream-agent.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Dream Sub-agent — CC autoDream parity.
+ *
+ * Memory consolidation runs as a restricted sub-agent:
+ *   - Read-only tool access (bash: ls/grep/cat/find/stat/wc/head/tail)
+ *   - File writes restricted to memory directory
+ *   - 4-phase system prompt: Orient → Gather → Consolidate → Prune
+ *   - Trigger gates: time (24h) + session count (5)
+ *   - PID-based consolidation lock
+ *
+ * Reference: claude-code src/services/autoDream/
+ */
+import type { DreamTaskState, DreamTurn } from "../../orchestration/task-types.js";
+import type { ToolDefinition, ToolInvoker, AgentLogger, HookRegistry } from "../../agent/types.js";
+import type { LLMTransport } from "../../llm/transport.js";
+export interface DreamTriggerConfig {
+    /** Minimum hours since last consolidation. Default: 24. */
+    minHours: number;
+    /** Minimum sessions since last consolidation. Default: 5. */
+    minSessions: number;
+    /** Scan throttle interval (ms). Default: 600_000 (10 min). */
+    scanIntervalMs: number;
+    /** Force run, ignoring gates. */
+    force?: boolean;
+}
+export interface DreamContext {
+    /** Root directory where memory files live. */
+    memoryRoot: string;
+    /** Directory containing session transcript JSONL files. */
+    transcriptDir: string;
+    /** Current agent session ID (excluded from session count). */
+    currentSessionId: string;
+    /** Callback to list session IDs touched since a timestamp. */
+    listSessionsSince: (sinceMs: number) => Promise<string[]>;
+}
+export interface DreamToolRestriction {
+    toolName: string;
+    input: Record<string, unknown>;
+}
+export type DreamToolVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/** Result of a dream consolidation run. */
+export interface DreamRunResult {
+    /** Whether dream ran successfully. */
+    ok: boolean;
+    /** Number of sessions reviewed. */
+    sessionsReviewed: number;
+    /** Memory files touched. */
+    filesTouched: string[];
+    /** Dream turns produced. */
+    turns: DreamTurn[];
+    /** Total duration (ms). */
+    durationMs: number;
+    /** Error message if failed. */
+    error?: string;
+}
+/**
+ * Check if a tool invocation is allowed during dream consolidation.
+ *
+ * Allowed:
+ *   - read_file, grep, glob, search — unrestricted read-only tools
+ *   - bash — only read-only commands (ls, grep, cat, find, stat, wc, head, tail)
+ *   - file_edit, file_write — only within memoryRoot
+ *   - Everything else — denied
+ */
+export declare function canUseDreamTool(memoryRoot: string, restriction: DreamToolRestriction): DreamToolVerdict;
+/**
+ * Build the 4-phase memory consolidation prompt.
+ *
+ * Adapted from CC's consolidationPrompt.ts with our project context.
+ */
+export declare function buildConsolidationPrompt(memoryRoot: string, transcriptDir: string, sessionIds: string[], opts?: {
+    hasQMemory?: boolean;
+}): string;
+/**
+ * Check whether dream consolidation should run.
+ *
+ * Gate order (cheapest first):
+ *   1. Time gate — hours since lastConsolidatedAt >= minHours
+ *   2. Scan throttle — 10-minute interval to suppress redundant scans
+ *   3. Session gate — session count since lastConsolidatedAt >= minSessions
+ *
+ * @returns Session IDs to review, or null if gates failed.
+ */
+export declare function shouldTriggerDream(ctx: DreamContext, config?: Partial<DreamTriggerConfig>): Promise<{
+    sessionIds: string[];
+} | null>;
+/**
+ * Attempt to acquire the consolidation lock.
+ *
+ * @returns Prior mtime (for rollback) or null if blocked.
+ */
+export declare function tryAcquireConsolidationLock(memoryRoot: string): Promise<number | null>;
+/**
+ * Rollback the lock mtime after a failed dream run.
+ */
+export declare function rollbackConsolidationLock(memoryRoot: string, priorMtime: number): Promise<void>;
+/**
+ * Update the lock file to record successful consolidation (mtime = now).
+ */
+export declare function markConsolidationComplete(memoryRoot: string): Promise<void>;
+/** Create initial DreamTaskState. */
+export declare function createDreamTaskState(opts: {
+    sessionId: string;
+    sessionsReviewing: number;
+    priorLockMtime: number;
+    parentTaskId?: string;
+}): DreamTaskState;
+/** Add a turn to the dream state. */
+export declare function addDreamTurn(state: DreamTaskState, turn: DreamTurn, touchedPaths: string[]): DreamTaskState;
+/** Mark dream as completed. */
+export declare function completeDreamState(state: DreamTaskState): DreamTaskState;
+/** Mark dream as failed. */
+export declare function failDreamState(state: DreamTaskState): DreamTaskState;
+/**
+ * Full dream orchestration entry point.
+ *
+ * This coordinates the entire dream lifecycle:
+ *   1. Check trigger gates
+ *   2. Acquire consolidation lock
+ *   3. Build consolidation prompt
+ *   4. Return dream context for the caller to run through agent loop
+ *
+ * The caller (stdio-server) is responsible for:
+ *   - Running the prompt through the agent's tool loop
+ *   - Applying canUseDreamTool() restrictions via tool.before_invoke hook
+ *   - Calling markConsolidationComplete() on success
+ *   - Calling rollbackConsolidationLock() on failure
+ */
+export declare function prepareDreamRun(ctx: DreamContext, config?: Partial<DreamTriggerConfig>): Promise<{
+    prompt: string;
+    taskState: DreamTaskState;
+    sessionIds: string[];
+} | null>;
+export interface DreamRunDeps {
+    /** Dream context (memoryRoot, transcriptDir, etc.) */
+    context: DreamContext;
+    /** Trigger configuration */
+    triggerConfig?: Partial<DreamTriggerConfig>;
+    /** LLM transport */
+    transport: LLMTransport;
+    /** Tool invoker */
+    toolInvoker: ToolInvoker;
+    /** Available tools (will be filtered by canUseDreamTool) */
+    tools: ToolDefinition[];
+    /** API key */
+    apiKey: string;
+    /** Model for dream */
+    model: string;
+    /** Logger */
+    log: AgentLogger;
+    /** Hook registry */
+    hooks?: HookRegistry;
+    /** Parent abort signal */
+    parentSignal?: AbortSignal;
+    /**
+     * QMemory adapter — when provided, Dream Agent acts as the "hippocampus":
+     * reads existing long-term memories, writes classified session insights,
+     * and submits feedback on outdated/contradicted memories.
+     */
+    qmemoryAdapter?: {
+        search(query: string, userId: string, options?: {
+            limit?: number;
+        }): Promise<Array<{
+            blockId: string;
+            text: string;
+            score: number;
+        }>>;
+        addText?(text: string, userId: string, options?: {
+            sessionId?: string;
+            source?: string;
+        }): Promise<{
+            memoriesAdded: number;
+        }>;
+        feedback?(memoryIds: string[], signal: string, sessionId?: string): Promise<void>;
+    };
+    /** User ID for QMemory operations. */
+    qmemoryUserId?: string;
+}
+/**
+ * Run a complete dream consolidation using an isolated forked agent.
+ *
+ * CC parity: This uses runForkedAgent() for true isolation instead of
+ * hook-based tool restriction on the shared agent loop. The dream runs
+ * in its own message history with its own AbortController.
+ *
+ * Full lifecycle:
+ *   1. Check trigger gates
+ *   2. Acquire consolidation lock
+ *   3. Build consolidation prompt
+ *   4. Fork sub-agent with restricted tools
+ *   5. Run to completion
+ *   6. Mark consolidation complete (or rollback on failure)
+ */
+export declare function runDream(deps: DreamRunDeps): Promise<DreamRunResult>;

package/dist/types/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 } from "../../agent/types.js";
+import type { LLMTransport } from "../../llm/transport.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;
+    /** 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 sidechain depth (propagated to child tool loop) */
+    parentDepth?: number;
+    /** Sidechain type for tool access policy (default "code-repair" = full) */
+    sidechainType?: import("../../orchestration/index.js").SidechainType;
+}
+/**
+ * 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>;

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

@@ -0,0 +1,6 @@
+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 { createProgressTracker, updateProgressFromUsage, recordToolUse, getProgressUpdate, type AgentProgress, } from "./progress-tracker.js";

package/dist/types/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/types/runtime/execution/remote-agent.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Remote Agent Runtime — cloud sandbox execution via HTTP relay.
+ *
+ * Enables the local agent to delegate tasks to a cloud-hosted sandbox
+ * (e.g., qlogicagent-hub GPU workers, CCR-style isolated environments).
+ *
+ * Protocol:
+ *   1. POST /agents/run  → start remote execution, returns sessionId
+ *   2. GET  /agents/:id  → poll for status + streaming results
+ *   3. POST /agents/:id/abort → cancel remote execution
+ *
+ * Reference: CC cloudCode / remoteAgent patterns
+ */
+import type { AgentLogger, TokenUsage } from "../../agent/types.js";
+export interface RemoteAgentConfig {
+    /** Base URL of the remote execution endpoint (e.g., hub relay). */
+    baseUrl: string;
+    /** API key for authentication. */
+    apiKey: string;
+    /** Timeout for HTTP requests in ms (default: 30_000). */
+    timeoutMs?: number;
+    /** Polling interval in ms (default: 2_000). */
+    pollIntervalMs?: number;
+    /** Max polling duration in ms (default: 300_000 = 5 min). */
+    maxPollDurationMs?: number;
+    /** Logger. */
+    log: AgentLogger;
+}
+export interface RemoteAgentRequest {
+    /** Task prompt for the remote agent. */
+    prompt: string;
+    /** Model to use on the remote side. */
+    model?: string;
+    /** Max turns for the remote agent. */
+    maxTurns?: number;
+    /** Tool restrictions (allowlist). */
+    allowedTools?: string[];
+    /** Label for tracking. */
+    label?: string;
+}
+export interface RemoteAgentResult {
+    /** Remote session ID. */
+    sessionId: string;
+    /** Whether it completed successfully. */
+    ok: boolean;
+    /** Text output from the remote agent. */
+    output?: string;
+    /** Error message if failed. */
+    error?: string;
+    /** Token usage on the remote side. */
+    usage?: TokenUsage;
+    /** Duration in ms. */
+    durationMs: number;
+}
+/**
+ * Run a task on a remote agent endpoint.
+ *
+ * This is a polling-based implementation:
+ * 1. POST to start the remote execution
+ * 2. Poll GET until completion or timeout
+ * 3. Return the aggregated result
+ */
+export declare function runRemoteAgent(config: RemoteAgentConfig, request: RemoteAgentRequest, signal?: AbortSignal): Promise<RemoteAgentResult>;

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

@@ -0,0 +1,100 @@
+/**
+ * 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 "../../agent/types.js";
+import { type OpenAiToolCall } from "../../orchestration/index.js";
+export type ToolStatus = "queued" | "executing" | "completed" | "yielded";
+export interface ToolExecutionResult {
+    callId: string;
+    toolName: string;
+    ok: boolean;
+    error?: string;
+    blocked?: boolean;
+    blockReason?: string;
+    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;
+}

package/dist/types/runtime/execution/tool-eligibility.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tool eligibility resolver for CLI subprocess mode.
+ *
+ * Ported from src/core/runtime/tool-eligibility.ts, replacing Hub's
+ * StoredGatewayCapabilitySnapshot with CLI's ToolDefinition[] from agent.turn.
+ *
+ * Core decision logic preserved:
+ *   - Policy blocked (explicit block list)
+ *   - Approval required (meta.requiresApproval / meta.isDangerous)
+ *   - Read-only / safe tools (meta.isReadOnly → skip approval even in strict)
+ *   - All tools from Gateway manifest are considered enabled & reachable
+ *     (Gateway only sends available tools)
+ *
+ * Zero imports from express/pg/ioredis/ws.
+ */
+import type { ToolDefinition } from "../../agent/types.js";
+/**
+ * Tool permission levels aligned with Claude Code's permission model:
+ *
+ *   Level 1 — always-allow:  isReadOnly tools (e.g. read_file, search)
+ *   Level 2 — default-allow: normal tools with no risk markers
+ *   Level 3 — notify:        isDangerous tools → emit tool_blocked warning but allow
+ *   Level 4 — ask:           requiresApproval tools → hook can block, emit approval.requested
+ *   Level 5 — never-allow:   explicitly blocked by policy
+ */
+export type PermissionLevel = 1 | 2 | 3 | 4 | 5;
+export type ToolEligibilityStatus = "eligible" | "approval-required" | "blocked-by-policy" | "dangerous-notify";
+export type ToolEligibilityReasonCode = "policy_blocked" | "approval_required" | "dangerous_tool" | "always_allowed";
+export interface ToolEligibilityEntry {
+    toolName: string;
+    status: ToolEligibilityStatus;
+    permissionLevel: PermissionLevel;
+    approvalRequired: boolean;
+    reasonCodes: ToolEligibilityReasonCode[];
+}
+export interface ToolEligibilityContext {
+    /** Explicitly blocked tool names (e.g. from config or policy) */
+    blockedToolNames?: string[];
+    /** Dangerous tool name patterns (regex strings) for pattern-based detection */
+    dangerousPatterns?: string[];
+}
+export interface ToolEligibilityResult {
+    /** Tools eligible for execution (includes approval-required ones) */
+    eligibleTools: ToolDefinition[];
+    /** Tools blocked by policy (removed from LLM tool list) */
+    blockedTools: ToolEligibilityEntry[];
+    /** Tools needing approval before execution */
+    approvalRequiredTools: ToolEligibilityEntry[];
+    /** Full eligibility map by tool name */
+    eligibilityByName: Map<string, ToolEligibilityEntry>;
+}
+/**
+ * Resolve tool eligibility for a set of tools from agent.turn.
+ *
+ * Returns filtered tool lists and eligibility metadata.
+ * Blocked tools are removed from the eligible list (not sent to LLM).
+ * Approval-required tools remain in the list but flagged for hook interception.
+ */
+export declare function resolveToolEligibility(tools: ToolDefinition[], context?: ToolEligibilityContext): ToolEligibilityResult;