better-dsh 0.2.3-c → 0.2.3-e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-dsh",
-  "version": "0.2.3-c",
+  "version": "0.2.3-e",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -13,6 +13,10 @@
       "types": "./lib/py-sdk.d.ts",
       "default": "./lib/py-sdk.js"
     },
+    "./fs-aware-sandbox": {
+      "types": "./lib/fs-aware/sandbox-plugin.d.ts",
+      "default": "./lib/fs-aware/sandbox-plugin.js"
+    },
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json",
     "./client": {
@@ -24,7 +28,8 @@
     "lib",
     "docs",
     "cordis.patch.yml",
-    "control-prompt.md",
+    "eval-description.md",
+    "url-schemes-instruction.md",
     "scripts/kernel-provision.mjs"
   ],
   "scripts": {

package/url-schemes-instruction.md

@@ -0,0 +1,22 @@
+# Internal URL Schemes
+
+- Format: `scheme://<path>[:selector]`.
+- Compatibility: Supported anywhere a filesystem path is accepted across `read`, `write`, `grep`, and `glob`.
+- `skill://`, `agent://`, `ctx://`, `dsh://`, `dvc://`, `http(s)://`.
+- Reading scheme:// lists available surfaces/help for that scheme.
+
+**Selectors:**
+- `:raw` — Accesses the full underlying content bypasses prepared faces/summaries.
+- `:N-M[,N2-M2]` — Line range selection (1-based, inclusive; `N-` reads to end). Indexes canonical full content (so `:raw:N-M` ≡ `:N-M`).
+- `:path/<a.b>` — Traverses JSON using dot-path notation.
+- `?q=<q>` — Dot-path search or plain line filter.
+
+**Schemes:**
+- `skill://<name>[/<file>]` — a registered skill's files; first level = skill names.
+- `agent://[<id>[/transcript]]` — agent roster / a LIVE agent's transcript.
+- `dsh://docs[/<doc>]` and `dsh://config` — harness docs / live resolved config.
+- `ctx://session/<face>` — THIS session's own log; faces: `transcript`, `compactions`, `compactions[<label|n>]`, `thinking`, `system`, `user_prompts[n]`, `tool_calls[n]`, `agent_responses[n]`.
+- `dvc://<device>` — device registry; devices: `ast_edit`, `ast_grep`, `browser`, `lsp`; `write` executes.
+- `http(s)://<host>/<path>` — plain fetch.
+
+Bulk: prefer grep or `:N-M` line windows over full reads.

package/control-prompt.md

@@ -1,37 +0,0 @@
-## The DASHR REPL interface
-
-This agent has TWO ways to act:
-
-1. **Direct tool calls** — call native tools (`read`/`write`/`edit`/`bash`/…) as ordinary function calls. Use these for payload-shaped work: one long read, one edit, one command.
-2. **`eval` cells** — one `eval` call runs one Python program on a session-persistent scripting pad. Use it when you need logic: loops, conditions, fan-out, or composing many tool results into one step.
-
-`eval` takes two required arguments: `cell` (one Python program; top-level `await` works; top-level `return` is a SyntaxError — the cell runs in module scope; variables/imports/definitions from earlier cells are still alive) and `description` (a short summary).
-
-## Tools inside a cell
-
-Inside a cell, every native tool is a member of the `tool` object, called as `await tool.name({...})` with ONE positional arguments object — `await tool.read({"file_path": "x"})`, never `tool.read(file_path="x")`. A failed call raises `ToolCallError`. Tool names that are not plain identifiers (non-identifier characters, e.g. hyphens) have no `tool.<name>` member — call those as direct tool calls. Delegation: `agent` is the unified agent-spawn entry; `subagent` is its native alias — both delegate through the same runtime, so call either.
-
-```python
-# One step cell
-print(await tool.read({"file_path": "docs/README.md"}))
-
-# shell is another tool
-r = await tool.bash({"command": "ls -la src/", "description": "List source directory"})
-print(r["stdout"]["text"])
-
-# fan-out with gather
-import asyncio
-matches, files = await asyncio.gather(
-    tool.grep({"pattern": "TODO", "path": "src"}),
-    tool.glob({"pattern": "**/*.ts", "path": "src"}),
-)
-
-# variables persist across cells and turns
-cfg = await tool.read({"file_path": "config.yaml"})   # cfg stays alive in later cells
-```
-
-## Rules
-
-- Payload-shaped work (a long read, a big write, a single command) → direct tool call. Logic-shaped work (loops, conditions, composition) → an `eval` cell.
-- Only print or return what you need next; everything else stays in the scripting pad.
-- Variables persist across cells and turns, but they live in the pad's process: keep durable state in files.

package/lib/py-sdk-BCaOGYz7.d.ts

@@ -1,125 +0,0 @@
-//#region src/py-sdk.d.ts
-/**
- * DASHR kernel SDK codegen — Python flavor, cell edition.
- *
- * The pure projection from one calling scope's visible tool schemas to the
- * Python SDK text the model programs against inside `eval` cells. The
- * type-rendering machinery is ported from `@deepseek-ai/dsh-tools`
- * `py-types.ts` (0.1.0-rc.6) per blueprint §7.4, deliberately slimmed to
- * DASHR's single-language, stateful surface:
- *
- * - The usage instructions are OURS, not upstream's: upstream promises a
- *   one-shot program ("runs as the body of an async function", value-less
- *   between calls), while a DASHR cell runs on a PERSISTENT kernel whose
- *   variables, imports, and definitions survive across `eval` calls.
- *   The prose here must never state the throwaway contract.
- * - No language table and no context-free renderer: DASHR renders Python
- *   only, and object shapes always render through the named-`TypedDict`
- *   path this module owns. (Upstream's exported `jsonSchemaToPy` degrades
- *   every object to `dict[str, Any]`; reusing it would lose the shape.)
- * - The bare-identifier rule, `camelCase` derivation, class-name capping
- *   and collision suffixing, `typing` import emission, and the
- *   deterministic lexicographic member order are ported near-verbatim: the
- *   parseability invariants (NFKC stability, reserved words, unprintable
- *   escapes, bracket-nesting cap) exist because the emitted block is the
- *   model's ONLY declaration of the tools, and a syntax error in it poisons
- *   the whole mode.
- * - renders one `tool.<name>(args) -> Output` member per tool — no `Tools`
- *   protocol and no `tools` singleton — matching the kernel's `tool`
- *   object holder. Which names may render as members is decided by
- *   {@link isFlatBindableName}, the one policy the renderer and the bridge
- *   share.
- * @module dashr-repl/py-sdk
- */
-/**
- * One tool as the SDK renderer sees it: the model-facing schema
- * (name/description/parameters) plus the tool's canonical output schema.
- * The caller (the presentation plugin) excludes `eval` itself and reads
- * both through the tool registry's public projection APIs.
- */
-interface DASHRSdkSchema {
-  /** Tool name as registered (may be exotic; the renderer routes non-bindable names to not-callable comments). */
-  readonly name: string;
-  /** Tool description, rendered as the method docstring. */
-  readonly description: string;
-  /** Validated JSON-Schema node for the arguments object. */
-  readonly parameters: unknown;
-  /** Validated JSON-Schema node for the canonical output value. */
-  readonly output: unknown;
-}
-/**
- * Whether a tool name can be emitted AND bound as a `tool` member — the ONE
- * policy shared by this renderer and the bridge's binding
- * loop (src/index.ts), so the catalog never promises a name the kernel does
- * not bind. Strictly narrower than the runtime's validation: the
- * language-portable identifier subset (`[A-Za-z_][A-Za-z0-9_]*`, ASCII — a
- * non-ASCII XID name is legal CPython but not portable, so the runtime
- * refuses it as a binding global and the catalog must not teach it), minus
- * every portable reserved word (ECMAScript ∪ Python — `type` and `match`
- * are legal Python but reserved on the seam), minus the seam's reserved
- * binding globals (`console`, dunders), minus underscore-leading names
- * (kernel-shim prefix plus the call-site hazards; not callable as taught
- * flat globals). The runtime's `validateBindings` remains the authoritative
- * backstop: everything this accepts, it accepts.
- */
-declare function isFlatBindableName(name: string): boolean;
-/**
- * Render the `dashr:tool-catalog` prompt section body from the registry
- * schemas: the cell-flavored usage instructions above, the
- * `ToolCallError` declaration, one named `TypedDict` per tool argument or
- * output object (and per nested object), and one
- * `tool.<name>(args: XArgs) -> XOutput` member per visible tool — no `Tools`
- * protocol, no `tools` singleton, every tool is a member of the `tool`
- * object exactly as the kernel binds it — inside one fenced
- * ```python block. The `typing` import line lists exactly the symbols the
- * render used (and is omitted entirely when none are).
- *
- * Deterministic — tools are emitted in lexicographic name order and class
- * declarations precede the function that references them in that same
- * order (nested classes before the parent that references them), so an
- * unchanged tool set produces byte-identical text across assemblies.
- *
- * Non-bindable names (reserved, exotic, or underscore-leading) render as
- * comment lines: they are registered upstream but NOT callable from cells,
- * and the comment keeps the signature and description visible instead of
- * silently dropping the tool.
- * @param schemas - the calling scope's visible tools (caller excludes
- *   `eval` and the masked delegation names).
- * @returns the complete section body.
- */
-declare function renderToolsSdkPy(schemas: readonly DASHRSdkSchema[]): string;
-/**
- * The `dashr:tool-catalog` section's presentation mode (design D4):
- * `'signatures'` renders one compact declaration line per visible tool
- * (the omp code-mode shape: `name(args: {…})` per line, argument and output
- * sketches abbreviated to depth 2 — the default, chosen for low-tier model
- * robustness); `'convention'` renders the one-sentence calling convention
- * alone (zero repetition, the A/B deployment experiment's other arm).
- * Both modes keep the output contract (each tool's canonical JSON output
- * shape) and the non-flat-name exception; neither presents a REPL binding
- * listing — the declaration lines themselves are the authoritative surface.
- */
-type ReplBridgeCatalogMode = 'signatures' | 'convention';
-/** The deployed presentation mode; flip to `'convention'` to ship arm A. */
-declare const REPL_BRIDGE_CATALOG_MODE: ReplBridgeCatalogMode;
-/**
- * Render the `dashr:tool-catalog` prompt section body as the REPL bridge
- * instructions (design D4/D5): the scripting-pad positioning and the
- * calling convention above, then — in the default `'signatures'` mode —
- * one compact declaration line per visible tool
- * (`tool.<name>(args: {…}) -> <output shape>`, omp code-mode shape with
- * the output contract kept), inside one fenced ```python block.
- * Non-bindable names (reserved, exotic, underscore-leading) are omitted
- * from the lines; the convention sentence above states that limit once.
- *
- * Deterministic — lines are emitted in lexicographic name order, so an
- * unchanged tool set produces byte-identical text across assemblies.
- * @param schemas - the calling scope's visible tools (the caller already
- *   excluded the transport and the wire-masked names).
- * @param mode - override the deployed {@link REPL_BRIDGE_CATALOG_MODE}
- *   (the two render states; tests exercise both).
- * @returns the complete section body.
- */
-declare function renderReplBridgeInstructions(schemas: readonly DASHRSdkSchema[], mode?: ReplBridgeCatalogMode): string;
-//#endregion
-export { renderReplBridgeInstructions as a, isFlatBindableName as i, REPL_BRIDGE_CATALOG_MODE as n, renderToolsSdkPy as o, ReplBridgeCatalogMode as r, DASHRSdkSchema as t };