dsh-bash-terminal-ts 0.2.5

package/src/client.tsx

@@ -0,0 +1,161 @@
+// dsh-bash-terminal-ts client plugin: a "Default terminal" preference row in the
+// Web UI General settings. The user picks powershell / gitbash / msys2 / wsl;
+// the host shell tool obeys that choice (the model cannot change it).
+//
+// The option list below must stay in lockstep with SHELLS in ./index.ts: every
+// id gets an <option> here and a `shell.<id>` entry in both dictionaries. The
+// shipped bundle cannot import the host module (it pulls node: builtins), so
+// test/client.ts asserts the bundle covers every host shell id instead.
+
+import { defineStore } from "@deepseek-ai/dsh-client-store";
+
+const SETTINGS_NS = "settings.bash-terminal";
+const SETTINGS_NAMESPACE = "bash-terminal";
+
+const zh: Record<string, string> = {
+  "shell.title": "默认终端",
+  "shell.description": "shell 工具执行命令时使用的终端（由你决定，AI 无法更改）",
+  "shell.powershell": "PowerShell",
+  "shell.gitbash": "Git Bash",
+  "shell.msys2": "MSYS2",
+  "shell.wsl": "WSL"
+};
+const en: Record<string, string> = {
+  "shell.title": "Default terminal",
+  "shell.description": "Terminal used by the shell tool (you control this; the AI cannot change it)",
+  "shell.powershell": "PowerShell",
+  "shell.gitbash": "Git Bash",
+  "shell.msys2": "MSYS2",
+  "shell.wsl": "WSL"
+};
+
+export const inject = ["slots", "locale", "settingsScope"];
+
+/** Row state snapshot served through the settings store. */
+interface RowState {
+  shell: string;
+  revision: number;
+  writable: boolean;
+}
+
+interface ShellPreferenceRowProps {
+  t: (key: string) => string;
+  useStore: <S>(selector: (state: RowState) => S) => S;
+  setShell: (id: string) => void;
+}
+
+function ShellPreferenceRow({ t, useStore, setShell }: ShellPreferenceRowProps) {
+  const shell = useStore((s) => s.shell);
+  const writable = useStore((s) => s.writable);
+  return (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: 16,
+        padding: "12px 0"
+      }}
+    >
+      <div style={{ minWidth: 0 }}>
+        <div style={{ fontSize: 14, fontWeight: 500, lineHeight: "22px", color: "var(--dsw-alias-label-primary, inherit)" }}>
+          {t("shell.title")}
+        </div>
+        <div style={{ fontSize: 12, lineHeight: "18px", opacity: 0.65 }}>{t("shell.description")}</div>
+      </div>
+      <select
+        value={shell}
+        disabled={!writable}
+        onChange={(e) => setShell(e.target.value)}
+        style={{
+          fontSize: 14,
+          padding: "6px 10px",
+          borderRadius: 8,
+          border: "1px solid var(--dsw-alias-line-strong, #ccc)",
+          background: "var(--dsw-alias-bg-layer-2, #fff)",
+          color: "var(--dsw-alias-label-primary, inherit)",
+          outline: "none",
+          cursor: writable ? "pointer" : "not-allowed",
+          maxWidth: 180
+        }}
+      >
+        <option value="powershell">{t("shell.powershell")}</option>
+        <option value="gitbash">{t("shell.gitbash")}</option>
+        <option value="msys2">{t("shell.msys2")}</option>
+        <option value="wsl">{t("shell.wsl")}</option>
+      </select>
+    </div>
+  );
+}
+
+interface SettingsSnapshot {
+  status: string;
+  value?: { defaultShell?: string };
+  revision: number;
+  writable: boolean;
+}
+
+interface SettingsScopeBinding {
+  getSnapshot(): SettingsSnapshot;
+  subscribe(fn: () => void): () => void;
+  set(field: string, value: string): void;
+  unset(): void;
+}
+
+interface ClientContext {
+  effect(fn: () => unknown, name?: string): unknown;
+  locale: { register(ns: string, dicts: Record<string, Record<string, string>>): unknown };
+  settingsScope: { bind(options: { namespace: string }): SettingsScopeBinding };
+  slots: {
+    inject(slot: string, fn: () => unknown, name?: string): void;
+    register(options: Record<string, unknown>, Component: unknown): Record<string, unknown>;
+  };
+}
+
+interface RowStoreActions {
+  sync(shell?: string, revision?: number, writable?: boolean): void;
+}
+
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), "bash-terminal: settings dictionaries");
+  const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE });
+  const store = defineStore<RowState, { sync: (draft: RowState, shell?: string, revision?: number, writable?: boolean) => void }>({
+    init: (): RowState => ({ shell: "powershell", revision: -1, writable: false }),
+    actions: {
+      sync: (d, shell, revision, writable) => {
+        if (revision !== undefined && revision <= d.revision) return;
+        if (shell !== undefined) d.shell = shell;
+        if (revision !== undefined) d.revision = revision;
+        if (writable !== undefined) d.writable = writable;
+      }
+    }
+  });
+  // defineStore() yields a { spec, create } factory; slots.register creates
+  // the live store, so we bind the actions in the inject callback and push
+  // the initial snapshot there too (mirrors the theme row pattern).
+  let bound: RowStoreActions | undefined;
+  const push = (snap: SettingsSnapshot): void => {
+    bound?.sync(snap.value?.defaultShell, snap.revision, snap.writable);
+  };
+  ctx.slots.inject(
+    "settings.general.item",
+    () =>
+      ctx.slots.register(
+        {
+          name: "settings.general.item",
+          id: "bash-terminal-shell",
+          order: 20,
+          store,
+          locale: SETTINGS_NS,
+          inject: (actions: unknown) => {
+            bound = actions as RowStoreActions;
+            push(scope.getSnapshot());
+            return { setShell: (value: string) => void scope.set("defaultShell", value) };
+          }
+        },
+        ShellPreferenceRow
+      ),
+    "bash-terminal: settings row"
+  );
+  ctx.effect(() => scope.subscribe(() => push(scope.getSnapshot())), "bash-terminal: settings watch");
+}

