@wenathlan/saddle 1.8.1

package/LICENSE

@@ -0,0 +1,203 @@
+                    PROPRIETARY SOURCE-AVAILABLE LICENSE - VIEW ONLY
+                       Version 1.0, August 2026
+
+ Copyright (C) August 2026 devthink, nathlan, akadion, nathu filho, allan neris, andraneris
+ Everyone is permitted to view this license document, but changing it
+ is not allowed. This license is NOT an Open Source license.
+
+                            Preamble
+
+  This License governs the source code made available by the Licensor.
+  Unlike free software licenses such as the GNU GPL, this is a
+  proprietary, source-available license.
+
+  The Software is made visible for transparency and verification
+  purposes only. It is NOT free software. It is NOT open source.
+
+  When we speak of proprietary, we are referring to full ownership and
+  restriction, not freedom. Our intention is to protect the Licensor's
+  exclusive rights to copy, modify, distribute and use the work. By
+  contrast to the GPL which guarantees your freedom to share and change,
+  this License is intended to guarantee that the Software remains the
+  exclusive property of its authors and that no rights beyond viewing
+  are granted.
+
+  To protect our rights, we must prevent others from copying, modifying,
+  distributing, or using the Software without permission. Therefore,
+  you have no rights to convey, modify, or use the Software beyond
+  viewing it in its public repository form.
+
+  For the authors' protection, this License clearly explains that there
+  is no warranty for this proprietary software and that any unauthorized
+  use will be treated as copyright infringement.
+
+  The precise terms and conditions for viewing and restriction follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 1.0 of the Proprietary Source-Available
+  License - View Only.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+  works.
+
+  "The Program" or "The Software" refers to any copyrightable work licensed
+  under this License, including source code, object code, documentation,
+  and associated files. Each licensee is addressed as "you".
+
+  "Licensor" refers to the copyright holders: devthink, nathlan, akadion,
+  nathu filho, alllan neris, andraneris.
+
+  To "view" means to read and examine the Software in its public repository
+  form through a web browser, without creating a local copy beyond the
+  temporary cache of your browser.
+
+  To "use" means to execute, run, compile, deploy, host, or otherwise
+  benefit from the functionality of the Software, which is NOT permitted.
+
+  1. Ownership and Intellectual Property.
+
+  The Software is and shall remain the exclusive property of the Licensor.
+  All right, title, and interest in and to the Software, including all
+  copyrights, trademarks, trade secrets, and other intellectual property
+  rights, are owned solely by the Licensor.
+
+  No ownership rights, implied or otherwise, are transferred to you under
+  this License. All rights not expressly granted are reserved.
+
+  2. Grant of Rights - VIEW ONLY.
+
+  Subject to the terms of this License, Licensor grants you a limited,
+  non-exclusive, non-transferable, revocable license solely to VIEW the
+  Software in its public repository form for personal evaluation.
+
+  This grant DOES NOT include any right to:
+
+    a) use, execute, or run the Software;
+    b) copy, reproduce, or duplicate;
+    c) modify, adapt, or create derivative works;
+    d) distribute, publish, sublicense, or sell;
+    e) reverse engineer or decompile.
+
+  3. Prohibitions and Restrictions.
+
+  You are STRICTLY PROHIBITED from undertaking any of the following
+  without prior written permission from the Licensor:
+
+    a) Copying, reproducing, duplicating, or storing the Software, in
+    whole or in part, in any medium;
+
+    b) Modifying, adapting, translating, transforming, or creating
+    derivative works based on the Software;
+
+    c) Distributing, publishing, sublicensing, disclosing, or otherwise
+    making the Software available to third parties, whether gratis or
+    for a fee;
+
+    d) Using the Software for any purpose, including but not limited to
+    development, production, commercial use, internal business operations,
+    offering as a service (SaaS), or training artificial intelligence
+    models;
+
+    e) Removing, altering, or obscuring any copyright, proprietary, or
+    license notices contained in the Software;
+
+    f) Reverse engineering, decompiling, disassembling, or attempting to
+    derive the source code of the Software.
+
+  Any use beyond viewing constitutes copyright infringement and will be
+  prosecuted to the fullest extent of the law.
+
+  4. Confidentiality.
+
+  The Software contains confidential information and proprietary trade
+  secrets of the Licensor. Unauthorized access, inspection, or disclosure
+  is strictly prohibited and may result in civil and criminal liability.
+
+  5. No Warranty.
+
+  The Software is provided for viewing only and may contain errors or
+  omissions. No support, maintenance, or updates are implied.
+
+  6. Acceptance Not Required for Viewing.
+
+  You are not required to accept this License to view the Software in a
+  web browser. However, any action beyond viewing, such as copying,
+  modifying, or using the Software, requires explicit written permission
+  and a separate license agreement. By doing so without permission, you
+  infringe copyright.
+
+  7. Termination.
+
+  This License and all rights granted herein automatically terminate upon
+  any breach of Section 3 by you. Upon termination, you must cease all
+  viewing and destroy all copies, including cached or local copies, of
+  the Software in your possession.
+
+  Moreover, termination does not terminate the rights of the Licensor
+  to seek damages or injunctive relief.
+
+  8. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+  APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+  HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+  OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+  PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+  IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+  ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  9. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+  WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO HAS VIEWED THE PROGRAM
+  AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+  GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+  VIEWING OR INABILITY TO VIEW THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS
+  OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+  PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE), EVEN IF SUCH HOLDER OR
+  OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+  10. Interpretation and Governing Law.
+
+  If the disclaimer of warranty and limitation of liability provided above
+  cannot be given local legal effect according to their terms, reviewing
+  courts shall apply local law that most closely approximates an absolute
+  waiver of all civil liability in connection with the Program, unless a
+  warranty or assumption of liability accompanies a copy of the Program
+  in return for a fee.
+
+  This License shall be governed by the laws of Brazil.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to remain proprietary and
+  fully owned by you, with source visible but with no rights granted, the
+  best way to achieve this is to attach the following notices to the program.
+  It is safest to attach them to the start of each source file.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) August 2026 devthink, nathlan, akadion, nathu filho, alllan neris, andraneris
+    Project ID: <saddle>
+
+    This program is proprietary and confidential: you can view its source
+    code for evaluation purposes only under the terms of the Proprietary
+    Source-Available License - View Only as published by the Licensor.
+    You are not permitted to copy, modify, distribute, or use this program
+    without prior written permission.
+
+    This program is distributed in the hope that it will be transparent,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    Proprietary Source-Available License for more details.
+
+    You should have received a copy of the Proprietary Source-Available
+    License along with this program. If not, see
+    <https://github.com/iakadion/saddle/LICENSE>
+
+  Also add information on how to contact you by electronic and paper mail.

