nanocodex 0.4.0 → 0.6.0

package/runtime/tempo-provider.d.mts

@@ -0,0 +1,125 @@
+import type { McpPayment, McpServers, MppSession } from "../types.mjs";
+
+export declare const DEFAULT_MERCATOR_MCP_URL = "https://mercator.tempo.xyz/mcp";
+
+export type TempoProvider<Session extends MppSession = MppSession> = MppSession & Readonly<{
+  kind: "tempo";
+  /** The underlying session, available for channel and payment telemetry. */
+  session: Session;
+  /** MPP-aware HTTP fetch using the same methods as paid MCP calls. */
+  fetch?: TempoPaymentFetch | undefined;
+}>;
+
+export function createTempoProvider<Session extends MppSession>(
+  options: { session: Session; payment: McpPayment; fetch?: TempoPaymentFetch | undefined },
+): TempoProvider<Session>;
+
+export type TempoPaymentFetch = (
+  input: RequestInfo | URL,
+  init?: RequestInit | undefined,
+  policy?: Readonly<{
+    maxAmount?: bigint | undefined;
+    intent?: "charge" | "session" | undefined;
+  }> | undefined,
+) => Promise<Response>;
+
+type WalletParameters = {
+  getClient: (...args: any[]) => any;
+  resolveAccount: (...args: any[]) => any;
+};
+
+/** The adapter-neutral surface implemented by every Accounts SDK provider. */
+export type AccountsWallet = {
+  getMppxParameters(options?: { accessKey?: `0x${string}` | undefined }): WalletParameters;
+  getAccount?(options?: unknown): { address: `0x${string}` };
+  store?: {
+    getState?(): { activeAccount?: number; accounts?: readonly { address: `0x${string}` }[]; chainId?: number };
+    accessKeys?: {
+      get(options: {
+        account: `0x${string}`;
+        accessKey: `0x${string}`;
+        chainId: number;
+      }): Promise<unknown>;
+    };
+  };
+};
+
+export type AccountsTempoPolicy = {
+  /**
+   * These values stay structurally typed so a wallet may use any compatible
+   * Accounts/MPPx/Viem dependency instance without nominal package coupling.
+   */
+  autoSwap?: unknown;
+  channelStore?: unknown;
+  decimals?: number | undefined;
+  escrow?: `0x${string}` | undefined;
+  maxDeposit?: string | undefined;
+  topUpAmount?: string | undefined;
+  [option: string]: unknown;
+};
+
+export type AccountsTempoSessionOptions = AccountsTempoPolicy & {
+  bootstrap?: boolean | undefined;
+  fetch?: typeof globalThis.fetch | undefined;
+  webSocket?: unknown;
+};
+
+export type AccountsTempoMercatorOptions = AccountsTempoPolicy & {
+  onChannelUpdate?: ((entry: {
+    channelId: `0x${string}`;
+    cumulativeAmount: bigint;
+    [field: string]: unknown;
+  }) => void | Promise<void>) | undefined;
+};
+
+export type AccountsTempoPaymentOptions = {
+  /** Raw fetch wrapped by MPPx. */
+  fetch?: typeof globalThis.fetch | undefined;
+  /** Maximum atomic amount accepted from one HTTP or MCP challenge. */
+  maxAmount?: bigint | undefined;
+  /** Optional application approval composed after the amount check. */
+  onPaymentRequired?: ((challenge: unknown) => boolean | Promise<boolean>) | undefined;
+};
+
+export type AccountsTempoSession = MppSession & {
+  readonly channelId: `0x${string}` | undefined;
+  readonly cumulative: bigint;
+  readonly opened: boolean;
+  readonly state: unknown;
+  close(): Promise<unknown>;
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+  topUp(amount: string | bigint): Promise<unknown>;
+};
+
+export type AccountsTempoProviderOptions = {
+  /** Any provider returned by Accounts SDK `Provider.create(...)`. */
+  wallet: AccountsWallet;
+  /** Connected root account owning the delegated key. Inferred from Accounts when omitted. */
+  account?: `0x${string}` | undefined;
+  /** Optional Accounts SDK access key to pin for both model and MCP payments. */
+  accessKey?: `0x${string}` | undefined;
+  /** Chain on which the delegated key is authorized. Inferred from Accounts when omitted. */
+  chainId?: number | undefined;
+  /** Shared Tempo payment policy applied to the model session and Mercator. */
+  policy?: AccountsTempoPolicy | undefined;
+  /** Model-session-only overrides, such as `bootstrap` or `webSocket`. */
+  session?: AccountsTempoSessionOptions | undefined;
+  /** Mercator-only Tempo method overrides, such as `onChannelUpdate`. */
+  mercator?: AccountsTempoMercatorOptions | undefined;
+  /** Shared HTTP and MCP challenge policy. */
+  payment?: AccountsTempoPaymentOptions | undefined;
+};
+
+/**
+ * Constructs a Tempo provider from any Accounts SDK wallet adapter without
+ * taking a runtime dependency on `accounts`.
+ */
+export function createTempoProviderFromAccounts(
+  options: AccountsTempoProviderOptions,
+): Promise<TempoProvider<AccountsTempoSession>>;
+
+/** @internal */
+export function resolveMcpServers(
+  provider: MppSession | undefined,
+  configured: McpServers | false | undefined,
+): McpServers | undefined;

