dsh-loop-engine 0.1.5-rc2 → 0.1.5-rc4

package/lib/types/preset.d.ts

@@ -1,48 +1,61 @@
 /**
- * Hosted-engine agent preset: a managed copy of the deployment's `standard`
- * preset with the dsh-native command and skill rows stripped.
+ * Hosted-engine agent presets: one managed copy of the deployment's `standard`
+ * preset per hosted engine, with the dsh-native command and skill rows
+ * stripped.
  *
  * A hosted engine (Claude Code, Codex, Pi, Kimi) owns its session's command
- * and skill surface: the engine's own slash commands and skill providers are
- * registered globally by the plugin, and the dsh-native equivalents would only
- * duplicate or mislead — dsh `/plan` is advisory prompt text an external
- * engine never assembles, dsh `/compact` cannot shrink a context the engine's
- * child process holds, and dsh skills would sit next to the engine's own
- * catalog. Those rows live inside the agent-preset composition, which a
- * profile patch cannot reach, so the plugin authors a stripped preset into the
- * user preset root (`$DSH_HOME/.agent-presets/<id>`) and steers the roster's
- * default at runtime (see the plugin's apply).
+ * and skill surface: the plugin bridges the engine's own slash commands and
+ * skill providers into the session (see `engine-surface.ts`), and the
+ * dsh-native equivalents would only duplicate or mislead — dsh `/plan` is
+ * advisory prompt text an external engine never assembles, dsh `/compact`
+ * cannot shrink a context the engine's child process holds, and dsh skills
+ * would sit next to the engine's own catalog. Those rows live inside the
+ * agent-preset composition, which a profile patch cannot reach, so the plugin
+ * authors a stripped preset per engine into the user preset root
+ * (`$DSH_HOME/.agent-presets/<id>`).
  *
- * The preset is REGENERATED from the current `standard` composition on every
- * boot that needs it: text on disk is never authoritative, so a harness
- * upgrade that changes `standard` flows through. The file is plain YAML the
- * loader already accepts — the strip is a line transform that preserves
- * everything it does not drop byte for byte, comments included.
+ * The preset id is ALSO the per-session engine selector: the harness resolves
+ * one preset per session and hands its id to the agent factory at create time
+ * (`CreateAgentOptions.meta.agentPreset`), which is the only per-session
+ * channel that reaches agent creation. One preset per engine is therefore what
+ * makes "session A on Codex, session B on Kimi, concurrently" expressible in a
+ * harness that admits exactly one AgentFactory.
+ *
+ * The presets are REGENERATED from the current `standard` composition on every
+ * boot: text on disk is never authoritative, so a harness upgrade that changes
+ * `standard` flows through. The file is plain YAML the loader already accepts —
+ * the strip is a line transform that preserves everything it does not drop byte
+ * for byte, comments included.
  *
  * @module dsh-loop-engine/preset
  */
-/** Preset id the plugin authors into the user preset root. */
-export declare const HOSTED_PRESET_ID = "loop-engine";
+export { HOSTED_PRESET_PREFIX, SOURCE_PRESET_ID, engineOfPreset, enginePresetId, hostedEngineOf, sessionEngineOf, } from './agent-preset-ids.ts';
+export type { SessionEngine } from './agent-preset-ids.ts';
 /** Harness-home-relative directory of locally authored presets (mirrors `USER_PRESET_DIR` in `dsh-agent-presets`). */
 export declare const USER_PRESET_DIR = ".agent-presets";
 /** The composition file that makes a directory a preset. */
 export declare const COMPOSITION_FILE = "agent.cordis.yml";
 /** The display-metadata file beside a preset's composition. */
 export declare const METADATA_FILE = "preset.yml";
-/** Source preset the hosted preset derives from. */
-export declare const SOURCE_PRESET_ID = "standard";
+/** Every preset id this plugin owns, whether or not it is currently authored. */
+export declare const HOSTED_PRESET_IDS: readonly string[];
 /**
  * Top-level rows stripped from the source preset for hosted engines:
  * - `skill-filesystem` / `tool-skill`: the dsh skill surface — each engine
- *   registers its own skill provider globally;
- * - `tool-goal`: the model-facing goal tool — the managed block already
- *   disables dsh's `/goal` command for hosted engines;
+ *   registers its own skill provider in the session's agent scope;
+ * - `tool-goal` / `command-goal`: dsh's goal mode. The model-facing tool only
+ *   works while an in-process loop drives the session, and the human command
+ *   would sit in the menu with nothing behind it — no hosted engine here
+ *   implements `/goal`, so there is nothing for it to hand over to. The
+ *   `command-goal` row lives HERE, in the preset layer, because that is where
+ *   the human command is registered; disabling the host-plane row from the
+ *   profile patch does not reach it (`standard` carries its own row);
  * - `planning`: dsh plan mode — its only model-visible effect is a system
  *   prompt section an external engine never assembles;
  * - `compaction`: dsh `/compact` and auto-compaction — a hosted engine owns
  *   its context and its own `/compact` (Claude, Kimi).
  */
