@wenathlan/saddle 1.8.7 → 1.8.9

package/extension/popup.js

@@ -1,25 +0,0 @@
-/**
- * popup sends user initiated read commands through the service worker.
- */
-
-import { createcommand } from "./protocol.js";
-
-const status = document.querySelector("#status");
-const output = document.querySelector("#output");
-
-for (const button of document.querySelectorAll("[data-command]")) button.addEventListener("click", () => request(button.dataset.command));
-
-async function request(command) {
-  try {
-    status.textContent = "Reading active tab…";
-    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
-    if (!tab?.id) throw new Error("no active tab");
-    const response = await chrome.runtime.sendMessage(createcommand(command, { tabid: tab.id }));
-    if (response?.type === "error") throw new Error(response.error?.message ?? "extension request failed");
-    output.textContent = JSON.stringify(response?.payload ?? response, null, 2);
-    status.textContent = "Complete.";
-  } catch (error) {
-    status.textContent = "Request failed.";
-    output.textContent = String(error.message ?? error);
-  }
-}

package/extension/protocol.js

@@ -1,95 +0,0 @@
-/**
- * extension protocol defines serializable commands, responses, errors and page snapshots.
- */
-
-export const protocolversion = 1;
-export const extensioncommands = Object.freeze(["snapshot", "readpage", "pagefacts", "clickref", "fillref"]);
-
-/** Creates a compact identifier without embedding a host, port or credential. */
-export function createid(prefix = "msg", source) {
-  const generator = source ?? (() => globalThis.crypto?.randomUUID?.() ?? `${Date.now()}${Math.random().toString(16).slice(2)}`);
-  const value = generator().replaceAll("-", "");
-  return `${prefix}${value}`;
-}
-
-/** Creates a versioned command for the extension message bus. */
-export function createcommand(command, payload = {}, options = {}) {
-  if (!extensioncommands.includes(command)) throw new TypeError(`unsupported extension command: ${command}`);
-  return createmessage("command", { ...options, command, payload });
-}
-
-/** Creates a serializable message envelope. */
-export function createmessage(type, options = {}) {
-  if (!["command", "response", "error", "event"].includes(type)) throw new TypeError(`unsupported extension message type: ${type}`);
-  const message = { version: protocolversion, type, id: options.id ?? createid(type) };
-  if (options.requestid) message.requestid = options.requestid;
-  if (options.command) message.command = options.command;
-  if (options.payload !== undefined) message.payload = options.payload;
-  if (options.error) message.error = options.error;
-  assertserializable(message);
-  return message;
-}
-
-/** Creates a correlated successful response. */
-export function createresponse(request, payload = {}) {
-  assertmessage(request);
-  return createmessage("response", { requestid: request.id, payload });
-}
-
-/** Creates a correlated error response with stable error fields. */
-export function createerror(request, error, options = {}) {
-  const requestid = request?.id ?? options.requestid;
-  const failure = { code: options.code ?? error?.code ?? "extension_error", message: String(error?.message ?? error ?? "extension request failed"), retryable: Boolean(options.retryable ?? error?.retryable) };
-  return createmessage("error", { requestid, error: failure });
-}
-
-/** Validates a message before a privileged context handles it. */
-export function assertmessage(message) {
-  if (!message || typeof message !== "object") throw new TypeError("extension message must be an object");
-  if (message.version !== protocolversion) throw new TypeError(`unsupported extension protocol version: ${message.version}`);
-  if (typeof message.type !== "string" || typeof message.id !== "string") throw new TypeError("extension message requires type and id");
-  if (message.type === "command" && !extensioncommands.includes(message.command)) throw new TypeError(`unsupported extension command: ${message.command}`);
-  if (message.payload !== undefined && (!message.payload || typeof message.payload !== "object" || Array.isArray(message.payload))) throw new TypeError("extension payload must be an object");
-  return message;
-}
-
-/** Creates a structured page snapshot with stable element references. */
-export function createsnapshot(input = {}) {
-  const snapshot = {
-    version: protocolversion,
-    snapshotid: String(input.snapshotid ?? createid("snap")),
-    createdat: Number(input.createdat ?? Date.now()),
-    windowid: input.windowid === undefined ? undefined : String(input.windowid),
-    tabid: input.tabid === undefined ? undefined : String(input.tabid),
-    frameid: input.frameid === undefined ? undefined : String(input.frameid),
-    url: String(input.url ?? ""),
-    title: String(input.title ?? ""),
-    text: String(input.text ?? ""),
-    elements: Array.isArray(input.elements) ? input.elements.map((element) => ({ ref: String(element.ref), role: String(element.role ?? "generic"), name: String(element.name ?? ""), value: element.value === undefined ? undefined : String(element.value), disabled: Boolean(element.disabled) })) : []
-  };
-  assertserializable(snapshot);
-  return snapshot;
-}
-
-/** Returns whether a reference still belongs to the current page snapshot. */
-export function isfreshsnapshot(snapshotid, currentid) { return Boolean(snapshotid && currentid && snapshotid === currentid); }
-
-/** Computes bounded additions, removals and changed elements between extension snapshots. */
-export function snapshotdiff(previous, current) {
-  const before = createsnapshot(previous);
-  const after = createsnapshot(current);
-  const oldmap = new Map(before.elements.map((element) => [element.ref, element]));
-  const newmap = new Map(after.elements.map((element) => [element.ref, element]));
-  return {
-    from: before.snapshotid,
-    to: after.snapshotid,
-    contextchanged: before.windowid !== after.windowid || before.tabid !== after.tabid || before.frameid !== after.frameid,
-    added: after.elements.filter((element) => !oldmap.has(element.ref)),
-    removed: before.elements.filter((element) => !newmap.has(element.ref)),
-    changed: after.elements.filter((element) => oldmap.has(element.ref) && JSON.stringify(oldmap.get(element.ref)) !== JSON.stringify(element))
-  };
-}
-
-function assertserializable(value) {
-  try { JSON.stringify(value); } catch (error) { throw new TypeError(`extension message is not serializable: ${error.message}`); }
-}