package/runtime/tempo-provider.mjs

@@ -0,0 +1,264 @@
+const tempoMcp = Symbol.for("nanocodex.tempo.mcp");
+
+export const DEFAULT_MERCATOR_MCP_URL = "https://mercator.tempo.xyz/mcp";
+
+const defaultMercator = (payment) => ({
+  url: DEFAULT_MERCATOR_MCP_URL,
+  description: "Discovers and composes paid Tempo services and MPP flows.",
+  payment,
+});
+
+/**
+ * Marks an MPP session as a Tempo provider and uses the same wallet policy for
+ * Nanocodex's built-in paid Mercator MCP. Generic MPP sessions remain generic.
+ */
+export function createTempoProvider(options) {
+  const session = options?.session;
+  if (!session || typeof session.ws !== "function") {
+    throw new TypeError("session must provide ws(endpoint)");
+  }
+  if (!options.payment || !Array.isArray(options.payment.methods) || !options.payment.methods.length) {
+    throw new TypeError("Tempo provider payment must include at least one MPPx method");
+  }
+
+  const provider = {
+    kind: "tempo",
+    session,
+    ws(endpoint) {
+      return session.ws(endpoint);
+    },
+    ...(typeof options.fetch === "function" ? { fetch: options.fetch } : {}),
+  };
+  if (typeof session.close === "function") {
+    provider.close = () => session.close();
+  }
+  Object.defineProperty(provider, tempoMcp, {
+    value: { mercator: defaultMercator(options.payment) },
+  });
+  return Object.freeze(provider);
+}
+
+/**
+ * Creates the model session and Mercator payment method from any Accounts SDK
+ * provider. Accounts adapters all meet the same getMppxParameters() contract,
+ * so wallet selection remains entirely application-owned.
+ */
+export async function createTempoProviderFromAccounts(options) {
+  const wallet = options?.wallet;
+  if (!wallet || typeof wallet.getMppxParameters !== "function") {
+    throw new TypeError("wallet must provide getMppxParameters(options)");
+  }
+  const accessKey = options.accessKey;
+  const walletParametersRaw = wallet.getMppxParameters(
+    accessKey === undefined ? undefined : { accessKey },
+  );
+  if (!walletParametersRaw || typeof walletParametersRaw.getClient !== "function"
+    || typeof walletParametersRaw.resolveAccount !== "function") {
+    throw new TypeError("wallet.getMppxParameters() returned invalid MPPx parameters");
+  }
+  // Keep mppx out of normal/API-key browser bundles. It is loaded only when an
+  // application explicitly asks Nanocodex to construct a Tempo wallet path.
+  const [{ Mppx, tempo }, { createClient, http }] = await Promise.all([
+    import("mppx/client"),
+    import("viem/tempo"),
+  ]);
+  const walletParameters = await pinnedScopedAccountParameters(
+    wallet,
+    walletParametersRaw,
+    accessKey,
+    {
+      account: options.account,
+      chainId: options.chainId,
+      createClient,
+      http,
+    },
+  );
+  const policy = options.policy ?? {};
+  const session = tempo.session.manager({
+    ...policy,
+    ...options.session,
+    ...walletParameters,
+  });
+  const method = tempo({
+    ...policy,
+    ...options.mercator,
+    ...walletParameters,
+  });
+  const paymentPolicy = options.payment ?? {};
+  const approvePayment = paymentApproval(paymentPolicy);
+  const payment = {
+    methods: [method],
+    ...(approvePayment ? { onPaymentRequired: approvePayment } : {}),
+  };
+  const fetch = (input, init, requestPolicy) => {
+    const requestApproval = paymentApproval({
+      ...paymentPolicy,
+      ...(requestPolicy?.maxAmount === undefined
+        ? {}
+        : { maxAmount: requestPolicy.maxAmount }),
+    });
+    const mppx = Mppx.create({
+      methods: [method],
+      polyfill: false,
+      ...(paymentPolicy.fetch ? { fetch: paymentPolicy.fetch } : {}),
+      ...(requestPolicy?.intent
+        ? {
+            orderChallenges(candidates) {
+              return [...candidates].sort((left, right) =>
+                Number(right.challenge.intent === requestPolicy.intent)
+                - Number(left.challenge.intent === requestPolicy.intent));
+            },
+          }
+        : {}),
+      ...(requestApproval
+        ? {
+            async onChallenge(challenge, { createCredential }) {
+              if (!(await requestApproval(challenge))) {
+                throw new Error("MPP payment declined by Nanocodex policy.");
+              }
+              return createCredential();
+            },
+          }
+        : {}),
+    });
+    return mppx.fetch(input, init);
+  };
+  return createTempoProvider({
+    session,
+    payment,
+    fetch,
+  });
+}
+
+/** @internal */
+export async function pinnedScopedAccountParameters(wallet, parameters, accessKey, clientFactory) {
+  const getAccessKey = wallet?.store?.accessKeys?.get;
+  if (accessKey === undefined || typeof getAccessKey !== "function") return parameters;
+
+  const state = wallet.store.getState?.();
+  const rootAccount = clientFactory.account
+    ?? wallet.getAccount?.()?.address
+    ?? state?.accounts?.[state.activeAccount ?? 0]?.address;
+  const chainId = Number(clientFactory.chainId ?? state?.chainId ?? 4217);
+  if (typeof rootAccount !== "string") {
+    throw new Error("The connected Accounts root address is unavailable.");
+  }
+  const pinnedAccount = await getAccessKey.call(wallet.store.accessKeys, {
+    account: rootAccount,
+    accessKey,
+    chainId,
+  });
+  const expected = accessKey.toLowerCase();
+  if (!pinnedAccount || pinnedAccount.accessKeyAddress?.toLowerCase() !== expected) {
+    throw new Error(`Pinned access key "${accessKey}" is not available in the Accounts keystore.`);
+  }
+
+  const clients = new Map();
+
+  return {
+    ...parameters,
+    getClient(info = {}) {
+      const source = parameters.getClient(info);
+      const requestedChainId = Number(info.chainId ?? source?.chain?.id ?? chainId);
+      if (requestedChainId !== chainId) {
+        throw new Error(
+          `Pinned access key "${accessKey}" is authorized for chain ${chainId}, not ${requestedChainId}.`,
+        );
+      }
+      let client = clients.get(requestedChainId);
+      if (client) return client;
+
+      const rpcUrl = source?.chain?.rpcUrls?.default?.http?.[0];
+      if (typeof rpcUrl !== "string") {
+        throw new Error(`No direct Tempo RPC URL is configured for chain ${requestedChainId}.`);
+      }
+      // The Accounts client routes JSON-RPC back through the wallet provider.
+      // That transport may auto-select a different valid access key while
+      // filling a transaction. Use the chain's direct RPC transport here, but
+      // keep reads rooted at the payer account. Setting the client account to
+      // the unpublished access key makes viem encode eth_call as a keychain
+      // call before the first payment transaction has attached its pending
+      // keyAuthorization, so even balanceOf fails with KeyNotFound. MPPx passes
+      // the exact local pinnedAccount returned by resolveAccount when it
+      // prepares and signs the mutating channel transaction; that is the point
+      // where viem attaches and consumes the pending authorization.
+      client = clientFactory.createClient({
+        account: { address: rootAccount, type: "json-rpc" },
+        chain: source.chain,
+        transport: clientFactory.http(rpcUrl),
+      });
+      clients.set(requestedChainId, client);
+      return client;
+    },
+    async resolveAccount(info) {
+      const authority = info?.operation?.kind === "authorizePaymentChannel"
+        ? info.operation.authority?.toLowerCase()
+        : undefined;
+      if (authority !== undefined && authority !== expected) {
+        throw new Error(
+          `MPP channel authority "${info.operation.authority}" does not match pinned access key "${accessKey}".`,
+        );
+      }
+
+      // Accounts may have several valid delegated keys for the same Tempo
+      // account. Its generic resolver is allowed to choose any key whose
+      // scopes cover a transaction, but an MPP channel is bound to one exact
+      // authority. Load that signer directly so channel top-ups and closes
+      // can never drift to a newer matching key.
+      if (info.chainId !== chainId) {
+        throw new Error(
+          `Pinned access key "${accessKey}" is authorized for chain ${chainId}, not ${info.chainId}.`,
+        );
+      }
+      if (info.account.address.toLowerCase() !== rootAccount.toLowerCase()) {
+        throw new Error(
+          `Pinned access key "${accessKey}" cannot sign for account "${info.account.address}".`,
+        );
+      }
+      return pinnedAccount;
+    },
+  };
+}
+
+function paymentApproval(policy) {
+  const hasMaximum = policy.maxAmount !== undefined;
+  const approve = policy.onPaymentRequired;
+  if (!hasMaximum && typeof approve !== "function") return undefined;
+  const maximum = hasMaximum ? nonNegativeBigInt(policy.maxAmount, "payment.maxAmount") : undefined;
+  return async (challenge) => {
+    if (maximum !== undefined) {
+      const amount = challenge?.request?.amount;
+      if (typeof amount !== "string" || !/^\d+$/.test(amount)) {
+        throw new Error("MPP payment challenge has no valid atomic amount.");
+      }
+      if (BigInt(amount) > maximum) {
+        throw new Error(
+          `MPP payment amount ${amount} exceeds the per-request limit ${maximum}.`,
+        );
+      }
+    }
+    return typeof approve === "function" ? approve(challenge) : true;
+  };
+}
+
+function nonNegativeBigInt(value, name) {
+  let parsed;
+  try {
+    parsed = BigInt(value);
+  } catch (error) {
+    throw new TypeError(`${name} must be an atomic integer`, { cause: error });
+  }
+  if (parsed < 0n) throw new TypeError(`${name} must not be negative`);
+  return parsed;
+}
+
+/** @internal */
+export function resolveMcpServers(provider, configured) {
+  if (configured === false) return undefined;
+  const defaults = provider?.[tempoMcp];
+  if (!defaults) return configured;
+  return {
+    ...defaults,
+    ...configured,
+  };
+}

