@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.1

package/dist/engine/engine.d.ts

@@ -1,22 +1,16 @@
 /**
  * Engine — the main facade that wires all components together.
  */
-import type { ClientDefaults, LLMConfig, SessionOrigin, StreamCallback, TerminalReason, TokenUsage } from "../types.js";
+import type { LLMConfig, StreamCallback } from "../types.js";
 import { ToolRegistry } from "../tool-system/registry.js";
 import { type BuiltinToolFn } from "../tool-system/builtin/index.js";
-import { type ApprovalBackend } from "../tool-system/permission.js";
 import { HookRegistry } from "../hooks/registry.js";
-import type { HookEventName } from "../hooks/events.js";
-import type { HookHandler } from "../hooks/registry.js";
-import { type GoalConfig } from "./goal.js";
+import { type GoalConfig, type GoalExtension } from "./goal.js";
 import { SessionManager } from "../session/session-manager.js";
-import type { CostStateStore } from "./cost-store.js";
 import type { AskUserFn } from "../tool-system/builtin/ask-user.js";
-import { type SettingsScope } from "../settings/manager.js";
 import type { CapabilityOverride } from "../settings/schema.js";
+import { type FeatureFlagName } from "../settings/feature-flags.js";
 import type { ToolContext } from "../tool-system/context.js";
-import { type SandboxConfig } from "../tool-system/sandbox/index.js";
-import { type AgentPresetName } from "../preset/index.js";
 import { ModelPool, type ModelEntry } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { EngineRuntime } from "./runtime.js";
@@ -31,118 +25,9 @@ export declare function compatFileNamesFrom(instructions?: {
     compatClaude?: boolean;
     compatCodex?: boolean;
 }): string[];
-export interface EngineConfig {
-    llm: LLMConfig;
-    /**
-     * Cross-model runtime knobs (temperature/timeout/retryMaxAttempts/imageDetail).
-     * Stays stable across hot model switches — only `llm` rotates. When omitted,
-     * Engine reads settings.json (model.temperature, images.detail) on construction.
-     */
-    clientDefaults?: ClientDefaults;
-    cwd?: string;
-    maxTurns?: number;
-    maxToolCallsPerTurn?: number;
-    permissionMode?: "default" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "auto" | "plan";
-    preset?: AgentPresetName;
-    enabledBuiltinTools?: string[];
-    disabledBuiltinTools?: string[];
-    customSystemPrompt?: string;
-    appendSystemPrompt?: string;
-    responseLanguage?: string;
-    userProfile?: string;
-    instructions?: {
-        compatClaude?: boolean;
-        compatCodex?: boolean;
-    };
-    /**
-     * Goal mode: when set, the engine registers a GoalStopHook on `on_stop`
-     * so the turn loop runs until the session model judges this goal met
-     * (bounded by maxStopBlocks + maxTurns). Orthogonal to permissionMode —
-     * the desktop UI defaults permission to bypass when a goal is set, but
-     * the engine treats the two independently.
-     *
-     * Accepts a raw string (objective only) or a full GoalConfig (objective +
-     * optional token/time budgets); the run boundary normalizes it once.
-     */
-    goal?: string | GoalConfig;
-    sessionStorageDir?: string;
-    maxContextTokens?: number;
-    approvalBackend?: ApprovalBackend;
-    hooks?: EngineHookConfig[];
-    askUser?: AskUserFn;
-    mcpServers?: Record<string, import("../types.js").MCPServerConfig>;
-    /**
-     * Optional opaque store for per-session cost/usage state. When provided,
-     * Engine calls `restore()` on session resume and `serialize()` at the end
-     * of each `run()` and stores the blob on the session. Without this the
-     * Engine doesn't persist cost state — it's a UI concern.
-     */
-    costStore?: CostStateStore;
-    /**
-     * True when the Engine runs in a no-UI / one-shot context (e.g. the `run`
-     * command). Currently controls InvestigationGuard soft-mode: in headless
-     * we never hard-block a tool call because there is no human to retry.
-     * Defaults to false.
-     */
-    headless?: boolean;
-    /**
-     * When true, treat like headless for InvestigationGuard soft-mode — a
-     * read-only session should never be hard-blocked for repeated reads.
-     */
-    readOnlySession?: boolean;
-    /**
-     * Sandbox configuration for shell-tool execution. When omitted, headless
-     * runs default to "auto" (Seatbelt on macOS / bwrap on Linux when
-     * available) and interactive runs default to "off" because a human is in
-     * the loop to approve commands.
-     */
-    sandbox?: SandboxConfig;
-    /**
-     * True when this Engine is itself a sub-agent (spawned by another
-     * Engine's Agent tool). Threaded into ToolContext so the Agent tool can
-     * refuse re-entry — defense in depth against the tool-list strip in
-     * spawn(): if a tool registry regression ever leaks Agent into a child's
-     * pool, the runtime check still blocks the call.
-     */
-    isSubAgent?: boolean;
-    /**
-     * Host/context that created this Engine's sessions — written to state.json's
-     * `origin` so the desktop disk-rebuild can filter the sidebar (desktop +
-     * automation shown; tui hidden). Sub-agents override to "subagent".
-     */
-    origin?: SessionOrigin;
-    /**
-     * Optional shared EngineRuntime providing pre-constructed shared resources
-     * (modelPool, toolRegistry, etc.). When provided, Engine uses these instead
-     * of constructing its own. Existing callers that omit this field continue to
-     * work unchanged — T11 will migrate them.
-     */
-    runtime?: EngineRuntime;
-    /**
-     * Which disk config layers this Engine may read. Defaults to 'project' —
-     * the safe default: a library/SDK embedding never silently inherits the
-     * host user's personal ~/.code-shell config (keys, models, MCP, hooks); it
-     * only reads the project-level ${cwd}/.code-shell that travels with a repo.
-     * Host-terminal entrypoints (TUI/desktop/CLI) pass 'full' to restore the
-     * managed+user+project+local behavior. 'isolated' reads no disk at all.
-     * Subagents inherit the parent Engine's scope. See SettingsScope.
-     */
-    settingsScope?: SettingsScope;
-}
+export type { EngineConfig, EngineHookConfig, EngineResult } from "./types.js";
+import type { EngineConfig, EngineResult } from "./types.js";
 export { diskDefaultsFrom, type DiskDefaultPatch } from "../settings/disk-defaults.js";
