better-dsh 0.2.3 → 0.2.4

package/lib/fs-aware/sandbox-plugin.js

@@ -0,0 +1,249 @@
+import { f as UrlSchemesError, t as buildFsLayerResolver } from "../wrap-JFjcWwZf.js";
+import { Context } from "@deepseek-ai/cordis";
+import { dirname, sep } from "node:path";
+import { stat } from "node:fs/promises";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { writableRoots } from "@deepseek-ai/dsh-sandbox";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+
+//#region node_modules/@deepseek-ai/dsh-fs-sandbox/lib/index.js
+/**
+* Path-containment mechanics for the filesystem sandbox. Canonical spellings
+* take the fast lexical path; filesystem identity supplies the conservative
+* fallback for alias-equivalent roots such as Windows 8.3 names and casing.
+* @module @deepseek-ai/dsh-fs-sandbox/containment
+*/
+const MISSING_CODES = new Set(["ENOENT", "ENOTDIR"]);
+function isMissing(error) {
+	const code = error.code;
+	return MISSING_CODES.has(code);
+}
+function comparablePath(path, caseSensitive) {
+	return caseSensitive ? path : path.toLowerCase();
+}
+function isLexicallyUnder(path, root, caseSensitive) {
+	const comparableTarget = comparablePath(path, caseSensitive);
+	const comparableRoot = comparablePath(root, caseSensitive);
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+async function statIfPresent(path) {
+	try {
+		return await stat(path, { bigint: true });
+	} catch (error) {
+		/* v8 ignore else -- a non-missing stat failure requires a host permission or I/O fault after resolve reached this ancestor. */
+		if (isMissing(error)) return void 0;
+		/* v8 ignore next -- requires a host permission or I/O fault after resolve already reached this ancestor. */
+		throw error;
+	}
+}
+function sameIdentity(left, right) {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+/**
+* Determine whether a canonical target is a writable root or lies beneath it.
+* The lexical fast path handles normal canonical spellings. When spellings
+* differ, walk the target's existing ancestors and compare filesystem identity
+* with the root; this recognizes Windows long-name/8.3 aliases and casing
+* without weakening containment to a textual approximation.
+* @param path - canonical target key, which may end in a missing suffix.
+* @param root - canonical writable root.
+* @param caseSensitive - whether lexical comparison preserves case; defaults
+*   to the host filesystem convention used by supported platforms.
+* @returns whether the target is the root or a descendant of it.
+*/
+async function isPathUnder(path, root, caseSensitive = process.platform !== "win32") {
+	if (isLexicallyUnder(path, root, caseSensitive)) return true;
+	const rootInfo = await statIfPresent(root);
+	if (!rootInfo) return false;
+	let ancestor = path;
+	while (true) {
+		const ancestorInfo = await statIfPresent(ancestor);
+		if (ancestorInfo && sameIdentity(ancestorInfo, rootInfo)) return true;
+		const parent = dirname(ancestor);
+		if (parent === ancestor) return false;
+		ancestor = parent;
+	}
+}
+/**
+* `SandboxedFileSystem`: the sandbox-enforcing implementation of the
+* `@deepseek-ai/dsh-fs` Service Definition. It extends `LocalFileSystem` so all
+* text-storage mechanics — resolve, stat, read/stream, list, the atomic
+* write and the read-match-write edit critical section — are the local
+* implementation's, verbatim; this package adds only the per-call POLICY fence
+* on the two mutations. Reads pass through untouched: every mode permits
+* reading.
+*
+* The fence is a policy check in TRUSTED code over a MODEL-CONTROLLED path,
+* NOT a kernel boundary — the operations are the seam's own (open, rename),
+* and only the target path is untrusted, so canonicalize-then-contain is the
+* complete answer to this surface. This is containment, not a security
+* boundary; kernel-grade isolation of untrusted CODE stays `ctx.shell`'s job
+* (`@deepseek-ai/dsh-bash-sandbox`). The residual
+* TOCTOU (an ancestor symlink swapped between the containment re-check and the
+* syscall) is narrowed by re-canonicalizing immediately before delegating and
+* is accepted for this threat model.
+*
+* Per-call policy: `read-only` denies every mutation; `workspace-write` allows
+* a mutation only when the target canonicalizes under the policy's workspace
+* root or a platform temp area from the shared `writableRoots` policy;
+* `danger-full-access` delegates unfenced. A denial throws the structured
+* `FS_SANDBOX_DENIED`.
+*
+* @module @deepseek-ai/dsh-fs-sandbox
+*/
+/**
+* Sandbox-enforcing filesystem backend. Registers as `ctx.fs` (loading it
+* INSTEAD OF `dsh-fs-local`, together with a `ctx.sandboxPolicy`, is the whole
+* swap — the model-facing tools are untouched). Its configured default mode is
+* the capability fact exposed by {@link sandboxMode}; `dsh-tool-fs` resolves
+* each session's mode and cwd into a policy for every mutation, while an
+* approved escalation may stamp a strictly wider mode for one call.
+*/
+var SandboxedFileSystem = class extends LocalFileSystem {
+	static inject = ["sandboxPolicy"];
+	defaultMode;
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.defaultMode = ctx.sandboxPolicy.defaultMode;
+	}
+	/** The deployment default mode — the capability fact the tool layer reads to advertise escalation. */
+	get sandboxMode() {
+		return this.defaultMode;
+	}
+	/**
+	* Fence the write by the per-call policy, then delegate to the inherited
+	* atomic write. See {@link checkedTarget}.
+	* @param target - the resolved target to write.
+	* @param content - the full new file content.
+	* @param expected - the write intent guarding the write; omit for unconditional.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the write outcome from the inherited backend.
+	*/
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		return super.writeText(await this.checkedTarget(target, sandboxPolicy), content, expected, signal);
+	}
+	/**
+	* Fence the edit by the per-call policy, then delegate to the inherited
+	* atomic edit. See {@link checkedTarget}.
+	* @param target - the resolved target to edit.
+	* @param edit - the literal search/replace request.
+	* @param expected - the version guard; omit for an unconditional edit.
+	* @param signal - aborts before atomic publication takes effect.
+	* @param sandboxPolicy - the per-call mode and workspace root; omit to use
+	*   the deployment fallback.
+	* @returns the edit outcome from the inherited backend.
+	*/
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
+	}
+	/**
+	* Enforce the per-call policy against `target` and return the EXACT target the
+	* mutation must use, so the checked identity is the mutated one (no
+	* check-here-write-there TOCTOU). `read-only` denies; `workspace-write`
+	* re-canonicalizes NOW (`resolve` realpaths the deepest existing ancestor,
+	* reflecting a concurrently swapped symlink), requires containment under a
+	* writable root, and returns THAT fresh target; `danger-full-access` returns
+	* the caller's target unfenced. Throws the structured `FS_SANDBOX_DENIED` on
+	* refusal — the tool layer maps it to the model-facing `[sandbox: …]` marker
+	* and the escalation hint.
+	*/
+	async checkedTarget(target, sandboxPolicy) {
+		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
+		const { mode } = policy;
+		if (mode === "danger-full-access") return target;
+		if (mode === "read-only") throw new FsError(`cannot write "${target.displayPath}": file access denied under read-only mode`, "FS_SANDBOX_DENIED");
+		const fresh = await this.resolve(target.displayPath);
+		let contained = false;
+		for (const root of writableRoots(policy)) if (await isPathUnder(fresh.targetKey, root)) {
+			contained = true;
+			break;
+		}
+		if (!contained) throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
+		return fresh;
+	}
+};
+
+//#endregion
+//#region src/fs-aware/sandbox-plugin.ts
+/** Scheme prefix test — mirrors the resolver's own grammar. */
+function isSchemePath(path) {
+	return /^[a-z][a-z0-9]*:\/\//.test(path);
+}
+/** Session-layer schemes are excluded from FS-layer resolution (design D2). */
+function isSessionLayerScheme(path) {
+	return path.startsWith("ctx://") || path.startsWith("agent://") || path.startsWith("skill://");
+}
+function sessionLayerError(url) {
+	if (url.startsWith("skill://")) return new UrlSchemesError("CTX_SESSION_LAYER", `${url}: session-layer scheme — skill discovery (which roots load, scan depth, layered scope merge) is the host skill provider's business logic and resolves only against a calling agent, which the filesystem layer does not have. Load skills with the native \`skill\` tool; grep/glob with path=skill://… keep working through the tool layer`);
+	return new UrlSchemesError("CTX_SESSION_LAYER", `${url}: session-layer scheme — read it through the read tool (the session-layer resolver environment carries the live agent this filesystem layer does not have)`);
+}
+const Base = SandboxedFileSystem;
+var FsAwareSandboxFileSystem = class extends Base {
+	static inject = [
+		"sandboxPolicy",
+		"settings",
+		"agents"
+	];
+	resolver;
+	schemeResolution;
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.schemeResolution = config?.urlSchemes !== false;
+		this.resolver = this.buildResolver(ctx);
+	}
+	/**
+	* FS-layer resolver — the SHARED builder from `wrap.ts` (design D2). One
+	* registration source for both FS consumers: this backend and the instance
+	* wrap. (A private duplicate here once drifted — a doubled `dsh` register
+	* and a literal `'http'` that would silently drop `https` if this backend
+	* were ever the outermost layer.) The `ctx`/`agent` handlers it registers
+	* are unreachable here: session-layer schemes are guarded before resolve.
+	*/
+	buildResolver(ctx) {
+		return buildFsLayerResolver({ settings: ctx.settings }, this);
+	}
+	/** FS-layer resolver env: no live agent — session-layer schemes are excluded upstream. */
+	envFor(url) {
+		return {
+			fs: this,
+			rawUrl: url
+		};
+	}
+	async resolve(path, opts) {
+		if (!this.schemeResolution || !isSchemePath(path)) return super.resolve(path, opts);
+		if (isSessionLayerScheme(path)) throw sessionLayerError(path);
+		await this.resolver.resolve(this.envFor(path), path);
+		return {
+			targetKey: path,
+			displayPath: path
+		};
+	}
+	async stat(target, signal) {
+		if (!this.schemeResolution || !isSchemePath(target.targetKey)) return super.stat(target, signal);
+		if (isSessionLayerScheme(target.targetKey)) throw sessionLayerError(target.targetKey);
+		return {
+			type: "file",
+			size: (await this.resolver.resolve(this.envFor(target.targetKey), target.targetKey)).length
+		};
+	}
+	async readText(target, signal) {
+		if (!this.schemeResolution || !isSchemePath(target.targetKey)) return super.readText(target, signal);
+		if (isSessionLayerScheme(target.targetKey)) throw sessionLayerError(target.targetKey);
+		return this.resolver.resolve(this.envFor(target.targetKey), target.targetKey);
+	}
+	async writeText(target, ...rest) {
+		if (this.schemeResolution && isSchemePath(target.targetKey)) throw new UrlSchemesError("FS_VIRTUAL_READONLY", `cannot write "${target.targetKey}": scheme resources are read-only at the filesystem layer`);
+		return super.writeText(target, ...rest);
+	}
+	async editText(target, ...rest) {
+		if (this.schemeResolution && isSchemePath(target.targetKey)) throw new UrlSchemesError("FS_VIRTUAL_READONLY", `cannot edit "${target.targetKey}": scheme resources are read-only at the filesystem layer`);
+		return super.editText(target, ...rest);
+	}
+};
+
+//#endregion
+export { FsAwareSandboxFileSystem as default };

