qlogicagent 0.5.2 → 0.6.0

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;

package/dist/types/runtime/execution/tool-result-storage.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Tool result storage — CC toolResultStorage.ts aligned.
+ *
+ * Two-layer mechanism to manage tool result sizes:
+ *   Level 1 (per-tool): At execution time, results > DEFAULT_MAX_RESULT_SIZE_CHARS
+ *           are persisted to disk and replaced with preview references.
+ *   Level 2 (per-message budget): Before API call, aggregate tool results in
+ *           each group (consecutive tool messages between assistant messages)
+ *           are checked against MAX_TOOL_RESULTS_PER_MESSAGE_CHARS. The largest
+ *           fresh results are persisted until under budget.
+ *
+ * ContentReplacementState tracks decisions across turns for prompt cache
+ * stability — once a tool result's fate is decided (replaced or not), the
+ * decision is frozen for the remainder of the conversation.
+ *
+ * CC reference: src/utils/toolResultStorage.ts
+ * Zero imports from express/pg/ioredis/ws.
+ */
+export declare const TOOL_RESULTS_SUBDIR = "tool-results";
+/** XML tag wrapping persisted output previews (CC PERSISTED_OUTPUT_TAG) */
+export declare const PERSISTED_OUTPUT_TAG = "<persisted-output>";
+export declare const PERSISTED_OUTPUT_CLOSING_TAG = "</persisted-output>";
+/** Marker injected by microcompact when clearing old tool results (CC parity) */
+export declare const TOOL_RESULT_CLEARED_MESSAGE = "[Old tool result content cleared]";
+/**
+ * Per-conversation-thread state for the aggregate tool result budget.
+ * State must be stable to preserve prompt cache:
+ *   - seenIds: tool_call_ids that have passed through the budget check (replaced
+ *     or not). Once seen, a result's fate is frozen for the conversation.
+ *   - replacements: subset of seenIds that were persisted to disk and
+ *     replaced with previews, mapped to the exact preview string.
+ *     Re-application is a Map lookup — no file I/O, byte-identical.
+ *
+ * CC reference: ContentReplacementState
+ */
+export type ContentReplacementState = {
+    seenIds: Set<string>;
+    replacements: Map<string, string>;
+};
+export type PersistedToolResult = {
+    filepath: string;
+    originalSize: number;
+    preview: string;
+    hasMore: boolean;
+};
+export declare function createContentReplacementState(): ContentReplacementState;
+export declare function generatePreview(content: string, maxBytes: number): {
+    preview: string;
+    hasMore: boolean;
+};
+export declare function persistToolResult(content: string, toolCallId: string, sessionId: string): Promise<PersistedToolResult | null>;
+/**
+ * Build a reference message for large tool results (CC buildLargeToolResultMessage parity).
+ */
+export declare function buildLargeToolResultMessage(result: PersistedToolResult): string;
+/**
+ * If content exceeds threshold, persist to disk and return a preview reference.
+ * Falls back to hard truncation if persistence fails.
+ * Called at tool execution time in streaming-tool-executor.ts.
+ */
+export declare function maybePersistLargeToolResult(content: string, toolCallId: string, sessionId: string, threshold?: number): Promise<string>;
+interface MessageLike {
+    role: string;
+    content?: string | unknown;
+    tool_call_id?: string;
+}
+/**
+ * Enforce per-message aggregate budget on tool results.
+ * CC enforceToolResultBudget parity.
+ *
+ * For each group of tool messages whose content together exceeds
+ * the per-message limit, the largest FRESH (never-before-seen) results
+ * are persisted to disk and replaced with previews.
+ *
+ * State is tracked by tool_call_id: once a result is seen, its fate is
+ * frozen. Previously-replaced results get the same replacement re-applied
+ * (no I/O, byte-identical). Previously-unreplaced results are never
+ * replaced later (would break prompt cache).
+ *
+ * @param state — MUTATED in place (seenIds and replacements updated)
+ * @returns messages with replacements applied + count of new replacements
+ */
+export declare function enforceToolResultBudget(messages: MessageLike[], state: ContentReplacementState, sessionId: string, limit?: number): Promise<{
+    messages: MessageLike[];
+    newlyReplacedCount: number;
+}>;
+export {};

