qlogicagent 0.5.2 → 0.6.0

package/dist/types/runtime/infra/secure-storage.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Secure Storage — CC secureStorage parity.
+ *
+ * Platform-aware credential persistence abstraction:
+ *   - Interface: get/set/delete with typed data
+ *   - Implementation: file-based JSON with 0o600 permissions (CC plainTextStorage parity)
+ *   - macOS Keychain / Windows Credential Manager can be added as plugins
+ *
+ * Storage layout:
+ *   ~/.qlogicagent/.credentials.json  — API keys, OAuth tokens
+ *
+ * Reference: claude-code-haha/src/utils/secureStorage/
+ */
+export interface SecureStorageData {
+    /** Primary API key (user-set) */
+    apiKey?: string;
+    /** OAuth tokens (if using OAuth flow) */
+    oauth?: {
+        accessToken: string;
+        refreshToken: string;
+        expiresAt: number;
+    };
+    /** Arbitrary key-value pairs for extensibility */
+    [key: string]: unknown;
+}
+/**
+ * CC SecureStorage interface parity.
+ *
+ * Implementations may use OS keychain, encrypted file, or plain-text file.
+ * Callers should not assume any specific storage backend.
+ */
+export interface SecureStorage {
+    readonly name: string;
+    get(): Promise<SecureStorageData | null>;
+    set(data: SecureStorageData): Promise<{
+        success: boolean;
+        warning?: string;
+    }>;
+    delete(): Promise<boolean>;
+}
+/**
+ * File-based secure storage with restrictive permissions.
+ *
+ * On Unix: file created with 0o600 (owner-only read/write).
+ * On Windows: ACLs are not set (relies on user profile permissions).
+ *
+ * This matches CC's plainTextStorage.ts behavior — it's the default
+ * on Linux/Windows, and the fallback on macOS.
+ */
+export declare class FileSecureStorage implements SecureStorage {
+    readonly name = "file";
+    get(): Promise<SecureStorageData | null>;
+    set(data: SecureStorageData): Promise<{
+        success: boolean;
+        warning?: string;
+    }>;
+    delete(): Promise<boolean>;
+}
+/**
+ * Get the platform-appropriate secure storage instance.
+ *
+ * Currently returns FileSecureStorage on all platforms.
+ * macOS Keychain integration can be added by checking platform
+ * and returning a KeychainSecureStorage wrapper.
+ */
+export declare function getSecureStorage(): SecureStorage;
+/**
+ * Save an API key to secure storage.
+ */
+export declare function saveApiKey(apiKey: string): Promise<{
+    success: boolean;
+    warning?: string;
+}>;
+/**
+ * Load the stored API key (returns null if none saved).
+ */
+export declare function loadApiKey(): Promise<string | null>;
+/**
+ * Delete the stored API key.
+ */
+export declare function deleteApiKey(): Promise<boolean>;