-export declare const STRIPPED_ROWS: readonly ["skill-filesystem", "tool-skill", "tool-goal", "planning", "compaction"];
+export declare const STRIPPED_ROWS: readonly ["skill-filesystem", "tool-skill", "tool-goal", "command-goal", "planning", "compaction"];
 /**
  * Remove top-level entries by id from a preset composition, preserving every
  * other byte. Each entry owns the comment/blank run directly above its opener
@@ -61,7 +74,7 @@ export interface PresetCompositionSource {
     read(id: string): Promise<string>;
 }
 /**
- * Regenerate the hosted-engine preset under the dsh home's user preset root
+ * Regenerate every hosted engine's preset under the dsh home's user preset root
  * from the roster's `standard` preset. Idempotent: an up-to-date directory is
  * untouched, so no standing mount sees a spurious file-stamp change.
  * @param dshHome - the resolved harness home.
@@ -69,5 +82,5 @@ export interface PresetCompositionSource {
  * @returns whether any file was written.
  * @throws when the source preset cannot be read or the writes fail.
  */
-export declare function ensureHostedPreset(dshHome: string, source: PresetCompositionSource): Promise<boolean>;
+export declare function ensureEnginePresets(dshHome: string, source: PresetCompositionSource): Promise<boolean>;
 //# sourceMappingURL=preset.d.ts.map

package/lib/types/provider-route.d.ts

@@ -1,56 +1,103 @@
 /**
- * Hosted-engine provider route placeholders.
+ * Hosted-engine provider route placeholder.
  *
- * Every hosted engine logs its sessions' request/header with its own provider
- * label (`claude-code`, `codex`, `pi`, `kimi`) rather than a model endpoint the
+ * Every hosted engine logs its sessions' request/header with ONE shared provider
+ * label ({@link HOSTED_ROUTE_LABEL}, `external`) rather than a model endpoint the
  * harness llm registry serves — the engine owns its model natively. The web
  * host derives a session's model selection from that header and refuses a turn
  * whose provider no registered adapter serves, so without a placeholder route
  * the SECOND prompt of every hosted session fails with `model-unavailable`.
- * The placeholder serves the label and advertises no models unless a deployment
- * injects a catalog (only `pi` does, from its model probe); catalog groups that
- * advertise nothing are dropped, so the picker is otherwise unchanged.
+ *
+ * One label for all four engines, because the browser model catalog is built
+ * per Host GENERATION and does not require (or vary by) a Session
+ * (`packages/api/session-controller/src/catalog.ts`). A per-engine label would
+ * therefore show one provider group per engine in every session's menu at once —
+ * four identical `default` entries — so they are collapsed into this one route.
+ *
+ * Serving the label is only half of it. The model menu renders the session's
+ * selection through the catalog, and a provider group that advertises no models
+ * is dropped (`packages/api/session-controller/src/catalog.ts`, non-empty
+ * groups only) — leaving the seat to show the raw `provider/model` string, i.e.
+ * a model that does not exist to any adapter. So the placeholder advertises
+ * exactly ONE entry, {@link HOSTED_DEFAULT_MODEL}:
+ * `{ provider: HOSTED_ROUTE_LABEL, id: 'default', name: 'default' }`. The id is
+ * the same string every engine logs as its model label, which is what makes the
+ * seat resolve the session's `(provider, model)` to this entry and render the
+ * engine's own word for "whatever it decides" instead of a composite string
+ * (see {@link HOSTED_DEFAULT_MODEL} for the host-side mechanism).
+ *
+ * The entry is not a model this plugin can serve: {@link HostedEngineRouteAdapter.stream}
+ * fails loud, because a real model call reaching one of these routes means a
+ * session the harness loop drives was handed an engine label — a wiring bug,
+ * not a request. Two things keep that from happening: a session switched back
+ * to `in-process` has the deployment default written into its log
+ * (`model-selection-reset.ts`), and a session BUILT on `in-process` whose
+ * selection is one of these labels has it replaced by the same authority before
+ * the host installs it (same module, `guardFor`).
  *
  * @module dsh-loop-engine/provider-route
  */
