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

package/lib/types/engine-remote.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The plugin's own Remote: "which engine does this session run?" and "move this
+ * session to another engine", both answered from the plugin's own per-session
+ * record, the session's live agent, and the durable log through one shared read.
+ *
+ * The browser half cannot answer the first question honestly from what the
+ * harness hands a page. The client Session list carries `projectionValues`
+ * computed by `@deepseek-ai/dsh-api-session-controller`'s `projectionsFor()`,
+ * which returns a `SessionProjectionHints` snapshot — "every currently cached
+ * wire value", and partial by its own documentation: a cell the page's cache has
+ * not folded yet is simply absent. The engine a session ACTUALLY runs is not a
+ * cache fact at all, so the plugin becomes its own authority:
+ *
+ *  - node half (here): a Typert Remote service, discovered by the host Gateway
+ *    through its visible `typertRemote` binding and its `@Remote` method marks
+ *    (`bindTypertRemote` / `@Remote` in `@deepseek-ai/dsh-typert-protocol`, the
+ *    same mechanism `@deepseek-ai/dsh-agent-presets` uses for its own roster).
+ *    Both endpoints go through {@link engineReportOfSession} /
+ *    {@link RouterLoop.reportEngine} / {@link RouterLoop.selectEngine} — the very
+ *    reads the router routes on — so what a session is driven by and what a
+ *    session is shown as running cannot disagree, because there is one answer.
+ *    The report carries the ONE case in which a session has two facts (a live
+ *    agent and a record that did not displace it) as two fields rather than
+ *    blending them; see {@link SessionEngineReport}.
+ *  - browser half (`src/client/session-engine.ts`): mounts these endpoints as
+ *    `remote.loopEngine.engine({ sessionId })` and
+ *    `remote.loopEngine.select({ sessionId, engine })`, and renders only what
+ *    they answer.
+ *
+ * Both methods take a PLAIN object parameter rather than an identity the Gateway
+ * resolves: typert resolves a parameter named `agent`/`session` into a LIVE
+ * object through its lookup providers, and these endpoints must answer for any
+ * PERSISTED session — including one no process has loaded.
+ *
+ * Wire contract (no codegen is involved; the Gateway derives the signature from
+ * the live method):
+ *
+ *  - endpoint `loopEngine/engine`;
+ *  - endpoint `loopEngine/select`;
+ *  - one `src-json` argument per endpoint whose wire name is the method's own
+ *    parameter name (`request`) — REQUIRED for the browser half to be
+ *    understood, so the parameter name is part of the contract and must not be
+ *    renamed or destructured (see the Gateway's `methodParameterNames`);
+ *  - `engine` results in the plain-JSON {@link SessionEngineReport} — the engine
+ *    the session ACTUALLY runs, plus (only while a live agent the record did not
+ *    displace keeps running) the one the record names; `select` results in the
+ *    plain-JSON {@link LoopEngineSelectResult} — a refusal is a VALUE, so a
+ *    predictable "no" travels as data the surface can render (a
+ *    {@link LoopEngineRefusalCode} plus the host's own sentence as detail, which
+ *    is what lets the browser half show localized copy instead of a raw English
+ *    one-liner), while only a malformed request is a `RemoteError`, and an
+ *    outcome carrying `reload` tells the browser half to reload the page, because
+ *    the switch was made to land by releasing the session's agent.
+ *
+ * @module dsh-loop-engine-allinone/engine-remote
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { type LoopEngineId, type SessionEngine, type SessionEngineReport, type LoopEngineSelectResult } from './agent-preset-ids.ts';
+/** Cordis service key AND wire namespace of the plugin's own Remote. */
+export declare const LOOP_ENGINE_REMOTE_KEY = "loopEngine";
+/** Endpoint method reporting one session's engine. */
+export declare const LOOP_ENGINE_REMOTE_METHOD = "engine";
+/** Endpoint method moving one session to another engine. */
+export declare const LOOP_ENGINE_REMOTE_SELECT_METHOD = "select";
+/** The wire request the reporting endpoint accepts. */
+export interface LoopEngineRequest {
+    /** The session to report on. A plain string, never a resolved live object. */
+    readonly sessionId: string;
+}
+/**
+ * The wire request the switching endpoint accepts. The engine is typed as a
+ * string because that is what the wire carries; the endpoint validates it
+ * against {@link LOOP_ENGINE_IDS} before anything acts on it.
+ */
+export interface LoopEngineSelectRequest {
+    /** The session to move. A plain string, never a resolved live object. */
+    readonly sessionId: string;
+    /** The engine that session should run. */
+    readonly engine: string;
+}
+/**
+ * The engine one session runs, read from the plugin's own record and the durable
+ * log (`engineOfSession`).
+ *
+ * The FALLBACK answer, not the whole one: it knows nothing about a live agent, so
+ * the endpoint uses it only while no router is mounted
+ * ({@link RouterSurfaceHolder}) — the mount window, in which no session is driven
+ * by this plugin anyway.
+ */
+export type SessionEngineResolver = (sessionId: SessionId) => Promise<SessionEngine>;
+/** Move one session to another engine, refusing with a reason rather than throwing. */
+export type SessionEngineSelector = (sessionId: SessionId, engine: LoopEngineId) => Promise<LoopEngineSelectResult>;
+/**
+ * The mounted loop router, as these two endpoints need it: the reporting read
+ * and the move, both of which only a live router can make.
+ *
+ * Structural rather than the class itself, so this module takes no build-time
+ * dependency on `./router-loop.ts` (which drags in the harness loop and every
+ * engine driver) and a test can stand in for it.
+ */
+export interface RouterSurface {
+    /** Report what one session actually runs, plus the recorded engine when the two differ. */
+    reportEngine(sessionId: SessionId): Promise<SessionEngineReport>;
+    /** Move one session to another engine, or answer why it was not moved. */
+    selectEngine(sessionId: SessionId, engine: LoopEngineId): Promise<LoopEngineSelectResult>;
+}
+/**
+ * Where the two endpoints find the mounted router.
+ *
+ * A holder rather than a fixed reference because the router is mounted
+ * asynchronously — and not at all until the harness's live patch reload drops the
+ * base bundle's `agent-loop` row (`src/index.ts` `mountRouter`). Until then both
+ * endpoints answer from what a router-less process still knows: the record and
+ * the log. A session that is not driven by this plugin has no live agent to
+ * report anyway, so the answers agree.
+ */
+export interface RouterSurfaceHolder {
+    /** The mounted router, or undefined while there is no router. */
+    current: RouterSurface | undefined;
+}
+/**
+ * `remote.loopEngine`: report one session's engine, and move it to another.
+ *
+ * Registered as a Cordis service under {@link LOOP_ENGINE_REMOTE_KEY} on the
+ * plugin's own fiber, so the binding and the method marks disappear with the
+ * plugin: a profile that mounts no Gateway never discovers it, and unmounting
+ * the plugin withdraws both.
+ */
+export declare class LoopEngineRemote extends TypertRemoteService {
+    private readonly resolve;
+    private readonly router;
+    private readonly warn;
+    /**
+     * @param ctx - the context the service (and its lifetime) belongs to.
+     * @param resolve - the router-less read; normally
+     *   `engineOfSession(ctx, sessionId, records)`.
+     * @param router - where both endpoints find the mounted loop router.
+     * @param warn - diagnostic sink for a session that could not be read.
+     */
+    constructor(ctx: Context, resolve: SessionEngineResolver, router: RouterSurfaceHolder, warn: (message: string) => void);
+    /**
+     * Report what one session runs — and, when its own record names a different
+     * engine than the live agent, that fact separately.
+     *
+     * The router answers when it is mounted, because the live agent outranks every
+     * record: only the router knows which engine built the agent driving this
+     * session now, and only the router can tell a record whose release did not take
+     * from one that already landed. Without a router (the mount-retry window) no
+     * session is driven by this plugin, so the record — i.e.
+     * {@link SessionEngineResolver} — is the whole answer.
+     *
+     * A session that cannot be read answers `unset` rather than throwing: a
+     * surface that asked about a session the durable log does not know must render
+     * "engine not recorded", not break the page it is rendered in. Failures are
+     * reported once on the host's log instead.
+     *
+     * A malformed REQUEST is a caller fault, not an unreadable session, and is
+     * refused the way every typert endpoint refuses one.
+     * @param request - the wire request carrying the session id.
+     * @returns the engine driving that session, plus the recorded engine it is not
+     * running when the two differ.
+     * @throws {RemoteError} with `gateway/bad-request` when no session id was sent.
+     */
+    engine(request: LoopEngineRequest): Promise<SessionEngineReport>;
+    /**
+     * Move one session to another engine.
+     *
+     * The move owns no policy of its own: the router decides whether this session
+     * can be moved right now and answers with a reason when it cannot, because
+     * only it knows the session's live agent, its turn state, and the teardown it
+     * would have to perform. This endpoint's job is the boundary — reject a
+     * malformed request the way every typert endpoint does, and hand a well-formed
+     * one to the selector.
+     * @param request - the wire request carrying the session id and target engine.
+     * @returns the engine now recorded for the session — with `reload: true` when
+     * its agent had to be released for the change to land, which the browser half
+     * acts on by reloading the page — or, as `ok: false`, the
+     * {@link LoopEngineRefusalCode} of the branch that refused it together with the
+     * host's own sentence about this session (`router-unmounted` is this
+     * endpoint's own, `session-closed` / `turn-running` / `subagent-session` /
+     * `not-driven` / `record-failed` / `rebuild-failed` come from the router's
+     * checks). The browser half localizes from the code and keeps the sentence as
+     * detail, so the code is part of this endpoint's contract even though the
+     * shape allows it to be absent.
+     * @throws {RemoteError} with `gateway/bad-request` when the session id is not
+     * a non-empty string or the engine is not an installed engine id.
+     */
+    select(request: LoopEngineSelectRequest): Promise<LoopEngineSelectResult>;
+}
+//# sourceMappingURL=engine-remote.d.ts.map

package/lib/types/engine-surface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-session command and skill surface of the hosted engines.
+ *
+ * A hosted engine owns its session's slash-command menu and skill catalog: the
+ * engine expands `/name` itself and reads its own instruction files, so the
+ * plugin bridges both into the session the engine serves and nothing more.
+ *
+ * The registrations are made through the AGENT's own context, which is what
+ * makes them session-scoped: `commands.register` and
+ * `skills.registerProvider` file a definition into the layer of the calling
+ * context's scope (`packages/core/scope/src/store.ts` `effect()` keys the layer
+ * by `scopeOf(ctx)`), and an agent's scope key is the agent itself
+ * (`createScope(loopCtx, this)` in the default loop; the hosted drivers do the
+ * same). Two sessions running different engines therefore never see each
+ * other's menus, and the whole surface disappears with the agent's scope — no
+ * plugin-side bookkeeping, no leak across an engine switch.
+ *
+ * @module dsh-loop-engine-allinone/engine-surface
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { HostedEngineId } from './settings.ts';
+/**
+ * Bridge one hosted engine's commands and skills into the session it serves.
+ *
+ * Best-effort like the rest of the plugin's host-service use: a profile without
+ * the commands or skills registry simply has no surface to extend. A name that
+ * collides with an already-registered command in the same layer is skipped with
+ * a warning rather than failing the agent: the engine expands the raw `/name`
+ * line itself, so a shyer menu beats an agent that refuses to start.
+ *
+ * @param agent - the freshly built agent whose scope owns the registrations.
+ * @param engine - the hosted engine driving that agent.
+ * @param warn - sink for the skip diagnostics.
+ */
+export declare function registerEngineSurface(agent: Agent, engine: HostedEngineId, warn: (message: string) => void): void;
+//# sourceMappingURL=engine-surface.d.ts.map

