@alwith-ai/dsh-agent 0.2.0

package/src/codec.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure translation between the ACP wire format and the harness lifecycle.
+ * Adapted from @deepseek-ai/dsh-acp's codec (MIT); upstream deliberately
+ * removed its interactive ACP surface (automation-only, design note
+ * 2026-07-23), so this layer is self-contained rather than importing the
+ * upstream package.
+ */
+
+import type { ContentBlock as AcpContentBlock, StopReason } from "@agentclientprotocol/sdk/experimental/v2"
+import type { TurnEndReason } from "@deepseek-ai/dsh-session"
+
+/** Map a harness turn ending to ACP's terminal reason vocabulary. */
+export function turnEndToStopReason(reason: TurnEndReason): StopReason {
+  switch (reason.kind) {
+    case "completed":
+      return "end_turn"
+    case "max-tokens":
+      return "max_tokens"
+    // `cancelled` is reserved for explicit session/cancel and disposal, both
+    // settled out of band; a turn aborted by a hook or another owner is
+    // ordinary quiescence and reports end_turn.
+    case "aborted":
+      return "end_turn"
+    case "interrupted":
+      return "cancelled"
+    case "blocked":
+    case "error":
+      return "end_turn"
+    default:
+      return "end_turn"
+  }
+}
+
+// The v2 unions carry an open fallback variant ({ type: string; [key: string]: unknown }),
+// so a `case` switch cannot narrow them — take variants with Extract instead.
+type BlockVariant<K extends string> = Extract<AcpContentBlock, { type: K }>
+
+/** Flatten baseline ACP prompt blocks to text; resource links become explicit textual references. */
+export function acpPromptToText(prompt: readonly AcpContentBlock[]): string {
+  return prompt
+    .flatMap((block): string[] => {
+      if (block.type === "text") return [(block as BlockVariant<"text">).text]
+      if (block.type === "resource_link") {
+        const link = block as BlockVariant<"resource_link">
+        return [`\n[resource_link name=${JSON.stringify(link.name)} uri=${JSON.stringify(link.uri)}]\n`]
+      }
+      return []
+    })
+    .join("")
+}
+
+/** Whether the prompt carries content beyond the baseline (text / resource_link). */
+export function promptHasUnsupportedContent(prompt: readonly AcpContentBlock[]): boolean {
+  return prompt.some(block => block.type !== "text" && block.type !== "resource_link")
+}

package/src/compose.ts

@@ -0,0 +1,60 @@
+/**
+ * Composes the dsh runtime from the plugin manifest (src/plugins.ts).
+ *
+ * The roster per preset is fixed in code — a platform decision, not a
+ * user-patchable tree — but users keep dsh's two degrees of freedom through
+ * the overrides file: per-plugin enable/disable and per-plugin config.
+ * Composition stays deterministic: same preset + same overrides ⟹ same tree.
+ *
+ * Why not dsh's loader: the sidecar spawns one process per session, so
+ * overrides naturally take effect on the next session — no HMR needed — and
+ * dsh's HMR machinery requires Node loader internals Bun does not provide.
+ */
+
+import { Context } from "@deepseek-ai/cordis"
+import {
+  type HarnessPreset,
+  type PermissionMode,
+  type PluginOverrides,
+  pluginRows,
+  resolvePlugins,
+} from "./plugins.ts"
+
+export type { HarnessPreset, PermissionMode }
+
+export interface ComposeOptions {
+  /**
+   * Root directory for JSONL session logs. Absent means no persistence —
+   * session/resume then fails loud (`session persistence is not configured`).
+   */
+  sessionsRoot?: string
+  /** Sandbox workspace root (writes allowed under it in workspace-write mode). */
+  workspaceRoot?: string
+  /** Deployment permission mode; mirrors dsh's DSH_PERMISSION_MODE. */
+  permissionMode?: PermissionMode
+  /** Tool-surface preset; defaults to the standard coding agent. */
+  preset?: HarnessPreset
+  /** Per-plugin enable/disable + config, from the plugins.json overrides file. */
+  overrides?: PluginOverrides
+  /** Extra pi-ai provider routes (see ResolvedComposeOptions.piProviders). */
+  piProviders?: Record<string, unknown>
+  /** The harness credential file (see ResolvedComposeOptions.credentialsFile). */
+  credentialsFile?: string
+}
+
+export async function composeRuntime(options: ComposeOptions = {}): Promise<Context> {
+  const rows = pluginRows({
+    sessionsRoot: options.sessionsRoot,
+    workspaceRoot: options.workspaceRoot ?? process.cwd(),
+    permissionMode: options.permissionMode ?? "workspace-write",
+    preset: options.preset ?? "standard",
+    piProviders: options.piProviders,
+    credentialsFile: options.credentialsFile,
+  })
+  const { mounted } = resolvePlugins(rows, options.overrides ?? {})
+  const ctx = new Context()
+  for (const entry of mounted) {
+    await entry.row.mount(ctx, entry.config)
+  }
+  return ctx
+}

