byterover-cli 1.8.0 → 2.1.0

package/dist/server/core/interfaces/context-tree/i-context-tree-archive-service.d.ts

@@ -0,0 +1,30 @@
+import type { ICipherAgent } from '../../../../agent/core/interfaces/i-cipher-agent.js';
+import type { ArchiveResult, DrillDownResult } from '../../domain/knowledge/summary-types.js';
+/**
+ * Service for archiving and restoring context tree entries.
+ *
+ * Archives low-importance entries into _archived/ with:
+ * - .stub.md: searchable ghost cue (~220 tokens)
+ * - .full.md: lossless preserved original content
+ */
+export interface IContextTreeArchiveService {
+    /**
+     * Archive a context entry: write .full.md + .stub.md, delete original.
+     * Uses LLM to generate ghost cue with deterministic fallback.
+     */
+    archiveEntry(relativePath: string, agent: ICipherAgent, directory?: string): Promise<ArchiveResult>;
+    /**
+     * Drill down into an archived entry: read .full.md via stub's points_to.
+     * No LLM call — purely file-based lookup.
+     */
+    drillDown(stubPath: string, directory?: string): Promise<DrillDownResult>;
+    /**
+     * Find entries that are candidates for archiving.
+     * Returns paths where importance < ARCHIVE_IMPORTANCE_THRESHOLD and maturity === 'draft'.
+     */
+    findArchiveCandidates(directory?: string): Promise<string[]>;
+    /**
+     * Restore an archived entry: write .full.md content to original_path, delete stub + full.
+     */
+    restoreEntry(stubPath: string, directory?: string): Promise<string>;
+}

package/dist/server/core/interfaces/context-tree/i-context-tree-manifest-service.d.ts

@@ -0,0 +1,30 @@
+import type { ContextManifest, LaneTokens, ResolvedEntry } from '../../domain/knowledge/summary-types.js';
+/**
+ * Service for building and reading the context manifest (_manifest.json).
+ *
+ * The manifest allocates context tree entries into three lanes
+ * (summaries, contexts, stubs) with token budgets, enabling
+ * efficient context injection for queries.
+ */
+export interface IContextTreeManifestService {
+    /**
+     * Build (or rebuild) the manifest from current context tree state.
+     * Writes _manifest.json and returns the manifest.
+     */
+    buildManifest(directory?: string, laneBudgets?: LaneTokens): Promise<ContextManifest>;
+    /**
+     * Read the manifest from disk. Returns null if no manifest exists.
+     */
+    readManifest(directory?: string): Promise<ContextManifest | null>;
+    /**
+     * Read the manifest only if it is fresh (source-fingerprint match).
+     * Returns null if the manifest is stale or missing.
+     */
+    readManifestIfFresh(directory?: string): Promise<ContextManifest | null>;
+    /**
+     * Resolve manifest entries into content ready for prompt injection.
+     * Orders: summaries (broadest first) → contexts → stubs.
+     * If query is provided, reorders contexts by BM25 relevance.
+     */
+    resolveForInjection(manifest: ContextManifest, query?: string, directory?: string): Promise<ResolvedEntry[]>;
+}

package/dist/server/core/interfaces/context-tree/i-context-tree-merger.d.ts