package/dist/types/runtime/hooks/context-compression.d.ts

@@ -0,0 +1,61 @@
+import { ContextEngineRegistry, type CompressibleMessage, type CompressionResult, type CompressionStrategy, type AsyncCompressionStrategy, type SummarizeFn } from "../../orchestration/index.js";
+import type { HookRegistry } from "./hook-registry.js";
+import type { RuntimeLogger } from "./hook-registry.js";
+import type { LLMTransport } from "../../llm/transport.js";
+/** Rough token estimate: ~4 chars per token for mixed CJK/English. */
+export declare function estimateTokens(msg: CompressibleMessage): number;
+/** Estimate total tokens for a message array. */
+export declare function estimateTotalTokens(messages: CompressibleMessage[]): number;
+export declare function getCompressionMetrics(): import("../../orchestration/index.js").CompressionMetricsSnapshot;
+export declare function getContextEngineRegistry(): ContextEngineRegistry;
+/**
+ * Create a summarization callback using an injected LLM transport.
+ * For CLI mode: uses the same transport that powers the agent loop.
+ * Falls back to non-LLM summary when transport/apiKey not available.
+ */
+export declare function createSummarizeFn(log: RuntimeLogger, opts?: {
+    transport?: LLMTransport;
+    apiKey?: string;
+    model?: string;
+}): SummarizeFn;
+/** Phase 1: sync-only pipeline (ToolResultTrim + MicroCompact + SlidingWindow) */
+export declare function createSyncPipeline(): CompressionStrategy;
+/** Phase 2+3: async pipeline with LLM summarization + cache awareness */
+export declare function createAsyncPipeline(summarize: SummarizeFn, opts?: {
+    onCacheInvalidated?: (info: {
+        droppedCount: number;
+        strategy: string;
+    }) => void;
+}): AsyncCompressionStrategy;
+/** Phase 2.3: incremental compaction pipeline (for partial compact) */
+export declare function createIncrementalPipeline(summarize: SummarizeFn, opts?: {
+    preserveRecentCount?: number;
+    onCacheInvalidated?: (info: {
+        droppedCount: number;
+        strategy: string;
+    }) => void;
+}): AsyncCompressionStrategy;
+export interface CompressOptions {
+    budget?: number;
+    model?: string;
+    pipeline?: CompressionStrategy;
+    allowLlm?: boolean;
+    summarize?: SummarizeFn;
+    sessionId?: string;
+}
+/** Synchronous compression (Phase 1 only). */
+export declare function compressMessages(messages: CompressibleMessage[], opts?: CompressOptions): CompressionResult;
+/** Async compression (Phase 2+) — supports LLM summarization. */
+export declare function compressMessagesAsync(messages: CompressibleMessage[], opts: CompressOptions & {
+    summarize: SummarizeFn;
+}): Promise<CompressionResult>;
+export declare function registerDefaultContextEngine(log: RuntimeLogger, opts?: {
+    transport?: LLMTransport;
+    apiKey?: string;
+    model?: string;
+}): void;
+export declare function registerContextCompressionHook(hooks: HookRegistry, log: RuntimeLogger, opts?: {
+    transport?: LLMTransport;
+    apiKey?: string;
+    model?: string;
+}): void;

package/dist/types/runtime/hooks/hook-registry.d.ts

@@ -0,0 +1,12 @@
+import type { HookPoint, HookContextMap, HookResult, HookHandler, HookRegistration, HookRegistry } from "../../contracts/hooks.js";
+export type { HookPoint, HookContextMap, HookResult, HookHandler, HookRegistration, HookRegistry };
+/** Minimal logger interface — compatible with both pino and AgentLogger. */
+export interface RuntimeLogger {
+    info(msg: string): void;
+    info(obj: Record<string, unknown>, msg: string): void;
+    warn(msg: string): void;
+    warn(obj: Record<string, unknown>, msg: string): void;
+    debug(msg: string): void;
+    debug(obj: Record<string, unknown>, msg: string): void;
+}
+export declare function createHookRegistry(log: RuntimeLogger): HookRegistry;

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