package/src/main.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env bun
+/**
+ * stdio entry: `bun src/main.ts` starts an ACP v2 server for a host to spawn.
+ * The DeepSeek key resolves through llm-deepseek's default credential lookup
+ * ($DEEPSEEK_API_KEY).
+ */
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { credentialKey } from "@deepseek-ai/dsh-credentials"
+import { composeRuntime } from "./compose.ts"
+import { defaultCredentialsFile } from "./oauth.ts"
+import { loadPluginOverrides } from "./plugins.ts"
+import { defaultPluginsFile, runPluginsCli } from "./plugins-cli.ts"
+import * as Bridge from "./bridge.ts"
+
+// `plugins` / `sessions` subcommands: host-facing management without an ACP
+// server. Failures exit 1 with the reason as a single stderr line — the host
+// surfaces stderr verbatim, so no runtime stack noise here. No process.exit()
+// on the success path: Bun's exit does not flush pipes and a session dump
+// exceeds the 64KB pipe buffer — the drained event loop ends the process.
+const subcommand = process.argv[2]
+if (subcommand === "plugins" || subcommand === "sessions" || subcommand === "oauth") {
+  try {
+    if (subcommand === "plugins") await runPluginsCli(process.argv.slice(3))
+    else if (subcommand === "oauth") await (await import("./oauth.ts")).runOauthCli(process.argv.slice(3))
+    else await (await import("./sessions-cli.ts")).runSessionsCli(process.argv.slice(3))
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    process.exitCode = 1
+  }
+} else {
+  await startServer()
+}
+
+async function startServer(): Promise<void> {
+  const provider = process.env.ALWITH_DSH_PROVIDER ?? "deepseek-official"
+  const model = process.env.ALWITH_DSH_MODEL ?? "deepseek-v4-flash"
+  // Host-facing provider identity for _meta.alwith turn metadata (the ALwith
+  // Desktop provider vocabulary, not the dsh adapter route).
+  const providerId = process.env.ALWITH_DSH_PROVIDER_ID ?? "deepseek"
+  // Background LLM session titles ride the session's model unless overridden.
+  const titleModel = process.env.ALWITH_DSH_TITLE_MODEL ?? model
+  // Session logs live under the sidecar's own home by default; the host
+  // (ALwith Desktop) overrides this to its managed location.
+  const sessionsRoot = process.env.ALWITH_DSH_SESSIONS_ROOT ?? join(homedir(), ".dsh-agent", "sessions")
+  // The host spawns one sidecar per session and pins the sandbox workspace to
+  // that session's cwd; standalone runs default to the process cwd.
+  const workspaceRoot = process.env.ALWITH_DSH_WORKSPACE_ROOT ?? process.cwd()
+  const permissionMode = (process.env.ALWITH_DSH_PERMISSION_MODE ?? "workspace-write") as
+    | "read-only"
+    | "workspace-write"
+    | "danger-full-access"
+  // Preset gate fails loud on the modes this sidecar does not compose yet —
+  // the host UI disables them, and a misrouted value must not silently degrade.
+  const rawPreset = process.env.ALWITH_DSH_PRESET ?? "standard"
+  const PRESETS = ["standard", "minimal", "anchored", "code", "cordis"] as const
+  if (!(PRESETS as readonly string[]).includes(rawPreset)) {
+    throw new Error(`unsupported harness preset "${rawPreset}": this sidecar composes ${PRESETS.join(", ")}`)
+  }
+
+  // Per-plugin enable/disable + config; invalid content fails the spawn loud.
+  const overrides = loadPluginOverrides(defaultPluginsFile())
+
+  // Extra pi-ai provider routes (JSON dict, full upstream config shape:
+  // apiKeyEnv / baseURL / api / models / compat / …). Absent = DeepSeek-only.
+  let piProviders: Record<string, unknown> | undefined
+  const rawPiProviders = process.env.ALWITH_DSH_PI_PROVIDERS
+  if (rawPiProviders !== undefined) {
+    const parsed: unknown = JSON.parse(rawPiProviders)
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("ALWITH_DSH_PI_PROVIDERS must be a JSON object keyed by provider route")
+    }
+    piProviders = parsed as Record<string, unknown>
+  }
+
+  const ctx = await composeRuntime({
+    sessionsRoot,
+    workspaceRoot,
+    permissionMode,
+    preset: rawPreset as (typeof PRESETS)[number],
+    overrides,
+    piProviders,
+    // The credential plane rides with the pi-ai seat: subscription grants and
+    // their refreshes live in the harness credential file, not in this process.
+    credentialsFile: piProviders === undefined ? undefined : defaultCredentialsFile(),
+  })
+  // A route with no apiKeyEnv authenticates through a stored subscription
+  // grant. Check it here, where the credential plane is the single source of
+  // truth, so a session never boots into a first request that must fail —
+  // the host cannot read the harness credential file and should not try.
+  for (const [route, config] of Object.entries(piProviders ?? {})) {
+    const declared = config as { apiKeyEnv?: unknown }
+    if (declared.apiKeyEnv !== undefined) continue
+    const record = await ctx.credentials.describeRecord(credentialKey("llm-pi-ai", route))
+    if (!record.configured) {
+      throw new Error(
+        `provider route "${route}" declares no API key and has no stored subscription credential: `
+        + "add an API key (Settings → Model providers) or sign in with a subscription (Settings → Harness)",
+      )
+    }
+  }
+  await ctx.plugin(
+    { name: Bridge.name, inject: [...Bridge.inject], apply: (inner: typeof ctx) => Bridge.apply(inner, { provider, model, providerId, titleModel }) },
+  )
+  // stdin keeps the process alive; the bridge's quiesce handles connection close.
+}

