@wenathlan/saddle 1.8.1

package/api/control.js

@@ -0,0 +1,33 @@
+/**
+ * control service exposes operator controls through Web Request and Response without selecting a web framework.
+ */
+
+import { authorize } from "./auth.js";
+import { requestcontext } from "./contracts.js";
+import { errorresponse, jsonresponse } from "./http.js";
+import { controlsurface } from "../surfaces/controls.js";
+
+/** Creates a framework-neutral HTTP handler for an injected operator control surface. */
+export function controlservice(options = {}) {
+  const controls = options.controls ?? controlsurface({ adapters: options.adapters, audit: options.audit });
+  const path = String(options.path ?? "/v1/control");
+  if (!path.startsWith("/")) throw new TypeError("control service path must be absolute");
+
+  async function handle(request) {
+    const context = requestcontext(request, { path });
+    try {
+      await authorize(request, { verify: options.verify });
+      const url = new URL(request.url ?? request);
+      if (url.pathname !== path) return errorresponse("NOT_FOUND", "control route not found", { status: 404, requestid: context.requestid });
+      if (request.method === "GET") return jsonresponse({ ...controls.describe(), requestid: context.requestid });
+      if (request.method !== "POST") return errorresponse("METHOD_NOT_ALLOWED", "control route requires GET or POST", { status: 405, requestid: context.requestid });
+      const input = typeof request.json === "function" ? await request.json() : {};
+      const result = await controls.execute(input);
+      return jsonresponse({ requestid: context.requestid, data: result }, { status: result.ok ? 200 : 409 });
+    } catch (error) {
+      return errorresponse(error?.code ?? "CONTROL_REQUEST_FAILED", error?.message ?? error, { status: error?.code === "UNAUTHORIZED" ? 401 : 400, requestid: context.requestid });
+    }
+  }
+
+  return { path, controls, handle };
+}

package/api/http.js

@@ -0,0 +1,12 @@
+/**
+ * http helpers use the web request response contract and remain framework neutral.
+ */
+export function jsonresponse(data, options = {}) { return new Response(JSON.stringify(data), { status: options.status ?? 200, headers: { "content-type": "application/json; charset=utf-8", "x-content-type-options": "nosniff", "referrer-policy": "no-referrer", ...(options.headers ?? {}) } }); }
+
+export function errorresponse(code, message, options = {}) { return jsonresponse({ error: { code, message, retryafter: options.retryafter ?? 0, requestid: options.requestid ?? `request${Date.now().toString(36)}` } }, { status: options.status ?? 400, headers: options.headers }); }
+
+export function sseresponse(events) {
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({ start(controller) { for (const event of events) controller.enqueue(encoder.encode(`event: ${event.event ?? "message"}\ndata: ${JSON.stringify(event.data ?? {})}\n\n`)); controller.close(); } });
+  return new Response(stream, { headers: { "content-type": "text/event-stream", "cache-control": "no-cache, no-store", connection: "keep-alive", "x-accel-buffering": "no", "x-content-type-options": "nosniff" } });
+}

package/api/rate.js

@@ -0,0 +1,31 @@
+/**
+ * token bucket rate limiting supports global user and domain keys.
+ */
+export function ratebucket(options = {}) {
+  const capacity = options.capacity ?? 10;
+  const refill = options.refill ?? capacity;
+  const interval = options.interval ?? 60000;
+  const buckets = new Map();
+  function consume(key, cost = 1) {
+    const now = Date.now();
+    const previous = buckets.get(key) ?? { tokens: capacity, at: now };
+    const tokens = Math.min(capacity, previous.tokens + ((now - previous.at) / interval) * refill);
+    if (tokens < cost) return { allowed: false, retryafter: Math.ceil(((cost - tokens) / refill) * interval) };
+    buckets.set(key, { tokens: tokens - cost, at: now });
+    return { allowed: true, retryafter: 0 };
+  }
+  return { consume, clear() { buckets.clear(); } };
+}
+
+export function ratelimiter(options = {}) {
+  const global = ratebucket(options.global ?? { capacity: 1000, refill: 1000 });
+  const user = ratebucket(options.user ?? { capacity: 100, refill: 100 });
+  const domain = ratebucket(options.domain ?? { capacity: 10, refill: 10 });
+  return {
+    check(input = {}) {
+      const checks = [[global, "global"], [user, `user:${input.user ?? "anonymous"}`], [domain, `domain:${input.domain ?? "unknown"}`]];
+      for (const [bucket, key] of checks) { const result = bucket.consume(key); if (!result.allowed) return { allowed: false, retryafter: result.retryafter, scope: key }; }
+      return { allowed: true, retryafter: 0 };
+    }
+  };
+}