package/runtime/tool-configuration.mjs

@@ -0,0 +1 @@
+export * from "nanocodex-tools/runtime/tool-configuration";

package/runtime/tool-router.mjs

@@ -0,0 +1 @@
+export * from "nanocodex-tools/runtime/tool-router";

package/runtime/utf8.mjs

@@ -0,0 +1 @@
+export * from "nanocodex-tools/runtime/utf8";

package/runtime/worker-evaluator.mjs

@@ -0,0 +1,162 @@
+const WORKER_PROTOCOL = "nanocodex.code-evaluator.v1";
+let nextEvaluation = 1;
+
+/** Creates the browser's per-cell, synchronously terminable Code Mode boundary. */
+export function createWorkerEvaluator(options = {}) {
+  const createWorker = options.createWorker ?? createCodeEvaluatorWorker;
+  if (options.createWorker === undefined && typeof globalThis.Worker !== "function") {
+    throw new TypeError("browser Code Mode isolation requires Worker");
+  }
+  if (typeof createWorker !== "function") {
+    throw new TypeError("browser Code Mode isolation requires a Worker factory");
+  }
+
+  return (source, environment) => new Promise((resolve, reject) => {
+    environment.signal?.throwIfAborted();
+    const worker = createWorker();
+    const evaluationId = nextEvaluation++;
+    let closed = false;
+
+    const close = () => {
+      if (closed) return false;
+      closed = true;
+      environment.signal?.removeEventListener("abort", onAbort);
+      worker.onmessage = null;
+      worker.onerror = null;
+      worker.onmessageerror = null;
+      worker.terminate();
+      return true;
+    };
+    const fail = (error) => {
+      if (!close()) return;
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    const onAbort = () => {
+      const reason = environment.signal?.reason ?? new Error("Code Mode execution was cancelled");
+      // AbortSignal dispatch is synchronous. Let every parent-held nested tool
+      // observe cancellation before terminating its guest evaluator boundary.
+      queueMicrotask(() => fail(reason));
+    };
+
+    worker.onmessage = ({ data }) => {
+      if (closed || data?.protocol !== WORKER_PROTOCOL || data.evaluationId !== evaluationId) return;
+      if (data.type === "tool.call") {
+        const tool = environment.tools[data.name];
+        Promise.resolve().then(() => {
+          if (typeof tool !== "function") {
+            throw new Error(`unknown application tool: ${data.name}`);
+          }
+          return tool(data.input);
+        }).then(
+          (value) => postToolResult(worker, evaluationId, data.id, true, value, () => closed),
+          (error) => postToolResult(
+            worker,
+            evaluationId,
+            data.id,
+            false,
+            cloneableError(error),
+            () => closed,
+          ),
+        );
+        return;
+      }
+      if (data.type === "output") {
+        try {
+          if (data.kind === "text") environment.text(data.value);
+          else if (data.kind === "image") environment.image(data.value, data.detail);
+          else if (data.kind === "audio") environment.audio(data.value);
+          else if (data.kind === "notify") environment.notify(data.value);
+          else if (data.kind === "yield_control") environment.yield_control();
+          else if (data.kind === "generatedImage") environment.generatedImage(data.value);
+          else throw new Error(`unknown Code Mode output kind: ${data.kind}`);
+        } catch (error) {
+          fail(error);
+        }
+        return;
+      }
+      if (data.type === "console") {
+        const logger = typeof environment.console?.[data.level] === "function"
+          ? environment.console[data.level]
+          : environment.console?.log;
+        logger?.(...data.values);
+        return;
+      }
+      if (data.type !== "completed" && data.type !== "failed") {
+        fail(new Error(`unknown Code Mode evaluator message: ${data.type}`));
+        return;
+      }
+      try {
+        for (const [key, value] of data.storedWrites ?? []) environment.store(key, value);
+      } catch (error) {
+        fail(error);
+        return;
+      }
+      if (!close()) return;
+      if (data.type === "completed") resolve();
+      else reject(new Error(data.error || "Code Mode evaluator failed"));
+    };
+    worker.onerror = (event) => fail(new Error(event?.message || "Code Mode evaluator Worker failed"));
+    worker.onmessageerror = () => fail(new Error("Code Mode evaluator Worker returned unreadable data"));
+    environment.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      worker.postMessage({
+        protocol: WORKER_PROTOCOL,
+        evaluationId,
+        egress: options.egress,
+        type: "evaluate",
+        source,
+        storedEntries: environment.storedEntries,
+        toolDefinitions: environment.toolDefinitions,
+        toolNames: Object.keys(environment.tools),
+      });
+    } catch (error) {
+      fail(error);
+    }
+  });
+}
+
+// Vite recognizes only this literal Worker + URL shape as a worker entry. Keep
+// the test factory above out of the production construction path so the
+// evaluator and its imports are emitted as one runnable browser asset.
+function createCodeEvaluatorWorker() {
+  return new Worker(
+    new URL("./code-evaluator.worker.mjs", import.meta.url),
+    { name: "nanocodex-code-evaluator", type: "module" },
+  );
+}
+
+function postToolResult(worker, evaluationId, id, ok, value, isClosed) {
+  if (isClosed()) return;
+  try {
+    worker.postMessage({
+      protocol: WORKER_PROTOCOL,
+      evaluationId,
+      type: "tool.result",
+      id,
+      ok,
+      value,
+    });
+  } catch (error) {
+    worker.postMessage({
+      protocol: WORKER_PROTOCOL,
+      evaluationId,
+      type: "tool.result",
+      id,
+      ok: false,
+      value: `tool result could not cross the evaluator Worker boundary: ${errorMessage(error)}`,
+    });
+  }
+}
+
+function cloneableError(error) {
+  try {
+    structuredClone(error);
+    return error;
+  } catch {
+    return errorMessage(error);
+  }
+}
+
+function errorMessage(error) {
+  return error && (error.stack || error.message) ? error.stack || error.message : String(error);
+}