package/extension/serviceworker.js

@@ -1,109 +0,0 @@
-/**
- * service worker router forwards user initiated commands to the active tab and persists resumable state.
- */
-
-import { assertmessage } from "./protocol.js";
-
-/** Creates a browser independent router around Chrome tabs, scripting and storage APIs. */
-export function createworkerrouter(options = {}) {
-  const tabs = options.tabs;
-  const scripting = options.scripting;
-  const storage = options.storage;
-  const contentfile = options.contentfile ?? "content.js";
-  const statekey = options.statekey ?? "saddleextensionstate";
-  const maxpending = options.maxpending ?? 32;
-  if (typeof tabs?.sendMessage !== "function") throw new TypeError("extension router requires tabs.sendMessage");
-  if (!Number.isSafeInteger(maxpending) || maxpending < 1) throw new TypeError("extension router maxpending must be a positive safe integer");
-
-  async function ensurecontent(tabid) {
-    if (!Number.isInteger(tabid)) throw new TypeError("extension command requires a tab id");
-    if (typeof scripting?.executeScript !== "function") throw new TypeError("extension router requires scripting.executeScript");
-    await scripting.executeScript({ target: { tabId: tabid }, files: [contentfile] });
-  }
-
-  async function readstate() {
-    if (typeof storage?.get !== "function") return {};
-    const result = await storage.get(statekey);
-    return result?.[statekey] ?? {};
-  }
-
-  async function savestate(value) {
-    if (typeof storage?.set === "function") await storage.set({ [statekey]: value });
-  }
-
-  async function pendingstate() {
-    const value = await readstate();
-    return { ...value, pending: Array.isArray(value.pending) ? value.pending.filter(validpending) : [] };
-  }
-
-  async function enqueue(request, sender) {
-    const state = await pendingstate();
-    const record = pendingrecord(request, sender);
-    const pending = state.pending.filter((item) => item.requestid !== record.requestid);
-    if (pending.length >= maxpending && !state.pending.some((item) => item.requestid === record.requestid)) throw extensionerror("PENDING_LIMIT", "extension pending command limit reached");
-    pending.push(record);
-    await savestate({ ...state, pending });
-    return record;
-  }
-
-  async function complete(requestid, patch = {}) {
-    const state = await pendingstate();
-    await savestate({ ...state, ...patch, pending: state.pending.filter((item) => item.requestid !== requestid) });
-  }
-
-  async function markfailure(requestid, error) {
-    const state = await pendingstate();
-    const pending = state.pending.map((item) => item.requestid === requestid ? { ...item, attempts: item.attempts + 1, lasterror: { code: String(error?.code ?? "extension_error"), message: String(error?.message ?? error) }, updatedat: Date.now() } : item);
-    await savestate({ ...state, pending });
-  }
-
-  async function dispatch(request, sender = {}) {
-    const tabid = request.payload?.tabid ?? sender.tab?.id;
-    await ensurecontent(tabid);
-    const response = await tabs.sendMessage(tabid, request);
-    return decorate(response, sender, tabid);
-  }
-
-  async function handle(message, sender = {}) {
-    const request = assertmessage(message);
-    if (request.type !== "command") throw new TypeError("extension router accepts commands only");
-    const tabid = request.payload?.tabid ?? sender.tab?.id;
-    await enqueue(request, { ...sender, tab: { ...sender.tab, id: tabid } });
-    try {
-      const response = await dispatch(request, { ...sender, tab: { ...sender.tab, id: tabid } });
-    await complete(request.id, response?.type === "response" && response.payload?.snapshotid ? { tabid, snapshotid: response.payload.snapshotid, frameid: response.payload.frameid, windowid: response.payload.windowid, updatedat: Date.now() } : { updatedat: Date.now() });
-      return response;
-    } catch (error) {
-      await markfailure(request.id, error);
-      throw error;
-    }
-  }
-
-  async function rehydrate() { return pendingstate(); }
-
-  async function resume(requestid, sender = {}) {
-    const state = await pendingstate();
-    const pending = state.pending.find((item) => item.requestid === requestid);
-    if (!pending) throw extensionerror("PENDING_NOT_FOUND", `pending command not found: ${requestid}`);
-    const tabid = pending.tabid ?? sender.tab?.id;
-    const response = await dispatch(pending.message, { ...sender, frameId: pending.frameid ?? sender.frameId, tab: { ...sender.tab, id: tabid, windowId: pending.windowid ?? sender.tab?.windowId } });
-    await complete(requestid, response?.type === "response" && response.payload?.snapshotid ? { tabid, snapshotid: response.payload.snapshotid, frameid: response.payload.frameid, windowid: response.payload.windowid, updatedat: Date.now() } : { updatedat: Date.now() });
-    return response;
-  }
-
-  async function cancel(requestid) { const state = await pendingstate(); await savestate({ ...state, pending: state.pending.filter((item) => item.requestid !== requestid) }); }
-
-  return { ensurecontent, readstate, savestate, rehydrate, enqueue, resume, cancel, handle };
-}
-
-function pendingrecord(request, sender = {}) { return { requestid: request.id, command: request.command, message: request, tabid: request.payload?.tabid ?? sender.tab?.id, frameid: request.payload?.frameid ?? sender.frameId, windowid: request.payload?.windowid ?? sender.tab?.windowId, attempts: 0, createdat: Date.now(), updatedat: Date.now() }; }
-
-function decorate(response, sender, tabid) {
-  if (response?.type !== "response" || !response.payload || typeof response.payload !== "object" || !response.payload.snapshotid) return response;
-  const payload = { ...response.payload, tabid: response.payload.tabid ?? (tabid === undefined ? undefined : String(tabid)), frameid: response.payload.frameid ?? (sender.frameId === undefined ? undefined : String(sender.frameId)), windowid: response.payload.windowid ?? (sender.tab?.windowId === undefined ? undefined : String(sender.tab.windowId)) };
-  return { ...response, payload };
-}
-
-function validpending(value) { return Boolean(value && typeof value === "object" && typeof value.requestid === "string" && value.message && value.message.type === "command" && Number.isSafeInteger(value.attempts) && value.attempts >= 0); }
-
-function extensionerror(code, message) { const error = new Error(message); error.code = code; return error; }

