@finalai/agent-provider 0.1.0

package/dist/modules/sandbox/confined-files.mjs

@@ -0,0 +1,142 @@
+import * as z from "zod";
+import { concatBytes, readAllBytes } from "./bytes.mjs";
+import { dirEntrySchema, statSchema } from "./wire.mjs";
+const CONFINED_FILES_SCRIPT = `import json, os, stat, sys, datetime
+p = json.loads(sys.argv[1])
+root = os.path.normpath(p['root'])
+path = os.path.normpath(p['path'])
+if not root.startswith('/') or not path.startswith('/') or os.path.commonpath([root, path]) != root:
+    raise ValueError('path outside workspace')
+fd = os.open('/', os.O_RDONLY | os.O_DIRECTORY)
+try:
+    parts = [x for x in path.split('/') if x]
+    for i, part in enumerate(parts):
+        flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK
+        if i < len(parts) - 1 or p['operation'] == 'directory':
+            flags |= os.O_DIRECTORY
+        next_fd = os.open(part, flags, dir_fd=fd)
+        os.close(fd)
+        fd = next_fd
+    info = os.fstat(fd)
+    def kind(s):
+        return 'directory' if stat.S_ISDIR(s.st_mode) else 'file' if stat.S_ISREG(s.st_mode) else 'symlink' if stat.S_ISLNK(s.st_mode) else 'other'
+    if p['operation'] == 'stat':
+        print(json.dumps({'path': path, 'type': kind(info), 'size': info.st_size, 'modifiedAt': datetime.datetime.fromtimestamp(info.st_mtime, datetime.timezone.utc).isoformat(), 'mode': stat.S_IMODE(info.st_mode)}))
+    elif p['operation'] == 'directory':
+        entries = []
+        for name in os.listdir(fd):
+            try:
+                s = os.stat(name, dir_fd=fd, follow_symlinks=False)
+            except FileNotFoundError:
+                continue
+            entries.append({'name': name, 'path': os.path.join(path, name), 'type': kind(s), 'size': s.st_size})
+        print(json.dumps(entries))
+    else:
+        if not stat.S_ISREG(info.st_mode):
+            raise ValueError('not a regular file')
+        sys.stdout.buffer.write(b'OK\\n')
+        sys.stdout.buffer.flush()
+        while True:
+            chunk = os.read(fd, 65536)
+            if not chunk:
+                break
+            sys.stdout.buffer.write(chunk)
+except FileNotFoundError:
+    if p['operation'] == 'read':
+        sys.stdout.buffer.write(b'MISSING\\n')
+    else:
+        print('null')
+finally:
+    os.close(fd)
+`;
+const invocation = (options, operation) => ({
+  command: "python3",
+  args: [
+    "-c",
+    CONFINED_FILES_SCRIPT,
+    JSON.stringify({ root: options.root, path: options.path, operation })
+  ],
+  abortSignal: options.abortSignal
+});
+const confinedStat = async (sandbox, options) => {
+  const result = await sandbox.run(invocation(options, "stat"));
+  if (result.exitCode !== 0) throw new Error("Confined file stat failed");
+  return statSchema.nullable().parse(JSON.parse(result.stdout));
+};
+const confinedReadDir = async (sandbox, options) => {
+  const result = await sandbox.run(invocation(options, "directory"));
+  if (result.exitCode !== 0) throw new Error("Confined directory read failed");
+  return z.array(dirEntrySchema).parse(JSON.parse(result.stdout));
+};
+const confinedReadFile = async (sandbox, options) => {
+  const process = await sandbox.spawn(invocation(options, "read"));
+  const stderr = readAllBytes(process.stderr);
+  void stderr.catch(() => void 0);
+  const reader = process.stdout.getReader();
+  let buffered = new Uint8Array(0);
+  let newline = -1;
+  try {
+    while (newline === -1) {
+      const next = await reader.read();
+      if (next.done) throw new Error("Confined file read failed");
+      buffered = concatBytes([buffered, next.value]);
+      newline = buffered.indexOf(10);
+      if (newline === -1 && buffered.length > 128) throw new Error("Invalid confined file header");
+    }
+    const header = new TextDecoder().decode(buffered.subarray(0, newline));
+    if (header === "MISSING") {
+      await reader.cancel();
+      await process.wait();
+      await stderr;
+      return null;
+    }
+    if (header !== "OK") throw new Error("Invalid confined file header");
+  } catch (cause) {
+    await reader.cancel().catch(() => void 0);
+    await process.kill().catch(() => void 0);
+    await stderr.catch(() => void 0);
+    throw cause;
+  }
+  const first = buffered.subarray(newline + 1);
+  return new ReadableStream({
+    start: (controller) => {
+      if (first.length > 0) controller.enqueue(first);
+    },
+    pull: async (controller) => {
+      try {
+        const next = await reader.read();
+        if (!next.done) {
+          controller.enqueue(next.value);
+          return;
+        }
+        const result = await process.wait();
+        await stderr;
+        if (result.exitCode !== 0) controller.error(new Error("Confined file read failed"));
+        else controller.close();
+      } catch (cause) {
+        await reader.cancel().catch(() => void 0);
+        await process.kill().catch(() => void 0);
+        await stderr.catch(() => void 0);
+        controller.error(cause);
+      }
+    },
+    cancel: async () => {
+      await reader.cancel().catch(() => void 0);
+      await process.kill().catch(() => void 0);
+      await stderr.catch(() => void 0);
+    }
+  });
+};
+const createConfinedFileReader = (sandbox) => ({
+  readFile: (options) => confinedReadFile(sandbox, options),
+  stat: (options) => confinedStat(sandbox, options),
+  readDir: (options) => confinedReadDir(sandbox, options)
+});
+export {
+  CONFINED_FILES_SCRIPT,
+  confinedReadDir,
+  confinedReadFile,
+  confinedStat,
+  createConfinedFileReader
+};
+//# sourceMappingURL=confined-files.mjs.map

