totemlayer 0.1.97 → 0.1.115

package/bin/native-pi-bridge.mjs

@@ -0,0 +1,170 @@
+import { spawn, execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { realpath } from "node:fs/promises";
+import { StringDecoder } from "node:string_decoder";
+import { localClientEnvironment } from "./platform-client.mjs";
+
+const fail = (code) => Object.assign(new Error(code), { code });
+const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+function supportedPolicyArgs(args) {
+  for (let index = 0; index < args.length; index++) {
+    const value = args[index];
+    if (["--no-extensions", "--no-skills", "--no-prompt-templates", "--no-builtin-tools"].includes(value)) continue;
+    if (["-e", "--extension"].includes(value) && args[++index] === "builtin:mcp") continue;
+    if (value === "--tools" && /^[A-Za-z0-9_,:.-]+$/.test(args[++index] ?? "")) continue;
+    return false; // Never accept a positional startup prompt or an arbitrary extension.
+  }
+  return true;
+}
+
+/** Setup supplies an owned dedicated session and its observed native settings.
+ * Queued messages may supply prompt text, never invocation or binding settings.
+ * This bridge proves native execution, not a Totem reply or durable installation.
+ */
+export function createPiNativeBridge(binding, options = {}) {
+  if (
+    binding?.dedicated !== true || !uuid.test(binding.sessionId ?? "") ||
+    ![binding.node, binding.cliPath, binding.cwd, binding.sessionFile].every(v => typeof v === "string" && isAbsolute(v) && !/[\0\r\n]/.test(v)) ||
+    ![binding.provider, binding.model, binding.thinkingLevel].every(v => typeof v === "string" && /^[a-zA-Z0-9._:/-]{1,128}$/.test(v)) ||
+    !Array.isArray(binding.args) || binding.args.length > 64 ||
+    !binding.args.every(v => typeof v === "string" && v.length < 4096 && !/\0|tn_(?:live|test)_|Bearer\s/i.test(v)) ||
+    !supportedPolicyArgs(binding.args)
+  ) throw fail("NATIVE_PI_BINDING_INVALID");
+  const settings = structuredClone(binding);
+  const environment = localClientEnvironment(options.env ?? process.env);
+  // A background host must use its own saved sign-in. Coordinator credentials
+  // could silently select a different provider account or override native OAuth.
+  for (const key of Object.keys(environment)) {
+    if (/^(TOTEM|AGENTTRUST)_|^(OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)$/i.test(key)) delete environment[key];
+  }
+  let child, closing, closed = false, busy = false, turn, buffer = "", sessionPath;
+  const pending = new Map(), decoder = new StringDecoder("utf8");
+  const requestTimeoutMs = options.requestTimeoutMs ?? 10000;
+
+  function rejectAll(code) {
+    for (const item of pending.values()) { clearTimeout(item.timer); item.reject(fail(code)); }
+    pending.clear();
+    turn?.finish(fail(code));
+  }
+  function terminal(code) {
+    rejectAll(code);
+    void close();
+  }
+  function accept(record) {
+    if (!record || typeof record !== "object" || Array.isArray(record)) return terminal("NATIVE_PI_PROTOCOL_INVALID");
+    if (record.type === "response") {
+      const item = pending.get(record.id);
+      if (!item || item.command !== record.command) return terminal("NATIVE_PI_PROTOCOL_INVALID");
+      clearTimeout(item.timer); pending.delete(record.id);
+      if (record.success !== true) item.reject(fail("NATIVE_PI_COMMAND_FAILED"));
+      else item.resolve(record.data);
+    } else if (record.type === "extension_ui_request") {
+      terminal("NATIVE_PI_INTERACTION_REQUIRED");
+    } else if (record.type === "message_end" && record.message?.role === "assistant" && ["error", "aborted"].includes(record.message.stopReason)) {
+      if (turn) turn.failed = true;
+    } else if (record.type === "agent_settled" && turn) {
+      turn.settled = true;
+      if (turn.accepted) turn.finish(turn.failed ? fail("NATIVE_PI_TURN_FAILED") : undefined);
+    }
+  }
+  function request(type, values = {}) {
+    if (!child || closed || closing || child.exitCode !== null || child.signalCode !== null) return Promise.reject(fail("NATIVE_PI_UNAVAILABLE"));
+    const id = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { terminal("NATIVE_PI_REQUEST_TIMEOUT"); }, requestTimeoutMs);
+      pending.set(id, { command: type, resolve, reject, timer });
+      child.stdin.write(JSON.stringify({ ...values, type, id }) + "\n", error => {
+        if (error && pending.has(id)) { clearTimeout(timer); pending.delete(id); reject(fail("NATIVE_PI_UNAVAILABLE")); }
+      });
+    });
+  }
+  async function inspect() {
+    const state = await request("get_state");
+    const observedPath = typeof state?.sessionFile === "string" ? await realpath(state.sessionFile).catch(() => undefined) : undefined;
+    if (state?.sessionId !== settings.sessionId || observedPath !== sessionPath) throw fail("NATIVE_PI_SESSION_CHANGED");
+    if (state.model?.provider !== settings.provider || state.model?.id !== settings.model || state.thinkingLevel !== settings.thinkingLevel) throw fail("NATIVE_PI_MODEL_CHANGED");
+    return { sessionId: state.sessionId, sessionFile: sessionPath, provider: state.model.provider, model: state.model.id,
+      thinkingLevel: state.thinkingLevel, isStreaming: state.isStreaming, pendingMessageCount: state.pendingMessageCount };
+  }
+  async function close() {
+    if (closing) return closing;
+    closed = true; rejectAll("NATIVE_PI_CLOSED");
+    if (!child) return;
+    closing = new Promise(resolve => {
+      if (child.exitCode !== null || child.signalCode !== null) return resolve();
+      let force;
+      const timer = setTimeout(() => {
+        if (child.exitCode !== null || child.signalCode !== null) return;
+        if (process.platform === "win32") {
+          execFile("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true, timeout: 3000 }, () => {});
+        } else child.kill("SIGTERM");
+        force = setTimeout(() => {
+          if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+        }, 2000);
+      }, 2000);
+      child.once("close", () => { clearTimeout(timer); clearTimeout(force); resolve(); });
+      child.stdin.end();
+    });
+    return closing;
+  }
+  return {
+    async open() {
+      if (child || closed) throw fail("NATIVE_PI_ALREADY_OPENED");
+      sessionPath = await realpath(settings.sessionFile).catch(() => { throw fail("NATIVE_PI_SESSION_UNAVAILABLE"); });
+      try { child = (options.spawn ?? spawn)(settings.node, [settings.cliPath, "--mode", "rpc", ...settings.args,
+        "--session", sessionPath, "--provider", settings.provider, "--model", settings.model, "--thinking", settings.thinkingLevel],
+      { cwd: settings.cwd, env: environment, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }); }
+      catch { closed = true; throw fail("NATIVE_PI_START_FAILED"); }
+      child.stderr.resume(); // Provider diagnostics never enter returned results or shared logs.
+      child.stdin.on("error", () => terminal("NATIVE_PI_UNAVAILABLE"));
+      child.once("error", () => rejectAll("NATIVE_PI_START_FAILED"));
+      child.once("exit", () => { closed = true; rejectAll("NATIVE_PI_PROCESS_EXITED"); });
+      child.stdout.on("data", bytes => {
+        buffer += decoder.write(bytes);
+        if (Buffer.byteLength(buffer) > 8 * 1024 * 1024) { rejectAll("NATIVE_PI_OUTPUT_LIMIT"); void close(); return; }
+        let index;
+        while ((index = buffer.indexOf("\n")) >= 0) {
+          const line = buffer.slice(0, index).replace(/\r$/, ""); buffer = buffer.slice(index + 1);
+          if (!line) continue;
+          try { accept(JSON.parse(line)); } catch { rejectAll("NATIVE_PI_PROTOCOL_INVALID"); void close(); }
+        }
+      });
+      try { return await inspect(); } catch (error) { await close(); throw error; }
+    },
+    inspect,
+    async run(message, { signal, timeoutMs = 120000 } = {}) {
+      if (typeof message !== "string" || !message.trim() || Buffer.byteLength(message) > 65536 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 900000) throw fail("NATIVE_PI_PROMPT_INVALID");
+      if (busy) throw fail("NATIVE_PI_BUSY");
+      if (signal?.aborted) throw fail("NATIVE_PI_CANCELLED");
+      busy = true;
+      try {
+      const state = await inspect();
+      if (state.isStreaming || state.pendingMessageCount) throw fail("NATIVE_PI_BUSY");
+      await new Promise((resolve, reject) => {
+        const abort = () => { void request("abort").catch(() => {}); active.finish(fail("NATIVE_PI_CANCELLED")); };
+        const timer = setTimeout(() => { void request("abort").catch(() => {}); active.finish(fail("NATIVE_PI_TURN_TIMEOUT")); }, timeoutMs);
+        const active = { accepted: false, settled: false, failed: false, finish(error) {
+          if (turn !== active) return;
+          turn = undefined; clearTimeout(timer); signal?.removeEventListener("abort", abort);
+          if (error) reject(error); else resolve();
+        } };
+        turn = active; signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) return abort();
+        void request("prompt", { message }).then(data => {
+          if (data?.disposition !== "started") return active.finish(fail("NATIVE_PI_WAKE_UNVERIFIED"));
+          active.accepted = true;
+          if (active.settled) active.finish(active.failed ? fail("NATIVE_PI_TURN_FAILED") : undefined);
+        }, () => active.finish(fail("NATIVE_PI_COMMAND_FAILED")));
+      });
+      return { nativeRunSettled: true, ...await inspect() };
+      } catch (error) {
+        // RPC events carry no turn identifier. Retiring this process after an
+        // uncertain run prevents a late agent_settled from completing new work.
+        await close();
+        throw error;
+      } finally { busy = false; }
+    },
+    close,
+  };
+}