@@ -0,0 +1,80 @@
+import type { CogitSnapshotFile } from '../../domain/entities/cogit-snapshot-file.js';
+import type { ContextTreeChanges } from '../../domain/entities/context-tree-snapshot.js';
+/**
+ * Parameters for a merge operation.
+ */
+export interface MergeParams {
+    /** Project base directory */
+    directory: string;
+    /** Remote snapshot files from CoGit pull */
+    files: readonly CogitSnapshotFile[];
+    /**
+     * Local changes detected before the merge.
+     * Note: locally-deleted files (localChanges.deleted) are absent from disk and excluded
+     * from conflict detection. If the remote has the file, remote wins and re-creates it locally.
+     */
+    localChanges: ContextTreeChanges;
+    /**
+     * When true, applies first-time-connect semantics: the local context tree has no shared
+     * history with the target space, so local always wins unless both sides have independently
+     * changed the same file.
+     *
+     * Concretely:
+     * - Clean local files absent from remote are preserved (not deleted).
+     * - Clean local files that exist in remote with different content are treated as conflicts
+     *   (local copy saved as _N.md, remote written to original path) rather than silently overwritten.
+     *
+     * Preserved files will appear as "added" on the next getChanges() call, prompting the user
+     * to push their local work to the new space.
+     *
+     * When false (default), clean local files absent from remote are deleted, and clean local
+     * files are silently overwritten by remote — the correct behaviour for a regular pull where
+     * the remote is the source of truth.
+     */
+    preserveLocalFiles?: boolean;
+}
+/**
+ * Result of a merge operation.
+ */
+export interface MergeResult {
+    /**
+     * Files added to the context tree. Includes both remote-originated new files and
+     * local files renamed with a _N.md suffix due to conflicts.
+     */
+    added: string[];
+    /**
+     * Original paths that had true conflicts (both local and remote changed the same file).
+     * For each path in this list, the local version was renamed to a _N.md suffix while
+     * the remote version took the original path.
+     */
+    conflicted: string[];
+    /** Local clean files removed because remote deleted them */
+    deleted: string[];
+    /**
+     * Files updated with remote content. Includes clean local files overwritten by remote
+     * (regular pull) and paths where both sides independently changed to the same content
+     * (convergence — no conflict).
+     */
+    edited: string[];
+    /**
+     * Files the user had deleted locally but which remote re-created because remote had a
+     * newer version. These paths are present in the context tree again after the merge.
+     * Callers should notify the user so they can decide whether to keep or delete them.
+     */
+    restoredFromRemote: string[];
+}
+/**
+ * Merges remote CoGit snapshot files into the local context tree while
+ * preserving local changes. Conflicting local files are renamed with a
+ * numeric suffix (_1.md, _2.md, …) before remote content takes the original path.
+ *
+ * When conflicts occur, the original local versions of conflicted files are copied
+ * to .brv/context-tree-conflicts/ for review. This folder is cleared automatically
+ * at the start of the next merge.
+ *
+ * On failure, the context tree is automatically restored to its pre-merge state
+ * and the temporary backup is removed.
+ */
+export interface IContextTreeMerger {
+    merge(params: MergeParams): Promise<MergeResult>;
+}

package/dist/server/core/interfaces/context-tree/i-context-tree-service.d.ts

@@ -4,6 +4,11 @@
  * initialization and existence checking.
  */
 export interface IContextTreeService {
+    /**
+     * Deletes the context tree directory and its contents.
+     * @param directory - Optional base directory (defaults to current working directory)
+     */
+    delete(directory?: string): Promise<void>;
     /**
      * Checks if the context tree structure exists in the project.
      * @param directory - Optional base directory (defaults to current working directory)

package/dist/server/core/interfaces/context-tree/i-context-tree-snapshot-service.d.ts

@@ -16,6 +16,13 @@ export interface IContextTreeSnapshotService {
      * @returns Map of relative file paths to their current state (hash and size)
      */
     getCurrentState(directory?: string): Promise<Map<string, FileState>>;
+    /**
+     * Gets the saved snapshot state (the last committed baseline).
+     * Returns an empty map if no snapshot exists.
+     * @param directory - Optional base directory (defaults to current working directory)
+     * @returns Map of relative file paths to their snapshotted state (hash and size)
+     */
+    getSnapshotState(directory?: string): Promise<Map<string, FileState>>;
     /**
      * Checks if a snapshot file exists.
      * @param directory - Optional base directory (defaults to current working directory)
@@ -33,4 +40,12 @@ export interface IContextTreeSnapshotService {
      * @param directory - Optional base directory (defaults to current working directory)
      */
     saveSnapshot(directory?: string): Promise<void>;
+    /**
+     * Saves a snapshot from a pre-computed file state map.
+     * Use this after a merge to record only the remote files, so that
+     * locally preserved/renamed files appear as "added" on next getChanges().
+     * @param state - Map of relative file paths to their file states
+     * @param directory - Optional base directory (defaults to current working directory)
+     */
+    saveSnapshotFromState(state: Map<string, FileState>, directory?: string): Promise<void>;
 }

package/dist/server/core/interfaces/context-tree/i-context-tree-summary-service.d.ts