package/extension/worker.js

@@ -1,22 +0,0 @@
-/**
- * worker binds the generic extension router to the Manifest V3 runtime APIs.
- */
-
-import { createerror } from "./protocol.js";
-import { createworkerrouter } from "./serviceworker.js";
-
-/** Installs the service worker listeners against a caller supplied Chrome API object. */
-export function startworker(chromeapi = globalThis.chrome) {
-  if (!chromeapi?.runtime?.onMessage || !chromeapi?.tabs || !chromeapi?.scripting) throw new TypeError("extension worker requires runtime tabs and scripting APIs");
-  const router = createworkerrouter({ tabs: chromeapi.tabs, scripting: chromeapi.scripting, storage: chromeapi.storage?.session });
-  const listener = (message, sender, sendresponse) => {
-    router.handle(message, sender).then(sendresponse).catch((error) => sendresponse(createerror(message, error)));
-    return true;
-  };
-  const startup = () => router.rehydrate().catch(() => undefined);
-  chromeapi.runtime.onMessage.addListener(listener);
-  chromeapi.runtime.onStartup?.addListener(startup);
-  return { router, dispose() { chromeapi.runtime.onMessage.removeListener?.(listener); chromeapi.runtime.onStartup?.removeListener?.(startup); } };
-}
-
-if (globalThis.chrome?.runtime?.onMessage) startworker();