-export interface EngineHookConfig {
-    event: HookEventName;
-    handler: HookHandler;
-    priority?: number;
-    name?: string;
-}
-export interface EngineResult {
-    text: string;
-    reason: TerminalReason;
-    sessionId: string;
-    turnCount: number;
-    usage: TokenUsage;
-}
 /**
  * Resolve the LLM config for a spawned child Engine.
  * - `modelKey` set + present in pool → that model's config (pure entry-derived
@@ -162,6 +47,23 @@ export declare function resolveChildLlm(modelKey: string | undefined, pool: Mode
  *   2. user-level     ~/.code-shell/agents/*.md        (user wins on name)
  * Names in `disabledAgents` are filtered out so the LLM never sees them.
  */
+/**
+ * Resolve the working directory for a run. Precedence:
+ *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
+ *
+ * The session-cwd tier is what stops a project-bound session from being
+ * resumed against the wrong directory: when a host omits options.cwd (e.g. its
+ * sidebar repo selection drifted to null), the session's own recorded cwd is
+ * recovered so the engine still loads THAT project's agents/settings/memory,
+ * not whatever process.cwd() happens to be. Pure so the precedence is testable
+ * without standing up an Engine.
+ */
+export declare function resolveRunCwd(args: {
+    optionCwd?: string;
+    sessionCwd?: string;
+    configCwd?: string;
+    processCwd: string;
+}): string;
 export declare function loadAgentDefinitionsForCwd(cwd: string, disabledAgents?: string[], disabledPlugins?: string[]): AgentDefinitionRegistry;
 /**
  * #7: apply a project's per-turn builtin capability override to a tool list.
@@ -245,10 +147,49 @@ export declare class Engine {
      * LLM response arrives.
      */
     private ctxOverheadBySid;
+    /**
+     * Step-gap steering queue (per sessionId, in-memory). Host pushes user
+     * messages here via enqueueSteer while a run is in flight; the turn loop
+     * drains it at each step boundary and splices them into the next LLM request
+     * WITHOUT aborting (the 不打断 path, vs cancel+resend). Pure memory, forgotten
+     * on process exit — same model as the credential session-allow set, so
+     * multiple Engines don't interfere and it stays cleanly extractable.
+     */
+    private steerQueueBySid;
     private activePermission;