package/lib/index.d.ts

@@ -1,9 +1,8 @@
-import { t as DASHRSdkSchema } from "./py-sdk-BCaOGYz7.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { ToolDefinition, ToolExecutionInput, ToolRunContext, ToolRuntime } from "@deepseek-ai/dsh-tools";
 import { ContentBlock, HarnessError } from "@deepseek-ai/dsh-llm";
-import { ScopeKey, Scoped } from "@deepseek-ai/dsh-scope";
+import { Scoped } from "@deepseek-ai/dsh-scope";
 import { Agent } from "@deepseek-ai/dsh-agent";
 
 //#region src/vendored/types.d.ts
@@ -547,15 +546,22 @@ type ToolCallId = ToolExecutionInput['callId'];
 interface WebTrustConfig {
   /** Hostnames this operator declares their own devices' pages run on. */
   trustedPageAuthorities?: readonly string[];
-  /** Mobile responsiveness knobs (client half consumes via page global). */
   mobile?: {
     enabled?: boolean;
-    breakpoint?: number;
     swipeDistancePx?: number;
     dominanceRatio?: number;
     leftEdgeBandPx?: number;
     rightZoneRatio?: number;
     swipeVelocityPxPerMs?: number;
+    /**
+     * iOS focus auto-zoom suppression mode (change
+     * `2026-09-03-ios-focus-zoom-suppression`): `'meta'` (default) rewrites
+     * the viewport meta on iOS-class narrow viewports; `'off'` is the escape
+     * hatch. `'font'` (16px floor, solution A) is a RESERVED value slot,
+     * deliberately not in the schema enum — unimplemented values fail loud
+     * at config load rather than no-op silently.
+     */
+    zoomGuard?: 'meta' | 'off';
   };
 }
 //#endregion
