@lamplitisles/dsh-nanocodex 0.1.0-beta.0

package/vendor/nanocodex-tools/tools/execution-contract.d.mts

@@ -0,0 +1,5 @@
+export const EXEC_COMMAND_PARAMETERS: Readonly<Record<string, unknown>>;
+export const WRITE_STDIN_PARAMETERS: Readonly<Record<string, unknown>>;
+export const EXECUTION_OUTPUT_SCHEMA: Readonly<Record<string, unknown>>;
+export const MACHINE_PREVIEW_PARAMETERS: Readonly<Record<string, unknown>>;
+export const PREVIEW_OUTPUT_SCHEMA: Readonly<Record<string, unknown>>;

package/vendor/nanocodex-tools/tools/execution-contract.mjs

@@ -0,0 +1,63 @@
+export const EXEC_COMMAND_PARAMETERS = Object.freeze({
+  type: "object",
+  properties: {
+    cmd: { type: "string", description: "Shell command to execute." },
+    justification: { type: "string", description: "User-facing approval question for `require_escalated`; omit otherwise." },
+    workdir: { type: "string", description: "Working directory for the command." },
+    shell: { type: "string", description: "Shell binary to launch. Defaults to the selected hand's shell." },
+    login: { type: "boolean", description: "True runs with login-shell semantics when supported." },
+    tty: { type: "boolean", description: "True allocates a PTY when supported." },
+    yield_time_ms: { type: "number", description: "Wait before yielding output. Defaults to 10000 ms." },
+    max_output_tokens: { type: "number", description: "Output token budget. Defaults to 10000 tokens." },
+    prefix_rule: { type: "array", items: { type: "string" }, description: "Reusable approval prefix for `require_escalated`." },
+    sandbox_permissions: { type: "string", enum: ["use_default", "require_escalated"], description: "Per-command sandbox policy request." },
+  },
+  required: ["cmd"],
+  additionalProperties: false,
+});
+
+export const WRITE_STDIN_PARAMETERS = Object.freeze({
+  type: "object",
+  properties: {
+    session_id: { type: "number", description: "Session identifier returned by exec_command." },
+    chars: { type: "string", description: "Characters to write; omit or pass an empty string to poll." },
+    yield_time_ms: { type: "number", description: "Wait before yielding more output." },
+    max_output_tokens: { type: "number", description: "Output token budget." },
+  },
+  required: ["session_id"],
+  additionalProperties: false,
+});
+
+export const EXECUTION_OUTPUT_SCHEMA = Object.freeze({
+  type: "object",
+  properties: {
+    chunk_id: { type: "string", description: "Chunk identifier included when the response reports one." },
+    wall_time_seconds: { type: "number", description: "Elapsed wall time spent waiting for output in seconds." },
+    exit_code: { type: "number", description: "Process exit code when the command finished during this call." },
+    session_id: { type: "number", description: "Session identifier to pass to write_stdin when the process is still running." },
+    original_token_count: { type: "number", description: "Approximate token count before output truncation." },
+    output: { type: "string", description: "Command output text, possibly truncated." },
+  },
+  required: ["wall_time_seconds", "output"],
+  additionalProperties: false,
+});
+
+export const MACHINE_PREVIEW_PARAMETERS = Object.freeze({
+  type: "object",
+  properties: {
+    port: { type: "integer", minimum: 1024, maximum: 65_535, not: { const: 3_000 } },
+  },
+  required: ["port"],
+  additionalProperties: false,
+});
+
+export const PREVIEW_OUTPUT_SCHEMA = Object.freeze({
+  type: "object",
+  properties: {
+    port: { type: "integer" },
+    url: { type: "string" },
+    persistent: { type: "boolean" },
+  },
+  required: ["port", "url", "persistent"],
+  additionalProperties: false,
+});

package/vendor/nanocodex-tools/tools/hostedCatalog.d.mts