package/src/oauth.ts

@@ -0,0 +1,138 @@
+/**
+ * Subscription OAuth for the pi-ai seat, on the harness's own credential plane.
+ *
+ * Since dsh 0.1.2 the pi-ai adapter ships the whole sign-in translation:
+ * `dsh-llm-pi-ai` registers one `ctx.authorization` flow per catalog provider
+ * that offers a login, and persists what pi-ai's `Models.login()` produces
+ * (and later refreshes under its own lock) as `llm-pi-ai/<provider>` records in
+ * `ctx.credentials`. This module only composes that plane and drives it:
+ *
+ * - `dsh-credentials-local` at `ALWITH_DSH_OAUTH_CREDENTIALS` (default
+ *   `~/.dsh-agent/.credentials.yaml`; the file is private to the OS user),
+ * - `dsh-authorization` — the flow registry the adapter registers into,
+ * - the `oauth login/status/logout` CLI. `login` emits the flow's notices as
+ *   JSON lines on stdout (`{"type":"auth_url",…}` → the host opens the
+ *   browser); the provider's local callback server completes the exchange.
+ */
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { Context } from "@deepseek-ai/cordis"
+import AuthorizationService, {
+  type AuthorizationInteraction,
+  type AuthorizationNotice,
+  type AuthorizationPrompt,
+} from "@deepseek-ai/dsh-authorization"
+import { credentialKey, credentialKeyId, credentialKeyScope } from "@deepseek-ai/dsh-credentials"
+import LocalCredentialProvider from "@deepseek-ai/dsh-credentials-local"
+import LlmRuntime from "@deepseek-ai/dsh-llm"
+// Namespace import: a module-plugin default export drops `inject` (dsh postmortem 0001).
+import * as LlmPiAi from "@deepseek-ai/dsh-llm-pi-ai"
+
+/** The record scope the pi-ai adapter writes under (its registered plugin name). */
+const PI_AI_RECORD_SCOPE = "llm-pi-ai"
+
+export function defaultCredentialsFile(): string {
+  return process.env.ALWITH_DSH_OAUTH_CREDENTIALS ?? join(homedir(), ".dsh-agent", ".credentials.yaml")
+}
+
+function emit(event: Record<string, unknown>): void {
+  process.stdout.write(`${JSON.stringify(event)}\n`)
+}
+
+/**
+ * The minimal composition that owns subscription credentials: the store, the
+ * flow registry, and the adapter that registers the flows. No session, no
+ * sandbox, no tools — signing in is not a conversation. `watch` is off: this
+ * process is the only writer for its lifetime and must exit when done.
+ */
+export async function composeCredentialPlane(credentialsFile: string): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LocalCredentialProvider, { path: credentialsFile, watch: false } as never)
+  await ctx.plugin(AuthorizationService)
+  await ctx.plugin(LlmRuntime)
+  await ctx.plugin(LlmPiAi, { providers: {} } as never)
+  return ctx
+}
+
+/**
+ * Interaction callbacks for a host-driven login, in the seam's neutral
+ * vocabulary. Notices pass through as JSON lines: one carrying a page becomes
+ * `auth_url` (the host opens it), one carrying a code becomes `device_code`,
+ * the rest `info`. A prompt carrying `signal` is an alternative input path
+ * raced against the flow's callback server (anthropic's paste-the-redirect-URL
+ * question); answering is optional, so it stays pending until the flow aborts
+ * it after login settles. A signal-less prompt is required input this
+ * non-interactive host cannot supply — fail loud rather than hang. (A plain
+ * rejection, not `AuthorizationDeclinedError`: "no" would settle the attempt
+ * as cancelled and hide the fact that the host cannot answer.)
+ */
+export function hostLoginInteraction(): AuthorizationInteraction {
+  return {
+    notify: (notice: AuthorizationNotice) => {
+      if (notice.url !== undefined && notice.code !== undefined) {
+        emit({ type: "device_code", verificationUri: notice.url, userCode: notice.code, message: notice.message })
+      } else if (notice.url !== undefined) {
+        emit({ type: "auth_url", url: notice.url, instructions: notice.message })
+      } else {
+        emit({ type: "info", message: notice.message })
+      }
+    },
+    prompt: (prompt: AuthorizationPrompt) =>
+      new Promise<string>((_resolve, reject) => {
+        if (!prompt.signal) {
+          reject(new Error(`interactive prompt not supported in host login flow: ${JSON.stringify(prompt)}`))
+          return
+        }
+        prompt.signal.addEventListener(
+          "abort",
+          () => reject(new Error(`prompt "${prompt.kind}" cancelled: login settled out of band`)),
+          { once: true }
+        )
+      }),
+  }
+}
+
+/** `oauth login <provider>` / `oauth status` / `oauth logout <provider>`; stdout is JSON lines. */
+export async function runOauthCli(argv: string[]): Promise<void> {
+  const [command, providerId] = argv
+  const ctx = await composeCredentialPlane(defaultCredentialsFile())
+  try {
+    if (command === "status") {
+      const stored = await ctx.credentials.listRecords()
+      const credentials = stored
+        .filter((entry) => credentialKeyScope(entry.key) === PI_AI_RECORD_SCOPE)
+        .map((entry) => ({ providerId: credentialKeyId(entry.key), type: entry.kind === "api-key" ? "api_key" : "oauth" }))
+      emit({ type: "status", credentials })
+      return
+    }
+    if (command === "logout") {
+      if (!providerId) throw new Error("usage: oauth logout <provider>")
+      await ctx.credentials.deleteRecord(credentialKey(PI_AI_RECORD_SCOPE, providerId))
+      emit({ type: "logged-out", providerId })
+      return
+    }
+    if (command === "login") {
+      if (!providerId) throw new Error("usage: oauth login <provider>")
+      const key = credentialKey(PI_AI_RECORD_SCOPE, providerId)
+      const flow = ctx.authorization.describe(key)
+      if (flow === undefined) {
+        const available = ctx.authorization
+          .list()
+          .filter((entry) => credentialKeyScope(entry.key) === PI_AI_RECORD_SCOPE)
+          .map((entry) => credentialKeyId(entry.key))
+        throw new Error(`no subscription login wired for "${providerId}" (available: ${available.join(", ")})`)
+      }
+      if (!flow.methods.some((method) => method.id === "oauth")) {
+        throw new Error(`"${providerId}" offers no OAuth login (methods: ${flow.methods.map((m) => m.id).join(", ")})`)
+      }
+      const outcome = await ctx.authorization.begin({ key, method: "oauth", interaction: hostLoginInteraction() })
+      if (outcome.status !== "authorized") throw new Error(`subscription login for "${providerId}" was cancelled`)
+      emit({ type: "logged-in", providerId })
+      return
+    }
+    throw new Error(`unknown oauth command "${command ?? ""}": expected login, status or logout`)
+  } finally {
+    await ctx.fiber.dispose()
+  }
+}

