dsh-codebuddy-llm 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "dsh-codebuddy-llm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Delegating CLI LLM adapter for the DeepSeek Harness: answers each model call by running the CodeBuddy CLI child that carries its own sign-in and agent loop, so a deployment runs without an API key",
+  "author": "saisaiwang <287442583@qq.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ws199171/dsh-codebuddy-cli.git"
+  },
+  "homepage": "https://github.com/ws199171/dsh-codebuddy-cli#readme",
+  "bugs": {
+    "url": "https://github.com/ws199171/dsh-codebuddy-cli/issues"
+  },
+  "type": "module",
+  "main": "index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "cordis-plugin",
+    "codebuddy",
+    "llm",
+    "cli",
+    "adapter"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "dsh": "^0.2.1-rc.3",
+    "node": ">=24.9"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.3"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/types/acp.d.ts

@@ -0,0 +1,177 @@
+/**
+ * ACP transport: one long-lived CLI child that carries every delegated run of a
+ * route, driven over the Agent Client Protocol (NDJSON on stdin and stdout).
+ *
+ * The print transport starts a child per model call, so every call pays the
+ * CLI's cold start and the answer can only be read from that one run. This
+ * transport starts the child once, handshakes, and maps each model call to a
+ * `session/prompt` on the session its conversation owns; the answer arrives as
+ * `session/update` notifications, which is also where the CLI's own thinking
+ * becomes visible instead of staying inside the child.
+ *
+ * The child is addressed by JSON-RPC framing: requests carry an id this module
+ * correlates, notifications carry a session id it routes, and a request the CLI
+ * raises for itself — a tool permission — is answered by the configured policy
+ * rather than left hanging, because an unanswered request stalls the turn.
+ *
+ * @module dsh-codebuddy-llm/acp
+ */
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** One incremental piece of a delegated answer. */
+export type AcpTurnEvent = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'thought';
+    text: string;
+};
+/**
+ * How one delegated turn ended, as the CLI itself reported it. A turn the CLI
+ * refused or cancelled still answers `session/prompt`; only this outcome tells
+ * the caller that the empty answer is a failure rather than a short reply.
+ */
+export interface AcpPromptOutcome {
+    /** The ACP stop reason the CLI reported for the turn. */
+    readonly stopReason: string;
+    /** The CLI's own failure detail reported beside the reason, when it gave one. */
+    readonly detail?: string;
+}
+/**
+ * The CLI session one conversation is bound to, and whether this child opened it
+ * fresh. A lease is what tells the caller whether the CLI already holds the
+ * conversation: a fresh session holds none, so the call has to carry the history.
+ */
+export interface AcpSessionLease {
+    /** Session id the CLI itself assigned. */
+    sessionId: string;
+    /** Whether this child created the session (as opposed to adopting an existing one). */
+    created: boolean;
+}
+/** One model the CLI advertises when it opens a session. */
+export interface AcpCatalogModel {
+    /** Model id the CLI accepts for `--model`. */
+    readonly id: string;
+    /** Display name the CLI reports, when it reports one. */
+    readonly name?: string;
+    /** Input capacity the CLI discloses for this id, when it discloses one. */
+    readonly contextWindow?: number;
+}
+/** One permission option the CLI offers for a tool call it wants to run. */
+export interface AcpPermissionOption {
+    /** Identifier the answer selects. */
+    id: string;
+    /** Protocol-level kind, which is what a policy answers in terms of. */
+    kind: string;
+}
+/** What the transport needs to run one route's child. */
+export interface AcpTransportOptions {
+    /** The subprocess seam's spawn operation. */
+    spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
+    /** Executable and ACP arguments; a prompt never rides argv here. */
+    argv: readonly string[];
+    /** Working directory the child itself starts in. */
+    cwd: string;
+    /** Environment entries layered over the seam's base. */
+    env: Record<string, string>;
+    /** Grace in milliseconds for child process-tree termination. */
+    graceMs: number;
+    /**
+     * Answer one permission request: the option id to select, or undefined to
+     * refuse. Absent refuses every request, which is what a deployment that
+     * expects no tool activity wants.
+     */
+    selectPermission?: (options: readonly AcpPermissionOption[]) => string | undefined;
+    /**
+     * Ceiling in milliseconds for one prompted turn, or absent for none. The CLI
+     * runs its whole agent loop inside one prompt, so this is the only bound the
+     * client can put on a run that never converges: on expiry the turn is
+     * cancelled and the caller is told it outlived its deadline.
+     */
+    turnTimeoutMs?: number;
+}
+/** A delegated turn that outlived the connection's deadline. */
+export declare class AcpTurnTimeoutError extends Error {
+    /** @param timeoutMs - the deadline the turn exceeded. */
+    constructor(timeoutMs: number);
+}
+/**
+ * One route's long-lived ACP connection.
+ *
+ * A transport is started lazily on first use and lives until {@link dispose};
+ * sessions are created per harness conversation and reused across its calls,
+ * so a second call to the same conversation pays neither a cold start nor a
+ * handshake.
+ */
+export declare class AcpTransport {
+    private readonly options;
+    private child;
+    private starting;
+    private buffer;
+    private nextId;
+    private disposed;
+    private readonly pending;
+    private readonly turns;
+    private readonly sessions;
+    constructor(options: AcpTransportOptions);
+    /**
+     * The ACP session one conversation is bound to, opened on first use.
+     *
+     * A conversation this child already serves keeps its session. Otherwise the
+     * caller's `adopt` id — the session a previous child created for the same
+     * conversation — is loaded through `session/load`, which is what keeps the
+     * CLI's own history across a restarted harness or a replaced child. A failed
+     * load (the CLI forgot it, or does not support loading) falls back to a fresh
+     * session, and the returned lease says so, which is the caller's signal that
+     * this call must carry the conversation itself.
+     *
+     * @param key - the harness conversation this session belongs to.
+     * @param cwd - workspace the session runs in.
+     * @param adopt - CLI session id a previous child created for this conversation.
+     * @returns the session id and whether this child created it.
+     */
+    openSession(key: string, cwd: string, adopt?: string): Promise<AcpSessionLease>;
+    /**
+     * Read the model catalog this CLI advertises, by opening the session whose
+     * answer carries it. The connection is the caller's to dispose afterwards: a
+     * discovery probe wants the catalog and nothing of the session's history.
+     * @param cwd - workspace the probe session runs in.
+     * @returns one entry per advertised model, with the capacity it discloses.
+     */
+    describeModels(cwd: string): Promise<readonly AcpCatalogModel[]>;
+    /**
+     * Ask the child to resume a session a previous child created.
+     * @param cwd - workspace the session runs in.
+     * @param sessionId - CLI session id to load.
+     * @returns whether the child resumed it; a refusal is not this call's failure.
+     */
+    private loadSession;
+    /**
+     * Run one model call as a prompt on the session that owns the conversation.
+     * @param sessionId - the ACP session from {@link openSession}.
+     * @param text - the prompt text this call carries.
+     * @param signal - caller cancellation, forwarded as `session/cancel`.
+     * @returns the answer's incremental events, and how the CLI ended the turn
+     *   once they are drained — `cancelled` and `refusal` are outcomes, not errors.
+     */
+    prompt(sessionId: string, text: string, signal?: AbortSignal): AsyncGenerator<AcpTurnEvent, AcpPromptOutcome>;
+    /**
+     * End the connection and the child behind it.
+     * @returns once the child's process tree is gone.
+     */
+    dispose(): Promise<void>;
+    /** Start the child and handshake once; a second caller joins the first attempt. */
+    private ensureStarted;
+    private start;
+    /** Route one parsed line: a response, a turn update, or a request to answer. */
+    private handleLine;
+    /** Answer one request the CLI raised, so the turn it belongs to can continue. */
+    private answerRequest;
+    /** Send one request and await its response. */
+    private request;
+    /** Send one notification, which expects no answer. */
+    private notify;
+    private write;
+    /** Fail every waiter: the child is gone, so no request can be answered. */
+    private failAll;
+}
+//# sourceMappingURL=acp.d.ts.map