@@ -0,0 +1,20 @@
+import type { NamedTool } from "./types.mjs";
+
+export type HostedToolCatalogEntry = Readonly<{
+  provider: string;
+  remote_name: string;
+  definition: Readonly<Record<string, unknown>>;
+  parallel_safe: boolean;
+  summary?: string | undefined;
+  timeout_ms: number;
+}>;
+
+export type { HostedMachine } from "./hostedMachine.mjs";
+
+export function hostedAppToolCatalog(
+  tools: readonly NamedTool[] | Readonly<Record<string, unknown>>,
+  provider?: string,
+): readonly HostedToolCatalogEntry[];
+
+export function hostedCatalog(catalog: readonly HostedToolCatalogEntry[]): readonly HostedToolCatalogEntry[];
+export function hostedToolCatalogDigest(catalog: readonly HostedToolCatalogEntry[]): Promise<`0x${string}`>;

package/vendor/nanocodex-tools/tools/hostedCatalog.mjs

@@ -0,0 +1,67 @@
+import { resolveTools } from "../runtime/tool-configuration.mjs";
+import { ToolRouter, toolMapSource } from "../runtime/tool-router.mjs";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const CATALOG_DIGEST_DOMAIN = "nanocodex-app-tool-catalog-v1\0";
+
+/** Materializes the exact reverse-tool catalog emitted for app-local named tools. */
+export function hostedAppToolCatalog(tools, provider = "javascript") {
+  const resolved = resolveTools(tools ?? [], { defaultSubagents: false });
+  if (resolved.subagents) throw new TypeError("hosted app tool catalogs do not accept subagents");
+  const router = new ToolRouter();
+  if (Object.keys(resolved.tools).length > 0) {
+    router.addSource(toolMapSource("custom", resolved.tools, { kind: "cloud" }));
+  }
+  return hostedCatalog(router.catalog(provider));
+}
+
+/** Normalizes an admitted router catalog to the socket-owned wire contract. */
+export function hostedCatalog(catalog) {
+  if (!Array.isArray(catalog) || catalog.length > 256) {
+    throw new RangeError("tool attachment catalogs contain at most 256 tools");
+  }
+  return Object.freeze(catalog.map((entry) => Object.freeze({
+    provider: entry.provider,
+    remote_name: entry.remote_name,
+    definition: hostedDefinition(entry.definition),
+    parallel_safe: entry.parallel_safe === true,
+    ...(entry.summary === undefined ? {} : { summary: entry.summary }),
+    timeout_ms: entry.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+  })));
+}
+
+/** Returns the exact domain-separated digest signed into a Connect grant. */
+export async function hostedToolCatalogDigest(catalog) {
+  const normalized = hostedCatalog(catalog);
+  const canonical = canonicalJson([...normalized]
+    .sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right))));
+  const bytes = new TextEncoder().encode(`${CATALOG_DIGEST_DOMAIN}${canonical}`);
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+  return `0x${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function hostedDefinition(definition) {
+  if (definition.type === "custom") return Object.freeze({
+    type: "custom", name: definition.name, description: definition.description, format: definition.format,
+  });
+  return Object.freeze({
+    type: "function",
+    name: definition.name,
+    description: definition.description ?? "Application-defined tool.",
+    strict: definition.strict ?? false,
+    parameters: definition.parameters ?? { type: "object", additionalProperties: true },
+    ...(definition.output_schema === undefined ? {} : { output_schema: definition.output_schema }),
+  });
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => (
+      `${JSON.stringify(key)}:${canonicalJson(value[key])}`
+    )).join(",")}}`;
+  }
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined) throw new TypeError("hosted tool catalogs must be JSON-serializable");
+  return encoded;
+}

package/vendor/nanocodex-tools/tools/hostedMachine.d.mts