package/README.md

@@ -0,0 +1,192 @@
+# Saddle
+
+<p align="center">
+  <img src="docs/assets/saddlemark.svg" alt="Saddle" width="720" />
+</p>
+
+<p align="center">
+  <strong>Storage-backed jobs, scraping contracts and portable runners for Node.js.</strong><br/>
+  <strong>Binary computing agent, agent browser, computer-use, scraper and packager.</strong><br/>
+  <a href="https://github.com/iakadion/saddle/actions/workflows/ci.yml"><img src="https://github.com/iakadion/saddle/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/iakadion/saddle/releases/tag/v1.8.0"><img src="https://img.shields.io/badge/release-v1.8.0-d35d3d" alt="Release 1.8.0" /></a>
+  <a href="https://github.com/iakadion/saddle/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-202a2f" alt="GPL 3.0 license" /></a>
+</p>
+
+> **Core idea:** storage is the durable side of the working set; the runner is replaceable; the artifact is the boundary. **Storage == Compute** — RAM and disk are the same construct, differing only by usage flag.
+
+Saddle is a **JavaScript ESM engine** for jobs that move data between storage, a working set, an injected runner and durable artifacts. It is also a **virtual machine you publish as a package** that runs on other people's computers (GitHub Actions, Forgejo, Gitea, GitLab, Codeberg, free Docker containers) and turns unlimited third-party storage buckets into virtual RAM/GPU/CPU. Nothing runs on the operator's local machine.
+
+Ships as a library, CLI, binary, n8n node, CRX extension, Android/iOS and Tauri desktop app. Package `@wenathlan/saddle` — published to npm, GitHub Packages, Maven, NuGet, RubyGems and GHCR (auto-mirrored to jsDelivr).
+
+## Start here
+
+Saddle requires **Node.js 22 or newer**.
+
+```bash
+npm install @wenathlan/saddle
+```
+
+```js
+import { scrapeurl, formatforagent } from "@wenathlan/saddle";
+
+const result = await scrapeurl("https://example.com", { format: "markdown" });
+const context = formatforagent(result, { maxchunksize: 2000, keypoints: 4 });
+
+console.log(context.summary);
+```
+
+Deterministic example with no network:
+
+```bash
+node examples/publicapi.js
+```
+
+## What is included
+
+| Area | Contract | Result |
+| --- | --- | --- |
+| Jobs | `engine`, `scheduler`, `inprocess` | `prepare → process → sync → cleanup` |
+| Storage | local, chunked, content-addressed, S3-compatible, GitHub Contents, file hosting | durable objects, ranges, dedupe and sync |
+| Working set | memory bridge, modes, objects, transforms | storage-to-compute and compute-to-storage |
+| Scraping | robots, cache, extraction, semantic facts, schema, scraper | text, metadata, links, controls and structured output |
+| Crawl | normalization, priority frontier, BFS crawler, per-domain budgets and persistent frontier | bounded domain-aware crawling |
+| Browser | snapshots, tabs, frames, actions, fingerprint, session, replay and injected agent | browser actions without vendor lock-in |
+| Operations | queues, idempotency, saga, retry, circuit breaker, health and heartbeat | controlled execution and recovery |
+| Protocols | JSON, NDJSON, SSE, blocks, API envelopes and MCP | transport-neutral messages |
+| Delivery | manifests, workflow registry, binary/container plans | package and runner surfaces |
+| Integrations | GitHub, GitLab, Forgejo, app lifecycle, command scopes and delivery adapters | caller-owned provider connectivity |
+| Agent Browser | capture & replay, stealth, fingerprint | Brave capture, movement replay, session recording |
+| Compute Backends | github-actions, huggingface, gitlab-ci, kaggle, oracle-cloud | free runners chain |
+| Storage Backends | HF, Kaggle, Terabox, R2, Telegram, Discord via rclone | unlimited disk as RAM |
+| Extension | Manifest V3 bridge, snapshot protocol, popup and service worker | user initiated browser control |
+
+## Public API
+
+| Export | Purpose |
+| --- | --- |
+| `saddleurl` | choose fetch or injected browser path |
+| `scrapeurl` | fetch one URL and extract |
+| `scrapehtml` | extract from HTML without network |
+| `extractcontent` | structured extraction |
+| `serializeresult` | serialize as JSON, Markdown, XML |
+| `formatforagent` | summary, chunks, token count |
+| `batchscrape` | bounded URL groups |
+| `crawlurl` | crawl contract |
+| `browseragent` | navigation, click, type, screenshot |
+| `mcpserver` / `mcptransport` | MCP tools over JSONL/HTTP |
+| `nodeserver` | Web Request/Response handler |
+
+Complete API: `docs/libraryapi.md`. Surface overview: [`docs/productindex.md`](docs/productindex.md). Usage examples: [`docs/usage.md`](docs/usage.md).
+
+## The execution model
+
+Saddle coordinates contracts instead of hiding providers. A repo + CI runner is a virtual processor:
+
+- Repo = Disk (persistent state)
+- CI = CPU (workflow_dispatch = function call)
+- Pages = Bus + CDN
+- Static site = BIOS
+- repository_dispatch = IPC
+
+```js
+import { engine, eventbus, inprocess, scheduler } from "@wenathlan/saddle";
+import { localmemory } from "@wenathlan/saddle/memory-node";
+import { localstorage } from "@wenathlan/saddle/storage-node";
+const events = eventbus();
+const run = engine({
+  storage: localstorage("./.saddle-data"),
+  memory: localmemory(),
+  scheduler: scheduler([inprocess()]),
+  events
+});
+const result = await run.run(
+  { name: "example", input: { value: 42 } },
+  ({ job }) => ({ jobid: job.id, ok: true })
+);
+```
+
+The caller still chooses how to provide `fetcher`, browser transport, persistence, proxy pool, captcha solver, webhook secret and remote credentials. The root entry is transport-neutral; Node filesystem and HTTP adapters are explicit subpaths such as `@wenathlan/saddle/storage-node`, `@wenathlan/saddle/memory-node`, `@wenathlan/saddle/server-node`, `@wenathlan/saddle/sessions-file` and `@wenathlan/saddle/queue-persistent`. Saddle does not embed secrets, fixed hosts or a mandatory cloud vendor.
+
+## Browser extension
+
+Version 1.1 includes a pure JavaScript Manifest V3 reference surface in [`extension/`](extension/). It is deliberately narrow: the user invokes the action, the popup sends a versioned command, the service worker routes it, and an isolated content bridge returns bounded page metadata, visible text or a user initiated action result.
+
+```bash
+# load the unpacked extension from chrome://extensions
+ls extension/manifest.json extension/worker.js extension/content.js extension/popup.html
+```
+
+The extension requests `activeTab`, `scripting` and `storage`; it does not request broad host permissions, cookies, `webRequest`, debugger access or arbitrary page code execution. Its public contracts are available from `@wenathlan/saddle/extension`. See [`extension/README.md`](extension/README.md) for the unpacked development flow.
+
+## CLI
+
+```bash
+saddle help
+saddle modes
+saddle runexample
+saddle mcp
+```
+
+## Security boundaries
+
+| Boundary | Policy |
+| --- | --- |
+| Credentials | injected at runtime; never committed |
+| Network | http/https validated; private targets blocked |
+| Crawling | robots rules and crawl delay explicit |
+| Storage | adapters replaceable |
+| Runtime | Node HTTP isolated |
+| Failure | retry, circuit breaker, idempotency configurable |
+
+## Package surfaces
+
+| Registry | Artifact | Workflow | Status |
+| --- | --- | --- | --- |
+| GitHub npm | `@iakadion/saddle@1.8.0` | publishgithubnpm.yml | published |
+| GHCR | `ghcr.io/iakadion/saddle:1.8.0` and `latest` | publishghcr.yml | published |
+| Maven | `io.devthink:saddle:1.8.0` | publishmaven.yml | published after JDK 26 retry |
+| NuGet | `Saddle.1.8.0.nupkg` | publishnuget.yml | published |
+| RubyGems | `saddle 1.8.0` | publishrubygems.yml | published |
+| npmjs | `@wenathlan/saddle@1.8.1` | publishnpmjs.yml | pending follow-up release workflow |
+
+## Development
+
+```bash
+npm ci
+npm test
+npm run check
+npm run formatcheck
+npm run pack:check
+```
+
+Test suite deterministic, no network or real credentials required.
+
+## Repository map
+
+```
+core/          errors, events and identifiers
+domain/        jobs, artifacts, sessions and providers
+memory/        working-set bridge, modes, objects and transforms
+storage/       local, chunked, remote and file-hosting adapters
+scrape/        robots, cache, extraction, schema and scraper
+crawl/         URL normalization, crawler and persistent frontier
+queue/         queue, idempotency, saga and recovery
+browser/       fingerprint, session and agent contracts
+browser/       snapshots, tabs, frames, actions and recorder contracts
+mcp/           optional server and JSONL/HTTP transport
+protocol/      JSON, NDJSON, SSE and block serializers
+workflow/      manifests, templates and registry
+tests/         deterministic engine coverage
+docs/          architecture, API, release and registry notes
+surfaces/      browser, extension, desktop, mobile and n8n contracts
+```
+
+Root-based JavaScript ESM layout, no src/ directory, no TypeScript build required.
+
+## Current scope
+
+Version 1.8 establishes the engine contracts, browser snapshot foundation, storage sync primitives, runner recovery contracts, scraping context provenance, API/MCP security contracts, bot integration lifecycle, the first tested extension bridge, desktop/mobile/n8n surface contracts, a framework-neutral operator control boundary and the first cross-runtime import boundary. Native runtimes, n8n host registration, provider credentials, persistent databases and production deployment remain caller-selected adapters. The next improvements should extend these contracts without coupling the core to one forge, registry, browser or storage vendor.
+
+## License
+
+Saddle is distributed under the [GNU General Public License v3.0](LICENSE).

