qlogicagent 1.1.0 → 1.2.0

package/dist/types/runtime/infra/agent-process.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Agent Process Manager — CC tmux-aligned subprocess isolation.
+ *
+ * Spawns team member agents as independent child processes, each with:
+ *   - Own cwd (set to worktree path for git isolation)
+ *   - Own stdin/stdout JSON-RPC transport
+ *   - Own memory + tool context (no shared process.cwd)
+ *   - Lifecycle tracking (PID, health, abort)
+ *
+ * CC does this via tmux split-pane + `claude --agent-id ...` commands.
+ * We spawn `node dist/cli.js` as child processes with JSON-RPC stdio.
+ *
+ * Reference: claude-code-haha/src/utils/swarm/spawnMultiAgent.ts
+ * Reference: claude-code-haha/src/utils/swarm/spawnUtils.ts
+ */
+import type { ExternalAgentDescriptor, McpServerConfig } from "./acp-types.js";
+import type { AgentConfig } from "./acp-types.js";
+import { AcpUsageTracker } from "./acp-usage-tracker.js";
+export interface AgentProcessConfig {
+    /** Unique member ID (e.g. "team-research-coder"). */
+    memberId: string;
+    /** Display name. */
+    name: string;
+    /** Working directory for this agent (worktree path). */
+    cwd: string;
+    /** Initial task prompt sent after handshake. */
+    prompt: string;
+    /** Environment variables to forward (subset of parent env). */
+    env?: Record<string, string>;
+    /** Agent type hint for the child (sets system prompt behavior). */
+    agentType?: string;
+    /** Model override for the child. */
+    model?: string;
+    /** API key (forwarded via env). */
+    apiKey?: string;
+    /** Base URL for LLM API. */
+    baseUrl?: string;
+    /** Enable verbose logging in child. */
+    verbose?: boolean;
+    /** External ACP agent descriptor (if set, spawn via ACP protocol). */
+    external?: ExternalAgentDescriptor;
+    /** MCP server configs to inject into ACP session (only for external agents). */
+    mcpServers?: McpServerConfig[];
+    /** System prompt to inject into ACP session. */
+    systemPrompt?: string;
+}
+/** Snapshot of ongoing media generation progress reported by a child agent. */
+export interface MediaProgressSnapshot {
+    /** Provider-specific task ID (e.g. volcengine job id). */
+    taskId: string;
+    /** Media type ("video" | "image" | "tts" | "3d"). */
+    mediaType: string;
+    /** Estimated completion 0-100. */
+    percent: number;
+    /** Provider status label (e.g. "queuing", "running", "processing"). */
+    status: string;
+    /** Which provider. */
+    provider?: string;
+    /** When this snapshot was last updated. */
+    updatedAt: number;
+}
+export interface AgentProcessHandle {
+    /** Process identifier for this agent. */
+    memberId: string;
+    /** Display name. */
+    name: string;
+    /** OS process ID (-1 if not spawned). */
+    pid: number;
+    /** Working directory. */
+    cwd: string;
+    /** Current lifecycle state. */
+    state: "starting" | "ready" | "running" | "completed" | "failed" | "killed";
+    /** Session ID assigned by the child (after initialize). */
+    sessionId?: string;
+    /** Final result text (after turn completes). */
+    resultText?: string;
+    /** Error message if failed. */
+    error?: string;
+    /** Spawn timestamp. */
+    startedAt: number;
+    /** End timestamp. */
+    endedAt?: number;
+    /** Latest media generation progress (auto-captured from child turn.media_progress). */
+    mediaProgress?: MediaProgressSnapshot;
+    /** Last tool call name seen from child (from turn.tool_call notification). */
+    lastToolCall?: string;
+    /** Last status text from child (from turn.delta notification). */
+    lastDelta?: string;
+    /** Last delta timestamp. */
+    lastActivityAt?: number;
+    /** Whether the ACP agent supports session/resume (D-1). */
+    supportsResume?: boolean;
+}
+/** Callbacks for process lifecycle events. */
+export interface AgentProcessCallbacks {
+    /** Called when child emits a JSON-RPC notification. */
+    onNotification?: (memberId: string, method: string, params: unknown) => void;
+    /** Called when child process state changes. */
+    onStateChange?: (memberId: string, state: AgentProcessHandle["state"]) => void;
+    /** Called when child process exits. */
+    onExit?: (memberId: string, code: number | null, signal: string | null) => void;
+    /** Called when MCP bridge server proxies a tool call from an external agent. */
+    onMcpToolCall?: (memberId: string, tool: string, args: Record<string, unknown>) => Promise<unknown>;
+    /** Logger. */
+    log?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        debug?(msg: string): void;
+    };
+    /** Session directory for stderr logs. If set, ACP agent stderr is written to {sessionDir}/{agentId}.stderr.log. */
+    sessionDir?: string;
+}
+/**
+ * Build LLM-related environment variables for an external ACP teammate.
+ *
+ * Priority chain:
+ *   1. Per-agent override (AgentConfig.apiKey / baseUrl)
+ *   2. Gateway proxy mode (all requests through shared gateway)
+ *   3. Inherit from qlogicagent's own env
+ *
+ * Handles the asymmetry between agents that support base URL override
+ * (can redirect to gateway) vs those that don't (only API key forwarding).
+ */
+export declare function buildLlmEnvForTeammate(agentId: string, agentConfig: AgentConfig | null, gatewayUrl: string | undefined): Record<string, string>;
+/** Fault severity levels for ACP agent errors. */
+export declare const ACP_FAULT_LEVEL: {
+    /** Unrecoverable — agent binary missing, permission denied, etc. */
+    readonly FATAL: "fatal";
+    /** Retriable — spawn timeout, handshake timeout, transient crash. */
+    readonly RETRIABLE: "retriable";
+    /** Warning — non-critical issue (e.g. degraded capabilities). */
+    readonly WARN: "warn";
+};
+export type AcpFaultLevel = (typeof ACP_FAULT_LEVEL)[keyof typeof ACP_FAULT_LEVEL];
+/**
+ * Manages a pool of child agent processes.
+ * Each child is a `qlogicagent` subprocess using JSON-RPC over stdio.
+ */
+export declare class AgentProcessManager {
+    private processes;
+    private callbacks;
+    private cliBinaryPath;
+    private mcpBridgeScriptPath;
+    constructor(callbacks?: AgentProcessCallbacks);
+    /** Format: [ISO] [level] [agent:id] [phase] message */
+    private slog;
+    /** Spawn a child agent process in the given cwd. */
+    spawn(config: AgentProcessConfig): Promise<AgentProcessHandle>;
+    /**
+     * Send a task to a child agent (e.g. thread.turn).
+     * Returns the JSON-RPC result.
+     */
+    sendTask(memberId: string, prompt: string, options?: {
+        model?: string;
+        apiKey?: string;
+        baseUrl?: string;
+        sessionId?: string;
+        timeout?: number;
+    }): Promise<unknown>;
+    /** Send a raw JSON-RPC request to a child. */
+    sendRpc(memberId: string, method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+    /**
+     * Send a long-running task to a child agent with heartbeat keepalive.
+     *
+     * Unlike `sendTask()` (which blocks for up to 5 minutes), this method:
+     *   1. Dispatches the task via `thread.turn`
+     *   2. Periodically sends `ping` RPCs to detect child liveness
+     *   3. Supports very long execution times (hours/days) for async work
+     *      like video generation, batch processing, etc.
+     *
+     * The child is expected to emit `turn.delta` / `turn.progress`
+     * notifications during long work. If no response to ping within
+     * `pingTimeout`, the task is considered failed.
+     */
+    sendTaskAsync(memberId: string, prompt: string, options?: {
+        model?: string;
+        apiKey?: string;
+        baseUrl?: string;
+        sessionId?: string;
+        /** Total timeout for the task (default: unlimited, 0 = no timeout) */
+        timeout?: number;
+        /** Ping interval in ms (default: 60_000 = 1 minute) */
+        pingInterval?: number;
+        /** Ping response timeout in ms (default: 10_000) */
+        pingTimeout?: number;
+    }): Promise<unknown>;
+    /**
+     * Ping a child agent to check liveness.
+     *
+     * Q-2 protocol alignment:
+     * - Internal agents: JSON-RPC `ping` request (guaranteed to respond).
+     * - ACP agents: Send `notifications/ping` notification, then wait for
+     *   `$/alive` notification back. Falls back to `sendRpc("ping")` if
+     *   `$/alive` is not received (some ACP agents may support RPC ping).
+     */
+    ping(memberId: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Get the runtime status of a child agent process.
+     * Includes real-time media generation progress if available.
+     */
+    getStatus(memberId: string): {
+        alive: boolean;
+        state: AgentProcessHandle["state"];
+        runningFor?: number;
+        resultText?: string;
+        error?: string;
+        /** Current media generation progress (from child's turn.media_progress). */
+        mediaProgress?: MediaProgressSnapshot;
+        /** Last tool the child invoked. */
+        lastToolCall?: string;
+        /** Seconds since last activity from child. */
+        idleFor?: number;
+    } | null;
+    /**
+     * Auto-capture structured progress from child notifications.
+     * This is the key mechanism that allows the parent to know:
+     *   - Which provider task ID the child is polling (for video/3D/TTS)
+     *   - Real progress percentage
+     *   - What the child is currently doing (which tool, what delta text)
+     */
+    private captureChildProgress;
+    /**
+     * Spawn an external ACP agent with retry logic.
+     * Retries up to MAX_SPAWN_RETRIES times with exponential backoff.
+     */
+    private spawnAcpAgentWithRetry;
+    /**
+     * Spawn an external ACP agent process.
+     * Uses the ACP protocol adapter for lifecycle management.
+     */
+    private spawnAcpAgent;
+    /** Kill a specific child agent process. */
+    kill(memberId: string): void;
+    /** Kill all child processes and clean up. */
+    killAll(): void;
+    /** Get the handle for a specific member. */
+    getHandle(memberId: string): AgentProcessHandle | undefined;
+    /** Get all handles. */
+    getAllHandles(): AgentProcessHandle[];
+    /** Get usage tracker for an ACP agent (returns null for internal agents). */
+    getUsageTracker(memberId: string): AcpUsageTracker | null;
+    /**
+     * Create a named-pipe IPC server for MCP bridge tool-call proxying.
+     * External agents' MCP bridge servers connect here to proxy tool calls
+     * back to qlogicagent.
+     */
+    private createMcpIpcServer;
+    /** Handle a single JSON-RPC message from the MCP bridge IPC connection. */
+    private handleMcpIpcMessage;
+    /**
+     * Attempt to restart a crashed ACP agent.
+     * Re-spawns the child process prepping the same config and env,
+     * then re-runs ACP handshake.
+     */
+    private attemptRuntimeRestart;
+    /** Get IPC pipe path for a member's MCP bridge. */
+    getMcpIpcPath(memberId: string): string | undefined;
+    private heartbeatTimers;
+    private missedBeats;
+    /** Heartbeat interval (ms). */
+    private static readonly HEARTBEAT_INTERVAL;
+    /** Number of missed heartbeats before force-kill. */
+    private static readonly MAX_MISSED_BEATS;
+    /**
+     * Start heartbeat monitoring for a running agent.
+     * Sends periodic ping RPCs; after MAX_MISSED_BEATS consecutive failures,
+     * the agent is force-killed and marked as "hang".
+     */
+    startHeartbeat(memberId: string, onHang?: (memberId: string) => void): void;
+    /** Stop heartbeat monitoring for an agent. */
+    stopHeartbeat(memberId: string): void;
+    /** Get missed heartbeat count for an agent. */
+    getMissedBeats(memberId: string): number;
+    /** Get count of active (non-terminal) processes. */
+    activeCount(): number;
+    /** Remove a terminated process from tracking. */
+    remove(memberId: string): void;
+    /** Clean up all processes. */
+    dispose(): void;
+}

package/dist/types/runtime/infra/agent-process.test.d.ts

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

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

@@ -6,3 +6,13 @@ export { TaskStore } from "./task-runtime.js";
 export { createWorktreeBackend } from "./worktree-backend.js";
 export { registerCleanup, runCleanupFunctions } from "./cleanup-registry.js";
 export { atomicWriteFile, readJsonFile, writeJsonFile, loadPersistedMemory, savePersistedMemory, getMemoryFilePath, type PersistedMemory, } from "./disk-storage.js";
+export { AcpDetector, ACP_BACKENDS } from "./acp-detector.js";
+export { AcpProtocolAdapter, type TranslatedNotification } from "./acp-protocol-adapter.js";
+export { AcpUsageTracker, type AccumulatedUsage } from "./acp-usage-tracker.js";
+export { AgentConfigStore } from "./agent-config-store.js";
+export { ModelIdTranslator } from "./model-id-translator.js";
+export { SkillInjector } from "./skill-injector.js";
+export { ACP_FAULT_LEVEL, type AcpFaultLevel, buildLlmEnvForTeammate } from "./agent-process.js";
+export { McpBridge, MCP_BRIDGE_TOOLS } from "./mcp-bridge.js";
+export type { AgentCategory, AgentProtocol, AgentStatus, AcpBackendConfig, AgentDescriptor, ExternalAgentDescriptor, CustomAgentDef, AgentConfig, AgentConfigStoreData, AgentCapabilities, AcpInitializeResult, AcpSessionResult, AcpPromptResponse, AcpContentItem, AcpPromptResponseUsage, AcpUsageUpdatePayload, McpServerConfig, AgentsScanParams, AgentsConfigParams, AgentsSetConfigParams, AgentsGetConfigParams, AgentsRemoveConfigParams, AgentsSetGatewayParams, SoloState, SoloAgentState, SoloAgentResult, SoloEvaluation, SoloStatus, SoloStartParams, SoloIdParams, SoloSelectParams, ProductPhase, ProductInstanceState, ProductTaskStatus, ProductBudget, ProductInstanceDef, ProductTaskDef, ProductCreateParams, ProductIdParams, ProductInstanceStatus, ProductTaskState, ProductStatus, ProductSummary, AgentsGetGatewayResult, AgentsListConfiguredItem, AgentsProcessInfo, AgentsKillParams, AgentsGetLogParams, AgentsGetLogResult, AgentsTestConnectionParams, AgentsTestConnectionResult, SoloDeleteParams, ProductDeleteParams, AgentSource, } from "./acp-types.js";
+export type { AgentsStatusNotification, AgentsErrorNotification, SoloProgressNotification, SoloEvaluationNotification, SoloAgentDeltaNotification, ProductTaskStartedNotification, ProductTaskCompletedNotification, ProductTaskFailedNotification, ProductCheckpointedNotification, ProductBudgetWarningNotification, ProductCompletedNotification, } from "../../protocol/notifications.js";

package/dist/types/runtime/infra/mcp-bridge.d.ts

@@ -0,0 +1,166 @@
+/**
+ * MCP Bridge — exports qlogicagent tools as MCP (Model Context Protocol) servers
+ * for injection into external ACP agent sessions.
+ *
+ * When an ACP agent's session is created, we inject MCP servers that expose
+ * qlogicagent's native tools (media_generate, memory_*, web_search, etc.)
+ * so external agents can call them.
+ *
+ * Architecture:
+ *   qlogicagent ─── ACP ───→ external agent
+ *       └── MCP bridge server ◄── tools/call ── external agent
+ *
+ * The bridge server runs as a stdio child process. Each external agent
+ * session gets its own MCP bridge server instance.
+ */
+import type { McpServerConfig, AgentCapabilities } from "./acp-types.js";
+/**
+ * Tools exported via MCP bridge.
+ * These represent qlogicagent capabilities that external agents can call.
+ */
+export declare const MCP_BRIDGE_TOOLS: readonly [{
+    readonly name: "media_generate";
+    readonly description: "Generate images or videos using AI models.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly prompt: {
+                readonly type: "string";
+                readonly description: "Generation prompt";
+            };
+            readonly type: {
+                readonly type: "string";
+                readonly enum: readonly ["image", "video"];
+                readonly description: "Media type";
+            };
+        };
+        readonly required: readonly ["prompt"];
+    };
+}, {
+    readonly name: "media_status";
+    readonly description: "Check status of an async media generation job.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly jobId: {
+                readonly type: "string";
+                readonly description: "Job ID to check";
+            };
+        };
+        readonly required: readonly ["jobId"];
+    };
+}, {
+    readonly name: "memory_read";
+    readonly description: "Read from persistent memory.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly key: {
+                readonly type: "string";
+                readonly description: "Memory key to read";
+            };
+        };
+        readonly required: readonly ["key"];
+    };
+}, {
+    readonly name: "memory_write";
+    readonly description: "Write to persistent memory.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly key: {
+                readonly type: "string";
+                readonly description: "Memory key";
+            };
+            readonly value: {
+                readonly type: "string";
+                readonly description: "Value to store";
+            };
+        };
+        readonly required: readonly ["key", "value"];
+    };
+}, {
+    readonly name: "memory_search";
+    readonly description: "Search persistent memory by query.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Search query";
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+}, {
+    readonly name: "web_search";
+    readonly description: "Search the web for information.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Search query";
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+}, {
+    readonly name: "web_fetch";
+    readonly description: "Fetch content from a URL.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly url: {
+                readonly type: "string";
+                readonly description: "URL to fetch";
+            };
+        };
+        readonly required: readonly ["url"];
+    };
+}, {
+    readonly name: "team_status";
+    readonly description: "Get status of all agent team members.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+}, {
+    readonly name: "team_message";
+    readonly description: "Send a message to another team member agent.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly targetAgentId: {
+                readonly type: "string";
+                readonly description: "Target agent ID";
+            };
+            readonly message: {
+                readonly type: "string";
+                readonly description: "Message to send";
+            };
+        };
+        readonly required: readonly ["targetAgentId", "message"];
+    };
+}];
+export declare class McpBridge {
+    private bridgeScriptPath;
+    constructor(distDir: string);
+    /**
+     * Check whether an ACP agent supports MCP server injection.
+     */
+    canInjectMcp(capabilities?: AgentCapabilities): boolean;
+    /**
+     * Generate the MCP server config to inject into an ACP session.
+     * This config tells the ACP agent how to spawn our MCP bridge server.
+     *
+     * @param parentRpcPort - Port/path for the bridge to call back to qlogicagent
+     * @param sessionId - Current session ID for scoping
+     */
+    getMcpServerConfig(parentRpcPort: string, sessionId: string): McpServerConfig;
+    /**
+     * Get the list of tools that the MCP bridge will expose.
+     * Can be used for display or capability checking.
+     */
+    getExportedTools(): typeof MCP_BRIDGE_TOOLS;
+}