@@ -0,0 +1,3 @@
+export { createHookRegistry, type RuntimeLogger } from "./hook-registry.js";
+export { registerMemoryHooks, createMemoryPrefetchState, type MemoryHooksDeps, type MemoryPrefetchState, MEMORY_PREFETCH_CONFIG, } from "./memory-hooks.js";
+export { registerContextCompressionHook, compressMessages } from "./context-compression.js";

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

@@ -0,0 +1,49 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { MemoryProvider } from "qlogicagent-runtime-contracts";
+export declare const MEMORY_PREFETCH_CONFIG: {
+    /** Max bytes of memory content to inject per session (CC: 60KB) */
+    readonly MAX_SESSION_BYTES: number;
+    /** Max results per recall query */
+    readonly LIMIT_PER_RECALL: 10;
+    /** Max entries in surfaced-path LRU set */
+    readonly MAX_SURFACED_ENTRIES: 100;
+};
+export interface MemoryHooksDeps {
+    /** QMemory adapter (MemoryProvider with search/health). */
+    memoryProvider?: MemoryProvider;
+    /** User ID for memory lookups. */
+    userId: string;
+    /** Logger. */
+    log: {
+        debug(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+/** Session-scoped state for dedup and byte budget (CC parity). */
+export interface MemoryPrefetchState {
+    /** Paths already surfaced this session (CC readFileState LRU parity). */
+    surfacedPaths: Set<string>;
+    /** Total bytes injected this session. */
+    sessionBytes: number;
+}
+/**
+ * Create a fresh memory prefetch state (once per session).
+ */
+export declare function createMemoryPrefetchState(): MemoryPrefetchState;
+/**
+ * Register memory lifecycle hooks on the HookRegistry.
+ *
+ * Hook points wired:
+ *   - memory.before_recall: prefetch context from qmemory (query-based)
+ *   - memory.after_recall: log recall results
+ *
+ * CC parity additions:
+ *   - LRU dedup via surfacedPaths (filterDuplicateMemoryAttachments)
+ *   - Session byte limit (MAX_SESSION_BYTES = 60KB)
+ *   - Async prefetch (non-blocking promise, abort-aware)
+ *
+ * Returns a cleanup function to unregister.
+ */
+export declare function registerMemoryHooks(hooks: HookRegistry, deps: MemoryHooksDeps, 
+/** Shared state — pass the same object across hook re-registrations in a session. */
+prefetchState?: MemoryPrefetchState): () => void;

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

@@ -0,0 +1,5 @@
+export * from "./session/index.js";
+export * from "./hooks/index.js";
+export * from "./execution/index.js";
+export * from "./prompt/index.js";
+export * from "./infra/index.js";

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

@@ -0,0 +1,57 @@
+/**
+ * Agent Paths — Centralized dot-directory name and path helpers.
+ *
+ * All filesystem paths under `~/.qlogicagent/` (user-level) or
+ * `<project>/.qlogicagent/` (project-level) must go through these
+ * helpers so the dot-dir name is defined in exactly one place.
+ */
+/** Dot-directory name used for both user-level and project-level storage. */
+export declare const AGENT_DOT_DIR = ".qlogicagent";
+/** `~/.qlogicagent/` */
+export declare function getUserAgentHome(): string;
+/** `~/.qlogicagent/sessions/` */
+export declare function getUserSessionsRoot(): string;
+/** `~/.qlogicagent/sessions/{sessionId}` */
+export declare function getUserSessionDir(sessionId: string): string;
+/** `~/.qlogicagent/.credentials.json` */
+export declare function getUserCredentialsPath(): string;
+/** `~/.qlogicagent/plugins/` */
+export declare function getUserPluginsDir(): string;
+/** `~/.qlogicagent/skills/` */
+export declare function getUserSkillsDir(): string;
+/** `~/.qlogicagent/settings.json` */
+export declare function getUserSettingsPath(): string;
+/** `~/.qlogicagent/cache/` */
+export declare function getUserCacheDir(): string;
+/** `~/.qlogicagent/debug-logs/` */
+export declare function getUserDebugLogsDir(): string;
+/** `~/.qlogicagent/checkpoints/` or `~/.qlogicagent/checkpoints/{sessionId}` */
+export declare function getUserCheckpointsDir(sessionId?: string): string;
+/** `~/.qlogicagent/plugin-cache/` */
+export declare function getUserPluginCacheDir(): string;
+/** `~/.qlogicagent/mcp.json` */
+export declare function getUserMcpConfigPath(): string;
+/** `~/.qlogicagent/marketplace.json` */
+export declare function getUserMarketplaceConfigPath(): string;
+/** `~/.qlogicagent/workflows/` */
+export declare function getUserWorkflowsDir(): string;
+/** `~/.qlogicagent/INSTRUCTIONS.md` */
+export declare function getUserInstructionsPath(): string;
+/** `~/.qlogicagent/rules/` */
+export declare function getUserRulesDir(): string;
+/** `<cwd>/.qlogicagent/` */
+export declare function getProjectAgentDir(cwd?: string): string;
+/** `<cwd>/.qlogicagent/workflows/` */
+export declare function getProjectWorkflowsDir(cwd?: string): string;
+/** `<cwd>/.qlogicagent/plugins/` */
+export declare function getProjectPluginsDir(cwd?: string): string;
+/** `<cwd>/.qlogicagent/skills/` */
+export declare function getProjectSkillsDir(cwd?: string): string;
+/** `<cwd>/.qlogicagent/settings.json` */
+export declare function getProjectSettingsPath(cwd?: string): string;
+/** `<cwd>/.qlogicagent/INSTRUCTIONS.md` */
+export declare function getProjectInstructionsPath(cwd?: string): string;
+/** `<cwd>/.qlogicagent/rules/` */
+export declare function getProjectRulesDir(cwd?: string): string;
+/** `<gitRoot>/.qlogicagent/hooks/` */
+export declare function getGitRootHooksDir(gitRoot: string): string;

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

@@ -0,0 +1,8 @@
+/**
+ * Local Checkpoint Backend — git-based shadow repo implementation.
+ *
+ * Creates and manages checkpoint snapshots in `~/.qlogicagent/checkpoints/<sessionId>/`
+ * using a shadow git repository independent of the user's project .git.
+ */
+import type { CheckpointToolDeps } from "../../skills/tools/checkpoint-tool.js";
+export declare function createLocalCheckpointBackend(projectRoot: string, sessionId: string): CheckpointToolDeps;

package/dist/types/runtime/infra/cleanup-registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cleanup Registry — CC cleanupRegistry.ts parity.
+ *
+ * Global registry for cleanup functions that should run during graceful shutdown.
+ * Separate from stop handling to avoid circular dependencies.
+ *
+ * Reference: claude-code src/utils/cleanupRegistry.ts
+ */
+/**
+ * Register a cleanup function to run during graceful shutdown.
+ * @param cleanupFn - Function to run during cleanup (can be sync or async)
+ * @returns Unregister function that removes the cleanup handler
+ */
+export declare function registerCleanup(cleanupFn: () => Promise<void>): () => void;
+/**
+ * Run all registered cleanup functions.
+ * Used internally by graceful shutdown path.
+ */
+export declare function runCleanupFunctions(): Promise<void>;
+/**
+ * Get count of registered cleanup handlers (for diagnostics).
+ */
+export declare function getCleanupCount(): number;

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

@@ -0,0 +1,36 @@
+/**
+ * Disk Storage Manager — unified atomic file I/O for agent self-managed storage.
+ *
+ * Provides:
+ * - Atomic write (tmp + rename) with dir auto-creation
+ * - JSON read/write helpers
+ * - MemoryStore disk persistence (auto-save on mutation)
+ */
+/**
+ * Write data atomically: write to a temp file in the same directory,
+ * then rename over the target. This prevents partial/corrupted reads.
+ */
+export declare function atomicWriteFile(filePath: string, data: string | Buffer): Promise<void>;
+/**
+ * Read a JSON file. Returns `undefined` if the file does not exist.
+ */
+export declare function readJsonFile<T = unknown>(filePath: string): Promise<T | undefined>;
+/**
+ * Write a JSON file atomically.
+ */
+export declare function writeJsonFile(filePath: string, data: unknown): Promise<void>;
+/** Path to user-level memory file: `~/.qlogicagent/memory.json` */
+export declare function getMemoryFilePath(): string;
+export interface PersistedMemory {
+    memory: string;
+    user: string;
+    /** ISO 8601 timestamp of last save. */
+    savedAt: string;
+}
+/** Load persisted memory from disk. Returns undefined if no file exists. */
+export declare function loadPersistedMemory(): Promise<PersistedMemory | undefined>;
+/** Save memory to disk atomically. */
+export declare function savePersistedMemory(data: {
+    memory: string;
+    user: string;
+}): Promise<void>;

package/dist/types/runtime/infra/file-watcher.d.ts

@@ -0,0 +1,72 @@
+/**
+ * File Watcher — CC filesystem change tracking parity.
+ *
+ * Fires hook events when files in the project change:
+ *   - file.changed (created/modified/deleted)
+ *   - cwd.changed (working directory switch)
+ *
+ * Uses Node.js fs.watch for project-level file monitoring.
+ * Does NOT use chokidar or other heavyweight watchers —
+ * this is a lightweight change-awareness system.
+ *
+ * Watched paths:
+ *   - .qlogicagent/settings.json → permission hot-reload
+ *   - INSTRUCTIONS.md / .qlogicagent/INSTRUCTIONS.md → instruction re-load
+ *   - configurable additional patterns
+ *
+ * Reference: claude-code file-watcher usage throughout lifecycle
+ */
+import type { HookRegistry } from "../../contracts/hooks.js";
+export interface FileWatcherDeps {
+    /** Project root directory (base for relative paths) */
+    projectRoot: string;
+    /** Session ID for hook context */
+    sessionId: string;
+    /** Hook registry for file.changed / cwd.changed events */
+    hooks: HookRegistry;
+    /** Logger */
+    log?: (msg: string) => void;
+    /** Callback to reset instruction cache when instructions change (injected, decoupled from prompt/) */
+    onInstructionCacheReset?: () => void;
+}
+export type ChangeType = "created" | "modified" | "deleted";
+export interface FileChangeEvent {
+    filePath: string;
+    changeType: ChangeType;
+    relativePath: string;
+}
+export declare class FileWatcher {
+    private watchers;
+    private deps;
+    private debounceTimers;
+    private _cwd;
+    constructor(deps: FileWatcherDeps);
+    get cwd(): string;
+    /**
+     * Start watching files.
+     * Watches each path in WATCHED_PATHS that exists on disk.
+     */
+    start(): Promise<void>;
+    /**
+     * Watch a single path. If it's a directory, watches recursively.
+     */
+    private watchPath;
+    /**
+     * Handle a file change event (debounced).
+     */
+    private handleChange;
+    /**
+     * Update the current working directory.
+     * Fires cwd.changed hook if the directory actually changed.
+     */
+    setCwd(newCwd: string): void;
+    /**
+     * Stop all watchers.
+     */
+    stop(): void;
+}
+/**
+ * Create and start a file watcher.
+ * Returns the watcher instance (call .stop() to clean up).
+ */
+export declare function createFileWatcher(deps: FileWatcherDeps): Promise<FileWatcher>;

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

@@ -0,0 +1,8 @@
+export { AGENT_DOT_DIR, getUserAgentHome, getUserSessionDir, getUserCredentialsPath, getUserPluginsDir, getUserSkillsDir, getUserSettingsPath, getUserCacheDir, getUserDebugLogsDir, getUserCheckpointsDir, getUserPluginCacheDir, getUserMcpConfigPath, getUserMarketplaceConfigPath, getUserWorkflowsDir, getUserInstructionsPath, getProjectAgentDir, getProjectWorkflowsDir, getProjectPluginsDir, getProjectSkillsDir, getProjectSettingsPath, getProjectInstructionsPath, getProjectRulesDir, getGitRootHooksDir, } from "./agent-paths.js";
+export { getBudgetContinuationMessage } from "./token-budget.js";
+export { type SecureStorage, saveApiKey, loadApiKey } from "./secure-storage.js";
+export { createFileWatcher, FileWatcher } from "./file-watcher.js";
+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";