+    /**
+     * The TurnLoop of the in-flight run(), exposed so extendGoalRun() can bump a
+     * running goal's turn/budget ceilings mid-run (TODO 3.1). Null when idle.
+     */
+    private activeTurnLoop;
+    /**
+     * The goal-stop hook of the in-flight goal run, exposed so clearGoal() can
+     * unregister it mid-run (the closure holds the now-cleared goal and would
+     * otherwise keep re-blocking the stop). Null when no goal run is active.
+     */
+    private activeGoalHook;
+    /**
+     * The in-flight run's session bundle, held so clearGoal() can wipe the goal
+     * on the SAME instance the run loop is persisting each turn — not a fresh
+     * detached copy from resume(). Without this, a mid-run 清除 clears disk, but
+     * the still-running loop's next saveState(bundle.state) resurrects the goal
+     * (bundle.state.activeGoal was never dropped). A never-completing goal run
+     * (judge keeps returning not_met → continueSession) stays live for a long
+     * time, so this write-back race is the norm, not an edge case, for such runs.
+     * Single-valued like activeTurnLoop — one top-level run per engine at a time.
+     * Null when idle; set at run start, cleared in run's finally.
+     */
+    private activeRunSession;
     /** Public accessor so UI/clients can read the resolved per-model window. */
     get maxContextTokens(): number;
     private resolveMaxContextTokens;
+    /**
+     * Compaction thresholds from settings.context, clamped so they keep the
+     * required ordering floor < compact < summarize even if the user configures
+     * conflicting values (e.g. summarize below compact). Falls back to the
+     * ContextManager defaults when a field is absent.
+     */
+    private resolveContextRatios;
     /**
      * Emit a lifecycle hook with isSubAgent auto-merged into data so handlers
      * can skip noisy injections for spawned children. All Engine-side hook
@@ -279,20 +220,20 @@ export declare class Engine {
     reloadHooks(): void;
     constructor(config: EngineConfig);
     /**
-     * Load models[] / providers[] from settings into the active ModelPool and
+     * Load modelConnections[] from settings into the active ModelPool and
      * resync this.config.llm with the matching entry. Called from the ctor and
      * from reloadModelPool() (e.g. after onboarding writes new entries to disk).
      */
     private populateModelPoolFromSettings;
     /**
      * Re-read settings and refresh the model pool. Used after onboarding /login
-     * writes new providers[] / models[] to disk so the running engine picks them
+     * writes new modelConnections[] to disk so the running engine picks them
      * up without a process restart. Existing pool entries are kept (re-registering
      * the same key overwrites them), so callers don't need to clear first.
      */
     reloadModelPool(): void;
     /**
-     * Auto-populate the model pool when settings.models[] is empty but
+     * Auto-populate the model pool when no modelConnections[] are configured but
      * the user has configured an API key. Detects the provider from the
      * key prefix / baseUrl and registers all its known models.
      */