package/lib/types/engine-zcode/agent.d.ts

@@ -0,0 +1,50 @@
+/**
+ * ZCode agent: one `zcode -p "prompt"` child per dsh step, with the durable
+ * session log as the sole source of model context.
+ *
+ * Like the Hermes driver this reads stdout as a finished answer, and the reason
+ * is the same shape of fact recorded in `./process.ts`: the structured
+ * app-server surface exists but its request parameter shape could not be probed,
+ * so the driver uses the surface that is verified to reach the model rather than
+ * guessing a protocol.
+ *
+ * ZCode additionally needs its provider catalog located: run outside the desktop
+ * app the bundled CLI refuses to start a turn until
+ * `ZCODE_BUILTIN_PROVIDER_CONFIG_FILE` points at the app's own copy. The driver
+ * supplies the discovered default; a deployment's explicit `env` wins.
+ *
+ * @module dsh-loop-engine-allinone/engine-zcode/agent
+ */
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { HostedEngineId } from '../engine-registry.ts';
+import { CliHostedAgent } from '../driver-cli/cli-agent.ts';
+import type { SinkPosition } from '../driver-cli/session-sink.ts';
+import type { CliSpawnCapability } from '../driver-cli/transport.ts';
+import { zcodeArgvPrefix, zcodeBuiltinProviderConfig } from './process.ts';
+/** Deployment-resolved configuration for the ZCode engine. */
+export interface ResolvedZcodeConfig {
+    /** The argv prefix ending in the entrypoint. */
+    readonly prefix: readonly string[];
+    /** Explicit environment entries layered over the scrubbed parent environment. */
+    readonly env: Record<string, string>;
+    /** Pinned model. */
+    readonly model: string | undefined;
+    /** The discovered bundled provider catalog, when present. */
+    readonly providerConfig: string | undefined;
+}
+/** The engine id this driver registers under. */
+export declare const ZCODE_ENGINE: HostedEngineId;
+/** Drives one session through turn and step boundaries on ZCode. */
+export declare class ZcodeAgent extends CliHostedAgent {
+    private readonly config;
+    private readonly spawn;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedZcodeConfig, spawn: CliSpawnCapability);
+    protected runStep(messages: readonly UserMessage[], position: SinkPosition, signal: AbortSignal): Promise<{
+        kind: 'completed';
+    } | null>;
+}
+/** Re-exported so `./loop.ts` does not have to know how the prefix is built. */
+export { zcodeArgvPrefix, zcodeBuiltinProviderConfig };
+//# sourceMappingURL=agent.d.ts.map

