@immediately-run/sdk 0.17.0 → 0.18.1

package/dist/fs.d.cts

@@ -0,0 +1,109 @@
+import { SandboxMount } from './mounts.cjs';
+import './tasks.cjs';
+
+/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */
+interface NodeFsPromises {
+    readFile(path: string, encoding?: any): Promise<string | Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    readdir(path: string, opts?: any): Promise<any[]>;
+    stat(path: string): Promise<any>;
+    mkdir(path: string, opts?: any): Promise<unknown>;
+    rm(path: string, opts?: any): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+}
+/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —
+ *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */
+interface SandboxFsPort {
+    promises?: NodeFsPromises;
+    readFile?: NodeFsPromises['readFile'];
+}
+/**
+ * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the
+ * resolution order previously duplicated in every app's `mountFs.ts`:
+ *
+ * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.
+ * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`
+ *    whose surface has `readFile` (the bundler ZenFS-layer bound context).
+ * 3. else `null` (local `vite dev` / before boot).
+ *
+ * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute
+ * `/mnt/{hash}` paths (the file explorer / editor).
+ */
+declare function sandboxFs(): SandboxFsPort | null;
+/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before
+ *  boot — gate file affordances on it so an app degrades instead of throwing. */
+declare function fsAvailable(): boolean;
+/** A directory entry from {@link MountFs.readdir}. */
+interface DirEntry {
+    name: string;
+    kind: 'file' | 'dir';
+}
+/** A stat result from {@link MountFs.stat}. */
+interface FileStat {
+    kind: 'file' | 'dir';
+    size: number;
+    mtimeMs?: number;
+}
+/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`
+ *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */
+interface FsError extends Error {
+    code: 'not-found' | 'read-only' | 'not-permitted' | 'exists' | 'not-empty' | 'invalid-path' | 'unavailable' | 'unknown';
+}
+/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;
+ *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).
+ *  Obtain one with {@link openFs}. */
+interface MountFs {
+    /** The mount this view is anchored to (read `mode`/`rules` for writability). */
+    readonly mount: SandboxMount;
+    /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */
+    readFile(relPath: string, encoding: 'utf8'): Promise<string>;
+    readFile(relPath: string): Promise<Uint8Array>;
+    /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */
+    writeFile(relPath: string, data: string | Uint8Array): Promise<void>;
+    /** List a directory (the mount root when `relPath` is omitted). */
+    readdir(relPath?: string): Promise<DirEntry[]>;
+    /** Stat a path. Throws `not-found` if absent. */
+    stat(relPath: string): Promise<FileStat>;
+    /** Does `relPath` exist? Never throws on absence. */
+    exists(relPath: string): Promise<boolean>;
+    /** Create a directory (pass `{ recursive: true }` to make parents). */
+    mkdir(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Remove a file, or a directory with `{ recursive: true }`. */
+    rm(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Rename/move within the mount. */
+    rename(fromRel: string, toRel: string): Promise<void>;
+    /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),
+     *  so an app can hide an "edit" affordance instead of catching `read-only`
+     *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade
+     *  flips it. EROFS from the host stays authoritative. */
+    canWrite(relPath?: string): boolean;
+}
+/**
+ * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:
+ * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you
+ * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path
+ * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the
+ * real enforcer).
+ *
+ * ```ts
+ * import { mountSpace } from '@immediately-run/sdk';
+ * import { openFs } from '@immediately-run/sdk/fs';
+ * const fs = openFs(await mountSpace({ spaceId }));
+ * const text = await fs.readFile('notes/idea.mdx', 'utf8');
+ * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);
+ * ```
+ *
+ * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`
+ * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}
+ * with a mapped `.code` (`not-found`, `read-only`, …).
+ */
+declare function openFs(mount: SandboxMount): MountFs;
+/** Open a mount-anchored view of this app's OWN repository working tree — a convenience
+ *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */
+declare function openAppFs(): MountFs;
+
+export { type DirEntry, type FileStat, type FsError, type MountFs, type SandboxFsPort, fsAvailable, openAppFs, openFs, sandboxFs };

package/dist/fs.d.ts