package/format/check.js

@@ -1,21 +0,0 @@
-/**
- * format check validates the public root based JavaScript layout before release.
- */
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-
-const roots = ["core", "domain", "memory", "runners", "runtime", "storage", "sessions", "modes", "adapters", "persistence", "queue", "dispatch", "scrape", "crawl", "api", "mcp", "browser", "proxy", "captcha", "ai", "webhook", "surfaces", "library", "errors", "retry", "server", "binary", "deploy", "workflow", "packager", "bot", "protocol", "cli"];
-
-/** Finds JavaScript files that do not follow the skill formatting contract. */
-export async function formatissues(root = process.cwd()) {
-  const issues = [];
-  for (const directory of roots) for (const file of await javascriptfiles(join(root, directory))) { const relative = file.slice(root.length + 1); const source = await readFile(file, "utf8"); if (/[A-Z_-]/.test(relative)) issues.push(`${relative}: invalid path format`); if (!source.includes("/**")) issues.push(`${relative}: missing jsdoc`); }
-  return issues;
-}
-
-/** Runs the check as a CLI and throws a short diagnostic on failure. */
-export async function runformatcheck() { const issues = await formatissues(); if (issues.length) throw new Error(issues.join("\n")); return { ok: true, checked: roots.length }; }
-
-async function javascriptfiles(directory) { let entries; try { entries = await readdir(directory, { withFileTypes: true }); } catch { return []; } const files = []; for (const entry of entries) { const file = join(directory, entry.name); if (entry.isDirectory()) files.push(...await javascriptfiles(file)); else if (entry.name.endsWith(".js")) files.push(file); } return files; }
-
-if (import.meta.url === `file://${process.argv[1]}`) runformatcheck().then((result) => console.log(JSON.stringify(result))).catch((error) => { console.error(error.message); process.exitCode = 1; });

package/library/public.js