package/lib/types/engine-zcode/loop.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ZCode loop engine module: drives every session it is handed through one
+ * `zcode -p "prompt"` child per dsh step, with the durable session log as the
+ * sole source of model context. The router routes a session here on the plugin's
+ * own engine record, else its agent preset; this module is a library, not a
+ * Cordis plugin entry.
+ *
+ * See `./process.ts` for why this driver uses ZCode's one-shot print surface
+ * rather than its JSON-RPC app-server, and what was and was not verified.
+ *
+ * @module dsh-loop-engine-allinone/engine-zcode
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { CliEngineRuntime } from '../driver-cli/cli-loop.ts';
+import { ZcodeAgent, type ResolvedZcodeConfig } from './agent.ts';
+/** Deployment-owned configuration for the ZCode engine. */
+export interface Config {
+    /** Model label (`--model`); ZCode's own settings own the model when omitted. */
+    model?: string;
+    /** Explicit environment entries passed to the child; these win over the discovered ones. */
+    env?: Record<string, string>;
+    /** The `zcode` entrypoint (a `.cjs` bundle or a native binary); auto-discovered when not pinned. */
+    bin?: string;
+}
+/** Schema of the ZCode engine configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const ZCODE_ENGINE_LABEL = "agentLoopZcode";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopZcode: ZcodeLoop;
+    }
+}
+/**
+ * Creation/resume machinery for the ZCode engine. The process-wide AgentFactory
+ * slot belongs to the router, which delegates each session to the engine its
+ * preset names; this class is that engine's driver, not a plugin.
+ */
+export declare class ZcodeLoop extends CliEngineRuntime<ResolvedZcodeConfig, ZcodeAgent> {
+    constructor(ctx: Context, config: Config);
+    /** Construct the ZCode driver for one prepared session. */
+    protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): ZcodeAgent;
+}
+//# sourceMappingURL=loop.d.ts.map

