dsh-loop-engine-allinone 0.0.0-stage → 0.4.0

package/lib/types/client/session-engine.d.ts

@@ -0,0 +1,508 @@
+/**
+ * Per-session engine, browser half: read the engine a session actually runs
+ * from the plugin's OWN Remote, and switch it through that same Remote.
+ *
+ * The engine a session runs is NOT a client-cache fact, and reading one as if it
+ * were is the bug this module exists to prevent. The harness hands a page a
+ * projection HINT per session (`@deepseek-ai/dsh-api-session-controller`'s
+ * `projectionsFor()` returns `SessionProjectionHints`: "every currently cached
+ * wire value", partial by its own documentation), and its `agentPreset` cell
+ * answers a different question than "what does this session run": a session may
+ * switch engine while it is blank (and, with this plugin, at any time), and that
+ * choice lives in the plugin's own record while the session header keeps naming
+ * the preset the session was CREATED with. A page reading the hint therefore
+ * shows a claude-code session that switched to pi — and the engine it actually
+ * runs — as Claude Code, the misreport this plugin shipped a production incident
+ * for.
+ *
+ * So the browser half asks the host instead:
+ * `remote.loopEngine.engine({ sessionId })` to read, and
+ * `remote.loopEngine.select({ sessionId, engine })` to switch — the endpoints
+ * `src/engine-remote.ts` serves from the same read the router routes on. Nothing
+ * is derived here: the three-state arrives decided, and a refused switch arrives
+ * with the host's own reason.
+ *
+ * This module is deliberately React-free: the cache, the contribution, and the
+ * switch are plain logic, so they run in node under its own spec
+ * (`tests/session-engine-cache.spec.ts`). The one part that needs a component to
+ * render — the hook that subscribes a surface to the cache — lives in
+ * `./use-session-engine.ts`.
+ *
+ * The cache owns NO document-level side effect, deliberately. The chat
+ * turn-status row is painted through a document-level attribute
+ * (`./turn-status.ts`), so the only writer entitled to it is the session on
+ * screen — and this cache publishes for every session a surface has ever
+ * watched, the session the user just left included. Reflecting from
+ * `publish` therefore let a background session's (or a left session's late)
+ * answer take the attribute over from the session on screen, which painted ITS
+ * engine onto the row beside it — a session running pi drew Kimi's moon. The
+ * reflection is driven from `./use-session-engine.ts` instead: that hook is
+ * where a component knows which session it is the surface of, and the reflection
+ * it makes carries a focus guard. Here the cache answers one question only —
+ * what one session's engine is.
+ *
+ * One member of the framework's standard seat is still read from the slot props:
+ * the session-scope `sessionId`. The harness declares it by declaration-merging
+ * `SessionStandardProps` in `@deepseek-ai/dsh-client-ui-session/client`, and its
+ * published declarations elide the type-only imports that carry the merge — so a
+ * half compiled against the installed artifacts (this package's
+ * `tsconfig.build.json` pins `@deepseek-ai/*` to the artifact plane) never sees
+ * it. It is therefore restated structurally here, in the shape the harness
+ * declares (`packages/client/ui-session/src/client/index.ts`), and the
+ * components assert it off their slot props. The `useSessions` hook needs no
+ * such restatement any more: nothing here reads the session list.
+ *
+ * The Remote's client-side types are restated structurally for the same reason
+ * and one more: a third-party plugin cannot reach the main repository's
+ * generated `typert.remote-client.d.ts`, and it does not need to — the protocol
+ * has no schema registry, so a contribution is plain data (see
+ * `LOOP_ENGINE_REMOTE_CONTRIBUTION`).
+ *
+ * @module dsh-loop-engine-allinone/client/session-engine
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type LoopEngineId, type LoopEngineRefusalCode, type LoopEngineSelectResult, type SessionEngine, type SessionEngineReport } from '../agent-preset-ids.ts';
+import { type ReloadPage } from './reload.ts';
+/**
+ * The three-state engine answer, re-exported so the client half names one type.
+ * It is DEFINED in the zero-import shared module: the node half decides it
+ * (`src/engine-of-session.ts`) and this half only renders what it is told.
+ */
+export type { SessionEngine } from '../agent-preset-ids.ts';
+/**
+ * What one session's engine read answers: the engine it ACTUALLY runs, plus the
+ * engine a committed switch has recorded for it but not yet reached.
+ *
+ * Re-exported for the same reason as the three-state: the split between the two
+ * facts is decided on the host (`src/engine-of-session.ts`) and this half renders
+ * both without ever merging them — the pending engine belongs in a "not in force
+ * yet" marker, never in the place that names what the session runs.
+ */
+export type { SessionEngineReport } from '../agent-preset-ids.ts';
+/**
+ * The standard seat members this half reads off a session-scope slot.
+ *
+ * The identity, plus the one live fact the turn-status row needs: whether the
+ * session is mid-turn. The engine itself is no longer read from a framework
+ * hook, it is asked of the host through this plugin's own Remote.
+ */
+export interface SessionSeat {
+    /**
+     * Current Session identity. Undefined only off a seat rendered without a
+     * session: the composer then picks the new-session default, and the header chip
+     * (which only ever renders with a session) shows nothing.
+     */
+    sessionId?: string;
+    /**
+     * Selector hook over the current Session's snapshot (`SessionStandardProps` of
+     * every session-scoped seat). Optional for the same reason as the identity: a
+     * caller with no such seat — or a test rendering one directly — has none, and
+     * the turn-status gate is then left alone rather than guessed.
+     */
+    useSession?: SnapshotSelector;
+}
+/**
+ * The selector-hook shape this half needs from `useSession`: a read of one field
+ * of the Session snapshot, with no equality function of its own.
+ */
+export type SnapshotSelector = <S>(select: (snapshot: SessionRunningState) => S) => S;
+/** The one field of the Session snapshot the turn-status row reads. */
+export interface SessionRunningState {
+    /** Whether a turn is in flight for this session. */
+    readonly running: boolean;
+}
+/** Cordis service key AND wire namespace of the plugin's own Remote. */
+export declare const LOOP_ENGINE_REMOTE_NAMESPACE = "loopEngine";
+/** Reporting endpoint of the plugin's own Remote (mirrors `src/engine-remote.ts`). */
+export declare const LOOP_ENGINE_REMOTE_METHOD = "engine";
+/** Switching endpoint of the plugin's own Remote (mirrors `src/engine-remote.ts`). */
+export declare const LOOP_ENGINE_REMOTE_SELECT_METHOD = "select";
+/** One refused Remote call (harness: the error branch of `RemoteResult`). */
+export interface RemoteFailure {
+    /** The host's own framing of the refusal. */
+    readonly message: string;
+    /** The refusal's detail map; a `reason` entry carries the unframed cause. */
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/** What `remote.loopEngine.engine` resolves to (harness: `RemoteResult<SessionEngineReport>`). */
+export type SessionEngineResult = {
+    readonly ok: true;
+    readonly value: SessionEngineReport;
+} | {
+    readonly ok: false;
+    readonly error: RemoteFailure;
+};
+/** What `remote.loopEngine.select` resolves to (harness: `RemoteResult<LoopEngineSelectResult>`). */
+export type EngineSelectResult = {
+    readonly ok: true;
+    readonly value: LoopEngineSelectResult;
+} | {
+    readonly ok: false;
+    readonly error: RemoteFailure;
+};
+/** This plugin's own Remote namespace, as the browser half calls it. */
+export interface SessionEngineRemote {
+    /** Report the engine one session runs (and the recorded engine it is not running, if any). */
+    engine(request: {
+        readonly sessionId: string;
+    }): Promise<SessionEngineResult>;
+    /** Move one session to another engine, or answer why it was not moved. */
+    select(request: {
+        readonly sessionId: string;
+        readonly engine: LoopEngineId;
+    }): Promise<EngineSelectResult>;
+}
+/** Outcome of one per-session engine switch, ready to render. */
+export type SessionSwitchResult = {
+    readonly ok: true;
+    /**
+     * Present when the host made the switch land by RELEASING the session's
+     * agent — a change with the harness loop on either side of it. This page has
+     * already been reloaded (and the session remembered for the page that
+     * replaces it) by the time a caller sees this, so a surface renders it as
+     * "the switch is happening" rather than as a session that can be typed into.
+     */
+    readonly reload?: true;
+}
+/** This page cannot reach the plugin's own Remote at all. */
+ | {
+    readonly ok: false;
+    readonly kind: 'unavailable';
+}
+/**
+ * The host refused the switch. `code` says which refusal it was, for the
+ * surface to render in the user's language, and `reason` is the host's own
+ * sentence about this session — detail under that copy, or the whole message
+ * when the code is absent (an unknown code, a rejected CALL, a lost
+ * connection: none of those has a refusal code, and none of them may leave the
+ * surface with nothing to show).
+ */
+ | {
+    readonly ok: false;
+    readonly kind: 'refused';
+    readonly reason: string;
+    readonly code?: LoopEngineRefusalCode;
+};
+/** Move one session to another engine. */
+export type SessionEngineSwitcher = (sessionId: string, engine: LoopEngineId) => Promise<SessionSwitchResult>;
+/**
+ * Whether a pick on one session's engine can be committed at all — that is,
+ * whether the host has answered what that session runs.
+ *
+ * This is the composer's usability gate, and it is hostile to guessing on
+ * purpose. The reload judgement below is a statement about two engines, and with
+ * no answer there is nothing honest to state: an unknown session may reload in
+ * EITHER direction. Answering the question anyway would cost the user something
+ * either way — `true` raises a confirmation for a switch that may not reload
+ * (and the confirmation is the only thing keeping an UNEXPLAINED reload from
+ * looking like a glitch), while `false` commits a pick that reloads and takes
+ * this page's unsent draft with it. So the picker is simply not usable until the
+ * answer lands: the trigger is greyed out with its menu unopenable, and it keeps
+ * reading「读取中…」so the user can see what it is waiting for. The instant the
+ * answer arrives the control becomes usable, unchanged.
+ *
+ * It is a TYPE PREDICATE as well as the runtime gate, so "no pick is ever judged
+ * against an unknown engine" is enforced by the compiler: the composer narrows a
+ * session's report through this before it asks {@link switchNeedsReload}, whose
+ * parameter therefore cannot be undefined.
+ *
+ * A seat with NO session is not this function's business and never calls it: it
+ * writes the default for sessions created later, moves nothing, and reloads
+ * nothing, so there is no engine to wait for.
+ * @param report - the session's engine report, or undefined while the host has
+ * not answered yet (or cannot answer at all).
+ * @returns whether the engine is known — the one condition under which a pick on
+ * that session may be judged and sent.
+ */
+export declare function engineSwitchReady(report: SessionEngineReport | undefined): report is SessionEngineReport;
+/**
+ * Whether moving a session from `current` to `target` has to land through a page
+ * reload — the one thing a surface must ask the user about BEFORE it commits,
+ * because the reload is what takes this page's unsent draft and scroll position
+ * with it.
+ *
+ * The rule is the host's own split (`src/router-loop.ts` `move`): a move with the
+ * harness loop on EITHER side cannot be handed over in place — `AgentLoop` neither
+ * hands a live session over nor accepts one it did not create — so the session's
+ * agent is released, the session goes cold, and the page reloads to rebuild it on
+ * the recorded engine. Between two hosted engines nothing reloads: the agent is
+ * swapped in place and the conversation stays open. So the move reloads exactly
+ * when the two engines differ in being the in-process one.
+ *
+ * `current` is the engine the session ACTUALLY runs — the report's `engine`, never
+ * the engine its record names, which is why this takes a {@link SessionEngine} and
+ * not a bare id:
+ *
+ *  - a state that names an engine answers the rule above directly;
+ *  - `legacy` and `unset` name no engine, and both are built on the in-process
+ *    loop (`src/agent-preset-ids.ts` `hostedEngineOf` — the router falls back to
+ *    the harness loop for a preset this plugin does not own), so they are read as
+ *    the in-process side of the rule rather than as "unknown": picking any hosted
+ *    engine on such a session really does reload.
+ *
+ * There is deliberately NO third branch for "the host has not answered yet": that
+ * state never reaches here, because the composer gates every pick on
+ * {@link engineSwitchReady} first (the picker is disabled until the answer lands),
+ * and the parameter's non-optional type is what holds that down. A judgement made
+ * without an answer would be a guess in one direction or the other, which is
+ * exactly what the gate exists to avoid.
+ *
+ * It is a pure function of the two engines on purpose: the composer's confirmation
+ * is only as trustworthy as this judgement, and this way it is pinned by a test
+ * rather than by reading the component.
+ * @param current - the engine the session runs now, as the host reports it. Never
+ * unknown: callers hold a report that passed {@link engineSwitchReady}.
+ * @param target - the engine the user picked.
+ * @returns whether committing that pick releases the session's agent and reloads
+ * this page.
+ */
+export declare function switchNeedsReload(current: SessionEngine, target: LoopEngineId): boolean;
+/** One boundary schema of a wire field (a zod schema, as the Gateway holds it). */
+interface RemoteSchema {
+    parse(value: unknown): unknown;
+}
+/**
+ * A codec of one wire field (harness: `TypertCodec`, strict branch).
+ *
+ * The two harness generations read DIFFERENT members of this object and each
+ * validates only its own: the 0.1.5 line's registry and client parse through
+ * `schema`, while the 0.1.7 line's registry requires a `create()` factory and
+ * parses through `codec.create()` (`typert: … strict codec has no create()
+ * factory`). One build serves both, so the codec carries both fields.
+ */
+interface RemoteCodec {
+    readonly mode: 'strict';
+    /** Stable identity of the field's declared type, for diagnostics. */
+    readonly typeSymbol: string;
+    /** The 0.1.5 line's read: the boundary schema itself. */
+    readonly schema: RemoteSchema;
+    /**
+     * The 0.1.7 line's read: a factory returning the boundary schema.
+     * @returns the same boundary schema.
+     */
+    readonly create: () => RemoteSchema;
+}
+/** One ordered business parameter (harness: `InvocationParameterDescriptor`). */
+interface RemoteParameter {
+    readonly name: string;
+    /** Wire field this parameter occupies in `args`. */
+    readonly wire: string;
+    readonly source: 'json';
+    readonly codec: RemoteCodec;
+}
+/** One exported method (harness: `InvocationDescriptor`). */
+interface RemoteMethod {
+    readonly id: string;
+    readonly service: string;
+    readonly namespace: string;
+    readonly method: string;
+    readonly invocation: {
+        readonly kind: 'direct';
+    };
+    readonly parameters: readonly RemoteParameter[];
+    readonly result: RemoteCodec;
+}
+/** One package's exported methods (harness: `TypertRemoteContribution`). */
+export interface RemoteContribution {
+    readonly package: string;
+    readonly descriptors: readonly RemoteMethod[];
+}
+/** The Client Remote service, as much of it as this half calls (harness: `ClientRemote`). */
+export interface EngineRemoteHost {
+    /** Install one contribution's namespaces for the calling fiber. */
+    $mount(contribution: RemoteContribution): Promise<() => Promise<void>>;
+}
+/** The plugin's npm package name, as the contribution identifies itself. */
+export declare const LOOP_ENGINE_PACKAGE = "dsh-loop-engine-allinone";
+/** The plugin's own Remote, declared for the Gateway's client mount. */
+export declare const LOOP_ENGINE_REMOTE_CONTRIBUTION: RemoteContribution;
+/**
+ * What one session's engine is, cached per session.
+ *
+ * Every read goes to the host's authoritative answer and is cached by session id
+ * so the chip and the composer in the same header cannot disagree. Until the
+ * first answer arrives a session has NO engine here: {@link read} returns
+ * undefined, and the surfaces render nothing (chip) or a neutral loading state
+ * (composer) rather than a guess — a default or a list hint would be exactly the
+ * misreport this class exists to end.
+ *
+ * What is cached is the whole {@link SessionEngineReport}, the recorded engine
+ * that differs from the live one included, because the three surfaces read
+ * different halves of it: the chip, the composer's label, and the chat
+ * turn-status row all name the engine the session RUNS, and only the first two
+ * also carry the "recorded, not in force" marker. Merging the two here would
+ * make that distinction unavailable downstream; leaving the report intact lets
+ * each surface take the half it renders.
+ *
+ * A cached answer is never treated as final for the page's lifetime: a session
+ * the user comes back to is re-read when its surfaces appear again
+ * ({@link watch} → {@link refresh}). Coming back does not move the session — a
+ * switch is performed on the host, between hosted engines it swaps the agent in
+ * place, and the direction that has to release the session reloads this very
+ * page (`./reload.ts`) — but the answer this page holds is still only one this
+ * page took earlier: another window, a hot swap performed elsewhere, or a plugin
+ * reload can have moved the session since. The answer a surface holds is
+ * therefore correct for as long as that surface is on screen, and refreshed at
+ * every re-mount — not only when a switch this page performed invalidated it
+ * ({@link invalidate}).
+ *
+ * Its answer is also what the chat turn-status row draws (the third place a
+ * session's engine is shown), but through the surfaces rather than through this
+ * class: the row follows the session on screen because the hook both surfaces
+ * share reflects that session's answer with a focus guard — the same authority
+ * the chip and the composer read, where the settings default it used to follow
+ * was not. Nothing here writes to the document; see `./turn-status.ts` and
+ * `./use-session-engine.ts`.
+ */
+export declare class SessionEngineCache {
+    private readonly engines;
+    private readonly watchers;
+    private readonly reading;
+    /**
+     * Monotonic read generation per session. A read started before an
+     * invalidation describes the session as it was BEFORE the switch, so however
+     * late it settles it must not publish — publishing it would put the old engine
+     * back on screen, which is the very misreport this cache exists to prevent.
+     */
+    private readonly generations;
+    private remote;
+    private disposed;
+    /**
+     * Attach the mounted Remote namespace. Values asked for before the mount
+     * settled are re-read, so a surface that mounted first is not left loading.
+     * @param remote - the namespace, or undefined when the mount failed.
+     */
+    attach(remote: SessionEngineRemote | undefined): void;
+    /**
+     * The engine report cached for one session, or undefined while the first
+     * answer is still in flight (or when the host could not answer at all).
+     * @param sessionId - the session whose engine is asked for.
+     * @returns the authoritative report, cached by session id.
+     */
+    read(sessionId: string): SessionEngineReport | undefined;
+    /**
+     * Follow one session's engine, re-reading it whenever a session's surfaces
+     * appear again.
+     *
+     * A watch is a surface appearing for this session, and that is the moment the
+     * cached answer can be stale in a way nothing else reports: a session whose
+     * surfaces all went away and came back — the page switched to another session
+     * and back — must not render what the page cached before. A re-mount is not
+     * what moves a session's engine (a switch is performed on the host, and either
+     * swaps the agent in place or releases the session and reloads this page), but
+     * the page's answer is old by then, and a surface that rendered it as current
+     * would be the one lying about what runs.
+     *
+     * Only the FIRST watcher of a session triggers the re-read, which is what
+     * makes this "the session's surfaces appeared" rather than "a component
+     * rendered": the chip and the composer are two watchers of one session, and
+     * the second joins the read the first one started instead of sending its own.
+     * While a session keeps its surfaces, nothing here asks again — the answer only
+     * changes through {@link invalidate} (a committed switch) or a later re-mount.
+     * @param sessionId - the session to follow.
+     * @param listener - called whenever that session's cached state changes.
+     * @returns the unsubscribe.
+     */
+    watch(sessionId: string, listener: () => void): () => void;
+    /**
+     * Ask the host for one session's engine report again, superseding nothing.
+     *
+     * This is the way a surface that has just been rendered asks "is what this page
+     * cached still what runs?" — the answer that can go stale without anyone
+     * invalidating it, because the page is not the only thing that can move a
+     * session (another window, a hot swap elsewhere, a plugin reload).
+     * A read already in flight for that session is joined rather than replaced (it
+     * was started no earlier than this call and describes the same moment), and the
+     * cached answer is kept until the new one lands, so a re-read never blinks the
+     * chip back to "reading". Use {@link invalidate} instead for an answer that is
+     * known to be WRONG.
+     * @param sessionId - the session whose answer should be re-read.
+     */
+    refresh(sessionId: string): void;
+    /**
+     * Forget one session's cached engine and ask the host again.
+     *
+     * A successful engine switch changes what the host answers for that session,
+     * so the picker MUST come through here: without it the composer would keep
+     * showing the engine the session no longer runs. Any read already in flight
+     * for that session is superseded and can no longer publish.
+     * @param sessionId - the session whose answer is now stale.
+     */
+    invalidate(sessionId: string): void;
+    /** Drop every cached answer and notification (plugin unload). */
+    dispose(): void;
+    /**
+     * Ask unless the session is already answered, being read, or unanswerable.
+     *
+     * For the paths that need an answer and have none: the plugin's mount settling
+     * (a surface asked before the Remote existed), a session whose cached answer
+     * was just dropped — and never a re-read of an answer this page already holds,
+     * which is {@link refresh}'s job and only a freshly rendered surface may ask
+     * for.
+     */
+    private readIfUnknown;
+    /**
+     * Start one read for a session, unless there is nothing to read it with.
+     * @param sessionId - the session to read.
+     */
+    private start;
+    /**
+     * One read, quiet on failure: a session the host cannot answer for stays
+     * unknown, and the surfaces keep their neutral state instead of claiming an
+     * engine. A refusal is not cached as an answer, so the next watch re-asks.
+     * @param remote - the mounted namespace.
+     * @param sessionId - the session asked about.
+     * @param generation - the read generation this answer belongs to.
+     */
+    private ask;
+    /**
+     * Notify one session's watchers.
+     *
+     * Nothing is painted here. The session's engine shows up in the chat
+     * turn-status row too, but that row hangs off a DOCUMENT-level attribute, whose
+     * only entitled owner is the session on screen — and a publish says nothing
+     * about what is on screen (this is called for every session a surface has ever
+     * watched, and for a session the user has already left, when its late answer
+     * lands). So painting here let a background session take the attribute over
+     * from the session on screen. The surfaces reflect instead, with the focus
+     * guard in `./turn-status.ts`; this is the notification the chip and the
+     * composer wake up on.
+     */
+    private publish;
+}
+/**
+ * Mount this plugin's own engine Remote and return the cache the session
+ * surfaces render from.
+ *
+ * `remote` is taken lazily rather than declared in the client half's `inject`:
+ * the settings page must keep working on a page that composes no Gateway, and
+ * the two session surfaces degrade to "engine not recorded" — never to a guess.
+ * @param ctx - the client root context.
+ * @returns the cache both session surfaces and the switcher share.
+ */
+export declare function createSessionEngineCache(ctx: ClientContext): SessionEngineCache;
+/**
+ * Build the per-session switch over this plugin's own Remote.
+ *
+ * Every refusal is reported rather than thrown: the host's own reason when it
+ * refused (the session is not open, it is mid-turn, it belongs to subagent
+ * routing, or the engine record could not be written), and this page's own words
+ * when the namespace is not reachable. A switch that DID land drops the cached
+ * answer, because the host's read for that session just changed.
+ *
+ * A switch the host had to make by RELEASING the session's agent is finished
+ * here rather than reported: the page is reloaded — the only action that clears
+ * the client state a `session/disposed` leaves behind — and the session is
+ * stashed for the page that replaces it, so the reload lands back on it
+ * (`./reload.ts` explains why each half is necessary). That is why this function
+ * owns the reload instead of leaving it to a component: it is the one place that
+ * knows the host released the agent, and it keeps the sequence (invalidate →
+ * stash → reload) in one testable step.
+ * @param ctx - the client context carrying the Remote namespace.
+ * @param onSwitched - called with the session id once the host accepted the
+ *   switch, so the caller can drop the cached engine it just changed.
+ * @param page - the page to reload and to stash the return in.
+ * @returns the switch the composer's picker commits through.
+ */
+export declare function sessionEngineSwitcher(ctx: ClientContext, onSwitched?: (sessionId: string) => void, page?: ReloadPage): SessionEngineSwitcher;
+//# sourceMappingURL=session-engine.d.ts.map

package/lib/types/client/store.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Loop engine selection store: a settings transport is the channel, and the
+ * store publishes a render-safe snapshot plus the write path. The transport is
+ * abstracted so one store follows either generation's client service — the
+ * 0.1.7 `ConfigForm` for the plugin's own profile entry, or the 0.1.5
+ * `SettingsScope` for its `agent-loop-engine` settings section.
+ * @module dsh-loop-engine-allinone/client/store
+ */
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { LoopEngineId } from '../agent-preset-ids.ts';
+import type { LoopEngineSettings } from '../settings.ts';
+/** State rendered by the loop engine section. */
+export interface LoopEngineState {
+    status: 'loading' | 'ready' | 'unavailable' | 'saving';
+    engine: LoopEngineId;
+    showInComposer: boolean;
+    showEngineBadge: boolean;
+    writable: boolean;
+    error: string | null;
+}
+/** The render-relevant slice of a settings snapshot, shared by both generations' transports. */
+export interface LoopEngineSettingsSnapshot {
+    status: 'loading' | 'ready' | 'unavailable';
+    value: LoopEngineSettings | undefined;
+    writable: boolean;
+}
+/**
+ * The settings channel the store follows. Satisfied by the 0.1.7 `ConfigForm`
+ * and by the 0.1.5 `SettingsScope` (through a thin adapter in `./index.ts`); the
+ * write's boolean is optional because the 0.1.5 scope reports acceptance only
+ * through the snapshot it leaves behind.
+ */
+export interface LoopEngineSettingsTransport {
+    /** @returns the current sync snapshot. */
+    getSnapshot(): LoopEngineSettingsSnapshot;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing the listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Persist one field.
+     * @param field - the field to write.
+     * @param value - the value to write.
+     * @returns whether the write was accepted, when the transport reports it.
+     */
+    set(field: 'engine' | 'showInComposer' | 'showEngineBadge', value: unknown): Promise<boolean | void>;
+}
+/**
+ * Narrow a wire section to the stored engine id and display toggles; an invalid
+ * one reads default. Used by the 0.1.5 `settingsScope.bind` decoder, whose scope
+ * receives raw wire sections.
+ * @param section - the wire section value.
+ * @returns the decoded selection, or `undefined` when the section is unusable.
+ */
+export declare function decodeLoopEngine(section: unknown): {
+    engine: LoopEngineId;
+    showInComposer: boolean;
+    showEngineBadge: boolean;
+} | undefined;
+/** Coordinates the settings-backed loop engine selection. */
+export declare class LoopEngineStore {
+    private readonly transport;
+    /** uSES-safe state source shared by the registered settings section. */
+    readonly store: SnapshotStore<LoopEngineState>;
+    private following;
+    private saving;
+    /**
+     * @param transport - the settings channel the store follows.
+     */
+    constructor(transport: LoopEngineSettingsTransport);
+    /** Begin following the transport and publish its current answer. */
+    load(): void;
+    /**
+     * Persist the selected engine. Success is the transport's accepted answer
+     * (when it reports one) checked against the snapshot the write left behind,
+     * so a refused write reports error after its recovery.
+     * @param engine - the engine to select for future Agent turns.
+     * @returns whether the write landed.
+     */
+    setEngine(engine: LoopEngineId): Promise<boolean>;
+    /**
+     * Persist whether the composer shows the engine picker. Unlike
+     * {@link setEngine}, landing does not reload the page — the toggle only
+     * changes composer visibility.
+     * @param show - whether the chat page composer reveals the engine picker.
+     * @returns whether the write landed.
+     */
+    setShowInComposer(show: boolean): Promise<boolean>;
+    /**
+     * Persist whether the conversation header shows the engine badge. Unlike
+     * {@link setEngine}, landing does not reload the page — the toggle only
+     * changes header visibility.
+     * @param show - whether the conversation header reveals the engine badge.
+     * @returns whether the write landed.
+     */
+    setShowEngineBadge(show: boolean): Promise<boolean>;
+    /** Stop following the transport. */
+    dispose(): void;
+    private derive;
+}
+//# sourceMappingURL=store.d.ts.map