@lamplitisles/dsh-nanocodex 0.1.0-beta.0

package/vendor/nanocodex/tools/browser/index.d.mts

@@ -0,0 +1,209 @@
+import type { Workspace } from "../../runtime/workspace.mjs";
+import type { NamedTool } from "../../types.mjs";
+import type { JustBashDescriptor } from "../bash.mjs";
+import type { DatasetOptions, JsonToolOptions } from "../index.mjs";
+
+export type BrowserThread = Readonly<{
+  id: string;
+  workspaceName: string;
+  repositoryName: string;
+  branch: "nanocodex";
+  remoteUrl: string;
+  shareUrl: string;
+}>;
+
+export type ThreadGitStatus = Readonly<{
+  branch: "nanocodex";
+  head?: string | undefined;
+  changes: string[];
+  remoteUrl: string;
+}>;
+
+export type OpfsFileStat = Readonly<{
+  size: number;
+  mtimeMs: number;
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): false;
+}>;
+
+export type OpfsDirectoryEntry = Readonly<{
+  name: string;
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): false;
+}>;
+
+export type OpfsGitFs = Readonly<{
+  promises: Readonly<{
+    readFile(path: string): Promise<Uint8Array>;
+    readFile(path: string, options: string | { encoding: string; maxBytes?: number }): Promise<string>;
+    readFile(path: string, options: { maxBytes: number; encoding?: undefined }): Promise<Uint8Array>;
+    writeFile(path: string, value: string | Uint8Array): Promise<void>;
+    appendFile(path: string, value: string | Uint8Array): Promise<void>;
+    unlink(path: string): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<OpfsDirectoryEntry[]>;
+    mkdir(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rm(path: string, options?: { recursive?: boolean }): Promise<void>;
+    stat(path: string): Promise<OpfsFileStat>;
+    lstat(path: string): Promise<OpfsFileStat>;
+    readlink(path: string): Promise<never>;
+    symlink(target: string, path: string): Promise<never>;
+  }>;
+}>;
+
+export type BrowserCommandResult = Readonly<{
+  output: string;
+  wall_time_seconds: number;
+  exit_code: number;
+  original_token_count?: number | undefined;
+}>;
+
+export type BrowserBashResult = Readonly<{
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  env: Record<string, string>;
+}>;
+
+export type BrowserBash = {
+  exec(
+    script: string,
+    options?: Readonly<{
+      cwd?: string | undefined;
+      env?: Record<string, string> | undefined;
+      replaceEnv?: boolean | undefined;
+      rawScript?: boolean | undefined;
+      stdin?: string | undefined;
+      stdinKind?: "text" | "bytes" | undefined;
+      signal?: AbortSignal | undefined;
+      args?: string[] | undefined;
+    }>,
+  ): Promise<BrowserBashResult>;
+};
+
+export type BrowserShellStat = Readonly<{
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymbolicLink: boolean;
+  mode: number;
+  size: number;
+  mtime: Date;
+}>;
+
+export type BrowserShellFileSystem = {
+  readonly mutationVersion: number;
+  refreshPaths(): Promise<void>;
+  recordExternalWrite(path: string): void;
+  recordExternalRemove(path: string): void;
+  recordRepositoryMutation(): void;
+  readFile(path: string, options?: string | { encoding?: string }): Promise<string>;
+  readFileBytes(path: string): Promise<string>;
+  readFileBuffer(path: string): Promise<Uint8Array>;
+  writeFile(path: string, content: string | Uint8Array, options?: string): Promise<void>;
+  appendFile(path: string, content: string | Uint8Array, options?: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<BrowserShellStat>;
+  mkdir(path: string): Promise<void>;
+  readdir(path: string): Promise<string[]>;
+  readdirWithFileTypes(path: string): Promise<OpfsDirectoryEntry[]>;
+  rm(path: string, options?: { force?: boolean; recursive?: boolean }): Promise<void>;
+  cp(src: string, dest: string, options?: { recursive?: boolean }): Promise<void>;
+  mv(src: string, dest: string): Promise<void>;
+  resolvePath(base: string, path: string): string;
+  getAllPaths(): string[];
+  chmod(path: string, mode: number): Promise<void>;
+  symlink(target: string, linkPath: string): Promise<never>;
+  link(existingPath: string, newPath: string): Promise<never>;
+  readlink(path: string): Promise<never>;
+  lstat(path: string): Promise<BrowserShellStat>;
+  realpath(path: string): Promise<string>;
+  utimes(path: string, atime: Date | number, mtime: Date | number): Promise<void>;
+};
+
+export type BrowserOptions = Readonly<{
+  threadId: string;
+  origin?: string | undefined;
+  fetch?: typeof globalThis.fetch | undefined;
+  headers?: HeadersInit | undefined;
+  installFetch?: boolean | undefined;
+  /** Exposes a tool that returns provider authorization links for account connections. */
+  accountConnectionRequests?: boolean | undefined;
+  accountInfo?: Readonly<{
+    endpoint?: string | undefined;
+    requireAuthorization?: boolean | undefined;
+  }> | undefined;
+  web?: JsonToolOptions | undefined;
+  images?: JsonToolOptions | undefined;
+  dataset?: DatasetOptions | undefined;
+  recentImages?(sessionId: string, count: number): string[];
+  rememberImage?(sessionId: string, imageUrl: string): void;
+}>;
+
+export type BrowserTools = Readonly<{
+  filesystem: Workspace;
+  instructions: string;
+  projectInstructions?: string | undefined;
+  tools: readonly NamedTool[];
+}>;
+
+/** Thread-scoped OPFS, Git, shell, and module state reusable across Agent starts. */
+export type PreparedBrowser = Readonly<{
+  origin: string;
+  threadId: string;
+}>;
+
+/** Opens a persistent OPFS workspace and composes its WASM-backed tools. */
+export function browser(options: BrowserOptions): Promise<BrowserTools>;
+export function prepareBrowser(
+  options: Pick<BrowserOptions, "threadId" | "origin">,
+): Promise<PreparedBrowser>;
+export function bindBrowser(prepared: PreparedBrowser, options: BrowserOptions): BrowserTools;
+
+export function browserThread(threadId: string, origin: string): BrowserThread;
+export function getBrowserThread(): BrowserThread;
+export function selectBrowserThread(threadId: string): BrowserThread;
+export function openKernelWorkspace(): Promise<Workspace>;
+export function openThreadWorkspace(threadId: string): Promise<Workspace>;
+export function subscribeThreadWorkspaceChanges(threadId: string, listener: () => void): () => void;
+
+export function openOpfsWorkspaceRoot(workspaceName: string): Promise<FileSystemDirectoryHandle>;
+export function openOpfsGitFs(workspaceName: string): Promise<OpfsGitFs>;
+export function createOpfsGitFs(root: FileSystemDirectoryHandle): OpfsGitFs;
+
+export function initializeThreadGit(thread: BrowserThread): Promise<ThreadGitStatus>;
+export function inspectThreadGit<T>(thread: BrowserThread, inspect: (fs: OpfsGitFs) => Promise<T>): Promise<T>;
+export function threadGitStatus(thread: BrowserThread): Promise<ThreadGitStatus>;
+export function commitAndPushThread(
+  thread: BrowserThread,
+  message?: string,
+  notificationSource?: string,
+): Promise<ThreadGitStatus>;
+export function pullThread(thread: BrowserThread, notificationSource?: string): Promise<ThreadGitStatus>;
+export function subscribeThreadGitChanges(thread: BrowserThread, listener: (source?: string) => void): () => void;
+export function notifyThreadGitChanged(thread: BrowserThread, source?: string): void;
+export function withThreadGitLock<T>(
+  thread: BrowserThread,
+  operation: () => Promise<T>,
+  signal?: AbortSignal,
+): Promise<T>;
+
+export function loadBrowserProjectInstructions(rawFs: OpfsGitFs): Promise<string | undefined>;
+export function validateBrowserArtifactSource(source: string): Promise<void>;
+export function createBrowserBash(
+  rawFs: OpfsGitFs,
+  thread: BrowserThread,
+  options?: Record<string, unknown>,
+): Promise<{
+  bash: BrowserBash;
+  descriptor: JustBashDescriptor;
+  filesystem: BrowserShellFileSystem;
+  instructions: string;
+  tool: NamedTool;
+  exec(
+    input: Record<string, unknown>,
+    context?: { signal?: AbortSignal },
+  ): Promise<BrowserCommandResult>;
+}>;

package/vendor/nanocodex/tools/browser/index.mjs

@@ -0,0 +1,174 @@
+import "./browserBuffer.mjs";
+import { browseX } from "../../../nanocodex-tools/tools/x.mjs";
+import {
+  createBrowserEgressFetch,
+  createBrowserRuntimeFetch,
+  installBrowserEgressFetch,
+} from "./browserEgress.mjs";
+import {
+  browserAccountConnectionTool,
+  browserAccountInfoTool,
+  browserRuntimeInfoTool,
+} from "./accountInfo.mjs";
+
+const preparedBrowsers = new Map();
+const ACCOUNT_CONNECTION_INSTRUCTIONS = "Use requestAccountConnection when the user asks to connect or authenticate GitHub, a Google Workspace service, Slack, or X. For authorization_required results, return the exact authorization_url as a Markdown link. Never claim the account is connected until a later accountInfo call reports it as authenticated.";
+
+export {
+  createOpfsGitFs,
+  openOpfsGitFs,
+  openOpfsWorkspaceRoot,
+} from "./opfsGit.mjs";
+export {
+  browserThread,
+  commitAndPushThread,
+  initializeThreadGit,
+  inspectThreadGit,
+  notifyThreadGitChanged,
+  pullThread,
+  subscribeThreadGitChanges,
+  threadGitStatus,
+  withThreadGitLock,
+} from "./threadGit.mjs";
+export {
+  getBrowserThread,
+  selectBrowserThread,
+  openKernelWorkspace,
+  openThreadWorkspace,
+  subscribeThreadWorkspaceChanges,
+} from "./workspace.mjs";
+
+export async function browser(options) {
+  const prepared = options?.prepared ?? await prepareBrowser(options);
+  return bindBrowser(prepared, options);
+}
+
+export function prepareBrowser(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("browser tool options must be an object");
+  }
+  const origin = options.origin ?? globalThis.location?.origin;
+  if (typeof options.threadId !== "string" || !options.threadId) {
+    throw new TypeError("browser threadId must be a non-empty string");
+  }
+  if (typeof origin !== "string" || !origin) {
+    throw new TypeError("browser origin is required outside a browser location");
+  }
+  if (options.installFetch === false) {
+    return prepareBrowserRuntime(options.threadId, origin, options);
+  }
+  const key = `${origin}\n${options.threadId}`;
+  let prepared = preparedBrowsers.get(key);
+  prepared ??= prepareBrowserRuntime(options.threadId, origin, options).catch((error) => {
+    preparedBrowsers.delete(key);
+    throw error;
+  });
+  preparedBrowsers.set(key, prepared);
+  return prepared;
+}
+
+async function prepareBrowserRuntime(threadId, origin, options) {
+  const [shellModule, standard, datasets] = await Promise.all([
+    import("./browserShell.mjs"),
+    import("../standard.mjs"),
+    import("../dataset.mjs"),
+  ]);
+  const fetch = (options.installFetch === false
+    ? createBrowserRuntimeFetch
+    : installBrowserEgressFetch)({
+    fetch: options.fetch,
+    headers: options.headers,
+    origin,
+    threadId,
+  });
+  const secureFetch = createBrowserEgressFetch({ fetch, origin, threadId });
+  const shell = await shellModule.prepareBrowserShell(
+    threadId,
+    origin,
+    secureFetch,
+    options.headers,
+  );
+  return Object.freeze({
+    origin,
+    threadId,
+    fetch,
+    shell,
+    standard,
+    datasets,
+  });
+}
+
+export function bindBrowser(prepared, options = {}) {
+  if (!prepared || typeof prepared !== "object" || Array.isArray(prepared)) {
+    throw new TypeError("prepared browser runtime is required");
+  }
+  if (options.threadId !== undefined && options.threadId !== prepared.threadId) {
+    throw new Error("prepared browser runtime belongs to a different thread");
+  }
+  const { datasets, fetch, shell, standard } = prepared;
+  const web = {
+    url: new URL("/api/tools/web-search", prepared.origin),
+    fetch,
+    ...options.web,
+  };
+  const images = {
+    url: new URL("/api/tools/image-generation", prepared.origin),
+    fetch,
+    ...options.images,
+  };
+  const account = {
+    endpoint: options.accountInfo?.endpoint,
+    fetch,
+    origin: prepared.origin,
+    requireAuthorization: options.accountInfo?.requireAuthorization,
+  };
+  return Object.freeze({
+    filesystem: shell.workspace,
+    instructions: options.accountConnectionRequests
+      ? `${shell.instructions}\n\n${ACCOUNT_CONNECTION_INSTRUCTIONS}`
+      : shell.instructions,
+    projectInstructions: shell.projectInstructions,
+    tools: Object.freeze([
+      standard.namedTool("exec_command", shell.execTool),
+      browserRuntimeInfoTool(account, shell.descriptor),
+      browserAccountInfoTool(account),
+      ...(options.accountConnectionRequests ? [browserAccountConnectionTool(account)] : []),
+      browseX({
+        fetch: (input, init) => {
+          const source = new URL(input);
+          const url = new URL(`/api/tools/x/${source.pathname.slice("/api/".length)}`, prepared.origin);
+          url.search = source.search;
+          const headers = new Headers(init?.headers);
+          headers.set("x-nanocodex-request", "1");
+          return fetch(url, { ...init, headers, credentials: "same-origin" });
+        },
+      }),
+      standard.web(web),
+      standard.imageGeneration({
+        ...images,
+        recentImages: options.recentImages,
+        rememberImage: options.rememberImage,
+        workspace: shell.workspace,
+      }),
+      standard.viewImage({ workspace: shell.workspace }),
+      standard.updatePlan(),
+      datasets.dataset(options.dataset),
+      shell.artifactTool,
+    ]),
+  });
+}
+
+export async function createBrowserBash(rawFs, thread, options) {
+  const { createBrowserBash: create } = await import("./browserShell.mjs");
+  return create(rawFs, thread, options);
+}
+
+export async function loadBrowserProjectInstructions(rawFs) {
+  const { loadBrowserProjectInstructions: load } = await import("./browserShell.mjs");
+  return load(rawFs);
+}
+
+export async function validateBrowserArtifactSource(source) {
+  const { validateBrowserArtifactSource: validate } = await import("./browserShell.mjs");
+  return validate(source);
+}

package/vendor/nanocodex/tools/browser/opfsGit.mjs

@@ -0,0 +1,248 @@
+const WORKSPACE_DIRECTORY = "nanocodex-workspaces";
+export async function openOpfsWorkspaceRoot(workspaceName) {
+    if (!navigator.storage?.getDirectory) {
+        throw new Error("Origin Private File System storage is unavailable in this browser");
+    }
+    const origin = await navigator.storage.getDirectory();
+    const workspaces = await origin.getDirectoryHandle(WORKSPACE_DIRECTORY, { create: true });
+    return workspaces.getDirectoryHandle(encodeURIComponent(workspaceName), { create: true });
+}
+export async function openOpfsGitFs(workspaceName) {
+    return createOpfsGitFs(await openOpfsWorkspaceRoot(workspaceName));
+}
+export function createOpfsGitFs(root) {
+    return { promises: createPromises(root) };
+}
+function createPromises(root) {
+    return {
+        async readFile(path, options) {
+            const relative = normalize(path);
+            if (!relative)
+                throw fsError("EISDIR", "cannot read a directory");
+            try {
+                const { parent, name } = await parentHandle(root, relative, false);
+                const file = await (await parent.getFileHandle(name)).getFile();
+                const maxBytes = typeof options === "object" ? options.maxBytes : undefined;
+                const source = maxBytes === undefined ? file : file.slice(0, maxBytes);
+                let bytes = new Uint8Array(await source.arrayBuffer());
+                if (maxBytes !== undefined && bytes.byteLength > maxBytes) {
+                    bytes = bytes.subarray(0, maxBytes);
+                }
+                const encoding = typeof options === "string" ? options : options?.encoding;
+                return encoding ? new TextDecoder(encoding).decode(bytes) : bytes;
+            }
+            catch (error) {
+                throw translateError(error, "ENOENT", `cannot read ${relative}`);
+            }
+        },
+        async writeFile(path, value) {
+            const relative = normalize(path);
+            if (!relative)
+                throw fsError("EISDIR", "cannot write a directory");
+            try {
+                const { parent, name } = await parentHandle(root, relative, false);
+                const handle = await parent.getFileHandle(name, { create: true });
+                const writable = await handle.createWritable();
+                try {
+                    await writable.write(asWriteValue(value));
+                    await writable.close();
+                }
+                catch (error) {
+                    await writable.abort(error).catch(() => undefined);
+                    throw error;
+                }
+            }
+            catch (error) {
+                throw translateError(error, "ENOENT", `cannot write ${relative}`);
+            }
+        },
+        async appendFile(path, value) {
+            const relative = normalize(path);
+            if (!relative)
+                throw fsError("EISDIR", "cannot append to a directory");
+            try {
+                const { parent, name } = await parentHandle(root, relative, false);
+                const handle = await parent.getFileHandle(name, { create: true });
+                const size = (await handle.getFile()).size;
+                const writable = await handle.createWritable({ keepExistingData: true });
+                try {
+                    await writable.seek(size);
+                    await writable.write(asWriteValue(value));
+                    await writable.close();
+                }
+                catch (error) {
+                    await writable.abort(error).catch(() => undefined);
+                    throw error;
+                }
+            }
+            catch (error) {
+                throw translateError(error, "ENOENT", `cannot append ${relative}`);
+            }
+        },
+        async unlink(path) {
+            await remove(root, normalize(path), false);
+        },
+        async readdir(path) {
+            const directory = await directoryHandle(root, normalize(path), false);
+            const names = [];
+            const entries = directoryEntries(directory);
+            for await (const [name] of entries)
+                names.push(name);
+            return names;
+        },
+        async readdirWithFileTypes(path) {
+            const directory = await directoryHandle(root, normalize(path), false);
+            const entries = [];
+            for await (const [name, handle] of directoryEntries(directory)) {
+                entries.push({
+                    name,
+                    isFile: handle.kind === "file",
+                    isDirectory: handle.kind === "directory",
+                    isSymbolicLink: false,
+                });
+            }
+            return entries;
+        },
+        async mkdir(path) {
+            await directoryHandle(root, normalize(path), true);
+        },
+        async rmdir(path) {
+            const relative = normalize(path);
+            if (!relative)
+                throw fsError("EPERM", "cannot remove workspace root");
+            await remove(root, relative, false);
+        },
+        async rm(path, options) {
+            const relative = normalize(path);
+            if (!relative)
+                throw fsError("EPERM", "cannot remove workspace root");
+            await remove(root, relative, Boolean(options?.recursive));
+        },
+        async stat(path) {
+            return stat(root, normalize(path));
+        },
+        async lstat(path) {
+            return stat(root, normalize(path));
+        },
+        async readlink() {
+            throw fsError("ENOSYS", "OPFS does not support symbolic links");
+        },
+        async symlink() {
+            throw fsError("ENOSYS", "OPFS does not support symbolic links");
+        },
+    };
+}
+function directoryEntries(directory) {
+    return directory.entries();
+}
+async function stat(root, relative) {
+    try {
+        const handle = relative ? await entryHandle(root, relative) : root;
+        if (handle.kind === "directory") {
+            return fileStat("directory", 0, 0);
+        }
+        const file = await handle.getFile();
+        return fileStat("file", file.size, file.lastModified);
+    }
+    catch (error) {
+        throw translateError(error, "ENOENT", `cannot stat ${relative}`);
+    }
+}
+function fileStat(kind, size, modifiedAt) {
+    return {
+        size,
+        mode: kind === "directory" ? 0o040755 : 0o100644,
+        mtimeMs: modifiedAt,
+        ctimeMs: modifiedAt,
+        isFile: () => kind === "file",
+        isDirectory: () => kind === "directory",
+        isSymbolicLink: () => false,
+    };
+}
+async function entryHandle(root, relative) {
+    const { parent, name } = await parentHandle(root, relative, false);
+    try {
+        return await parent.getFileHandle(name);
+    }
+    catch (fileError) {
+        try {
+            return await parent.getDirectoryHandle(name);
+        }
+        catch {
+            throw fileError;
+        }
+    }
+}
+async function directoryHandle(root, relative, create) {
+    let directory = root;
+    if (!relative)
+        return directory;
+    try {
+        for (const segment of relative.split("/")) {
+            directory = await directory.getDirectoryHandle(segment, { create });
+        }
+        return directory;
+    }
+    catch (error) {
+        throw translateError(error, "ENOENT", `cannot open directory ${relative}`);
+    }
+}
+async function parentHandle(root, relative, create) {
+    const segments = relative.split("/");
+    const name = segments.pop();
+    if (!name)
+        throw fsError("EINVAL", "path cannot be empty");
+    return { parent: await directoryHandle(root, segments.join("/"), create), name };
+}
+async function remove(root, relative, recursive) {
+    try {
+        const { parent, name } = await parentHandle(root, relative, false);
+        await parent.removeEntry(name, { recursive });
+    }
+    catch (error) {
+        throw translateError(error, "ENOENT", `cannot remove ${relative}`);
+    }
+}
+function normalize(path) {
+    if (typeof path !== "string")
+        throw fsError("EINVAL", "path must be a string");
+    const raw = path.replace(/\\/g, "/").replace(/^\/+/, "");
+    const relative = raw === "workspace" ? "" : raw.startsWith("workspace/") ? raw.slice(10) : raw;
+    const segments = [];
+    for (const segment of relative.split("/")) {
+        if (!segment || segment === ".")
+            continue;
+        if (segment === "..")
+            throw fsError("EPERM", "path escapes the workspace");
+        segments.push(segment);
+    }
+    return segments.join("/");
+}
+function asWriteValue(value) {
+    if (typeof value === "string" || value instanceof Blob)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return value;
+    if (ArrayBuffer.isView(value)) {
+        const bytes = new Uint8Array(value.byteLength);
+        bytes.set(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+        return bytes;
+    }
+    throw fsError("EINVAL", "file contents must be bytes or text");
+}
+function translateError(error, fallback, message) {
+    if (error && typeof error === "object" && "code" in error &&
+        typeof error.code === "string") {
+        return error;
+    }
+    const name = error instanceof DOMException ? error.name : "";
+    const code = name === "NotFoundError" ? "ENOENT"
+        : name === "TypeMismatchError" ? "ENOTDIR"
+            : name === "InvalidModificationError" ? "ENOTEMPTY"
+                : name === "NoModificationAllowedError" ? "EPERM"
+                    : fallback;
+    return fsError(code, message, error);
+}
+function fsError(code, message, cause) {
+    return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code });
+}