dsh-loop-engine 0.1.5-rc5 → 0.1.7-rc1

package/lib/types/driver-core/host-servers.d.ts

@@ -30,8 +30,12 @@ export interface SkillsService {
 export interface AgentPresetsService {
     /** The effective default preset id. */
     readonly defaultId: string;
-    /** Read one preset's composition text. */
-    read(id: string): Promise<string>;
+    /** 0.1.5 line: read one preset's composition text directly. */
+    read?(id: string): Promise<string>;
+    /** 0.1.7 line: read one preset's document; its `content` is the composition text. */
+    readDocument?(id: string): Promise<{
+        readonly content: string;
+    }>;
 }
 /** The host settings service's mutation seam, as this plugin uses it. */
 export interface SettingsMutator {

package/lib/types/driver-core/hosted-engine-runtime.d.ts

@@ -91,9 +91,9 @@ export interface SwapAgentOptions {
  *
  * Creation and resume follow the registry factory contract and the shared
  * publication transaction: prepare, run setup, then publish through both
- * registries, announce, and emit `agent/session-start`. {@link swap} follows the
- * same transaction onto a session another agent entered, which is the only
- * difference between taking a session over and owning it from birth.
+ * registries and await the serial `agent/created` announcement. {@link swap}
+ * follows the same transaction onto a session another agent entered, which is
+ * the only difference between taking a session over and owning it from birth.
  */
 export declare abstract class HostedEngineRuntime<TConfig, TAgent extends HostedAgent> implements AgentFactory {
     /** Validated configuration owned by this engine instance. */

package/lib/types/driver-core/system-head.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Give a session started on a hosted engine the protected system head the
+ * harness's own loop would have logged.
+ *
+ * The harness loop logs the rendered system prompt as a `system/message` on a
+ * session's first step (`packages/core/agent-loop/src/agent.ts`:
+ * `systemPrompt.project` → `session.append('system/message', …)`). A hosted
+ * engine's external CLI owns its own system prompt, so these drivers log no dsh
+ * system message at all: a session that STARTS on a hosted engine has no surface
+ * head, and if it is later served by the in-process loop the harness logs its
+ * system message MID-log. Session format v4 requires the system message — when
+ * one exists — to be the FIRST surface event, so such a mixed session is refused
+ * on the v3→v4 migration (`packages/session/session-format-v3-to-v4/src/
+ * relationships.ts` `foldSurface`: "system/message requires a protected first
+ * surface head").
+ *
+ * Appending an EMPTY system message as the session's first surface event closes
+ * that hole: the head is protected from the start (a later in-process system
+ * message REPLACES it rather than arriving misplaced), and empty content is
+ * dropped from the derived history (`deriveEventMessage` yields `null`), so no
+ * system prompt is injected into what the engine is handed — the drivers build
+ * their prompt from `serializeHistory`, which ignores the `system` role too.
+ *
+ * Conservative and idempotent: it appends ONLY while the session has no surface
+ * event of its own, so a session the harness loop created (or one already
+ * carrying history) is left exactly as it is. A mid-surface system head would be
+ * refused by the SAME v4 rule and is never produced here.
+ *
+ * @module dsh-loop-engine/driver-core/system-head
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+/**
+ * Append an empty `system/message` head when the session has no surface event
+ * yet, so a hosted-engine session carries the protected head format v4 expects.
+ *
+ * A no-op once any surface event exists: the head can only ever be the FIRST
+ * surface event, and a later one would be refused on migration.
+ * @param session - the session a hosted driver is about to run a step on.
+ * @param turn - the open turn's number.
+ * @param step - the open step's number.
+ */
+export declare function appendSystemHeadIfMissing(session: Session, turn: number, step: number): void;
+//# sourceMappingURL=system-head.d.ts.map

package/lib/types/index.d.ts

@@ -29,7 +29,7 @@
  * with no record) — it is no longer the thing that decides a running session's
  * engine.
  *
- * The `agent-loop-engine` settings section carries the DEFAULT engine for new
+ * The plugin's own live `engine` Config field carries the DEFAULT engine for new
  * sessions — which preset the roster's default points at — not a process-wide
  * switch: existing sessions keep the engine they run, and nothing is torn down or
  * reloaded by it. (A PER-SESSION switch is a different thing: it is made from the
@@ -38,10 +38,11 @@
  *
  * @module dsh-loop-engine
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { type Config as ClaudeCodeConfig } from './engine-claude/loop.ts';
 import type { CodexApprovalPolicy, CodexSandboxMode } from './engine-codex/types.ts';
+import { type LoopEngineId } from './settings.ts';
 export declare const name = "loop-engine";
 /**
  * Services the plugin's own fiber requires. The plugin declares none of its
@@ -69,7 +70,20 @@ export interface Config extends ClaudeCodeConfig {
     piThinking?: string;
     /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
     kimiBin?: string;
+    /**
+     * Default engine NEW sessions are created on. A live, profile-backed field:
+     * the settings shell edits it and the running plugin reads it through this
+     * volatile reference (`config.engine.get()`).
+     */
+    engine: Volatile<LoopEngineId>;
+    /** Whether the chat composer shows the engine picker; a live, profile-backed field. */
+    showInComposer: Volatile<boolean>;
 }
+/** Rejected input of the composition entry: live fields arrive as plain values and resolve to references. */
+type ConfigInput = Omit<Config, 'engine' | 'showInComposer'> & {
+    engine?: LoopEngineId;
+    showInComposer?: boolean;
+};
 /**
  * Schema of the loop engine composition entry.
  *
@@ -80,8 +94,15 @@ export interface Config extends ClaudeCodeConfig {
  * omitted deployment tunables fall back to the session). The composition entry
  * is an engine-agnostic superset: every hosted engine's knobs live here at
  * once, because any session may select any engine.
+ *
+ * On the 0.1.7 line `engine` and `showInComposer` are the entry's live fields:
+ * `.volatile()` makes them profile-backed settings the settings shell projects
+ * as form fields, and the runtime reads each one through its reference
+ * (`config.engine.get()`). On the 0.1.5 line there are no live Config fields —
+ * the selection is a settings section (`LOOP_ENGINE_SETTINGS_SCHEMA`), whose
+ * provider owns the storage — so the entry is the engine knobs alone.
  */
-export declare const Config: z<Config>;
+export declare const Config: z<ConfigInput, Config>;
 /** Resolve the managed patch file from configuration, defaulting to the web profile. */
 export declare function resolvePatchPath(config: Config): string;
 /** Atomically replace the patch file (same-directory temp + rename). */
@@ -112,4 +133,5 @@ export declare function syncManagedBlock(path: string): Promise<boolean>;
  * @param config - composition entry for the managed patch file and engine knobs.
  */
 export declare function apply(ctx: Context, config: Config): void;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/lib/types/namespace.d.ts

@@ -1,9 +1,25 @@
 /**
- * Loop engine namespace literal: the one string both halves agree on, in a
- * module with no runtime imports so the browser bundle can import it without
+ * 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/namespace
  */
-/** Settings namespace carrying the deployment's selected agent loop engine. */
-export declare const LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL = "agent-loop-engine";
+/**
+ * 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/preset.d.ts

@@ -68,10 +68,14 @@ export declare const STRIPPED_ROWS: readonly ["skill-filesystem", "tool-skill",
  * @returns the stripped composition.
  */
 export declare function stripPresetRows(text: string, ids?: readonly string[]): string;
-/** Minimal read seam over the host's preset roster (`AgentPresets.read`). */
+/** Minimal read seam over the host's preset roster, per harness generation. */
 export interface PresetCompositionSource {
-    /** Read one preset's composition text; throws when the id is unknown. */
-    read(id: string): Promise<string>;
+    /** 0.1.5 line: read one preset's composition text; throws when the id is unknown. */
+    read?(id: string): Promise<string>;
+    /** 0.1.7 line: read one preset's document; `content` is the composition text. */
+    readDocument?(id: string): Promise<{
+        readonly content: string;
+    }>;
 }
 /**
  * Regenerate every hosted engine's preset under the dsh home's user preset root

package/lib/types/settings.d.ts

@@ -1,21 +1,30 @@
 /**
- * Shared loop-engine identity, namespace, and schema.
+ * Shared loop-engine identity, namespaces, and schemas.
  *
- * Both the namespace literal and the engine/preset-id mapping live in
+ * Both the namespace literals and the engine/preset-id mapping live in
  * zero-import modules (`./namespace.ts`, `./agent-preset-ids.ts`) so both halves
  * agree on them: the node half brands the literal as a `SettingsNamespace` and
- * builds this schema, while the browser half imports the same literals without
- * pulling host-side packages (`dsh-settings`, `schemastery`, `node:fs`) into the
- * client bundle (cross-plugin value imports go through cordis services, and
- * `settings-scope.ts` follows the same discipline). This module re-exports them
- * so node-side importers keep their paths.
+ * builds these schemas, while the browser half imports the same literals
+ * without pulling host-side packages (`dsh-settings`, `schemastery`, `node:fs`)
+ * into the client bundle (cross-plugin value imports go through cordis
+ * services). This module re-exports them so node-side importers keep their
+ * paths.
+ *
+ * The two live schema families exist because one build serves two harness
+ * generations: the 0.1.5 line addresses a settings SECTION registered by a
+ * provider under a namespace string ({@link LOOP_ENGINE_SETTINGS_SCHEMA} via
+ * {@link loopEngineSettingsNamespace}), while the 0.1.7 line makes the plugin's
+ * two live fields profile-backed Config entries
+ * ({@link LOOP_ENGINE_ENGINE_SCHEMA} / {@link LOOP_ENGINE_SHOW_IN_COMPOSER_SCHEMA}).
+ * Which family a running plugin builds is decided by `./compat.ts`
+ * (`LEGACY_HARNESS`) in `./index.ts`.
  *
  * @module dsh-loop-engine/settings
  */
 import z from '@deepseek-ai/schemastery';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import type { LoopEngineId } from './agent-preset-ids.ts';
-export { LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL } from './namespace.ts';
+export { LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL, LEGACY_LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL } from './namespace.ts';
 export { HOSTED_ENGINE_IDS, HOSTED_PRESET_PREFIX, LOOP_ENGINE_IDS, SOURCE_PRESET_ID, engineOfPreset, enginePresetId, } from './agent-preset-ids.ts';
 export type { HostedEngineId, LoopEngineId } from './agent-preset-ids.ts';
 /** Stored and composed loop engine selection. */
@@ -26,10 +35,21 @@ export interface LoopEngineSettings {
     showInComposer: boolean;
 }
 /**
- * Schema of the loop engine settings section. The engine union derives from
- * {@link LOOP_ENGINE_IDS}, so adding an engine there also admits it here.
+ * Schema of the loop engine settings section, as the 0.1.5 line's settings host
+ * consumes it. The engine union derives from {@link LOOP_ENGINE_IDS}, so adding
+ * an engine there also admits it here.
  */
 export declare const LOOP_ENGINE_SETTINGS_SCHEMA: z<LoopEngineSettings>;
-/** The shared literal branded as a settings namespace on the node side. */
+/** The 0.1.5-line namespace branded as a settings namespace on the node side. */
 export declare function loopEngineSettingsNamespace(): SettingsNamespace;
+/**
+ * Live Config field schema for the default engine (0.1.7 line). `.volatile()`
+ * declares it profile-backed: the settings shell projects it as a form field,
+ * and a committed edit reaches the running plugin through the live Config
+ * reference. The engine union derives from {@link LOOP_ENGINE_IDS}, so adding
+ * an engine there admits it here too.
+ */
+export declare const LOOP_ENGINE_ENGINE_SCHEMA: z<"in-process" | "claude-code" | "codex" | "pi" | "kimi", "in-process" | "claude-code" | "codex" | "pi" | "kimi", "volatile-defined">;
+/** Live Config field schema for the composer picker toggle (0.1.7 line). */
+export declare const LOOP_ENGINE_SHOW_IN_COMPOSER_SCHEMA: z<boolean, boolean, "volatile-defined">;
 //# sourceMappingURL=settings.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-loop-engine",
   "description": "Web-switchable agent loop engine selection for the DeepSeek Harness - out-of-tree plugin (Claude Code / Codex / Pi / Kimi Code drivers) maintained by @kuun993, zero main-repo changes",
-  "version": "0.1.5-rc5",
+  "version": "0.1.7-rc1",
   "publishConfig": {
     "access": "public"
   },
@@ -63,39 +63,39 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.220",
     "@anthropic-ai/sdk": "0.93.0",
-    "@deepseek-ai/schemastery": "3.18.1",
+    "@deepseek-ai/schemastery": "3.18.4",
     "@earendil-works/pi-coding-agent": "0.84.3",
     "@openai/codex": "0.149.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-agent-loop": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-scope": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-settings": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-subprocess": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-timeout": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.5-rc.2"
+    "@deepseek-ai/dsh-agent": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-agent-loop": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-invariants": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-scope": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-session": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-session-persistence": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-settings": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-subprocess": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-timeout": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0",
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-rc.1 <0.1.8-0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent-loop": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-attachment": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-locale": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-store": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-home-paths": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-subprocess-local": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-attachment": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-store": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-home-paths": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.1",
     "@types/node": "^22.20.0",
     "@types/react": "^19.0.0",
     "@vitest/coverage-v8": "^4.1.8",