@@ -0,0 +1,10 @@
+export type HostedMachine = Readonly<{
+  id: string;
+  name: string;
+  workspace: string;
+  capabilities: readonly string[];
+}>;
+
+export function normalizeHostedMachines(
+  machines?: readonly HostedMachine[],
+): readonly HostedMachine[];

package/vendor/nanocodex-tools/tools/hostedMachine.mjs

@@ -0,0 +1,56 @@
+import { utf8ByteLength } from "../runtime/utf8.mjs";
+
+const MAX_MACHINES = 1;
+const MAX_MACHINE_CAPABILITIES = 64;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,122}$/;
+const CAPABILITY = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
+const normalizedSnapshots = new WeakSet();
+
+/** Normalizes the non-secret machines represented by one attached tool host. */
+export function normalizeHostedMachines(machines = []) {
+  if (normalizedSnapshots.has(machines)) return machines;
+  if (!Array.isArray(machines) || machines.length > MAX_MACHINES) {
+    throw new RangeError(`tool attachments describe at most ${MAX_MACHINES} machines`);
+  }
+  const ids = new Set();
+  const normalized = Object.freeze(machines.map((machine, index) => {
+    if (!machine || typeof machine !== "object" || Array.isArray(machine)) {
+      throw new TypeError(`machines[${index}] must be an object`);
+    }
+    const allowed = new Set(["id", "name", "workspace", "capabilities"]);
+    for (const key of Object.keys(machine)) {
+      if (!allowed.has(key)) throw new TypeError(`machines[${index}] contains unsupported field ${key}`);
+    }
+    if (typeof machine.id !== "string" || !IDENTIFIER.test(machine.id)) {
+      throw new TypeError(`machines[${index}].id must be a safe identifier of at most 123 bytes`);
+    }
+    if (ids.has(machine.id)) throw new TypeError(`duplicate machine id: ${machine.id}`);
+    ids.add(machine.id);
+    if (typeof machine.name !== "string" || !machine.name.trim() || utf8ByteLength(machine.name) > 128) {
+      throw new TypeError(`machines[${index}].name must be 1-128 UTF-8 bytes`);
+    }
+    if (typeof machine.workspace !== "string" || !machine.workspace.trim()
+      || utf8ByteLength(machine.workspace) > 1024 || machine.workspace.includes("\0")) {
+      throw new TypeError(`machines[${index}].workspace must be 1-1024 UTF-8 bytes`);
+    }
+    if (!Array.isArray(machine.capabilities)
+      || machine.capabilities.length > MAX_MACHINE_CAPABILITIES
+      || machine.capabilities.some((capability) => (
+        typeof capability !== "string" || !CAPABILITY.test(capability)
+      ))) {
+      throw new TypeError(`machines[${index}].capabilities must be safe identifiers`);
+    }
+    const capabilities = [...new Set(machine.capabilities)];
+    if (capabilities.length !== machine.capabilities.length) {
+      throw new TypeError(`machines[${index}].capabilities must be unique`);
+    }
+    return Object.freeze({
+      id: machine.id,
+      name: machine.name.trim(),
+      workspace: machine.workspace,
+      capabilities: Object.freeze(capabilities),
+    });
+  }));
+  normalizedSnapshots.add(normalized);
+  return normalized;
+}

package/vendor/nanocodex-tools/tools/just-bash-browser.d.mts

@@ -0,0 +1 @@
+export { Bash, defineCommand } from "just-bash/browser";

package/vendor/nanocodex-tools/tools/just-bash-browser.mjs

@@ -0,0 +1 @@
+export { Bash, defineCommand } from "just-bash/browser";

package/vendor/nanocodex-tools/tools/namedTool.d.mts

@@ -0,0 +1,3 @@
+import type { NamedTool, Tool } from "./types.mjs";
+
+export function namedTool(name: string, tool: Tool): NamedTool;

package/vendor/nanocodex-tools/tools/namedTool.mjs

@@ -0,0 +1,3 @@
+export function namedTool(name, tool) {
+  return Object.freeze({ name, ...tool });
+}