package/lib/types/engine-zcode/process.d.ts

@@ -0,0 +1,111 @@
+/**
+ * ZCode CLI process projection.
+ *
+ * ZCode is the Z.AI (GLM) coding CLI. It ships as a Node bundle at
+ * `resources/glm/zcode.cjs` inside the ZCode desktop app, so `argv[0]` is
+ * usually `process.execPath` and `argv[1]` the script — which is why the
+ * resolver returns an argv PREFIX rather than a single path.
+ *
+ * ## Why this driver uses the one-shot `-p` surface
+ *
+ * ZCode advertises two machine-facing surfaces, and they are not equally ready:
+ *
+ *  1. **`zcode app-server`** — a JSON-RPC stdio server. The probe
+ *     (`docs/probes/zcode.md`) confirmed the transport and captured its method
+ *     surface (`startup/*`, `session/create`, `session/send`,
+ *     `session/subscribe`, `session/events`, `session/event`, `session/stop`,
+ *     `session/setModel`, `session/setMode`, `session/resume`, `session/list`,
+ *     `session/compact`, `session/messages`, `session/read`, …) and its
+ *     server-initiated `startup/storageState` notifications. What the probe could
+ *     NOT obtain is the REQUEST parameter shape: `initialize` drew no response
+ *     frame at all, and every `session/create` attempt ended the run before a
+ *     reply. Writing a request shape from the method names alone would be
+ *     guessing, which the probe-first rule forbids.
+ *  2. **`zcode -p "prompt"`** — the documented one-shot print mode. The probe
+ *     confirmed it runs and produces a result, but every run stopped at
+ *     `ProviderBusinessError [1309] … GLM Coding Plan 已到期` (the machine's GLM
+ *     Coding Plan subscription has lapsed), so the SUCCESS output shape is also
+ *     unverified.
+ *
+ * So this driver takes the surface that is verified to at least reach the model,
+ * treats stdout as the answer, and declares `protocol: 'text'` /
+ * `streaming: false` in the registry — an honest statement of what the DRIVER
+ * does, not of what the CLI could do. Upgrading it to the app-server protocol is
+ * the recorded next step (`docs/engine-registry.md` §6, TODO).
+ *
+ * @module dsh-loop-engine-allinone/engine-zcode/process
+ */
+import type { CliSpawnRequest } from '../driver-cli/transport.ts';
+/** Grace in milliseconds for ZCode process-tree termination. */
+export declare const ZCODE_DISPOSE_GRACE_MS = 3000;
+/** The `--mode` values the CLI accepts. */
+export declare const ZCODE_MODES: readonly ["build", "edit", "plan", "yolo"];
+/** One ZCode permission mode. */
+export type ZcodeMode = (typeof ZCODE_MODES)[number];
+/**
+ * Resolve the argv prefix that launches ZCode.
+ *
+ * Three shapes, and the difference is why this returns an array: a pinned `.cjs`
+ * path runs under the current node (the bundled form), a pinned native binary is
+ * spawned directly, and with nothing pinned the well-known bundle is used before
+ * falling back to a `zcode` on PATH.
+ * @param configBin - an operator-pinned executable or script, if any.
+ * @returns the argv prefix ending in the ZCode entrypoint.
+ */
+export declare function zcodeArgvPrefix(configBin?: string): string[];
+/**
+ * The environment entry the bundled ZCode needs to find its own provider
+ * catalog.
+ *
+ * Discovered by the probe: run outside the desktop app, the bundle reports
+ * `无法定位 CLI ZCode Built-in Provider Config` and refuses to start a turn until
+ * this variable points at the app's own `zcode-builtin.json`. The driver sets it
+ * only when the deployment has not — an explicit deployment value always wins.
+ */
+export declare const ZCODE_PROVIDER_CONFIG_ENV = "ZCODE_BUILTIN_PROVIDER_CONFIG_FILE";
+/** The bundled provider catalog inside the desktop app, when it exists. */
+export declare function zcodeBuiltinProviderConfig(): string | undefined;
+/**
+ * Map the session's dsh knobs onto ZCode's `--mode`.
+ *
+ * Fail-closed like the other engines: full access is the only thing that earns
+ * `yolo`; everything else, including "no knobs at all", gets the CLI's own
+ * `build` mode, and the subprocess sandbox remains the real boundary.
+ * @param sandbox - the session's durable sandbox mode, if any.
+ * @returns the mode to pass.
+ */
+export declare function zcodeMode(dangerFullAccess: boolean): ZcodeMode;
+/** Everything one step's ZCode child needs. */
+export interface ZcodeSpawnSpec {
+    /** The argv prefix ending in the entrypoint. */
+    readonly prefix: readonly string[];
+    /** The prompt, passed as an argv argument. */
+    readonly prompt: string;
+    /** The session's working directory. */
+    readonly cwd: string;
+    /** Explicit environment entries layered over the scrubbed parent environment. */
+    readonly env: Record<string, string>;
+    /** Pinned model (`--model` is not a flag; ZCode selects a model per session). */
+    readonly model: string | undefined;
+    /** Resolved permission mode. */
+    readonly mode: ZcodeMode;
+    /** Cancellation. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Build the argv for one non-interactive ZCode step.
+ * @param spec - the step's spawn spec.
+ * @returns the argv.
+ */
+export declare function zcodeArgv(spec: ZcodeSpawnSpec): string[];
+/**
+ * Project one step's spawn spec onto the transport request.
+ *
+ * The provider-catalog variable is merged UNDER the deployment's own entries, so
+ * an explicit `env` always wins over the discovered default.
+ * @param spec - the step's spawn spec.
+ * @param providerConfig - the discovered catalog path, if any.
+ * @returns the transport's request shape.
+ */
+export declare function zcodeSpawnRequest(spec: ZcodeSpawnSpec, providerConfig: string | undefined): CliSpawnRequest;
+//# sourceMappingURL=process.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Per-session agent loop engines, node half.
+ *
+ * Hosts the non-default agent-loop engines (Claude Code, Codex, Pi, Kimi Code)
+ * and routes each session to the engine it runs. The engine is the PLUGIN's own
+ * per-session fact (`session-engine-store.ts`), read first and over the recorded
+ * agent preset; a session the plugin has no record for keeps the preset answer,
+ * which is what makes every pre-existing session behave exactly as before.
+ * The harness admits exactly one AgentFactory per process, so "session A on
+ * Codex while session B runs Kimi" is realized by a single router factory
+ * ({@link RouterLoop}, which extends the harness's own `AgentLoop`) dispatching
+ * to one driver runtime per engine; `in-process` sessions keep the harness loop
+ * through that same router.
+ *
+ * Because the router owns the slot, the plugin keeps the base bundle's
+ * `agent-loop` row disabled for as long as it is composed. That managed block
+ * lives in the profile's `cordis.patch.yml` (see `patch-manager.ts`) and is the
+ * plugin's only footprint in the harness's configuration alongside the preset
+ * rows below; the block names no engine, because the engine is a per-session
+ * decision.
+ *
+ * The plugin authors one preset per hosted engine — each a copy of `standard`
+ * minus the dsh-native command and skill rows an external engine replaces — and
+ * it serves every hosted engine's provider route label in the llm registry
+ * (`provider-route.ts`): an engine logs its own label into each session's
+ * request/header, and the web host refuses a turn whose session selection names
+ * a provider no adapter serves. WHERE that copy lives depends on the harness
+ * generation — a directory under `$DSH_HOME/.agent-presets/loop-engine-<engine>`
+ * on the 0.1.5 line, a `@deepseek-ai/dsh-agent-preset` insert row in the profile
+ * patch on the 0.1.7 line, which stopped reading the directory (see
+ * `preset.ts`, {@link authorHostedPresets}). The preset is now only the
+ * session's agent-plane composition (and the engine's own default for a session
+ * with no record) — it is no longer the thing that decides a running session's
+ * engine.
+ *
+ * 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
+ * chat composer, and when it involves the harness loop it releases that session's
+ * agent and reloads the page — `router-loop.ts` `move`, `client/reload.ts`.)
+ *
+ * @module dsh-loop-engine-allinone
+ */
+import type { Context, Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { EngineDriverConfig } from './engine-drivers.ts';
+import type { CodexApprovalPolicy, CodexSandboxMode } from './engine-codex/types.ts';
+import type { SummarizerTarget } from './preset.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
+ * own: the optional host services it reads (`commands`, `skills`, `agentPresets`,
+ * `llm`) are resolved lazily via `ctx.get` and may be absent, and the router
+ * declares the harness loop's own dependency set when it mounts. Empty keeps
+ * the plugin from demanding a service that a minimal profile does not provide.
+ */
+export declare const inject: never[];
+/** Composition entry for the loop engine selection and the hosted engine drivers. */
+export interface Config extends EngineDriverConfig {
+    /** Profile whose `cordis.patch.yml` carries the managed block; defaults to `web`. */
+    profile?: string;
+    /** Patch file name inside the profile; defaults to `cordis.patch.yml`. */
+    patchFilename?: string;
+    /** Explicit absolute path to the patch file, overriding profile + filename. */
+    patchPath?: string;
+    /** Pinned sandbox mode for the Codex and Pi children; falls back to the session's dsh permission knobs. */
+    sandboxMode?: CodexSandboxMode;
+    /** Pinned Codex approval policy; falls back to the session's dsh permission knobs. */
+    approvalPolicy?: CodexApprovalPolicy;
+    /**
+     * Idle window in milliseconds after which a hosted session's PERSISTENT child
+     * process (Kimi's `kimi acp`, Codex's app-server) is shut down and spawned
+     * again by the next step. Zero or omitted keeps the child for the session's
+     * whole life. Only these two engines hold a child between steps: the Pi and
+     * Claude Code drivers spawn per step, so the knob does not reach them.
+     */
+    childIdleMs?: number;
+    /**
+     * Context window (in tokens) dsh assumes for the hosted provider route.
+     *
+     * A hosted engine reports no capacity to dsh — each owns its model inside its
+     * own child process — so this is the number dsh's auto-compaction sizes its
+     * pressure threshold from (default threshold ratio `0.8` of it, so compaction
+     * fires once a hosted session's replayed transcript crosses 80% of this). It
+     * is declared on the placeholder route (`src/provider-route.ts`
+     * `resolveModel`); without it the pressure path warns once and compaction
+     * never fires. A deployment running several engines should set it to the
+     * SMALLEST engine window in use, so the threshold that fires is safe for
+     * every engine. Defaults to
+     * {@link DEFAULT_ENGINE_CONTEXT_WINDOW} (262144).
+     */
+    engineContextWindow?: number;
+    /**
+     * Dsh provider route a hosted session's compaction SUMMARIZES through; set
+     * together with {@link Config.summarizerModel}, or not at all.
+     *
+     * The pair is only needed because a hosted engine's own model cannot serve
+     * that call: compaction summarizes with an ordinary llm request, and a hosted
+     * session's routed model is this plugin's placeholder route
+     * (`external/default`), whose `stream()` fails loud. Without the pair the
+     * plugin leaves the composition it authors untouched, and every compaction
+     * attempt logs a warning and lets the turn continue — the safe degraded mode,
+     * in which the session log is never folded. The plugin writes the pair into
+     * its own hosted presets (`src/preset.ts` `applySummarizerTarget`) because a
+     * profile-patch row replaces its target's whole `config`, and the patch index
+     * does not descend into a preset's `config.plugins` — the nested
+     * `compaction-basic` row is reachable only from the composition the plugin
+     * authors, never from the deployment's profile patch.
+     */
+    summarizerProvider?: string;
+    /**
+     * Dsh model id on {@link Config.summarizerProvider} that hosted sessions
+     * summarize through; must be set together with it.
+     */
+    summarizerModel?: 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>;
+    /** Whether the conversation header shows the engine badge; a live, profile-backed field. */
+    showEngineBadge: Volatile<boolean>;
+}
+/** Rejected input of the composition entry: live fields arrive as plain values and resolve to references. */
+type ConfigInput = Omit<Config, 'engine' | 'showInComposer' | 'showEngineBadge'> & {
+    engine?: LoopEngineId;
+    showInComposer?: boolean;
+    showEngineBadge?: boolean;
+};
+/**
+ * Schema of the loop engine composition entry.
+ *
+ * A schemastery object validates each field only when it is present and lets
+ * an absent key fall through as `undefined`, so omitted knobs are accepted —
+ * matching the permissive interface and read path (`resolvePatchPath` defaults
+ * the patch path; each engine driver resolves only the knobs it owns and
+ * 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`, `showInComposer`, and `showEngineBadge` 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<ConfigInput, Config>;
+/** Resolve the managed patch file from configuration, defaulting to the web profile. */
+export declare function resolvePatchPath(config: Config): string;
+/**
+ * Resolve the summarization model the plugin writes into every hosted preset,
+ * or `undefined` when the deployment names none.
+ *
+ * The two knobs are one decision — a provider route without a model (or the
+ * reverse) cannot be resolved to a call — so a half-set pair is a
+ * misconfiguration rather than a usable half, and it fails loud here instead of
+ * being dropped on the floor. This runs as the plugin applies, i.e. at compose
+ * time, and it runs before anything is written, so a bad profile never leaves a
+ * half-authored patch file behind.
+ *
+ * Schemastery has no cross-field check, so the schema keeps the two fields
+ * permissive and the rule is enforced here (the same compose-time posture the
+ * engine loops take for their own resolved config).
+ * @param config - the composition entry's static knobs.
+ * @returns the summarization target, or undefined when neither field is set.
+ * @throws when exactly one field is set, or either one is an empty string.
+ */
+export declare function resolveSummarizerTarget(config: Config): SummarizerTarget | undefined;
+/** Atomically replace the patch file (same-directory temp + rename). */
+export declare function writePatchFile(path: string, text: string): Promise<void>;
+/**
+ * Synchronously atomically replace the patch file. The settings onChange that
+ * commits a default-engine change is a synchronous hook with no await, and the
+ * write MUST land before the caller is told the change committed — otherwise a
+ * user who restarts `dsh web` immediately reads the stale file.
+ * @param path - the profile's patch file.
+ * @param text - the next file content.
+ */
+export declare function writePatchFileSync(path: string, text: string): void;
+/**
+ * Ensure the profile's patch file carries the plugin's managed block, which
+ * disables the base bundle's `agent-loop` row so this plugin's router owns the
+ * single AgentFactory slot. Idempotent: a file already carrying a block and no
+ * legacy block is left untouched.
+ * @param path - the profile's patch file.
+ * @returns whether a write occurred.
+ */
+export declare function syncManagedBlock(path: string): Promise<boolean>;
+/**
+ * Apply the plugin: own the profile's managed block, mount the routing factory,
+ * author the per-engine presets, and serve every hosted engine's provider
+ * route. The settings section carries the deployment's default engine.
+ * @param ctx - the composing context.
+ * @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