package/runtime/workspace.d.mts

@@ -0,0 +1 @@
+export * from "nanocodex-tools/workspace";

package/runtime/workspace.mjs

@@ -0,0 +1 @@
+export * from "nanocodex-tools/workspace";

package/tools/Tools.d.mts

@@ -0,0 +1,56 @@
+import type { McpServers, NamedTool, ToolMap } from "../types.mjs";
+import type { Workspace } from "../runtime/workspace.mjs";
+import type { HostedMachine } from "./hostedCatalog.mjs";
+
+declare const toolsBrand: unique symbol;
+
+export type AttachmentSocket = {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  addEventListener?(type: string, listener: (event: any) => void, options?: unknown): void;
+  on?(type: string, listener: (...args: any[]) => void): void;
+};
+
+export type AttachmentTransport = Readonly<{
+  connect(target: string | URL): AttachmentSocket | Promise<AttachmentSocket>;
+}>;
+
+export type AttachmentTarget = string | URL | Readonly<{
+  endpoint: string | URL;
+  transport: AttachmentTransport;
+}>;
+
+export type AttachmentClient = Readonly<{
+  readonly connected: boolean;
+  closed(): Promise<void>;
+  close(): Promise<void>;
+}>;
+
+export type Tools = Readonly<{
+  readonly [toolsBrand]: true;
+  attach(target: AttachmentTarget): Readonly<{
+    connect(): Promise<AttachmentClient>;
+    closed(): Promise<void>;
+    close(): Promise<void>;
+  }>;
+  close(): Promise<void>;
+}>;
+
+/**
+ * Creates one owned tool runtime. Caller-supplied tool ownership transfers only
+ * after this promise resolves; a rejected construction leaves those tools with
+ * the caller. The returned runtime joins all owned cleanup through close().
+ */
+export function createTools(options?: {
+  tools?: ToolMap | readonly NamedTool[];
+  /** Stable safe ASCII identifier (at most 123 bytes) for this independent attachment. */
+  attachmentId?: string;
+  /** Sole non-secret machine published by this host; its id must equal attachmentId. */
+  machines?: readonly HostedMachine[];
+  /** Portable workspace handle; React Native supplies one via createWorkspace({ backend }). */
+  workspace?: Workspace;
+  workspaceOptions?: { maxEntries?: number; maxReadBytes?: number; maxWriteBytes?: number };
+  mcp?: McpServers | false;
+  mcpOptions?: Readonly<Record<string, unknown>>;
+}): Promise<Tools>;