deepseek-harness/packages/ui/stdio-agent/src/index.ts

/**
 * The stdio chat app: the providerless agent spine ({@link
 * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster a terminal
 * chat needs — a console logger, the readline UI (the in-package `stdio-chat`
 * module), JSONL session
 * persistence, and a pre-created `main` agent the UI drives.
 *
 * The cluster is BAKED IN, not left to the leaf: a stdio app always logs to the
 * console (stdout is just the terminal) and always pre-creates the `main` agent
 * the readline UI sends to. The leaf supplies the swappable backends (the LLM
 * adapter, the bash executor), optional product tools, the optional `hmr`
 * dev-reload plugin, and this app's {@link Config} (model, prompt, persistence
 * root, welcome banner).
 *
 * `hmr` is deliberately a LEAF entry, not baked in here: it is a Loader-only,
 * subprocess-only dev plugin (its constructor throws without `--expose-internals`
 * + a live `loader`, and the in-process test tier cannot even import it), so a
 * package whose `apply` statically pulled it in could never be unit-tested or
 * carry the per-file coverage gate. Unlike the console logger, a stray `hmr` is
 * not a stdout-purity footgun — so leaving it at the leaf costs no safety, while
 * baking the LOGGER in (the real coupling) keeps stdout-vs-no-stdout a property
 * of the artifact.
 *
 * Counterpart to {@link @deepseek-ai/dsh-acp-agent}, which bakes in the OPPOSITE
 * cluster (no stdout logger, no pre-created agents — the ACP bridge reserves
 * stdout for JSON-RPC and creates agents on demand). Splitting the two front
 * doors into two packages makes each cluster a property of the artifact: there
 * is no logger entry in the ACP leaf to get wrong.
 *
 * Plugin export shape: named `name`/`Config`/`apply`, NO default export — the
 * cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray
 * default would collapse the module to the bare `apply` and drop the `Config`
 * namespace (see docs/postmortem/0001). This app carries no `inject`, so a
 * collapsed shape would BOOT rather than crash a smoke — the shape is pinned by
 * the explicit `unwrapExports` assertion in this package's unit suite, and the
 * keyless echo smoke proves the composed tree runs through the real Loader.
 *
 * @module @deepseek-ai/dsh-stdio-agent
 */

import type { Context } from 'cordis'
import ConsoleExporter from '@cordisjs/plugin-logger-console'
import z from 'schemastery'
import { AgentId } from '@deepseek-ai/dsh-agent'
import { SessionId } from '@deepseek-ai/dsh-session'
import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
import * as agentCore from '@deepseek-ai/dsh-agent-core'
import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
import * as uiStdio from './stdio-chat.ts'

export const name = 'stdio-agent'

/**
 * App config: the swappable per-demo values, each routed to where the app wires
 * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
 * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
 * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
 * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner.
 */
export interface Config {
  /** Model name for the `main` agent (must have a registered adapter). */
  model: string
  /** Deployment persona (the system-prompt plugin's `persona` config). */
  persona?: string
  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
  toolOrder?: string[]
  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
  tools?: ToolsConfig
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
  welcome?: string
  /**
   * If set, the `main` agent RESUMES this persisted session id instead of
   * starting fresh. Sourced from an env var in the leaf `cordis.yml`
   * (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`).
   */
  resumeSessionId?: string
}

export const Config: z<Config> = z.object({
  model: z.string().required(),
  persona: z.string(),
  // The array default is forced to undefined: ABSENT means "lexicographic
  // order" (the owning dsh-system-prompt schema does the same), while
  // schemastery's native [] default would read as an invalid configured list.
  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
  tools: ToolRegistry.Config,
  persistenceRoot: z.string().default('./.sessions'),
  welcome: z.string().default('ready.'),
  resumeSessionId: z.string(),
})

/**
 * Compose the spine with the stdio front door. The console logger comes first
 * (infra), then the agent-core bundle pre-creating the `main` agent from this
 * app's `model`/`resumeSessionId` with the deployment `persona`, then the JSONL
 * backend, then the readline UI bound to `main`. The `hmr` dev-reload plugin is
 * a leaf concern (see the module doc), so it is not mounted here.
 */
export function apply(ctx: Context, config: Config): void {
  ctx.plugin(ConsoleExporter)
  ctx.plugin(agentCore, {
    ...config.persona !== undefined ? { persona: config.persona } : {},
    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
    ...config.tools !== undefined ? { tools: config.tools } : {},
    agents: [{
      id: AgentId('main'),
      model: config.model,
      ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
    }],
  })
  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
  ctx.plugin(uiStdio, { welcome: config.welcome ?? 'ready.', agent: 'main' })
}