package/dist/modules/sandbox/confined-files.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/sandbox/confined-files.ts"],
+  "sourcesContent": ["import * as z from 'zod';\nimport { concatBytes, readAllBytes } from \"./bytes.mjs\";\nimport type { AbortableIface, ConfinedSandboxFilesIface, SandboxSessionIface } from \"./types.mjs\";\nimport { dirEntrySchema, statSchema } from \"./wire.mjs\";\n\n// Pin each ancestor with openat(O_NOFOLLOW). A concurrent rename cannot redirect\n// a read outside the opened directory. Missing Python support fails closed.\nexport const CONFINED_FILES_SCRIPT = `import json, os, stat, sys, datetime\np = json.loads(sys.argv[1])\nroot = os.path.normpath(p['root'])\npath = os.path.normpath(p['path'])\nif not root.startswith('/') or not path.startswith('/') or os.path.commonpath([root, path]) != root:\n    raise ValueError('path outside workspace')\nfd = os.open('/', os.O_RDONLY | os.O_DIRECTORY)\ntry:\n    parts = [x for x in path.split('/') if x]\n    for i, part in enumerate(parts):\n        flags = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK\n        if i < len(parts) - 1 or p['operation'] == 'directory':\n            flags |= os.O_DIRECTORY\n        next_fd = os.open(part, flags, dir_fd=fd)\n        os.close(fd)\n        fd = next_fd\n    info = os.fstat(fd)\n    def kind(s):\n        return 'directory' if stat.S_ISDIR(s.st_mode) else 'file' if stat.S_ISREG(s.st_mode) else 'symlink' if stat.S_ISLNK(s.st_mode) else 'other'\n    if p['operation'] == 'stat':\n        print(json.dumps({'path': path, 'type': kind(info), 'size': info.st_size, 'modifiedAt': datetime.datetime.fromtimestamp(info.st_mtime, datetime.timezone.utc).isoformat(), 'mode': stat.S_IMODE(info.st_mode)}))\n    elif p['operation'] == 'directory':\n        entries = []\n        for name in os.listdir(fd):\n            try:\n                s = os.stat(name, dir_fd=fd, follow_symlinks=False)\n            except FileNotFoundError:\n                continue\n            entries.append({'name': name, 'path': os.path.join(path, name), 'type': kind(s), 'size': s.st_size})\n        print(json.dumps(entries))\n    else:\n        if not stat.S_ISREG(info.st_mode):\n            raise ValueError('not a regular file')\n        sys.stdout.buffer.write(b'OK\\\\n')\n        sys.stdout.buffer.flush()\n        while True:\n            chunk = os.read(fd, 65536)\n            if not chunk:\n                break\n            sys.stdout.buffer.write(chunk)\nexcept FileNotFoundError:\n    if p['operation'] == 'read':\n        sys.stdout.buffer.write(b'MISSING\\\\n')\n    else:\n        print('null')\nfinally:\n    os.close(fd)\n`;\n\ninterface ConfinedPathIface extends AbortableIface {\n  path: string;\n  root: string;\n}\n\nconst invocation = (options: ConfinedPathIface, operation: string) => ({\n  command: 'python3',\n  args: [\n    '-c',\n    CONFINED_FILES_SCRIPT,\n    JSON.stringify({ root: options.root, path: options.path, operation }),\n  ],\n  abortSignal: options.abortSignal,\n});\n\nexport const confinedStat = async (\n  sandbox: Pick<SandboxSessionIface, 'run' | 'spawn'>,\n  options: ConfinedPathIface,\n) => {\n  const result = await sandbox.run(invocation(options, 'stat'));\n  if (result.exitCode !== 0) throw new Error('Confined file stat failed');\n  return statSchema.nullable().parse(JSON.parse(result.stdout));\n};\n\nexport const confinedReadDir = async (\n  sandbox: Pick<SandboxSessionIface, 'run' | 'spawn'>,\n  options: ConfinedPathIface,\n) => {\n  const result = await sandbox.run(invocation(options, 'directory'));\n  if (result.exitCode !== 0) throw new Error('Confined directory read failed');\n  return z.array(dirEntrySchema).parse(JSON.parse(result.stdout));\n};\n\nexport const confinedReadFile = async (\n  sandbox: Pick<SandboxSessionIface, 'run' | 'spawn'>,\n  options: ConfinedPathIface,\n) => {\n  const process = await sandbox.spawn(invocation(options, 'read'));\n  const stderr = readAllBytes(process.stderr);\n  void stderr.catch(() => undefined);\n  const reader = process.stdout.getReader();\n  let buffered: Uint8Array = new Uint8Array(0);\n  let newline = -1;\n  try {\n    while (newline === -1) {\n      const next = await reader.read();\n      if (next.done) throw new Error('Confined file read failed');\n      buffered = concatBytes([buffered, next.value]);\n      newline = buffered.indexOf(10);\n      if (newline === -1 && buffered.length > 128) throw new Error('Invalid confined file header');\n    }\n    const header = new TextDecoder().decode(buffered.subarray(0, newline));\n    if (header === 'MISSING') {\n      await reader.cancel();\n      await process.wait();\n      await stderr;\n      return null;\n    }\n    if (header !== 'OK') throw new Error('Invalid confined file header');\n  } catch (cause) {\n    await reader.cancel().catch(() => undefined);\n    await process.kill().catch(() => undefined);\n    await stderr.catch(() => undefined);\n    throw cause;\n  }\n  const first = buffered.subarray(newline + 1);\n  return new ReadableStream<Uint8Array>({\n    start: (controller) => {\n      if (first.length > 0) controller.enqueue(first);\n    },\n    pull: async (controller) => {\n      try {\n        const next = await reader.read();\n        if (!next.done) {\n          controller.enqueue(next.value);\n          return;\n        }\n        const result = await process.wait();\n        await stderr;\n        if (result.exitCode !== 0) controller.error(new Error('Confined file read failed'));\n        else controller.close();\n      } catch (cause) {\n        await reader.cancel().catch(() => undefined);\n        await process.kill().catch(() => undefined);\n        await stderr.catch(() => undefined);\n        controller.error(cause);\n      }\n    },\n    cancel: async () => {\n      await reader.cancel().catch(() => undefined);\n      await process.kill().catch(() => undefined);\n      await stderr.catch(() => undefined);\n    },\n  });\n};\n\n// Bind the fixed read scripts before narrowing the public process capability.\nexport const createConfinedFileReader = (\n  sandbox: Pick<SandboxSessionIface, 'run' | 'spawn'>,\n): ConfinedSandboxFilesIface => ({\n  readFile: (options) => confinedReadFile(sandbox, options),\n  stat: (options) => confinedStat(sandbox, options),\n  readDir: (options) => confinedReadDir(sandbox, options),\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/sandbox/convenience.d.mts

@@ -0,0 +1,10 @@
+import { type SandboxProcessOptionsIface, type SandboxRunResultIface, type SandboxSessionIface } from "./types.mjs";
+export declare const streamToBytes: (stream: ReadableStream<Uint8Array>) => Promise<Uint8Array>;
+export declare const streamToString: (stream: ReadableStream<Uint8Array>, encoding?: string) => Promise<string>;
+export declare const stringToStream: (text: string) => ReadableStream<Uint8Array>;
+export declare const runCollect: (sandbox: Pick<SandboxSessionIface, "spawn">, options: SandboxProcessOptionsIface) => Promise<SandboxRunResultIface>;
+export declare const readTextFileStream: (stream: ReadableStream<Uint8Array>, options?: Omit<Parameters<SandboxSessionIface["readTextFile"]>[0], "path">) => Promise<string>;
+export declare const readAllText: (sandbox: Pick<SandboxSessionIface, "readFile">, path: string) => Promise<string | null>;
+export declare const writeText: (sandbox: Pick<SandboxSessionIface, "writeFile">, path: string, text: string) => Promise<void>;
+export declare const exists: (sandbox: Pick<SandboxSessionIface, "stat">, path: string) => Promise<boolean>;
+export declare const ensureDir: (sandbox: Pick<SandboxSessionIface, "stat" | "run">, path: string) => Promise<void>;

package/dist/modules/sandbox/convenience.mjs

@@ -0,0 +1,116 @@
+import { bytesToStream, decodeSandboxText, readAllBytes, utf8Decode, utf8Encode } from "./bytes.mjs";
+import {
+  SandboxEntryType
+} from "./types.mjs";
+const streamToBytes = (stream) => readAllBytes(stream);
+const streamToString = async (stream, encoding = "utf-8") => {
+  const bytes = await readAllBytes(stream);
+  return encoding === "utf-8" || encoding === "utf8" ? utf8Decode(bytes) : new TextDecoder(encoding).decode(bytes);
+};
+const stringToStream = (text) => bytesToStream(utf8Encode(text));
+const runCollect = async (sandbox, options) => {
+  const process = await sandbox.spawn({ ...options, stdin: options.stdin ?? "" });
+  const output = Promise.all([
+    streamToString(process.stdout),
+    streamToString(process.stderr),
+    process.wait()
+  ]);
+  void output.catch(() => void 0);
+  try {
+    const [stdout, stderr, result] = await output;
+    return { exitCode: result.exitCode, stdout, stderr };
+  } catch (cause) {
+    await process.kill().catch(() => void 0);
+    throw cause;
+  }
+};
+const readTextFileStream = async (stream, options = {}) => {
+  if (options.abortSignal?.aborted === true) {
+    await stream.cancel().catch(() => void 0);
+    options.abortSignal.throwIfAborted();
+  }
+  const encoding = options.encoding ?? "utf-8";
+  const name = encoding.toLowerCase().replaceAll("-", "");
+  if (["base64", "base64url", "hex", "ascii", "latin1", "binary"].includes(name)) {
+    const text = decodeSandboxText(await readAllBytes(stream, options.abortSignal), encoding);
+    options.abortSignal?.throwIfAborted();
+    if (options.startLine == null && options.endLine == null) return text;
+    return (text.match(/[^\n]*\n|[^\n]+$/g) ?? []).slice(Math.max(1, options.startLine ?? 1) - 1, options.endLine).join("");
+  }
+  const decoderName = name === "utf8" ? "utf-8" : name === "ucs2" || name === "utf16le" ? "utf-16le" : name === "utf16be" ? "utf-16be" : encoding;
+  let decoder;
+  try {
+    decoder = new TextDecoder(decoderName);
+  } catch (cause) {
+    await stream.cancel().catch(() => void 0);
+    throw cause;
+  }
+  const reader = stream.getReader();
+  const cancel = () => {
+    void reader.cancel().catch(() => void 0);
+  };
+  options.abortSignal?.addEventListener("abort", cancel, { once: true });
+  if (options.abortSignal?.aborted === true) cancel();
+  const result = [];
+  const start = Math.max(1, options.startLine ?? 1);
+  const end = options.endLine;
+  let line = 1;
+  let partial = "";
+  try {
+    for (; ; ) {
+      const next = await reader.read();
+      options.abortSignal?.throwIfAborted();
+      const text = next.done ? decoder.decode() : decoder.decode(next.value, { stream: true });
+      if (options.startLine == null && end == null) {
+        result.push(text);
+        if (next.done) return result.join("");
+        continue;
+      }
+      partial += text;
+      let newline = partial.indexOf("\n");
+      while (newline >= 0) {
+        if (line >= start && (end == null || line <= end))
+          result.push(partial.slice(0, newline + 1));
+        line += 1;
+        partial = partial.slice(newline + 1);
+        if (end != null && line > end) return result.join("");
+        newline = partial.indexOf("\n");
+      }
+      if (next.done) {
+        if (partial.length > 0 && line >= start && (end == null || line <= end))
+          result.push(partial);
+        return result.join("");
+      }
+    }
+  } finally {
+    options.abortSignal?.removeEventListener("abort", cancel);
+    await reader.cancel().catch(() => void 0);
+    reader.releaseLock();
+  }
+};
+const readAllText = async (sandbox, path) => {
+  const stream = await sandbox.readFile({ path });
+  return stream == null ? null : streamToString(stream);
+};
+const writeText = (sandbox, path, text) => sandbox.writeFile({ path, content: stringToStream(text) });
+const exists = async (sandbox, path) => await sandbox.stat({ path }) != null;
+const ensureDir = async (sandbox, path) => {
+  const stat = await sandbox.stat({ path });
+  if (stat?.type === SandboxEntryType.Directory) return;
+  if (stat != null)
+    throw Object.assign(new Error(`${path} exists and is not a directory`), { code: "EEXIST" });
+  const result = await sandbox.run({ command: "mkdir", args: ["-p", path] });
+  if (result.exitCode !== 0) throw new Error(`mkdir -p ${path} failed: ${result.stderr.trim()}`);
+};
+export {
+  ensureDir,
+  exists,
+  readAllText,
+  readTextFileStream,
+  runCollect,
+  streamToBytes,
+  streamToString,
+  stringToStream,
+  writeText
+};
+//# sourceMappingURL=convenience.mjs.map

package/dist/modules/sandbox/convenience.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/sandbox/convenience.ts"],
+  "sourcesContent": ["import { bytesToStream, decodeSandboxText, readAllBytes, utf8Decode, utf8Encode } from \"./bytes.mjs\";\nimport {\n  SandboxEntryType,\n  type SandboxProcessOptionsIface,\n  type SandboxRunResultIface,\n  type SandboxSessionIface,\n} from \"./types.mjs\";\n\n// Conveniences over the streaming primitives. Everything\n// here is expressed in SandboxSessionIface terms, so it works on any provider.\n\nexport const streamToBytes = (stream: ReadableStream<Uint8Array>): Promise<Uint8Array> =>\n  readAllBytes(stream);\n\nexport const streamToString = async (\n  stream: ReadableStream<Uint8Array>,\n  encoding = 'utf-8',\n): Promise<string> => {\n  const bytes = await readAllBytes(stream);\n  return encoding === 'utf-8' || encoding === 'utf8'\n    ? utf8Decode(bytes)\n    : new TextDecoder(encoding).decode(bytes);\n};\n\nexport const stringToStream = (text: string): ReadableStream<Uint8Array> =>\n  bytesToStream(utf8Encode(text));\n\n// Spawn, collect both streams and wait: `run` in terms of `spawn`.\nexport const runCollect = async (\n  sandbox: Pick<SandboxSessionIface, 'spawn'>,\n  options: SandboxProcessOptionsIface,\n): Promise<SandboxRunResultIface> => {\n  const process = await sandbox.spawn({ ...options, stdin: options.stdin ?? '' });\n  const output = Promise.all([\n    streamToString(process.stdout),\n    streamToString(process.stderr),\n    process.wait(),\n  ]);\n  void output.catch(() => undefined);\n  try {\n    const [stdout, stderr, result] = await output;\n    return { exitCode: result.exitCode, stdout, stderr };\n  } catch (cause) {\n    await process.kill().catch(() => undefined);\n    throw cause;\n  }\n};\n\n// Read line ranges from the stream, retaining their original line endings.\nexport const readTextFileStream = async (\n  stream: ReadableStream<Uint8Array>,\n  options: Omit<Parameters<SandboxSessionIface['readTextFile']>[0], 'path'> = {},\n): Promise<string> => {\n  if (options.abortSignal?.aborted === true) {\n    await stream.cancel().catch(() => undefined);\n    options.abortSignal.throwIfAborted();\n  }\n  const encoding = options.encoding ?? 'utf-8';\n  const name = encoding.toLowerCase().replaceAll('-', '');\n  if (['base64', 'base64url', 'hex', 'ascii', 'latin1', 'binary'].includes(name)) {\n    const text = decodeSandboxText(await readAllBytes(stream, options.abortSignal), encoding);\n    options.abortSignal?.throwIfAborted();\n    if (options.startLine == null && options.endLine == null) return text;\n    return (text.match(/[^\\n]*\\n|[^\\n]+$/g) ?? [])\n      .slice(Math.max(1, options.startLine ?? 1) - 1, options.endLine)\n      .join('');\n  }\n  const decoderName =\n    name === 'utf8'\n      ? 'utf-8'\n      : name === 'ucs2' || name === 'utf16le'\n        ? 'utf-16le'\n        : name === 'utf16be'\n          ? 'utf-16be'\n          : encoding;\n  let decoder: TextDecoder;\n  try {\n    decoder = new TextDecoder(decoderName);\n  } catch (cause) {\n    await stream.cancel().catch(() => undefined);\n    throw cause;\n  }\n  const reader = stream.getReader();\n  const cancel = () => {\n    void reader.cancel().catch(() => undefined);\n  };\n  options.abortSignal?.addEventListener('abort', cancel, { once: true });\n  if (options.abortSignal?.aborted === true) cancel();\n  const result: string[] = [];\n  const start = Math.max(1, options.startLine ?? 1);\n  const end = options.endLine;\n  let line = 1;\n  let partial = '';\n  try {\n    for (;;) {\n      const next = await reader.read();\n      options.abortSignal?.throwIfAborted();\n      const text = next.done ? decoder.decode() : decoder.decode(next.value, { stream: true });\n      if (options.startLine == null && end == null) {\n        result.push(text);\n        if (next.done) return result.join('');\n        continue;\n      }\n      partial += text;\n      let newline = partial.indexOf('\\n');\n      while (newline >= 0) {\n        if (line >= start && (end == null || line <= end))\n          result.push(partial.slice(0, newline + 1));\n        line += 1;\n        partial = partial.slice(newline + 1);\n        if (end != null && line > end) return result.join('');\n        newline = partial.indexOf('\\n');\n      }\n      if (next.done) {\n        if (partial.length > 0 && line >= start && (end == null || line <= end))\n          result.push(partial);\n        return result.join('');\n      }\n    }\n  } finally {\n    options.abortSignal?.removeEventListener('abort', cancel);\n    await reader.cancel().catch(() => undefined);\n    reader.releaseLock();\n  }\n};\n\nexport const readAllText = async (\n  sandbox: Pick<SandboxSessionIface, 'readFile'>,\n  path: string,\n): Promise<string | null> => {\n  const stream = await sandbox.readFile({ path });\n  return stream == null ? null : streamToString(stream);\n};\n\nexport const writeText = (\n  sandbox: Pick<SandboxSessionIface, 'writeFile'>,\n  path: string,\n  text: string,\n): Promise<void> => sandbox.writeFile({ path, content: stringToStream(text) });\n\nexport const exists = async (\n  sandbox: Pick<SandboxSessionIface, 'stat'>,\n  path: string,\n): Promise<boolean> => (await sandbox.stat({ path })) != null;\n\n// Creates a directory and its parents. Uses `mkdir -p`, the only portable way\n// to create an empty directory through the handle (writes create parents).\nexport const ensureDir = async (\n  sandbox: Pick<SandboxSessionIface, 'stat' | 'run'>,\n  path: string,\n): Promise<void> => {\n  const stat = await sandbox.stat({ path });\n  if (stat?.type === SandboxEntryType.Directory) return;\n  if (stat != null)\n    throw Object.assign(new Error(`${path} exists and is not a directory`), { code: 'EEXIST' });\n  const result = await sandbox.run({ command: 'mkdir', args: ['-p', path] });\n  if (result.exitCode !== 0) throw new Error(`mkdir -p ${path} failed: ${result.stderr.trim()}`);\n};\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/sandbox/editor.d.mts

@@ -0,0 +1,49 @@
+import * as z from 'zod';
+export declare enum SandboxEditorOperation {
+    Available = "available",
+    Open = "open",
+    Refresh = "refresh",
+    Close = "close"
+}
+export declare const sandboxEditorRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<SandboxEditorOperation.Available>;
+}, z.core.$strip>, z.ZodObject<{
+    operation: z.ZodLiteral<SandboxEditorOperation.Open>;
+}, z.core.$strip>, z.ZodObject<{
+    operation: z.ZodLiteral<SandboxEditorOperation.Refresh>;
+    id: z.ZodString;
+    authorizationId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    operation: z.ZodLiteral<SandboxEditorOperation.Close>;
+    id: z.ZodString;
+    authorizationId: z.ZodString;
+}, z.core.$strip>], "operation">;
+export type SandboxEditorRequestIface = z.infer<typeof sandboxEditorRequestSchema>;
+export declare const sandboxEditorSessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    authorizationId: z.ZodString;
+    workingDirectory: z.ZodString;
+    url: z.ZodString;
+    expiresAt: z.ZodString;
+    authentication: z.ZodObject<{
+        url: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SandboxEditorSessionIface = z.infer<typeof sandboxEditorSessionSchema>;
+export declare const sandboxEditorResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    id: z.ZodString;
+    authorizationId: z.ZodString;
+    workingDirectory: z.ZodString;
+    url: z.ZodString;
+    expiresAt: z.ZodString;
+    authentication: z.ZodObject<{
+        url: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    available: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    closed: z.ZodLiteral<true>;
+}, z.core.$strip>]>;
+export type SandboxEditorResultIface = z.infer<typeof sandboxEditorResultSchema>;

