dsh-codebuddy-llm 0.0.0-stage → 0.1.0

package/types/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `llm-cli`: a provider route answered by a CLI child instead of a provider HTTP
+ * endpoint.
+ *
+ * The route exists so a deployment can run the harness with no API key at all:
+ * the configured CLI (CodeBuddy by default) carries its own authentication and
+ * runs its own agentic loop with its own tools. The harness forwards
+ * conversation text and receives the final answer, so a model swap is a
+ * configuration change rather than a harness change.
+ *
+ * The plugin depends on exactly two seams — `llm` (the adapter registry) and
+ * `subprocess` (child lifecycle) — and reaches the session store, when a
+ * deployment has one, through an untyped service lookup. Nothing here requires
+ * `dsh-session`, a remote surface, or a client package, so mounting it changes
+ * no shared package.
+ *
+ * ```yaml
+ * - id: llm-cli
+ *   name: 'dsh-codebuddy-llm'
+ *   config:
+ *     command: codebuddy
+ *     args: ['--print', '--output-format', 'stream-json', '--include-partial-messages']
+ *     permissionMode: bypassPermissions
+ * ```
+ *
+ * @module dsh-codebuddy-llm
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.js';
+export { CliAdapter, CLI_TRANSPORTS, CODEBUDDY_EFFORT_LEVELS, CODEBUDDY_PERMISSION_MODES, DEFAULT_TRANSPORT, } from './adapter.js';
+export type { CliAdapterOptions, CliCatalogModel, CliConnectionOptions, CliTransport, CodeBuddyEffort, CodeBuddyPermissionMode, } from './adapter.js';
+export { AcpTransport } from './acp.js';
+export type { AcpCatalogModel, AcpPermissionOption, AcpPromptOutcome, AcpTransportOptions, AcpTurnEvent } from './acp.js';
+export { Config, DEFAULT_ARGS, DEFAULT_COMMAND, DEFAULT_DISPOSE_GRACE_MS, DEFAULT_MODEL_DISCOVERY_ARGS, DEFAULT_MODEL_DISCOVERY_TIMEOUT_MS, DEFAULT_PERMISSION_MODE, DEFAULT_SESSION_ID_ARG, plainOptions, resolveAdapterOptions, } from './config.js';
+export type { Options, ResolvedCliOptions } from './config.js';
+export { discoverCliModels, parseCodeBuddyModels } from './discovery.js';
+export * from './translate.js';
+export * from './wire.js';
+export declare const name = "llm-cli";
+export declare const inject: string[];
+/** Register the CLI route, its settings section, and its model discovery. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/types/translate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Message translation for the CLI adapter: turns harness conversation content
+ * into the prompt text one CLI child run consumes, and lifts the system prompt
+ * out of the history into the CLI's own system-prompt slot.
+ *
+ * The delegated CLI runs its own agentic loop with its own tools, so no harness
+ * tool vocabulary crosses the boundary; only human-authored user text and prior
+ * assistant answers do, and the CLI's own session (keyed by the harness session
+ * id) owns its tool history.
+ *
+ * @module dsh-codebuddy-llm/translate
+ */
+import type { RequestMessage } from '@deepseek-ai/dsh-llm';
+/**
+ * Flatten one message's text content into consecutive lines.
+ * @param message - the harness message to flatten.
+ * @returns its text blocks, in order.
+ */
+export declare function textBlocksOf(message: RequestMessage): string[];
+/**
+ * The rendered system prompt a request carries.
+ *
+ * Two request shapes reach an adapter, and they carry the prompt differently: a
+ * loop-built request passes its derived history, whose leading system-role
+ * message is the prompt, and leaves `GenerateOptions.system` undefined; a
+ * hand-built one-shot may fill that field instead. Reading both — preferring
+ * the explicit field — is what keeps the prompt from being silently dropped on
+ * either path. System blocks are concatenated without a separator, matching the
+ * projection `dsh-llm-deepseek` applies to the same history so both routes read
+ * one session alike.
+ * @param messages - ordered conversation messages.
+ * @param system - the request's explicit system slot, when it has one.
+ * @returns the system prompt text, or undefined when the request carries none.
+ */
+export declare function systemTextOf(messages: readonly RequestMessage[], system?: string): string | undefined;
+/**
+ * Flatten the harness conversation into one prompt text for a stateless call.
+ *
+ * Plugin-injected user-role context is user-role conversation and therefore
+ * *is* forwarded here: a stateless call has no CLI-side history, so dropping it
+ * would hand the CLI a different conversation than the harness model would have
+ * seen. That is the opposite of {@link trailingUserText}, where the same
+ * injected text must not displace the human's newest input.
+ *
+ * @param messages - ordered conversation messages.
+ * @returns the complete prompt, or `undefined` when nothing text-worthy exists.
+ */
+export declare function flattenConversation(messages: readonly RequestMessage[]): string | undefined;
+/**
+ * The conversation as it stood before the newest human input, for a delegated
+ * CLI that owns no history of it.
+ *
+ * The ACP transport keeps the CLI's own session alive, so an ongoing
+ * conversation normally never needs this. It is the fallback for the cases
+ * where that session is gone — a restarted harness, a replaced child, or a CLI
+ * that refused to resume one — and the CLI would otherwise answer the newest
+ * message knowing nothing that came before it.
+ *
+ * @param messages - ordered conversation messages.
+ * @returns the prior turns, or `undefined` when only the newest input exists.
+ */
+export declare function conversationRecap(messages: readonly RequestMessage[]): string | undefined;
+/**
+ * Extract the trailing human-authored user text of a conversation. A
+ * persistent session forwards only the newest human input, because the CLI
+ * already knows the history under the session id. Plugin context also uses the
+ * user role, so the message source — not the role alone — is what distinguishes
+ * the human's words from an injected context message that must not replace them.
+ * @param messages - ordered conversation messages.
+ * @returns the last human-authored user text, or `undefined` when none exists.
+ */
+export declare function trailingUserText(messages: readonly RequestMessage[]): string | undefined;
+//# sourceMappingURL=translate.d.ts.map