@@ -0,0 +1,109 @@
+import { SandboxMount } from './mounts.js';
+import './tasks.js';
+
+/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */
+interface NodeFsPromises {
+    readFile(path: string, encoding?: any): Promise<string | Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    readdir(path: string, opts?: any): Promise<any[]>;
+    stat(path: string): Promise<any>;
+    mkdir(path: string, opts?: any): Promise<unknown>;
+    rm(path: string, opts?: any): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+}
+/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —
+ *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */
+interface SandboxFsPort {
+    promises?: NodeFsPromises;
+    readFile?: NodeFsPromises['readFile'];
+}
+/**
+ * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the
+ * resolution order previously duplicated in every app's `mountFs.ts`:
+ *
+ * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.
+ * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`
+ *    whose surface has `readFile` (the bundler ZenFS-layer bound context).
+ * 3. else `null` (local `vite dev` / before boot).
+ *
+ * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute
+ * `/mnt/{hash}` paths (the file explorer / editor).
+ */
+declare function sandboxFs(): SandboxFsPort | null;
+/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before
+ *  boot — gate file affordances on it so an app degrades instead of throwing. */
+declare function fsAvailable(): boolean;
+/** A directory entry from {@link MountFs.readdir}. */
+interface DirEntry {
+    name: string;
+    kind: 'file' | 'dir';
+}
+/** A stat result from {@link MountFs.stat}. */
+interface FileStat {
+    kind: 'file' | 'dir';
+    size: number;
+    mtimeMs?: number;
+}
+/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`
+ *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */
+interface FsError extends Error {
+    code: 'not-found' | 'read-only' | 'not-permitted' | 'exists' | 'not-empty' | 'invalid-path' | 'unavailable' | 'unknown';
+}
+/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;
+ *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).
+ *  Obtain one with {@link openFs}. */
+interface MountFs {
+    /** The mount this view is anchored to (read `mode`/`rules` for writability). */
+    readonly mount: SandboxMount;
+    /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */
+    readFile(relPath: string, encoding: 'utf8'): Promise<string>;
+    readFile(relPath: string): Promise<Uint8Array>;
+    /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */
+    writeFile(relPath: string, data: string | Uint8Array): Promise<void>;
+    /** List a directory (the mount root when `relPath` is omitted). */
+    readdir(relPath?: string): Promise<DirEntry[]>;
+    /** Stat a path. Throws `not-found` if absent. */
+    stat(relPath: string): Promise<FileStat>;
+    /** Does `relPath` exist? Never throws on absence. */
+    exists(relPath: string): Promise<boolean>;
+    /** Create a directory (pass `{ recursive: true }` to make parents). */
+    mkdir(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Remove a file, or a directory with `{ recursive: true }`. */
+    rm(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Rename/move within the mount. */
+    rename(fromRel: string, toRel: string): Promise<void>;
+    /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),
+     *  so an app can hide an "edit" affordance instead of catching `read-only`
+     *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade
+     *  flips it. EROFS from the host stays authoritative. */
+    canWrite(relPath?: string): boolean;
+}
+/**
+ * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:
+ * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you
+ * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path
+ * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the
+ * real enforcer).
+ *
+ * ```ts
+ * import { mountSpace } from '@immediately-run/sdk';
+ * import { openFs } from '@immediately-run/sdk/fs';
+ * const fs = openFs(await mountSpace({ spaceId }));
+ * const text = await fs.readFile('notes/idea.mdx', 'utf8');
+ * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);
+ * ```
+ *
+ * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`
+ * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}
+ * with a mapped `.code` (`not-found`, `read-only`, …).
+ */
+declare function openFs(mount: SandboxMount): MountFs;
+/** Open a mount-anchored view of this app's OWN repository working tree — a convenience
+ *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */
+declare function openAppFs(): MountFs;
+
+export { type DirEntry, type FileStat, type FsError, type MountFs, type SandboxFsPort, fsAvailable, openAppFs, openFs, sandboxFs };

package/dist/fs.js