package/dist/types/runtime/infra/task-runtime.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Task Runtime — CC framework.ts parity.
+ *
+ * Manages task lifecycle: creation, state updates, completion, cleanup.
+ * All task types (local_bash, local_agent, dream, etc.) use this framework.
+ *
+ * CC equivalent: src/utils/task/framework.ts + src/Task.ts
+ *
+ * Architecture note: CC uses React-style setAppState(prev => next). We use
+ * a simple Map-based store since we're in a subprocess (no React).
+ */
+import type { TaskState, TaskType, TaskLifecycle, PermissionRole, IsolationMode, LocalAgentTaskState, LocalBashTaskState } from "../../orchestration/subagent/task-types.js";
+import type { HookRegistry } from "../../contracts/hooks.js";
+/** Polling interval for running tasks (ms) */
+export declare const POLL_INTERVAL_MS = 1000;
+/** Display duration for killed tasks before eviction (ms) */
+export declare const STOPPED_DISPLAY_MS = 3000;
+/** Grace period for terminal tasks before eviction (ms) */
+export declare const PANEL_GRACE_MS = 30000;
+export declare function generateTaskId(type: TaskType): string;
+/**
+ * In-memory task store — replaces CC's AppState.tasks.
+ *
+ * Thread-safe for single-process use. All mutations go through
+ * updateTaskState / registerTask for consistency.
+ */
+export declare class TaskStore {
+    private tasks;
+    private listeners;
+    private hooks;
+    private sessionId;
+    /** Attach a hook registry to fire task.created / task.completed hooks. */
+    setHooks(hooks: HookRegistry, sessionId: string): void;
+    /**
+     * Register a listener for task state changes.
+     * @returns Unregister function
+     */
+    onTaskChange(listener: (taskId: string, task: TaskState | null) => void): () => void;
+    private notify;
+    /**
+     * Register a new task.
+     */
+    registerTask(task: TaskState): void;
+    /**
+     * Update a task's state via an updater function.
+     * CC equivalent: updateTaskState()
+     */
+    updateTask<T extends TaskState>(taskId: string, updater: (task: T) => T): void;
+    /**
+     * Get a task by ID.
+     */
+    getTask(taskId: string): TaskState | undefined;
+    /**
+     * Get all running tasks.
+     */
+    getRunningTasks(): TaskState[];
+    /**
+     * Get all tasks.
+     */
+    getAllTasks(): TaskState[];
+    /**
+     * Evict a terminal task from the store.
+     */
+    evictTask(taskId: string): void;
+    /**
+     * Evict all terminal tasks that have passed their grace period.
+     */
+    evictStaleTasks(graceMs?: number): void;
+}
+export declare function isTerminalLifecycle(lifecycle: TaskLifecycle): boolean;
+/**
+ * Transition a task to a terminal state.
+ */
+export declare function completeTask(store: TaskStore, taskId: string): void;
+export declare function failTask(store: TaskStore, taskId: string, error?: string): void;
+export declare function cancelTask(store: TaskStore, taskId: string): void;
+/**
+ * Create and register a local agent task.
+ */
+export declare function createLocalAgentTask(store: TaskStore, opts: {
+    agentName: string;
+    systemPrompt: string;
+    allowedTools?: string[];
+    parentTaskId?: string;
+    tokenBudget?: number;
+    maxTurns?: number;
+    permissionRole?: PermissionRole;
+    isolation?: IsolationMode;
+    worktreeBranch?: string;
+}): LocalAgentTaskState;
+/**
+ * Create and register a local bash task.
+ */
+export declare function createLocalBashTask(store: TaskStore, opts: {
+    command: string;
+    cwd: string;
+    parentTaskId?: string;
+    label?: string;
+}): LocalBashTaskState;
+/**
+ * Build a task notification message in CC's XML format.
+ * This is injected into the conversation as context for the model.
+ */
+export declare function buildTaskNotification(task: TaskState, summary: string): string;
+/**
+ * Get the global task store singleton.
+ */
+export declare function getTaskStore(): TaskStore;

