@struktoai/mirage-dsh 0.0.1-alpha.1

package/dist/fs-CuiUEA7A.d.ts

@@ -0,0 +1,54 @@
+import { Context } from '@deepseek-ai/cordis';
+import { FileSystem, FsTarget, FsInfo, FsPathInfo, FsDirEntry, FsWriteIntent, FsWriteOutcome, FsEditRequest, FsVersion, FsEditOutcome } from '@deepseek-ai/dsh-fs';
+
+/** Configuration for the mirage filesystem backend. */
+interface MirageFsConfig {
+    /** Virtual base directory for relative paths. Defaults to `/`. */
+    cwd?: string;
+    /** Exclusive byte limit on each overwrite-diff side. Defaults to 10 MiB. */
+    diffBasisMaxBytes?: number;
+}
+/**
+ * Mirage-backed implementation of `ctx.fs`. Targets are canonical virtual
+ * paths (namespace symlinks followed), every operation walks the workspace
+ * op door — session grants, admission policies, cache read-through and
+ * post-write invalidation all fire exactly as they do for a shell command —
+ * and `processPath` answers in the same virtual path space the mirage shell
+ * executes in, so the two providers share one execution world.
+ */
+declare class MirageFileSystem extends FileSystem {
+    static readonly inject: string[];
+    private fsOps;
+    private readonly cwd;
+    private readonly diffBasisMaxBytes;
+    private readonly locks;
+    constructor(ctx: Context, config?: MirageFsConfig);
+    private ops;
+    private get links();
+    private normalize;
+    private follow;
+    private withLock;
+    resolve(path: string, opts?: {
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<FsTarget>;
+    processPath(target: FsTarget): string;
+    fileUrl(target: FsTarget): string;
+    contains(parent: FsTarget, child: FsTarget): boolean;
+    stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>;
+    lstat(path: string, opts?: {
+        cwd?: string;
+    }, signal?: AbortSignal): Promise<FsPathInfo | undefined>;
+    readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
+    streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
+    listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
+    private dirEntry;
+    writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>;
+    private diffBasis;
+    private versionAfterWrite;
+    editText(target: FsTarget, edit: FsEditRequest, expected?: {
+        version: FsVersion;
+    }, signal?: AbortSignal): Promise<FsEditOutcome>;
+}
+
+export { MirageFileSystem as M, type MirageFsConfig as a };

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { M as MirageConfig, a as MirageMount, b as MirageMountBlock, c as MirageRuntimeBlock, d as MirageService } from './service-CxFYAvoV.js';
+export { M as MirageFileSystem, a as MirageFsConfig } from './fs-CuiUEA7A.js';
+export { M as MirageShellConfig, a as MirageShellExecutor } from './shell-B0N_jppN.js';
+import '@deepseek-ai/cordis';
+import '@struktoai/mirage-core';
+import '@struktoai/mirage-node';
+import '@deepseek-ai/dsh-fs';
+import '@deepseek-ai/dsh-shell';

package/dist/index.js

@@ -0,0 +1,16 @@
+import {
+  MirageFileSystem
+} from "./chunk-C67TSSYB.js";
+import {
+  MirageService
+} from "./chunk-J6F4OX6Z.js";
+import {
+  MirageShellExecutor
+} from "./chunk-ZSZVHBSL.js";
+import "./chunk-CATVBGGR.js";
+export {
+  MirageFileSystem,
+  MirageService,
+  MirageShellExecutor
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/plugin/fs.d.ts

@@ -0,0 +1,3 @@
+export { M as default } from '../fs-CuiUEA7A.js';
+import '@deepseek-ai/cordis';
+import '@deepseek-ai/dsh-fs';

package/dist/plugin/fs.js

@@ -0,0 +1,8 @@
+import {
+  MirageFileSystem
+} from "../chunk-C67TSSYB.js";
+import "../chunk-CATVBGGR.js";
+export {
+  MirageFileSystem as default
+};
+//# sourceMappingURL=fs.js.map

package/dist/plugin/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/plugin/service.d.ts

@@ -0,0 +1,4 @@
+export { d as default } from '../service-CxFYAvoV.js';
+import '@deepseek-ai/cordis';
+import '@struktoai/mirage-core';
+import '@struktoai/mirage-node';

package/dist/plugin/service.js

@@ -0,0 +1,7 @@
+import {
+  MirageService
+} from "../chunk-J6F4OX6Z.js";
+export {
+  MirageService as default
+};
+//# sourceMappingURL=service.js.map

package/dist/plugin/service.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/plugin/shell.d.ts

@@ -0,0 +1,3 @@
+export { a as default } from '../shell-B0N_jppN.js';
+import '@deepseek-ai/cordis';
+import '@deepseek-ai/dsh-shell';

package/dist/plugin/shell.js

@@ -0,0 +1,8 @@
+import {
+  MirageShellExecutor
+} from "../chunk-ZSZVHBSL.js";
+import "../chunk-CATVBGGR.js";
+export {
+  MirageShellExecutor as default
+};
+//# sourceMappingURL=shell.js.map

package/dist/plugin/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/service-CxFYAvoV.d.ts

@@ -0,0 +1,91 @@
+import { Service, Context } from '@deepseek-ai/cordis';
+import { MountSpec } from '@struktoai/mirage-core';
+import { Workspace, Mount, NodeWorkspaceOptions } from '@struktoai/mirage-node';
+
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        mirage: MirageService;
+    }
+}
+/**
+ * A declarative mount, YAML-friendly: the resource is named by its
+ * registry type and built through `buildResource`, so a dsh bundle
+ * patch can mount anything without holding a live instance. Told apart
+ * from a live `Mount` by the type of `resource`: a string names a
+ * registry entry, an object is the instance itself.
+ */
+interface MirageMountBlock {
+    /** Resource registry name (`ram`, `s3`, `slack`, `redis`, ...). */
+    resource: string;
+    /** Mount mode: `read`, `write`, or `exec`. Omitted = the workspace default. */
+    mode?: string;
+    /** Resource constructor config, passed to the registry factory. */
+    config?: Record<string, unknown>;
+}
+/** One mount entry: a live spec or instance, or a declarative block. */
+type MirageMount = MountSpec | Mount | MirageMountBlock;
+/** A runtime entry, YAML-friendly: a name, or a name with captures. */
+interface MirageRuntimeBlock {
+    /** Runtime registry name (`monty`, `pyodide`, `quickjs`, ...). */
+    name: string;
+    /** Command words this runtime captures (e.g. `['python', 'python3']`). */
+    captures?: string[];
+}
+/**
+ * Configuration for the shared mirage execution world. Exactly one of
+ * `workspace` (adopt a live workspace the embedder owns and closes) or
+ * `mounts` (construct a workspace here; the service closes it when its
+ * plugin unloads) must be given.
+ */
+interface MirageConfig {
+    /** A live workspace to adopt; its lifecycle stays with the embedder. */
+    workspace?: Workspace;
+    /** Mounts for a service-owned workspace, keyed by mount prefix. */
+    mounts?: Record<string, MirageMount>;
+    /**
+     * Runtimes for a service-owned workspace, built via `buildRuntime`.
+     * The YAML-friendly twin of `workspaceOptions.runtimes`; pass one or
+     * the other, not both.
+     */
+    runtimes?: (string | MirageRuntimeBlock)[];
+    /** Options forwarded to the service-owned workspace's constructor. */
+    workspaceOptions?: NodeWorkspaceOptions;
+}
+/**
+ * The one mirage `Workspace` behind every mirage-backed dsh provider
+ * (`ctx.mirage`, mirroring how `ctx.e2b` owns one sandbox for the E2B
+ * adapters). `MirageFileSystem` and `MirageShellExecutor` both inject it,
+ * which is what keeps `ctx.fs` targets and `ctx.shell` commands in one
+ * execution world: a `processPath` handed to the shell resolves there.
+ *
+ * Construction with live resources is synchronous; a declarative mount
+ * block defers to `buildResource`, so consumers await `ready` (the
+ * adapters do) and `workspace` throws until it resolves, mirroring how
+ * the E2B service owner exposes its sandbox.
+ */
+declare class MirageService extends Service {
+    static readonly provide = "mirage";
+    /** Resolves to the shared workspace once every mount is built. */
+    readonly ready: Promise<Workspace>;
+    private built;
+    private readonly plannedRuntimes;
+    constructor(ctx: Context, config?: MirageConfig);
+    /** The live workspace; throws until `ready` resolves. */
+    get workspace(): Workspace;
+    /**
+     * True while every runtime in the world reaches only the vfs
+     * (`Runtime.reach`), meaning the workspace dispatch is the single
+     * gate for anything the agent can execute: every effect passes
+     * mount modes, session grants, and policy before touching the real
+     * backend behind a mount. The default world qualifies, and so do
+     * the bridged engines, while the host `local` python or a remote
+     * sandbox can act around the gate. Answers before `ready` from the
+     * constructor-resolved entries (mounts resolve asynchronously,
+     * runtimes never do) and from the live workspace afterwards, so a
+     * later `addRuntime` is seen.
+     */
+    get vfsOnly(): boolean;
+    private open;
+}
+
+export { type MirageConfig as M, type MirageMount as a, type MirageMountBlock as b, type MirageRuntimeBlock as c, MirageService as d };

package/dist/shell-B0N_jppN.d.ts

@@ -0,0 +1,108 @@
+import { Context } from '@deepseek-ai/cordis';
+import { ShellExecutor, ShellExecRequest, ShellExecSpec, ShellRunResult, ShellProcess } from '@deepseek-ai/dsh-shell';
+
+/** Configuration for the mirage shell executor. */
+interface MirageShellConfig {
+    /**
+     * Default working directory for commands. Defaults to `/`. With
+     * `sessionId` it instead seeds the bound session's initial cwd, and the
+     * session's own cwd is the default from then on.
+     */
+    workdir?: string;
+    /** Default foreground timeout in milliseconds. Defaults to 120000. */
+    defaultTimeoutMs?: number;
+    /** Upper cap on any requested timeout. Defaults to 600000. */
+    maxTimeoutMs?: number;
+    /** Default stdout capture budget in bytes. Defaults to 200000. */
+    stdoutMaxBytes?: number;
+    /** stderr capture budget in bytes. Defaults to 64000. */
+    stderrMaxBytes?: number;
+    /**
+     * Bind every command to this named workspace session. By default each
+     * command runs in an ephemeral fork of the workspace's default session,
+     * so nothing persists between calls, which is the one-shot contract of
+     * dsh's bash tool. With a session bound, `cd`, `export`, and function
+     * definitions persist across calls, the persistent-shell contract. The
+     * session is created on first use if the workspace does not have it; an
+     * existing session is adopted as is. A spec carrying an explicit
+     * `workdir` or `env` still runs as a one-call subshell of the bound
+     * session, per mirage's `ExecuteOptions` semantics.
+     */
+    sessionId?: string;
+    /**
+     * When set, a background command whose streamed output overruns its
+     * delta budget spills its full stdout and stderr to files under this
+     * workspace directory, and `readOutput()` points at them so a reader
+     * can recover what the delta dropped. The directory is a workspace
+     * path (e.g. `/tmp` on a ram mount), so the agent reads the spill
+     * through the same VFS as everything else; the writes go through the
+     * workspace, so they appear in history like any other write. Unset
+     * (the default) means no spill: output that overruns is simply
+     * flagged `lossy`, the honest "no safe path available" answer.
+     */
+    spillDir?: string;
+}
+/**
+ * Mirage-backed implementation of `ctx.shell`: `run` executes the command
+ * line with mirage's own shell (coreutils-faithful commands, installed
+ * CLIs, the policy layer) against the shared `ctx.mirage` workspace, so a
+ * path from `ctx.fs` means the same file here. There is no OS process
+ * behind a command: `signal` in results is a compatibility value for kills,
+ * and abort/timeout act cooperatively at the executor's own boundaries.
+ *
+ * Every command runs in an ephemeral fork of the workspace's default
+ * session, so no shell state survives from one call to the next, matching
+ * the one-shot contract of dsh's bash tool. Configuring a `sessionId`
+ * binds all commands to one named session instead, whose cwd, exports,
+ * and functions persist across calls.
+ */
+declare class MirageShellExecutor extends ShellExecutor {
+    static readonly inject: string[];
+    private readonly workdir;
+    private readonly defaultTimeoutMs;
+    private readonly maxTimeoutMs;
+    private readonly stdoutMaxBytes;
+    private readonly stderrMaxBytes;
+    private readonly sessionId;
+    private readonly spillDir;
+    private sessionReady;
+    constructor(ctx: Context, config?: MirageShellConfig);
+    private workspace;
+    private newSpill;
+    /**
+     * With every runtime in the world reaching only the vfs
+     * (`ctx.mirage.vfsOnly`), the workspace dispatch is the single gate
+     * for anything a command can do, so this executor behaves like a
+     * workspace-write sandbox: reads and writes land only where mounts
+     * (and their modes) allow. Declaring it lets sandbox-aware plugins
+     * (dsh's permission presets) compose over this executor. A world
+     * holding a runtime with doors around the gate (the host `local`
+     * python, a remote sandbox) voids that claim, so this answers
+     * undefined then (the base contract's "does not sandbox") and those
+     * plugins refuse to compose instead of trusting a lie.
+     */
+    get sandboxMode(): ShellExecutor['sandboxMode'];
+    /**
+     * The sandbox facts to stamp on this run's result and process handle,
+     * or undefined when the world is not fully workspace-bound (no claim).
+     *
+     * `enforcement` is 'full': when every runtime reaches only the vfs, the
+     * workspace gate cannot be bypassed, so unlike an OS sandbox on an older
+     * kernel there is no promised effect it fails to govern. `denied` is
+     * false because mirage has no out-of-band denial channel: a refused write
+     * (a read-only mount) fails in-band as an ordinary command error with a
+     * nonzero exit, the way EROFS would, not as a separate sandbox verdict,
+     * so there is nothing here to distinguish from the command's own failure.
+     * `runnerFailed` is false because the workspace executor is the runner
+     * and a failure to run surfaces as a rejected/aborted execution, not a
+     * runner that never started.
+     */
+    private sandboxInfo;
+    resolve(request: ShellExecRequest): ShellExecSpec;
+    private ensureSession;
+    private provisionSession;
+    run(spec: ShellExecSpec): Promise<ShellRunResult>;
+    start(spec: ShellExecSpec): ShellProcess;
+}
+
+export { type MirageShellConfig as M, MirageShellExecutor as a };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@struktoai/mirage-dsh",
+  "version": "0.0.1-alpha.1",
+  "description": "DeepSeek Harness (dsh) providers backed by a mirage workspace: ctx.fs and ctx.shell over mounted resources",
+  "homepage": "https://github.com/strukto-ai/mirage#readme",
+  "bugs": {
+    "url": "https://github.com/strukto-ai/mirage/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/strukto-ai/mirage.git",
+    "directory": "typescript/packages/dsh"
+  },
+  "license": "Apache-2.0",
+  "author": "Zecheng Zhang <zecheng@strukto.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./service": {
+      "types": "./dist/plugin/service.d.ts",
+      "import": "./dist/plugin/service.js"
+    },
+    "./fs": {
+      "types": "./dist/plugin/fs.d.ts",
+      "import": "./dist/plugin/fs.js"
+    },
+    "./shell": {
+      "types": "./dist/plugin/shell.d.ts",
+      "import": "./dist/plugin/shell.js"
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "dist",
+    "cordis.patch.yml"
+  ],
+  "dependencies": {
+    "@struktoai/mirage-node": "0.0.5-alpha.1",
+    "@struktoai/mirage-core": "0.0.5-alpha.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-fs": "0.0.1-rc.1",
+    "@deepseek-ai/dsh-shell": "0.0.1-rc.5"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-fs": "0.0.1-rc.1",
+    "@deepseek-ai/dsh-shell": "0.0.1-rc.5",
+    "tsup": "^8.5.0",
+    "typescript": "^6.0.0",
+    "vitest": "^3.2.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}