@@ -1,85 +0,0 @@
-/**
- * public library helpers compose fetch extraction serialization chunking and crawl contracts.
- */
-import { crawl } from "../crawl/crawler.js";
-import { chunkmarkdown } from "../ai/chunk.js";
-import { estimatetokens } from "../ai/tokens.js";
-import { extracthtml } from "../scrape/extract.js";
-import { normalizeresponse } from "../scrape/normalize.js";
-import { browseragent } from "../browser/agent.js";
-
-/** Selects the fetch or browser execution path. */
-export async function saddleurl(url, options = {}) {
-  const mode = options.mode ?? "fetch";
-  if (mode === "browser") return scrapewithbrowser(url, options);
-  return scrapeurl(url, options);
-}
-
-/** Fetches one URL through the caller supplied transport. */
-export async function scrapeurl(url, options = {}) {
-  const target = safeurl(url);
-  const response = await (options.fetcher ?? fetch)(target, { signal: options.signal, headers: options.headers });
-  if (!response.ok) throw new Error(`scrape request failed with ${response.status}`);
-  const normalized = await normalizeresponse(response, { url: target, defaultcontenttype: "text/html", maxbytes: options.maxbytes });
-  const result = normalized.kind === "html" ? scrapehtml(normalized.content, target, options) : { content: normalized.content, data: normalized.data, metadata: { url: target, contenttype: normalized.contenttype, size: normalized.size }, bytes: normalized.bytes };
-  return formatresult(result, options);
-}
-
-/** Extracts a serializable result from HTML without network access. */
-export function scrapehtml(html, url, options = {}) {
-  const result = extracthtml(html, url);
-  return { content: result.text, metadata: { url: result.url, title: result.title, description: result.description, links: result.links }, html: options.includehtml ? html : undefined };
-}
-
-/** Exposes structured extraction for callers that do not need formatting. */
-export function extractcontent(html, options = {}) { return extracthtml(html, options.url); }
-
-/** Runs a scrape through the injected browser agent contract. */
-export async function scrapewithbrowser(url, options = {}) {
-  const agent = browseragent(options.browser);
-  await agent.navigate({ url, waituntil: options.waituntil ?? "networkidle" });
-  return formatresult({ content: await agent.text(), metadata: { url, title: await agent.title(), html: options.includehtml ? await agent.html() : undefined } }, options);
-}
-
-/** Serializes a result into a supported output format. */
-export function serializeresult(result, options = {}) {
-  const format = options.format ?? "json";
-  if (format === "json") return JSON.stringify(result, null, options.pretty ? 2 : 0);
-  if (format === "text") return result.content ?? "";
-  if (format === "markdown") return `# ${result.metadata?.title ?? "result"}\n\n${result.content ?? ""}`;
-  if (format === "xml") return `<result><title>${escape(result.metadata?.title ?? "")}</title><content>${escape(result.content ?? "")}</content></result>`;
-  if (format === "redis") return JSON.stringify({ content: result.content, metadata: result.metadata });
-  throw new TypeError(`unsupported format: ${format}`);
-}
-
-/** Converts local HTML into Markdown. */
-export function serializehtml(html, options = {}) { return serializeresult(scrapehtml(html, options.url), { format: "markdown" }); }
-
-/** Builds compact context for an agent or a vector pipeline. */
-export function formatforagent(result, options = {}) {
-  const content = result.content ?? "";
-  const chunks = chunkmarkdown(content, { maxtokens: options.maxchunksize ?? 4000 });
-  const lines = content.split(/[.!?]\s+/).filter(Boolean);
-  return { summary: lines.slice(0, 2).join(". "), keypoints: lines.slice(0, options.keypoints ?? 5), relevanturls: result.metadata?.links ?? [], chunks, tokencount: estimatetokens(content, options.model) };
-}
-
-/** Processes URLs in bounded groups and emits progress events. */
-export async function batchscrape(options = {}) {
-  const urls = options.urls ?? [];
-  const concurrency = options.concurrency ?? 10;
-  const results = [];
-  for (let index = 0; index < urls.length; index += concurrency) {
-    const group = urls.slice(index, index + concurrency);
-    const completed = await Promise.all(group.map((url) => scrapeurl(url, options)));
-    results.push(...completed);
-    options.onprogress?.({ completed: results.length, total: urls.length });
-  }
-  return results;
-}
-
-/** Runs the crawler through the public scrape contract. */
-export async function crawlurl(url, options = {}) { return crawl(url, { ...options, scrape: (target) => scrapeurl(target, options) }); }
-
-function safeurl(value) { const url = new URL(value); if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("url must use http or https"); return url.href; }
-function formatresult(result, options) { return options.format ? { ...result, serialized: serializeresult(result, options) } : result; }
-function escape(value) { return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;"); }

package/mcp/browser.js

@@ -1,12 +0,0 @@
-/**
- * browser MCP tools expose snapshots and actions only through an injected browser adapter.
- */
-
-/** Creates optional browser tools for an MCP server without selecting Playwright or another vendor. */
-export function browsertools(browser) {
-  if (typeof browser?.snapshot !== "function" || typeof browser?.action !== "function") throw new TypeError("browser MCP tools require snapshot and action");
-  return {
-    browser_snapshot: async (input = {}) => browser.snapshot(input),
-    browser_action: async (input = {}) => browser.action(input)
-  };
-}

package/mcp/server.js

@@ -1,28 +0,0 @@
-/**
- * mcp server implements a small JSON RPC tool surface and remains transport agnostic.
- */
-import { crawl } from "../crawl/crawler.js";
-import { extractwithschema } from "../scrape/schema.js";
-import { jsonencode } from "../protocol/json.js";
-import { browsertools } from "./browser.js";
-
-export function mcpserver(options = {}) {
-  if (typeof options.scrape !== "function") throw new TypeError("mcp server requires scrape");
-  const tools = {
-    scrape: async (input) => options.scrape(input.url, input),
-    crawl: async (input) => crawl(input.url, { ...input, scrape: (url) => options.scrape(url, input) }),
-    batch: async (input) => ({ results: await Promise.all((input.urls ?? []).map((url) => options.scrape(url, input))) }),
-    extract: async (input) => extractwithschema(input.html, input.schema, input.url),
-    serialize: async (input) => jsonencode(input.value),
-    ...(options.browser ? browsertools(options.browser) : {}),
-    ...(options.tools ?? {})
-  };
-  return {
-    listtools() { return Object.keys(tools).map((name) => ({ name, description: `saddle ${name} tool` })); },
-    async handle(request) {
-      if (request.method === "tools/list") return { jsonrpc: "2.0", id: request.id, result: { tools: this.listtools() } };
-      if (request.method === "tools/call") { const handler = tools[request.params?.name]; if (!handler) return { jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "tool not found" } }; try { return { jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: JSON.stringify(await handler(request.params.arguments ?? {})) }] } }; } catch (error) { return { jsonrpc: "2.0", id: request.id, error: { code: -32000, message: error.message } }; } }
-      return { jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "method not found" } };
-    }
-  };
-}