package/types/adapter.d.ts

@@ -0,0 +1,166 @@
+/**
+ * `CliAdapter`: the delegating LLM adapter that answers one model call by
+ * running one CLI child process and translating its stream-json output into
+ * harness `StreamChunk`s. The configured CLI (CodeBuddy by default) carries its
+ * own authentication and runs its own agentic loop with its own tools, so the
+ * harness forwards conversation text and receives the final answer: no API key,
+ * no harness-side tool loop, and no harness tool vocabulary on the wire.
+ *
+ * The adapter is transport-only. Executable facts arrive through a thunk
+ * resolved once per operation, and the registering plugin owns validation,
+ * defaults, and configuration — so a settings change reaches the next call
+ * without re-registering this route.
+ *
+ * @module dsh-codebuddy-llm/adapter
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** One optional model entry the CLI route advertises. */
+export interface CliCatalogModel {
+    /** Model id accepted by {@link GenerateOptions.model} for this route. */
+    id: string;
+    /** Selector label; defaults to {@link id}. */
+    name?: string;
+    /**
+     * Input capacity this id accepts, when the deployment knows it. Compaction and
+     * switching need it, and a route that owns no endpoint cannot derive it; the
+     * ACP handshake supplies the CLI's own figure where it reports one.
+     */
+    contextWindow?: number;
+}
+/** The CLI permission modes its non-interactive print command accepts. */
+export declare const CODEBUDDY_PERMISSION_MODES: readonly ["acceptEdits", "bypassPermissions", "default", "plan", "dontAsk", "auto"];
+/** The delegated CLI's policy for approving tools inside its own agent loop. */
+export type CodeBuddyPermissionMode = typeof CODEBUDDY_PERMISSION_MODES[number];
+/** The reasoning effort levels the CLI's own flag accepts. */
+export declare const CODEBUDDY_EFFORT_LEVELS: readonly ["minimal", "low", "medium", "high", "xhigh", "max"];
+/** Reasoning effort the delegated CLI forwards to the model. */
+export type CodeBuddyEffort = typeof CODEBUDDY_EFFORT_LEVELS[number];
+/** The ways this route can reach the CLI. */
+export declare const CLI_TRANSPORTS: readonly ["print", "acp"];
+/**
+ * How one call reaches the CLI: `print` starts a child per call and reads its
+ * stream-json, `acp` keeps one child per route and prompts a session on it.
+ * `print` is the default because it needs nothing of the CLI but its own
+ * non-interactive mode.
+ */
+export type CliTransport = typeof CLI_TRANSPORTS[number];
+/** Transport a deployment gets without asking for one. */
+export declare const DEFAULT_TRANSPORT: CliTransport;
+/**
+ * Validated executable facts for one operation. The plugin's resolve step
+ * produces this shape; the adapter trusts it and re-reads it per operation.
+ */
+export interface CliConnectionOptions {
+    /** Executable and base arguments; `argv[0]` is the program. */
+    argv: readonly string[];
+    /** Configured working directory, or the process fallback for the CLI child. */
+    cwd: string;
+    /** Whether a persistent session's own workspace replaces {@link cwd} when one is available. */
+    useSessionCwd: boolean;
+    /** Explicit environment entries layered over the subprocess seam's base. */
+    env: Record<string, string>;
+    /** Argument carrying the persistent session id, or undefined for stateless runs. */
+    sessionIdArg?: string;
+    /** How a call reaches the CLI; see {@link CliTransport}. */
+    transport: CliTransport;
+    /** The CLI's permission policy for tools its own loop executes. */
+    permissionMode: CodeBuddyPermissionMode;
+    /** Tool set the CLI restricts itself to; an empty value disables every built-in tool. Absent leaves its own default. */
+    tools?: string;
+    /** Cap on the CLI's own agentic turns; absent leaves its own default. */
+    maxTurns?: number;
+    /** Reasoning effort the CLI forwards to the model; absent leaves its own default. */
+    effort?: CodeBuddyEffort;
+    /** Grace in milliseconds for child process-tree termination. */
+    disposeGraceMs: number;
+    /**
+     * Ceiling in milliseconds for one delegated `acp` turn, or `0` for none. The
+     * CLI runs a whole agent loop inside one call, so without a ceiling a run that
+     * never converges holds the turn open for as long as the CLI keeps working.
+     */
+    turnTimeoutMs: number;
+    /** Executable and arguments that start the CLI as a long-lived ACP agent. */
+    acpArgv: readonly string[];
+    /** Executable and arguments that print the CLI's supported model ids. */
+    discoveryArgv: readonly string[];
+    /** Hard ceiling in milliseconds for one model-discovery child. */
+    discoveryTimeoutMs: number;
+    /** Advisory models exposed to discovery consumers. */
+    models: readonly CliCatalogModel[];
+}
+/** Constructor options for {@link CliAdapter}. */
+export interface CliAdapterOptions {
+    /** Current validated executable facts; read once per operation. */
+    options: () => CliConnectionOptions;
+    /** The subprocess seam's spawn operation. */
+    spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
+    /** Resolve the workspace selected for a persistent harness session. */
+    resolveSessionCwd?: (sessionId: NonNullable<GenerateOptions['sessionId']>) => string | undefined;
+}
+/**
+ * Delegating CLI adapter: one provider route whose model ids name the CLI's own
+ * model selection. Its default transport spawns a child per call, hands it the
+ * prompt as its final positional argument, and consumes stream-json on stdout;
+ * the ACP transport keeps one child per route and prompts a session on it, so
+ * the CLI's cold start is paid once per route instead of once per call.
+ */
+export declare class CliAdapter extends LlmAdapter {
+    private readonly options;
+    private readonly spawn;
+    private readonly resolveSessionCwd;
+    /**
+     * The long-lived ACP connection of each workspace, replaced when what starts
+     * its child changes. The CLI takes its workspace from the directory the child
+     * starts in rather than from `session/new`, so a workspace needs its own child.
+     */
+    private readonly acp;
+    /**
+     * CLI sessions this route opened, by harness conversation. Held here rather
+     * than in the transport because a replaced child must be able to resume them:
+     * the id names a session in the CLI's own store, not in one child.
+     */
+    private readonly acpSessions;
+    /** Numbers the throwaway sessions a stateless call gets. */
+    private statelessCalls;
+    constructor(options: CliAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Answer one call through the route's long-lived ACP child. The session owns
+     * the conversation, so only this call's text is sent — which is also why the
+     * transport pays the CLI's cold start once per route instead of once per call.
+     * @param facts - resolved executable facts for this operation.
+     * @param options - the model call being answered.
+     * @param prompt - the text this call carries.
+     * @param recap - the conversation before this call's newest human text, sent
+     *   instead of `prompt` when the CLI session is new and holds no history.
+     * @param cwd - workspace the conversation's session runs in.
+     * @param signal - caller cancellation, forwarded as a session cancel.
+     * @returns the call's chunks, ending with its terminal.
+     */
+    private streamAcp;
+    /**
+     * Release the route's long-lived children, if any were ever started. The
+     * plugin calls this from the effect that registered the route, so unloading
+     * the route unloads its children rather than leaving them to outlive the
+     * composition.
+     * @returns once every child's process tree is gone.
+     */
+    dispose(): Promise<void>;
+    /**
+     * The ACP connection one workspace runs on, started on first use and replaced
+     * when the facts that started it change. The model and the workspace ride the
+     * process: the CLI takes both as launch facts, so one child serves one model
+     * in one workspace.
+     * @param facts - resolved executable facts for this operation.
+     * @param model - model id this call selected.
+     * @param cwd - workspace the conversation's session runs in.
+     * @returns the connection to prompt on.
+     */
+    private acpTransport;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/types/config.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Plugin configuration and the one resolve step from raw config to validated
+ * executable facts.
+ *
+ * Every field is `Volatile`, so a Models-page edit reaches the next request
+ * through the loader's volatile update without restarting anything. The resolve
+ * step re-judges every default and bound because programmatic construction and
+ * a settings snapshot both bypass Schemastery normalization.
+ *
+ * @module dsh-codebuddy-llm/config
+ */
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { CliCatalogModel, CliConnectionOptions, CliTransport, CodeBuddyEffort, CodeBuddyPermissionMode } from './adapter.js';
+/** The default CLI executable; a bare name resolves on PATH. */
+export declare const DEFAULT_COMMAND = "codebuddy";
+/**
+ * Base arguments producing stream-json on stdout with a trailing positional
+ * prompt. Partial messages are requested too: without them the CLI reports a
+ * message only once it is complete, so a caller waits out the child's whole
+ * agent loop — tool rounds included — before the first character arrives.
+ */
+export declare const DEFAULT_ARGS: readonly string[];
+/** The argument that carries the persistent session id. */
+export declare const DEFAULT_SESSION_ID_ARG = "--session-id";
+/** Permission mode that makes a delegated, non-interactive CLI run usable by default. */
+export declare const DEFAULT_PERMISSION_MODE: CodeBuddyPermissionMode;
+/** Default graceful-termination window for a CLI child. */
+export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+/** Arguments that start the CLI as a long-lived ACP agent on stdio. */
+export declare const DEFAULT_ACP_ARGS: readonly string[];
+/** Arguments that print the CLI's supported model ids without starting an agent session. */
+export declare const DEFAULT_MODEL_DISCOVERY_ARGS: readonly string[];
+/** Default ceiling for one model-discovery child. */
+export declare const DEFAULT_MODEL_DISCOVERY_TIMEOUT_MS = 15000;
+/**
+ * Default ceiling for one delegated `acp` turn. A turn is the CLI's whole agent
+ * loop, not one model round, so the bound is generous; it exists to end a run
+ * that never converges rather than to pace an ordinary one.
+ */
+export declare const DEFAULT_TURN_TIMEOUT_MS = 600000;
+/**
+ * Plugin config, validated by the same-named schemastery schema and doubling as
+ * the `llm-cli` user-settings section shape. Every field is optional in yml: a
+ * missing command falls back to `codebuddy`, and an empty section still
+ * registers the route with the defaults.
+ */
+export interface Config {
+    /** CLI executable; a bare name resolves on PATH. */
+    command: Volatile<string>;
+    /** Arguments producing stream-json on stdout; the prompt is appended last. */
+    args: Volatile<string[]>;
+    /** Arguments that start the CLI as a long-lived ACP agent; used by the `acp` transport. */
+    acpArgs: Volatile<string[]>;
+    /** Arguments that print the CLI's supported model ids without starting an agent session. */
+    modelDiscoveryArgs: Volatile<string[]>;
+    /** Hard ceiling in milliseconds for one model-discovery child. */
+    modelDiscoveryTimeoutMs: Volatile<number>;
+    /**
+     * Ceiling in milliseconds for one delegated `acp` turn, or `0` for none. The
+     * CLI runs its whole agent loop inside one call, so an unbounded turn is a
+     * run that can hold the conversation open for as long as it keeps working.
+     */
+    turnTimeoutMs: Volatile<number>;
+    /** Advisory model ids offered beside the discovered ones. */
+    models: Volatile<CliCatalogModel[]>;
+    /** Child working directory; when absent, a persistent session's workspace wins. */
+    cwd: Volatile<string | undefined>;
+    /** Explicit environment entries layered over the subprocess seam's base. */
+    env: Volatile<Record<string, string>>;
+    /** Argument carrying the persistent session id; an empty value disables CLI-side sessions. */
+    sessionIdArg: Volatile<string>;
+    /**
+     * How a call reaches the CLI: `print` starts a child per call, `acp` keeps
+     * one child per route and prompts a session on it.
+     */
+    transport: Volatile<CliTransport>;
+    /** The CLI's own tool-approval policy for the delegated run. */
+    permissionMode: Volatile<CodeBuddyPermissionMode>;
+    /**
+     * Tool set the delegated run restricts itself to. An empty value disables
+     * every built-in tool, which reduces the CLI to a model call; absent leaves
+     * the CLI's own default set.
+     */
+    tools: Volatile<string | undefined>;
+    /**
+     * Cap on the CLI's own agentic turns. Absent leaves the CLI's own default,
+     * which is what lets it run a whole tool loop inside one call.
+     */
+    maxTurns: Volatile<number | undefined>;
+    /** Reasoning effort the CLI forwards to the model; absent leaves its own default. */
+    effort: Volatile<CodeBuddyEffort | undefined>;
+    /** Grace in milliseconds for child process-tree termination. */
+    disposeGraceMs: Volatile<number>;
+}
+/**
+ * Plain config accepted by the resolver: one detached value per option. Derived
+ * from {@link Config} so the two cannot drift; each value is a frozen snapshot
+ * of a volatile reference, read-only in practice.
+ */
+export type Options = {
+    [K in keyof Config]?: Config[K] extends Volatile<infer T> ? Exclude<T, undefined> : never;
+};
+/**
+ * Read the current value behind every reference of a parsed {@link Config}.
+ * Every schema field is volatile, so each entry is a reference by construction.
+ * @param config - parsed plugin config.
+ * @returns one detached value per option.
+ */
+export declare function plainOptions(config: Config): Options;
+/** Fields shared by the plugin entry config and the `llm-cli` settings section. */
+export declare const cliConfigFields: {
+    command: z<string, string, "volatile-defined">;
+    args: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    acpArgs: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    modelDiscoveryArgs: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    modelDiscoveryTimeoutMs: z<number, number, "volatile-defined">;
+    turnTimeoutMs: z<number, number, "volatile-defined">;
+    models: z<NoInfer<CliCatalogModel[]>, NoInfer<CliCatalogModel[]>, "volatile-defined">;
+    cwd: z<string, string, "volatile">;
+    env: z<NoInfer<import("@deepseek-ai/cosmokit").Dict<string, string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<string, string>>, "volatile-defined">;
+    sessionIdArg: z<string, string, "volatile-defined">;
+    transport: z<"print" | "acp", "print" | "acp", "volatile-defined">;
+    permissionMode: z<"acceptEdits" | "bypassPermissions" | "default" | "plan" | "dontAsk" | "auto", "acceptEdits" | "bypassPermissions" | "default" | "plan" | "dontAsk" | "auto", "volatile-defined">;
+    tools: z<string, string, "volatile">;
+    maxTurns: z<number, number, "volatile">;
+    effort: z<"minimal" | "low" | "medium" | "high" | "xhigh" | "max", "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "volatile">;
+    disposeGraceMs: z<number, number, "volatile-defined">;
+};
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    command: z<string, string, "volatile-defined">;
+    args: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    acpArgs: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    modelDiscoveryArgs: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    modelDiscoveryTimeoutMs: z<number, number, "volatile-defined">;
+    turnTimeoutMs: z<number, number, "volatile-defined">;
+    models: z<NoInfer<CliCatalogModel[]>, NoInfer<CliCatalogModel[]>, "volatile-defined">;
+    cwd: z<string, string, "volatile">;
+    env: z<NoInfer<import("@deepseek-ai/cosmokit").Dict<string, string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<string, string>>, "volatile-defined">;
+    sessionIdArg: z<string, string, "volatile-defined">;
+    transport: z<"print" | "acp", "print" | "acp", "volatile-defined">;
+    permissionMode: z<"acceptEdits" | "bypassPermissions" | "default" | "plan" | "dontAsk" | "auto", "acceptEdits" | "bypassPermissions" | "default" | "plan" | "dontAsk" | "auto", "volatile-defined">;
+    tools: z<string, string, "volatile">;
+    maxTurns: z<number, number, "volatile">;
+    effort: z<"minimal" | "low" | "medium" | "high" | "xhigh" | "max", "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "volatile">;
+    disposeGraceMs: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    command: z<string, string, "volatile-defined">;
+    args: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    acpArgs: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    modelDiscoveryArgs: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    modelDiscoveryTimeoutMs: z<number, number, "volatile-defined">;
+    turnTimeoutMs: z<number, number, "volatile-defined">;
+    models: z<NoInfer<CliCatalogModel[]>, NoInfer<CliCatalogModel[]>, "volatile-defined">;
+    cwd: z<string, string, "volatile">;
+    env: z<NoInfer<import("@deepseek-ai/cosmokit").Dict<string, string>>, NoInfer<import("@deepseek-ai/cosmokit").Dict<string, string>>, "volatile-defined">;
+    sessionIdArg: z<string, string, "volatile-defined">;
+    transport: z<"print" | "acp", "print" | "acp", "volatile-defined">;
+    permissionMode: z<"acceptEdits" | "bypassPermissions" | "default" | "plan" | "dontAsk" | "auto", "acceptEdits" | "bypassPermissions" | "default" | "plan" | "dontAsk" | "auto", "volatile-defined">;
+    tools: z<string, string, "volatile">;
+    maxTurns: z<number, number, "volatile">;
+    effort: z<"minimal" | "low" | "medium" | "high" | "xhigh" | "max", "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "volatile">;
+    disposeGraceMs: z<number, number, "volatile-defined">;
+}>>, "plain">;
+/** Validated executable facts for one operation, as the adapter reads them. */
+export type ResolvedCliOptions = CliConnectionOptions;
+/**
+ * Merge what the CLI last advertised with the ids the deployment declared. The
+ * advertised order leads — it is the CLI's own listing, which is what a picker
+ * should show — and a declared entry keeps the fields it declares there, so a
+ * curated label is not replaced by the bare id, while everything it leaves out
+ * still comes from the CLI. Declared ids the CLI did not report follow, so an
+ * advisory id stays selectable.
+ * @param configured - catalog entries the deployment declared.
+ * @param discovered - entries the last probe of the CLI reported.
+ * @returns one entry per id, advertised order first.
+ */
+export declare function mergeCatalog(configured: readonly CliCatalogModel[], discovered: readonly CliCatalogModel[]): CliCatalogModel[];
+/**
+ * The one explicit resolve step from raw config to validated executable facts.
+ * @param config - raw plugin config or a resolved settings snapshot.
+ * @param defaultCwd - fallback working directory for the CLI child.
+ * @returns validated executable facts for the adapter.
+ */
+export declare function resolveAdapterOptions(config: Options, defaultCwd: string): ResolvedCliOptions;
+//# sourceMappingURL=config.d.ts.map

package/types/discovery.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Host-side CLI model discovery. It runs the configured CLI's own listing
+ * command (default `--help`) through the shared subprocess seam and parses the
+ * model ids the CLI reports, so the standard Models page can offer the CLI's
+ * real catalog without this package owning a remote surface of its own.
+ *
+ * Every child here goes through the seam, so discovery inherits process-tree
+ * termination and environment scrubbing instead of managing a child itself.
+ *
+ * @module dsh-codebuddy-llm/discovery
+ */
+import type { LlmDiscoveredModel } from '@deepseek-ai/dsh-llm';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { CliCatalogModel } from './adapter.js';
+/** The ACP connection a route that speaks ACP can be interrogated over. */
+export interface CliAcpDiscovery {
+    /** Executable and arguments that start the CLI as a long-lived ACP agent. */
+    argv: readonly string[];
+    /** Environment entries layered over the seam's base. */
+    env: Record<string, string>;
+    /** Grace in milliseconds for terminating the probe's process tree. */
+    graceMs: number;
+}
+/** One discovery run's inputs, already validated by the resolver. */
+export interface CliDiscoveryRequest {
+    /** Executable and arguments producing the model listing on stdout. */
+    argv: readonly string[];
+    /** Working directory for the discovery child. */
+    cwd: string;
+    /** Hard ceiling in milliseconds for the listing child. */
+    timeoutMs: number;
+    /** The route's advisory catalog, offered after the discovered ids. */
+    configured: readonly CliCatalogModel[];
+    /** The subprocess seam's spawn operation. */
+    spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
+    /**
+     * The ACP connection to interrogate instead of the listing command, when the
+     * route reaches the CLI over ACP: that handshake carries the capacity of each
+     * advertised model, which a listing of ids cannot.
+     */
+    acp?: CliAcpDiscovery | undefined;
+    /** Caller cancellation, honored beside the timeout. */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Parse the model ids a CodeBuddy-style CLI lists for its `--model` option.
+ * @param help - the CLI's own help output.
+ * @returns the unique ids in the CLI's reported order, without display names.
+ */
+export declare function parseCodeBuddyModels(help: string): LlmDiscoveredModel[];
+/**
+ * Discover the models the configured CLI advertises.
+ * @param request - the listing invocation, its bounds, and the route's own catalog.
+ * @returns the discovered models first, then configured ids the CLI did not report.
+ */
+export declare function discoverCliModels(request: CliDiscoveryRequest): Promise<readonly LlmDiscoveredModel[]>;
+//# sourceMappingURL=discovery.d.ts.map