package/adapters/forge.js

@@ -0,0 +1,16 @@
+/**
+ * forge adapter defines the common dispatch and artifact surface for compatible forges.
+ */
+import { transport } from "./transport.js";
+
+export function forgeadapter(options = {}) {
+  if (!options.baseurl || typeof options.token !== "function") throw new TypeError("forge adapter requires baseurl and token function");
+  const client = transport({ fetcher: options.fetcher, attempts: options.attempts, timeout: options.timeout });
+  async function call(path, init = {}) { const token = await options.token(); return client.request(new URL(path, options.baseurl), { ...init, headers: { authorization: `Bearer ${token}`, accept: "application/json", ...(init.headers ?? {}) } }); }
+  return {
+    kind: options.kind ?? "forge",
+    async health(path = "/") { const response = await call(path); return { ok: response.ok, status: response.status }; },
+    async dispatch(spec) { if (!spec?.path || !spec.ref) throw new TypeError("forge dispatch requires path and ref"); const response = await call(spec.path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ref: spec.ref, inputs: spec.inputs ?? {} }) }); return { accepted: response.ok, status: response.status, body: response.json ? await response.json() : undefined }; },
+    async upload(spec) { if (!spec?.path || !spec.data) throw new TypeError("forge upload requires path and data"); const response = await call(spec.path, { method: "PUT", headers: { "content-type": spec.contenttype ?? "application/octet-stream" }, body: spec.data }); return { accepted: response.ok, status: response.status }; }
+  };
+}