-import type { GenerateOptions, LlmModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
 import { LlmAdapter } from '@deepseek-ai/dsh-llm';
-import type { LoopEngineId } from './settings.ts';
-import type { PiModelEntry } from './engine-pi/probe.ts';
-/** Provider route label each hosted engine logs into its sessions' request/header. */
-export declare const HOSTED_PROVIDER_ROUTES: Readonly<Record<Exclude<LoopEngineId, 'in-process'>, string>>;
-/** Injectable catalog source a hosted engine route can advertise over the placeholder. */
-export interface HostedEngineRouteAdapterOptions {
-    /**
-     * Optional model catalog generator. When present, `listModels` advertises
-     * these entries under this route's provider label; when absent, the catalog
-     * stays empty (the default, "engine owns its models" behavior).
-     */
-    readonly listModels?: () => readonly PiModelEntry[];
-}
+import type { HostedEngineId } from './settings.ts';
+/**
+ * The provider route label ONE hosted engine logs into its sessions'
+ * request/header — always {@link HOSTED_ROUTE_LABEL}.
+ *
+ * A function rather than a per-engine map because there is now ONE label: the
+ * engine an id names no longer changes the route. It is kept as a function so
+ * the "an engine logs a route" relationship still reads as such at the call
+ * sites that have an engine id in hand (`router-loop.ts` `engineRouteOptions`,
+ * `model-selection-reset.ts` `seatOf`).
+ * @param _engine - the hosted engine whose route label is asked for.
+ * @returns the single route label every hosted engine logs.
+ */
+export declare function hostedRouteLabelOf(_engine: HostedEngineId): string;
 /**
- * Placeholder adapter serving one hosted engine's provider route label. It
- * advertises the injected catalog when a deployment provides one and stays
- * empty otherwise (the engine's model is not itself a harness-selectable
- * endpoint), and {@link stream} fails loud: a call reaching it means a real
- * model query was routed to an engine that owns its model natively — a wiring
- * bug, not a request to serve.
+ * Whether a provider is one of this plugin's hosted engine route labels — a
+ * label some hosted engine logs (now, or in an earlier build), which no adapter
+ * serves a real model on.
+ *
+ * The OLD four per-engine labels are members on purpose, even though only
+ * {@link HOSTED_ROUTE_LABEL} is registered. A pre-existing session's header
+ * still names one of them; treating only the current label as hosted would let
+ * such a session keep the stale selection, and the host — which finds no
+ * adapter serving `kimi` any more — would refuse its next turn
+ * (`model-unavailable`). Membership here is what lets `model-selection-reset`
+ * rewrite the seat to `external/default` (or the deployment default) first.
+ * @param provider - the provider of any selection, header, or default.
+ * @returns whether that provider is a hosted engine's route label.
+ */
+export declare function isHostedProviderRoute(provider: string): boolean;
+/**
+ * Placeholder adapter serving the one hosted engine provider route label.
+ *
+ * It advertises the single menu entry ({@link HOSTED_DEFAULT_MODEL}) so the
+ * model seat can name the session's selection, carries the route's display name
+ * ({@link HOSTED_ROUTE_NAME}) so the catalog's provider group is labelled
+ * `external`, and {@link stream} fails loud: a call reaching it means a real model
+ * query was routed to an engine that owns its model natively — a wiring bug, not
+ * a request to serve.
  */
 export declare class HostedEngineRouteAdapter extends LlmAdapter {
-    private readonly label;
-    private readonly options;
     /**
-     * @param label - the provider route label this placeholder serves.
-     * @param options - optional catalog source; omit for an empty catalog.
+     * Name the route's one entry.
+     *
+     * `id` must equal the provider the adapter was registered for (the registry
+     * rejects a mismatch — `packages/llm/llm/src/index.ts` `prepareRoutes`), so it
+     * is echoed back; `name` is the one localized string the catalog carries.
+     * @param provider - the route this adapter is registered for.
+     * @returns the route's display metadata.
      */
-    constructor(label: string, options?: HostedEngineRouteAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
     /**
-     * Advertise the injected Pi models (if any) under this route's provider label.
+     * Advertise the route's single entry.
      *
-     * The model is what the picker shows at the top level, so `name` is the bare
-     * model; the `provider/model` composite stays the submitted `id`, which is
-     * both what the engine receives as `--model` and how the driver validates a
-     * session-selected model against its catalog.
+     * The id is the model label the engine logs, so the picker resolves a hosted
+     * session's selection to this entry (and highlights its row) rather than
+     * falling through to the raw composite string; the name is the same word,
+     * rendered as-is.
+     * @returns the one entry this route advertises.
      */
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
     stream(_options: GenerateOptions): AsyncIterable<StreamChunk>;