dsh-loop-engine 0.1.5-rc3 → 0.1.5-rc4

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

@@ -2,6 +2,7 @@
  * Loop engine settings page copy (Chinese product copy; comments in English).
  * @module dsh-loop-engine/client/locales
  */
+import { type LoopEngineId, type LoopEngineRefusalCode, type SessionEngine } from '../agent-preset-ids.ts';
 /** Copy keys of the loop engine settings page. */
 export interface LoopEngineKey {
     /** Settings navigation label. */
@@ -18,6 +19,12 @@ export interface LoopEngineKey {
     enginePi: string;
     /** Option label: the Kimi Code CLI driver. */
     engineKimi: string;
+    /** Option label: a session on the pre-routing single preset id. */
+    engineLegacy: string;
+    /** Option label: a session this plugin holds no engine record for. */
+    engineUnrecorded: string;
+    /** Composer picker label while the session's own engine has no answer yet. */
+    engineLoading: string;
     /** Settings toggle: show the engine picker in the chat page composer. */
     showInComposerLabel: string;
     /** Unavailable-state message. */
@@ -26,21 +33,140 @@ export interface LoopEngineKey {
     switchNotice: string;
     /** Saving state label. */
     saving: string;
-    /** Confirmation dialog title. */
+    /** Settings-section confirmation title: the picker that changes the new-session default. */
     confirmTitle: string;
-    /** Confirmation dialog body. */
+    /** Settings-section confirmation body: the picker that changes the new-session default. */
     confirmBody: string;
-    /** Confirmation action label. */
+    /** Session-header chip tooltip: the engine this session runs, and what decides it. */
+    sessionNotice: string;
+    /** Session-header chip tooltip when the session's engine was never recorded. */
+    legacySessionNotice: string;
+    /** Marker lead-in naming the engine a session's record holds while another one drives it. */
+    enginePendingPrefix: string;
+    /** Marker trailer saying that recorded engine is not what the session runs. */
+    enginePendingSuffix: string;
+    /** Composer menu-row suffix marking the engine a session's record holds but is not running. */
+    engineMenuPendingSuffix: string;
+    /** Session-header chip tooltip while the record names an engine the session is not running. */
+    pendingSessionNotice: string;
+    /** Composer picker tooltip while the record names an engine the session is not running. */
+    pendingComposerHint: string;
+    /** Composer picker tooltip: it chooses this session's engine, and which picks apply immediately. */
+    composerHint: string;
+    /** Title of the notice reporting a refused per-session switch. */
+    switchFailedTitle: string;
+    /** Body of a refused per-session switch: the session is not open yet. */
+    refusedSessionClosed: string;
+    /** Body of a refused per-session switch: a turn is in flight and is not interrupted. */
+    refusedTurnRunning: string;
+    /** Body of a refused per-session switch: a delegated child's engine follows its parent. */
+    refusedSubagentSession: string;
+    /** Body of a refused per-session switch while this process has no loop engine router. */
+    refusedRouterNotReady: string;
+    /** Body of a refused per-session switch whose engine record could not be written. */
+    refusedRecordFailed: string;
+    /** Body of a refused per-session switch whose successor engine could not be built. */
+    refusedRebuildFailed: string;
+    /** Title of the confirmation shown before a switch that reloads the page. */
+    switchReloadConfirmTitle: string;
+    /** Body of that confirmation: what the reload is for, and what this page loses with it. */
+    switchReloadConfirmBody: string;
+    /** Confirm action label of that confirmation. */
+    switchReloadConfirmAction: string;
+    /** Title of the notice shown while a per-session switch reloads the page. */
+    switchReloadTitle: string;
+    /** Body of that notice: what the reload is doing, and that it returns to this session. */
+    switchReloadBody: string;
+    /** Message when this page cannot reach the engine switch endpoint at all. */
+    switchUnavailable: string;
+    /** Confirmation action label of the settings section's own dialog. */
     confirmAction: string;
-    /** Cancel action label. */
+    /** Cancel action label of the settings section's own dialog. */
     cancelAction: string;
-    /** Accessible close-button label of the confirmation dialog. */
+    /** Accessible close-button label of the settings confirmation and the switch notices. */
     closeLabel: string;
-    /** Notice shown while the Claude Code engine owns the slot: model selection is native. */
-    claudeModelNotice: string;
+    /** Notice shown while a hosted engine drives the session: the model seat is the engine's own business. */
+    hostedEngineModelNotice: string;
 }
 /** Simplified Chinese copy. */
 export declare const zh: Record<keyof LoopEngineKey, string>;
 /** English copy. */
 export declare const en: Record<keyof LoopEngineKey, string>;
+/**
+ * The copy key naming one engine, shared by the session header chip and the
+ * composer picker (both name a resolved engine, and neither may invent a name
+ * for one of the two non-engine session states).
+ * @param engine - a resolved engine id.
+ * @returns the key of that engine's own label.
+ */
+export declare function engineLabelKey(engine: LoopEngineId): keyof LoopEngineKey;
+/**
+ * The copy key naming the engine a session RUNS, for the two surfaces that name
+ * one (the header chip and the composer picker's trigger).
+ *
+ * The three-state is folded in one place so the two surfaces cannot answer the
+ * "which engine is this?" question differently — and so neither can hand it the
+ * pending engine: {@link SessionEngine} is the ACTUAL answer by construction, and
+ * the recorded-but-not-adopted engine travels beside it
+ * (`SessionEngineReport.pending`), where {@link pendingEngineText} turns it into
+ * a marker rather than a name.
+ * @param state - what the session's engine read answered for its live engine.
+ * @returns the key of that state's label.
+ */
+export declare function engineStateLabelKey(state: SessionEngine): keyof LoopEngineKey;
+/**
+ * The marker naming the engine a session's record holds while something else is
+ * driving it.
+ *
+ * It is an aside, never a name: a surface appends it to the engine the session is
+ * actually running, so the user reads "Pi CLI, and the record says X" — not "X".
+ * Both surfaces that show a session's engine render it, which is why it is
+ * composed here rather than in either of them.
+ *
+ * Its trailer deliberately makes no promise about WHEN the recorded engine takes
+ * over (`enginePendingSuffix`): a switch that has to release the session's agent
+ * lands through a page reload, and this marker never survives one — it is what
+ * the user sees when that release did not take, and picking the engine again is
+ * the action that retries it.
+ * @param t - the surface's copy function.
+ * @param engine - the engine the session's own record names.
+ * @returns the complete marker, e.g. `切到 Pi CLI · 尚未接管`.
+ */
+export declare function pendingEngineText(t: (key: keyof LoopEngineKey) => string, engine: LoopEngineId): string;
+/**
+ * How one refused switch reads: which local copy says it, and whether the host's
+ * own sentence belongs under that copy as detail.
+ *
+ * The refusal arrives from the host as a code plus the host's English sentence
+ * about one session (`LoopEngineRefusal.reason`), and the sentence is what a
+ * surface used to show verbatim — which is how a user got a raw
+ * `session "…" is running; switch its engine after this turn ends` for a state
+ * this plugin can say perfectly well in the user's own language. So the code
+ * decides the message here, and the sentence is kept where it is genuinely
+ * additional information: the two failures whose copy is generic and whose text
+ * carries the underlying cause (a write error, a driver that would not start).
+ */
+export interface RefusalFace {
+    /**
+     * Body copy key for this refusal. Absent when no local copy can say it — an
+     * absent or unknown code, where the host's own sentence IS the message
+     * (`undefined` is also what a client older than the host normalizes an
+     * unrecognized code to, `src/client/session-engine.ts` `parseSelectResult`).
+     */
+    readonly body?: keyof LoopEngineKey;
+    /** Whether the host's `reason` is rendered under the body as detail. */
+    readonly detail: boolean;
+}
+/**
+ * Resolve what one refused switch shows.
+ *
+ * A refusal ALWAYS leaves something readable: a known code gets this plugin's own
+ * copy (and, for the two technical failures, the host's sentence under it), while
+ * an absent or unknown code falls back to that sentence as the message itself.
+ * @param code - the code the host's refusal carried, or undefined when it carried
+ * none this build knows.
+ * @returns the copy key to render, plus whether the host's own text is shown as
+ * detail.
+ */
+export declare function refusalFace(code: LoopEngineRefusalCode | undefined): RefusalFace;
 //# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,135 @@
+/**
+ * Reloading the page, and coming back to the session the switch rebuilt.
+ *
+ * Switching a session onto — or off — the harness loop cannot move its agent in
+ * place, so the host RELEASES that agent and answers `reload: true`
+ * (`src/router-loop.ts` `move`): the session's record already names the engine it
+ * must run, and the host builds it again on its next resolve. Two things have to
+ * happen on this side for the user to experience that as a switch rather than as
+ * a session that broke:
+ *
+ *  1. THE PAGE MUST RELOAD. Releasing the agent publishes `session/disposed`, and
+ *     the session controller's client half reads it as this session being GONE:
+ *     the row leaves its list, the current selection is masked away, and the
+ *     session object is marked `removed` — a flag NOTHING in that page's
+ *     lifetime clears (`packages/api/session-controller/src/client/sessions/session.ts`
+ *     `handleRemoved`), which is what locks the composer
+ *     (`packages/client/ui-conversation/src/client/skeleton/InputBar.tsx`). A
+ *     page that stayed put would show the session as unusable; a reload is the
+ *     smallest action that replaces that page state with a fresh list and a
+ *     fresh, unmarked session object.
+ *  2. THAT SESSION HAS TO BE OPENED AGAIN, or the user lands wherever the client
+ *     falls back to. Nothing does it for us: the reload clears the session
+ *     controller's own persisted selection cell once the current selection was
+ *     masked away (`.../client/sessions/service.ts` `projectList`), and the
+ *     workspace's startup navigation only reuses a BLANK session of the most
+ *     recent workspace, creating a fresh session otherwise
+ *     (`.../client/ui-workspace/src/client/navigation.ts` `watchNavigation`). So
+ *     the id is stashed in TAB storage — which survives a reload and dies with
+ *     the tab — and {@link restoreReloadReturn} opens it as soon as the client's
+ *     session list knows it.
+ *
+ * That last step is what makes the whole flow worth having: the session is still
+ * on DISK, so the list the page re-pulls from the host contains it (the host's
+ * list unions persisted headers with live sessions), and opening it is what makes
+ * the host resolve the session at all — no live agent → `ctx.agents.resume(...)`
+ * → the router reads the plugin's own record → the harness loop builds it. The
+ * process never restarts.
+ *
+ * The page is poked only through `window.location.reload()` — nothing else: a
+ * reload is the action a user would take themselves, and it is the one this
+ * plugin can justify.
+ *
+ * @module dsh-loop-engine/client/reload
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+/** Tab-scoped web storage, as this feature reads and writes it. */
+export interface ReloadStash {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The browser this plugin's client half is running in, as this feature needs it. */
+export interface ReloadPage {
+    /** The tab's storage, or undefined off a browser (and in node, where the specs run). */
+    readonly stash: ReloadStash | undefined;
+    /** Reload the current page. */
+    reload(): void;
+}
+/**
+ * The stash key holding the session a reload has to come back to.
+ *
+ * Namespaced by package: tab storage is shared with everything else the page
+ * runs, and one key per concern is all this feature needs.
+ */
+export declare const RELOAD_RETURN_KEY = "dsh-loop-engine:reload-session";
+/** The live page, read off the globals. Missing ones simply mean "no page". */
+export declare function browserPage(): ReloadPage;
+/**
+ * Remember the session a reload must reopen.
+ *
+ * Best-effort by design: a page whose storage refuses the write (private mode,
+ * quota) still reloads, it just cannot promise the way back — the caller reports
+ * what it could do rather than refusing the switch the host already performed.
+ * @param page - the page to stash into.
+ * @param sessionId - the session to come back to.
+ * @returns whether the id was stashed.
+ */
+export declare function armReloadReturn(page: ReloadPage, sessionId: string): boolean;
+/**
+ * Take the session this page was reloaded for, clearing it as it is read.
+ *
+ * Reading is destructive so the return happens exactly once per reload: the id
+ * must not survive a second reload the user starts for their own reasons, and a
+ * later visit to this tab has no session to come back to.
+ * @param page - the page to read.
+ * @returns the stashed session id, or undefined when this page is not one.
+ */
+export declare function takeReloadReturn(page: ReloadPage): string | undefined;
+/**
+ * The slice of the session controller's client service this module drives:
+ * the list it publishes, and the verb that opens one of its sessions.
+ *
+ * Declared structurally rather than imported: this is a third-party client
+ * plugin (no build-time dependency on the harness's client packages), and the
+ * only two members it needs are these.
+ */
+export interface SessionListFace {
+    readonly list: {
+        getSnapshot(): {
+            readonly phase: 'pending' | 'ready';
+            readonly ids: readonly string[];
+        };
+        subscribe(listener: () => void): () => void;
+    };
+    open(id: string): void;
+}
+/**
+ * Open the session this page was reloaded for, once the client knows it.
+ *
+ * The wait is real and cannot be skipped: the list arrives with the host's list
+ * RPC, asynchronously, and `open` refuses an id it does not know yet
+ * (`sessions.select: unknown session ...`). One decision is made, on the FIRST
+ * settled list — the id is either in it (open it) or the session is not listed
+ * at all, in which case opening it is impossible and waiting longer would only
+ * mean hijacking the page minutes later, after the user had moved on.
+ * @param sessions - the session controller's client service.
+ * @param page - the page whose stash is read.
+ * @param warn - diagnostic sink for the two ways this can end without opening.
+ * @returns the release, in case the plugin unloads before the list settles.
+ */
+export declare function restoreReloadReturn(sessions: SessionListFace, page: ReloadPage, warn: (message: string) => void): () => void;
+/**
+ * Wire the return-to-session half into the client tree.
+ *
+ * Takes the `sessions` service through a nested injection rather than declaring
+ * it in this plugin's own `inject`: a profile that composes no session
+ * controller (the settings page's own tests, a minimal client) must keep
+ * working, and this feature degrades to "reload without the way back" there —
+ * the id is simply not stashed, because nothing could open it.
+ * @param ctx - the client root context.
+ * @param page - the page to read the stash from; the real browser by default.
+ * @param warn - diagnostic sink; the client logger by default.
+ */
+export declare function installReloadReturn(ctx: ClientContext, page?: ReloadPage, warn?: (message: string) => void): void;
+//# sourceMappingURL=reload.d.ts.map