@@ -0,0 +1,29 @@
+import type { ICipherAgent } from '../../../../agent/core/interfaces/i-cipher-agent.js';
+import type { StalenessCheckResult, SummaryGenerationResult } from '../../domain/knowledge/summary-types.js';
+/**
+ * Service for managing hierarchical summary nodes (_index.md) in the context tree.
+ *
+ * Agent is passed per-call (not setter-based) to avoid race conditions
+ * with concurrent tasks (AGENT_MAX_CONCURRENT_TASKS = 5).
+ */
+export interface IContextTreeSummaryService {
+    /**
+     * Check whether the summary for a directory is stale.
+     * Returns isStale: true if no _index.md exists or if children hash has changed.
+     */
+    checkStaleness(directoryPath: string, directory?: string): Promise<StalenessCheckResult>;
+    /**
+     * Generate or regenerate the _index.md summary for a directory.
+     * Uses three-tier escalation: normal → aggressive → deterministic fallback.
+     * Fail-open: returns { actionTaken: false } on any error.
+     */
+    generateSummary(directoryPath: string, agent: ICipherAgent, directory?: string): Promise<SummaryGenerationResult>;
+    /** Check whether a directory has an existing _index.md summary. */
+    hasSummary(directoryPath: string, directory?: string): Promise<boolean>;
+    /**
+     * Propagate staleness upward from changed paths.
+     * Processes bottom-up: regenerates stale summaries from deepest to shallowest.
+     * Stops climbing on LLM/IO errors; continues on empty directories.
+     */
+    propagateStaleness(changedPaths: string[], agent: ICipherAgent, directory?: string): Promise<SummaryGenerationResult[]>;
+}

package/dist/server/core/interfaces/daemon/i-agent-idle-timeout-policy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Idle timeout policy for agent process cleanup.
+ * Tracks agent activity to kill idle agents after a period of inactivity.
+ */
+export interface IAgentIdleTimeoutPolicy {
+    /**
+     * Returns idle status for all tracked agents.
+     * Used by debug command to show countdown timers.
+     *
+     * @returns Array of idle status per agent (empty if no agents tracked)
+     */
+    getIdleStatus(): Array<{
+        idleMs: number;
+        projectPath: string;
+        remainingMs: number;
+    }>;
+    /**
+     * Notifies that an agent completed a task (was active).
+     * Resets the idle timer for the given project.
+     */
+    onAgentActivity(projectPath: string): void;
+    /**
+     * Removes an agent from tracking (e.g., when agent is manually killed).
+     * Prevents firing onAgentIdle for removed agents.
+     */
+    removeAgent(projectPath: string): void;
+    /**
+     * Starts idle timeout checking.
+     *
+     * Idempotent: calling when already running is a no-op.
+     */
+    start(): void;
+    /**
+     * Stops idle timeout checking.
+     *
+     * Idempotent: calling when not running is a no-op.
+     */
+    stop(): void;
+}

package/dist/server/core/interfaces/daemon/i-daemon-resilience.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Daemon resilience management.
+ * Installs process-level error and signal handlers that keep
+ * the daemon alive through uncaught exceptions, unhandled rejections,
+ * and sleep/wake cycles.
+ */
+export interface IDaemonResilience {
+    /**
+     * Installs all resilience handlers:
+     * - uncaughtException (log + continue)
+     * - unhandledRejection (log + continue)
+     * - SIGHUP (no-op, survive terminal close)
+     * - Sleep/wake detection timer
+     *
+     * Idempotent: calling when already installed is a no-op.
+     */
+    install(): void;
+    /**
+     * Removes all resilience handlers and stops sleep/wake detection.
+     *
+     * Idempotent: calling when not installed is a no-op.
+     */
+    uninstall(): void;
+}

package/dist/server/core/interfaces/daemon/i-heartbeat-writer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * File-based heartbeat writer.
+ * Writes the current epoch timestamp to a file at regular intervals,
+ * allowing external processes to detect if the daemon is alive.
+ */
+export interface IHeartbeatWriter {
+    /**
+     * Writes the heartbeat immediately without starting the periodic timer.
+     * Useful for refreshing after sleep/wake detection.
+     */
+    refresh(): void;
+    /**
+     * Starts periodic heartbeat writes.
+     * Writes immediately on start, then schedules recursive timeouts.
+     *
+     * Idempotent: calling when already running is a no-op.
+     */
+    start(): void;
+    /**
+     * Stops periodic heartbeat writes.
+     * Does NOT delete the heartbeat file — it naturally becomes stale
+     * when writes stop, preventing cascade kills during overlapping
+     * shutdown/startup sequences.
+     *
+     * Idempotent: calling when not running is a no-op.
+     */
+    stop(): void;
+}