@@ -0,0 +1,187 @@
+import { getAppMountPath } from "./mounts";
+const hasFs = (fs) => typeof fs?.promises?.readFile === "function" || typeof fs?.readFile === "function";
+function sandboxFs() {
+  try {
+    const shared = globalThis.__sandpackSharedFs;
+    if (hasFs(shared)) return shared;
+  } catch {
+  }
+  try {
+    const layers = module?.evaluation?.module?.bundler?.fs?.layers;
+    if (Array.isArray(layers)) {
+      for (const layer of layers) {
+        const fs = layer?.boundContext?.fs;
+        if (hasFs(fs)) return fs;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function fsAvailable() {
+  return sandboxFs() != null;
+}
+const ERRNO = {
+  ENOENT: "not-found",
+  EROFS: "read-only",
+  EACCES: "not-permitted",
+  EPERM: "not-permitted",
+  EEXIST: "exists",
+  ENOTEMPTY: "not-empty"
+};
+const fsError = (code, message) => {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+};
+const mapError = (e) => {
+  const errno = e?.code;
+  const code = (errno ? ERRNO[errno] : void 0) ?? "unknown";
+  const err = new Error(e?.message ?? "fs operation failed");
+  err.code = code;
+  return err;
+};
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+const resolveUnder = (root, relPath) => {
+  if (relPath.startsWith("/")) {
+    throw fsError("invalid-path", `expected a mount-relative path, got absolute "${relPath}"`);
+  }
+  const parts = [];
+  for (const seg of relPath.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      throw fsError("invalid-path", `"${relPath}" escapes the mount root`);
+    }
+    parts.push(seg);
+  }
+  const base = root.endsWith("/") ? root.slice(0, -1) : root;
+  return parts.length ? `${base}/${parts.join("/")}` : base;
+};
+const writableAt = (mount, relPath) => {
+  const path = "/" + relPath.split("/").filter((s) => s && s !== ".").join("/");
+  const rules = mount.rules;
+  if (rules && rules.length) {
+    let best;
+    for (const r of rules) {
+      const sub = r.subtree.endsWith("/") ? r.subtree : r.subtree + "/";
+      if (path === r.subtree || path.startsWith(sub) || r.subtree === "/") {
+        if (!best || r.subtree.length > best.subtree.length) best = r;
+      }
+    }
+    if (best) return best.mode === "rw";
+  }
+  return (mount.mode ?? "rw") === "rw";
+};
+const promisesOf = (port) => port.promises ?? port;
+function openFs(mount) {
+  const root = mount.path;
+  const port = () => {
+    const p = sandboxFs();
+    if (!p) throw fsError("unavailable", "immediately.run: sandbox filesystem unavailable");
+    return promisesOf(p);
+  };
+  const api = {
+    mount,
+    async readFile(relPath, encoding) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        const data = await p.readFile(abs);
+        const bytes = typeof data === "string" ? encoder.encode(data) : data;
+        return encoding === "utf8" ? decoder.decode(bytes) : bytes;
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async writeFile(relPath, data) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        await p.writeFile(abs, typeof data === "string" ? encoder.encode(data) : data);
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async readdir(relPath = "") {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        const entries = await p.readdir(abs, { withFileTypes: true });
+        return entries.map(
+          (d) => typeof d === "string" ? { name: d, kind: "file" } : { name: d.name, kind: d.isDirectory?.() ? "dir" : "file" }
+        );
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async stat(relPath) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        const s = await p.stat(abs);
+        return {
+          kind: s.isDirectory?.() ? "dir" : "file",
+          size: typeof s.size === "number" ? s.size : 0,
+          mtimeMs: typeof s.mtimeMs === "number" ? s.mtimeMs : void 0
+        };
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async exists(relPath) {
+      try {
+        await api.stat(relPath);
+        return true;
+      } catch (e) {
+        if (e.code === "not-found") return false;
+        if (e.code === "unavailable" || e.code === "invalid-path") {
+          throw e;
+        }
+        return false;
+      }
+    },
+    async mkdir(relPath, opts) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        await p.mkdir(abs, { recursive: opts?.recursive ?? false });
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async rm(relPath, opts) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        await p.rm(abs, { recursive: opts?.recursive ?? false });
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async rename(fromRel, toRel) {
+      const p = port();
+      const from = resolveUnder(root, fromRel);
+      const to = resolveUnder(root, toRel);
+      try {
+        await p.rename(from, to);
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    canWrite(relPath = "") {
+      return writableAt(mount, relPath);
+    }
+  };
+  return api;
+}
+function openAppFs() {
+  return openFs({ path: getAppMountPath(), type: "repo" });
+}
+export {
+  fsAvailable,
+  openAppFs,
+  openFs,
+  sandboxFs
+};
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fs.ts"],"sourcesContent":["// Typed, discoverable filesystem access — the app-facing surface for the ZenFS\n// mount ports (SDK_FS_SURFACE_SPEC; FILESYSTEM_SPEC §2 the ZenFS-shaped contract).\n//\n// The single most important thing an app does — read/write files in its mounts —\n// previously had NO SDK surface: apps reached an ambient `globalThis.__sandpackSharedFs`\n// by hand-rolling the same accessor (editor/file-explorer `src/fs/mountFs.ts`, \"keep the\n// two in sync\"), with a documented footgun (`module.evaluation.module.bundler.fs` is the\n// WRONG object — it has no `promises`/`stat`). This module is that accessor's ONE home,\n// typed and documented.\n//\n// It adds NO authority: the ZenFS port is already minted and chroot/`ro`-enforced\n// host-side (FILESYSTEM_SPEC §2, UI_AS_APPS §8.7). This is typing + discoverability +\n// de-duplication only. `fs` is a Resource PORT (a byte channel), not a host-brokered RPC,\n// so — unlike the `invoke()` catalog surface — it is hand-written, not gate-table-derived.\nimport type { SandboxMount, MountRule } from './mounts';\nimport { getAppMountPath } from './mounts';\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */\ninterface NodeFsPromises {\n  readFile(path: string, encoding?: any): Promise<string | Uint8Array>;\n  writeFile(path: string, data: string | Uint8Array): Promise<void>;\n  readdir(path: string, opts?: any): Promise<any[]>;\n  stat(path: string): Promise<any>;\n  mkdir(path: string, opts?: any): Promise<unknown>;\n  rm(path: string, opts?: any): Promise<void>;\n  rename(from: string, to: string): Promise<void>;\n}\n\n/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —\n *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */\nexport interface SandboxFsPort {\n  promises?: NodeFsPromises;\n  readFile?: NodeFsPromises['readFile'];\n}\n\nconst hasFs = (fs: any): boolean =>\n  typeof fs?.promises?.readFile === 'function' || typeof fs?.readFile === 'function';\n\n/**\n * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the\n * resolution order previously duplicated in every app's `mountFs.ts`:\n *\n * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.\n * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`\n *    whose surface has `readFile` (the bundler ZenFS-layer bound context).\n * 3. else `null` (local `vite dev` / before boot).\n *\n * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute\n * `/mnt/{hash}` paths (the file explorer / editor).\n */\nexport function sandboxFs(): SandboxFsPort | null {\n  try {\n    const shared = (globalThis as any).__sandpackSharedFs;\n    if (hasFs(shared)) return shared as SandboxFsPort;\n  } catch {\n    /* not in the sandbox */\n  }\n  try {\n    // @ts-ignore - `module` is injected by the sandbox runtime (see sandboxUtils transport).\n    const layers = module?.evaluation?.module?.bundler?.fs?.layers;\n    if (Array.isArray(layers)) {\n      for (const layer of layers) {\n        const fs = layer?.boundContext?.fs;\n        if (hasFs(fs)) return fs as SandboxFsPort;\n      }\n    }\n  } catch {\n    /* not in the sandbox */\n  }\n  return null;\n}\n\n/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before\n *  boot — gate file affordances on it so an app degrades instead of throwing. */\nexport function fsAvailable(): boolean {\n  return sandboxFs() != null;\n}\n\n/** A directory entry from {@link MountFs.readdir}. */\nexport interface DirEntry {\n  name: string;\n  kind: 'file' | 'dir';\n}\n\n/** A stat result from {@link MountFs.stat}. */\nexport interface FileStat {\n  kind: 'file' | 'dir';\n  size: number;\n  mtimeMs?: number;\n}\n\n/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`\n *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */\nexport interface FsError extends Error {\n  code:\n    | 'not-found' // ENOENT\n    | 'read-only' // EROFS — a `ro` mount / downgraded role; NEVER surface as UX (gate with canWrite)\n    | 'not-permitted' // EACCES\n    | 'exists' // EEXIST\n    | 'not-empty' // ENOTEMPTY\n    | 'invalid-path' // a `..` segment / absolute escape was passed as a relPath\n    | 'unavailable' // no sandbox fs (local dev / pre-boot)\n    | 'unknown';\n}\n\nconst ERRNO: Record<string, FsError['code']> = {\n  ENOENT: 'not-found',\n  EROFS: 'read-only',\n  EACCES: 'not-permitted',\n  EPERM: 'not-permitted',\n  EEXIST: 'exists',\n  ENOTEMPTY: 'not-empty',\n};\n\nconst fsError = (code: FsError['code'], message: string): FsError => {\n  const err = new Error(message) as FsError;\n  err.code = code;\n  return err;\n};\n\nconst mapError = (e: unknown): FsError => {\n  const errno = (e as { code?: string } | null)?.code;\n  const code: FsError['code'] = (errno ? ERRNO[errno] : undefined) ?? 'unknown';\n  const err = new Error((e as Error)?.message ?? 'fs operation failed') as FsError;\n  err.code = code;\n  return err;\n};\n\nconst decoder = new TextDecoder();\nconst encoder = new TextEncoder();\n\n// Join a mount-RELATIVE path under the mount root, rejecting `..` escapes and absolute\n// paths (CLAUDE.md security rule 3 — don't probe for escapes). The host chroot is the\n// real enforcer; this keeps an honest app from accidentally naming outside its grant.\nconst resolveUnder = (root: string, relPath: string): string => {\n  if (relPath.startsWith('/')) {\n    throw fsError('invalid-path', `expected a mount-relative path, got absolute \"${relPath}\"`);\n  }\n  const parts: string[] = [];\n  for (const seg of relPath.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') {\n      throw fsError('invalid-path', `\"${relPath}\" escapes the mount root`);\n    }\n    parts.push(seg);\n  }\n  const base = root.endsWith('/') ? root.slice(0, -1) : root;\n  return parts.length ? `${base}/${parts.join('/')}` : base;\n};\n\n// The longest matching `rules` subtree governs a path (mounts.ts MountRule); fall back to\n// the whole-mount `mode`. A CLIENT-SIDE hint mirroring the host rule — EROFS stays\n// authoritative (the host re-checks live policy on every write).\nconst writableAt = (mount: SandboxMount, relPath: string): boolean => {\n  const path = '/' + relPath.split('/').filter((s) => s && s !== '.').join('/');\n  const rules: MountRule[] | undefined = mount.rules;\n  if (rules && rules.length) {\n    let best: MountRule | undefined;\n    for (const r of rules) {\n      const sub = r.subtree.endsWith('/') ? r.subtree : r.subtree + '/';\n      if (path === r.subtree || path.startsWith(sub) || r.subtree === '/') {\n        if (!best || r.subtree.length > best.subtree.length) best = r;\n      }\n    }\n    if (best) return best.mode === 'rw';\n  }\n  return (mount.mode ?? 'rw') === 'rw';\n};\n\n/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;\n *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).\n *  Obtain one with {@link openFs}. */\nexport interface MountFs {\n  /** The mount this view is anchored to (read `mode`/`rules` for writability). */\n  readonly mount: SandboxMount;\n  /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */\n  readFile(relPath: string, encoding: 'utf8'): Promise<string>;\n  readFile(relPath: string): Promise<Uint8Array>;\n  /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */\n  writeFile(relPath: string, data: string | Uint8Array): Promise<void>;\n  /** List a directory (the mount root when `relPath` is omitted). */\n  readdir(relPath?: string): Promise<DirEntry[]>;\n  /** Stat a path. Throws `not-found` if absent. */\n  stat(relPath: string): Promise<FileStat>;\n  /** Does `relPath` exist? Never throws on absence. */\n  exists(relPath: string): Promise<boolean>;\n  /** Create a directory (pass `{ recursive: true }` to make parents). */\n  mkdir(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Remove a file, or a directory with `{ recursive: true }`. */\n  rm(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Rename/move within the mount. */\n  rename(fromRel: string, toRel: string): Promise<void>;\n  /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),\n   *  so an app can hide an \"edit\" affordance instead of catching `read-only`\n   *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade\n   *  flips it. EROFS from the host stays authoritative. */\n  canWrite(relPath?: string): boolean;\n}\n\nconst promisesOf = (port: SandboxFsPort): NodeFsPromises =>\n  (port.promises ?? (port as unknown as NodeFsPromises));\n\n/**\n * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:\n * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you\n * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path\n * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the\n * real enforcer).\n *\n * ```ts\n * import { mountSpace } from '@immediately-run/sdk';\n * import { openFs } from '@immediately-run/sdk/fs';\n * const fs = openFs(await mountSpace({ spaceId }));\n * const text = await fs.readFile('notes/idea.mdx', 'utf8');\n * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);\n * ```\n *\n * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`\n * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}\n * with a mapped `.code` (`not-found`, `read-only`, …).\n */\nexport function openFs(mount: SandboxMount): MountFs {\n  const root = mount.path;\n\n  const port = (): NodeFsPromises => {\n    const p = sandboxFs();\n    if (!p) throw fsError('unavailable', 'immediately.run: sandbox filesystem unavailable');\n    return promisesOf(p);\n  };\n\n  const api: MountFs = {\n    mount,\n    async readFile(relPath: string, encoding?: 'utf8'): Promise<any> {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const data = await p.readFile(abs);\n        const bytes =\n          typeof data === 'string' ? encoder.encode(data) : (data as Uint8Array);\n        return encoding === 'utf8' ? decoder.decode(bytes) : bytes;\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async writeFile(relPath, data) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.writeFile(abs, typeof data === 'string' ? encoder.encode(data) : data);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readdir(relPath = '') {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const entries = await p.readdir(abs, { withFileTypes: true });\n        return entries.map((d: any) =>\n          typeof d === 'string'\n            ? ({ name: d, kind: 'file' } as DirEntry)\n            : ({ name: d.name, kind: d.isDirectory?.() ? 'dir' : 'file' } as DirEntry),\n        );\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async stat(relPath) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const s: any = await p.stat(abs);\n        return {\n          kind: s.isDirectory?.() ? 'dir' : 'file',\n          size: typeof s.size === 'number' ? s.size : 0,\n          mtimeMs: typeof s.mtimeMs === 'number' ? s.mtimeMs : undefined,\n        };\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async exists(relPath) {\n      try {\n        await api.stat(relPath);\n        return true;\n      } catch (e) {\n        if ((e as FsError).code === 'not-found') return false;\n        if ((e as FsError).code === 'unavailable' || (e as FsError).code === 'invalid-path') {\n          throw e;\n        }\n        return false;\n      }\n    },\n    async mkdir(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.mkdir(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rm(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.rm(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rename(fromRel, toRel) {\n      const p = port();\n      const from = resolveUnder(root, fromRel);\n      const to = resolveUnder(root, toRel);\n      try {\n        await p.rename(from, to);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    canWrite(relPath = '') {\n      return writableAt(mount, relPath);\n    },\n  };\n  return api;\n}\n\n/** Open a mount-anchored view of this app's OWN repository working tree — a convenience\n *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */\nexport function openAppFs(): MountFs {\n  return openFs({ path: getAppMountPath(), type: 'repo' } as SandboxMount);\n}\n"],"mappings":"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","names":[]}

package/dist/index.cjs

@@ -38,6 +38,7 @@ __reExport(index_exports, require("./secrets"), module.exports);
 __reExport(index_exports, require("./llm"), module.exports);
 __reExport(index_exports, require("./diagnostics"), module.exports);
 __reExport(index_exports, require("./onFsChange"), module.exports);
+__reExport(index_exports, require("./fs"), module.exports);
 __reExport(index_exports, require("./debug"), module.exports);
 __reExport(index_exports, require("./tasks"), module.exports);
 __reExport(index_exports, require("./runtime"), module.exports);
@@ -71,6 +72,7 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./llm"),
   ...require("./diagnostics"),
   ...require("./onFsChange"),
+  ...require("./fs"),
   ...require("./debug"),
   ...require("./tasks"),
   ...require("./runtime"),

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,gCALd;AAMA,0BAAc,oBANd;AAOA,0BAAc,mBAPd;AAQA,0BAAc,oBARd;AASA,0BAAc,4BATd;AAUA,0BAAc,qBAVd;AAWA,0BAAc,yBAXd;AAYA,0BAAc,qBAZd;AAaA,0BAAc,qBAbd;AAcA,0BAAc,yBAdd;AAeA,0BAAc,sBAfd;AAgBA,0BAAc,kBAhBd;AAiBA,0BAAc,kBAjBd;AAkBA,0BAAc,uBAlBd;AAmBA,0BAAc,sBAnBd;AAoBA,0BAAc,kBApBd;AAqBA,0BAAc,0BArBd;AAsBA,0BAAc,yBAtBd;AAuBA,0BAAc,oBAvBd;AAwBA,0BAAc,oBAxBd;AAyBA,0BAAc,sBAzBd;AA0BA,0BAAc,wBA1Bd;AA2BA,0BAAc,oBA3Bd;AA4BA,0BAAc,sBA5Bd;AA6BA,0BAAc,6BA7Bd;AA8BA,0BAAc,2BA9Bd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,gCALd;AAMA,0BAAc,oBANd;AAOA,0BAAc,mBAPd;AAQA,0BAAc,oBARd;AASA,0BAAc,4BATd;AAUA,0BAAc,qBAVd;AAWA,0BAAc,yBAXd;AAYA,0BAAc,qBAZd;AAaA,0BAAc,qBAbd;AAcA,0BAAc,yBAdd;AAeA,0BAAc,sBAfd;AAgBA,0BAAc,kBAhBd;AAiBA,0BAAc,kBAjBd;AAkBA,0BAAc,uBAlBd;AAmBA,0BAAc,sBAnBd;AAoBA,0BAAc,kBApBd;AAqBA,0BAAc,0BArBd;AAsBA,0BAAc,yBAtBd;AAuBA,0BAAc,iBAvBd;AAwBA,0BAAc,oBAxBd;AAyBA,0BAAc,oBAzBd;AA0BA,0BAAc,sBA1Bd;AA2BA,0BAAc,wBA3Bd;AA4BA,0BAAc,oBA5Bd;AA6BA,0BAAc,sBA7Bd;AA8BA,0BAAc,6BA9Bd;AA+BA,0BAAc,2BA/Bd;","names":[]}

package/dist/index.d.cts

@@ -21,6 +21,7 @@ export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretV
 export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, onChatProviderChange, useChatProvider } from './llm.cjs';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.cjs';
 export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.cjs';
+export { DirEntry, FileStat, FsError, MountFs, SandboxFsPort, fsAvailable, openAppFs, openFs, sandboxFs } from './fs.cjs';
 export { DebugLevel, debug, isDebugEnabled, log, useDebugEnabled } from './debug.cjs';
 export { DirCap, FileCap, TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.cjs';
 export { SDK_PROTOCOL_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.cjs';

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretV
 export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, onChatProviderChange, useChatProvider } from './llm.js';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.js';
 export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.js';
+export { DirEntry, FileStat, FsError, MountFs, SandboxFsPort, fsAvailable, openAppFs, openFs, sandboxFs } from './fs.js';
 export { DebugLevel, debug, isDebugEnabled, log, useDebugEnabled } from './debug.js';
 export { DirCap, FileCap, TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.js';
 export { SDK_PROTOCOL_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.js';

package/dist/index.js

@@ -21,6 +21,7 @@ export * from "./secrets";
 export * from "./llm";
 export * from "./diagnostics";
 export * from "./onFsChange";
+export * from "./fs";
 export * from "./debug";
 export * from "./tasks";
 export * from "./runtime";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/llm.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\n\n/** Who authored a {@link ChatMessage}. */\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string }; // data: base64, no data: URL prefix\n\n/** One message in a {@link ChatRequest}: a role plus its content parts. */\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\n/** A host-brokered chat completion request: the messages plus optional tools,\n *  response format, and model hint (each honored per the provider's features). */\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\n/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  return invokeStream<ChatDelta, ChatResult>('llm:chat', req as unknown as Record<string, unknown>);\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n}\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\" (distinct from \"not yet answered\", which keeps the `initial` null).\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: 'llm-provider',\n  requestType: 'request-llm-provider',\n  initial: null,\n  parse: (msg) =>\n    'provider' in msg ? (msg.provider as ChatProviderInfo | null) : undefined,\n});\n\n/** The provider the host resolved for this app (or `null` if none bound). Poll for a\n *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,qBAA6B;AAC7B,yBAAkC;AAmE3B,SAAS,KAAK,KAA+D;AAClF,aAAO,6BAAoC,YAAY,GAAyC;AAClG;AA0BA,MAAM,cAAU,sCAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QACN,cAAc,MAAO,IAAI,WAAuC;AACpE,CAAC;AAIM,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAIhE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAIrC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\n\n/** Who authored a {@link ChatMessage}. */\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5); `tool-use`/`tool-result` only when it\n *  advertises `features.tools` — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string } // data: base64, no data: URL prefix\n  // A tool call the model emitted on a prior `assistant` turn — replay it in the\n  // conversation so a follow-up request carries the agentic history. Pairs with the\n  // streamed `tool-call` {@link ChatDelta} that first surfaced it.\n  | { type: 'tool-use'; id: string; name: string; input: Record<string, unknown> }\n  // The result of executing a `tool-use`, fed back so the model can continue. Carried\n  // on a `user`/`tool`-role message; `toolCallId` matches the `tool-use` `id`.\n  | { type: 'tool-result'; toolCallId: string; content: string; isError?: boolean };\n\n/** One message in a {@link ChatRequest}: a role plus its content parts. */\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\n/** A host-brokered chat completion request: the messages plus optional tools,\n *  response format, and model hint (each honored per the provider's features). */\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\n/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  return invokeStream<ChatDelta, ChatResult>('llm:chat', req as unknown as Record<string, unknown>);\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n}\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\" (distinct from \"not yet answered\", which keeps the `initial` null).\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: 'llm-provider',\n  requestType: 'request-llm-provider',\n  initial: null,\n  parse: (msg) =>\n    'provider' in msg ? (msg.provider as ChatProviderInfo | null) : undefined,\n});\n\n/** The provider the host resolved for this app (or `null` if none bound). Poll for a\n *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,qBAA6B;AAC7B,yBAAkC;AA2E3B,SAAS,KAAK,KAA+D;AAClF,aAAO,6BAAoC,YAAY,GAAyC;AAClG;AA0BA,MAAM,cAAU,sCAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QACN,cAAc,MAAO,IAAI,WAAuC;AACpE,CAAC;AAIM,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAIhE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAIrC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;","names":[]}

package/dist/llm.d.cts

@@ -1,7 +1,8 @@
 /** Who authored a {@link ChatMessage}. */
 type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
 /** A part of a message. `image` is only honored when the resolved provider
- *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */
+ *  advertises `features.vision` (§2.5); `tool-use`/`tool-result` only when it
+ *  advertises `features.tools` — branch on {@link describeChat} first. */
 type ContentPart = {
     type: 'text';
     text: string;
@@ -9,6 +10,16 @@ type ContentPart = {
     type: 'image';
     mimeType: string;
     data: string;
+} | {
+    type: 'tool-use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    content: string;
+    isError?: boolean;
 };
 /** One message in a {@link ChatRequest}: a role plus its content parts. */
 interface ChatMessage {

package/dist/llm.d.ts

@@ -1,7 +1,8 @@
 /** Who authored a {@link ChatMessage}. */
 type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
 /** A part of a message. `image` is only honored when the resolved provider
- *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */
+ *  advertises `features.vision` (§2.5); `tool-use`/`tool-result` only when it
+ *  advertises `features.tools` — branch on {@link describeChat} first. */
 type ContentPart = {
     type: 'text';
     text: string;
@@ -9,6 +10,16 @@ type ContentPart = {
     type: 'image';
     mimeType: string;
     data: string;
+} | {
+    type: 'tool-use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    content: string;
+    isError?: boolean;
 };
 /** One message in a {@link ChatRequest}: a role plus its content parts. */
 interface ChatMessage {