package/dist/types/runtime/infra/token-budget.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Sub-agent Token Budget Enforcer — CC-aligned budget limits.
+ *
+ * Prevents sub-agents from consuming infinite tokens by:
+ *   1. Per-task token budget (from TaskStateBase.tokenBudget)
+ *   2. Session-level aggregate budget (all tasks combined)
+ *   3. Budget continuation messages (CC tokenBudget.ts pattern)
+ *   4. Graceful degradation (warn → force-stop, never hard-crash)
+ *
+ * CC reference: utils/tokenBudget.ts, main.tsx --max-budget-usd / --task-budget
+ *
+ * Key difference from CC: We track prompt + completion tokens (not USD).
+ * CC has no explicit per-sub-agent budget; they rely on session-level maxBudgetUsd.
+ * We add per-task enforcement to prevent a single sub-agent from exhausting the budget.
+ */
+import type { TokenUsage } from "../../agent/types.js";
+export interface BudgetConfig {
+    /** Per-task token budget (prompt + completion). 0 = unlimited. */
+    taskBudgetTokens: number;
+    /** Session-level token budget across all tasks. 0 = unlimited. */
+    sessionBudgetTokens: number;
+    /** Warning threshold as percentage (0-100). Default: 80. */
+    warningThresholdPct: number;
+}
+export interface TaskBudgetState {
+    taskId: string;
+    /** Token budget for this task. 0 = unlimited. */
+    budgetTokens: number;
+    /** Accumulated token usage for this task. */
+    usage: TokenUsage;
+    /** Whether a warning has been issued for this task. */
+    warned: boolean;
+    /** Whether this task has been force-stopped due to budget. */
+    stopped: boolean;
+}
+export interface SessionBudgetState {
+    /** Session-level budget. 0 = unlimited. */
+    budgetTokens: number;
+    /** Aggregate usage across ALL tasks in this session. */
+    totalUsage: TokenUsage;
+    /** Per-task states keyed by taskId. */
+    tasks: Map<string, TaskBudgetState>;
+}
+export type BudgetCheckResult = {
+    status: "ok";
+} | {
+    status: "warning";
+    message: string;
+    usagePct: number;
+} | {
+    status: "exceeded";
+    message: string;
+    usagePct: number;
+};
+/**
+ * Parse a token budget from user text input.
+ * CC reference: parseTokenBudget()
+ *
+ * Supports:
+ *   - Shorthand start: "+500k", "+1.5m"
+ *   - Shorthand end:   "keep working +1m."
+ *   - Verbose:         "use 500k tokens", "spend 1.5M tokens"
+ */
+export declare function parseTokenBudget(text: string): number | null;
+/**
+ * Generate a budget continuation message (CC getBudgetContinuationMessage pattern).
+ * Appended to the assistant context when approaching budget limits.
+ */
+export declare function getBudgetContinuationMessage(usagePct: number, currentTokens: number, budgetTokens: number): string;
+export declare function createSessionBudgetState(config?: Partial<BudgetConfig>): SessionBudgetState;
+export declare function registerTaskBudget(session: SessionBudgetState, taskId: string, budgetTokens: number): TaskBudgetState;
+/**
+ * Record token usage for a task and aggregate into session.
+ */
+export declare function recordTaskUsage(session: SessionBudgetState, taskId: string, usage: TokenUsage): void;
+/**
+ * Check whether a task is within its token budget.
+ */
+export declare function checkTaskBudget(session: SessionBudgetState, taskId: string, config?: Partial<BudgetConfig>): BudgetCheckResult;
+/**
+ * Get a summary of all task budgets in a session.
+ */
+export declare function getSessionBudgetSummary(session: SessionBudgetState): {
+    sessionUsed: number;
+    sessionBudget: number;
+    tasks: Array<{
+        taskId: string;
+        used: number;
+        budget: number;
+        stopped: boolean;
+    }>;
+};

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

@@ -0,0 +1,85 @@
+/**
+ * Worktree Backend — git command implementation for WorktreeToolDeps.
+ *
+ * CC reference: claude-code-haha/src/utils/worktree.ts
+ *
+ * Implements the host-provided git worktree backend:
+ *   - enterWorktree(): git worktree add -B <branch> <path> HEAD
+ *   - exitWorktree(): git worktree remove / keep
+ *   - listWorktrees(): git worktree list --porcelain
+ *   - isInWorktree(): check if cwd is inside a worktree
+ *   - currentWorktree(): get current worktree info
+ *
+ * State management:
+ *   - Tracks current worktree session in memory
+ *   - CWD switching via process.chdir()
+ *   - Safety checks: uncommitted changes, unpushed commits
+ *
+ * Security: validateWorktreeSlug() prevents path traversal.
+ */
+import type { WorktreeToolDeps } from "../../skills/tools/worktree-tool.js";
+interface WorktreeSession {
+    originalCwd: string;
+    worktreePath: string;
+    worktreeName: string;
+    worktreeBranch: string;
+    /** tmux session name (CC parity). */
+    tmuxSessionName?: string;
+    /** Whether worktree was created via a user hook (CC hookBased). */
+    hookBased?: boolean;
+    /** Creation duration in ms (unset on resume). */
+    creationDurationMs?: number;
+    /** True if sparse-checkout was applied. */
+    usedSparsePaths?: boolean;
+}
+/** Get the current worktree session (CC getCurrentWorktreeSession parity). */
+export declare function getCurrentWorktreeSession(): WorktreeSession | null;
+/** Restore session on resume (CC restoreWorktreeSession parity). */
+export declare function restoreWorktreeSession(session: WorktreeSession | null): void;
+/** 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). */
+export declare function generateTmuxSessionName(repoPath: string, branch: string): string;
+/**
+ * Create a tmux session for a worktree (CC createTmuxSessionForWorktree parity).
+ * Returns the session name, or null if tmux is not available.
+ */
+export declare function createTmuxSession(worktreePath: string, sessionName: string): Promise<string | null>;
+/** Kill a tmux session (CC killTmuxSession parity). */
+export declare function killTmuxSession(sessionName: string): Promise<boolean>;
+/**
+ * Create a lightweight worktree for a sub-agent without modifying the
+ * global session. CC reference: createAgentWorktree().
+ */
+export declare function createAgentWorktree(gitRoot: string, slug: string, log?: {
+    info(msg: string): void;
+    warn(msg: string): void;
+}): Promise<{
+    worktreePath: string;
+    branch: string;
+} | null>;
+/** Remove an agent worktree (CC removeAgentWorktree parity). */
+export declare function removeAgentWorktree(gitRoot: string, worktreePath: string, branch: string, log?: {
+    info(msg: string): void;
+    warn(msg: string): void;
+}): Promise<boolean>;
+/**
+ * Clean up stale agent worktrees older than maxAgeDays (CC cleanupStaleAgentWorktrees parity).
+ */
+export declare function cleanupStaleAgentWorktrees(gitRoot: string, maxAgeDays?: number, log?: {
+    info(msg: string): void;
+    warn(msg: string): void;
+}): Promise<number>;
+export interface WorktreeBackendOptions {
+    /** Logger for worktree operations */
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+    /** Directories to symlink from main repo (CC parity: node_modules, etc.) */
+    symlinkDirs?: string[];
+    /** Sparse-checkout paths (CC settings.worktree.sparsePaths parity). */
+    sparsePaths?: string[];
+}
+export declare function createWorktreeBackend(opts: WorktreeBackendOptions): WorktreeToolDeps;
+export {};

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

