@lamplitisles/dsh-nanocodex 0.1.0-beta.0

package/vendor/nanocodex/runtime/durability.mjs

@@ -0,0 +1,153 @@
+const hosts = new Map();
+let nextRouteId = 1n;
+
+export function own(host, store, stateId) {
+  if ((store === undefined) !== (stateId === undefined)) {
+    throw new TypeError("durability and durabilityId must be supplied together");
+  }
+  const routeId = `durability-route-${nextRouteId++}`;
+  hosts.set(routeId, { host, store, stateId, references: 0 });
+  return Object.freeze({
+    id: routeId,
+    abandon: () => abandon(host, routeId),
+    retain: () => retain(host, routeId),
+    release: () => release(host, routeId),
+  });
+}
+
+export function retain(host, routeId) {
+  const ownership = hosts.get(routeId);
+  if (!ownership || ownership.host !== host) {
+    throw new Error(`Nanocodex durability route is not bound to this host: ${routeId}`);
+  }
+  ownership.references += 1;
+}
+
+export function release(host, routeId) {
+  const ownership = hosts.get(routeId);
+  if (!ownership || ownership.host !== host) return;
+  if (ownership.references > 0) ownership.references -= 1;
+  if (ownership.references === 0) hosts.delete(routeId);
+}
+
+export function abandon(host, routeId) {
+  const ownership = hosts.get(routeId);
+  if (ownership?.host === host && ownership.references === 0) hosts.delete(routeId);
+}
+
+export async function acquire(routeId, stateId, ownerId) {
+  const stored = await requiredRoute(routeId).store.acquire(stateId, { ownerId });
+  if (!stored || typeof stored !== "object" || Array.isArray(stored)) {
+    throw new TypeError("durability.acquire() must return an acquired state object");
+  }
+  exactKeys(stored, ["ownerId", "fence", "revision", "payload"], "durability acquired state");
+  const acquiredOwnerId = nonempty(stored.ownerId, "durability owner ID");
+  if (acquiredOwnerId !== ownerId) {
+    throw new TypeError("durability.acquire() must return the requested owner ID");
+  }
+  const retainedRevision = uint64(stored.revision, "durability state revision");
+  const payload = stored.payload === null
+    ? null
+    : string(stored.payload, "durability state payload");
+  if ((retainedRevision === "0") !== (payload === null)) {
+    throw new TypeError("durability.acquire() returned inconsistent revision and payload");
+  }
+  // Cross the WASM boundary as fields. Wrapping a large legacy payload in
+  // another JSON string duplicates it in both JS and WASM during cold recovery.
+  return Object.freeze({
+    owner_id: acquiredOwnerId,
+    fence: uint64(stored.fence, "durability owner fence"),
+    revision: retainedRevision,
+    // wasm-bindgen's string conversion can reserve three times a large
+    // Unicode string's length. UTF-8 bytes cross with one exact allocation.
+    payload: payload === null ? null : new TextEncoder().encode(payload),
+  });
+}
+
+export async function replace(
+  routeId,
+  stateId,
+  ownerId,
+  fence,
+  expectedRevision,
+  payload,
+) {
+  const result = await requiredRoute(routeId).store.replace(stateId, {
+    ownerId,
+    fence,
+    expectedRevision,
+    payload,
+  });
+  if (result?.status === "replaced") {
+    exactKeys(result, ["status", "revision"], "durability replaced result");
+    return JSON.stringify({
+      status: "replaced",
+      revision: uint64(result.revision, "durability replace revision"),
+    });
+  }
+  if (result?.status === "conflict") {
+    exactKeys(result, ["status", "actualRevision"], "durability conflict result");
+    return JSON.stringify({
+      status: "conflict",
+      actual_revision: uint64(result.actualRevision, "durability conflict revision"),
+    });
+  }
+  if (result?.status === "not_committed") {
+    exactKeys(result, ["status", "message"], "durability not-committed result");
+    return JSON.stringify({
+      status: "not_committed",
+      message: nonempty(result.message, "durability not-committed message"),
+    });
+  }
+  if (result?.status === "fenced") {
+    exactKeys(result, ["status"], "durability fenced result");
+    return JSON.stringify({ status: "fenced" });
+  }
+  throw new TypeError(
+    "durability.replace() must return a replaced, conflict, fenced, or not_committed result",
+  );
+}
+
+function requiredRoute(routeId) {
+  const route = hosts.get(routeId);
+  if (!route) throw new Error(`no Nanocodex host owns durability route: ${routeId}`);
+  const store = route.store;
+  if (!store || typeof store.acquire !== "function" || typeof store.replace !== "function") {
+    throw new TypeError("the selected Nanocodex host must define a durability state store");
+  }
+  return route;
+}
+
+function uint64(value, name) {
+  if (
+    typeof value !== "string"
+    || !/^(0|[1-9][0-9]*)$/.test(value)
+    || BigInt(value) > 18_446_744_073_709_551_615n
+  ) {
+    throw new TypeError(`${name} must be an unsigned 64-bit decimal string`);
+  }
+  return value;
+}
+
+function string(value, name) {
+  if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+  return value;
+}
+
+function nonempty(value, name) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function exactKeys(value, expected, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+  const actual = Object.keys(value).sort();
+  const required = [...expected].sort();
+  if (actual.length !== required.length || actual.some((key, index) => key !== required[index])) {
+    throw new TypeError(`${name} must contain exactly ${required.join(", ")}`);
+  }
+}