package/dist/modules/sandbox/editor.mjs

@@ -0,0 +1,43 @@
+import * as z from "zod";
+var SandboxEditorOperation = /* @__PURE__ */ ((SandboxEditorOperation2) => {
+  SandboxEditorOperation2["Available"] = "available";
+  SandboxEditorOperation2["Open"] = "open";
+  SandboxEditorOperation2["Refresh"] = "refresh";
+  SandboxEditorOperation2["Close"] = "close";
+  return SandboxEditorOperation2;
+})(SandboxEditorOperation || {});
+const sandboxEditorRequestSchema = z.discriminatedUnion("operation", [
+  z.object({ operation: z.literal("available" /* Available */) }),
+  z.object({ operation: z.literal("open" /* Open */) }),
+  z.object({
+    operation: z.literal("refresh" /* Refresh */),
+    id: z.string().min(1).max(256),
+    authorizationId: z.string().min(1).max(256)
+  }),
+  z.object({
+    operation: z.literal("close" /* Close */),
+    id: z.string().min(1).max(256),
+    authorizationId: z.string().min(1).max(256)
+  })
+]);
+const sandboxEditorSessionSchema = z.object({
+  id: z.string(),
+  authorizationId: z.string(),
+  workingDirectory: z.string(),
+  url: z.string().url(),
+  expiresAt: z.string(),
+  /** Post these fields to the authentication URL in the editor's browser frame. */
+  authentication: z.object({ url: z.string().url(), fields: z.record(z.string(), z.string()) })
+});
+const sandboxEditorResultSchema = z.union([
+  sandboxEditorSessionSchema,
+  z.object({ available: z.boolean() }),
+  z.object({ closed: z.literal(true) })
+]);
+export {
+  SandboxEditorOperation,
+  sandboxEditorRequestSchema,
+  sandboxEditorResultSchema,
+  sandboxEditorSessionSchema
+};
+//# sourceMappingURL=editor.mjs.map