package/adapters/forgejo.js

@@ -0,0 +1,8 @@
+/**
+ * forgejo and gitea can reuse the open forge contract with a caller supplied base url.
+ */
+import { forgeadapter } from "./forge.js";
+
+export function forgejoadapter(options = {}) { return forgeadapter({ ...options, kind: "forgejo" }); }
+export function giteaadapter(options = {}) { return forgeadapter({ ...options, kind: "gitea" }); }
+export function codebergadapter(options = {}) { return forgeadapter({ ...options, kind: "codeberg" }); }

package/adapters/github.js

@@ -0,0 +1,19 @@
+/**
+ * github adapter uses caller supplied credentials and base url configuration.
+ */
+import { transport } from "./transport.js";
+
+export function githubadapter(options = {}) {
+  if (!options.baseurl || typeof options.token !== "function") throw new TypeError("github adapter requires baseurl and token function");
+  const client = transport({ fetcher: options.fetcher, attempts: options.attempts, timeout: options.timeout });
+  async function call(path, init = {}) {
+    const token = await options.token();
+    const headers = { accept: "application/vnd.github+json", authorization: `Bearer ${token}`, "x-github-api-version": options.apiversion ?? "2022-11-28", ...(init.headers ?? {}) };
+    return client.request(new URL(path, options.baseurl), { ...init, headers });
+  }
+  return {
+    async health() { const response = await call("/rate_limit"); return { ok: response.ok, status: response.status }; },
+    async dispatch(owner, repository, workflow, input = {}) { const response = await call(`/repos/${owner}/${repository}/actions/workflows/${workflow}/dispatches`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ref: input.ref ?? "main", inputs: input.inputs ?? {} }) }); return { accepted: response.status === 204, status: response.status }; },
+    async run(owner, repository, runid) { const response = await call(`/repos/${owner}/${repository}/actions/runs/${runid}`); return response.json(); }
+  };
+}

