dsh-bash-terminal-ts 0.2.5

package/lib/dsh-types.d.ts

@@ -0,0 +1,260 @@
+/** 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;
+}
+/** 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>;
+}
+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>;
+}
+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;
+}
+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;
+}
+/** 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>;
+}
+export interface ApprovalSeam {
+    request(input: unknown): Promise<unknown>;
+}
+/**
+ * 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/lib/dsh-types.js

@@ -0,0 +1,9 @@
+// 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.
+export {};

package/lib/dsh.d.ts

@@ -0,0 +1,33 @@
+import { HarnessError } from "@deepseek-ai/dsh-llm";
+import { parseExitStatus } from "@deepseek-ai/dsh-shell";
+import { clampTimeout, deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
+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 declare const defineTool: <TValue>(spec: ToolSpec<TValue>) => ToolDefinition;
+/** Sentinel code stamped on aborted tool calls. */
+export declare const TOOL_ABORTED: string;
+/** Escalation modes advertised by the official sandbox seam. */
+export declare const ESCALATION_TARGETS: readonly string[];
+/** Official sandbox escalation (mirrors dsh-tool-bash / dsh-tool-pwsh). */
+export declare const approveEscalation: (request: EscalationRequest, context: EscalationContext) => Promise<string>;
+/** Fail-closed validation of the sandbox_permissions / justification pair. */
+export declare const validateEscalationArgs: (permissions: unknown, justification: unknown) => void;
+/** Marker appended to denied results so the UI can offer escalation. */
+export declare const sandboxDenialMarker: (mode: string) => string;
+/** Marker appended to denied results pointing at the escalation affordance. */
+export declare const escalationHintMarker: (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 declare const z: Schemastery;
+/** Re-exported for consumers that want to validate output schemas. */
+export type { JsonSchemaNode };

package/lib/dsh.js

@@ -0,0 +1,29 @@
+// 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";
+export { HarnessError, parseExitStatus, clampTimeout, deadline, timeoutOf };
+/** Wrap a fully specified tool spec into a registrable tool definition. */
+export const defineTool = toolsNs.defineTool;
+/** Sentinel code stamped on aborted tool calls. */
+export const TOOL_ABORTED = toolsNs.TOOL_ABORTED;
+/** Escalation modes advertised by the official sandbox seam. */
+export const ESCALATION_TARGETS = sandboxNs.ESCALATION_TARGETS;
+/** Official sandbox escalation (mirrors dsh-tool-bash / dsh-tool-pwsh). */
+export const approveEscalation = sandboxNs.approveEscalation;
+/** Fail-closed validation of the sandbox_permissions / justification pair. */
+export const validateEscalationArgs = sandboxNs.validateEscalationArgs;
+/** Marker appended to denied results so the UI can offer escalation. */
+export const sandboxDenialMarker = sandboxNs.sandboxDenialMarker;
+/** Marker appended to denied results pointing at the escalation affordance. */
+export const escalationHintMarker = sandboxNs.escalationHintMarker;
+export const z = zDefault;

package/lib/index.d.ts

@@ -0,0 +1,201 @@
+import type { BashTerminalContext, ExecAgent, JobsRegistry, JsonSchemaNode, ResolvedPaths, SandboxFacts, SandboxPolicy, ShellId, ToolRunContext } from "./dsh-types.js";
+/** Stable Cordis plugin name. */
+export declare const name = "bash-terminal";
+/** Services required before the tool can register. */
+export declare const inject: string[];
+/** The terminal backends this tool exposes, in catalog order. */
+export declare const SHELLS: readonly ["powershell", "gitbash", "msys2", "wsl"];
+/** The backend used when the caller does not name one. */
+export declare const DEFAULT_SHELL: ShellId;
+/** Settings namespace backing the user-chosen default terminal. */
+export declare const SETTINGS_NAMESPACE = "bash-terminal";
+/** Static shape of the runtime configuration schema. */
+export interface ConfigValues {
+    defaultShell: string;
+    timeoutMs: number;
+    maxTimeoutMs: number;
+    pwshPath: string;
+    gitBashPath: string;
+    msys2Path: string;
+    wslPath: string;
+}
+/** Runtime configuration schema. */
+export declare const Config: import("./dsh.js").SchemasterySchema;
+declare function candidateExists(candidate: string): boolean;
+/** Well-known PowerShell install locations plus PATH entries, newest first. */
+export declare function candidatePwshPaths(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Git for Windows locations, then PATH bash.exe entries EXCLUDING the
+ * System32 launcher (c:\\windows\\system32\\bash.exe is the WSL
+ * forwarder, not a Git Bash shell).
+ */
+export declare function candidateGitBashPaths(env?: NodeJS.ProcessEnv): string[];
+/**
+ * MSYS2 locations, in preference order: the real `bash.exe` under usr\bin first,
+ * then bin\bash.exe, and `msys2.exe` dead last.
+ *
+ * msys2.exe is NOT a usable backend for piped execution: it is the console-
+ * allocating Cygwin launcher, so a spawn with piped stdio returns exit 0 with
+ * zero bytes on both stdout and stderr (measured on MSYS2 with bash 5.3.15).
+ * Keeping it in the list only as a last-resort fallback preserves the path the
+ * config docs reference, but a working bash.exe always wins.
+ *
+ * MSYS2 uses the same Cygwin/MSYS2 runtime as Git Bash, so it cannot run under
+ * the DSH Windows ACL restricted-token sandbox.
+ */
+export declare function candidateMsys2Paths(env?: NodeJS.ProcessEnv): string[];
+export declare function defaultWslPath(env?: NodeJS.ProcessEnv): string;
+/** Executable paths, possibly undefined when a backend is not installed. */
+export type { ResolvedPaths };
+type PathConfig = Partial<Pick<ConfigValues, "pwshPath" | "gitBashPath" | "msys2Path" | "wslPath">>;
+export declare function resolveAllPaths(config?: PathConfig, env?: NodeJS.ProcessEnv): ResolvedPaths;
+export declare function buildArgv(shell: string, command: string, paths: ResolvedPaths, distro?: string): Array<string | undefined>;
+/**
+ * Merge the DSH_* environment over the process environment. For WSL, only
+ * variables explicitly listed in WSLENV cross the boundary, so every DSH_* key is
+ * appended to it (WSLENV is a `:` separated VAR[/flag] list).
+ *
+ * WSLENV usually already exists for reasons unrelated to us -- Windows Terminal
+ * exports e.g. `WT_SESSION:WT_PROFILE_ID:` -- so the list is layered rather than
+ * rebuilt, or those entries would be silently dropped from every WSL call.
+ * Callers that spawn through a seam which replaces the parent environment
+ * wholesale (the PTY path) must pass the inherited value explicitly.
+ *
+ * @param inheritedWslenv - the WSLENV the child would otherwise inherit.
+ */
+export declare function buildEnv(shell: string, dshEnv?: Record<string, string>, inheritedWslenv?: string | undefined): Record<string, string | undefined>;
+export interface SpawnResolution {
+    command: string;
+    workdir: string;
+    timeoutMs: number;
+    stdoutMaxBytes: number;
+    stdin?: string;
+}
+declare function spawnSpec(resolved: SpawnResolution, argv: string[], env: Record<string, string | undefined>, signal: AbortSignal): {
+    readonly argv: string[];
+    readonly cwd: string;
+    readonly stdio: {
+        readonly stdin: "ignore" | {
+            data: string;
+        };
+        readonly stdout: {
+            maxBytes: number;
+            spill: {
+                maxBytes: number;
+            };
+        };
+        readonly stderr: {
+            maxBytes: number;
+            spill: {
+                maxBytes: number;
+            };
+        };
+    };
+    readonly graceMs: 3000;
+    readonly signal: AbortSignal;
+    readonly env: Record<string, string | undefined>;
+};
+interface StreamOutput {
+    text: string;
+    truncated: boolean;
+    spillPath?: string;
+}
+export interface ForegroundOutcome {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    timeoutMs: number;
+    stdout: StreamOutput;
+    stderr: StreamOutput;
+}
+declare function runForeground(ctx: BashTerminalContext, argv: string[], resolved: SpawnResolution, env: Record<string, string | undefined>, signal: AbortSignal, timeoutMs: number): Promise<ForegroundOutcome>;
+export interface ProcessRead {
+    delta: string;
+    lossy: boolean;
+    stdoutSpillPath?: string;
+    stderrSpillPath?: string;
+}
+interface BackgroundProc {
+    status: "running" | "killed" | "completed";
+    exitCode: number | null;
+    signal: string | null;
+    done: Promise<void>;
+    readOutput(): ProcessRead;
+    kill(): boolean;
+}
+declare function startBackground(ctx: BashTerminalContext, argv: string[], resolved: SpawnResolution, env: Record<string, string | undefined>, signal: AbortSignal): BackgroundProc;
+declare function processOutcome(proc: BackgroundProc): {
+    status: string;
+    detail: string;
+};
+export interface RenderedResult {
+    stdout: StreamOutput;
+    stderr: StreamOutput;
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    timeoutMs: number;
+}
+export declare function renderResult(result: RenderedResult): string;
+/** Model-facing lead sentence for each backend. The user's default terminal is
+ * stated up front so the model never has to guess which syntax applies. */
+export declare const SHELL_DESCRIPTIONS: Record<ShellId, string>;
+/**
+ * Render the model-facing tool description for one backend. The backend is
+ * whatever the user chose in Settings -> General -> Default terminal; the
+ * description names it explicitly so the model writes the right syntax.
+ * @param backgroundEnabled - advertise `run_in_background` controls.
+ * @param shell - active backend; unknown values fall back to the default.
+ */
+export declare function toolDescription(backgroundEnabled: boolean, shell?: string): string;
+/** The shell tool's arguments after runtime validation. */
+export type ValidatedShellArgs = {
+    command: string;
+    description: string;
+    timeoutMs?: number;
+    distro?: string;
+    sandbox_permissions?: string;
+    justification?: string;
+    workdir?: string;
+    run_in_background?: boolean;
+    stdin?: string;
+};
+export declare function validateArgs(args: Record<string, unknown>): ValidatedShellArgs;
+declare function resolveWorkdir(modelWorkdir: string | undefined, exec: ToolRunContext): string | undefined;
+export interface ForegroundResult {
+    kind: "foreground";
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    timeoutMs: number;
+    stdout: StreamOutput;
+    stderr: StreamOutput;
+    sandbox?: SandboxFacts;
+}
+export interface BackgroundResult {
+    kind: "background";
+    jobId: string;
+}
+export type ShellToolResult = ForegroundResult | BackgroundResult;
+export declare function apply(ctx: BashTerminalContext, config?: Partial<ConfigValues>): void;
+export declare const internals: {
+    candidateExists: typeof candidateExists;
+    resolveAllPaths: typeof resolveAllPaths;
+    resolveWorkdir: typeof resolveWorkdir;
+    renderResult: typeof renderResult;
+    processOutcome: typeof processOutcome;
+    startBackground: typeof startBackground;
+    runForeground: typeof runForeground;
+    spawnSpec: typeof spawnSpec;
+    buildEnv: typeof buildEnv;
+    buildArgv: typeof buildArgv;
+    validateArgs: typeof validateArgs;
+    toolDescription: typeof toolDescription;
+    SHELL_DESCRIPTIONS: Record<ShellId, string>;
+    DEFAULT_TIMEOUT_MS: number;
+    MAX_TIMEOUT_MS: number;
+    DEFAULT_MAX_OUTPUT_BYTES: number;
+};
+export type { ExecAgent, JobsRegistry, JsonSchemaNode, SandboxFacts, SandboxPolicy, ShellId, ToolRunContext };