package/dist/modules/sandbox/editor.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/sandbox/editor.ts"],
+  "sourcesContent": ["import * as z from 'zod';\n\nexport enum SandboxEditorOperation {\n  Available = 'available',\n  Open = 'open',\n  Refresh = 'refresh',\n  Close = 'close',\n}\n\nexport const sandboxEditorRequestSchema = z.discriminatedUnion('operation', [\n  z.object({ operation: z.literal(SandboxEditorOperation.Available) }),\n  z.object({ operation: z.literal(SandboxEditorOperation.Open) }),\n  z.object({\n    operation: z.literal(SandboxEditorOperation.Refresh),\n    id: z.string().min(1).max(256),\n    authorizationId: z.string().min(1).max(256),\n  }),\n  z.object({\n    operation: z.literal(SandboxEditorOperation.Close),\n    id: z.string().min(1).max(256),\n    authorizationId: z.string().min(1).max(256),\n  }),\n]);\nexport type SandboxEditorRequestIface = z.infer<typeof sandboxEditorRequestSchema>;\n\nexport const sandboxEditorSessionSchema = z.object({\n  id: z.string(),\n  authorizationId: z.string(),\n  workingDirectory: z.string(),\n  url: z.string().url(),\n  expiresAt: z.string(),\n  /** Post these fields to the authentication URL in the editor's browser frame. */\n  authentication: z.object({ url: z.string().url(), fields: z.record(z.string(), z.string()) }),\n});\nexport type SandboxEditorSessionIface = z.infer<typeof sandboxEditorSessionSchema>;\n\nexport const sandboxEditorResultSchema = z.union([\n  sandboxEditorSessionSchema,\n  z.object({ available: z.boolean() }),\n  z.object({ closed: z.literal(true) }),\n]);\nexport type SandboxEditorResultIface = z.infer<typeof sandboxEditorResultSchema>;\n"],
+  "mappings": "AAAA,YAAY,OAAO;AAEZ,IAAK,yBAAL,kBAAKA,4BAAL;AACL,EAAAA,wBAAA,eAAY;AACZ,EAAAA,wBAAA,UAAO;AACP,EAAAA,wBAAA,aAAU;AACV,EAAAA,wBAAA,WAAQ;AAJE,SAAAA;AAAA,GAAA;AAOL,MAAM,6BAA6B,EAAE,mBAAmB,aAAa;AAAA,EAC1E,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,2BAAgC,EAAE,CAAC;AAAA,EACnE,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,iBAA2B,EAAE,CAAC;AAAA,EAC9D,EAAE,OAAO;AAAA,IACP,WAAW,EAAE,QAAQ,uBAA8B;AAAA,IACnD,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG;AAAA,IAC7B,iBAAiB,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG;AAAA,EAC5C,CAAC;AAAA,EACD,EAAE,OAAO;AAAA,IACP,WAAW,EAAE,QAAQ,mBAA4B;AAAA,IACjD,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG;AAAA,IAC7B,iBAAiB,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG;AAAA,EAC5C,CAAC;AACH,CAAC;AAGM,MAAM,6BAA6B,EAAE,OAAO;AAAA,EACjD,IAAI,EAAE,OAAO;AAAA,EACb,iBAAiB,EAAE,OAAO;AAAA,EAC1B,kBAAkB,EAAE,OAAO;AAAA,EAC3B,KAAK,EAAE,OAAO,EAAE,IAAI;AAAA,EACpB,WAAW,EAAE,OAAO;AAAA;AAAA,EAEpB,gBAAgB,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAG,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC;AAC9F,CAAC;AAGM,MAAM,4BAA4B,EAAE,MAAM;AAAA,EAC/C;AAAA,EACA,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AAAA,EACnC,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,IAAI,EAAE,CAAC;AACtC,CAAC;",
+  "names": ["SandboxEditorOperation"]
+}