package/adapters/gitlab.js

@@ -0,0 +1,10 @@
+/**
+ * gitlab adapter keeps project addressing and token ownership outside the package.
+ */
+import { forgeadapter } from "./forge.js";
+
+export function gitlabadapter(options = {}) {
+  const project = encodeURIComponent(options.project ?? "");
+  const base = forgeadapter({ ...options, kind: "gitlab" });
+  return { ...base, async dispatch(spec) { return base.dispatch({ ...spec, path: spec.path ?? `/api/v4/projects/${project}/pipeline` }); } };
+}

package/adapters/huggingface.js

@@ -0,0 +1,6 @@
+/**
+ * hugging face storage remains an explicit adapter with caller supplied repository path.
+ */
+import { forgeadapter } from "./forge.js";
+
+export function huggingfaceadapter(options = {}) { return forgeadapter({ ...options, kind: "huggingface" }); }

package/adapters/socket.js

@@ -0,0 +1,14 @@
+/**
+ * socket adapter keeps realtime optional and accepts a caller supplied websocket constructor.
+ */
+export function socketadapter(options = {}) {
+  const websocket = options.websocket ?? globalThis.WebSocket;
+  if (!websocket) throw new Error("websocket implementation is required");
+  return {
+    connect(url, protocols) {
+      if (!url) throw new TypeError("socket url is required");
+      const socket = new websocket(url, protocols);
+      return { socket, send(value) { socket.send(typeof value === "string" ? value : JSON.stringify(value)); }, close(code, reason) { socket.close(code, reason); } };
+    }
+  };
+}

