@hy-sde-org/dsh-tool-debug 0.1.1-rc.2

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Schema-level vocabulary for the `debug` tool: the closed action set and the
+ * raw model-facing argument shape (snake_case, DAP terminology). Ported from
+ * oh-my-pi's `coding-agent/src/tools/debug.ts` (MIT).
+ * @module @hy-sde-org/dsh-tool-debug/types
+ */
+/** The 28 debug actions. Read-only introspection actions are safe to read from
+ *  a paused program; everything else mutates execution state. */
+export declare const DEBUG_ACTIONS: readonly ["launch", "attach", "set_breakpoint", "remove_breakpoint", "set_instruction_breakpoint", "remove_instruction_breakpoint", "data_breakpoint_info", "set_data_breakpoint", "remove_data_breakpoint", "continue", "step_over", "step_in", "step_out", "pause", "evaluate", "stack_trace", "threads", "scopes", "variables", "disassemble", "read_memory", "write_memory", "modules", "loaded_sources", "custom_request", "output", "terminate", "sessions"];
+/** The closed union of debug actions. */
+export type DebugToolAction = (typeof DEBUG_ACTIONS)[number];
+/**
+ * Narrow a runtime value to `DebugToolAction` when it names one.
+ * @param value - the runtime value to test.
+ * @returns whether `value` is a known debug action.
+ */
+export declare function isDebugAction(value: unknown): value is DebugToolAction;
+/** Read-only actions that only inspect program state (no mutation/execution). */
+export declare const DEBUG_READONLY_ACTIONS: ReadonlySet<string>;
+/** Model-facing arguments of one `debug` call (all optional except `action`). */
+export interface DebugToolArgs {
+    readonly action: DebugToolAction;
+    /** Debug target path; Delve accepts Go package directories. */
+    readonly program?: string;
+    /** Program arguments for launch. */
+    readonly args?: string[];
+    /** Configured adapter id (gdb, lldb-dap, debugpy, dlv, ... or a dap.json entry). */
+    readonly adapter?: string;
+    /** Call working directory; defaults to the session workspace. */
+    readonly cwd?: string;
+    /** Source file (breakpoint operations; resolved against cwd). */
+    readonly file?: string;
+    readonly line?: number;
+    /** Function name (breakpoint operations). */
+    readonly function?: string;
+    /** Variable or data name (data_breakpoint_info). */
+    readonly name?: string;
+    /** Breakpoint condition expression. */
+    readonly condition?: string;
+    readonly hit_condition?: string;
+    /** Expression to evaluate. */
+    readonly expression?: string;
+    /** Evaluate context: watch | repl | hover | variables | clipboard. */
+    readonly context?: string;
+    readonly frame_id?: number;
+    /** Scope variables reference. */
+    readonly scope_id?: number;
+    /** Variable reference. */
+    readonly variable_ref?: number;
+    /** Process id for attach. */
+    readonly pid?: number;
+    /** Remote attach port. */
+    readonly port?: number;
+    readonly host?: string;
+    /** Max stack frames for stack_trace. */
+    readonly levels?: number;
+    /** Memory reference or address. */
+    readonly memory_reference?: string;
+    readonly instruction_reference?: string;
+    readonly instruction_count?: number;
+    readonly instruction_offset?: number;
+    /** Bytes to read for read_memory. */
+    readonly count?: number;
+    /** Base64 memory payload for write_memory. */
+    readonly data?: string;
+    readonly data_id?: string;
+    readonly access_type?: 'read' | 'write' | 'readWrite';
+    /** Custom DAP request command. */
+    readonly command?: string;
+    /** Custom request arguments. */
+    readonly arguments?: Record<string, unknown>;
+    readonly offset?: number;
+    readonly resolve_symbols?: boolean;
+    readonly allow_partial?: boolean;
+    readonly start_module?: number;
+    readonly module_count?: number;
+    /** Per-request timeout seconds. */
+    readonly timeout?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,60 @@
+/**
+ * Schema-level vocabulary for the `debug` tool: the closed action set and the
+ * raw model-facing argument shape (snake_case, DAP terminology). Ported from
+ * oh-my-pi's `coding-agent/src/tools/debug.ts` (MIT).
+ * @module @hy-sde-org/dsh-tool-debug/types
+ */
+/** The 28 debug actions. Read-only introspection actions are safe to read from
+ *  a paused program; everything else mutates execution state. */
+export const DEBUG_ACTIONS = [
+    'launch',
+    'attach',
+    'set_breakpoint',
+    'remove_breakpoint',
+    'set_instruction_breakpoint',
+    'remove_instruction_breakpoint',
+    'data_breakpoint_info',
+    'set_data_breakpoint',
+    'remove_data_breakpoint',
+    'continue',
+    'step_over',
+    'step_in',
+    'step_out',
+    'pause',
+    'evaluate',
+    'stack_trace',
+    'threads',
+    'scopes',
+    'variables',
+    'disassemble',
+    'read_memory',
+    'write_memory',
+    'modules',
+    'loaded_sources',
+    'custom_request',
+    'output',
+    'terminate',
+    'sessions',
+];
+/**
+ * Narrow a runtime value to `DebugToolAction` when it names one.
+ * @param value - the runtime value to test.
+ * @returns whether `value` is a known debug action.
+ */
+export function isDebugAction(value) {
+    return typeof value === 'string' && DEBUG_ACTIONS.includes(value);
+}
+/** Read-only actions that only inspect program state (no mutation/execution). */
+export const DEBUG_READONLY_ACTIONS = new Set([
+    'output',
+    'threads',
+    'stack_trace',
+    'scopes',
+    'variables',
+    'disassemble',
+    'read_memory',
+    'loaded_sources',
+    'modules',
+    'sessions',
+]);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;iEACiE;AACjE,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ;IACR,QAAQ;IACR,gBAAgB;IAChB,mBAAmB;IACnB,4BAA4B;IAC5B,+BAA+B;IAC/B,sBAAsB;IACtB,qBAAqB;IACrB,wBAAwB;IACxB,UAAU;IACV,WAAW;IACX,SAAS;IACT,UAAU;IACV,OAAO;IACP,UAAU;IACV,aAAa;IACb,SAAS;IACT,QAAQ;IACR,WAAW;IACX,aAAa;IACb,aAAa;IACb,cAAc;IACd,SAAS;IACT,gBAAgB;IAChB,gBAAgB;IAChB,QAAQ;IACR,WAAW;IACX,UAAU;CACF,CAAA;AAKV;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAC1F,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IACjE,QAAQ;IACR,SAAS;IACT,aAAa;IACb,QAAQ;IACR,WAAW;IACX,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,SAAS;IACT,UAAU;CACX,CAAC,CAAA"}

package/examples/agent-preset/agent.cordis.yml

@@ -0,0 +1,50 @@
+# User agent preset for @hy-sde-org/dsh-tool-debug — "agents get a real DAP
+# debugger".
+#
+# Install: copy this directory to ~/.dsh/.agent-presets/<id>/ (pick any id),
+# then select the preset in the Web UI preset picker (or `dsh agent` CLI).
+#
+# Structure: the `dap` service lives in an entry-local realm (isolate:
+# dap) so each mounted session owns its adapter processes and captured
+# output; tool-debug sits beside it and resolves `ctx.dap` from that realm.
+# The DAP adapters themselves are local binaries (debugpy / dlv / lldb-dap /
+# gdb...) resolved at runtime; no separate provider package is needed.
+#
+# Copy any other rows from the preset you normally use (bash, todo, ask-user,
+# skills, ...) next to these; only the debugging rows are special.
+
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+      Debug code with the `debug` tool, which attaches or launches a real
+      debugger (debugpy, lldb-dap, gdb, dlv, ...): set source/function/
+      instruction/data breakpoints, continue/pause/step, read stack
+      frames/scopes/variables, evaluate expressions, disassemble, read/write
+      memory, list modules and loaded sources, and send custom debugger
+      requests. One live debug session at a time; terminate it before
+      launching another.
+
+- id: agent-instructions
+  name: '@deepseek-ai/dsh-agent-instructions'
+  config:
+    maxBytes: 65536
+
+# DAP capability seam + the model-facing debug tool. The seam's realm means
+# adapter processes and breakpoint state belong to this session alone.
+- id: debug
+  name: cordis:group
+  group: true
+  isolate:
+    dap: true
+  config:
+    - id: dap
+      name: '@hy-sde-org/dsh-dap'
+
+    - id: tool-debug
+      name: '@hy-sde-org/dsh-tool-debug'
+      config:
+        maxResultChars: 16000
+        requestTimeoutSec: 30
+        timeoutMs: 120000

package/examples/agent-preset/preset.yml

@@ -0,0 +1,3 @@
+name: Debug Mode (real DAP)
+description: Coding agent with a real DAP debugger — launch/attach debugpy, lldb-dap, gdb, or dlv; breakpoints, stepping, frames/locals, evaluate, memory, modules.
+order: 6

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@hy-sde-org/dsh-tool-debug",
+  "version": "0.1.1-rc.2",
+  "description": "The `debug` tool for DeepSeek Harness — a model-facing Debug Adapter Protocol tool with 28 operations (launch/attach, breakpoints, continue/pause/step, threads/stackTrace/scopes/variables/evaluate, disassembly, memory, modules, output, terminate) over the standalone DAP seam — a standalone plugin with no upstream harness changes required.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./invariant": {
+      "types": "./dist/invariant.d.ts",
+      "default": "./dist/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "cordis.patch.yml",
+    "examples/agent-preset/agent.cordis.yml",
+    "examples/agent-preset/preset.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepack": "pnpm run clean && pnpm run build"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hy-sde/dsh-tool-debug.git"
+  },
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@hy-sde-org/dsh-dap": "workspace:^",
+    "@deepseek-ai/schemastery": "3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "@hy-sde-org/dsh-dap": "workspace:^",
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  },
+  "keywords": [
+    "deepseek",
+    "agent",
+    "harness",
+    "dsh-plugin",
+    "debug",
+    "dap",
+    "debugger"
+  ]
+}