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

package/lib/types/invariant.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Package-owned invariant companion for the loop engine selection.
+ *
+ * The plugin's owned relationship is the patch-manager round trip: applying the
+ * managed block must be a fixed point, the block must be the one that frees the
+ * single AgentFactory slot for the router, a legacy block naming a single engine
+ * must be migrated to the engine-agnostic form while still being readable as a
+ * legacy pin, and a comment-only layer must be re-seeded to a loadable
+ * top-level array rather than left as `null`. The companion asserts those
+ * against the pure transform, binding the writer's inverse to the reader
+ * directly.
+ *
+ * @module dsh-loop-engine-allinone/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "loop-engine-invariant";
+/** Services required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register the loop-engine invariant contribution.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/model-selection-reset.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Keep a session's model selection on the seat the engine driving it owns.
+ *
+ * A session's model selection FOLLOWS ITS ENGINE, in both directions:
+ *
+ *  - a HOSTED engine owns its model natively, and logs the one shared provider
+ *    label (`external`, {@link HOSTED_ROUTE_LABEL}) into the session's
+ *    `request/header`; the host derives the session's selection from the latest
+ *    header (`packages/api/session-controller/src/agent.ts`, `selectionFor`), so
+ *    a session a hosted engine drives selects `external`. That label is served
+ *    only by this plugin's placeholder route (`provider-route.ts`), which
+ *    advertises exactly one entry under it — {@link HOSTED_DEFAULT_MODEL}. So
+ *    the seat of a hosted session is `external/default`, and this module is what
+ *    puts that in the log BEFORE the engine's first request would. (A session
+ *    whose log still carries an EARLIER build's per-engine label —
+ *    `claude-code` / `codex` / `pi` / `kimi` — is recognized as hosted too,
+ *    {@link isHostedProviderRoute}, and rewritten to `external/default` on its
+ *    next build or switch: no adapter serves those labels any more, so leaving
+ *    one in place would fail the host's own route check with
+ *    `model-unavailable`.)
+ *  - the HARNESS LOOP (`in-process`) DOES call a real model, so it must select
+ *    something a real adapter serves, and the only selection this plugin can name
+ *    honestly is the deployment's own default:
+ *    `agentDefaultModel.currentSelection()`, the value the host's
+ *    `agentOptions()` gives every session it creates without one
+ *    (`packages/core/agent-default-model/src/index.ts`,
+ *    `packages/api/session-controller/src/agent.ts`). That default can name one of
+ *    these routes ITSELF — `session.selectModel` saves whatever the model menu
+ *    submitted as the deployment default, and the menu carries the hosted route
+ *    as an entry — so the deployment's COMPOSED default model (the settings
+ *    descriptor's `base` layer, what `packages/bundle/base/cordis.patch.yml`
+ *    configures) is what this plugin names instead, and says so once. See
+ *    {@link defaultSelection}.
+ *
+ * The write is the harness's own `model/selection` event: log-only, already a
+ * known session event type (`packages/core/session/src/known-event-types.ts`),
+ * and exactly what the host's own model picker appends
+ * (`ApiSessionAgentController.selectForNextRequest`). That is what makes it the
+ * one way a plugin can say "this session's next build selects X" without owning
+ * the host's in-memory selection: the event folds into the `modelSelection`
+ * projection, and the selection the host installs for the session's next agent
+ * reads it back (`selectionFor` prefers the projection's `pending` over the
+ * logged header).
+ *
+ * TWO triggers ask for it, and both answer through the same write:
+ *
+ *  - {@link ModelSelectionReset.resetFor} — a session SWITCHED to another
+ *    engine. The host reads a session's selection from its log and the change is
+ *    about to land on that session's next build, so the write has to happen at
+ *    the switch rather than at the next request.
+ *  - {@link ModelSelectionReset.guardFor} — a session being BUILT. The router
+ *    wraps the caller's `setup` for it, which is the one moment the plugin holds
+ *    the session before the host installs the selection for it
+ *    (`composeAgent`'s `setup` → `installSelection`), so the write still lands
+ *    before the first request — and it is what gives a NEW session on a hosted
+ *    engine its seat. For the harness loop this trigger also settles a defect the
+ *    build path owns: `session.selectModel` saves the pick it was given as the
+ *    DEPLOYMENT default (`packages/api/session-controller/src/commands.ts`
+ *    `selectModel` → `AgentDefaultModelConfig.saveSelection`), that default is
+ *    the selection of every session with nothing in its log, and the menu now
+ *    carries the hosted route as an entry — so ONE pick made while a hosted
+ *    session was open would otherwise hand every session built on the harness
+ *    loop a route no adapter serves.
+ *
+ * THREE judgements keep those writes honest, and both triggers share them
+ * ({@link ModelSelectionReset.appendSeat}):
+ *
+ *  - a REAL model selection is never overwritten. The test is the provider
+ *    ({@link isHostedProviderRoute}): only a label some hosted engine logs is a
+ *    seat this module owns. An explicit pick — the model menu's own event, which
+ *    also becomes the deployment default — survives every engine change, which is
+ *    what the browser half's model notice tells the user: under a hosted engine a
+ *    dsh model is inert, not forbidden.
+ *  - a session that already selects the target (provider and model) is left
+ *    alone, so repeated switches never grow the log.
+ *  - an engine SWITCH has nothing to write for a session whose log names no
+ *    selection at all: there is no seat to rewrite, and naming a session's first
+ *    seat is the BUILD trigger's job ({@link ModelSelectionReset.guardFor}), not
+ *    a switch's. Such a session still selects the deployment default — the host's
+ *    own fallback — so nothing is broken while the seat shows it.
+ *
+ * A deployment that composes no `agentDefaultModel` service, or one whose
+ * service cannot name a usable selection, is not an error here: the trigger is
+ * either the user's own action or a session about to run, and neither must fail
+ * over a selection this plugin cannot name. The write is skipped with ONE
+ * warning, and the session keeps whatever its log records.
+ *
+ * @module dsh-loop-engine-allinone/model-selection-reset
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionModelSelection } from './driver-core/host-servers.ts';
+import type { LoopEngineId } from './settings.ts';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Complete validated model selection requested for subsequent prompt
+         * assembly. Log-only: it never enters derived model history.
+         */
+        'model/selection': {
+            /** Registered provider route. */
+            readonly provider: string;
+            /** Provider-owned model id. */
+            readonly model: string;
+            /** Adapter-owned reasoning effort, or provider/default behavior when absent. */
+            readonly reasoningEffort?: string;
+        };
+    }
+}
+/** The host's `agentDefaultModel` service (`packages/core/agent-default-model`), as this read needs it. */
+export interface AgentDefaultModelService {
+    /**
+     * The selection the host gives an Agent created without one. Read live on
+     * every call, because the settings layer it reads may change at any time.
+     * @returns the deployment's default provider, model, and optional effort.
+     */
+    currentSelection(): SessionModelSelection;
+}
+/**
+ * Keeps a session's model selection on the seat the engine driving it owns — the
+ * shared `external/default` of a hosted engine, or a real model for the harness
+ * loop.
+ *
+ * One instance per router: the "cannot name a default" and "the default itself
+ * names a hosted route" warnings are each owed once per process, not once per
+ * session.
+ */
+export declare class ModelSelectionReset {
+    private readonly ctx;
+    private readonly warn;
+    /** Whether the one warning this deployment is owed has been reported. */
+    private warned;
+    /** Whether the one report that the deployment default names a hosted route has been made. */
+    private reportedHostedDefault;
+    /**
+     * @param ctx - context carrying the host's default-model service, its settings
+     *   (for the configured default), and the session-projection registry.
+     * @param warn - diagnostic sink, used at most once per problem.
+     */
+    constructor(ctx: Context, warn: (message: string) => void);
+    /**
+     * Give one session the selection the engine it is being SWITCHED TO owns,
+     * unless its log already names a real model of its own.
+     *
+     * The switch trigger. A session whose log names no selection at all is left
+     * alone: a switch rewrites a seat an engine already put there, and naming a
+     * session's first seat belongs to the build of a session being created
+     * ({@link guardFor}) rather than to a change of engine.
+     * @param session - the live Session the engine switch is being recorded for.
+     * @param engine - the engine the session is being moved to.
+     * @returns whether a `model/selection` event was appended.
+     */
+    resetFor(session: Session, engine: LoopEngineId): boolean;
+    /**
+     * Give one session the selection the engine BUILDING it owns, inside the
+     * router's wrapped `setup` — before the caller's own setup installs the
+     * session's selection — so a selection written here is the one the host reads
+     * back for the agent being built.
+     *
+     * The harness loop's own build keeps its narrower precondition: it makes real
+     * model calls, so it is the one build that must not be left selecting a
+     * placeholder route, and a session whose own log already names a real model
+     * needs nothing written for it. A hosted engine is being given its seat here,
+     * which is what a new session on it starts from.
+     * @param session - the session whose agent is being composed.
+     * @param engine - the engine composing it.
+     * @returns whether a `model/selection` event was appended.
+     */
+    guardFor(session: Session, engine: LoopEngineId): boolean;
+    /**
+     * Whether the selection this session's next request would use names one of
+     * the hosted engines' provider routes — a label this plugin serves as a
+     * placeholder and cannot answer a real model call on.
+     *
+     * The read is the host's own (`selectionFor`): a pending selection, else the
+     * logged header, else the deployment's default. A session with nothing in its
+     * log is therefore judged on the deployment default — the value the model menu
+     * can write a hosted label into — and that default is read AS IT IS, never as
+     * {@link defaultSelection} would substitute it: the substitution only exists
+     * once it is written into the session, so judging the substitute would skip
+     * the write that makes it real.
+     * @param session - the session whose selection is being judged.
+     * @returns whether that selection names a hosted engine route.
+     */
+    private selectsHostedRoute;
+    /**
+     * Append the selection one engine's seat carries, by the judgements both
+     * triggers share.
+     *
+     * A real model selection is never overwritten — the provider is the test,
+     * because only a label some hosted engine logs is a seat this module owns — and
+     * a session that already selects the target route is left alone. Provider and
+     * model are the comparison: a reasoning effort the target carries is not a
+     * reason to log a second event for a session that already selects the same
+     * route, and re-appending would only grow the log on every switch.
+     * @param session - the session whose selection is being written.
+     * @param engine - the engine whose seat the session should select.
+     * @returns whether a `model/selection` event was appended.
+     */
+    private appendSeat;
+    /**
+     * The selection one engine's seat carries: a hosted engine's shared
+     * `external/default`, or — for the harness loop — the deployment's default,
+     * with the substitution {@link defaultSelection} documents.
+     * @param engine - the engine a session runs, or is being moved to.
+     * @returns the selection to write, or undefined when this process cannot name
+     *   one for that engine.
+     */
+    private seatOf;
+    /**
+     * The selection the host will use for this session, by the host's own read —
+     * the shared read in `driver-core/session-model.ts` (`currentSelection`),
+     * which the hosted drivers also use to resolve the model they hand over.
+     * @param session - the session whose selection is being read.
+     * @returns the current selection, or undefined when the log records none.
+     */
+    private currentSelection;
+    /**
+     * The selection the deployment's own `agentDefaultModel` service answers, or
+     * undefined when this process cannot read one (reported once).
+     *
+     * Read twice for two different questions — as the selection a session with
+     * nothing in its log would use ({@link selectsHostedRoute}), and as the value
+     * this plugin restores ({@link defaultSelection}) — so the substitution below
+     * never hides the fact that the saved default itself is unusable.
+     * @returns the validated default, or undefined when it cannot be named.
+     */
+    private deploymentDefault;
+    /**
+     * The selection this plugin restores: the deployment's default, or — when that
+     * default names a hosted engine ROUTE — the model the deployment's own
+     * composition declares instead.
+     *
+     * The route case is not hypothetical: `session.selectModel` saves whatever the
+     * model menu submitted as the deployment default, and the menu carries the
+     * hosted route as an entry, so one pick made while a hosted session was open
+     * puts a label there that no adapter serves a real model on — handing it to a
+     * session the harness loop drives would fail that session's first request
+     * loud. The composed default is a real model the deployment itself asked for,
+     * so nothing is guessed on its behalf.
+     * @returns the restored selection, or undefined to skip the write.
+     */
+    private defaultSelection;
+    /**
+     * The model the DEPLOYMENT's own composition declares as its default, read
+     * from the settings descriptor's `base` layer — the value a saved (user-layer)
+     * default overrode.
+     *
+     * This is what replaces a default that names a hosted route, and it is read
+     * live because the composition is what the deployment itself configured:
+     * `packages/bundle/base/cordis.patch.yml` gives the `agent-default-model` row
+     * a real provider and model, and only the user layer can hold a pick made from
+     * the model menu.
+     * @returns the configured default, or undefined when this deployment composes
+     *   no default-model section, cannot enumerate settings, configured no usable
+     *   provider/model, or configured a hosted route there too.
+     */
+    private configuredDefault;
+    /** Read the host session-projection registry, structurally. */
+    private projections;
+    /**
+     * Report the one thing this read could not answer, once per plugin lifetime.
+     *
+     * Repeated triggers must not repeat it: a deployment without the service would
+     * otherwise log a line per session built for as long as it runs.
+     * @param problem - what this process cannot read, with the reason.
+     * @returns undefined, so callers can `return this.unavailable(…)` to skip.
+     */
+    private unavailable;
+}
+//# sourceMappingURL=model-selection-reset.d.ts.map