@@ -0,0 +1,23 @@
+/**
+ * Environment Context — CC environment-aware system prompt parity.
+ *
+ * Injects OS, shell, CWD, and platform info into the system prompt
+ * so the agent can generate platform-appropriate commands.
+ *
+ * CC reference: ShellSnapshot.ts (shell type detection),
+ *               shellCompletion.ts (platform-aware command generation)
+ *
+ * This is a system prompt section that provides:
+ *   - OS name + version
+ *   - Shell type (bash/powershell/zsh)
+ *   - Current working directory
+ *   - Node.js version
+ *   - Available package managers
+ */
+import { type SystemPromptSection } from "./system-prompt-sections.js";
+export type ShellType = "bash" | "powershell" | "zsh" | "cmd" | "fish" | "unknown";
+/**
+ * Create a system prompt section that provides environment context.
+ * Memoized — computed once per session (environment doesn't change mid-session).
+ */
+export declare function createEnvironmentContextSection(): SystemPromptSection;

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

@@ -0,0 +1,3 @@
+export { assembleSystemPrompt, clearSystemPromptSections, systemPromptSection, type SystemPromptSection, } from "./system-prompt-sections.js";
+export { getInstructions, buildInstructionsPrompt, resetInstructionCache, } from "./instruction-loader.js";
+export { createEnvironmentContextSection } from "./environment-context.js";