package/vendor/nanocodex/runtime/managed-transport.mjs

@@ -0,0 +1,460 @@
+import * as ManagedAgent from "../managed/Agent.mjs";
+import { registerManagedAgentAlias } from "../managed/internal.mjs";
+import { reportError } from "../internal.mjs";
+import { AttachmentRejectedError } from "../tools/attachment.mjs";
+import {
+  toolRouterBrand,
+  toolRuntimeLifecycle,
+} from "./tool-router.mjs";
+
+const MANAGED_AGENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const TRANSPORT_OPTIONS = new Set(["agent", "apiKey", "baseUrl", "fetch", "toolsTransport"]);
+const CREATE_OPTIONS = new Set(["tools", "transport"]);
+const ATTACHMENT_BACKOFF_MS = [250, 500, 1_000, 2_000, 5_000];
+const managedTransports = new WeakMap();
+let nextManagedAgent = 1;
+
+/** Defines an account-authenticated durable Agent transport without exposing its credentials. */
+export function createManagedTransport(options) {
+  validateTransportOptions(options);
+  const identity = Object.hasOwn(options.agent, "create")
+    ? Object.freeze({ kind: "create" })
+    : Object.freeze({ kind: "open", id: options.agent.id });
+  const transport = Object.freeze({});
+  const client = { ...options };
+  delete client.agent;
+  managedTransports.set(transport, Object.freeze({
+    identity,
+    client: Object.freeze(client),
+  }));
+  return transport;
+}
+
+export function managedTransportOptions(transport) {
+  return transport && typeof transport === "object"
+    ? managedTransports.get(transport)
+    : undefined;
+}
+
+/** Creates the common Agent lifecycle over an account-owned durable Agent. */
+export async function createManagedAgent(options) {
+  validateCreateOptions(options);
+  const setup = managedTransportOptions(options.transport);
+  if (!setup) throw new TypeError("Agent.create requires a managed transport");
+  const tools = options.tools;
+  if (tools !== undefined
+      && (!tools?.[toolRouterBrand] || typeof tools.attach !== "function")) {
+    throw new TypeError("managed Agent tools must be created by createTools()");
+  }
+  tools?.[toolRuntimeLifecycle].available();
+  const managed = setup.identity.kind === "create"
+    ? await ManagedAgent.create(setup.client)
+    : ManagedAgent.open(setup.identity.id, setup.client);
+  const managedState = await managed.state();
+  if (managedState.agent_id !== managed.id
+      || typeof managedState.session_id !== "string"
+      || !MANAGED_AGENT_ID.test(managedState.session_id)) {
+    throw new Error("managed Agent state returned inconsistent agent or session identity");
+  }
+  tools?.[toolRuntimeLifecycle].claim();
+  return managedAgentView(managed, managedState.agent_id, managedState.session_id, tools);
+}
+
+function managedAgentView(managed, agentId, sessionId, tools) {
+  const state = {
+    managed,
+    tools,
+    connector: undefined,
+    attachmentAbort: new AbortController(),
+    attachmentSupervisor: undefined,
+    closed: false,
+    closing: undefined,
+    agentId,
+    sessionId,
+    turns: new Set(),
+    uid: `managed-agent-${nextManagedAgent++}`,
+    watchers: new Set(),
+  };
+  const agent = agentView(state, {});
+  registerManagedAgentAlias(agent, managed);
+  if (tools) {
+    state.attachmentSupervisor = superviseAttachment(state).catch((error) => {
+      if (!state.closed) reportError(error);
+    });
+  }
+  return agent;
+}
+
+async function superviseAttachment(state) {
+  const target = state.managed.toolsTarget();
+  for (let attempt = 0; ; attempt += 1) {
+    if (state.attachmentAbort.signal.aborted) return;
+    const connector = state.tools.attach(target);
+    state.connector = connector;
+    try {
+      await connector.connect();
+      return;
+    } catch (error) {
+      connector.close();
+      if (state.connector === connector) state.connector = undefined;
+      if (error instanceof AttachmentRejectedError) throw error;
+      if (state.attachmentAbort.signal.aborted) return;
+      if (attempt === ATTACHMENT_BACKOFF_MS.length - 1) {
+        reportError(new Error(
+          "managed tool attachment remains unavailable; cloud tools continue while retrying",
+        ));
+      }
+      await attachmentBackoff(
+        ATTACHMENT_BACKOFF_MS[Math.min(attempt, ATTACHMENT_BACKOFF_MS.length - 1)],
+        state.attachmentAbort.signal,
+      );
+    }
+  }
+}
+
+function attachmentBackoff(milliseconds, signal) {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, milliseconds);
+    signal.addEventListener("abort", done, { once: true });
+    function done() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    }
+  });
+}
+
+function agentView(state, extensions) {
+  let agent;
+  const base = {
+    uid: state.uid,
+    key: "managed-durable",
+    name: "Nanocodex Managed Durable Agent",
+    type: "managed",
+    get agentId() { return state.agentId; },
+    get sessionId() { return state.sessionId; },
+    extend(decorator) {
+      if (typeof decorator !== "function") throw new TypeError("agent.extend requires a decorator function");
+      const value = decorator(agent);
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("an agent decorator must return an object");
+      }
+      const extension = { ...value };
+      for (const key of Object.keys(base)) delete extension[key];
+      return agentView(state, mergeExtensions(extensions, extension));
+    },
+    dispose() {
+      if (state.closed) return;
+      closeManagedAgent(state);
+    },
+  };
+  const lifecycle = {
+    events: {
+      watch: (options) => {
+        requireOpen(state);
+        const watcher = managedEventWatcher(
+          state.managed,
+          state.sessionId,
+          options,
+          () => state.watchers.delete(watcher),
+        );
+        state.watchers.add(watcher);
+        return watcher;
+      },
+    },
+    session: {
+      shutdown: () => shutdownManagedAgent(state),
+    },
+    turn: {
+      prompt: (options) => {
+        requireOpen(state);
+        const controller = new AbortController();
+        const active = { controller, turn: undefined };
+        const turn = state.managed.turn.prompt({
+          ...promptOptions(options),
+          signal: controller.signal,
+        });
+        active.turn = turn;
+        state.turns.add(active);
+        return managedTurn(agent, turn, () => state.turns.delete(active));
+      },
+    },
+  };
+  agent = Object.assign(base, mergeExtensions(lifecycle, extensions));
+  return agent;
+}
+
+function managedTurn(agent, turn, settled) {
+  let result;
+  return Object.freeze({
+    agent,
+    accepted: async () => {
+      await turn.accepted();
+      return turn.idempotencyKey;
+    },
+    result: () => result ??= turn.result()
+      .then((completed) => managedTurnResult(completed))
+      .finally(settled),
+    steer: async (options) => { await turn.steer(options); },
+    cancel: async () => { await turn.cancel(); },
+    dispose() {},
+  });
+}
+
+function managedTurnResult(result) {
+  let disposed = false;
+  return Object.freeze({
+    finalMessage: result.finalMessage,
+    usage: () => disposed
+      ? Promise.reject(new Error("the Nanocodex turn result has been disposed"))
+      : Promise.resolve(result.usage),
+    dispose() { disposed = true; },
+  });
+}
+
+function managedEventWatcher(managed, sessionId, options = {}, onClose) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("managed Agent event options must be an object");
+  }
+  const unsupported = Object.keys(options).find((key) => key !== "includeAllSessions");
+  if (unsupported) throw new TypeError(`managed Agent events do not accept ${unsupported}`);
+  const listeners = new Set();
+  const readers = new Set();
+  let observation;
+  let stream;
+  let pumping;
+  let closed = false;
+
+  const start = () => {
+    if (closed || pumping) return;
+    const controller = new AbortController();
+    const activeStream = managed.events.watch({ cursor: "latest", signal: controller.signal });
+    observation = controller;
+    stream = activeStream;
+    pumping = (async () => {
+      try {
+        for await (const envelope of activeStream) {
+          if (closed) return;
+          const event = projectManagedEvent(envelope, sessionId);
+          for (const listener of listeners) {
+            try { listener(event); } catch (error) { reportError(error); }
+          }
+          for (const reader of readers) reader.push(event);
+        }
+        for (const reader of readers) reader.end();
+      } catch (error) {
+        if (closed || controller.signal.aborted) return;
+        for (const reader of readers) reader.fail(error);
+        reportError(error);
+      } finally {
+        if (stream === activeStream) {
+          observation = undefined;
+          stream = undefined;
+          pumping = undefined;
+        }
+      }
+    })();
+  };
+  const stop = () => {
+    observation?.abort();
+    observation = undefined;
+    void stream?.return?.();
+    stream = undefined;
+    pumping = undefined;
+  };
+  const stopIfIdle = () => {
+    if (!listeners.size && !readers.size) stop();
+  };
+  const watcher = {
+    onEvent(listener) {
+      if (typeof listener !== "function") throw new TypeError("events.watch.onEvent requires a listener");
+      if (closed) return () => {};
+      listeners.add(listener);
+      start();
+      return () => {
+        listeners.delete(listener);
+        stopIfIdle();
+      };
+    },
+    off() {
+      if (closed) return;
+      closed = true;
+      stop();
+      listeners.clear();
+      for (const reader of readers) reader.end();
+      readers.clear();
+      onClose();
+    },
+    [Symbol.asyncIterator]() {
+      if (closed) return emptyIterator();
+      const reader = eventReader(() => {
+        readers.delete(reader);
+        stopIfIdle();
+      });
+      readers.add(reader);
+      start();
+      return reader;
+    },
+  };
+  return Object.freeze(watcher);
+}
+
+function eventReader(onClose) {
+  const queue = [];
+  const pending = [];
+  let ended = false;
+  let failure;
+  const reader = {
+    push(value) {
+      if (ended || failure) return;
+      const waiter = pending.shift();
+      if (waiter) waiter.resolve({ done: false, value });
+      else if (queue.length >= 4_096) reader.fail(new RangeError("managed event iterator exceeded 4096 buffered events"));
+      else queue.push(value);
+    },
+    fail(error) {
+      if (ended || failure) return;
+      failure = error;
+      for (const waiter of pending.splice(0)) waiter.reject(error);
+      onClose();
+    },
+    end() {
+      if (ended) return;
+      ended = true;
+      for (const entry of pending.splice(0)) entry.resolve({ done: true, value: undefined });
+      queue.length = 0;
+      onClose();
+    },
+    next() {
+      if (queue.length) return Promise.resolve({ done: false, value: queue.shift() });
+      if (failure) return Promise.reject(failure);
+      if (ended) return Promise.resolve({ done: true, value: undefined });
+      return new Promise((resolve, reject) => pending.push({ resolve, reject }));
+    },
+    return() { reader.end(); return Promise.resolve({ done: true, value: undefined }); },
+    [Symbol.asyncIterator]() { return this; },
+  };
+  return reader;
+}
+
+function projectManagedEvent(envelope, sessionId) {
+  const observed = envelope.data?.type === "event" ? envelope.data.event : undefined;
+  if (observed && typeof observed === "object" && !Array.isArray(observed)
+      && typeof observed.type === "string" && observed.payload
+      && typeof observed.payload === "object" && !Array.isArray(observed.payload)) {
+    return Object.freeze({
+      ...observed,
+      request_id: sessionId,
+      seq: eventSequence(envelope.cursor, observed.seq),
+      payload: Object.freeze({ ...observed.payload }),
+    });
+  }
+  return Object.freeze({
+    protocol_version: 1,
+    request_id: sessionId,
+    seq: eventSequence(envelope.cursor),
+    type: `managed.${envelope.data?.type ?? envelope.type ?? "event"}`,
+    payload: Object.freeze({ ...(envelope.data ?? {}) }),
+  });
+}
+
+function eventSequence(cursor, fallback = 0) {
+  const parsed = Number(cursor);
+  return Number.isSafeInteger(parsed) && parsed >= 0
+    ? parsed
+    : Number.isSafeInteger(fallback) && fallback >= 0 ? fallback : 0;
+}
+
+function emptyIterator() {
+  return {
+    next: () => Promise.resolve({ done: true, value: undefined }),
+    return: () => Promise.resolve({ done: true, value: undefined }),
+    [Symbol.asyncIterator]() { return this; },
+  };
+}
+
+function promptOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("Agent prompt options must be an object");
+  }
+  const unsupported = Object.keys(options).find((key) => key !== "id" && key !== "input");
+  if (unsupported) throw new TypeError(`managed Agent prompts do not accept ${unsupported}`);
+  return options.id === undefined
+    ? { input: options.input }
+    : { idempotencyKey: options.id, input: options.input };
+}
+
+function closeManagedAgent(state) {
+  state.closed = true;
+  for (const watcher of [...state.watchers]) watcher.off();
+  state.watchers.clear();
+  state.attachmentAbort.abort();
+  for (const active of state.turns) active.controller.abort(new Error("managed Agent disposed"));
+  state.turns.clear();
+  state.connector?.close();
+  if (state.tools) void state.tools.close().catch(reportError);
+}
+
+function shutdownManagedAgent(state) {
+  if (state.closing) return state.closing;
+  if (state.closed) return Promise.resolve();
+  state.closed = true;
+  for (const watcher of [...state.watchers]) watcher.off();
+  state.watchers.clear();
+  state.attachmentAbort.abort();
+  state.connector?.close();
+  state.closing = (async () => {
+    const activeTurns = [...state.turns];
+    await Promise.allSettled(activeTurns.map(async (active) => {
+      try { await active.turn.cancel(); }
+      finally { active.controller.abort(new Error("managed Agent shut down")); }
+    }));
+    for (const active of activeTurns) state.turns.delete(active);
+    await state.attachmentSupervisor;
+    await state.tools?.close();
+  })();
+  return state.closing;
+}
+
+function requireOpen(state) {
+  if (state.closed) throw new Error("the Nanocodex agent has been disposed");
+}
+
+function validateTransportOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("managed transport options must be an object");
+  }
+  const unsupported = Object.keys(options).find((key) => !TRANSPORT_OPTIONS.has(key));
+  if (unsupported) throw new TypeError(`managed transport does not accept ${unsupported}`);
+  const identity = options.agent;
+  if (!identity || typeof identity !== "object" || Array.isArray(identity)) {
+    throw new TypeError("managed transport requires agent: { create: true } or agent: { id }");
+  }
+  const keys = Object.keys(identity);
+  if (keys.length !== 1) {
+    throw new TypeError("managed transport requires exactly one explicit create or existing agent identity");
+  }
+  if (keys[0] === "create" && identity.create === true) return;
+  if (keys[0] === "id" && typeof identity.id === "string" && MANAGED_AGENT_ID.test(identity.id)) return;
+  throw new TypeError("managed transport requires agent: { create: true } or agent: { id: uuidV7 }");
+}
+
+function validateCreateOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("Agent.create options must be an object");
+  }
+  const unsupported = Object.keys(options).find((key) => !CREATE_OPTIONS.has(key));
+  if (unsupported) throw new TypeError(`managed Agent.create does not accept ${unsupported}`);
+}
+
+function mergeExtensions(left, right) {
+  const merged = { ...left };
+  for (const [key, value] of Object.entries(right)) {
+    merged[key] = value && typeof value === "object" && !Array.isArray(value)
+      && merged[key] && typeof merged[key] === "object" && !Array.isArray(merged[key])
+      ? mergeExtensions(merged[key], value)
+      : value;
+  }
+  return merged;
+}