package/src/plugins-cli.ts

@@ -0,0 +1,200 @@
+/**
+ * `plugins` subcommand: lets a host read and edit the plugin overrides file
+ * without a live session (`bun src/main.ts plugins list --json`).
+ *
+ * Output is JSON on stdout; validation failures throw (non-zero exit) with
+ * the reason on stderr — the host surfaces it verbatim.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  HARNESS_PRESETS,
+  type HarnessPreset,
+  type PluginConfigField,
+  loadPluginOverrides,
+  pluginRows,
+  resolvePlugins,
+  savePluginOverrides,
+} from "./plugins.ts";
+
+export function defaultPluginsFile(): string {
+  return (
+    process.env.ALWITH_DSH_PLUGINS_FILE ??
+    join(homedir(), ".dsh-agent", "plugins.json")
+  );
+}
+
+function configurableFields(id: string): PluginConfigField[] {
+  const fields = new Map<string, PluginConfigField>();
+  for (const preset of HARNESS_PRESETS) {
+    const row = pluginRows({
+      sessionsRoot: "/",
+      workspaceRoot: "/",
+      permissionMode: "workspace-write",
+      preset,
+    }).find((candidate) => candidate.id === id);
+    for (const field of row?.configurable ?? []) fields.set(field.key, field);
+  }
+  if (fields.size === 0)
+    throw new Error(`plugin "${id}" has no desktop-configurable fields`);
+  return [...fields.values()];
+}
+
+function parseConfigPatch(
+  id: string,
+  raw: string,
+): Record<string, unknown | null> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `plugin "${id}" config patch is not valid JSON: ${String(error)}`,
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`plugin "${id}" config patch must be a JSON object`);
+  }
+  const fields = new Map(
+    configurableFields(id).map((field) => [field.key, field]),
+  );
+  for (const [key, value] of Object.entries(parsed)) {
+    const field = fields.get(key);
+    if (field === undefined)
+      throw new Error(
+        `plugin "${id}" field "${key}" is not desktop-configurable`,
+      );
+    if (value === null) continue;
+    if (field.type === "number") {
+      if (
+        !Number.isInteger(value) ||
+        (field.minimum !== undefined && (value as number) < field.minimum)
+      ) {
+        throw new Error(
+          `plugin "${id}" field "${key}" must be an integer >= ${field.minimum}`,
+        );
+      }
+    } else if (typeof value !== "string" || !URL.canParse(value)) {
+      throw new Error(`plugin "${id}" field "${key}" must be an absolute URL`);
+    }
+  }
+  return parsed as Record<string, unknown | null>;
+}
+
+interface CliFlags {
+  preset: HarnessPreset;
+  file: string;
+  positional: string[];
+}
+
+function parseFlags(argv: string[]): CliFlags {
+  let preset = process.env.ALWITH_DSH_PRESET ?? "standard";
+  let file = defaultPluginsFile();
+  const positional: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]!;
+    if (argument === "--preset") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new Error("--preset requires a value");
+      preset = value;
+      index += 1;
+    } else if (argument === "--file") {
+      const value = argv[index + 1];
+      if (value === undefined) throw new Error("--file requires a value");
+      file = value;
+      index += 1;
+    } else if (argument.startsWith("--")) {
+      throw new Error(`unknown flag ${argument}`);
+    } else {
+      positional.push(argument);
+    }
+  }
+  if (!(HARNESS_PRESETS as readonly string[]).includes(preset)) {
+    throw new Error(
+      `unsupported preset "${preset}": expected one of ${HARNESS_PRESETS.join(", ")}`,
+    );
+  }
+  return { preset: preset as HarnessPreset, file, positional };
+}
+
+function listingFor(preset: HarnessPreset, file: string) {
+  const overrides = loadPluginOverrides(file);
+  // Listing does not touch the sandbox or session log; placeholder roots keep
+  // the row configs representative without requiring the host's real paths.
+  const rows = pluginRows({
+    sessionsRoot: join(homedir(), ".dsh-agent", "sessions"),
+    workspaceRoot: process.cwd(),
+    permissionMode: "workspace-write",
+    preset,
+  });
+  return { preset, file, plugins: resolvePlugins(rows, overrides).listing };
+}
+
+/** Rejects an overrides state that any preset would refuse to compose. */
+function assertValidAcrossPresets(
+  overrides: ReturnType<typeof loadPluginOverrides>,
+): void {
+  for (const preset of HARNESS_PRESETS) {
+    const rows = pluginRows({
+      sessionsRoot: "/",
+      workspaceRoot: "/",
+      permissionMode: "workspace-write",
+      preset,
+    });
+    resolvePlugins(rows, overrides);
+  }
+}
+
+export async function runPluginsCli(argv: string[]): Promise<void> {
+  const { preset, file, positional } = parseFlags(argv);
+  const [command, ...rest] = positional;
+  if (command === "list") {
+    process.stdout.write(`${JSON.stringify(listingFor(preset, file))}\n`);
+    return;
+  }
+  if (command === "set") {
+    const [id, state] = rest;
+    if (id === undefined || (state !== "enabled" && state !== "disabled")) {
+      throw new Error(
+        "usage: plugins set <id> <enabled|disabled> [--file <path>]",
+      );
+    }
+    const overrides = loadPluginOverrides(file);
+    const disabled = new Set(overrides.disabled ?? []);
+    if (state === "disabled") disabled.add(id);
+    else disabled.delete(id);
+    const next = { ...overrides, disabled: [...disabled].sort() };
+    // Validate before touching disk: the file must never hold a state compose would refuse.
+    assertValidAcrossPresets(next);
+    savePluginOverrides(file, next);
+    process.stdout.write(`${JSON.stringify(listingFor(preset, file))}\n`);
+    return;
+  }
+  if (command === "configure") {
+    const [id, raw] = rest;
+    if (id === undefined || raw === undefined) {
+      throw new Error(
+        "usage: plugins configure <id> <json-patch> [--file <path>]",
+      );
+    }
+    const patch = parseConfigPatch(id, raw);
+    const overrides = loadPluginOverrides(file);
+    const nextConfig = { ...overrides.config };
+    const pluginConfig = { ...nextConfig[id] };
+    for (const [key, value] of Object.entries(patch)) {
+      if (value === null) delete pluginConfig[key];
+      else pluginConfig[key] = value;
+    }
+    if (Object.keys(pluginConfig).length === 0) delete nextConfig[id];
+    else nextConfig[id] = pluginConfig;
+    const next = { ...overrides, config: nextConfig };
+    assertValidAcrossPresets(next);
+    savePluginOverrides(file, next);
+    process.stdout.write(`${JSON.stringify(listingFor(preset, file))}\n`);
+    return;
+  }
+  throw new Error(
+    `unknown plugins command "${command ?? ""}": expected list, set, or configure`,
+  );
+}