package/dist/types/runtime/prompt/instruction-loader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Instruction Loader — CC claudemd.ts parity (adapted for qlogicagent).
+ *
+ * Discovers and loads instruction files following CC's load order:
+ *   1. User instructions (~/.qlogicagent/INSTRUCTIONS.md)
+ *   2. Project instructions (INSTRUCTIONS.md, .qlogicagent/INSTRUCTIONS.md,
+ *      .qlogicagent/rules/*.md — walkup from cwd to git root)
+ *   3. Local instructions (INSTRUCTIONS.local.md — private, not checked in)
+ *
+ * Features ported from CC:
+ *   - Walkup discovery (cwd → root)
+ *   - @include directive support (text files only)
+ *   - Frontmatter globs for conditional rules
+ *   - HTML comment stripping
+ *   - Memoized loading with cache invalidation
+ *   - TEXT_FILE_EXTENSIONS whitelist
+ *   - MAX_INCLUDE_DEPTH circular reference prevention
+ *
+ * Reference: claude-code src/utils/claudemd.ts
+ */
+import type { HookRegistry } from "../../contracts/hooks.js";
+export type InstructionType = "User" | "Project" | "Local";
+export interface InstructionFileInfo {
+    path: string;
+    type: InstructionType;
+    content: string;
+    /** Path of the file that @included this one */
+    parent?: string;
+    /** Glob patterns from frontmatter — file only applies when target path matches */
+    globs?: string[];
+}
+/**
+ * Load all instruction files following CC's discovery order.
+ *
+ * Discovery order (priority: last loaded = highest):
+ *   1. User: ~/.qlogicagent/INSTRUCTIONS.md, ~/.qlogicagent/rules/*.md
+ *   2. Project: Walk from git root → cwd, each dir:
+ *      - INSTRUCTIONS.md
+ *      - .qlogicagent/INSTRUCTIONS.md
+ *      - .qlogicagent/rules/*.md (unconditional)
+ *   3. Local: INSTRUCTIONS.local.md (per dir, walkup)
+ *
+ * @param cwd - Starting directory for walkup discovery
+ * @param hooks - Optional hook registry for instructions.loaded event
+ */
+export declare function loadInstructions(cwd: string, hooks?: HookRegistry): Promise<InstructionFileInfo[]>;
+/**
+ * Build the instructions prompt string from loaded files.
+ * CC parity: getClaudeMds()
+ */
+export declare function buildInstructionsPrompt(files: InstructionFileInfo[]): string;
+/**
+ * Get conditional rules that match a target file path.
+ * CC parity: getManagedAndUserConditionalRules() + getMemoryFilesForNestedDirectory()
+ */
+export declare function getConditionalRules(cwd: string, targetPath: string): Promise<InstructionFileInfo[]>;
+/**
+ * Load instructions with memoization.
+ * CC parity: getMemoryFiles() with memoize.
+ * Returns cached result if cwd hasn't changed.
+ */
+export declare function getInstructions(cwd: string, hooks?: HookRegistry): Promise<InstructionFileInfo[]>;
+/** Clear the instruction cache. Called after file changes or compaction. */
+export declare function resetInstructionCache(): void;

package/dist/types/runtime/prompt/system-prompt-sections.d.ts

@@ -0,0 +1,63 @@
+/**
+ * System Prompt Sections — CC systemPromptSections.ts parity.
+ *
+ * Provides a section-based system prompt assembly mechanism:
+ *   - Memoized sections (computed once, cached until clear)
+ *   - Volatile sections (recompute every turn, cache-breaking)
+ *   - User-provided appendSystemPrompt / customSystemPrompt
+ *   - Clear on session reset / compact
+ *
+ * CC reference: src/constants/systemPromptSections.ts
+ */
+type ComputeFn = () => string | null | Promise<string | null>;
+export interface SystemPromptSection {
+    name: string;
+    compute: ComputeFn;
+    /** If true, recompute every turn (breaks prompt cache). CC: cacheBreak. */
+    cacheBreak: boolean;
+}
+/**
+ * Create a memoized system prompt section.
+ * Computed once, cached until clearSystemPromptSections() is called.
+ */
+export declare function systemPromptSection(name: string, compute: ComputeFn): SystemPromptSection;
+/**
+ * Create a volatile system prompt section that recomputes every turn.
+ * WARNING: This WILL break prompt cache when the value changes.
+ * Use sparingly — only for time-sensitive or frequently changing context.
+ *
+ * @param _reason - Why this section must be volatile (documentation only, CC parity).
+ */
+export declare function volatileSystemPromptSection(name: string, compute: ComputeFn, _reason?: string): SystemPromptSection;
+/**
+ * Resolve all system prompt sections, returning non-null prompt strings.
+ * Memoized sections are cached; volatile sections are always recomputed.
+ */
+export declare function resolveSystemPromptSections(sections: SystemPromptSection[]): Promise<string[]>;
+/**
+ * Clear all section caches. Called on session reset, /clear, or /compact.
+ */
+export declare function clearSystemPromptSections(): void;
+export interface SystemPromptAssemblyOptions {
+    /** Base system prompt (from Gateway config) */
+    basePrompt?: string;
+    /** Prepended instruction block (from INSTRUCTIONS.md files) */
+    instructionBlock?: string;
+    /** User-provided custom system prompt (replaces base) */
+    customSystemPrompt?: string;
+    /** User-provided append text (appended after all sections) */
+    appendSystemPrompt?: string;
+    /** Dynamic sections to resolve */
+    sections?: SystemPromptSection[];
+}
+/**
+ * Assemble the final system prompt from all sources.
+ *
+ * Order:
+ *   1. Instruction block (INSTRUCTIONS.md files)
+ *   2. Custom system prompt (replaces base) OR base prompt
+ *   3. Resolved sections
+ *   4. Append system prompt (user-provided suffix)
+ */
+export declare function assembleSystemPrompt(opts: SystemPromptAssemblyOptions): Promise<string>;
+export {};

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

@@ -0,0 +1,2 @@
+export { SessionState, type SessionCostSnapshot } from "./session-state.js";
+export { appendMessage, saveSessionState, loadSessionForResume, listSessions, deleteSession, pruneOldSessions, shouldGenerateTaskSummary, maybeGenerateTaskSummary, type SessionMetadata, type PersistedSession, type SessionListEntry, type TaskSummaryDeps, } from "./session-persistence.js";

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

@@ -0,0 +1,90 @@
+/**
+ * Session Memory — CC SessionMemory background extraction parity.
+ *
+ * Automatically extracts key insights from the conversation and saves
+ * them to session memory files. Runs as a forked sub-agent with restricted
+ * tool access after each turn when extraction thresholds are met.
+ *
+ * CC reference:
+ *   - src/services/SessionMemory/sessionMemory.ts
+ *   - src/services/SessionMemory/extractMemories.ts
+ *
+ * Extraction process:
+ *   1. Check thresholds (tokens + tool calls since last extraction)
+ *   2. Fork a sub-agent with restricted tools (read-only + memory write)
+ *   3. Sub-agent reviews conversation, extracts key facts/decisions
+ *   4. Sub-agent writes to session-memory.md file
+ *   5. Reset threshold counters
+ *
+ * Tool restrictions for extractor:
+ *   ✅ read, search, grep, glob (read-only fs)
+ *   ✅ memory_write (to session-memory path only)
+ *   ❌ Everything else (no file edits, no bash, no network)
+ */
+import type { ChatMessage, ToolDefinition, ToolInvoker, AgentLogger, HookRegistry } from "../../agent/types.js";
+import type { LLMTransport } from "../../llm/transport.js";
+import type { SessionState } from "./session-state.js";
+/** Tool permission check function (mirrors execution/forked-agent CanUseToolFn). */
+export type CanUseToolFn = (toolName: string, input: Record<string, unknown>) => {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/** Forked agent runner signature (injected by CLI layer). */
+export type ForkedAgentRunner = (params: {
+    promptMessages: ChatMessage[];
+    systemPrompt?: string;
+    tools: ToolDefinition[];
+    canUseTool?: CanUseToolFn;
+    transport: LLMTransport;
+    toolInvoker: ToolInvoker;
+    apiKey: string;
+    model: string;
+    log: AgentLogger;
+    hooks?: HookRegistry;
+    forkLabel: string;
+    maxTurns?: number;
+    parentSignal?: AbortSignal;
+    skipTranscript?: boolean;
+}) => Promise<{
+    ok: boolean;
+    content?: string;
+    error?: string;
+    durationMs: number;
+    totalUsage: {
+        prompt: number;
+        completion: number;
+    };
+}>;
+export interface SessionMemoryDeps {
+    /** Session state (for threshold tracking) */
+    sessionState: SessionState;
+    /** LLM transport for the extractor agent */
+    transport: LLMTransport;
+    /** Tool invoker */
+    toolInvoker: ToolInvoker;
+    /** Available tools (will be filtered for extraction) */
+    tools: ToolDefinition[];
+    /** API key */
+    apiKey: string;
+    /** Model for extraction (can use a cheaper/faster model) */
+    model: string;
+    /** Logger */
+    log: AgentLogger;
+    /** Hook registry */
+    hooks?: HookRegistry;
+    /** Path where session memory should be written */
+    memoryFilePath: string;
+    /** Parent abort signal */
+    parentSignal?: AbortSignal;
+    /** Forked agent runner (injected by CLI layer, decoupled from execution/) */
+    runForkedAgent: ForkedAgentRunner;
+}
+/**
+ * Check if memory extraction should run and execute if thresholds are met.
+ *
+ * Call this at the end of each turn (after turn.completed hook).
+ * It's a no-op if thresholds aren't met.
+ */
+export declare function maybeExtractSessionMemory(deps: SessionMemoryDeps, conversationMessages: ChatMessage[]): Promise<boolean>;