package/bin/native-pi-installation.mjs

@@ -0,0 +1,9 @@
+import { createPiNativeBridge } from "./native-pi-bridge.mjs";
+import { createPiMcpSurface } from "./native-pi-mcp.mjs";
+import { installNativeInboxReceiver } from "./native-inbox-installation.mjs";
+
+export function installPiNativeReceiver(root, config, options = {}) {
+  return installNativeInboxReceiver(root, config, { kind: "pi", createBridge: createPiNativeBridge, createSurface: createPiMcpSurface,
+    files: ["native-pi-bridge.mjs", "native-pi-mcp.mjs", "native-mcp-source.mjs", "native-pi-receiver.mjs", "native-inbox-receiver.mjs"],
+  }, options);
+}

package/bin/native-pi-mcp.mjs

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { localClientEnvironment } from "./platform-client.mjs";
+
+const fail = code => Object.assign(new Error(code), { code });
+const checkerTools = new Set([
+  "totem_get_identity", "totem_start_listener", "totem_listen",
+  "totem_list_messages", "totem_list_chat_commands", "totem_get_chat", "totem_get_conversation", "totem_get_activity",
+]);
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  return value;
+}
+
+/** Fingerprints stay local. Neither native configuration nor OAuth state is returned. */
+export function piMcpBindingFingerprint(entry) {
+  return createHash("sha256").update(JSON.stringify(canonical({
+    name: entry.name, config: entry.config, source: entry.source,
+    scope: entry.scope, override: entry.override,
+  }))).digest("hex");
+}
+
+async function loadNative(root) {
+  const load = path => import(pathToFileURL(join(root, "dist", path)).href);
+  const [config, runtime, auth] = await Promise.all([
+    load("extensions/mcp/config.js"), load("extensions/mcp/runtime.js"), load("core/auth-storage.js"),
+  ]);
+  return { ...config, ...runtime, ...auth };
+}
+
+/** Uses the installed host's transport and refresh locks, never a copied token.
+ * Binding and module loading are supplied by trusted local setup, never messages.
+ * Only the fixed inbox-checker tools are callable through this surface.
+ */
+export async function createPiMcpSurface(binding, options = {}) {
+  if (!binding || ![binding.nativeRoot, binding.agentDir, binding.cwd].every(value =>
+    typeof value === "string" && isAbsolute(value) && !/[\0\r\n]/.test(value)) ||
+    !/^[a-zA-Z0-9_-]{1,80}$/.test(binding.serverName ?? "") ||
+    !/^[a-f0-9]{64}$/.test(binding.serverFingerprint ?? "") ||
+    !/^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.-]+)?$/.test(binding.nativeVersion ?? "") ||
+    typeof binding.projectTrusted !== "boolean") throw fail("NATIVE_PI_MCP_BINDING_INVALID");
+  const saved = structuredClone(binding);
+  const environment = localClientEnvironment(options.env ?? process.env);
+  for (const key of Object.keys(environment)) {
+    if (/^(TOTEM|AGENTTRUST)_|^(OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)$/i.test(key)) delete environment[key];
+  }
+  let native, connection, closing, incoming = false, closed = false;
+  try {
+    const manifest = JSON.parse(await readFile(join(saved.nativeRoot, "package.json"), "utf8"));
+    if (manifest.name !== "@earendil-works/pi-coding-agent" || manifest.version !== saved.nativeVersion) throw fail("NATIVE_PI_VERSION_CHANGED");
+    native = await (options.loadNative ?? loadNative)(saved.nativeRoot);
+  } catch (error) {
+    throw fail(error.code === "NATIVE_PI_VERSION_CHANGED" ? error.code : "NATIVE_PI_MCP_UNAVAILABLE");
+  }
+  function inspect() {
+    if (closed) throw fail("NATIVE_PI_MCP_CLOSED");
+    let loaded;
+    try { loaded = native.loadMcpConfig({ agentDir: saved.agentDir, cwd: saved.cwd, projectTrusted: saved.projectTrusted }); }
+    catch { throw fail("NATIVE_PI_MCP_CONFIG_INVALID"); }
+    if (loaded.errors?.length) throw fail("NATIVE_PI_MCP_CONFIG_INVALID");
+    const entry = loaded.servers?.find(server => server.name === saved.serverName);
+    if (!entry) throw fail("NATIVE_PI_MCP_CONFIG_CHANGED");
+    if (entry.config.enabled === false) throw fail("LISTENER_PAUSED");
+    if (piMcpBindingFingerprint(entry) !== saved.serverFingerprint) throw fail("NATIVE_PI_MCP_CONFIG_CHANGED");
+    // Provider-token forwarding is a distinct grant; this adapter uses MCP OAuth
+    // or the owner's already-configured stdio connection only.
+    if (entry.config.auth?.provider) throw fail("NATIVE_PI_MCP_AUTH_UNSUPPORTED");
+    return entry;
+  }
+  async function close() {
+    closed = true;
+    closing ??= Promise.resolve().then(() => connection?.close()).catch(() => { throw fail("NATIVE_PI_MCP_CLOSE_FAILED"); });
+    await closing;
+  }
+  function safeError(error) {
+    const known = ["RUN_CANCELLED", "LISTENER_PAUSED", "NATIVE_PI_MCP_CLOSED", "NATIVE_PI_MCP_CONFIG_INVALID", "NATIVE_PI_MCP_CONFIG_CHANGED", "NATIVE_PI_MCP_AUTH_UNSUPPORTED", "MCP_TOOL_UNAVAILABLE"];
+    if (known.includes(error.code)) return fail(error.code);
+    if (connection?.state === "needs-auth") return fail("AGENT_AUTH_REQUIRED");
+    if (error.name === "AbortError" || error.name === "TimeoutError") return fail(error.name === "TimeoutError" ? "TIMEOUT" : "RUN_CANCELLED");
+    const result = fail("NATIVE_PI_MCP_CALL_FAILED");
+    if (Number.isInteger(error.status) && error.status >= 400 && error.status <= 599) result.status = error.status;
+    return result;
+  }
+  try {
+    const entry = inspect();
+    connection = new native.McpServerConnection({
+      entry, cwd: saved.cwd, createTransport(current, cwd, authProvider) {
+        const transport = native.createDefaultTransport(current, cwd, authProvider);
+        if ("url" in current.config) {
+          incoming = typeof transport?.startGetStream === "function" && typeof transport?.openSseStream === "function";
+          return transport;
+        }
+        if (!transport?.options || transport.constructor === Object || typeof transport.constructor !== "function") throw fail("NATIVE_PI_MCP_UNAVAILABLE");
+        // The native transport resolves the owner's explicit server env. Retain
+        // that grant while excluding unrelated coordinator process credentials.
+        return new transport.constructor({ ...transport.options,
+          inheritEnv: false, env: { ...environment, ...transport.options.env },
+        });
+      },
+      credentials: new native.McpOAuthCredentialStore(
+        new native.FileAuthStorageBackend(join(saved.agentDir, "mcp-auth.json")), saved.agentDir,
+      ),
+      onTools() {},
+    });
+    const connectSignal = AbortSignal.any([...(options.signal ? [options.signal] : []), AbortSignal.timeout(20000)]);
+    const cancel = () => { void close().catch(() => {}); };
+    connectSignal.addEventListener("abort", cancel, { once: true });
+    try {
+      if (connectSignal.aborted) throw fail("RUN_CANCELLED");
+      await connection.getClient();
+      if (connectSignal.aborted) throw fail("RUN_CANCELLED");
+    } finally { connectSignal.removeEventListener("abort", cancel); }
+  } catch (error) {
+    const safe = safeError(error);
+    await close().catch(() => {});
+    throw safe;
+  }
+  return {
+    get nativeIncoming() { return incoming; },
+    inspect: () => { inspect(); return { serverName: saved.serverName, nativeVersion: saved.nativeVersion, connected: connection.state === "connected" }; },
+    listTools() {
+      const entry = inspect();
+      return connection.tools.filter(tool => checkerTools.has(tool.name) && native.getMcpToolExposure(entry.config, tool.name) !== "hidden")
+        .map(tool => ({ name: tool.name, inputSchema: structuredClone(tool.inputSchema) }));
+    },
+    async call(name, args = {}, { signal } = {}) {
+      try {
+        const entry = inspect();
+        if (!checkerTools.has(name) || native.getMcpToolExposure(entry.config, name) === "hidden" ||
+          !connection.tools.some(tool => tool.name === name)) throw fail("MCP_TOOL_UNAVAILABLE");
+        return await connection.callTool(name, args, { signal });
+      } catch (error) { throw safeError(error); }
+    },
+    close,
+  };
+}