package/src/dsh-types.ts

@@ -0,0 +1,313 @@
+// Hand-written boundary types for the DSH seams this plugin consumes.
+//
+// The @deepseek-ai/* packages ship their own .d.ts, but their full generic
+// surface (cordis Context augmentation, agent/session graphs) is far wider
+// than what a plugin touches. These structural types describe exactly the
+// face this plugin programs against — call them the plugin's side of the
+// contract. Value imports stay on the real packages (see ./dsh.ts); only
+// the shapes live here, so peer version drift cannot ripple into this tree.
+
+// ---- shared ------------------------------------------------------------------
+
+/** The terminal backends this plugin exposes. */
+export type ShellId = "powershell" | "gitbash" | "msys2" | "wsl";
+
+/** Permissive node of the DSH JSON-schema dialect used in tool output declarations. */
+export interface JsonSchemaNode {
+  type?: string;
+  required?: boolean;
+  const?: string;
+  enum?: readonly string[];
+  properties?: Record<string, JsonSchemaNode>;
+  items?: JsonSchemaNode;
+  oneOf?: JsonSchemaNode[];
+  additionalProperties?: boolean;
+}
+
+/** Model-facing content block (subset). */
+export interface ContentBlock {
+  type: string;
+  text?: string;
+}
+
+// ---- tool surface ------------------------------------------------------------
+
+/** One entry of a tool's `parameters` declaration. */
+export interface ToolParameterProperty {
+  type: string;
+  required?: boolean;
+  description?: string;
+  enum?: readonly string[];
+}
+
+export interface ToolParameters {
+  type: "object";
+  properties: Record<string, ToolParameterProperty>;
+}
+
+/** Flat parameter map as accepted by defineTool (wrapped into `ToolParameters` by the runtime). */
+export type ToolParameterMap = Record<string, ToolParameterProperty>;
+
+/** The exec object every tool body receives. */
+export interface ToolRunContext {
+  /** Caller cancellation; observe or forward it in async work. */
+  signal: AbortSignal;
+  callId?: string;
+  agent?: ExecAgent;
+}
+
+/** The agent slice of exec this plugin reads (session cwd) or passes on (owner). */
+export interface ExecAgent {
+  session: { header: { cwd?: string } };
+}
+
+export interface ToolResult {
+  content: ContentBlock[];
+  isError?: boolean;
+}
+
+/** Tool output view handed to presentResult. */
+export interface CallView {
+  card: string;
+  [key: string]: unknown;
+}
+
+/** A fully specified tool: schema, canonical output, body, presentations. */
+export interface ToolSpec<TValue> {
+  name: string;
+  description: string;
+  parameters: ToolParameterMap;
+  output: {
+    schema: JsonSchemaNode;
+    render: (args: unknown, value: TValue) => ContentBlock[];
+  };
+  execute: (args: Record<string, unknown>, exec: ToolRunContext) => Promise<TValue>;
+  presentCall?: (args: Record<string, unknown>) => CallView;
+  presentResult?: (args: Record<string, unknown>, result: ToolResult) => CallView | undefined;
+}
+
+/** Canonical output declaration, erased of the tool's value type (registry face). */
+export interface ToolOutputDefinition {
+  schema: JsonSchemaNode;
+  render: (args: unknown, value: unknown) => ContentBlock[];
+}
+
+/** What defineTool hands back (opaque to the plugin; registered as-is). */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: ToolParameters;
+  output: ToolOutputDefinition;
+  execute: (args: Record<string, unknown>, exec: ToolRunContext) => Promise<unknown>;
+}
+
+// ---- ctx services ------------------------------------------------------------
+
+export interface LoggerSeam {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+}
+
+export interface SystemPromptSection {
+  name: string;
+  order: number;
+  text: string;
+}
+
+export interface SystemPromptSeam {
+  section(spec: SystemPromptSection): unknown;
+}
+
+export interface ToolsSeam {
+  register(tool: ToolDefinition): unknown;
+}
+
+/** A tool entry seen during system-prompt assembly (description re-render). */
+export interface AssembledToolRef {
+  name: string;
+  description?: string;
+}
+
+export interface PromptAssembly {
+  tools: AssembledToolRef[];
+  [key: string]: unknown;
+}
+
+/** Type of the system-prompt/assemble waterfall listener. */
+export type AssembleHandler = (
+  assembly: PromptAssembly,
+  context: unknown,
+  next: () => Promise<PromptAssembly>
+) => Promise<PromptAssembly>;
+
+export interface ShellEnvSeam {
+  collect(exec: ToolRunContext): Record<string, string> | undefined;
+}
+
+export interface SettingsScope<T> {
+  get(): T;
+}
+
+export interface SettingsSeam {
+  register<T>(namespace: string, schema: unknown, options: { base: T }): SettingsScope<T>;
+}
+
+// ---- sandbox ------------------------------------------------------------------
+
+export interface SandboxPolicy {
+  mode: string;
+  workspaceRoot?: string;
+  sessionId?: string;
+}
+
+export interface SandboxPolicySeam {
+  resolve(scope: { session?: unknown }): SandboxPolicy;
+}
+
+export interface SandboxConfineResult {
+  argv: string[];
+  enforcement: string;
+  denialSignatures?: string[];
+}
+
+export interface SandboxSeam {
+  confine(argv: string[], policy: SandboxPolicy): SandboxConfineResult;
+}
+
+/** Sandbox facts embedded in a canonical result. */
+export interface SandboxFacts {
+  mode: string;
+  enforcement: string;
+  denialSignatures?: string[];
+  denied?: boolean;
+}
+
+export interface EscalationRequest {
+  requestedMode: string;
+  justification: string;
+  effectiveMode: string;
+  subject: string;
+}
+
+export interface EscalationContext {
+  approver?: unknown;
+  agent?: unknown;
+  callId?: string;
+  toolName: string;
+  signal: AbortSignal;
+}
+
+// ---- background jobs ------------------------------------------------------------
+
+export interface JobHooks {
+  cancel: () => void;
+  done: Promise<unknown>;
+  readOutput: () => string;
+}
+
+export interface JobSpec {
+  kind: string;
+  label: string;
+  owner?: unknown;
+  run: () => JobHooks;
+}
+
+export interface JobsRegistry {
+  start(spec: JobSpec): string;
+}
+
+// ---- subprocess seam ------------------------------------------------------------
+
+/** Executable paths per backend; undefined when a backend is not installed. */
+export interface ResolvedPaths {
+  pwsh?: string;
+  gitbash?: string;
+  msys2?: string;
+  wsl?: string;
+}
+
+export interface CollectSpec {
+  maxBytes: number;
+  spill: { maxBytes: number };
+}
+
+export interface StdioSpec {
+  stdin: { data: string } | "ignore";
+  stdout: CollectSpec;
+  stderr: CollectSpec;
+}
+
+export interface SubprocessSpawnSpec {
+  argv: string[];
+  cwd?: string;
+  stdio: StdioSpec;
+  graceMs: number;
+  signal?: AbortSignal;
+  env?: Record<string, string | undefined>;
+}
+
+export interface CollectedStream {
+  readFrom(offset: number): { text: string; lossy: boolean; nextOffset: number; spillPath?: string };
+}
+
+export interface SubprocessOutcome {
+  exitCode: number | null;
+  signal: string | null;
+}
+
+export interface SubprocessHandle {
+  collected: { stdout: CollectedStream; stderr: CollectedStream };
+  done: Promise<SubprocessOutcome>;
+  terminate: () => void | Promise<void>;
+}
+
+export interface TerminalSpawnSpec {
+  argv: string[];
+  cwd: string;
+  env: Record<string, string | undefined>;
+  rows: number;
+  cols: number;
+  graceMs?: number;
+}
+
+export interface TerminalHandle {
+  pid: number;
+  output: NodeJS.ReadableStream;
+  done: Promise<SubprocessOutcome>;
+  write(data: string): void | Promise<void>;
+  signalForeground(sig: string): void | Promise<unknown>;
+  terminate(): Promise<void>;
+}
+
+export interface SubprocessSeam {
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+  spawnTerminal?(spec: TerminalSpawnSpec): Promise<TerminalHandle>;
+}
+
+// ---- approval ------------------------------------------------------------------
+
+export interface ApprovalSeam {
+  request(input: unknown): Promise<unknown>;
+}
+
+// ---- plugin context (server side) ----------------------------------------------
+
+/**
+ * The structural context face dsh-bash-terminal-ts programs against: the union
+ * of every `ctx.*` member touched by src/index.ts and src/terminal.ts.
+ */
+export interface BashTerminalContext {
+  logger?: LoggerSeam;
+  systemPrompt: SystemPromptSeam;
+  tools: ToolsSeam;
+  on(event: "system-prompt/assemble", handler: AssembleHandler): void;
+  shellEnv: ShellEnvSeam;
+  settings: SettingsSeam;
+  sandboxPolicy: SandboxPolicySeam;
+  sandbox: SandboxSeam;
+  get(key: string): unknown;
+  effect(fn: () => void | (() => void), name?: string): unknown;
+  /** Injected via `inject: ["subprocess"]`; tests may defer assignment. */
+  subprocess: SubprocessSeam | null;
+}