@@ -571,6 +577,10 @@ declare const inject: string[];
 /** Plugin config. */
 interface Config extends Config$1 {
   maxParallelSubCalls?: number;
+  /** URL scheme resolution (read/write/grep/glob scheme branches + `ctx://`). */
+  urlSchemes?: boolean;
+  /** Hashline feature: read anchors + the `edit`/`undo` tool family. */
+  hashline?: boolean;
   /** Page hostnames this operator declares their own (web-trust boot script). */
   trustedPageAuthorities?: string[];
   /** Mobile responsiveness knobs (delivered to the client half as a page global). */
@@ -596,6 +606,11 @@ declare const EVAL_NAME = "eval";
  * (`modelSelectionSettings: true`) lands on the agent's OWN layer, outside
  * registry restriction reach, so it stays visible on every surface and the
  * control prompt annotates it as an alias of the `agent` delegation tool.
+ * `skill` was REMOVED from this list (2026-09-12, user ruling): the native
+ * skill tool stays visible and self-surfaces its session catalog
+ * (`<available_skills>` is gated on the tool's registry visibility — masking
+ * the tool silenced the catalog). dashr's dual pipeline keeps `read
+ * skill://<name>` as the addressing form alongside native invocation.
  * own URL wrappers) is exempt from restrictions by construction — the
  * capability it carries stays reachable through the captured-definition
  * bridges below, never through the masked name.