package/mcp/transport.js

@@ -1,14 +0,0 @@
-/**
- * mcp transport keeps JSON RPC framing separate from the tool server.
- */
-import { jsondecode, jsonencode } from "../protocol/json.js";
-
-/** Creates JSONL and HTTP handlers for the transport agnostic MCP server. */
-export function mcptransport(server) {
-  if (typeof server?.handle !== "function") throw new TypeError("mcp transport requires server");
-  return {
-    async handleline(line) { const request = jsondecode(line); return jsonencode(await server.handle(request)); },
-    async *stream(lines) { for await (const line of lines) if (String(line).trim()) yield await this.handleline(line); },
-    async handlehttp(request) { const body = await request.text(); const response = await server.handle(jsondecode(body)); return new Response(jsonencode(response), { status: 200, headers: { "content-type": "application/json" } }); }
-  };
-}

package/memory/bridge.js

@@ -1,16 +0,0 @@
-/**
- * memory bridges materialize and clear temporary working sets.
- */
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { syncresult, workingset } from "../domain/runtime.js";
-
-export function localmemory(options = {}) {
-  const base = options.base ?? tmpdir();
-  return {
-    async prepare(job) { const location = await mkdtemp(join(base, "saddlejob")); return workingset(job.id, location, join(location, "resultbin")); },
-    async sync(set, bytes) { await mkdir(set.location, { recursive: true }); await writeFile(set.resultpath, bytes); return syncresult(bytes.byteLength, set.resultpath); },
-    async cleanup(set) { await rm(set.location, { recursive: true, force: true }); }
-  };
-}

package/memory/engine.js

@@ -1,45 +0,0 @@
-/**
- * memory engine loads from the first backend and persists to every backend.
- */
-import { memoryobject, tobytes } from "./objects.js";
-import { transformtocompute, transformtostorage } from "./transforms.js";
-import { storagecapabilities, syncbackends } from "../storage/sync.js";
-
-export function memoryengine(options = {}) {
-  const backends = options.backends ?? [];
-  const values = new Map();
-  async function load(key) {
-    if (!key) throw new TypeError("memory key is required");
-    if (values.has(key)) return values.get(key);
-    let last;
-    for (const backend of backends) {
-      try {
-        const value = await backend.get(key);
-        if (value == null) continue;
-        const object = memoryobject({ id: key, buffer: value.data ?? value, type: value.contenttype ?? value.type, metadata: value.metadata });
-        values.set(key, object);
-        return object;
-      } catch (error) { last = error; }
-    }
-    if (last) throw new Error(`memory engine load failed for key "${key}": ${last.message}`, { cause: last });
-    throw new Error(`memory engine load failed for key "${key}": not found`);
-  }
-  async function persist(key, data, options = {}) {
-    const payload = tobytes(data?.payload ?? data?.buffer ?? data);
-    const object = memoryobject({ id: key, buffer: payload, type: options.mimetype ?? data?.mimetype, metadata: options.metadata ?? data?.metadata });
-    for (const backend of backends) await backend.put(key, { data: object.buffer, contenttype: object.type, metadata: object.metadata });
-    values.set(key, object);
-    return object;
-  }
-  function release(key) { values.delete(key); }
-  async function safeload(key) { try { return { success: true, data: await load(key) }; } catch (error) { return { success: false, error }; } }
-  async function sync(key, options = {}) {
-    const sourceindex = Number(options.sourceindex ?? 0);
-    const source = backends[sourceindex];
-    if (!source) throw new TypeError("memory sync source backend is missing");
-    const targets = backends.filter((_backend, index) => index !== sourceindex);
-    return syncbackends(source, targets, key, options);
-  }
-  function capabilities() { return backends.map((backend, index) => ({ index, capabilities: storagecapabilities(backend) })); }
-  return { load, persist, release, safeload, sync, capabilities, transformtocompute, transformtostorage, list() { return [...values.keys()]; } };
-}