@@ -308,11 +249,51 @@ export declare class Engine {
      * before the server existed (chicken-and-egg: server takes engine in ctor).
      */
     setAskUser(fn: AskUserFn | undefined): void;
+    /**
+     * Inject the browser automation bridge after construction (same chicken-and-egg
+     * as setAskUser: the desktop host builds the bridge — which drives a webview —
+     * after the Engine exists). Undefined → the browser_* tools degrade with a
+     * clear "no browser panel" error.
+     */
+    setBrowserBridge(bridge: import("../tool-system/browser-bridge.js").BrowserBridge | undefined): void;
+    /**
+     * Queue a user message to be spliced into the in-flight run for `sessionId`
+     * at the next turn-loop step boundary — the 不打断 steering path (vs cancel +
+     * resend). General-purpose: any host path (UI 引导, future agent coordination,
+     * external triggers) can call it. If no run is active for the session the
+     * message simply waits in the queue and is consumed when that session next
+     * runs (rare race; host normally only steers while busy). No-op on blank text.
+     *
+     * `id` is the host's stable queue-entry id. It rides through to the
+     * `steer_injected` event (so the host can match the injected bubble back to
+     * the queued draft) and is the handle `unsteer` uses to revoke a still-pending
+     * entry. A blank id is tolerated but means the entry can't be revoked.
+     */
+    enqueueSteer(sessionId: string, text: string, id?: string): void;
+    /**
+     * Revoke a still-pending steer entry (the 撤回 path). Returns true if it was
+     * removed, false if it was already consumed by the turn loop (can't take it
+     * back — it has been spliced into the run).
+     */
+    unsteer(sessionId: string, id: string): boolean;
+    /** Drain + clear the steer queue for a session (turn loop consumes per step). */
+    private consumeSteer;
+    /** Wire the cookie→browser injection callback (InjectCredential tool). Same
+     *  post-construction injection model as setBrowserBridge. */
+    setInjectCredential(fn: import("../tool-system/context.js").InjectCredentialFn | undefined): void;
     /**
      * Whether this engine runs unattended (no interactive human). Used by the
      * in-process AgentServer to decide whether to wire an interactive askUser.
      */
     isHeadless(): boolean;
+    /**
+     * Probe whether a session already exists on disk (its state/transcript dir is
+     * present). Used by the protocol server to distinguish "resume an existing
+     * session" from "silently create a fresh empty one" — e.g. a cron resume job
+     * whose target session the user deleted must fail loudly, not run its prompt
+     * against a blank session. A stat probe, not a load.
+     */
+    sessionExistsOnDisk(sessionId: string): boolean;
     /**
      * Run a task from start to finish.
      */
@@ -328,6 +309,15 @@ export declare class Engine {
          * string or a full GoalConfig; normalized once at the run boundary.
          */
         goal?: string | GoalConfig;
+        /**
+         * Marks this turn's task as a SYNTHETIC system-reminder injection (e.g. a
+         * background-job completion notification the server re-injects to wake an
+         * idle session) rather than the user's own input. The task is still sent
+         * to the model as a `role:"user"` message, but it is persisted with an
+         * `injected` flag so the disk reader skips rendering it as a user bubble
+         * on replay (matching the live UI, which shows only the assistant reply).
+         */
+        injected?: boolean;
     }): Promise<EngineResult>;
     /**
      * Run the end-of-session memory pipeline as a fire-and-forget background
@@ -336,8 +326,8 @@ export declare class Engine {
      */
     /**
      * Resolve the LLM client for background/auxiliary work (memory extraction,
-     * auto-dream). When settings.auxModelKey names a valid pool model, build (and
-     * cache) a dedicated client for it so per-turn book-keeping runs on a cheap
+     * auto-dream). When settings.defaults.auxText names a valid pool model, build
+     * (and cache) a dedicated client for it so per-turn book-keeping runs on a cheap
      * fast model instead of the expensive primary. Falls back to `fallback` (the
      * active run's client) when unset, unknown, or on any build failure — aux
      * work is best-effort and must never break a run.
@@ -366,20 +356,26 @@ export declare class Engine {
      * Switch the active model by pool key. Takes effect on the next run() call.
      * Returns the new model entry.
      *
-     * Persists settings.activeKey (and a legacy settings.model.* mirror) so the
+     * Persists settings.defaults.text (= the connection id / pool key) so the
      * next process startup defaults to the same model — without this, switches
      * only live in memory and every restart reverts to the previously persisted
-     * activeKey.
+     * defaults.text.
      */
     switchModel(key: string): ModelEntry;
+    /**
+     * Zero a session's cumulative token/cache usage on disk. Called on a model
+     * switch: a different model has its own prompt cache, so the accumulated
+     * cache-hit stats from the prior model are no longer meaningful. The next
+     * run's baseline (snapshotted from state.tokenUsage) then starts from zero.
+     */
+    resetSessionUsage(sessionId: string): void;
     /**
      * Write the active model selection to ~/.code-shell/settings.json.
      *
-     * We mirror into the legacy settings.model.* block (provider/name/apiKey/
-     * baseUrl) because boot paths in cli/main.ts, repl.ts, run.ts still read it.
-     * The mirror uses resolved llm values (not raw entry.*) so credentials that
-     * live on settings.providers[] flow through correctly — entry.apiKey is
-     * undefined when the entry resolves via providerCatalog.
+     * Persists settings.defaults.text = entry.key (the connection id == pool
+     * key). That is the single field the boot path reads to restore the active
+     * text model on the next startup (see ctor: settings.defaults.text → pool
+     * switch). No legacy activeKey/model.* mirror is written.
      */
     private persistActiveModel;
     /** Get the model pool. */
