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

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

@@ -0,0 +1,584 @@
+/**
+ * The engine registry: the ONE data table every engine-shaped decision derives
+ * from.
+ *
+ * Before this module the engine roster lived in five places that had to be kept
+ * in step by hand — the `LOOP_ENGINE_IDS` array, the `buildEngine` switch, the
+ * settings schema's engine union, the preset display-name map, and the browser
+ * half's option list and glyph table. Adding an engine meant finding all of
+ * them, and a miss showed up as an engine that mounts but cannot be selected, or
+ * one the settings schema rejects. Now the roster is declared ONCE here and
+ * everything else is derived:
+ *
+ *   - {@link HOSTED_ENGINE_IDS} / {@link LOOP_ENGINE_IDS} (this module)
+ *   - the settings schema's union (`./settings.ts` maps the ids to `z.const`)
+ *   - the preset id prefix arithmetic (`./agent-preset-ids.ts`)
+ *   - the browser half's option list, glyph and copy key (`./client/**`)
+ *   - the driver dispatch (`./engine-drivers.ts`, which is the one node-side
+ *     table that must import the engine modules — it cannot live here)
+ *
+ * ## Why this module imports NOTHING
+ *
+ * It is read by the browser bundle (the settings page renders the option list
+ * from it), and the client artifact must never pull a host package
+ * (`dsh-settings`, `schemastery`, `node:fs`) into the browser. So this file is
+ * plain data and pure functions — no imports at all, not even type-only ones
+ * from a host package. `tests/agent-preset-ids.spec.ts` pins that property.
+ *
+ * Anything that needs the host (probing a binary, reading an auth file, spawning
+ * a child) lives in `./engine-probe.ts` on the node side and is keyed by
+ * {@link EngineDescriptor.id}. The split is the reason a descriptor can declare
+ * `authPaths` — a fact the settings page renders — while the *probe* that reads
+ * them stays out of the browser bundle.
+ *
+ * ## Adding an engine
+ *
+ * 1. add its id to {@link HOSTED_ENGINE_IDS};
+ * 2. add its {@link EngineDescriptor} row to {@link ENGINE_REGISTRY} (TypeScript
+ *    refuses the build until the record is exhaustive again);
+ * 3. add its driver to `./engine-drivers.ts` (same exhaustiveness rule);
+ * 4. add its copy to `./client/locales.ts` under the descriptor's
+ *    {@link EngineDescriptor.localeKey}.
+ *
+ * Nothing else: the settings schema, the preset ids, the option lists and the
+ * glyph table all read this table.
+ *
+ * @module dsh-loop-engine-allinone/engine-registry
+ */
+/**
+ * The wire shape an engine speaks, as a coarse family.
+ *
+ * The four families are the ones the drivers' protocol skeletons implement
+ * (`./driver-cli/`): line-delimited JSON frames, JSON-RPC 2.0, the Agent Client
+ * Protocol (JSON-RPC with ACP's method names), and plain text. The value is
+ * declared rather than inferred so the settings page can say what an engine can
+ * do without importing the driver.
+ */
+export declare const ENGINE_PROTOCOLS: readonly ["ndjson", "jsonrpc", "acp", "text"];
+/** One engine's wire-protocol family. */
+export type EngineProtocol = (typeof ENGINE_PROTOCOLS)[number];
+/**
+ * What one engine can do, declared rather than discovered.
+ *
+ * Every surface that would otherwise hardcode "engine X supports Y" reads this
+ * instead: the settings page hides a control an engine cannot honour, and a
+ * driver asked for something outside its declaration fails loud rather than
+ * pretending. A capability that is genuinely unknown is declared `false` — the
+ * rule is that a surface must never claim more than the engine was verified to
+ * do (`docs/engine-registry.md` records what was verified and how).
+ */
+export interface EngineCapabilities {
+    /** Whether the engine streams partial output, rather than answering in one block at the end. */
+    readonly streaming: boolean;
+    /** The wire-protocol family the driver speaks. */
+    readonly protocol: EngineProtocol;
+    /** Whether a session can be continued by id across separate process launches. */
+    readonly sessionResume: boolean;
+    /**
+     * The engine's own permission/approval mode names, when it has a mode switch
+     * the driver can map dsh's sandbox/approval knobs onto. Absent means the
+     * engine has no such switch — the driver then relies on the subprocess
+     * sandbox alone, and the settings page shows no mode control.
+     */
+    readonly permissionModes?: readonly string[];
+    /** Whether the engine accepts image input natively. */
+    readonly images: boolean;
+    /** Whether the engine exposes a reasoning-effort/thinking level. */
+    readonly reasoningLevels: boolean;
+    /**
+     * The ACP protocol version this engine's client announces at `initialize`.
+     *
+     * Declared rather than hardcoded because three engines now share ONE ACP
+     * skeleton (`driver-acp/`): before it, the announced version was a constant
+     * inside that client, so an engine that moved to a different protocol version
+     * would have been advanced — or silently frozen — for all of them at once. The
+     * value is per engine and optional; an engine that omits it (or that does not
+     * speak ACP at all) is announced as {@link DEFAULT_ACP_PROTOCOL_VERSION}.
+     */
+    readonly acpProtocolVersion?: number;
+}
+/**
+ * The ACP protocol version a client announces when its engine's row declares
+ * none.
+ *
+ * `1` is what every ACP engine on this fork's reference host answered to a client
+ * that announced `1` (measured: kimi, grok and MiniMax Code all reply
+ * `protocolVersion: 1`), and it is also the value the shared client sent before
+ * this became registry data — so an engine that declares nothing keeps the
+ * behavior it had.
+ */
+export declare const DEFAULT_ACP_PROTOCOL_VERSION = 1;
+/**
+ * One engine's account REGION, when its CLI makes the account's region a
+ * first-class deployment fact.
+ *
+ * MiniMax Code is the case: its login endpoint is region-scoped
+ * (`mcode login --region cn|global`), its credentials are stored per region
+ * (`~/.minimax/auth/prod/<region>/…`) and its own environment variable
+ * (`MCODE_REGION`) selects one. The descriptor declares the knob so the driver
+ * can set it on the child WITHOUT naming the engine's variable in shared code,
+ * and a deployment can override the default.
+ */
+export interface EngineRegion {
+    /** The composition-entry key a deployment sets to override {@link default}. */
+    readonly configKey: string;
+    /** The environment variable the CLI reads. */
+    readonly envVar: string;
+    /** The region used when a deployment pins none. */
+    readonly default: string;
+    /** Every region value the CLI accepts. */
+    readonly values: readonly string[];
+}
+/**
+ * One model an engine offers from its OWN subscription.
+ *
+ * Distinct from a dsh model: a hosted engine answers with its own account, so
+ * these ids are the engine's vocabulary, not something any dsh adapter serves.
+ * Picking one in the model menu hands that id to the engine (`--model <id>`),
+ * which is how a user chooses among the models their subscription includes
+ * instead of accepting "the engine decides".
+ *
+ * The list is DECLARED rather than discovered, for the same reason the
+ * capabilities are: probing an engine's catalog means spawning it, and this
+ * plugin's contract is that booting the harness starts **no** external process.
+ * A deployment whose subscription changed refreshes the list by editing it —
+ * and a stale id fails loudly at the engine, which is the honest outcome.
+ */
+export interface EngineModel {
+    /** The engine's own model id, passed verbatim to the engine. */
+    readonly id: string;
+    /** Human-readable name shown in the model menu. */
+    readonly label: string;
+}
+/**
+ * Everything the rest of the plugin needs to know about one engine, as data.
+ *
+ * The two groups are deliberately different in kind: the fields above
+ * {@link capabilities} are deployment facts (where the binary is, how to
+ * upgrade it, whether it ships with the plugin), and `capabilities` is what the
+ * engine can do. A surface that renders an engine reads the second; the settings
+ * page's engine-management area reads the first.
+ */
+export interface EngineDescriptor {
+    /** Stable engine id: the value stored in settings, records and preset ids. */
+    readonly id: string;
+    /** Human-readable name, used for the authored preset's metadata and as the fallback label. */
+    readonly label: string;
+    /** Where the engine comes from, shown as a link in the settings page's engine-management area. */
+    readonly repo?: string;
+    /**
+     * Whether the engine ships as an npm dependency of this plugin.
+     *
+     * The distinction is load-bearing rather than cosmetic: a bundled engine's
+     * version is pinned by this package's `package.json`, so it is upgraded by
+     * changing the dependency and reinstalling — never by running the CLI's own
+     * updater at runtime. Only an external CLI gets an upgrade button.
+     */
+    readonly bundled: boolean;
+    /**
+     * The composition-entry key that pins this engine's executable, when the
+     * deployment may point it at its own build. External CLIs and the bundled
+     * engines that can be unbound (`claude`'s SDK option, codex's and pi's own
+     * binaries) both carry one; an engine that can only ever run the bundled copy
+     * omits it.
+     */
+    readonly binConfigKey?: string;
+    /** argv (after the executable) that prints the engine's version. */
+    readonly versionArgv?: readonly string[];
+    /**
+     * argv (after the executable) that updates an EXTERNAL CLI in place.
+     *
+     * Absent for a bundled engine on purpose: its version is this package's
+     * dependency pin, and rewriting a dependency at runtime is an anti-pattern
+     * (`docs/engine-registry.md` §4).
+     */
+    readonly updateArgv?: readonly string[];
+    /** What to tell a user whose engine is installed but not signed in. */
+    readonly loginHint?: string;
+    /**
+     * The engine's account region, when its CLI scopes accounts by region.
+     *
+     * Absent for every engine whose account is region-independent. See
+     * {@link EngineRegion} for what the deployment can do with it.
+     */
+    readonly region?: EngineRegion;
+    /**
+     * Home-relative paths whose existence means "this engine has been signed in
+     * at least once", for the settings page's diagnostic.
+     *
+     * A hint, never a gate: engines own their credentials, and the plugin never
+     * reads, writes or refreshes them. The probe only reports whether the path
+     * exists (`./engine-probe.ts`).
+     */
+    readonly authPaths?: readonly string[];
+    /** The copy key naming this engine in the browser half's dictionary. */
+    readonly localeKey: string;
+    /**
+     * The models this engine offers from its own subscription, when the plugin
+     * knows them.
+     *
+     * An engine that omits this keeps the shared `external` route with its single
+     * `default` entry ("the engine decides") — which is the right answer for an
+     * engine whose catalog this build has no verified list for. An engine that
+     * declares one gets its OWN provider group in the model menu, holding
+     * `default` plus these entries, and selecting one passes its id to the engine.
+     */
+    readonly models?: readonly EngineModel[];
+    /** What the engine can do. */
+    readonly capabilities: EngineCapabilities;
+}
+/**
+ * Every engine this plugin hosts, in selection order.
+ *
+ * The order is the settings dropdown's order and the order the authored presets
+ * are written in. New engines are APPENDED: the ids are persisted in session
+ * logs, sidecar records and preset ids, so an existing id may never be removed
+ * or reordered without a migration (`docs/engine-registry.md` §5).
+ */
+export declare const HOSTED_ENGINE_IDS: readonly ["claude-code", "codex", "pi", "kimi", "agy", "zcode", "qoderclicn", "hermes", "grok", "minimaxcode"];
+/** An engine this plugin hosts itself; `in-process` is the harness's own loop. */
+export type HostedEngineId = (typeof HOSTED_ENGINE_IDS)[number];
+/**
+ * Every selectable engine, the harness's own loop first.
+ *
+ * `in-process` is not a descriptor: it is the harness's loop, not something this
+ * plugin hosts, so it has no binary, no protocol and no capabilities to declare.
+ * Keeping it out of {@link ENGINE_REGISTRY} is what makes the record exhaustive
+ * over {@link HostedEngineId} alone.
+ */
+export declare const LOOP_ENGINE_IDS: readonly ["in-process", "claude-code", "codex", "pi", "kimi", "agy", "zcode", "qoderclicn", "hermes", "grok", "minimaxcode"];
+/** Installed agent loop engine id. */
+export type LoopEngineId = (typeof LOOP_ENGINE_IDS)[number];
+/**
+ * The registry itself: one row per hosted engine.
+ *
+ * `satisfies` rather than a plain annotation, for two reasons at once. The
+ * `Record` half is the exhaustiveness check: TypeScript refuses to build when an
+ * id in {@link HOSTED_ENGINE_IDS} has no row, so "add an engine" cannot
+ * half-land. The `as const` half keeps every field's LITERAL type, which is what
+ * lets the browser half derive its copy keys from this table
+ * (`EngineLocaleKey` in `./client/locales.ts`) instead of restating the roster —
+ * an annotation would widen `localeKey` to `string` and destroy that.
+ */
+export declare const ENGINE_REGISTRY: {
+    readonly 'claude-code': {
+        readonly id: "claude-code";
+        readonly label: "Claude Code";
+        readonly repo: "https://github.com/anthropics/claude-code";
+        readonly bundled: true;
+        readonly binConfigKey: "claudeBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly loginHint: "run `claude` once and sign in, or point `claudeBin` at a signed-in install";
+        readonly authPaths: readonly [".claude/.credentials.json", ".claude.json"];
+        readonly localeKey: "engineClaudeCode";
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "ndjson";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["default", "acceptEdits", "bypassPermissions", "plan"];
+            readonly images: true;
+            readonly reasoningLevels: false;
+        };
+    };
+    readonly codex: {
+        readonly id: "codex";
+        readonly label: "Codex";
+        readonly repo: "https://github.com/openai/codex";
+        readonly bundled: true;
+        readonly binConfigKey: "codexBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly loginHint: "run `codex login`, or set CODEX_API_KEY, or point `codexBin` at a signed-in install";
+        readonly authPaths: readonly [".codex/auth.json"];
+        readonly localeKey: "engineCodex";
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "jsonrpc";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["read-only", "workspace-write", "danger-full-access"];
+            readonly images: true;
+            readonly reasoningLevels: true;
+        };
+    };
+    readonly pi: {
+        readonly id: "pi";
+        readonly label: "Pi";
+        readonly repo: "https://github.com/earendil-works/pi";
+        readonly bundled: true;
+        readonly binConfigKey: "piBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly loginHint: "run `pi` once and sign in, or set the provider API-key variable pi expects";
+        readonly authPaths: readonly [".pi/agent/auth.json"];
+        readonly localeKey: "enginePi";
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "jsonrpc";
+            readonly sessionResume: false;
+            readonly permissionModes: readonly ["read-only", "workspace-write", "danger-full-access"];
+            readonly images: true;
+            readonly reasoningLevels: true;
+        };
+    };
+    readonly kimi: {
+        readonly id: "kimi";
+        readonly label: "Kimi Code";
+        readonly repo: "https://github.com/MoonshotAI/kimi-cli";
+        readonly bundled: false;
+        readonly binConfigKey: "kimiBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly updateArgv: readonly ["update"];
+        readonly loginHint: "run `kimi` once and sign in (or `kimi login`)";
+        readonly authPaths: readonly [".kimi-code/credentials.json", ".kimi-code/auth.json"];
+        readonly localeKey: "engineKimi";
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "acp";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["ask", "allow", "deny"];
+            readonly images: true;
+            readonly reasoningLevels: false;
+        };
+    };
+    readonly agy: {
+        readonly id: "agy";
+        readonly label: "Antigravity";
+        readonly repo: "https://antigravity.google";
+        readonly bundled: false;
+        readonly binConfigKey: "agyBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly updateArgv: readonly ["update"];
+        readonly loginHint: "run `agy` once and complete the Google sign-in it opens";
+        readonly authPaths: readonly [".gemini/oauth_creds.json"];
+        readonly localeKey: "engineAgy";
+        readonly models: readonly [{
+            readonly id: "gemini-3.8-flash-high";
+            readonly label: "Gemini 3.8 Flash (High)";
+        }, {
+            readonly id: "gemini-3.8-flash-medium";
+            readonly label: "Gemini 3.8 Flash (Medium)";
+        }, {
+            readonly id: "gemini-3.8-flash-low";
+            readonly label: "Gemini 3.8 Flash (Low)";
+        }, {
+            readonly id: "claude-sonnet-4-6";
+            readonly label: "Claude Sonnet 4.6 (Thinking)";
+        }, {
+            readonly id: "claude-opus-4-6-thinking";
+            readonly label: "Claude Opus 4.6 (Thinking)";
+        }, {
+            readonly id: "gpt-oss-120b-medium";
+            readonly label: "GPT-OSS 120B (Medium)";
+        }];
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "ndjson";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["accept-edits", "auto", "plan"];
+            readonly images: false;
+            readonly reasoningLevels: true;
+        };
+    };
+    readonly zcode: {
+        readonly id: "zcode";
+        readonly label: "ZCode";
+        readonly repo: "https://z.ai";
+        readonly bundled: false;
+        readonly binConfigKey: "zcodeBin";
+        readonly versionArgv: readonly ["version"];
+        readonly updateArgv: readonly ["plugins", "update"];
+        readonly loginHint: "run `zcode login` to sign in with Z.AI";
+        readonly authPaths: readonly [".zcode/v2", ".zcode/cli"];
+        readonly localeKey: "engineZcode";
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "jsonrpc";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["build", "edit", "plan", "yolo"];
+            readonly images: false;
+            readonly reasoningLevels: false;
+        };
+    };
+    readonly qoderclicn: {
+        readonly id: "qoderclicn";
+        readonly label: "Qoder CN";
+        readonly repo: "https://qoder.com";
+        readonly bundled: false;
+        readonly binConfigKey: "qoderclicnBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly updateArgv: readonly ["update"];
+        readonly loginHint: "run `qoderclicn login` to sign in to Qoder CN";
+        readonly authPaths: readonly [".qoder-cn/.auth/user"];
+        readonly localeKey: "engineQoderclicn";
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "ndjson";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["default", "accept_edits", "bypass_permissions", "dont_ask", "auto"];
+            readonly images: false;
+            readonly reasoningLevels: true;
+        };
+    };
+    readonly hermes: {
+        readonly id: "hermes";
+        readonly label: "Hermes Agent";
+        readonly repo: "https://github.com/NousResearch/hermes";
+        readonly bundled: false;
+        readonly binConfigKey: "hermesBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly updateArgv: readonly ["update"];
+        readonly loginHint: "run `hermes setup` (or `hermes auth`) to sign in to an inference provider";
+        readonly authPaths: readonly ["auth.json"];
+        readonly localeKey: "engineHermes";
+        readonly capabilities: {
+            readonly streaming: false;
+            readonly protocol: "text";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["safe-mode", "yolo"];
+            readonly images: false;
+            readonly reasoningLevels: true;
+        };
+    };
+    readonly grok: {
+        readonly id: "grok";
+        readonly label: "Grok Build";
+        readonly repo: "https://github.com/xai-org/grok-build";
+        readonly bundled: false;
+        readonly binConfigKey: "grokBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly updateArgv: readonly ["update"];
+        readonly loginHint: "run `grok` once and complete the sign-in it opens (or `grok login`), then retry";
+        readonly authPaths: readonly [".grok/auth.json"];
+        readonly localeKey: "engineGrok";
+        readonly models: readonly [{
+            readonly id: "grok-4.7";
+            readonly label: "Grok 4.7";
+        }];
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "acp";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["ask", "always-approve"];
+            readonly images: false;
+            readonly reasoningLevels: true;
+            readonly acpProtocolVersion: 1;
+        };
+    };
+    readonly minimaxcode: {
+        readonly id: "minimaxcode";
+        readonly label: "MiniMax Code";
+        readonly repo: "https://agent.minimax.io/docs/cli/quick-start";
+        readonly bundled: false;
+        readonly binConfigKey: "minimaxcodeBin";
+        readonly versionArgv: readonly ["--version"];
+        readonly updateArgv: readonly ["update"];
+        readonly loginHint: "run `mcode login --region cn|global`, then `mcode provider use token-plan` to spend your M Plan subscription";
+        readonly authPaths: readonly [".minimax/auth/prod"];
+        readonly region: {
+            readonly configKey: "mcodeRegion";
+            readonly envVar: "MAVIS_REGION";
+            readonly default: "cn";
+            readonly values: readonly ["cn", "en"];
+        };
+        readonly localeKey: "engineMinimaxcode";
+        readonly models: readonly [{
+            readonly id: "m:minimax:MiniMax-M3:v:thinking";
+            readonly label: "M3 · thinking";
+        }, {
+            readonly id: "m:minimax:MiniMax-M3:v:";
+            readonly label: "M3";
+        }, {
+            readonly id: "m:minimax:MiniMax-M3.1-Flash-Preview:v:thinking";
+            readonly label: "M3.1-Flash-Preview · thinking";
+        }, {
+            readonly id: "m:minimax:MiniMax-M3.1-Flash-Preview:v:";
+            readonly label: "M3.1-Flash-Preview";
+        }, {
+            readonly id: "m:minimax:MiniMax-M2.7-highspeed:v:thinking";
+            readonly label: "M2.7-highspeed · thinking";
+        }, {
+            readonly id: "m:minimax:MiniMax-M2.7:v:thinking";
+            readonly label: "M2.7 · thinking";
+        }];
+        readonly capabilities: {
+            readonly streaming: true;
+            readonly protocol: "acp";
+            readonly sessionResume: true;
+            readonly permissionModes: readonly ["default", "auto", "bypassPermissions"];
+            readonly images: true;
+            readonly reasoningLevels: true;
+            readonly acpProtocolVersion: 1;
+        };
+    };
+};
+/** Every hosted engine descriptor, in selection order. */
+export declare const ENGINE_DESCRIPTORS: readonly EngineDescriptor[];
+/**
+ * Whether an engine is one this plugin hosts — an external CLI some other
+ * vendor runs, which owns its own model — rather than the harness's own loop.
+ *
+ * The judgement a surface needs to say "the model is the engine's own business"
+ * without hardcoding one engine's name: every hosted engine behaves the same
+ * way here, and naming one of them would make a general fact read as a property
+ * of that engine. An engine nobody has answered for yet is not hosted: a surface
+ * that does not know says nothing rather than claiming the wrong half.
+ * @param engine - an engine id, or undefined while one is still being read.
+ * @returns whether that engine is hosted by this plugin.
+ */
+export declare function isHostedEngine(engine: LoopEngineId | undefined): engine is HostedEngineId;
+/**
+ * Whether an untyped value is one of {@link LOOP_ENGINE_IDS}.
+ *
+ * The boundary test both halves need: a value crossing the wire, the sidecar
+ * file, or a projection read is only an engine when it is one of these.
+ * @param value - the value to classify.
+ * @returns whether `value` is an installed engine id.
+ */
+export declare function isLoopEngineId(value: unknown): value is LoopEngineId;
+/**
+ * The descriptor of one hosted engine.
+ *
+ * Total rather than partial by construction: the parameter is
+ * {@link HostedEngineId}, so there is no unknown-id case to answer for. Callers
+ * holding an untyped id narrow it with {@link isHostedEngine} first.
+ * @param engine - the hosted engine to describe.
+ * @returns that engine's descriptor.
+ */
+export declare function descriptorOf(engine: HostedEngineId): EngineDescriptor;
+/**
+ * The copy key naming one engine in the browser half's dictionary.
+ *
+ * Derived from the table rather than declared, so the union of valid keys grows
+ * with the registry: adding an engine makes its `localeKey` a required entry in
+ * both dictionaries (`./client/locales.ts`), and a typo in a registry row is a
+ * compile error rather than a blank label at runtime.
+ */
+export type EngineLocaleKey = (typeof ENGINE_REGISTRY)[HostedEngineId]['localeKey'];
+/**
+ * The descriptor of one engine, or undefined for `in-process` and for anything
+ * this build does not know.
+ * @param engine - an engine id from any source.
+ * @returns that engine's descriptor, or undefined when it is not hosted.
+ */
+export declare function descriptorOfOptional(engine: LoopEngineId | undefined): EngineDescriptor | undefined;
+/**
+ * The ACP protocol version to announce on behalf of one engine.
+ *
+ * The ONE reader of {@link EngineCapabilities.acpProtocolVersion}: every ACP
+ * driver goes through here, so the fallback to
+ * {@link DEFAULT_ACP_PROTOCOL_VERSION} is applied in one place and an engine that
+ * declares a different version cannot be missed by a driver that forgot to ask.
+ * @param engine - the hosted engine whose version is being announced.
+ * @returns the declared version, or the default when the engine declares none.
+ */
+export declare function acpProtocolVersionOf(engine: HostedEngineId): number;
+/**
+ * The region one engine's child should run under, or undefined when the engine
+ * declares no region.
+ * @param engine - the hosted engine.
+ * @param override - the deployment's own value from the descriptor's `configKey`.
+ * @returns the region to use, the engine's default when the deployment pins none.
+ * @throws when the deployment pins a value the engine's CLI does not accept —
+ *   fail loud at resolve time rather than spelling an invalid region into the
+ *   child's environment, where the CLI would silently fall back to its own.
+ */
+export declare function regionOf(engine: HostedEngineId, override?: string): string | undefined;
+//# sourceMappingURL=engine-registry.d.ts.map