package/vendor/nanocodex-tools/tools/nodeProcess.d.mts

@@ -0,0 +1,10 @@
+import type { NamedTool } from "./types.mjs";
+export function createNodeProcessTools(options: {
+  workspace: string;
+  onActivity?: (event: {
+    type: "started" | "completed";
+    sessionId: string;
+    processId: number;
+    exitCode?: number;
+  }) => void;
+}): Promise<{ tools: readonly NamedTool[]; close(): Promise<void> }>;

package/vendor/nanocodex-tools/tools/nodeProcess.mjs

@@ -0,0 +1,314 @@
+import { spawn } from "node:child_process";
+import { realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import {
+  EXEC_COMMAND_PARAMETERS,
+  WRITE_STDIN_PARAMETERS,
+  EXECUTION_OUTPUT_SCHEMA,
+} from "./execution-contract.mjs";
+import { namedTool } from "./namedTool.mjs";
+import { createProcessOutput } from "./processOutput.mjs";
+
+/** Native, explicitly authorized host execution. The workspace is the initial cwd,
+ * not an OS sandbox. Credentials from the embedding process are never inherited. */
+export async function createNodeProcessTools({
+  workspace,
+  onActivity = () => {},
+}) {
+  const root = await realpath(workspace);
+  const sessions = new Map();
+  const processes = new Set();
+  let sequence = 0;
+  let disposed = false;
+  const environment = Object.fromEntries(
+    ["PATH", "HOME", "USER", "TMPDIR", "LANG", "LC_ALL", "SYSTEMROOT"]
+      .filter((key) => process.env[key] !== undefined)
+      .map((key) => [key, process.env[key]]),
+  );
+  if (process.platform === "darwin") {
+    // Finder launches apps with a minimal PATH. Discover common installations
+    // without sourcing shell profiles or importing their environment secrets.
+    const candidates = [
+      "/opt/homebrew/bin",
+      "/usr/local/bin",
+      join(homedir(), ".cargo", "bin"),
+      "/opt/homebrew/sbin",
+    ];
+    const available = await Promise.all(candidates.map(async directory => {
+      try { return (await stat(directory)).isDirectory() ? directory : undefined; }
+      catch { return undefined; }
+    }));
+    const inherited = (environment.PATH || "/usr/bin:/bin:/usr/sbin:/sbin").split(":");
+    environment.PATH = [...new Set([...inherited, ...available.filter(Boolean)])].join(":");
+  }
+  environment.TERM = "dumb";
+  const kill = (record, signal = "SIGTERM") => {
+    if (!record.child.pid) return;
+    try {
+      process.kill(
+        process.platform === "win32" ? record.child.pid : -record.child.pid,
+        signal,
+      );
+    } catch (error) {
+      if (error.code !== "ESRCH") throw error;
+    }
+  };
+  const stopGroup = async (record, signal) => {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        kill(record, signal);
+        return;
+      } catch (error) {
+        // Darwin can briefly return EPERM for a group whose last member is
+        // being reaped. Retry that transition; still report a real refusal.
+        if (error.code !== "EPERM" || !record.done || attempt === 4)
+          throw error;
+        await delay(25);
+      }
+    }
+  };
+  const stop = (record) =>
+    (record.stopping ??= (async () => {
+      await stopGroup(record, "SIGTERM");
+      await Promise.race([
+        record.closed,
+        delay(1_500, undefined, { ref: false }),
+      ]);
+      // Kill descendants too, even if the shell itself exited first.
+      await stopGroup(record, "SIGKILL");
+      await record.closed;
+      await record.output.close();
+      sessions.delete(record.id);
+      processes.delete(record);
+    })());
+  const collect = () => {
+    for (const record of processes)
+      if (record.done) {
+        try {
+          if (record.child.pid)
+            process.kill(
+              process.platform === "win32"
+                ? record.child.pid
+                : -record.child.pid,
+              0,
+            );
+          else processes.delete(record);
+        } catch (error) {
+          if (error.code === "ESRCH") processes.delete(record);
+        }
+      }
+  };
+  const activity = (event) => {
+    try {
+      onActivity(event);
+    } catch {
+      /* Observers cannot interrupt process cleanup. */
+    }
+  };
+  const read = async (record, input, signal, maximumWait = 30_000) => {
+    const started = performance.now();
+    const wait = integer(input.yield_time_ms, 1_000, 0, maximumWait);
+    const maxBytes = integer(input.max_output_tokens, 10_000, 1, 32_000) * 4;
+    if (record.reading)
+      throw new Error("A read is already pending for this process.");
+    record.reading = true;
+    const timer = new AbortController();
+    try {
+      await Promise.race([
+        record.closed,
+        delay(wait, undefined, {
+          signal: signal ? AbortSignal.any([signal, timer.signal]) : timer.signal,
+          ref: false,
+        }),
+      ]);
+      if (signal?.aborted) throw signal.reason;
+      if (record.outputError) throw record.outputError;
+      const output = await record.output.read(maxBytes);
+      if (record.outputError) throw record.outputError;
+      const result = {
+        output,
+        wall_time_seconds: (performance.now() - started) / 1_000,
+      };
+      if (record.done && !record.output.unread) {
+        result.output += record.output.end();
+        await record.output.close();
+        result.exit_code = record.exitCode;
+        sessions.delete(record.id);
+        collect();
+      } else result.session_id = record.id;
+      return result;
+    } finally {
+      // A completed process must not retain a long-poll timer or its abort listener.
+      timer.abort();
+      record.reading = false;
+    }
+  };
+  const exec = namedTool("exec_command", {
+    description:
+      "Run a native command in the authorized host workspace. Supports pipe sessions and write_stdin; PTYs are not available on this hand.",
+    parameters: EXEC_COMMAND_PARAMETERS,
+    outputSchema: EXECUTION_OUTPUT_SCHEMA,
+    supportsParallelToolCalls: true,
+    async handler(input, context) {
+      if (disposed) throw new Error("This compute hand is stopped.");
+      if (!input || typeof input.cmd !== "string" || !input.cmd.trim())
+        throw new TypeError("cmd is required");
+      if (input.tty)
+        throw new Error(
+          "This native Hand supports pipes. Use a VM Hand for PTY commands.",
+        );
+      if (input.sandbox_permissions === "require_escalated")
+        throw new Error("This Hand does not provide privilege escalation.");
+      integer(input.yield_time_ms, 1_000, 0, 30_000);
+      integer(input.max_output_tokens, 10_000, 1, 32_000);
+      if (input.workdir !== undefined && typeof input.workdir !== "string")
+        throw new TypeError("workdir must be text");
+      collect();
+      const cwd = await realpath(resolve(root, input.workdir ?? root));
+      const path = relative(root, cwd);
+      if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path))
+        throw new Error("workdir is outside this Hand's workspace.");
+      const shell =
+        input.shell ?? (process.platform === "win32" ? "cmd.exe" : "/bin/sh");
+      if (typeof shell !== "string" || !isAbsolute(shell))
+        throw new Error("shell must be an absolute executable path.");
+      if (disposed) throw new Error("This compute hand is stopped.");
+      context.signal?.throwIfAborted();
+      const output = await createProcessOutput();
+      if (disposed || context.signal?.aborted) {
+        await output.close();
+        context.signal?.throwIfAborted();
+        throw new Error("This compute hand is stopped.");
+      }
+      let child;
+      try {
+        child = spawn(
+          shell,
+          [input.login === true ? "-lc" : "-c", input.cmd],
+          {
+            cwd,
+            env: environment,
+            detached: process.platform !== "win32",
+            stdio: ["pipe", "pipe", "pipe"],
+          },
+        );
+      } catch (error) {
+        await output.close();
+        throw error;
+      }
+      let finish;
+      const record = {
+        id: ++sequence,
+        owner: context.sessionId,
+        child,
+        output,
+        done: false,
+        exitCode: 0,
+        reading: false,
+        closed: new Promise((resolve) => {
+          finish = resolve;
+        }),
+      };
+      sessions.set(record.id, record);
+      processes.add(record);
+      activity({
+        type: "started",
+        sessionId: context.sessionId,
+        processId: record.id,
+      });
+      const append = (data, stream) => {
+        stream?.pause();
+        void record.output.append(data).catch(error => {
+          record.outputError = error;
+          void stop(record).catch(() => {});
+        }).finally(() => stream?.resume());
+      };
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", data => append(data, child.stdout));
+      child.stderr.on("data", data => append(data, child.stderr));
+      child.stdin.on("error", () => {});
+      child.on("error", (error) => {
+        append(error.message);
+        record.exitCode = 1;
+      });
+      child.on("close", (code) => {
+        record.done = true;
+        record.exitCode =
+          code !== null && code >= 0 ? code : record.exitCode || 130;
+        finish();
+        collect();
+        activity({
+          type: "completed",
+          sessionId: context.sessionId,
+          processId: record.id,
+          exitCode: record.exitCode,
+        });
+      });
+      const abort = () => {
+        void stop(record).catch(() => {});
+      };
+      context.signal?.addEventListener("abort", abort, { once: true });
+      if (context.signal?.aborted) abort();
+      try {
+        return await read(record, input, context.signal);
+      } finally {
+        context.signal?.removeEventListener("abort", abort);
+      }
+    },
+    releaseSession(owner) {
+      for (const record of new Set([...processes, ...sessions.values()]))
+        if (record.owner === owner) void stop(record).catch(() => {});
+    },
+    async dispose() {
+      disposed = true;
+      await Promise.all([...new Set([...processes, ...sessions.values()])].map(stop));
+      sessions.clear();
+    },
+  });
+  const stdin = namedTool("write_stdin", {
+    description:
+      "Write to or poll a pipe session belonging to this agent on this Hand.",
+    parameters: WRITE_STDIN_PARAMETERS,
+    outputSchema: EXECUTION_OUTPUT_SCHEMA,
+    supportsParallelToolCalls: true,
+    async handler(input, context) {
+      const record = sessions.get(input?.session_id);
+      if (disposed || !record || record.owner !== context.sessionId)
+        throw new Error("Process session is unavailable for this agent.");
+      if (input.chars !== undefined && typeof input.chars !== "string")
+        throw new TypeError("chars must be text");
+      const maximumWait = input.chars ? 30_000 : 300_000;
+      integer(input.yield_time_ms, 1_000, 0, maximumWait);
+      integer(input.max_output_tokens, 10_000, 1, 32_000);
+      if (record.reading)
+        throw new Error("A read is already pending for this process.");
+      context.signal?.throwIfAborted();
+      if (input.chars && !record.done) {
+        if (input.chars === "\u0003") kill(record, "SIGINT");
+        else record.child.stdin.write(input.chars);
+      }
+      const abort = () => {
+        void stop(record).catch(() => {});
+      };
+      context.signal?.addEventListener("abort", abort, { once: true });
+      try {
+        return await read(record, input, context.signal, maximumWait);
+      } finally {
+        context.signal?.removeEventListener("abort", abort);
+      }
+    },
+  });
+  return Object.freeze({ tools: [exec, stdin], close: exec.dispose });
+}
+
+function integer(value, fallback, minimum, maximum) {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
+    throw new RangeError(
+      `Expected an integer between ${minimum} and ${maximum}.`,
+    );
+  return value;
+}