package/adapters/transport.js

@@ -0,0 +1,30 @@
+/**
+ * transport centralizes timeout retry and jitter without choosing a host or vendor.
+ */
+export function transport(options = {}) {
+  const fetcher = options.fetcher ?? fetch;
+  const attempts = options.attempts ?? 3;
+  const timeout = options.timeout ?? 30000;
+  const retrycodes = new Set(options.retrycodes ?? [408, 409, 429, 500, 502, 503, 504]);
+  async function request(url, init = {}) {
+    let last;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      try {
+        const response = await fetcher(url, { ...init, signal: init.signal ?? controller.signal });
+        if (response.ok || !retrycodes.has(response.status) || attempt === attempts - 1) return response;
+        last = new Error(`request failed with ${response.status}`);
+      } catch (error) {
+        last = error;
+        if (attempt === attempts - 1) throw error;
+      } finally { clearTimeout(timer); }
+      await delay(backoff(options, attempt));
+    }
+    throw last ?? new Error("request failed");
+  }
+  return { request };
+}
+
+function backoff(options, attempt) { const base = options.backoff ?? 250; const jitter = options.jitter ?? 0; return base * 2 ** attempt + Math.floor(Math.random() * jitter); }
+function delay(milliseconds) { return new Promise((resolve) => setTimeout(resolve, milliseconds)); }

package/ai/chunk.js