@@ -401,12 +397,10 @@ export declare class Engine {
      * payloads are dropped so out-of-order reload deliveries can't let an older
      * config clobber a newer one (Q5).
      *
-     * MCP: only connects (idempotent — already-connected servers are skipped);
-     * never disconnects, so an in-flight tool call on an existing server is
-     * never severed (Q3). Removed servers are deferred to the next session
-     * rebuild. If mcpManager isn't built yet (no MCP run has happened), the
-     * new servers will be connected on the next run via the existing per-run
-     * connectAll path — so we skip the connect here.
+     * MCP: reconciles the shared MCP pool against the new disk-default server
+     * set. Added servers connect idempotently; removed/disabled servers are
+     * disconnected and their registered MCP tools are unregistered so plugin
+     * disable takes effect without an Electron restart.
      *
      * Preset (#2): a preset hot-reload re-resolves `this.preset` so the next-turn
      * PromptComposer picks up the new preset's system prompt / behavior — that's
@@ -436,6 +430,26 @@ export declare class Engine {
      * engine.run() call for this session picks up the injected content
      * instead of a stale snapshot from the previous run.
      */
+    /**
+     * Read a session's persisted active goal WITHOUT resuming it (cheap — reads
+     * only state.json via SessionManager.readActiveGoal). The desktop host calls
+     * this on session load to re-surface the goal block + its Cancel button: a
+     * persistent goal lives only in state.activeGoal and is never replayed from
+     * the transcript, so after a reload of an aborted goal run the UI would
+     * otherwise show nothing (the "goal 还在但页面不显示、取消不了" bug). Returns
+     * undefined when the session is unknown or has no active goal.
+     */
+    getGoal(sessionId: string): GoalConfig | undefined;
+    /**
+     * Clear a session's persisted active goal (CC `/goal clear`). Works whether
+     * the session is idle or its goal run is in flight: it wipes
+     * `state.activeGoal` (so the next bare send won't re-inherit it) and, if a
+     * goal hook is currently registered for this engine, unregisters it so an
+     * in-flight run can stop instead of being re-blocked by the now-cleared goal.
+     * Returns true if a goal was actually cleared. Idempotent — clearing a
+     * session with no active goal is a no-op returning false.
+     */
+    clearGoal(sessionId: string): boolean;
     injectContext(sessionId: string, content: string): void;
     /**
      * Force context compaction on the current session.
@@ -466,6 +480,25 @@ export declare class Engine {
      */
     setPermissionMode(mode: NonNullable<EngineConfig["permissionMode"]>): void;
     getPermissionMode(): NonNullable<EngineConfig["permissionMode"]>;
+    /**
+     * Extend the in-flight run's turn ceiling and/or goal budgets (TODO 3.1 —
+     * 运行中续轮/加预算). No-op (returns null) when no run is active. Lets a user
+     * keep an unattended goal going past its original cap instead of restarting.
+     */
+    extendGoalRun(opts: GoalExtension): {
+        maxTurns: number;
+        tokenBudget?: number;
+        timeBudgetMs?: number;
+        maxStopBlocks: number;
+    } | null;
+    /**
+     * The effective permission rules for the current mode + cwd (TODO 5.1) —
+     * preset defaults + mode-derived + settings.permissions.rules, in the same
+     * order the classifier evaluates them. Exposed read-only so `/permissions`
+     * (and any UI) can list what's actually in force. Pure read; builds the same
+     * rule set buildPermissionConfig does, without constructing a backend.
+     */
+    getPermissionRules(): import("../types.js").PermissionRule[];
     /**
      * Toggle plan mode directly. Called by the Plan tool (Task 7) via ToolContext.engine.
      * Also syncs permissionMode to keep both fields consistent.
@@ -489,6 +522,14 @@ export declare class Engine {
      * both. Subscribe-before-await closes the check/wait race either way.
      */
     private waitForBackgroundAgentChange;
+    /**
+     * Like waitForBackgroundAgentChange but with no abort signal and a hard
+     * timeout. Resolves `true` on a registry/queue change, `false` if `timeoutMs`
+     * elapses first. Used only by the headless abort-drain cleanup, where we want
+     * to catch a completing agent's just-about-to-enqueue notification without
+     * risking a permanent hang on an agent that never completes.
+     */
+    private waitForBackgroundAgentChangeOrTimeout;
     /**
      * Sub-agent role registry for the given cwd, memoized per-cwd so the
      * directory is read once rather than every turn. A new cwd (e.g. via
@@ -519,6 +560,58 @@ export declare class Engine {
      * by tests that want a ToolContext without a full run() cycle.
      */
     private resolveSandboxWithoutRuntime;
+    /**
+     * Build the shell env layered onto the Bash tool / background shells (see
+     * mergeShellEnv). Three user-configured sources, merged lowest → highest:
+     *
+     *   1. project `localEnvironment.env`  — the per-project "local environment"
+     *      panel (DATABASE_URL etc.); the floor, so a project's own panel values
+     *      can be overridden by an explicit top-level `env`.
+     *   2. global top-level `env`          — ~/.code-shell/settings.json; the
+     *      canonical home for API keys (OPENAI_API_KEY) a skill script reads —
+     *      configure once, every project's skills get it.
+     *   3. project top-level `env`         — .code-shell/settings.json; a project
+     *      that wants to override a global key wins.
+     *
+     * Each scope is read UNMERGED so the layering here is the single source of
+     * precedence (getForScope merges nothing). Returns undefined when no layer
+     * contributes a key, so the caller passes it through unchanged for projects
+     * that configure none.
+     *
+     * Sub-agents: a sub-agent is the user's OWN agent doing the user's work
+     * (mirrors Claude Code, where sub-agents inherit the parent environment), so
+     * it now reads the SAME env as the parent. The sub-agent branch is kept as an
+     * explicit seam (`filterSubagentEnv`) rather than removed — a future policy
+     * could narrow what a sub-agent sees (e.g. drop credential secrets) by
+     * changing that one hook; today it passes everything through unchanged.
+     * A no-cwd context still gets nothing (there is genuinely no project to read).
+     *
+     * None of these is filtered through the deny regex (mergeShellEnv): the user
+     * put them there deliberately. The allowlist/deny machinery only guards the
+     * host's process.env from a tainted model exfiltrating it via `env | curl`.
+     */
+    private readShellEnv;
+    /**
+     * Policy seam for what a sub-agent's shell sees. A sub-agent inherits the
+     * parent environment by default (mirrors Claude Code), so this is the
+     * identity function today. It exists so a future policy can narrow the set
+     * (e.g. strip credential `exposeAsEnv` secrets, or allowlist by name) in ONE
+     * place instead of scattering `isSubAgent` checks through readShellEnv.
+     */
+    private filterSubagentEnv;
+    /**
+     * Read the project's `localEnvironment.setupScripts` for this cwd (the raw
+     * per-platform map). Used by EnterWorktree to run setup once in a freshly
+     * created worktree. Returns undefined for sub-agents / no cwd (same minimal
+     * surface as readShellEnv). The platform selection + run live in
+     * git/worktree.ts; this only fetches the configured scripts.
+     */
+    readWorktreeSetupScripts(cwd?: string): {
+        default?: string;
+        macos?: string;
+        linux?: string;
+        windows?: string;
+    } | undefined;
     buildToolContext(): ToolContext;
     /**
      * Read settings.disabledSkills + settings.disabledPlugins in a single
@@ -532,4 +625,40 @@ export declare class Engine {
      * the same snapshot.
      */
     private readDisabledLists;
+    /**
+     * Public view of the folded disabled lists, for hosts that need the
+     * EFFECTIVE state (e.g. the protocol server's settings hot-reload rebuilds
+     * the plugin-MCP merge per session — a project-level "on" must override the
+     * global disabledPlugins there too).
+     */
+    getEffectiveDisabledLists(): {
+        disabledSkills: string[];
+        disabledPlugins: string[];
+    };
+    /**
+     * Public: resolve every known feature flag to its effective boolean (the
+     * settings overlay merged over the compiled-in defaults). Used by the
+     * `config` protocol query so the `/features` command can list flag state.
+     */
+    getFeatureFlags(): Record<FeatureFlagName, boolean>;
+    /**
+     * Read the merged `settings.featureFlags` overlay for this cwd. Project
+     * settings override user settings via the normal SettingsManager merge.
+     * Returns undefined (→ all defaults) on any read error or for sub-agents,
+     * so a flag check never throws and a child runs with default behavior.
+     */
+    private readFeatureFlags;
+    /**
+     * Read settings.memories ({ maxCount, maxAge, extractionModel, autoExtract }).
+     * Returns undefined on any error or when absent, so the memory pipeline
+     * falls back to its built-in defaults.
+     */
+    private readMemoriesConfig;
+    /**
+     * LLM client for memory extraction (TODO 8.1). Prefers
+     * settings.memories.extractionModel when it names a valid pool model;
+     * otherwise falls back to the aux client (which itself falls back to the
+     * passed primary). Build failures fall back too — extraction is best-effort.
+     */
+    private resolveExtractionClient;
 }