package/api/security.js

@@ -0,0 +1,42 @@
+/**
+ * URL security rejects private network targets before a fetch is attempted.
+ * DNS resolution remains a host adapter concern and is never performed silently.
+ */
+export function assertpublicurl(value, options = {}) {
+  const url = new URL(value);
+  if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("url protocol is not allowed");
+  if (Array.isArray(options.allowedhosts) && options.allowedhosts.length > 0 && !options.allowedhosts.includes(url.hostname)) throw new Error("url host is not allowed");
+  if (options.allowprivate) return url;
+  if (privatehostname(url.hostname) || privateip(url.hostname)) throw new Error("private network target is not allowed");
+  return url;
+}
+
+/** Checks a resolved address list through a caller supplied DNS resolver to reduce rebinding risk. */
+export async function assertresolvedpublicurl(value, options = {}) {
+  const url = assertpublicurl(value, options);
+  if (typeof options.resolve !== "function" || options.allowprivate) return url;
+  const addresses = await options.resolve(url.hostname);
+  if (!Array.isArray(addresses) || addresses.length === 0) throw new Error("url host did not resolve to an address");
+  for (const address of addresses) if (privateip(String(address)) || privatehostname(String(address))) throw new Error("resolved target is private");
+  return url;
+}
+
+/** Validates a redirect chain as public and bounded before a caller follows it. */
+export function assertredirectchain(values = [], options = {}) {
+  const maxredirects = Number(options.maxredirects ?? 5);
+  if (!Array.isArray(values) || values.length > maxredirects + 1) throw new Error("redirect chain exceeds configured limit");
+  return values.map((value) => assertpublicurl(value, options).href);
+}
+
+/** Returns a non throwing boolean for validators and middleware. */
+export function ispublicurl(value, options = {}) { try { assertpublicurl(value, options); return true; } catch { return false; } }
+
+function privatehostname(hostname) { const value = hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, ""); return value.endsWith(".local") || value.endsWith(".internal") || value.endsWith(".localhost") || value === "localhost" || value === "broadcasthost"; }
+function privateip(hostname) {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe80:") || normalized.startsWith("::ffff:")) return true;
+  const parts = normalized.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+  const [first, second] = parts;
+  return first === 10 || first === 127 || first === 169 && second === 254 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168;
+}

package/api/service.js

@@ -0,0 +1,36 @@
+/**
+ * saddle service exposes universal routes without choosing hono fastify express or another server.
+ */
+import { crawl } from "../crawl/crawler.js";
+import { ratelimiter } from "./rate.js";
+import { errorresponse, jsonresponse, sseresponse } from "./http.js";
+import { assertpublicurl } from "./security.js";
+import { authorize } from "./auth.js";
+import { requestcontext, successpayload } from "./contracts.js";
+
+export function saddleservice(options = {}) {
+  if (typeof options.scrape !== "function") throw new TypeError("service requires scrape");
+  const limit = options.ratelimiter ?? ratelimiter();
+  const jobs = new Map();
+  async function handle(request) {
+    const url = new URL(request.url ?? request);
+    const context = requestcontext(request, { path: url.pathname });
+    const input = request.json ? await request.clone().json().catch(() => ({})) : request.body ?? {};
+    let principal;
+    try { principal = await authorize(request, { verify: options.verify }); } catch (error) { return errorresponse(error.code ?? "UNAUTHORIZED", error.message, { status: 401, requestid: context.requestid }); }
+    const rate = limit.check({ user: request.headers?.get?.("x-api-key") ?? "anonymous", domain: url.hostname });
+    if (!rate.allowed) return errorresponse("RATE_LIMITED", "request rate limit exceeded", { status: 429, retryafter: rate.retryafter, requestid: context.requestid });
+    try {
+      if (url.pathname === "/health" && request.method === "GET") return jsonresponse({ healthy: true, jobs: jobs.size, principal: principal.subject }, { headers: { "x-request-id": context.requestid } });
+      if (url.pathname === "/v1/event" && request.method === "GET") return sseresponse([{ event: "health", data: { healthy: true } }]);
+      if (url.pathname === "/v1/scrape" && request.method === "POST") { assertpublicurl(input.url, options.security); const result = await options.scrape(input.url, input); return jsonresponse(options.envelope ? successpayload(result, context) : result, { headers: { "x-request-id": context.requestid } }); }
+      if (url.pathname === "/v1/crawl" && request.method === "POST") { assertpublicurl(input.url, options.security); const result = await crawl(input.url, { ...input, scrape: (target) => options.scrape(target, input) }); return jsonresponse(result); }
+      if (url.pathname === "/v1/batch" && request.method === "POST") { const results = []; for (const item of input.urls ?? []) { assertpublicurl(item, options.security); results.push(await options.scrape(item, input)); } return jsonresponse({ results, completed: results.length, total: input.urls?.length ?? 0 }); }
+      if (url.pathname === "/v1/scrape/async" && request.method === "POST") { assertpublicurl(input.url, options.security); const id = `task${Date.now().toString(36)}${jobs.size}`; jobs.set(id, { id, status: "queued" }); Promise.resolve(options.scrape(input.url, input)).then((result) => jobs.set(id, { id, status: "completed", result }), (error) => jobs.set(id, { id, status: "failed", error: error.message })); return jsonresponse({ id, status: "queued" }, { status: 202 }); }
+      const match = url.pathname.match(/^\/v1\/scrape\/([^/]+)$/);
+      if (match && request.method === "GET") return jobs.has(match[1]) ? jsonresponse(jobs.get(match[1])) : errorresponse("NOT_FOUND", "task not found", { status: 404 });
+      return errorresponse("NOT_FOUND", "route not found", { status: 404 });
+    } catch (error) { return errorresponse(error.code ?? "REQUEST_FAILED", error.message, { status: error.code === "UNAUTHORIZED" ? 401 : 500, requestid: context.requestid }); }
+  }
+  return { handle, jobs };
+}