package/vendor/nanocodex-tools/tools/processOutput.mjs

@@ -0,0 +1,56 @@
+import { mkdtemp, open, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+// Serialize disk operations; callers pause each source until append completes.
+// Reply budgets limit each read, never how much unread output is retained.
+export async function createProcessOutput() {
+  const directory = await mkdtemp(join(tmpdir(), "nanocodex-output-"));
+  let file;
+  try { file = await open(join(directory, "output"), "wx+", 0o600); }
+  catch (error) { await rm(directory, { recursive: true, force: true }); throw error; }
+  let queued = Promise.resolve();
+  let accepted = 0;
+  let written = 0;
+  let consumed = 0;
+  let closing;
+  const decoder = new StringDecoder("utf8");
+  const enqueue = operation => {
+    const result = queued.then(operation);
+    queued = result.catch(() => {});
+    return result;
+  };
+  return {
+    get unread() { return accepted - consumed; },
+    append(data) {
+      if (closing) return Promise.reject(new Error("Process output is closed."));
+      const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+      accepted += buffer.length;
+      return enqueue(async () => {
+        let offset = 0;
+        while (offset < buffer.length) {
+          const { bytesWritten } = await file.write(buffer, offset, buffer.length - offset, written);
+          if (!bytesWritten) throw new Error("Could not write process output.");
+          offset += bytesWritten;
+          written += bytesWritten;
+        }
+      });
+    },
+    read(maxBytes) {
+      return enqueue(async () => {
+        const buffer = Buffer.alloc(Math.min(maxBytes, written - consumed));
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, consumed);
+        consumed += bytesRead;
+        return decoder.write(buffer.subarray(0, bytesRead));
+      });
+    },
+    end() { return decoder.end(); },
+    close() {
+      return closing ??= enqueue(async () => {
+        try { await file.close(); }
+        finally { await rm(directory, { recursive: true, force: true }); }
+      });
+    },
+  };
+}