package/dist/server/core/interfaces/daemon/i-idle-timeout-policy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Idle timeout policy for daemon auto-shutdown.
+ * Tracks client connections to shut down the daemon
+ * after a period of inactivity.
+ */
+export interface IIdleTimeoutPolicy {
+    /**
+     * Returns daemon idle status.
+     * Used by debug command to show countdown timer.
+     *
+     * @returns Idle status if clientCount = 0, undefined if clients are connected
+     */
+    getIdleStatus(): undefined | {
+        clientCount: number;
+        idleMs: number;
+        remainingMs: number;
+    };
+    /** Notifies that a client has connected. Resets the idle timer. */
+    onClientConnected(): void;
+    /** Notifies that a client has disconnected. Resets the idle timer. */
+    onClientDisconnected(): void;
+    /**
+     * Starts idle timeout checking.
+     *
+     * Idempotent: calling when already running is a no-op.
+     */
+    start(): void;
+    /**
+     * Stops idle timeout checking.
+     *
+     * Idempotent: calling when not running is a no-op.
+     */
+    stop(): void;
+}

package/dist/server/core/interfaces/daemon/i-shutdown-handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Ordered graceful shutdown handler for the daemon.
+ */
+export interface IShutdownHandler {
+    /**
+     * Performs ordered graceful shutdown.
+     * Idempotent: second call is a no-op.
+     *
+     * Shutdown sequence (8 steps):
+     * 1. Stop server idle timeout checks
+     * 2. Stop agent idle timeout checks
+     * 3. Uninstall resilience handlers
+     * 4. Stop heartbeat writer
+     * 5. Stop agent pool
+     * 6. Stop transport server
+     * 7. Release daemon.json
+     * 8. Schedule force exit safety net
+     */
+    shutdown(): Promise<void>;
+}

package/dist/server/core/interfaces/daemon/index.d.ts

@@ -0,0 +1,4 @@
+export type { IDaemonResilience } from './i-daemon-resilience.js';
+export type { IHeartbeatWriter } from './i-heartbeat-writer.js';
+export type { IIdleTimeoutPolicy } from './i-idle-timeout-policy.js';
+export type { IShutdownHandler } from './i-shutdown-handler.js';

package/dist/server/core/interfaces/daemon/index.js

@@ -0,0 +1,2 @@
+export {};
+// ISpawnLock, SpawnLockAcquireResult → @campfirein/brv-transport-client

package/dist/server/core/interfaces/executor/i-curate-executor.d.ts