package/memory/modes.js

@@ -1,55 +0,0 @@
-/**
- * memory modes expose the same byte contract with different backing choices.
- */
-export function internalmemory(initial = {}) {
-  const values = new Map(Object.entries(initial).map(([key, value]) => [key, tobytes(value)]));
-  return {
-    mode: "internal",
-    async put(key, value) { values.set(key, tobytes(value)); return { key, bytes: values.get(key).byteLength }; },
-    async get(key) { return values.get(key) ?? null; },
-    async delete(key) { values.delete(key); },
-    async list() { return [...values.keys()]; }
-  };
-}
-
-export function externalmemory(storage) {
-  if (!storage?.put || !storage?.get) throw new TypeError("external memory requires storage adapter");
-  return {
-    mode: "external",
-    async put(key, value) { return storage.put({ key, data: tobytes(value) }); },
-    async get(key) { try { return await storage.get(key); } catch (error) { if (error.code === "ARTIFACT_NOT_FOUND") return null; throw error; } },
-    async delete(key) { return storage.delete(key); },
-    async list(prefix) { return storage.list(prefix); }
-  };
-}
-
-export function physicalmemory(options = {}) {
-  if (!options.path) throw new TypeError("physical memory requires a path");
-  return { mode: "physical", path: options.path, put: options.put, get: options.get, delete: options.delete, list: options.list };
-}
-
-export function vectorizedmemory() {
-  const vectors = new Map();
-  return {
-    mode: "vectorized",
-    async put(key, vector) { assertvector(vector); vectors.set(key, [...vector]); return { key, dimensions: vector.length }; },
-    async get(key) { return vectors.get(key) ?? null; },
-    async average(keys) { const selected = keys.map((key) => vectors.get(key)).filter(Boolean); if (!selected.length) return null; const size = selected[0].length; const result = Array.from({ length: size }, () => 0); for (const vector of selected) for (let index = 0; index < size; index += 1) result[index] += vector[index] / selected.length; return result; },
-    async list() { return [...vectors.keys()]; }
-  };
-}
-
-export function librarymemory(factory) {
-  if (typeof factory !== "function") throw new TypeError("library memory requires a factory");
-  return { mode: "library", async load(options) { return factory(options); } };
-}
-
-function tobytes(value) {
-  if (value instanceof Uint8Array) return value;
-  if (typeof value === "string") return new TextEncoder().encode(value);
-  return new TextEncoder().encode(JSON.stringify(value));
-}
-
-function assertvector(vector) {
-  if (!Array.isArray(vector) || vector.length === 0 || vector.some((value) => !Number.isFinite(value))) throw new TypeError("vector must be a non empty numeric array");
-}

package/memory/objects.js

@@ -1,18 +0,0 @@
-/**
- * memory objects and compute results are serializable contracts between storage and runtime.
- */
-export function memoryobject(options = {}) {
-  const buffer = tobytes(options.buffer ?? options.data ?? new Uint8Array(0));
-  return { id: options.id ?? `memory${Date.now().toString(36)}`, buffer, size: buffer.byteLength, type: options.type ?? "application/octet-stream", createdat: options.createdat ?? Date.now(), metadata: { ...(options.metadata ?? {}) } };
-}
-
-export function computeresult(options = {}) {
-  return { id: options.id ?? `result${Date.now().toString(36)}`, payload: options.payload, mimetype: options.mimetype, metadata: { ...(options.metadata ?? {}) }, processingtimems: options.processingtimems ?? 0, memoryusedbytes: options.memoryusedbytes ?? 0 };
-}
-
-export function tobytes(value) {
-  if (value instanceof Uint8Array) return value;
-  if (value instanceof ArrayBuffer) return new Uint8Array(value);
-  if (typeof value === "string") return new TextEncoder().encode(value);
-  return new TextEncoder().encode(JSON.stringify(value));
-}

package/memory/targets.js

