dsh-bash-terminal-ts 0.4.0 → 0.4.1

package/lib/dsh-types.d.ts

@@ -1,260 +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;
-}
+/** 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.d.ts

@@ -1,33 +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 };
+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 };