package/vendor/nanocodex-tools/tools/repository-workspace.d.mts

@@ -0,0 +1,55 @@
+import type { Workspace } from "./types.mjs";
+
+export type RepositoryWorkspaceFetch = (
+  url: string,
+  options?: Readonly<{
+    method?: string | undefined;
+    headers?: Headers | Record<string, string> | undefined;
+    body?: Uint8Array | undefined;
+    signal?: AbortSignal | undefined;
+  }>,
+) => Promise<Response | Readonly<{
+  status: number;
+  statusText?: string | undefined;
+  headers?: Headers | Record<string, string> | undefined;
+  body?: Uint8Array | AsyncIterable<Uint8Array> | undefined;
+  url?: string | undefined;
+  arrayBuffer?(): Promise<ArrayBuffer>;
+}>>;
+
+export type RepositoryWorkspaceRemote = Readonly<{
+  name: string;
+  url: string;
+  branch: string;
+}>;
+
+export type RepositoryWorkspaceDescriptor = Readonly<{
+  branch: string;
+  directory: string;
+  gitDirectory: string;
+  head: string;
+  markerPath: string;
+  seedUrl: string;
+  writableRemote?: RepositoryWorkspaceRemote | undefined;
+}>;
+
+/**
+ * Materializes one immutable, generation-pinned Git seed into a package-owned
+ * workspace child. A matching retained checkout is reopened without network
+ * access or implicit refresh, preserving local worktree changes.
+ */
+export function materializeRepositoryWorkspace(options: Readonly<{
+  workspace: Workspace;
+  fetch: RepositoryWorkspaceFetch;
+  /** Credential-free smart-HTTP URL ending in the exact lowercase SHA-1 `head`. */
+  seedUrl: string;
+  head: string;
+  branch?: string | undefined;
+  /** One safe child name beneath `workspace.root`; defaults to `repository`. */
+  directory?: string | undefined;
+  writableRemote?: Readonly<{
+    url: string;
+    name?: string | undefined;
+    branch?: string | undefined;
+  }> | undefined;
+}>): Promise<RepositoryWorkspaceDescriptor>;