package/binary/build.js

@@ -0,0 +1,17 @@
+/**
+ * binary builder plans portable artifacts without choosing a compiler vendor.
+ */
+export const binarytargets = Object.freeze(["node", "deno", "bun", "wasm", "singlefile"]);
+
+/** Creates a deterministic binary build plan from explicit options. */
+export function binaryplan(options = {}) {
+  const target = options.target ?? "node";
+  if (!binarytargets.includes(target)) throw new TypeError(`unsupported binary target: ${target}`);
+  return { name: options.name ?? "saddle", target, entry: options.entry ?? "cli/main.js", output: options.output ?? "dist", command: options.command ?? `build ${target}`, minify: options.minify ?? false, embedruntime: options.embedruntime ?? false, externaldependencies: options.externaldependencies ?? [], metadata: options.metadata ?? {} };
+}
+
+/** Returns an artifact manifest without writing files or running a compiler. */
+export function binarymanifest(plan) { return { name: plan.name, target: plan.target, entry: plan.entry, output: plan.output, files: [plan.entry], reproducible: true, metadata: plan.metadata }; }
+
+/** Resolves an injected builder and preserves the plan as the execution boundary. */
+export async function buildbinary(plan, builder) { if (typeof builder !== "function") throw new TypeError("binary builder is required"); return builder(binarymanifest(plan)); }

package/bot/adapter.js

@@ -0,0 +1,8 @@
+/**
+ * platform adapters expose only the operations a bot needs.
+ */
+export function platformadapter(methods) {
+  const required = ["authenticate", "listrepos", "createwebhook", "executebot"];
+  for (const name of required) if (typeof methods?.[name] !== "function") throw new TypeError(`platform adapter requires ${name}`);
+  return methods;
+}

package/bot/bot.js

@@ -0,0 +1,39 @@
+/**
+ * saddlebot unifies commands without owning a platform credential or scheduler.
+ */
+import { parsecommand } from "./commands.js";
+
+export function saddlebot(options = {}) {
+  const adapters = new Map(Object.entries(options.adapters ?? {}));
+  const tasks = new Map();
+  const guard = options.guard;
+  const keys = new Map();
+  const state = { status: "stopped", startedat: undefined, commands: 0 };
+  const timers = new Set();
+  async function executecommand(input, context = {}) {
+    const parsed = typeof input === "string" ? parsecommand(input) : input;
+    state.commands += 1;
+    if (parsed.command === "status") return getstatus();
+    if (parsed.command === "help") return { commands: ["capture", "scrape", "review", "deploy", "memory", "test", "release", "webhook", "schedule", "publish", "artifact", "status"] };
+    const platform = parsed.flags.platform ?? context.platform;
+    const adapter = adapters.get(platform);
+    if (!adapter) throw new Error(`no adapter registered for ${platform ?? "command"}`);
+    const permission = guard?.check({ command: parsed.command, platform, scopes: context.scopes ?? [] });
+    if (permission && !permission.allowed) { const error = new Error(`bot command is not authorized: ${parsed.command}`); error.code = "BOT_COMMAND_UNAUTHORIZED"; error.missing = permission.missing; throw error; }
+    const key = context.idempotencykey;
+    if (key && keys.has(key)) return keys.get(key);
+    const result = await adapter.executebot({ command: parsed.command, flags: parsed.flags, context });
+    if (key) keys.set(key, result);
+    return result;
+  }
+  function getstatus() { return { ...state, adapters: [...adapters.keys()], tasks: [...tasks.keys()] }; }
+  return {
+    register(name, adapter) { adapters.set(name, adapter); return this; },
+    async start() { state.status = "running"; state.startedat = Date.now(); return getstatus(); },
+    async stop() { for (const timer of timers) clearTimeout(timer); timers.clear(); state.status = "stopped"; return getstatus(); },
+    executecommand,
+    async handlewebhook(platform, event) { const adapter = adapters.get(platform); if (!adapter) throw new Error(`no adapter registered for ${platform}`); return adapter.executebot({ command: "webhook", event }); },
+    scheduletask(name, task, delay) { if (typeof task !== "function" || !Number.isFinite(delay)) throw new TypeError("schedule requires task and delay"); const timer = setTimeout(async () => { tasks.delete(name); await task(); }, delay); timers.add(timer); tasks.set(name, { name, delay, scheduledat: Date.now() }); return tasks.get(name); },
+    getstatus
+  };
+}