package/dist/types/runtime/infra/mcp-bridge.test.d.ts

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

package/dist/types/runtime/infra/model-id-translator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Model ID Translator — converts qlogicagent internal model IDs
+ * to external agent-specific model IDs.
+ *
+ * Lookup order:
+ *   1. Per-agent custom override (from AgentConfig.modelIdMap)
+ *   2. Pre-built translation table (covers mainstream agents)
+ *   3. Pass-through (unknown IDs forwarded as-is, never blocked)
+ */
+export declare class ModelIdTranslator {
+    /**
+     * Translate a model ID for a specific agent.
+     *
+     * @param agentId - Target agent (e.g. "claude", "codex")
+     * @param internalModelId - qlogicagent's internal model ID
+     * @param customMap - Per-agent override from AgentConfig.modelIdMap
+     * @returns The translated model ID (or original if no mapping exists)
+     */
+    translate(agentId: string, internalModelId: string, customMap?: Record<string, string>): string;
+    /** Get all available mappings for an agent (defaults + custom overlay). */
+    getMappings(agentId: string, customMap?: Record<string, string>): Record<string, string>;
+}

package/dist/types/runtime/infra/model-id-translator.test.d.ts

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

package/dist/types/runtime/infra/skill-injector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Skill Injector — shares qlogicagent skills with external ACP agents.
+ *
+ * Two injection methods:
+ *
+ * 1. **Native skill directory sync**: For agents that support a `skillsDirs`
+ *    convention (e.g. `.claude/skills/`), create symlinks or copies of
+ *    qlogicagent's optional skills into the agent's native directory.
+ *
+ * 2. **First-message prompt injection**: For agents without native skill
+ *    directory support, prepend skill instructions text to the first prompt.
+ */
+import type { AgentCapabilities } from "./acp-types.js";
+export declare class SkillInjector {
+    /**
+     * Synchronize skills to an agent's native skill directory.
+     * Creates symlinks where possible; falls back to file copy.
+     *
+     * @param targetDir - Agent's native skill directory (e.g. `<cwd>/.claude/skills/`)
+     * @param cwd - Project working directory (for project-level skills)
+     */
+    syncSkillsToDir(targetDir: string, cwd?: string): void;
+    /**
+     * Build a skill description block to prepend to the first message
+     * for agents that don't support native skill directories.
+     *
+     * @param cwd - Project working directory (for project-level skills)
+     * @returns Markdown text with skill instructions, or empty string if no skills.
+     */
+    buildPromptWithSkills(cwd?: string): string;
+    /**
+     * Determine the injection method for an agent.
+     *
+     * @param capabilities - Agent's discovered capabilities
+     * @returns "native" if agent has skillsDirs, "prompt" otherwise
+     */
+    getInjectionMethod(capabilities?: AgentCapabilities): "native" | "prompt";
+    /**
+     * Apply skills to an agent based on its capabilities.
+     *
+     * @param capabilities - Agent's discovered capabilities
+     * @param cwd - Project working directory
+     * @returns Skill prompt text (for "prompt" method) or empty string (for "native" method)
+     */
+    applySkills(capabilities?: AgentCapabilities, cwd?: string): string;
+    /**
+     * Collect all skill file paths from user-level and project-level dirs.
+     * Only `.md` files are treated as skills.
+     */
+    private collectSkillPaths;
+}