@@ -20,8 +20,8 @@ export interface CurateExecuteOptions {
  * It's an Executor that wraps agent.execute() with curate-specific options.
  *
  * Architecture:
- * - TaskProcessor injects the long-lived CipherAgent
- * - Event streaming is handled by agent-worker (subscribes to agentEventBus)
+ * - AgentProcess injects the long-lived CipherAgent
+ * - Event streaming is handled by agent-process (subscribes to agentEventBus)
  * - Executor focuses solely on curate execution
  */
 export interface ICurateExecutor {

package/dist/server/core/interfaces/executor/i-query-executor.d.ts

@@ -16,8 +16,8 @@ export interface QueryExecuteOptions {
  * It's an Executor that wraps agent.execute() with query-specific options.
  *
  * Architecture:
- * - TaskProcessor injects the long-lived CipherAgent
- * - Event streaming is handled by agent-worker (subscribes to agentEventBus)
+ * - AgentProcess injects the long-lived CipherAgent
+ * - Event streaming is handled by agent-process (subscribes to agentEventBus)
  * - Executor focuses solely on query execution
  */
 export interface IQueryExecutor {

package/dist/server/core/interfaces/hub/i-hub-install-service.d.ts

@@ -0,0 +1,45 @@
+import type { AuthScheme } from '../../../../shared/transport/types/auth-scheme.js';
+import type { HubEntryDTO } from '../../../../shared/transport/types/dto.js';
+import { Agent } from '../../domain/entities/agent.js';
+/**
+ * Auth parameters for private registry downloads.
+ */
+export interface HubInstallAuthParams {
+    authScheme?: AuthScheme;
+    authToken?: string;
+    headerName?: string;
+}
+/**
+ * Result of a hub install operation.
+ */
+export interface HubInstallResult {
+    installedFiles: string[];
+    installedPath: string;
+    message: string;
+}
+/**
+ * Parameters for installing a hub entry.
+ */
+export interface HubInstallParams {
+    /** The target agent display name (required for skills). */
+    agent?: Agent;
+    /** Optional auth parameters for private registry downloads. */
+    auth?: HubInstallAuthParams;
+    /** The hub entry to install. */
+    entry: HubEntryDTO;
+    /** The project root path. */
+    projectPath: string;
+    /** Optional scope for skill installs ('global' or 'project'). Ignored for bundles. */
+    scope?: 'global' | 'project';
+}
+/**
+ * Interface for installing hub entries (skills and bundles).
+ */
+export interface IHubInstallService {
+    /**
+     * Installs a hub entry.
+     * Skills are written to the target agent's skill directory.
+     * Bundles are written to the context tree.
+     */
+    install(params: HubInstallParams): Promise<HubInstallResult>;
+}

package/dist/server/core/interfaces/hub/i-hub-install-service.js

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

package/dist/server/core/interfaces/hub/i-hub-keychain-store.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Interface for securely storing private hub registry auth tokens.
+ * Uses system keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager)
+ * or file-based encrypted fallback.
+ */
+export interface IHubKeychainStore {
+    /**
+     * Deletes the auth token for a registry.
+     *
+     * @param registryName The registry name
+     */
+    deleteToken(registryName: string): Promise<void>;
+    /**
+     * Gets the auth token for a registry.
+     *
+     * @param registryName The registry name
+     * @returns The auth token if found, undefined otherwise
+     */
+    getToken(registryName: string): Promise<string | undefined>;
+    /**
+     * Sets the auth token for a registry.
+     *
+     * @param registryName The registry name
+     * @param token The auth token to store
+     */
+    setToken(registryName: string, token: string): Promise<void>;
+}

package/dist/server/core/interfaces/hub/i-hub-keychain-store.js

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

package/dist/server/core/interfaces/hub/i-hub-registry-config-store.d.ts

@@ -0,0 +1,27 @@
+import type { AuthScheme } from '../../../../shared/transport/types/auth-scheme.js';
+/**
+ * A configured private hub registry entry.
+ */
+export interface HubRegistryEntry {
+    readonly authScheme?: AuthScheme;
+    readonly headerName?: string;
+    readonly name: string;
+    readonly url: string;
+}
+/**
+ * Interface for storing and retrieving private hub registry configurations.
+ */
+export interface IHubRegistryConfigStore {
+    /**
+     * Adds a registry. Throws if a registry with the same name already exists.
+     */
+    addRegistry(entry: HubRegistryEntry): Promise<void>;
+    /**
+     * Returns all configured registries.
+     */
+    getRegistries(): Promise<HubRegistryEntry[]>;
+    /**
+     * Removes a registry by name. No-op if the registry does not exist.
+     */
+    removeRegistry(name: string): Promise<void>;
+}

package/dist/server/core/interfaces/hub/i-hub-registry-config-store.js

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

package/dist/server/core/interfaces/hub/i-hub-registry-service.d.ts

@@ -0,0 +1,30 @@
+import type { HubEntryDTO } from '../../../../shared/transport/types/dto.js';
+/**
+ * Interface for fetching hub registry entries.
+ */
+export interface IHubRegistryService {
+    /**
+     * Fetches all entries from the hub registry.
+     *
+     * @returns A promise resolving to the list of entries and registry version.
+     */
+    getEntries(): Promise<{
+        entries: HubEntryDTO[];
+        version: string;
+    }>;
+    /**
+     * Fetches ALL entries matching the given ID across all registries.
+     * Used for detecting ID collisions across multiple registries.
+     *
+     * @param entryId The ID of the entry to find.
+     * @returns A promise resolving to an array of matching entries (may be empty).
+     */
+    getEntriesById(entryId: string): Promise<HubEntryDTO[]>;
+    /**
+     * Fetches a single entry by its ID.
+     *
+     * @param entryId The ID of the entry to find.
+     * @returns A promise resolving to the entry, or undefined if not found.
+     */
+    getEntryById(entryId: string): Promise<HubEntryDTO | undefined>;
+}

package/dist/server/core/interfaces/hub/i-hub-registry-service.js

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

package/dist/server/core/interfaces/i-provider-config-store.d.ts

@@ -12,6 +12,7 @@ export interface IProviderConfigStore {
      */
     connectProvider: (providerId: string, options?: {
         activeModel?: string;
+        baseUrl?: string;
     }) => Promise<void>;
     /**
      * Removes a provider connection.
@@ -64,8 +65,9 @@ export interface IProviderConfigStore {
      *
      * @param providerId The provider ID
      * @param modelId The model ID to set as active
+     * @param contextLength Optional context window size from provider API
      */
-    setActiveModel: (providerId: string, modelId: string) => Promise<void>;
+    setActiveModel: (providerId: string, modelId: string, contextLength?: number) => Promise<void>;
     /**
      * Sets the active provider.
      *

package/dist/server/core/interfaces/i-provider-model-fetcher.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Provider Model Fetcher Interface
+ *
+ * Defines the contract for fetching models from LLM providers.
+ * Each provider implements this to enable model listing and API key validation.
+ */
+/**
+ * Normalized model info returned by all provider fetchers.
+ * Compatible with the existing NormalizedModel from OpenRouter client.
+ */
+export interface ProviderModelInfo {
+    /** Capabilities (optional, provider-specific) */
+    capabilities?: {
+        streaming?: boolean;
+        tools?: boolean;
+        vision?: boolean;
+    };
+    /** Context window size in tokens */
+    contextLength: number;
+    /** Optional description */
+    description?: string;
+    /** Model identifier (e.g., 'claude-sonnet-4-5-20250929', 'gpt-4.1') */
+    id: string;
+    /** Whether this model is free to use */
+    isFree: boolean;
+    /** Display name */
+    name: string;
+    /** Pricing per million tokens (USD) */
+    pricing: {
+        inputPerM: number;
+        outputPerM: number;
+    };
+    /** Provider name (e.g., 'Anthropic', 'OpenAI') */
+    provider: string;
+}
+/**
+ * Interface for provider-specific model fetching.
+ *
+ * Implementations handle the specifics of each provider's API
+ * and normalize the results to a common format.
+ */
+export interface IProviderModelFetcher {
+    /**
+     * Fetch available models from the provider.
+     * @param apiKey - API key for authentication
+     * @param forceRefresh - If true, bypass any cache
+     * @returns Array of normalized model info
+     */
+    fetchModels(apiKey: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    /**
+     * Validate an API key by attempting a lightweight API call.
+     * @param apiKey - API key to validate
+     * @returns Validation result with optional error message
+     */
+    validateApiKey(apiKey: string): Promise<{
+        error?: string;
+        isValid: boolean;
+    }>;
+}

package/dist/server/core/interfaces/i-provider-model-fetcher.js

@@ -0,0 +1,7 @@
+/**
+ * Provider Model Fetcher Interface
+ *
+ * Defines the contract for fetching models from LLM providers.
+ * Each provider implements this to enable model listing and API key validation.
+ */
+export {};

package/dist/server/core/interfaces/process/i-task-lifecycle-hook.d.ts

@@ -0,0 +1,27 @@
+import type { LlmToolResultEvent } from '../../domain/transport/schemas.js';
+import type { TaskInfo } from '../../domain/transport/task-info.js';
+/**
+ * Hook interface for observing task lifecycle events.
+ *
+ * All methods are optional — implement only the events you care about.
+ * Implementations must never throw; errors should be handled internally.
+ *
+ * Design: TaskRouter accepts lifecycleHooks[] so new hooks (e.g. QueryLogHandler)
+ * can be added without modifying TaskRouter.
+ */
+export interface ITaskLifecycleHook {
+    /** Called after onTaskCompleted, onTaskError, or onTaskCancelled to release in-memory resources. */
+    cleanup?(taskId: string): void;
+    /** Called when a task is cancelled by the user. Distinct from onTaskError. */
+    onTaskCancelled?(taskId: string, task: TaskInfo): Promise<void>;
+    /** Called when a task completes successfully. */
+    onTaskCompleted?(taskId: string, result: string, task: TaskInfo): Promise<void>;
+    /** Called when a new task is created. Return {logId} to associate a log entry with the task. */
+    onTaskCreate?(task: TaskInfo): Promise<void | {
+        logId?: string;
+    }>;
+    /** Called when a task fails with an error. */
+    onTaskError?(taskId: string, errorMessage: string, task: TaskInfo): Promise<void>;
+    /** Called when an LLM tool result event is received for an ACTIVE task (not grace-period). */
+    onToolResult?(taskId: string, payload: LlmToolResultEvent): void;
+}

package/dist/server/core/interfaces/process/i-task-lifecycle-hook.js

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