package/dist/modules/sandbox/frame-channel.d.mts

@@ -0,0 +1,47 @@
+export type WireFrame = string | Uint8Array;
+export interface FrameChannelCloseIface {
+    code: number;
+    reason: string;
+}
+export interface FrameChannelHandlersIface {
+    frame: (frame: WireFrame) => void;
+    close: (info: FrameChannelCloseIface) => void;
+}
+export interface FrameChannelIface {
+    send(frame: WireFrame): void;
+    close(code?: number, reason?: string): void;
+    listen(handlers: FrameChannelHandlersIface): void;
+}
+export type WebSocketMessageData = string | ArrayBuffer | ArrayBufferView | Blob | Uint8Array[];
+export interface WebSocketMessageEventLikeIface {
+    readonly data: WebSocketMessageData;
+}
+export interface WebSocketEventLikeIface {
+    readonly type: string;
+}
+export interface WebSocketCloseEventLikeIface {
+    readonly code: number;
+    readonly reason: string;
+}
+export interface WebSocketLikeIface {
+    readonly readyState: number;
+    binaryType: string;
+    send(data: string | Uint8Array<ArrayBuffer>): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'message', listener: (event: WebSocketMessageEventLikeIface) => void): void;
+    addEventListener(type: 'close', listener: (event: WebSocketCloseEventLikeIface) => void): void;
+    addEventListener(type: 'open', listener: (event: WebSocketEventLikeIface) => void): void;
+    addEventListener(type: 'error', listener: (event: WebSocketEventLikeIface) => void): void;
+}
+export type WebSocketConstructorIface = new (url: string, protocols?: string | string[]) => WebSocketLikeIface;
+export interface WebSocketFrameChannelIface {
+    channel: FrameChannelIface;
+    opened: Promise<void>;
+}
+export declare const frameChannelFromWebSocket: (socket: WebSocketLikeIface) => WebSocketFrameChannelIface;
+export interface FrameStreamIface {
+    readable: ReadableStream<WireFrame>;
+    writable: WritableStream<WireFrame>;
+}
+export declare const frameChannelFromStream: (stream: FrameStreamIface) => FrameChannelIface;
+export declare const createFrameChannelPair: () => [FrameChannelIface, FrameChannelIface];