@@ -609,10 +624,6 @@ declare const MASKED_TOOL_NAMES: ReadonlySet<string>;
  * bridges that read captured definitions.
  */
 declare const WIRE_MASKED_NAMES: ReadonlySet<string>;
-/** The `dashr:control-prompt` section order: the FIRST section in the 100–199 tool-guidance band, so the cell paradigm is taught before the Tool Catalog renders its signatures. */
-declare const CONTROL_SECTION_ORDER = 100;
-/** The `dashr:tool-catalog` section order: the 100–199 tool-guidance band's SDK position, matching upstream `tools:sdk`. */
-declare const SDK_SECTION_ORDER = 150;
 /**
  * The `dashr:escalation-guidance` CONTEXT order: sits inside the runtime-context snapshot
  * band between upstream `approval:policy` (115) and `subagent:delegation` (120) — the
@@ -663,7 +674,7 @@ declare module '@deepseek-ai/cordis' {
     /**
      * Allow a listener to replace content in the DURABLE LOG COPY of one
      * `eval` sub-dispatch outcome before the bridge appends its
-     * `tool/code-dispatch` event. `next()` keeps the content unchanged; a
+     * `tool/ptc-dispatch` event. `next()` keeps the content unchanged; a
      * listener may return replacement blocks (e.g. the spill policy's preview
      * + locator for an oversized text result). Scope-filtered dispatch
      * (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that
@@ -706,7 +717,7 @@ interface RunCellBridgeOptions {
  * in the module doc. Sub-calls ride the registry's exported staged scheduler
  * (`prepare`/`dispatch`/`finalize`/`finish`) under the native concurrency
  * contract; each sub-dispatch is logged for reconstruction
- * (`tool/code-dispatch-start` / `tool/code-dispatch`) while only the outer
+ * (`tool/ptc-dispatch-start` / `tool/ptc-dispatch`) while only the outer
  * curated result enters model history.
  * @param registry - the host tool registry (sub-calls go through its staged
  *   scheduler, bindings cover its registered tools).
@@ -714,17 +725,6 @@ interface RunCellBridgeOptions {
  * @returns the registry-ready definition.
  */
 declare function createRunCellTool(registry: ToolRuntime, options: RunCellBridgeOptions): ToolDefinition;
-/**
- * Collect one calling scope's bridge-declaration schemas through the
- * registry's public projection APIs: `schemas(scope)` for the model-facing
- * view (scoped tools join, restrictions apply — the wire mask is a
- * registry-level restriction installed at session-start, so every masked
- * name is ALREADY absent from this projection; no second name filter
- * exists to drift), `get(name, scope)` for the canonical output schema,
- * snapshotted so a live definition cannot mutate under the render. `eval`
- * itself is excluded — it is the transport, not a binding.
- */
-declare function collectSdkSchemas(registry: ToolRuntime, scope?: ScopeKey): DASHRSdkSchema[];
 declare function apply(ctx: Context, config: Config): void;
 declare const _default: {
   name: string;
@@ -733,4 +733,4 @@ declare const _default: {
   apply: typeof apply;
 };
 //#endregion
-export { CONTROL_SECTION_ORDER, Config, DASHRRunFailedError, DashrRuntime, ESCALATION_GUIDANCE_ORDER, EVAL_NAME, MASKED_TOOL_NAMES, ReplDispatchLog, ReplRuntime, RunCellBridgeOptions, type Config$1 as RuntimeConfig, SDK_SECTION_ORDER, WIRE_MASKED_NAMES, apply, collectSdkSchemas, createRunCellTool, _default as default, inject, name, resolveMaxParallelSubCalls };
+export { Config, DASHRRunFailedError, DashrRuntime, ESCALATION_GUIDANCE_ORDER, EVAL_NAME, MASKED_TOOL_NAMES, ReplDispatchLog, ReplRuntime, RunCellBridgeOptions, type Config$1 as RuntimeConfig, WIRE_MASKED_NAMES, apply, createRunCellTool, _default as default, inject, name, resolveMaxParallelSubCalls };