package/lib/types/namespace.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Loop engine namespace literals: the strings both halves agree on, in a
+ * module with no runtime imports so the browser bundle can import them without
+ * dragging `dsh-settings` (a host-side service) into the client artifact.
+ * @module dsh-loop-engine-allinone/namespace
+ */
+/**
+ * Settings namespace carrying the deployment's selected agent loop engine on
+ * the 0.1.7 line.
+ *
+ * Profile-backed settings are addressed by the composing entry id, so this
+ * literal is the plugin's own profile entry id: the shipped `cordis.patch.yml`
+ * inserts the entry as `loop-engine`, and the browser half passes the same
+ * string to `ctx.configForms.get(...)`. A deployment that renames the entry id
+ * must change this literal with it.
+ */
+export declare const LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL = "loop-engine";
+/**
+ * Settings namespace carrying the same selection on the 0.1.5 line, where a
+ * settings section is addressed by the namespace a provider registers rather
+ * than by a composing entry id. This is the literal the pre-rewrite plugin
+ * shipped; it is stable across the whole 0.1.5 line.
+ */
+export declare const LEGACY_LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL = "agent-loop-engine";
+//# sourceMappingURL=namespace.d.ts.map

package/lib/types/patch-manager.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Managed-block editing for a profile's `cordis.patch.yml`.
+ *
+ * The plugin owns one contiguous block inside the user's patch file, delimited
+ * by a begin/end marker pair, and rewrites only that span — everything else the
+ * user wrote (other patches, their comments) survives byte for byte. The block
+ * is what hands the process-wide AgentFactory slot to this plugin's router: it
+ * disables the base bundle's `agent-loop` row, because the harness admits
+ * exactly one AgentFactory and the router (which extends the harness loop, and
+ * therefore serves `in-process` sessions too) registers itself as that one.
+ *
+ *   # -- dsh-loop-engine managed block --
+ *   - id: agent-loop
+ *     disabled: true
+ *   - id: command-goal
+ *     disabled: true
+ *   # -- /dsh-loop-engine managed block --
+ *
+ * The block names no engine. Which engine a session runs is a PER-SESSION
+ * decision carried by its agent preset, so it cannot live in a process-wide
+ * configuration file; the block's only job is to free the slot for the router.
+ * The `command-goal` row goes down with the loop: it is the host-plane copy of
+ * dsh's goal command, and a goal service nothing drives has no business being
+ * mounted for a profile whose loop is decided per session. The remaining
+ * dsh-native commands (`/export`, `/feedback`, `/permission`) are
+ * engine-agnostic session and settings controls that keep working under every
+ * engine. Per-session command surfaces are the preset's business — a hosted
+ * session joins an engine preset that strips `command-goal` itself, which is the
+ * only place that reaches the preset-layer registration.
+ *
+ * Blocks written before the plugin routed per session carried the single
+ * engine's id in the begin marker (`# -- dsh-loop-engine managed block:
+ * claude-code --`). {@link legacyBlockEngineOf} reads that form so an upgrade
+ * can carry the pinned engine into the settings seed before the block is
+ * rewritten to the engine-agnostic form; a legacy block is otherwise treated as
+ * a present block by {@link hasManagedBlock}.
+ *
+ * All functions here are pure string transforms — file I/O and durability live
+ * in the plugin's apply.
+ *
+ * @module dsh-loop-engine-allinone/patch-manager
+ */
+import type { LoopEngineId } from './settings.ts';
+/** Begin marker of the plugin-managed span inside a profile patch file. */
+export declare const MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block --";
+/**
+ * Begin-marker prefix of the pre-routing block form, which named the one engine
+ * the profile was pinned to.
+ */
+export declare const LEGACY_MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block: ";
+/** End marker of the plugin-managed span inside a profile patch file. */
+export declare const MANAGED_BLOCK_END = "# -- /dsh-loop-engine managed block --";
+/** The loader patch that frees the single AgentFactory slot for the router. */
+export declare function renderManagedBlock(): string;
+/**
+ * Whether a patch-file text contains the LEGACY managed block span, which
+ * named the single engine the profile used to be pinned to.
+ */
+export declare function hasLegacyManagedBlock(text: string): boolean;
+/**
+ * Whether a patch-file text contains the managed block span, in either the
+ * current or the legacy form.
+ */
+export declare function hasManagedBlock(text: string): boolean;
+/**
+ * The engine a LEGACY managed block pinned the profile to, when the block has
+ * that form and names an engine this build knows. `undefined` covers the
+ * current engine-agnostic block, no block at all, and a legacy block naming an
+ * engine this build does not recognize.
+ */
+export declare function legacyBlockEngineOf(text: string): LoopEngineId | undefined;
+/** Normalize a file so a managed span sits on its own lines with a blank separator. */
+export declare function ensureTrailingNewline(text: string): string;
+/**
+ * The profile seed template (`cordis.patch.yml` on a fresh profile) is a lone
+ * root-level empty flow sequence `[]`. The plugin's managed block is itself a
+ * root-level block sequence of loader entries, so a block coexisting with a
+ * surviving `[]` is TWO root collections in one document — YAML the harness
+ * rejects with "end of the stream or a document separator is expected", and the
+ * web app then fails to boot. Remove a whole-line root `[]` placeholder so the
+ * managed block is the sole top-level collection. Anchored to column 0 so an
+ * indented `[]` that is a real value inside an entry's nested config is never
+ * touched.
+ *
+ * Shared with the preset-rows region (`./preset.ts`): both regions are
+ * root-level collections appended to the same file, so either one can be the
+ * first thing that meets a surviving seed.
+ * @param text - the patch-file text.
+ * @returns the text without a whole-line root `[]` placeholder.
+ */
+export declare function dropSeedPlaceholder(text: string): string;
+/**
+ * Produce the next patch-file text carrying the managed block, preserving every
+ * byte outside the managed span. Appends the span when absent and replaces it
+ * when present — including a legacy span, which is rewritten to the current
+ * form. The managed block is a root-level collection, so a leftover seed `[]`
+ * is dropped with it, leaving the file a single valid top-level array the
+ * harness can boot: the block's own `- id: agent-loop` is a column-0 entry, so
+ * a file carrying it never needs a re-seed.
+ * @param text - current patch-file text.
+ * @returns the rewritten patch-file text.
+ */
+export declare function applyManagedBlock(text: string): string;
+//# sourceMappingURL=patch-manager.d.ts.map