@@ -0,0 +1,22 @@
+/**
+ * markdown chunking preserves heading paths and uses paragraph boundaries before hard cuts.
+ */
+import { estimatetokens } from "./tokens.js";
+
+export function chunkmarkdown(markdown, options = {}) {
+  const maxtokens = options.maxtokens ?? 512;
+  const overlap = options.overlaptokens ?? 50;
+  const lines = String(markdown ?? "").split(/\r?\n/);
+  const chunks = [];
+  let headingpath = [];
+  let buffer = [];
+  function flush() { if (!buffer.length) return; const content = buffer.join("\n").trim(); if (content) chunks.push({ content, headingpath: [...headingpath], tokencount: estimatetokens(content, options.model) }); buffer = []; }
+  for (const line of lines) {
+    const heading = line.match(/^(#{1,6})\s+(.+)$/);
+    if (heading) { flush(); const level = heading[1].length; headingpath = headingpath.slice(0, level - 1); headingpath[level - 1] = heading[2].trim(); buffer.push(line); continue; }
+    buffer.push(line);
+    if (estimatetokens(buffer.join("\n"), options.model) > maxtokens) { const last = buffer.pop(); flush(); const overlaptext = buffer.slice(-overlap).join("\n"); buffer = overlaptext ? [overlaptext, last] : [last]; }
+  }
+  flush();
+  return chunks.map((chunk, index) => ({ ...chunk, id: `chunk${index}` }));
+}

package/ai/llmstxt.js

@@ -0,0 +1,12 @@
+/**
+ * llms text generation creates compact absolute links for agent consumption.
+ */
+export function llmstxt(options = {}) {
+  const title = options.title ?? "saddle";
+  const description = options.description ?? "binary computing engine and browser automation library";
+  const pages = (options.pages ?? []).filter((page) => page?.url && /^https:\/\//.test(page.url)).slice(0, options.limit ?? 100);
+  const lines = [`# ${title}`, `> ${description}`, "", "## pages", "", ...pages.map((page) => `- [${page.title ?? page.url}](${page.url}): ${(page.description ?? "").slice(0, 100)}`)];
+  return `${lines.join("\n")}\n`;
+}
+
+export function llmsfull(options = {}) { return (options.pages ?? []).filter((page) => page?.url && /^https:\/\//.test(page.url)).map((page) => `# ${page.title ?? page.url}\n\nsource: ${page.url}\n\n${page.content ?? ""}`).join("\n\n---\n\n"); }

package/ai/provenance.js

@@ -0,0 +1,18 @@
+/**
+ * context provenance links retrieved chunks to source, query and transformation metadata.
+ */
+
+/** Creates a serializable retrieval record for an agent context result. */
+export function provenance(input = {}) {
+  if (!input.source && !input.sourceurl) throw new TypeError("provenance requires a source");
+  return { version: 1, source: input.source ?? input.sourceurl, sourceurl: input.sourceurl, documentid: input.documentid, query: input.query, retrievedat: Number(input.retrievedat ?? Date.now()), chunks: Array.isArray(input.chunks) ? input.chunks.map((chunk, index) => ({ id: String(chunk.id ?? index), contenthash: chunk.contenthash, score: chunk.score === undefined ? undefined : Number(chunk.score), headingpath: chunk.headingpath, tokencount: chunk.tokencount, citation: chunk.citation ?? input.sourceurl })) : [], metadata: { ...(input.metadata ?? {}) } };
+}
+
+/** Merges provenance records while deduplicating chunk identifiers. */
+export function mergeprovenance(records = []) {
+  const valid = records.filter(Boolean);
+  const chunks = [];
+  const seen = new Set();
+  for (const record of valid) for (const chunk of record.chunks ?? []) { const key = `${record.documentid ?? record.source}:${chunk.id}`; if (seen.has(key)) continue; seen.add(key); chunks.push({ ...chunk, source: record.source, documentid: record.documentid }); }
+  return { version: 1, sources: [...new Set(valid.map((record) => record.source))], chunks, mergedat: Date.now() };
+}

package/ai/rag.js

@@ -0,0 +1,14 @@
+/**
+ * rag manifests connect chunks to embedding stores without forcing a vendor client.
+ */
+export async function ragmanifest(input = {}) {
+  const chunks = input.chunks ?? [];
+  const unique = [];
+  const hashes = new Set();
+  for (const chunk of chunks) { const hash = await hashtext(chunk.content); if (hashes.has(hash)) continue; hashes.add(hash); unique.push({ ...chunk, contenthash: hash, documentid: hash.slice(0, 16), metadata: { ...(input.metadata ?? {}), ...(chunk.metadata ?? {}) } }); }
+  return { documentid: (await hashtext(input.source ?? unique.map((chunk) => chunk.content).join("\n"))).slice(0, 16), source: input.source, chunks: unique, embeddingmodel: input.embeddingmodel, embeddingdimensions: input.embeddingdimensions, createdat: Date.now() };
+}
+
+export function vectorrecord(chunk, vector, options = {}) { return { id: `${chunk.documentid}-${chunk.id}`, vector, metadata: { headingpath: chunk.headingpath, contenthash: chunk.contenthash, sourceurl: options.sourceurl, tokencount: chunk.tokencount, contenttype: options.contenttype ?? "text", language: options.language ?? "en", embeddingmodel: options.embeddingmodel, embeddingdimensions: vector?.length } }; }
+
+async function hashtext(text) { const bytes = new TextEncoder().encode(String(text)); if (globalThis.crypto?.subtle) { const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes); return [...new Uint8Array(digest)].map((value) => value.toString(16).padStart(2, "0")).join(""); } return Array.from(bytes).map((value) => value.toString(16).padStart(2, "0")).join("").slice(0, 64).padEnd(64, "0"); }

package/ai/tokens.js

@@ -0,0 +1,9 @@
+/**
+ * token helpers use configurable model ratios and never require a provider tokenizer.
+ */
+const ratios = Object.freeze({ default: 4, gpt: 3.5, claude: 3.2, gemini: 3.5 });
+
+export function estimatetokens(text, model = "default") { const ratio = ratios[model] ?? ratios.default; return Math.ceil(String(text ?? "").length / ratio); }
+export function fitscontext(text, context, model = "default") { return estimatetokens(text, model) <= context; }
+export function tokenbudget(text, options = {}) { const tokens = estimatetokens(text, options.model); return { tokens, context: options.context ?? null, fits: options.context == null ? true : tokens <= options.context, remaining: options.context == null ? null : Math.max(0, options.context - tokens) }; }
+export function settokenratios(values = {}) { Object.assign(ratios, values); return { ...ratios }; }

package/api/auth.js

@@ -0,0 +1,13 @@
+/**
+ * api authorization delegates token verification to the caller and never stores credentials.
+ */
+
+/** Authorizes a request through an injected verifier or returns an anonymous principal. */
+export async function authorize(request, options = {}) {
+  const token = request?.headers?.get?.("authorization")?.replace(/^Bearer\s+/i, "") ?? request?.headers?.get?.("x-api-key");
+  if (typeof options.verify !== "function") return { authenticated: false, subject: "anonymous", tokenpresent: Boolean(token) };
+  if (!token) return { authenticated: false, subject: "anonymous", tokenpresent: false };
+  const principal = await options.verify(token, request);
+  if (!principal) { const error = new Error("request is not authorized"); error.code = "UNAUTHORIZED"; throw error; }
+  return { authenticated: true, subject: String(principal.subject ?? principal.id ?? "caller"), claims: { ...(principal.claims ?? {}) } };
+}

package/api/contracts.js

@@ -0,0 +1,17 @@
+/**
+ * api contracts keep request identity and success envelopes stable across HTTP and MCP adapters.
+ */
+
+export const apiversion = 1;
+
+/** Extracts a caller supplied request id or creates a local id without exposing secrets. */
+export function requestcontext(request, options = {}) {
+  const requestid = request?.headers?.get?.("x-request-id") ?? options.requestid ?? `request${Date.now().toString(36)}`;
+  return { version: apiversion, requestid: String(requestid), method: request?.method ?? options.method, path: options.path };
+}
+
+/** Creates a versioned success envelope for APIs that opt into envelopes. */
+export function successpayload(data, context = {}) { return { version: apiversion, requestid: String(context.requestid ?? `request${Date.now().toString(36)}`), data }; }
+
+/** Creates a versioned error payload with a stable retry hint. */
+export function errorpayload(code, message, context = {}) { return { version: apiversion, requestid: String(context.requestid ?? `request${Date.now().toString(36)}`), error: { code: String(code), message: String(message), retryafter: Number(context.retryafter ?? 0) } }; }