package/types/wire.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Line-protocol parsing for a CLI child's stream-json output. CodeBuddy-style
+ * CLIs emit one JSON object per line; this parser owns line framing, the event
+ * vocabulary it understands, and the text-delta computation.
+ *
+ * Two line families carry answer text, and a run may produce either or both:
+ * `stream_event` frames wrap the model request's own SSE events when the child
+ * is asked for partial messages, so text arrives while it is still being
+ * generated; and the completed `assistant` frame repeats the whole message once
+ * the message ends. Both are measured against the text already observed *for
+ * the message in progress*, which is why `message_start` is reported rather
+ * than ignored — it is the only boundary a caller has for resetting that
+ * measurement. A frame adding nothing beyond the text already seen is ignored,
+ * so a run reading both families emits each character once.
+ *
+ * Unknown events are ignored: the event vocabulary is merge-extensible and this
+ * adapter only consumes what it maps.
+ *
+ * @module dsh-codebuddy-llm/wire
+ */
+import type { LlmFailure, TokenUsage } from '@deepseek-ai/dsh-llm';
+/** One emitted text delta, from a partial message or from a completed one. */
+export interface CliTextDelta {
+    /** Newly observed text since the previous frame of the message in progress. */
+    text: string;
+}
+/** Terminal outcome of one CLI run, as reported by its result event. */
+export type CliTerminal = {
+    kind: 'stop';
+    sessionId?: string;
+    usage?: TokenUsage;
+} | {
+    kind: 'max-turns';
+} | {
+    kind: 'error';
+    failure: LlmFailure;
+};
+/** What one parsed line contributes to the adapter. */
+export type CliLineEvent = {
+    kind: 'message-start';
+} | {
+    kind: 'text';
+    delta: CliTextDelta;
+} | {
+    kind: 'terminal';
+    terminal: CliTerminal;
+} | {
+    kind: 'ignored';
+};
+/**
+ * Parse one line of CLI stream-json output.
+ * @param line - one raw stdout line (already stripped of its newline).
+ * @param lastText - the text observed so far for the message in progress; a delta is measured against it.
+ * @returns the event this line contributes, or undefined when the line is blank.
+ */
+export declare function parseCliLine(line: string, lastText: string): CliLineEvent | undefined;
+//# sourceMappingURL=wire.d.ts.map