package/bot/commands.js

@@ -0,0 +1,18 @@
+/**
+ * command parsing keeps the bot surface serializable and platform neutral.
+ */
+export function parsecommand(input) {
+  const tokens = tokenize(String(input ?? ""));
+  const command = tokens.shift() ?? "help";
+  const flags = {};
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2).toLowerCase();
+    const value = tokens[index + 1]?.startsWith("--") ? true : tokens[++index] ?? true;
+    flags[key] = value;
+  }
+  return { command: command.toLowerCase(), flags };
+}
+
+function tokenize(input) { return input.match(/(?:[^\s"]+|"[^"]*")+/g)?.map((value) => value.replace(/^"|"$/g, "")) ?? []; }

package/bot/permissions.js

@@ -0,0 +1,16 @@
+/**
+ * command permissions keep bot actions explicit and platform neutral.
+ */
+
+/** Creates a command guard from caller supplied command and scope policies. */
+export function commandguard(options = {}) {
+  const policies = options.policies ?? {};
+  function check(input = {}) {
+    const command = String(input.command ?? "");
+    const policy = policies[command] ?? { scopes: [] };
+    const scopes = input.scopes ?? [];
+    const missing = (policy.scopes ?? []).filter((scope) => !scopes.includes(scope));
+    return { allowed: missing.length === 0, command, missing, platform: input.platform };
+  }
+  return { check };
+}

package/browser/actions.js

@@ -0,0 +1,33 @@
+/**
+ * browser actions normalize adapter outcomes and preserve failure metadata for agents and replay.
+ */
+
+export const browseractions = Object.freeze(["navigate", "click", "type", "fill", "key", "scroll", "upload", "screenshot", "snapshot"]);
+
+/** Creates a stable action result independent of the underlying browser vendor. */
+export function actionresult(action, options = {}) {
+  if (!browseractions.includes(action)) throw new TypeError(`unsupported browser action: ${action}`);
+  return { version: 1, action, ok: true, startedat: Number(options.startedat ?? Date.now()), finishedat: Number(options.finishedat ?? Date.now()), tabid: options.tabid === undefined ? undefined : String(options.tabid), frameid: options.frameid === undefined ? undefined : String(options.frameid), snapshotid: options.snapshotid, value: options.value, metadata: options.metadata ?? {} };
+}
+
+/** Creates a stable action failure without leaking adapter internals or credentials. */
+export function actionfailure(action, error, options = {}) {
+  if (!action || typeof action !== "string") throw new TypeError("browser action failure requires an action name");
+  return { version: 1, action, ok: false, code: String(options.code ?? error?.code ?? "BROWSER_ACTION_FAILED"), message: String(error?.message ?? error ?? "browser action failed"), retryable: Boolean(options.retryable ?? error?.retryable), tabid: options.tabid === undefined ? undefined : String(options.tabid), frameid: options.frameid === undefined ? undefined : String(options.frameid), snapshotid: options.snapshotid, metadata: options.metadata ?? {} };
+}
+
+/** Executes a bounded list of actions through an injected adapter and keeps per-action outcomes. */
+export async function actionbatch(adapter, actions = [], options = {}) {
+  if (!adapter || typeof adapter !== "object") throw new TypeError("browser action batch requires an adapter");
+  if (!Array.isArray(actions) || actions.length > (options.maxactions ?? 100)) throw new TypeError("browser action batch is invalid or too large");
+  const results = [];
+  for (const item of actions) {
+    const action = String(item?.action ?? "");
+    const method = adapter[action];
+    if (typeof method !== "function") { results.push(actionfailure(action, new Error(`browser adapter does not support ${action}`), { code: "UNSUPPORTED_ACTION" })); continue; }
+    const startedat = Date.now();
+    try { const value = await method(item.options ?? item.value); results.push(actionresult(action, { ...item, startedat, finishedat: Date.now(), value })); }
+    catch (error) { results.push(actionfailure(action, error, { ...item, tabid: item.tabid, frameid: item.frameid, snapshotid: item.snapshotid })); if (options.stoponerror) break; }
+  }
+  return results;
+}

package/browser/agent.js

@@ -0,0 +1,9 @@
+/**
+ * browser agent delegates browser actions to an injected runtime adapter.
+ */
+export function browseragent(adapter) {
+  const required = ["navigate", "click", "type", "screenshot", "html", "text", "title", "scrolltobottom", "executecommands"];
+  for (const name of required) if (typeof adapter?.[name] !== "function") throw new TypeError(`browser adapter requires ${name}`);
+  const optional = (name) => (...args) => { if (typeof adapter[name] !== "function") throw new Error(`browser adapter does not support ${name}`); return adapter[name](...args); };
+  return { navigate: (options) => adapter.navigate(options), click: (target) => adapter.click(target), type: (value) => adapter.type(value), screenshot: (options) => adapter.screenshot(options), html: () => adapter.html(), text: () => adapter.text(), title: () => adapter.title(), scrolltobottom: (options) => adapter.scrolltobottom(options), executecommands: (commands) => adapter.executecommands(commands), fill: optional("fill"), key: optional("key"), upload: optional("upload"), snapshot: optional("snapshot"), tabs: optional("tabs"), frames: optional("frames") };
+}

package/browser/context.js

@@ -0,0 +1,52 @@
+/**
+ * browser context tracks tabs and frames without owning a browser implementation.
+ */
+
+/** Creates a serializable browser context registry for an injected browser adapter. */
+export function browsercontext(options = {}) {
+  const sessionid = String(options.sessionid ?? `context${Date.now().toString(36)}`);
+  const tabs = new Map();
+  let activeid = options.activeid === undefined ? undefined : String(options.activeid);
+
+  function opentab(input = {}) {
+    const id = String(input.id ?? `tab${tabs.size + 1}`);
+    const tab = { id, url: String(input.url ?? "about:blank"), title: String(input.title ?? ""), active: Boolean(input.active), frames: new Map() };
+    tabs.set(id, tab);
+    if (tab.active || activeid === undefined) { activeid = id; tab.active = true; }
+    return describetab(tab);
+  }
+
+  function closetab(id) {
+    const key = String(id);
+    if (!tabs.delete(key)) return false;
+    if (activeid === key) activeid = tabs.keys().next().value;
+    if (activeid && tabs.has(activeid)) tabs.get(activeid).active = true;
+    return true;
+  }
+
+  function setactive(id) {
+    const key = String(id);
+    const tab = tabs.get(key);
+    if (!tab) throw new Error(`unknown browser tab: ${key}`);
+    for (const item of tabs.values()) item.active = false;
+    tab.active = true;
+    activeid = key;
+    return describetab(tab);
+  }
+
+  function openframe(tabid, input = {}) {
+    const tab = requiretab(tabid);
+    const id = String(input.id ?? `frame${tab.frames.size + 1}`);
+    tab.frames.set(id, { id, url: String(input.url ?? tab.url), parentid: input.parentid === undefined ? undefined : String(input.parentid), name: String(input.name ?? "") });
+    return { ...tab.frames.get(id) };
+  }
+
+  function closeframe(tabid, frameid) { return Boolean(requiretab(tabid).frames.delete(String(frameid))); }
+  function activetab() { return activeid === undefined ? undefined : describetab(requiretab(activeid)); }
+  function describe() { return { sessionid, activeid, tabs: [...tabs.values()].map(describetab) }; }
+
+  return { sessionid, opentab, closetab, setactive, openframe, closeframe, activetab, describe };
+
+  function requiretab(id) { const tab = tabs.get(String(id)); if (!tab) throw new Error(`unknown browser tab: ${id}`); return tab; }
+  function describetab(tab) { return { id: tab.id, url: tab.url, title: tab.title, active: tab.active, frames: [...tab.frames.values()].map((frame) => ({ ...frame })) }; }
+}

package/browser/fingerprint.js

@@ -0,0 +1,12 @@
+/**
+ * fingerprint profiles keep session settings coherent without modifying browser internals.
+ */
+const profiles = Object.freeze({
+  desktopwindows: { os: "windows", platform: "Win32", browser: "chrome", locale: "en-US", timezone: "America/New_York", touch: false, devicepixelratio: 1 },
+  desktopmacos: { os: "macos", platform: "MacIntel", browser: "safari", locale: "en-US", timezone: "America/Los_Angeles", touch: false, devicepixelratio: 2 },
+  mobileandroid: { os: "android", platform: "Linux armv8l", browser: "chrome", locale: "en-US", timezone: "America/Chicago", touch: true, devicepixelratio: 2.75 }
+});
+
+export function fingerprintprofile(name = "desktopwindows", overrides = {}) { return { ...(profiles[name] ?? profiles.desktopwindows), ...overrides, name }; }
+export function fingerprintvalidate(profile) { return Boolean(profile?.os && profile?.platform && profile?.browser && profile?.locale && profile?.timezone && typeof profile.touch === "boolean"); }
+export function fingerprintfor(sessionid, options = {}) { const names = options.profiles ?? Object.keys(profiles); const index = [...String(sessionid)].reduce((sum, value) => sum + value.charCodeAt(0), 0) % names.length; return fingerprintprofile(names[index], options.overrides); }

package/browser/index.js

@@ -0,0 +1,10 @@
+/**
+ * browser surface exports vendor-neutral context, snapshots, actions and recording contracts.
+ */
+export * from "./agent.js";
+export * from "./actions.js";
+export * from "./context.js";
+export * from "./fingerprint.js";
+export * from "./recorder.js";
+export * from "./session.js";
+export * from "./snapshot.js";

package/browser/recorder.js

@@ -0,0 +1,15 @@
+/**
+ * browser recorder captures action and snapshot boundaries for deterministic replay.
+ */
+
+/** Creates a bounded recorder that links actions to the snapshot used before execution. */
+export function actionrecorder(options = {}) {
+  const startedat = Number(options.startedat ?? Date.now());
+  const events = [];
+  let lastsnapshotid;
+  function snapshot(snapshot) { lastsnapshotid = snapshot?.snapshotid; events.push({ type: "snapshot", t: Date.now() - startedat, snapshotid: lastsnapshotid, tabid: snapshot?.tabid, frameid: snapshot?.frameid }); return snapshot; }
+  function action(input = {}) { const event = { type: "action", t: Date.now() - startedat, action: String(input.action), snapshotid: input.snapshotid ?? lastsnapshotid, tabid: input.tabid, frameid: input.frameid, payload: input.payload ?? {} }; events.push(event); return { ...event }; }
+  function list() { return events.map((event) => ({ ...event, payload: { ...event.payload } })); }
+  function manifest() { return { version: 1, startedat, eventcount: events.length, lastsnapshotid, events: list() }; }
+  return { snapshot, action, list, manifest };
+}

package/browser/session.js

@@ -0,0 +1,19 @@
+/**
+ * browser sessions bind one fingerprint to one proxy and one event recorder.
+ */
+import { fingerprintfor, fingerprintvalidate } from "./fingerprint.js";
+
+export function browsersession(options = {}) {
+  const id = options.id ?? `browsersession${Date.now().toString(36)}`;
+  const fingerprint = options.fingerprint ?? fingerprintfor(id, options);
+  if (!fingerprintvalidate(fingerprint)) throw new TypeError("browser fingerprint is incoherent");
+  const events = [];
+  return {
+    id,
+    fingerprint,
+    proxy: options.proxy,
+    record(event) { if (!event || !Number.isFinite(event.t) || event.t < 0 || typeof event.type !== "string") throw new TypeError("browser event is invalid"); events.push({ ...event }); return event; },
+    events() { return events.map((event) => ({ ...event })); },
+    manifest() { return { id, fingerprint: { ...fingerprint }, proxy: options.proxy?.id ?? options.proxy, eventcount: events.length }; }
+  };
+}

package/browser/snapshot.js

@@ -0,0 +1,57 @@
+/**
+ * browser snapshots turn page state into bounded serializable data with stable references.
+ */
+
+/** Creates a validated page snapshot for browser, MCP and extension adapters. */
+export function pagesnapshot(input = {}) {
+  if (!input || typeof input !== "object") throw new TypeError("page snapshot must be an object");
+  const snapshot = {
+    version: 1,
+    snapshotid: String(input.snapshotid ?? `snapshot${Date.now().toString(36)}`),
+    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 ?? "").slice(0, input.maxtext ?? 100000),
+    elements: normalizeelements(input.elements)
+  };
+  if (!snapshot.snapshotid || !snapshot.url) throw new TypeError("page snapshot requires snapshotid and url");
+  return snapshot;
+}
+
+/** Creates an element reference bound to a snapshot and browser context. */
+export function snapshotref(snapshot, input = {}) {
+  const current = pagesnapshot(snapshot);
+  const ref = String(input.ref ?? "");
+  if (!current.elements.some((element) => element.ref === ref)) throw new TypeError(`snapshot reference not found: ${ref}`);
+  return { version: 1, snapshotid: current.snapshotid, tabid: current.tabid, frameid: current.frameid, ref };
+}
+
+/** Throws a stable error when an action uses a reference from a previous page state. */
+export function assertfreshsnapshot(snapshot, reference) {
+  const current = pagesnapshot(snapshot);
+  if (!reference || reference.snapshotid !== current.snapshotid || (reference.tabid !== undefined && reference.tabid !== current.tabid) || (reference.frameid !== undefined && reference.frameid !== current.frameid)) {
+    const error = new Error("browser snapshot is stale");
+    error.code = "STALE_SNAPSHOT";
+    error.retryable = true;
+    throw error;
+  }
+  return true;
+}
+
+/** Computes additions, removals and changed labels between two snapshots. */
+export function snapshotdiff(previous, current) {
+  const before = pagesnapshot(previous);
+  const after = pagesnapshot(current);
+  const oldmap = new Map(before.elements.map((element) => [element.ref, element]));
+  const newmap = new Map(after.elements.map((element) => [element.ref, element]));
+  const added = after.elements.filter((element) => !oldmap.has(element.ref));
+  const removed = before.elements.filter((element) => !newmap.has(element.ref));
+  const changed = after.elements.filter((element) => oldmap.has(element.ref) && JSON.stringify(oldmap.get(element.ref)) !== JSON.stringify(element));
+  return { from: before.snapshotid, to: after.snapshotid, added, removed, changed };
+}
+
+function normalizeelements(elements) {
+  if (!Array.isArray(elements)) return [];
+  return elements.slice(0, 500).map((element, index) => ({ ref: String(element?.ref ?? `e${index + 1}`), role: String(element?.role ?? "generic"), name: String(element?.name ?? "").trim().slice(0, 200), value: element?.value === undefined ? undefined : String(element.value).slice(0, 500), disabled: Boolean(element?.disabled) }));
+}

package/captcha/contract.js

@@ -0,0 +1,15 @@
+/**
+ * captcha contracts separate detection and evidence from any solver provider.
+ */
+export const captchatypes = Object.freeze(["hcaptcha", "turnstile", "recaptcha", "unknown"]);
+
+export function captchacontract(options = {}) {
+  const detect = options.detect ?? (() => ({ kind: "unknown", detected: false }));
+  const solve = options.solve;
+  return {
+    async detect(context) { const result = await detect(context); return { kind: captchatypes.includes(result.kind) ? result.kind : "unknown", detected: Boolean(result.detected), sitekey: result.sitekey, evidenceurl: result.evidenceurl }; },
+    async request(context) { return { status: "reviewrequired", kind: context.kind ?? "unknown", message: "captcha requires explicit human or external solver review", context }; },
+    async solve(context) { if (typeof solve !== "function") return { status: "unavailable", reason: "no external solver configured" }; const result = await solve(context); return { status: result?.passed ? "passed" : "failed", passed: Boolean(result?.passed), solver: result?.solver ?? "external", token: result?.token, evidenceurl: result?.evidenceurl }; },
+    assert(result) { if (!result?.passed) throw new Error("captcha assertion failed"); return result; }
+  };
+}

package/captcha/evidence.js

@@ -0,0 +1,9 @@
+/**
+ * captcha evidence stores references and hashes, never raw secrets or tokens by default.
+ */
+import { sha256 } from "../core/hash.js";
+
+export function evidence(options = {}) {
+  const payload = options.data instanceof Uint8Array ? options.data : options.data ? new TextEncoder().encode(String(options.data)) : null;
+  return { kind: options.kind ?? "unknown", passed: Boolean(options.passed), solver: options.solver ?? "manual", evidenceurl: options.evidenceurl, sha256: payload ? sha256(payload) : options.sha256, createdat: options.createdat ?? Date.now(), metadata: { ...(options.metadata ?? {}) } };
+}

package/captcha/guard.js

@@ -0,0 +1,10 @@
+/**
+ * captcha guard blocks silent automation and records a review event for audit.
+ */
+export function captchaguard(options = {}) {
+  const events = [];
+  return {
+    async check(context) { const result = await options.contract.detect(context); if (!result.detected) return { allowed: true, result }; const event = { type: "captcha.detected", at: Date.now(), kind: result.kind, sitekey: result.sitekey }; events.push(event); return { allowed: false, result, event, action: "reviewrequired" }; },
+    events() { return events.map((event) => ({ ...event })); }
+  };
+}

package/cli/main.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * the cli keeps local execution explicit and leaves remote dispatch to adapters.
+ */
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { argv } from "node:process";
+import { eventbus } from "../core/events.js";
+import { localmemory } from "../memory/bridge.js";
+import { inprocess } from "../runners/inprocess.js";
+import { scheduler } from "../runners/scheduler.js";
+import { engine } from "../runtime/engine.js";
+import { localstorage } from "../storage/local.js";
+import { mcpserver } from "../mcp/server.js";
+import { modecatalog } from "../modes/matrix.js";
+
+/** Runs one CLI command and keeps external services behind adapters. */
+export async function main(args = argv.slice(2)) {
+  const command = args[0] ?? "help";
+  /* Help stays short and lists only stable local commands. */
+  if (["help", "--help", "-h"].includes(command)) { console.log("saddle <command>\n\ncommands\n  help\n  modes\n  runexample\n  mcp"); return; }
+  if (command === "modes") { console.log(JSON.stringify(modecatalog(), null, 2)); return; }
+  if (command === "runexample") {
+    const root = await mkdtemp(join(tmpdir(), "saddlecli"));
+    const events = eventbus();
+    const run = engine({ storage: localstorage(root), memory: localmemory(), scheduler: scheduler([inprocess()]), events });
+    const result = await run.run({ name: "cliexample", input: { hello: "saddle" } }, ({ job }) => ({ jobid: job.id, ok: true, message: "storage to working set to result" }));
+    console.log(JSON.stringify({ jobid: result.job.id, artifact: result.artifact, events: events.all().length }, null, 2));
+    return;
+  }
+  if (command === "mcp") { const server = mcpserver({ scrape: async (url) => ({ url, links: [] }) }); console.log(JSON.stringify({ tools: server.listtools() }, null, 2)); return; }
+  throw new Error(`unknown command: ${command}`);
+}
+
+if (import.meta.url === `file://${argv[1]}`) main().catch((error) => { console.error(error); process.exitCode = 1; });

package/core/errors.js

@@ -0,0 +1,37 @@
+/**
+ * typed engine errors keep recovery decisions explicit.
+ */
+export const errorcodes = Object.freeze({
+  invalidinput: "INVALID_INPUT",
+  artifactnotfound: "ARTIFACT_NOT_FOUND",
+  storagefailure: "STORAGE_FAILURE",
+  runnerunavailable: "RUNNER_UNAVAILABLE",
+  jobfailed: "JOB_FAILED",
+  sessioninvalid: "SESSION_INVALID"
+});
+
+export function saddleerror(message, options = {}) {
+  const error = new Error(message, { cause: options.cause });
+  error.name = "saddleerror";
+  error.code = options.code ?? errorcodes.jobfailed;
+  error.retryable = options.retryable ?? false;
+  error.details = options.details ?? {};
+  return error;
+}
+
+export function validationerror(message, details = {}) {
+  return saddleerror(message, { code: errorcodes.invalidinput, details });
+}
+
+export function artifactnotfound(key) {
+  return saddleerror(`artifact not found: ${key}`, { code: errorcodes.artifactnotfound, details: { key } });
+}
+
+export function runnerunavailable(jobid) {
+  return saddleerror(`no runner is available for job ${jobid}`, { code: errorcodes.runnerunavailable, retryable: true, details: { jobid } });
+}
+
+export function aserror(error, jobid) {
+  if (error?.name === "saddleerror") return error;
+  return saddleerror(`job ${jobid} failed`, { code: errorcodes.jobfailed, cause: error, details: { jobid } });
+}

package/core/events.js

@@ -0,0 +1,21 @@
+/**
+ * append only events are the small protocol shared by adapters.
+ */
+export const eventtypes = Object.freeze([
+  "jobqueued",
+  "jobpreparing",
+  "runnerselected",
+  "jobrunning",
+  "jobsyncing",
+  "storagecommitted",
+  "jobcompleted",
+  "jobfailed"
+]);
+
+export function eventbus() {
+  const recorded = [];
+  return {
+    emit(event) { recorded.push(Object.freeze({ ...event })); },
+    all() { return [...recorded]; }
+  };
+}