package/dist/modules/sandbox/frame-channel.mjs

@@ -0,0 +1,153 @@
+const ABNORMAL_CLOSE = 1006;
+const createBufferedListener = () => {
+  const pending = [];
+  let closed = null;
+  let handlers = null;
+  return {
+    frame: (frame) => {
+      if (handlers == null) pending.push(frame);
+      else handlers.frame(frame);
+    },
+    close: (info) => {
+      if (closed != null) return;
+      closed = info;
+      handlers?.close(info);
+    },
+    listen: (next) => {
+      handlers = next;
+      for (const frame of pending.splice(0)) next.frame(frame);
+      if (closed != null) next.close(closed);
+    },
+    isClosed: () => closed != null
+  };
+};
+const WS_OPEN = 1;
+const toWireFrame = (data) => {
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data))
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  if (data instanceof Blob) return null;
+  if (Array.isArray(data)) {
+    let total = 0;
+    for (const part of data) total += part.byteLength;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of data) {
+      out.set(part, offset);
+      offset += part.byteLength;
+    }
+    return out;
+  }
+  return data;
+};
+const frameChannelFromWebSocket = (socket) => {
+  socket.binaryType = "arraybuffer";
+  const listener = createBufferedListener();
+  let resolveOpen = () => void 0;
+  let rejectOpen = () => void 0;
+  const opened = new Promise((resolve, reject) => {
+    resolveOpen = resolve;
+    rejectOpen = reject;
+  });
+  opened.catch(() => void 0);
+  if (socket.readyState === WS_OPEN) resolveOpen();
+  socket.addEventListener("open", () => resolveOpen());
+  socket.addEventListener("message", (event) => {
+    const frame = toWireFrame(event.data);
+    if (frame != null) listener.frame(frame);
+  });
+  socket.addEventListener("close", (event) => {
+    rejectOpen(new Error(`websocket closed before opening (${event.code})`));
+    listener.close({ code: event.code, reason: event.reason });
+  });
+  socket.addEventListener("error", () => {
+    rejectOpen(new Error("websocket failed to open"));
+  });
+  const channel = {
+    send: (frame) => {
+      if (socket.readyState !== WS_OPEN) return;
+      if (!(frame instanceof Uint8Array)) socket.send(frame);
+      else if (frame.buffer instanceof ArrayBuffer)
+        socket.send(new Uint8Array(frame.buffer, frame.byteOffset, frame.byteLength));
+      else socket.send(new Uint8Array(frame));
+    },
+    close: (code, reason) => {
+      try {
+        socket.close(code, reason);
+      } catch {
+        socket.close();
+      }
+      listener.close({ code: code ?? 1e3, reason: reason ?? "" });
+    },
+    listen: (handlers) => listener.listen(handlers)
+  };
+  return { channel, opened };
+};
+const frameChannelFromStream = (stream) => {
+  const listener = createBufferedListener();
+  const writer = stream.writable.getWriter();
+  const reader = stream.readable.getReader();
+  const pump = async () => {
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        listener.frame(value);
+      }
+      listener.close({ code: 1e3, reason: "" });
+    } catch (error) {
+      listener.close({
+        code: ABNORMAL_CLOSE,
+        reason: error instanceof Error ? error.message : "stream error"
+      });
+    }
+  };
+  void pump();
+  return {
+    send: (frame) => {
+      if (listener.isClosed()) return;
+      writer.write(frame).catch(() => listener.close({ code: ABNORMAL_CLOSE, reason: "write failed" }));
+    },
+    close: (code, reason) => {
+      if (listener.isClosed()) return;
+      listener.close({ code: code ?? 1e3, reason: reason ?? "" });
+      writer.close().catch(() => void 0);
+      reader.cancel().catch(() => void 0);
+    },
+    listen: (handlers) => listener.listen(handlers)
+  };
+};
+const createFrameChannelPair = () => {
+  const left = createBufferedListener();
+  const right = createBufferedListener();
+  const deliver = (target, frame) => {
+    queueMicrotask(() => target.frame(frame));
+  };
+  const closeBoth = (info) => {
+    queueMicrotask(() => {
+      left.close(info);
+      right.close(info);
+    });
+  };
+  let closed = false;
+  const make = (peer, self) => ({
+    send: (frame) => {
+      if (closed) return;
+      deliver(peer, frame instanceof Uint8Array ? frame.slice() : frame);
+    },
+    close: (code, reason) => {
+      if (closed) return;
+      closed = true;
+      closeBoth({ code: code ?? 1e3, reason: reason ?? "" });
+    },
+    listen: (handlers) => self.listen(handlers)
+  });
+  return [make(right, left), make(left, right)];
+};
+export {
+  createFrameChannelPair,
+  frameChannelFromStream,
+  frameChannelFromWebSocket
+};
+//# sourceMappingURL=frame-channel.mjs.map