package/bin/native-pi-receiver.mjs

@@ -0,0 +1,28 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { privateRead } from "./runtime-installation.mjs";
+import { createPiNativeBridge } from "./native-pi-bridge.mjs";
+import { createPiMcpSurface } from "./native-pi-mcp.mjs";
+import { runNativeInboxReceiver } from "./native-inbox-receiver.mjs";
+
+const fail = code => Object.assign(new Error(code), { code });
+const safe = error => /^[A-Z0-9_]{1,100}$/.test(error?.code ?? "") ? error.code : "NATIVE_PI_RECEIVER_FAILED";
+export function runPiNativeReceiver(config, options = {}) {
+  return runNativeInboxReceiver(config, { kind: "pi", createBridge: createPiNativeBridge, createSurface: createPiMcpSurface }, options);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once("SIGTERM", stop); process.once("SIGINT", stop);
+  try {
+    if (!process.argv[2]) throw fail("NATIVE_PI_RECEIVER_CONFIG_REQUIRED");
+    const result = await runPiNativeReceiver(await privateRead(resolve(process.argv[2])), { signal: controller.signal });
+    if (result.state === "paused") {
+      // A service must remain quiet while paused, rather than restarting a model
+      // or repeatedly reconnecting. Resume is an explicit local setup action.
+      await new Promise(resolve => { if (controller.signal.aborted) resolve(); else controller.signal.addEventListener("abort", resolve, { once: true }); });
+    }
+  } catch (error) { process.stderr.write(safe(error) + "\n"); process.exitCode = 1; }
+  finally { process.off("SIGTERM", stop); process.off("SIGINT", stop); }
+}

package/bin/network-retry.mjs

@@ -8,6 +8,14 @@ export function transientNetworkError(error) {
   );
 }
 
+// Server cooldowns are minimum waits, including after SDK retries are exhausted.
+export function networkRetryDelay(error, fallbackMs) {
+  const seconds = error?.retryAfterSeconds;
+  return Number.isSafeInteger(seconds) && seconds > 0 && seconds <= 86400
+    ? Math.max(fallbackMs, seconds * 1000)
+    : fallbackMs;
+}
+
 // Only use for reads or mutations protected by a durable idempotency key.
 export async function retryNetwork(
   operation,
@@ -20,7 +28,7 @@ export async function retryNetwork(
     } catch (error) {
       if (signal?.aborted || !transientNetworkError(error) || attempt + 1 >= attempts) throw error;
       onRetry(error);
-      await pause(Math.min(delayMs * 2 ** attempt, 10000), signal);
+      await pause(networkRetryDelay(error, Math.min(delayMs * 2 ** attempt, 10000)), signal);
     }
   }
 }

package/bin/runtime-installation.mjs

@@ -223,16 +223,19 @@ if (process.env.TOTEM_RUNTIME_ENV_LOADED === entry) {
     stopping = true; controller.abort(); child?.kill(signal);
   }]);
   for (const [signal, handler] of handlers) process.once(signal, handler);