@@ -1,21 +0,0 @@
-/**
- * storage targets describe provider intent without importing a provider client.
- */
-const types = new Set(["github", "gitlab", "forgejo", "gitea", "huggingface", "kaggle", "modelscope", "filehosting"]);
-
-export function targetfactory(type, options = {}) {
-  if (!types.has(type)) throw new TypeError(`unknown memory target: ${type}`);
-  if (type === "github" || type === "gitlab" || type === "forgejo" || type === "gitea") return { type, platform: type, owner: options.owner, repo: options.repo, branch: options.branch ?? "main", path: options.path, token: options.token };
-  if (type === "huggingface") return { type, space: options.space, revision: options.revision ?? "main", path: options.path, token: options.token };
-  if (type === "kaggle") return { type, dataset: options.dataset, sslverification: options.sslverification ?? true, path: options.path, token: options.token };
-  if (type === "modelscope") return { type, namespace: options.namespace, repo: options.repo, revision: options.revision ?? "master", path: options.path, token: options.token };
-  return { type, host: options.host, path: options.path, method: options.method ?? "s3compatible", token: options.token };
-}
-
-export function targeturi(target) {
-  if (target.type === "github" || target.type === "gitlab" || target.type === "forgejo" || target.type === "gitea") return `${target.type}://${target.owner}/${target.repo}/${target.path}`;
-  if (target.type === "huggingface") return `hf://${target.space}/${target.path}`;
-  if (target.type === "kaggle") return `kaggle://${target.dataset}/${target.path}`;
-  if (target.type === "modelscope") return `modelscope://${target.namespace}/${target.repo}/${target.path}`;
-  return `${target.method}://${target.host}/${target.path}`;
-}

package/memory/transforms.js

@@ -1,15 +0,0 @@
-/**
- * transforms annotate byte movement without pretending remote storage is physical vram.
- */
-import { computeresult, memoryobject, tobytes } from "./objects.js";
-
-export function transformtocompute(value, options = {}) {
-  const started = performance.now();
-  const object = memoryobject({ ...options, buffer: value?.buffer ?? value });
-  return { ...object, processingtimems: performance.now() - started, memoryusedbytes: object.size };
-}
-
-export function transformtostorage(value, options = {}) {
-  const payload = tobytes(value?.payload ?? value?.buffer ?? value);
-  return computeresult({ id: value?.id, payload, mimetype: options.mimetype ?? value?.mimetype ?? "application/octet-stream", metadata: options.metadata ?? value?.metadata, processingtimems: value?.processingtimems, memoryusedbytes: payload.byteLength });
-}

package/modes/resolve.js

@@ -1,39 +0,0 @@
-/**
- * mode resolver selects open defaults while preserving every caller choice.
- */
-import { modeaxes, validatemode } from "./matrix.js";
-
-/** Resolves an execution profile without starting a process or opening a socket. */
-export function resolvemode(options = {}) {
-  const profile = {
-    execution: options.execution ?? "library",
-    runtime: options.runtime ?? "unknown",
-    memory: options.memory ?? "internal",
-    file: options.file ?? "internal",
-    dependency: options.dependency ?? "internal",
-    visibility: options.visibility ?? "headless",
-    pair: options.pair ?? "without"
-  };
-  for (const [axis, value] of Object.entries(profile)) if (!validatemode(axis, value)) throw new TypeError(`unsupported mode ${axis}:${value}`);
-  return { ...profile, capabilities: modecapabilities(profile) };
-}
-
-/** Returns stable capabilities for adapters and diagnostics. */
-export function modecapabilities(profile) {
-  return {
-    library: profile.execution === "library" || profile.execution === "application",
-    browser: profile.execution === "browser" || profile.execution === "extension" || profile.runtime === "browser" || profile.runtime === "worker",
-    cli: profile.execution === "cli" || profile.execution === "binary",
-    physicalmemory: profile.memory === "physical",
-    vectorizedmemory: profile.memory === "vectorized",
-    externalmemory: profile.memory === "external",
-    externalfile: profile.file === "external",
-    externaldependency: profile.dependency === "external",
-    visible: profile.visibility === "visible"
-  };
-}
-
-/** Applies one profile to a caller supplied operation. */
-export async function withmode(options, operation) { if (typeof operation !== "function") throw new TypeError("mode operation is required"); return operation(resolvemode(options)); }
-
-export { modeaxes };