qlogicagent 2.7.0 → 2.9.0

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

@@ -9,10 +9,12 @@
 export declare const AGENT_DOT_DIR = ".qlogicagent";
 /** `~/.qlogicagent/` (or QLOGICAGENT_HOME override) */
 export declare function getUserAgentHome(): string;
-/** `~/.qlogicagent/sessions/` */
-export declare function getUserSessionsRoot(): string;
-/** `~/.qlogicagent/sessions/{sessionId}` */
-export declare function getUserSessionDir(sessionId: string): string;
+/**
+ * Ensure the user agent home directory exists and is writable.
+ * Returns the path if accessible, throws with a friendly message otherwise.
+ * Call this once at startup rather than on every path resolution.
+ */
+export declare function ensureUserAgentHome(): string;
 /** `~/.qlogicagent/.credentials.json` */
 export declare function getUserCredentialsPath(): string;
 /** `~/.qlogicagent/plugins/` */
@@ -25,8 +27,6 @@ export declare function getUserSettingsPath(): string;
 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` */
@@ -39,26 +39,20 @@ export declare function getUserWorkflowsDir(): string;
 export declare function getUserInstructionsPath(): string;
 /** `~/.qlogicagent/rules/` */
 export declare function getUserRulesDir(): string;
-/** `~/.qlogicagent/media/` — auto-downloaded media files (images, videos, audio). */
-export declare function getUserMediaDir(): string;
 /** `<cwd>/.qlogicagent/` */
-export declare function getProjectAgentDir(cwd?: string): string;
+export declare function getProjectAgentDir(cwd: string): string;
 /** `<cwd>/.qlogicagent/workflows/` */
-export declare function getProjectWorkflowsDir(cwd?: string): string;
+export declare function getProjectWorkflowsDir(cwd: string): string;
 /** `<cwd>/.qlogicagent/plugins/` */
-export declare function getProjectPluginsDir(cwd?: string): string;
+export declare function getProjectPluginsDir(cwd: string): string;
 /** `<cwd>/.qlogicagent/skills/` */
-export declare function getProjectSkillsDir(cwd?: string): string;
+export declare function getProjectSkillsDir(cwd: string): string;
 /** `<cwd>/.qlogicagent/settings.json` */
-export declare function getProjectSettingsPath(cwd?: string): string;
+export declare function getProjectSettingsPath(cwd: string): string;
 /** `<cwd>/.qlogicagent/INSTRUCTIONS.md` */
-export declare function getProjectInstructionsPath(cwd?: string): string;
-/** `<cwd>/.qlogicagent/instructions/` — project-scoped instruction files (CRUD via RPC) */
-export declare function getProjectInstructionsDir(cwd?: string): string;
-/** `<cwd>/.qlogicagent/plans/` — project-scoped plan files */
-export declare function getProjectPlansDir(cwd?: string): string;
-/** `<cwd>/.qlogicagent/rules/` */
-export declare function getProjectRulesDir(cwd?: string): string;
+export declare function getProjectInstructionsPath(cwd: string): string;
+/** `<cwd>/.qlogicagent/rules/` — unified rules + instructions directory */
+export declare function getProjectRulesDir(cwd: string): string;
 /** `<cwd>/.qlogicagent/sessions/` */
 export declare function getProjectSessionsRoot(cwd: string): string;
 /** `<cwd>/.qlogicagent/sessions/{sessionId}` */
@@ -68,16 +62,19 @@ export declare function getProjectCheckpointsDir(cwd: string, sessionId?: string
 /** `<gitRoot>/.qlogicagent/hooks/` */
 export declare function getGitRootHooksDir(gitRoot: string): string;
 /**
- * Discover all known project directories from session history.
- * Scans `~/.qlogicagent/sessions/` metadata to extract unique `cwd` paths.
+ * Discover all known project directories from the project store.
  * Used for cross-project skill recall (read-only, never writes to foreign projects).
  *
+ * NOTE: Does NOT import project-store directly to avoid circular deps.
+ * Caller must pass the project list.
+ *
+ * @param projectDirs - All known project workspace directories
  * @param excludeCwd - Current project cwd to exclude from results
- * @returns Array of absolute paths to project roots that have been worked on
+ * @returns Array of absolute paths to project roots that have skill directories
  */
-export declare function getKnownProjectDirs(excludeCwd?: string): string[];
+export declare function getKnownProjectDirs(projectDirs: string[], excludeCwd?: string): string[];
 /**
  * Get skill directories from all known projects (excluding current).
  * Returns paths to `<project>/.qlogicagent/skills/` for recall-only access.
  */
-export declare function getAllProjectSkillDirs(excludeCwd?: string): string[];
+export declare function getAllProjectSkillDirs(projectDirs: string[], excludeCwd?: string): string[];

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

@@ -7,7 +7,7 @@
  *   - Own memory + tool context (no shared process.cwd)
  *   - Lifecycle tracking (PID, health, abort)
  *
- * CC does this via tmux split-pane + `claude --agent-id ...` commands.
+ * CC does this via tmux split-pane + `claudeagent-id ...` commands.
  * We spawn `node dist/cli.js` as child processes with JSON-RPC stdio.
  *
  * Reference: claude-code-haha/src/utils/swarm/spawnMultiAgent.ts

package/dist/types/runtime/infra/builtin-providers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Supported provider metadata for settings RPC.
+ *
+ * Bridges provider-core's BUILTIN_PROVIDERS into the ModelPurpose system.
+ * This is the authoritative list of providers shown in "Add Key" UI.
+ *
+ * IMPORTANT: Model lists here are the Layer 2 (offline fallback) data source.
+ * Layer 1 is ModelCatalog (models.dev remote). These two are the ONLY sources.
+ */
+import type { ModelPurpose } from "./model-registry.js";
+export interface KnownModelMeta {
+    model: string;
+    displayName: string;
+    purposes: ModelPurpose[];
+    baseUrl?: string;
+}
+export interface SupportedProviderMeta {
+    id: string;
+    displayName: string;
+    baseUrl: string;
+    defaultRateLimit?: {
+        rpm?: number;
+        tpm?: number;
+    };
+    knownModels: KnownModelMeta[];
+}
+/**
+ * Minimal offline fallback providers.
+ * Remote catalog (Layer 1) has text generation models; this Layer 2 keeps ONLY
+ * specialized models that remote may not cover: embedding, TTS, STT, image gen,
+ * video gen, music gen, 3D gen, realtime voice/video, voice clone.
+ *
+ * All providers are kept (for Add Key UI dropdown + baseUrl lookup).
+ * Text generation / image understanding models are NOT listed here — remote always has them.
+ */
+export declare const SUPPORTED_PROVIDERS: SupportedProviderMeta[];

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

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

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

@@ -1,8 +1,7 @@
-export { AGENT_DOT_DIR, getUserAgentHome, getUserSessionDir, getUserCredentialsPath, getUserPluginsDir, getUserSkillsDir, getUserSettingsPath, getUserCacheDir, getUserDebugLogsDir, getUserCheckpointsDir, getUserPluginCacheDir, getUserMcpConfigPath, getUserMarketplaceConfigPath, getUserWorkflowsDir, getUserInstructionsPath, getProjectAgentDir, getProjectWorkflowsDir, getProjectPluginsDir, getProjectSkillsDir, getProjectSettingsPath, getProjectInstructionsPath, getProjectInstructionsDir, getProjectPlansDir, getProjectRulesDir, getGitRootHooksDir, getKnownProjectDirs, getAllProjectSkillDirs, } from "./agent-paths.js";
+export { AGENT_DOT_DIR, getUserAgentHome, getUserCredentialsPath, getUserPluginsDir, getUserSkillsDir, getUserSettingsPath, getUserCacheDir, getUserDebugLogsDir, getUserPluginCacheDir, getUserMcpConfigPath, getUserMarketplaceConfigPath, getUserWorkflowsDir, getProjectAgentDir, getProjectWorkflowsDir, getProjectPluginsDir, getProjectSkillsDir, getProjectSettingsPath, getProjectInstructionsPath, getProjectRulesDir, getGitRootHooksDir, getKnownProjectDirs, getAllProjectSkillDirs, } from "./agent-paths.js";
 export { getBudgetContinuationMessage } from "./token-budget.js";
 export { type SecureStorage, saveApiKey, loadApiKey } from "./secure-storage.js";
 export { ProjectInstructionsStore, type InstructionFile } from "./project-instructions-store.js";
-export { ProjectPlanStore, type PlanEntry } from "./project-plan-store.js";
 export { createFileWatcher, FileWatcher } from "./file-watcher.js";
 export { TaskStore } from "./task-runtime.js";
 export { createWorktreeBackend } from "./worktree-backend.js";

package/dist/types/runtime/infra/key-pool.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Key Pool — commercial-grade multi-key load balancing per provider.
+ *
+ * Supports: weighted-round-robin, least-busy, random strategies.
+ * Features: RPM/TPM sliding window, failure cooldown, health detection, auto-failover.
+ *
+ * Runtime state (inFlight, counters, health) is in-memory only — resets on restart.
+ * Persistent config (keys, weights, strategy) is managed by the caller (settings.json).
+ */
+export type LoadBalanceStrategy = "weighted-round-robin" | "least-busy" | "random";
+export type KeyHealthStatus = "healthy" | "degraded" | "cooldown" | "disabled";
+/** Persistent key config (saved to settings.json). */
+export interface KeyConfig {
+    id: string;
+    key: string;
+    label?: string;
+    weight: number;
+    enabled: boolean;
+}
+/** Persistent provider pool config (saved to settings.json). */
+export interface ProviderPoolConfig {
+    providerId: string;
+    baseUrl?: string;
+    strategy: LoadBalanceStrategy;
+    keys: KeyConfig[];
+    rateLimit?: {
+        rpm?: number;
+        tpm?: number;
+    };
+}
+/** Acquired key handle — caller must call release() when done. */
+export interface KeyHandle {
+    keyId: string;
+    apiKey: string;
+    providerId: string;
+    release: (result: KeyReleaseResult) => void;
+}
+export interface KeyReleaseResult {
+    success: boolean;
+    tokens?: number;
+    errorCode?: number;
+    retryAfter?: number;
+}
+/** Full status for a single key (config + runtime). */
+export interface KeyStatus extends KeyConfig {
+    inFlight: number;
+    totalRequests: number;
+    totalTokens: number;
+    lastUsedAt: number;
+    lastErrorAt: number;
+    consecutiveErrors: number;
+    cooldownUntil: number;
+    healthStatus: KeyHealthStatus;
+}
+/** Full status for a provider pool. */
+export interface PoolStatus {
+    providerId: string;
+    baseUrl?: string;
+    strategy: LoadBalanceStrategy;
+    rateLimit?: {
+        rpm?: number;
+        tpm?: number;
+    };
+    keys: KeyStatus[];
+}
+export declare class KeyPool {
+    private pools;
+    private runtimeStates;
+    constructor(configs?: ProviderPoolConfig[]);
+    /**
+     * Acquire the next available key for a provider.
+     * Returns a KeyHandle with release() that MUST be called when the request completes.
+     * Returns null if no healthy key is available.
+     */
+    acquireKey(providerId: string): KeyHandle | null;
+    /**
+     * Release a key after request completion. Updates health/stats.
+     */
+    private releaseKey;
+    addProvider(providerId: string, opts?: {
+        baseUrl?: string;
+        strategy?: LoadBalanceStrategy;
+        rateLimit?: {
+            rpm?: number;
+            tpm?: number;
+        };
+    }): void;
+    removeProvider(providerId: string): void;
+    addKey(providerId: string, key: string, opts?: {
+        id?: string;
+        label?: string;
+        weight?: number;
+        enabled?: boolean;
+    }): string;
+    removeKey(keyId: string): void;
+    updateKey(keyId: string, updates: Partial<Pick<KeyConfig, "label" | "weight" | "enabled">>): void;
+    /** Explicitly set a key's health status (e.g. after background validation). */
+    setKeyHealth(keyId: string, status: KeyHealthStatus): void;
+    setStrategy(providerId: string, strategy: LoadBalanceStrategy): void;
+    setRateLimit(providerId: string, rateLimit: {
+        rpm?: number;
+        tpm?: number;
+    }): void;
+    getPoolStatus(providerId: string): PoolStatus | null;
+    getAllStatus(): PoolStatus[];
+    getProviderIds(): string[];
+    hasProvider(providerId: string): boolean;
+    hasAvailableKey(providerId: string): boolean;
+    /** Export persistent config (for saving to settings.json). */
+    exportConfig(): ProviderPoolConfig[];
+    /** Reload from config (e.g., after settings.json changes on disk). */
+    reloadConfig(configs: ProviderPoolConfig[]): void;
+    private createInitialState;
+    private getHealthyCandidates;
+    private selectByStrategy;
+    private weightedRandom;
+    private leastBusy;
+    private pruneWindow;
+    private buildPoolStatus;
+}

package/dist/types/runtime/infra/media-persistence.d.ts

@@ -5,12 +5,13 @@
  * cloud URLs, this service downloads them to a persistent local directory
  * so the user can access them offline without manual intervention.
  *
- * Storage layout:
- *   ~/.qlogicagent/media/
- *   ├── <session-or-date>/
- *   │   ├── image_20260520_143022_abc.png
- *   │   ├── video_20260520_143055_def.mp4
- *   │   └── audio_20260520_143100_ghi.mp3
+ * Storage layout (per persistence-storage-rules.md):
+ *   <project>/.qlogicagent/sessions/<sessionId>/media/
+ *   ├── image_20260520_143022_abc.png
+ *   ├── video_20260520_143055_def.mp4
+ *   └── audio_20260520_143100_ghi.mp3
+ *
+ * Media files belong to their session. No global media storage.
  *
  * Integration:
  *   Called from the tool result pipeline in tool-loop.ts.
@@ -29,28 +30,36 @@ export interface MediaDownloadResult {
 }
 export interface MediaPersistenceConfig {
     /**
-     * Project working directory. When set, media downloads to `{projectDir}/media/`.
-     * Takes precedence over `mediaDir`. This is the preferred approach — generated
-     * media files belong to the project, not the global user home.
+     * Project working directory. Media downloads to:
+     *   `{projectDir}/.qlogicagent/sessions/{sessionId}/media/`
+     * This is the only correct location per persistence-storage-rules.
      */
     projectDir?: string;
-    /** Base directory for media storage. Default: ~/.qlogicagent/media/ (fallback only). */
-    mediaDir?: string;
     /** Maximum file size to download (bytes). Default: 500MB. */
     maxFileSize?: number;
     /** Download timeout per file (ms). Default: 300_000 (5 min). */
     timeoutMs?: number;
 }
 export declare class MediaPersistence {
-    private mediaDir;
+    private projectDir;
     private readonly maxFileSize;
     private readonly timeoutMs;
     constructor(config?: MediaPersistenceConfig);
-    /** Update media directory to use a specific project root. */
+    /** Update project root directory. */
     setProjectDir(projectDir: string): void;
+    /**
+     * Resolve the media directory for a given session.
+     * Path: <project>/.qlogicagent/sessions/<sessionId>/media/
+     */
+    private resolveMediaDir;
     /**
      * Download a remote URL to local storage.
      * Returns the local file path and metadata.
+     *
+     * Robustness:
+     *   - Validates path length (Windows 260 char limit)
+     *   - Cleans up partial files on download failure/timeout
+     *   - Handles abort/network errors gracefully
      */
     download(remoteUrl: string, hint?: {
         type?: string;
@@ -66,6 +75,8 @@ export declare class MediaPersistence {
     }, log?: {
         warn: (msg: string) => void;
     }): Promise<MediaDownloadResult[]>;
-    /** Get the base media directory path. */
-    getMediaDir(): string;
+    /** Get the media directory path for a session. */
+    getMediaDir(sessionId?: string): string;
+    /** Get the project directory (for testing/inspection). */
+    getProjectDir(): string | null;
 }

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

@@ -0,0 +1,187 @@
+/**
+ * Model Registry — centralized model pool + per-purpose binding.
+ *
+ * Architecture: User adds Provider keys → enables models → binds each purpose to a model.
+ * Any code needing a model calls `registry.getActiveModel(purpose)`.
+ * Turn handler, media handler, STT, TTS — all go through this single source of truth.
+ *
+ * Persistence: ~/.qlogicagent/settings.json
+ * Runtime state (key health, inFlight): in-memory via KeyPool
+ */
+import { type ProviderPoolConfig, type KeyConfig, type LoadBalanceStrategy, type KeyHandle, type PoolStatus } from "./key-pool.js";
+import { type ModelInfo, type ProviderDef } from "@qlogic/provider-core";
+export type RegistryChangeCallback = () => void;
+/** Purpose categories for model routing. */
+export type ModelPurpose = "textGeneration" | "smallModel" | "stt" | "tts" | "imageGeneration" | "imageUnderstanding" | "videoGeneration" | "videoUnderstanding" | "threeDGeneration" | "embedding" | "voiceClone" | "musicGeneration" | "realtimeAudio" | "realtimeVideo";
+/** A model entry in the available model pool. */
+export interface ModelEntry {
+    id: string;
+    provider: string;
+    model: string;
+    displayName: string;
+    purposes: ModelPurpose[];
+    baseUrl?: string;
+    enabled: boolean;
+}
+/** Per-purpose binding: maps purpose → model ID. */
+export type PurposeBindings = Partial<Record<ModelPurpose, string>>;
+/** Persistent settings.json schema (new architecture). */
+export interface ModelRegistryConfig {
+    providers: ProviderPoolConfig[];
+    models: ModelEntry[];
+    bindings: PurposeBindings;
+    tunables?: Record<string, unknown>;
+}
+/** Resolved model ready for API call. */
+export interface ResolvedModel {
+    provider: string;
+    model: string;
+    apiKey: string;
+    baseUrl?: string;
+    keyHandle: KeyHandle;
+}
+export declare class ModelRegistry {
+    private keyPool;
+    private models;
+    private bindings;
+    private settingsPath;
+    private changeListeners;
+    constructor(config?: ModelRegistryConfig);
+    /**
+     * Get the currently bound model for a purpose, with a live API key from the pool.
+     * Returns null if purpose is not bound or no key is available.
+     *
+     * IMPORTANT: Caller MUST call result.keyHandle.release({ success, tokens? }) when done.
+     */
+    getActiveModel(purpose: ModelPurpose): ResolvedModel | null;
+    /**
+     * Peek at the bound model for a purpose WITHOUT acquiring a key.
+     * Useful for UI display, description generation, etc.
+     */
+    peekActiveModel(purpose: ModelPurpose): ModelEntry | null;
+    /**
+     * Check if a purpose has an available model + key (without acquiring).
+     */
+    isAvailable(purpose: ModelPurpose): boolean;
+    /**
+     * Resolve a model name for a purpose, falling back to textGeneration if not bound.
+     * Returns the raw model string (e.g. "deepseek-v4-flash") or null if nothing configured.
+     * Does NOT acquire a key — use for cases where the caller already has transport/key.
+     */
+    resolveModelForPurpose(purpose: ModelPurpose): string | null;
+    addProvider(providerId: string, opts?: {
+        baseUrl?: string;
+        strategy?: LoadBalanceStrategy;
+        rateLimit?: {
+            rpm?: number;
+            tpm?: number;
+        };
+    }): void;
+    removeProvider(providerId: string): void;
+    addKey(providerId: string, key: string, opts?: {
+        label?: string;
+        weight?: number;
+    }): string;
+    removeKey(keyId: string): void;
+    updateKey(keyId: string, updates: Partial<Pick<KeyConfig, "label" | "weight" | "enabled">>): void;
+    setKeyHealth(keyId: string, status: "healthy" | "degraded" | "cooldown" | "disabled"): void;
+    setStrategy(providerId: string, strategy: LoadBalanceStrategy): void;
+    addModel(entry: Omit<ModelEntry, "id"> & {
+        id?: string;
+    }): string;
+    removeModel(id: string): void;
+    enableModel(id: string): void;
+    disableModel(id: string): void;
+    listModels(filter?: {
+        purpose?: ModelPurpose;
+        provider?: string;
+        enabledOnly?: boolean;
+    }): ModelEntry[];
+    getModel(id: string): ModelEntry | null;
+    setBinding(purpose: ModelPurpose, modelId: string): void;
+    removeBinding(purpose: ModelPurpose): void;
+    getBinding(purpose: ModelPurpose): ModelEntry | null;
+    getAllBindings(): Record<string, ModelEntry | null>;
+    getProviderStatus(providerId: string): PoolStatus | null;
+    getAllProviderStatus(): PoolStatus[];
+    /** Save current config to settings.json. Preserves non-model fields (tunables, theme, etc.). */
+    save(): void;
+    /** Load config from settings.json. Returns false if file not found or parse error. */
+    load(): boolean;
+    /** Export full config (for serialization/transfer). */
+    exportConfig(): ModelRegistryConfig;
+    /**
+     * Read a tunable value from settings.json tunables section.
+     * Returns undefined if not set. Does NOT write — read-only accessor.
+     */
+    getTunable<T = unknown>(key: string): T | undefined;
+    private _providerRegistry;
+    private getProviderRegistry;
+    /**
+     * Get model metadata (streamRequired, contextWindow, etc.) from the merged
+     * provider-core registry. Replaces direct `this.registry.getModelInfo(...)`.
+     */
+    getModelInfo(providerId: string, modelId: string): ModelInfo | undefined;
+    /**
+     * Get the default model id for a provider (from builtin-providers).
+     * Replaces `this.registry.getProvider(provider)?.defaultModel`.
+     */
+    getProviderDefaultModel(providerId: string): string | undefined;
+    /**
+     * List all known provider definitions (builtin + catalog).
+     * Replaces `this.registry.listProviders()`.
+     */
+    listProviderDefs(): ProviderDef[];
+    /**
+     * Resolve an API key for a provider via env vars (fallback when KeyPool has no key).
+     * Replaces `this.registry.resolveApiKey(providerId)`.
+     */
+    resolveProviderApiKey(providerId: string): string | undefined;
+    /**
+     * Register a callback to be notified when registry state changes
+     * (binding change, model add/remove, key change, save/load).
+     * Returns an unsubscribe function.
+     */
+    onChange(callback: RegistryChangeCallback): () => void;
+    private emitChange;
+    /**
+     * Snapshot one available key for a provider WITHOUT holding it (for legacy flat-map consumers).
+     * Returns null if no healthy key exists.
+     */
+    getKeyForProvider(providerId: string): string | null;
+    /**
+     * Snapshot one key per provider (for media tools flat apiKeys map).
+     */
+    snapshotProviderKeys(): Record<string, string>;
+    private getProviderBaseUrl;
+}
+export declare const ALL_PURPOSES: ModelPurpose[];
+/**
+ * Get the global ModelRegistry singleton.
+ * Lazily loads from settings.json on first access.
+ */
+export declare function getModelRegistry(): ModelRegistry;
+/**
+ * Reset the global singleton (for testing or hot-reload).
+ */
+export declare function resetModelRegistry(): void;
+/**
+ * Derive which purposes a model supports from its ModelInfo metadata.
+ * Layer 1: ModelCatalog (models.dev) modalities → purpose mapping.
+ *
+ * Priority: mediaType field → vision field → fallback to textGeneration.
+ */
+export declare function deriveModelPurposes(model: ModelInfo): ModelPurpose[];
+/**
+ * Layer 3: Name-based heuristic for models not in ModelCatalog or builtin-providers.
+ */
+export declare function heuristicModelPurposes(modelId: string): ModelPurpose[];
+/**
+ * Refresh models from ModelCatalog (remote models.dev + disk cache) for given providers.
+ * Merges discovered models into the registry without overwriting user-modified entries.
+ */
+export declare function refreshModelsFromCatalog(registry: ModelRegistry, providerIds: string[]): void;
+/**
+ * Force refresh the ModelCatalog from remote, then merge into registry.
+ */
+export declare function forceRefreshCatalog(registry: ModelRegistry, providerIds: string[]): Promise<boolean>;

package/dist/types/runtime/infra/project-instructions-store.d.ts

@@ -1,8 +1,8 @@
 /**
- * ProjectInstructionsStore — CRUD for project-scoped instruction files.
+ * ProjectInstructionsStore — CRUD for project-scoped rule/instruction files.
  *
- * Storage location: `<workspace>/.qlogicagent/instructions/*.md`
- * Format matches Gateway's InstructionsStore output for seamless migration.
+ * Storage location: `<workspace>/.qlogicagent/rules/*.md`
+ * Unified directory for all project instructions and rules.
  */
 export interface InstructionFile {
     filename: string;

package/dist/types/runtime/infra/project-store.d.ts

@@ -12,10 +12,12 @@ export declare function createProject(params: {
     workspaceDir: string;
     type?: ProjectType;
     groupId?: string;
+    skipAutoSwitch?: boolean;
 }): ProjectInfo;
 export declare function listProjects(): ProjectInfo[];
 export declare function getActiveProject(): ProjectInfo | null;
 export declare function getProjectById(projectId: string): ProjectInfo | null;
+export declare function updateProject(projectId: string, patch: Partial<Pick<ProjectInfo, "planStatus" | "planAgents" | "planWinnerId" | "leaderSessionId">>): boolean;
 export declare function switchProject(projectId: string): ProjectInfo | null;
 export declare function deleteProject(projectId: string): {
     deleted: boolean;
@@ -23,6 +25,7 @@ export declare function deleteProject(projectId: string): {
 };
 export declare function getOrCreateDefaultProject(defaultWorkspaceDir: string): ProjectInfo;
 export declare function renameProject(projectId: string, newName: string): ProjectInfo | null;
+export declare function updateProjectWorkspaceDir(projectId: string, newDir: string): boolean;
 export declare function archiveProject(projectId: string): {
     archived: boolean;
     switchedTo?: ProjectInfo;

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

@@ -1,5 +1,5 @@
 /**
- * Sub-agent Token Budget Enforcer 鈥?CC-aligned budget limits.
+ * Sub-agent Token Budget EnforcerCC-aligned budget limits.
  *
  * Prevents sub-agents from consuming infinite tokens by:
  *   1. Per-task token budget (from TaskStateBase.tokenBudget)
@@ -7,7 +7,7 @@
  *   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
+ * CC reference: utils/tokenBudget.ts, main.tsxmax-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.

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

@@ -6,7 +6,7 @@
  * 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
+ *   - listWorktrees(): git worktree listporcelain
  *   - isInWorktree(): check if cwd is inside a worktree
  *   - currentWorktree(): get current worktree info
  *

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

@@ -0,0 +1,8 @@
+/**
+ * Pet module — barrel export.
+ */
+export { PetSoulService, type PetSoul, type PetStats, type PetBreed } from "./pet-soul-service.js";
+export { maybeGenerateReaction, generateLLMReaction, type ReactionPool, type LLMReactionContext, type ReactionStyle } from "./pet-reaction-service.js";
+export { petContextInjection } from "./pet-context-injection.js";
+export { PetGrowthEngine, type GrowthEvent, type MoltResult, type PetAbility } from "./pet-growth-engine.js";
+export { loadPetFile, validatePetManifest, sanitizeSvg, type PetManifest, type PetFileBundle } from "./pet-file-loader.js";

package/dist/types/runtime/pet/pet-context-injection.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pet Context Injection — injects pet soul into agent system prompt.
+ *
+ * When a pet is hatched, this adds a brief section to the system prompt
+ * so the LLM "knows" the pet exists and can occasionally respond in character.
+ */
+import type { PetSoul } from "./pet-soul-service.js";
+export declare function petContextInjection(soul: PetSoul | null): string;