package/dist/types/runtime/infra/skill-injector.test.d.ts

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

package/dist/types/runtime/infra/worktree-backend.d.ts

@@ -36,6 +36,7 @@ interface WorktreeSession {
 export declare function getCurrentWorktreeSession(): WorktreeSession | null;
 /** Restore session on resume (CC restoreWorktreeSession parity). */
 export declare function restoreWorktreeSession(session: WorktreeSession | null): void;
+export declare function findGitRoot(cwd?: string): Promise<string | null>;
 /** Check whether tmux is available on the system. */
 export declare function isTmuxAvailable(): Promise<boolean>;
 /** Generate a tmux session name from repo path and branch (CC parity). */

package/dist/types/runtime/prompt/environment-context.d.ts

@@ -21,3 +21,9 @@ export type ShellType = "bash" | "powershell" | "zsh" | "cmd" | "fish" | "unknow
  * Memoized — computed once per session (environment doesn't change mid-session).
  */
 export declare function createEnvironmentContextSection(cwdOverride?: string): SystemPromptSection;
+/**
+ * Create a system prompt section that provides tool usage guidance.
+ * CC parity: matches claude-code's AgentTool prompt guidance patterns.
+ * Tells the LLM when to use specialized tools vs. primitives.
+ */
+export declare function createToolGuidanceSection(): SystemPromptSection;

package/dist/types/runtime/session/session-persistence.d.ts

@@ -7,7 +7,8 @@
  *   3. Session metadata (model, cwd, agent mode)
  *
  * Storage layout:
- *   ~/.qlogicagent/sessions/<session-id>/
+ *   <project>/.qlogicagent/sessions/<session-id>/   (when projectRoot provided)
+ *   ~/.qlogicagent/sessions/<session-id>/            (fallback)
  *     transcript.jsonl   — append-only message log
  *     state.json          — cost snapshot + metadata
  *
@@ -52,31 +53,31 @@ export interface SessionListEntry {
  * Append a message to the session transcript.
  * Creates the session directory if it doesn't exist.
  */
-export declare function appendMessage(sessionId: string, message: ChatMessage): Promise<void>;
+export declare function appendMessage(sessionId: string, message: ChatMessage, projectRoot?: string): Promise<void>;
 /**
  * Save session state (cost + metadata) atomically.
  */
-export declare function saveSessionState(sessionId: string, costSnapshot: SessionCostSnapshot, metadata: Partial<SessionMetadata>): Promise<void>;
+export declare function saveSessionState(sessionId: string, costSnapshot: SessionCostSnapshot, metadata: Partial<SessionMetadata>, projectRoot?: string): Promise<void>;
 /**
  * Load a persisted session for resume — CC loadConversationForResume parity.
  *
  * Returns null if the session doesn't exist or is corrupted.
  */
-export declare function loadSessionForResume(sessionId: string): Promise<PersistedSession | null>;
+export declare function loadSessionForResume(sessionId: string, projectRoot?: string): Promise<PersistedSession | null>;
 /**
  * List available sessions for resume — CC ResumeConversation picker.
  * Returns most-recent-first, up to `limit` entries.
  */
-export declare function listSessions(limit?: number): Promise<SessionListEntry[]>;
+export declare function listSessions(limit?: number, projectRoot?: string): Promise<SessionListEntry[]>;
 /**
  * Delete a session (cleanup).
  */
-export declare function deleteSession(sessionId: string): Promise<void>;
+export declare function deleteSession(sessionId: string, projectRoot?: string): Promise<void>;
 /**
  * Prune old sessions beyond MAX_SESSIONS limit.
  * Deletes oldest sessions first.
  */
-export declare function pruneOldSessions(): Promise<number>;
+export declare function pruneOldSessions(projectRoot?: string): Promise<number>;
 export interface TaskSummaryDeps {
     transport: import("../../llm/transport.js").LLMTransport;
     apiKey: string;
@@ -91,4 +92,4 @@ export declare function shouldGenerateTaskSummary(metadata: SessionMetadata): bo
  * Generate and persist a task summary for a long session.
  * Fire-and-forget — errors are swallowed.
  */
-export declare function maybeGenerateTaskSummary(sessionId: string, metadata: SessionMetadata, recentMessages: ChatMessage[], deps: TaskSummaryDeps): Promise<string | null>;
+export declare function maybeGenerateTaskSummary(sessionId: string, metadata: SessionMetadata, recentMessages: ChatMessage[], deps: TaskSummaryDeps, projectRoot?: string): Promise<string | null>;