+  ${target === "automatic-runtime.mjs" ? `const { watchSupervisorChild } = await import(pathToFileURL(join(modulePath, '..', 'supervisor-watchdog.mjs')));` : ""}
   do {
     const started = Date.now();
     child = spawn(process.execPath, [entry, ...process.argv.slice(2)], {
       env: { ...environment, TOTEM_CONFIG_DIR: join(root, '..'), TOTEM_RUNTIME_ENV_LOADED: entry },
       stdio: 'inherit',
     });
+    ${target === "automatic-runtime.mjs" ? "const stopWatchdog = watchSupervisorChild(child, root);" : ""}
     const code = await new Promise((resolve) => {
       child.once('error', () => resolve(1));
       child.once('exit', (code) => resolve(code ?? 1));
     });
+    ${target === "automatic-runtime.mjs" ? "stopWatchdog();" : ""}
     ${
       target === "automatic-runtime.mjs"
         ? `if (code === 0) break;
@@ -415,7 +418,7 @@ export async function installRuntimeService(runtime, env = process.env, options
         if (exact) {
           const signal = options.processSignal ?? process.kill;
           signal(status.pid, "SIGTERM");
-          const deadline = Date.now() + 20000;
+          const deadline = Date.now() + (options.stopTimeoutMs ?? 20000);
           while (Date.now() < deadline) {
             try {
               signal(status.pid, 0);
@@ -425,6 +428,8 @@ export async function installRuntimeService(runtime, env = process.env, options
             }
             await new Promise((resolve) => setTimeout(resolve, 100));
           }
+          if ((await (options.processIdentity ?? processIdentity)(status.pid, owner.identity)) === owner.identity)
+            signal(status.pid, "SIGKILL");
         }
       }
     } catch {

package/bin/sdk/errors.d.ts

@@ -27,4 +27,4 @@ export declare class TotemNetworkError extends TotemError {
 }
 export declare class TotemCanceledError extends TotemError {
 }
-export declare function apiError(status: number, body: unknown, requestId?: string): TotemError;
+export declare function apiError(status: number, body: unknown, requestId?: string, headerRetryAfterSeconds?: number): TotemError;

package/bin/sdk/errors.js

@@ -1 +1 @@
-class TotemError extends Error{code;status;requestId;retryAfterSeconds;constructor(message,options){super(message,{cause:options.cause});this.name=new.target.name;this.code=options.code;this.status=options.status;this.requestId=options.requestId;this.retryAfterSeconds=options.retryAfterSeconds}}class TotemAuthenticationError extends TotemError{}class TotemPermissionError extends TotemError{}class TotemNotFoundError extends TotemError{}class TotemConflictError extends TotemError{}class TotemRateLimitError extends TotemError{}class TotemTimeoutError extends TotemError{}class TotemNetworkError extends TotemError{}class TotemCanceledError extends TotemError{}function apiError(status,body,requestId){const error=body&&typeof body==="object"&&"error"in body&&body.error&&typeof body.error==="object"?body.error:{};const message="message"in error&&typeof error.message==="string"?error.message:`Totem request failed (${status}).`;const code="code"in error&&typeof error.code==="string"?error.code:"HTTP_ERROR";const id="requestId"in error&&typeof error.requestId==="string"?error.requestId:requestId;const Constructor=status===401?TotemAuthenticationError:status===403?TotemPermissionError:status===404?TotemNotFoundError:status===409?TotemConflictError:status===429?TotemRateLimitError:TotemError;const details="details"in error?error.details:void 0;const retryAfter=details&&typeof details==="object"&&"retryAfterSeconds"in details?details.retryAfterSeconds:void 0;const retryAfterSeconds=status===429&&typeof retryAfter==="number"&&Number.isSafeInteger(retryAfter)&&retryAfter>0&&retryAfter<=86400?retryAfter:void 0;return new Constructor(message,{code,status,requestId:id,retryAfterSeconds})}export{TotemAuthenticationError,TotemCanceledError,TotemConflictError,TotemError,TotemNetworkError,TotemNotFoundError,TotemPermissionError,TotemRateLimitError,TotemTimeoutError,apiError};
+class TotemError extends Error{code;status;requestId;retryAfterSeconds;constructor(message,options){super(message,{cause:options.cause});this.name=new.target.name;this.code=options.code;this.status=options.status;this.requestId=options.requestId;this.retryAfterSeconds=options.retryAfterSeconds}}class TotemAuthenticationError extends TotemError{}class TotemPermissionError extends TotemError{}class TotemNotFoundError extends TotemError{}class TotemConflictError extends TotemError{}class TotemRateLimitError extends TotemError{}class TotemTimeoutError extends TotemError{}class TotemNetworkError extends TotemError{}class TotemCanceledError extends TotemError{}function apiError(status,body,requestId,headerRetryAfterSeconds){const error=body&&typeof body==="object"&&"error"in body&&body.error&&typeof body.error==="object"?body.error:{};const message="message"in error&&typeof error.message==="string"?error.message:`Totem request failed (${status}).`;const code="code"in error&&typeof error.code==="string"?error.code:"HTTP_ERROR";const id="requestId"in error&&typeof error.requestId==="string"?error.requestId:requestId;const Constructor=status===401?TotemAuthenticationError:status===403?TotemPermissionError:status===404?TotemNotFoundError:status===409?TotemConflictError:status===429?TotemRateLimitError:TotemError;const details="details"in error?error.details:void 0;const retryAfter=details&&typeof details==="object"&&"retryAfterSeconds"in details?details.retryAfterSeconds:void 0;const delays=[retryAfter,headerRetryAfterSeconds].filter(value=>[429,503].includes(status)&&typeof value==="number"&&Number.isSafeInteger(value)&&value>0&&value<=86400);const retryAfterSeconds=delays.length?Math.max(...delays):void 0;return new Constructor(message,{code,status,requestId:id,retryAfterSeconds})}export{TotemAuthenticationError,TotemCanceledError,TotemConflictError,TotemError,TotemNetworkError,TotemNotFoundError,TotemPermissionError,TotemRateLimitError,TotemTimeoutError,apiError};

package/bin/sdk/listener.d.ts

@@ -1,5 +1,6 @@
 import type { Totem } from "./index.js";
 export declare const DEFAULT_LISTENER_POLL_MS = 5000;
+export declare function listenerRetryDelay(retryAfterSeconds: unknown, pollMs?: number): number;
 export type ListenerStatus = {
     state: string;
     listenerReady: boolean;

package/bin/sdk/listener.js

@@ -1 +1 @@
-import{sleep}from"./transport.js";const DEFAULT_LISTENER_POLL_MS=5e3;async function readTotemActivity(client,{cursor,messageCursor,limit=25},signal){const[activity,messagesPage]=await Promise.all([client.activity.list({cursor,limit},{signal}),client.messages.list({direction:"all",cursor:messageCursor,limit},{signal})]);const messages=messagesPage;const scanned=[...messages.data,...messages.blocked??[]];const last=scanned.reduce((value,row)=>BigInt(row.sequence)>BigInt(value)?row.sequence:value,messageCursor??"0");return{activity,messages:{...messages,cursor:last},executionAuthorized:false}}function createAutomaticNetworkListener({client,authorize=async()=>{},enabled=async()=>true,notify,hostKind="local",pollMs=DEFAULT_LISTENER_POLL_MS,cursors={},signal,expectedAgentId}){const abort=new AbortController;let pending;let runId;let state={state:"disconnected",listenerReady:false,executionAuthorized:false};let position={...cursors};const options={signal:abort.signal};signal?.addEventListener("abort",()=>abort.abort(),{once:true});if(signal?.aborted)abort.abort();async function status(next){if(state.state===next.state&&state.runId===next.runId)return;state={listenerReady:false,executionAuthorized:false,...next};await notify("totem.listener",state)}async function loop(){try{if(!await enabled()){await status({state:"paused"});return}while(!abort.signal.aborted){let delay=pollMs;try{if(!await enabled()){await status({state:"paused"});break}await authorize(abort.signal);if(!runId){const identity=await client.agent(options);if(expectedAgentId&&identity.id!==expectedAgentId||!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(identity.id)||!["PRODUCTION","SANDBOX"].includes(identity.environment))throw Object.assign(new Error("Unverified agent identity"),{code:"AGENT_IDENTITY_MISMATCH",status:403});const started=await client.runtime.start({runId:globalThis.crypto.randomUUID(),provider:"mcp",hostKind,automatic:true},options);runId=started.runId;const probe=await client.runtime.probe(runId,options);if(probe.provider!=="mcp")throw Object.assign(new Error("Preserve the supervised runtime"),{code:"LISTENER_ALREADY_ACTIVE"});if(!probe.completed)await client.runtime.replyProbe({runId,reply:`TOTEM_READY:${probe.challenge}`},options)}await client.runtime.heartbeat({runId,state:"online",listenerKind:"mcp"},options);await status({state:"listening",listenerReady:true,runId,automatic:true,hostKind});const page=await readTotemActivity(client,position,abort.signal);if(page.activity.data.length||page.messages.data.length||page.messages.blocked?.length){await notify("totem.activity",page,`${page.activity.cursor}:${page.messages.cursor}`)}position={cursor:page.activity.cursor,messageCursor:page.messages.cursor};if(page.activity.nextCursor||page.messages.nextCursor)delay=0}catch(caught){const error=caught;if(abort.signal.aborted)break;if([401,403].includes(error.status??0)||error.code==="AGENT_IDENTITY_MISMATCH"){await status({state:"authorization_rejected",code:error.code});break}runId=void 0;const paused=["LISTENER_PAUSED","LISTENER_STOPPED"].includes(error.code??"");await status({state:paused?"paused":error.code==="LISTENER_ALREADY_ACTIVE"?"managed":"reconnecting",code:error.code??"NETWORK_ERROR"});delay=Math.max(pollMs,Math.min(3e4,(error.retryAfterSeconds??5)*1e3))}await sleep(delay,abort.signal)}}catch(caught){const error=caught;if(!abort.signal.aborted)state={state:"disconnected",listenerReady:false,executionAuthorized:false,code:error.code??"MCP_TRANSPORT_CLOSED"}}finally{state={...state,state:["listening","disconnected"].includes(state.state)?"disconnected":state.state,listenerReady:false}}}return{start(){pending??=loop()},async stop(){abort.abort();await pending},status(){return{...state}},async done(){await pending}}}export{DEFAULT_LISTENER_POLL_MS,createAutomaticNetworkListener,readTotemActivity};
+import{sleep}from"./transport.js";const DEFAULT_LISTENER_POLL_MS=5e3;function listenerRetryDelay(retryAfterSeconds,pollMs=DEFAULT_LISTENER_POLL_MS){const serverDelay=Number.isSafeInteger(retryAfterSeconds)&&retryAfterSeconds>0&&retryAfterSeconds<=86400?retryAfterSeconds*1e3:5e3;return Math.max(pollMs,serverDelay)}async function readTotemActivity(client,{cursor,messageCursor,limit=25},signal){const[activity,messagesPage]=await Promise.all([client.activity.list({cursor,limit},{signal}),client.messages.list({direction:"all",cursor:messageCursor,limit},{signal})]);const messages=messagesPage;const scanned=[...messages.data,...messages.blocked??[]];const last=scanned.reduce((value,row)=>BigInt(row.sequence)>BigInt(value)?row.sequence:value,messageCursor??"0");return{activity,messages:{...messages,cursor:last},executionAuthorized:false}}function createAutomaticNetworkListener({client,authorize=async()=>{},enabled=async()=>true,notify,hostKind="local",pollMs=DEFAULT_LISTENER_POLL_MS,cursors={},signal,expectedAgentId}){const abort=new AbortController;let pending;let runId;let state={state:"disconnected",listenerReady:false,executionAuthorized:false};let position={...cursors};const options={signal:abort.signal};signal?.addEventListener("abort",()=>abort.abort(),{once:true});if(signal?.aborted)abort.abort();async function status(next){if(state.state===next.state&&state.runId===next.runId)return;state={listenerReady:false,executionAuthorized:false,...next};await notify("totem.listener",state)}async function loop(){try{if(!await enabled()){await status({state:"paused"});return}while(!abort.signal.aborted){let delay=pollMs;try{if(!await enabled()){await status({state:"paused"});break}await authorize(abort.signal);if(!runId){const identity=await client.agent(options);if(expectedAgentId&&identity.id!==expectedAgentId||!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(identity.id)||!["PRODUCTION","SANDBOX"].includes(identity.environment))throw Object.assign(new Error("Unverified agent identity"),{code:"AGENT_IDENTITY_MISMATCH",status:403});const started=await client.runtime.start({runId:globalThis.crypto.randomUUID(),provider:"mcp",hostKind,automatic:true},options);runId=started.runId;const probe=await client.runtime.probe(runId,options);if(probe.provider!=="mcp")throw Object.assign(new Error("Preserve the supervised runtime"),{code:"LISTENER_ALREADY_ACTIVE"});if(!probe.completed)await client.runtime.replyProbe({runId,reply:`TOTEM_READY:${probe.challenge}`},options)}await client.runtime.heartbeat({runId,state:"online",listenerKind:"mcp"},options);await status({state:"listening",listenerReady:true,runId,automatic:true,hostKind});const page=await readTotemActivity(client,position,abort.signal);if(page.activity.data.length||page.messages.data.length||page.messages.blocked?.length){await notify("totem.activity",page,`${page.activity.cursor}:${page.messages.cursor}`)}position={cursor:page.activity.cursor,messageCursor:page.messages.cursor};if(page.activity.nextCursor||page.messages.nextCursor)delay=0}catch(caught){const error=caught;if(abort.signal.aborted)break;if([401,403].includes(error.status??0)||error.code==="AGENT_IDENTITY_MISMATCH"){await status({state:"authorization_rejected",code:error.code});break}runId=void 0;const paused=["LISTENER_PAUSED","LISTENER_STOPPED"].includes(error.code??"");await status({state:paused?"paused":error.code==="LISTENER_ALREADY_ACTIVE"?"managed":"reconnecting",code:error.code??"NETWORK_ERROR"});delay=listenerRetryDelay(error.retryAfterSeconds,pollMs)}await sleep(delay,abort.signal)}}catch(caught){const error=caught;if(!abort.signal.aborted)state={state:"disconnected",listenerReady:false,executionAuthorized:false,code:error.code??"MCP_TRANSPORT_CLOSED"}}finally{state={...state,state:["listening","disconnected"].includes(state.state)?"disconnected":state.state,listenerReady:false}}}return{start(){pending??=loop()},async stop(){abort.abort();await pending},status(){return{...state}},async done(){await pending}}}export{DEFAULT_LISTENER_POLL_MS,createAutomaticNetworkListener,listenerRetryDelay,readTotemActivity};

package/bin/sdk/transport.js

@@ -1 +1 @@
-import{apiError,TotemCanceledError,TotemError,TotemNetworkError,TotemTimeoutError}from"./errors.js";function idempotencyKey(){return globalThis.crypto.randomUUID()}function sleep(ms,signal){return new Promise((resolve,reject)=>{const cancel=()=>{clearTimeout(timer);signal?.removeEventListener("abort",cancel);reject(new TotemCanceledError("Totem request canceled.",{code:"CANCELED"}))};const timer=setTimeout(()=>{signal?.removeEventListener("abort",cancel);resolve()},ms);signal?.addEventListener("abort",cancel,{once:true});if(signal?.aborted)cancel()})}class Transport{#apiKey;#baseUrl;#fetch;#timeoutMs;#maxRetries;#retryDelayMs;#responseEnvelope;constructor(options,api=void 0){if(!options.apiKey?.trim())throw new TotemError("An agent API key is required.",{code:"INVALID_CONFIG"});const url=new URL(options.baseUrl??"https://totemlayer.com");const loopback=["localhost","127.0.0.1","[::1]"].includes(url.hostname);if(url.protocol!=="https:"&&!(url.protocol==="http:"&&loopback)||url.username||url.password||url.search||url.hash||url.pathname!=="/"){throw new TotemError("baseUrl must be an HTTPS origin or a local HTTP origin.",{code:"INVALID_CONFIG"})}this.#apiKey=options.apiKey;this.#baseUrl=`${url.origin}${api?.basePath??"/api/v1/network"}`;this.#responseEnvelope=api?.responseEnvelope??"data";this.#fetch=options.fetch??globalThis.fetch.bind(globalThis);this.#timeoutMs=options.timeoutMs??15e3;this.#maxRetries=options.maxRetries??2;this.#retryDelayMs=options.retryDelayMs??250;if(!Number.isFinite(this.#timeoutMs)||this.#timeoutMs<1||!Number.isInteger(this.#maxRetries)||this.#maxRetries<0||this.#maxRetries>10||!Number.isFinite(this.#retryDelayMs)||this.#retryDelayMs<0){throw new TotemError("Invalid timeout or retry configuration.",{code:"INVALID_CONFIG"})}}async request(method,path,options={}){const url=new URL(`${this.#baseUrl}${path}`);for(const[key,value]of Object.entries(options.query??{})){if(value!==void 0&&value!==null)url.searchParams.set(key,String(value))}const retrySafe=method==="GET"||options.retrySafe===true||Boolean(options.idempotencyKey);const body=options.binaryBody??(options.body===void 0?void 0:JSON.stringify(options.body));const headers={Authorization:`Bearer ${this.#apiKey}`,Accept:"application/json",...body===void 0||options.binaryBody?{}:{"Content-Type":"application/json"},...options.idempotencyKey?{"Idempotency-Key":options.idempotencyKey}:{},...options.headers??{}};for(let attempt=0;;attempt++){if(options.signal?.aborted)throw new TotemCanceledError("Totem request canceled.",{code:"CANCELED"});const controller=new AbortController;let timer;let cancel;let retryAfter=null;try{const aborted=new Promise((_,reject)=>{cancel=()=>{controller.abort();reject(new TotemCanceledError("Totem request canceled.",{code:"CANCELED"}))};options.signal?.addEventListener("abort",cancel,{once:true});if(options.signal?.aborted)cancel();timer=setTimeout(()=>{controller.abort();reject(new TotemTimeoutError("Totem request timed out.",{code:"TIMEOUT"}))},this.#timeoutMs)});const response=(async()=>{const result=await this.#fetch(url.toString(),{method,headers,body:body instanceof Uint8Array?new Uint8Array(body):body,signal:controller.signal,redirect:"error",cache:"no-store"});retryAfter=result.headers.get("Retry-After");const requestId=result.headers.get("X-Request-Id")??void 0;let payload;try{payload=await result.json()}catch{if(!result.ok)throw apiError(result.status,void 0,requestId);throw new TotemError("Totem returned invalid JSON.",{code:"INVALID_RESPONSE",requestId})}if(!result.ok)throw apiError(result.status,payload,requestId);if(!payload||typeof payload!=="object"||Array.isArray(payload)||this.#responseEnvelope==="data"&&!("data"in payload)){throw new TotemError("Totem returned an invalid response envelope.",{code:"INVALID_RESPONSE",requestId})}return payload})();return await Promise.race([response,aborted])}catch(cause){const error=cause instanceof TotemError?cause:new TotemNetworkError("Unable to reach Totem.",{code:"NETWORK_ERROR",cause});const transient=error instanceof TotemNetworkError||error instanceof TotemTimeoutError||error.status!==void 0&&[408,429,500,502,503,504].includes(error.status);if(!retrySafe||!transient||attempt>=this.#maxRetries)throw error;clearTimeout(timer);if(cancel)options.signal?.removeEventListener("abort",cancel);const seconds=retryAfter===null?NaN:Number(retryAfter);const parsedDate=retryAfter===null?NaN:Date.parse(retryAfter);const requestedDelay=Number.isFinite(seconds)?seconds*1e3:parsedDate-Date.now();const fallback=this.#retryDelayMs*2**attempt*(.75+Math.random()*.5);await sleep(Math.min(3e4,Math.max(0,Number.isFinite(requestedDelay)?requestedDelay:fallback)),options.signal)}finally{clearTimeout(timer);if(cancel)options.signal?.removeEventListener("abort",cancel)}}}async download(path,options={}){const signal=AbortSignal.any([options.signal,AbortSignal.timeout(this.#timeoutMs)].filter(Boolean));let response;try{response=await this.#fetch(`${this.#baseUrl}${path}`,{method:"GET",headers:{Authorization:`Bearer ${this.#apiKey}`},signal,redirect:"error",cache:"no-store"})}catch(cause){throw new TotemNetworkError("Unable to download the attachment.",{code:"NETWORK_ERROR",cause})}if(!response.ok){const payload=await response.json().catch(()=>void 0);throw apiError(response.status,payload,response.headers.get("x-request-id")??void 0)}const reported=Number(response.headers.get("content-length"));if(reported>2*1024*1024){await response.body?.cancel().catch(()=>{});throw new TotemError("The attachment exceeds the 2 MiB limit.",{code:"ATTACHMENT_TOO_LARGE"})}const reader=response.body?.getReader();const chunks=[];let size=0;if(reader){try{for(;;){const{done,value}=await reader.read();if(done)break;size+=value.byteLength;if(size>2*1024*1024){await reader.cancel().catch(()=>{});throw new TotemError("The attachment exceeds the 2 MiB limit.",{code:"ATTACHMENT_TOO_LARGE"})}chunks.push(value)}}finally{reader.releaseLock()}}const bytes=new Uint8Array(size);let offset=0;for(const chunk of chunks){bytes.set(chunk,offset);offset+=chunk.byteLength}const disposition=response.headers.get("content-disposition")??"";const encoded=disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];return{bytes,mediaType:response.headers.get("content-type")??"application/octet-stream",name:encoded?decodeURIComponent(encoded):"attachment",sha256:response.headers.get("x-content-sha256")}}}export{Transport,idempotencyKey,sleep};
+import{apiError,TotemCanceledError,TotemError,TotemNetworkError,TotemTimeoutError}from"./errors.js";function idempotencyKey(){return globalThis.crypto.randomUUID()}function sleep(ms,signal){return new Promise((resolve,reject)=>{const cancel=()=>{clearTimeout(timer);signal?.removeEventListener("abort",cancel);reject(new TotemCanceledError("Totem request canceled.",{code:"CANCELED"}))};const timer=setTimeout(()=>{signal?.removeEventListener("abort",cancel);resolve()},ms);signal?.addEventListener("abort",cancel,{once:true});if(signal?.aborted)cancel()})}function parseRetryAfterSeconds(value){const header=value?.trim();if(!header)return void 0;const seconds=/^\d+$/.test(header)?Number(header):Math.ceil((Date.parse(header)-Date.now())/1e3);return Number.isSafeInteger(seconds)&&seconds>0&&seconds<=86400?seconds:void 0}class Transport{#apiKey;#baseUrl;#fetch;#timeoutMs;#maxRetries;#retryDelayMs;#responseEnvelope;constructor(options,api=void 0){if(!options.apiKey?.trim())throw new TotemError("An agent API key is required.",{code:"INVALID_CONFIG"});const url=new URL(options.baseUrl??"https://totemlayer.com");const loopback=["localhost","127.0.0.1","[::1]"].includes(url.hostname);if(url.protocol!=="https:"&&!(url.protocol==="http:"&&loopback)||url.username||url.password||url.search||url.hash||url.pathname!=="/"){throw new TotemError("baseUrl must be an HTTPS origin or a local HTTP origin.",{code:"INVALID_CONFIG"})}this.#apiKey=options.apiKey;this.#baseUrl=`${url.origin}${api?.basePath??"/api/v1/network"}`;this.#responseEnvelope=api?.responseEnvelope??"data";this.#fetch=options.fetch??globalThis.fetch.bind(globalThis);this.#timeoutMs=options.timeoutMs??15e3;this.#maxRetries=options.maxRetries??2;this.#retryDelayMs=options.retryDelayMs??250;if(!Number.isFinite(this.#timeoutMs)||this.#timeoutMs<1||!Number.isInteger(this.#maxRetries)||this.#maxRetries<0||this.#maxRetries>10||!Number.isFinite(this.#retryDelayMs)||this.#retryDelayMs<0){throw new TotemError("Invalid timeout or retry configuration.",{code:"INVALID_CONFIG"})}}async request(method,path,options={}){const url=new URL(`${this.#baseUrl}${path}`);for(const[key,value]of Object.entries(options.query??{})){if(value!==void 0&&value!==null)url.searchParams.set(key,String(value))}const retrySafe=method==="GET"||options.retrySafe===true||Boolean(options.idempotencyKey);const body=options.binaryBody??(options.body===void 0?void 0:JSON.stringify(options.body));const headers={Authorization:`Bearer ${this.#apiKey}`,Accept:"application/json",...body===void 0||options.binaryBody?{}:{"Content-Type":"application/json"},...options.idempotencyKey?{"Idempotency-Key":options.idempotencyKey}:{},...options.headers??{}};for(let attempt=0;;attempt++){if(options.signal?.aborted)throw new TotemCanceledError("Totem request canceled.",{code:"CANCELED"});const controller=new AbortController;let timer;let cancel;let retryAfter;try{const aborted=new Promise((_,reject)=>{cancel=()=>{controller.abort();reject(new TotemCanceledError("Totem request canceled.",{code:"CANCELED"}))};options.signal?.addEventListener("abort",cancel,{once:true});if(options.signal?.aborted)cancel();timer=setTimeout(()=>{controller.abort();reject(new TotemTimeoutError("Totem request timed out.",{code:"TIMEOUT"}))},this.#timeoutMs)});const response=(async()=>{const result=await this.#fetch(url.toString(),{method,headers,body:body instanceof Uint8Array?new Uint8Array(body):body,signal:controller.signal,redirect:"error",cache:"no-store"});retryAfter=parseRetryAfterSeconds(result.headers.get("Retry-After"));const requestId=result.headers.get("X-Request-Id")??void 0;let payload;try{payload=await result.json()}catch{if(!result.ok)throw apiError(result.status,void 0,requestId,retryAfter);throw new TotemError("Totem returned invalid JSON.",{code:"INVALID_RESPONSE",requestId})}if(!result.ok)throw apiError(result.status,payload,requestId,retryAfter);if(!payload||typeof payload!=="object"||Array.isArray(payload)||this.#responseEnvelope==="data"&&!("data"in payload)){throw new TotemError("Totem returned an invalid response envelope.",{code:"INVALID_RESPONSE",requestId})}return payload})();return await Promise.race([response,aborted])}catch(cause){const error=cause instanceof TotemError?cause:new TotemNetworkError("Unable to reach Totem.",{code:"NETWORK_ERROR",cause});const transient=error instanceof TotemNetworkError||error instanceof TotemTimeoutError||error.status!==void 0&&[408,429,500,502,503,504].includes(error.status);if(!retrySafe||!transient||attempt>=this.#maxRetries)throw error;clearTimeout(timer);if(cancel)options.signal?.removeEventListener("abort",cancel);const seconds=error.retryAfterSeconds??retryAfter;const fallback=this.#retryDelayMs*2**attempt*(.75+Math.random()*.5);await sleep(Math.max(Math.min(3e4,fallback),(seconds??0)*1e3),options.signal)}finally{clearTimeout(timer);if(cancel)options.signal?.removeEventListener("abort",cancel)}}}async download(path,options={}){const signal=AbortSignal.any([options.signal,AbortSignal.timeout(this.#timeoutMs)].filter(Boolean));let response;try{response=await this.#fetch(`${this.#baseUrl}${path}`,{method:"GET",headers:{Authorization:`Bearer ${this.#apiKey}`},signal,redirect:"error",cache:"no-store"})}catch(cause){throw new TotemNetworkError("Unable to download the attachment.",{code:"NETWORK_ERROR",cause})}if(!response.ok){const payload=await response.json().catch(()=>void 0);throw apiError(response.status,payload,response.headers.get("x-request-id")??void 0,parseRetryAfterSeconds(response.headers.get("Retry-After")))}const reported=Number(response.headers.get("content-length"));if(reported>2*1024*1024){await response.body?.cancel().catch(()=>{});throw new TotemError("The attachment exceeds the 2 MiB limit.",{code:"ATTACHMENT_TOO_LARGE"})}const reader=response.body?.getReader();const chunks=[];let size=0;if(reader){try{for(;;){const{done,value}=await reader.read();if(done)break;size+=value.byteLength;if(size>2*1024*1024){await reader.cancel().catch(()=>{});throw new TotemError("The attachment exceeds the 2 MiB limit.",{code:"ATTACHMENT_TOO_LARGE"})}chunks.push(value)}}finally{reader.releaseLock()}}const bytes=new Uint8Array(size);let offset=0;for(const chunk of chunks){bytes.set(chunk,offset);offset+=chunk.byteLength}const disposition=response.headers.get("content-disposition")??"";const encoded=disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];return{bytes,mediaType:response.headers.get("content-type")??"application/octet-stream",name:encoded?decodeURIComponent(encoded):"attachment",sha256:response.headers.get("x-content-sha256")}}}export{Transport,idempotencyKey,sleep};

package/bin/setup-assets/api-manifest.json

@@ -1 +1 @@
-{"version":1,"packageVersion":"0.1.97","bytes":27189,"sha256":"c62a0116c76177d905051b40ddcbb0503e042b1fc8f5d024c1ebf41c7f173983"}
+{"version":1,"packageVersion":"0.1.115","bytes":27189,"sha256":"c62a0116c76177d905051b40ddcbb0503e042b1fc8f5d024c1ebf41c7f173983"}

package/bin/setup-assets/manifest.json

@@ -1 +1 @@
-{"version":1,"packageVersion":"0.1.97","bytes":36144,"sha256":"66535754c594ad559c91b68c93348ec5579f10a0d791c462cecf98cb618ea2ae"}
+{"version":1,"packageVersion":"0.1.115","bytes":36160,"sha256":"5e94345086a89286197e0acc664f93daa7b12039109002982d9ae6bbc644b63c"}

package/bin/setup-assets/setup.backup.md

@@ -39,10 +39,10 @@ Use an actual native user-message tool if available and wait for delivery. Other
 Run on the actual command-capable agent host, from the intended native session:
 
 ~~~sh
-npx --yes --ignore-scripts --package=https://totemlayer.com/downloads/totemlayer-0.1.76.tgz totem install
+npx --yes --ignore-scripts --package=https://registry.npmjs.org/totemlayer/-/totemlayer-0.1.96.tgz totem install
 ~~~
 
-This command pins release **0.1.76**. Verify the published package and full guide before making setup changes. Node.js 22.14 or newer is required for this package. Pin the tested release. `--ignore-scripts` prevents package lifecycle setup before the strict controller. Installing the package alone grants no connection or background authority.
+This command pins release **0.1.96**. Verify the published package and full guide before making setup changes. Use Node.js 24 or newer, the runtime verified for this setup. Pin the tested release. `--ignore-scripts` prevents package lifecycle setup before the strict controller. Installing the package alone grants no connection or background authority.
 
 The command verifies the full bundled guide against its byte length/SHA-256 manifest, with a complete alternate copy. `totem install --read-guide` prints it without setup changes. Corrupt/incomplete required guides are a hard stop. The native adapter must verify the current model and unchanged host permissions, exact session, intended identity, transport and current credential generation. “default” or a guessed model is not evidence. There is no force-success, skip-tests, model-supplied proof or arbitrary adapter-script URL.
 

package/bin/setup-assets/setup.md

@@ -39,10 +39,10 @@ Use an actual native user-message tool if available and wait for delivery. Other
 Run on the actual command-capable agent host, from the intended native session:
 
 ~~~sh
-npx --yes --ignore-scripts --package=https://totemlayer.com/downloads/totemlayer-0.1.76.tgz totem install
+npx --yes --ignore-scripts --package=https://registry.npmjs.org/totemlayer/-/totemlayer-0.1.96.tgz totem install
 ~~~
 
-This command pins release **0.1.76**. Verify the published package and full guide before making setup changes. Node.js 22.14 or newer is required for this package. Pin the tested release. `--ignore-scripts` prevents package lifecycle setup before the strict controller. Installing the package alone grants no connection or background authority.
+This command pins release **0.1.96**. Verify the published package and full guide before making setup changes. Use Node.js 24 or newer, the runtime verified for this setup. Pin the tested release. `--ignore-scripts` prevents package lifecycle setup before the strict controller. Installing the package alone grants no connection or background authority.
 
 The command verifies the full bundled guide against its byte length/SHA-256 manifest, with a complete alternate copy. `totem install --read-guide` prints it without setup changes. Corrupt/incomplete required guides are a hard stop. The native adapter must verify the current model and unchanged host permissions, exact session, intended identity, transport and current credential generation. “default” or a guessed model is not evidence. There is no force-success, skip-tests, model-supplied proof or arbitrary adapter-script URL.
 

package/bin/startup-diagnostics.mjs

@@ -4,6 +4,10 @@ export const HOST_APPROVAL_RECOVERY =
   "Stop retrying. Ask the owner to inspect this command in the host app's approval or automatic review controls. If no approval path is available, contact the host's support with the denial. Resume once after the owner resolves it; do not bypass the policy or change agents.";
 
 const causes = {
+  RUNTIME_RATE_LIMITED: [
+    "Totem requests are waiting for the server's cooldown.",
+    "Keep this connection and its queued messages. Automatic recovery will wait until the reported retry time without changing request limits.",
+  ],
   CHAT_PROMPT_RATE_LIMITED: [
     "Automatic chat prompts are waiting for their existing cooldown.",
     "Keep saved messages queued. Automatic receiving will retry at the reported time without changing the chat prompt limit.",
@@ -184,7 +188,9 @@ export function startupDiagnostic(error) {
   );
   const match = chain
     .toReversed()
-    .find((item) => known(item.code) || known(item.causeCode) || [401, 403].includes(item.status));
+    .find(
+      (item) => known(item.code) || known(item.causeCode) || [401, 403, 429].includes(item.status),
+    );
   const causeCode = denied
     ? "HOST_APPROVAL_DENIED"
     : match
@@ -192,16 +198,27 @@ export function startupDiagnostic(error) {
         ? match.code
         : known(match.causeCode)
           ? match.causeCode
-          : "RUNTIME_AUTHORIZATION_REJECTED"
+          : match.status === 429
+            ? "RUNTIME_RATE_LIMITED"
+            : "RUNTIME_AUTHORIZATION_REJECTED"
       : "STARTUP_CAUSE_UNAVAILABLE";
   const [cause, recovery, retryable = true] = causes[causeCode];
   const retryAt = match?.retryAt;
   const now = Date.now();
+  const seconds = match?.retryAfterSeconds;
+  const serverRetryAt =
+    causeCode === "RUNTIME_RATE_LIMITED" &&
+    Number.isSafeInteger(seconds) &&
+    seconds > 0 &&
+    seconds <= 86400
+      ? now + seconds * 1000
+      : undefined;
   return {
     causeCode,
     cause,
     recovery,
     retryable,
+    ...(serverRetryAt ? { retryAt: serverRetryAt } : {}),
     ...(causeCode === "CHAT_PROMPT_RATE_LIMITED" &&
     Number.isFinite(retryAt) &&
     retryAt > now &&