package/src/dsh.ts

@@ -0,0 +1,68 @@
+// Value bridge to the @deepseek-ai/* peer packages.
+//
+// Peer packages ship their own .d.ts, but this plugin's contract with them is
+// a narrow, stable face (see ./dsh-types.ts). Every import passes through one
+// narrow cast here, so the plugin compiles against any 0.1.x peer whose
+// runtime behavior matches the face — no deep generic coupling, no version
+// drift leaking into the rewrite.
+
+import * as toolsNs from "@deepseek-ai/dsh-tools";
+import * as sandboxNs from "@deepseek-ai/dsh-sandbox";
+import { HarnessError } from "@deepseek-ai/dsh-llm";
+import { parseExitStatus } from "@deepseek-ai/dsh-shell";
+import { clampTimeout, deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
+import zDefault from "@deepseek-ai/schemastery";
+import type {
+  EscalationContext,
+  EscalationRequest,
+  JsonSchemaNode,
+  ToolDefinition,
+  ToolSpec
+} from "./dsh-types.js";
+
+export { HarnessError, parseExitStatus, clampTimeout, deadline, timeoutOf };
+
+/** Wrap a fully specified tool spec into a registrable tool definition. */
+export const defineTool = toolsNs.defineTool as unknown as <TValue>(spec: ToolSpec<TValue>) => ToolDefinition;
+
+/** Sentinel code stamped on aborted tool calls. */
+export const TOOL_ABORTED = toolsNs.TOOL_ABORTED as string;
+
+/** Escalation modes advertised by the official sandbox seam. */
+export const ESCALATION_TARGETS = sandboxNs.ESCALATION_TARGETS as readonly string[];
+
+/** Official sandbox escalation (mirrors dsh-tool-bash / dsh-tool-pwsh). */
+export const approveEscalation = sandboxNs.approveEscalation as unknown as (
+  request: EscalationRequest,
+  context: EscalationContext
+) => Promise<string>;
+
+/** Fail-closed validation of the sandbox_permissions / justification pair. */
+export const validateEscalationArgs = sandboxNs.validateEscalationArgs as unknown as (
+  permissions: unknown,
+  justification: unknown
+) => void;
+
+/** Marker appended to denied results so the UI can offer escalation. */
+export const sandboxDenialMarker = sandboxNs.sandboxDenialMarker as unknown as (mode: string) => string;
+
+/** Marker appended to denied results pointing at the escalation affordance. */
+export const escalationHintMarker = sandboxNs.escalationHintMarker as unknown as (subject: string) => string;
+
+/** Runtime config schema factory (schemastery fork). */
+export interface SchemasterySchema {
+  default(value: unknown): SchemasterySchema;
+}
+
+export interface Schemastery {
+  object(fields: Record<string, SchemasterySchema>): SchemasterySchema;
+  string(): SchemasterySchema;
+  number(): SchemasterySchema;
+  const(value: string): SchemasterySchema;
+  union(schemas: SchemasterySchema[]): SchemasterySchema;
+}
+
+export const z = zDefault as unknown as Schemastery;
+
+/** Re-exported for consumers that want to validate output schemas. */
+export type { JsonSchemaNode };