@spredr/sdk 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,969 @@
+// src/agent.ts
+import { createServer } from "node:http";
+
+// src/errors.ts
+var SpredrError = class extends Error {
+  /** The HTTP status ai answered with; 0 when no answer came. */
+  status;
+  /** ai's trace id for this request, to quote when you write to spredr. */
+  trace;
+  constructor(status, message, trace = "") {
+    super(message);
+    this.name = new.target.name;
+    this.status = status;
+    this.trace = trace;
+  }
+};
+var BadRequestError = class extends SpredrError {
+};
+var AuthenticationError = class extends SpredrError {
+};
+var PermissionDeniedError = class extends SpredrError {
+};
+var NotFoundError = class extends SpredrError {
+};
+var ConflictError = class extends SpredrError {
+};
+var RateLimitError = class extends SpredrError {
+  /** Seconds ai asked to wait, when it said. */
+  retryAfter;
+  constructor(status, message, trace = "", retryAfter = null) {
+    super(status, message, trace);
+    this.retryAfter = retryAfter;
+  }
+};
+var InternalServerError = class extends SpredrError {
+};
+var ConnectionError = class extends SpredrError {
+};
+var TimeoutError = class extends ConnectionError {
+};
+var TaskError = class extends Error {
+  task;
+  constructor(task) {
+    super(task.status === "failed" ? task.error || "The task failed." : task.status === "paused" ? "The task waits for an answer: see pauses()." : `The task is ${task.status}.`);
+    this.name = "TaskError";
+    this.task = task;
+  }
+};
+var BY_STATUS = /* @__PURE__ */ new Map([[400, BadRequestError], [401, AuthenticationError], [403, PermissionDeniedError], [404, NotFoundError], [409, ConflictError]]);
+function errorFor(status, message, trace, retryAfter) {
+  if (status === 429) return new RateLimitError(status, message, trace, retryAfter);
+  if (status >= 500) return new InternalServerError(status, message, trace);
+  const Class = BY_STATUS.get(status) ?? SpredrError;
+  return new Class(status, message, trace);
+}
+
+// src/sign.ts
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign, verify } from "node:crypto";
+var HEADERS = { from: "x-spredr-from", time: "x-spredr-time", nonce: "x-spredr-nonce", signature: "x-spredr-signature" };
+var AI_SIGNER = "ai";
+var SKEW_MS = 5 * 6e4;
+var NONCE = /^[0-9a-f]{32}$/;
+var privateKeyOf = (base64) => createPrivateKey({ key: Buffer.from(base64, "base64"), format: "der", type: "pkcs8" });
+var publicKeyOf = (base64) => createPublicKey({ key: Buffer.from(base64, "base64"), format: "der", type: "spki" });
+function newKeys() {
+  const pair = generateKeyPairSync("ed25519");
+  return { privateKey: pair.privateKey.export({ format: "der", type: "pkcs8" }).toString("base64"), publicKey: pair.publicKey.export({ format: "der", type: "spki" }).toString("base64") };
+}
+var bytesToSign = (method, path, time, nonce, body) => Buffer.from([method.toUpperCase(), path, time, nonce, createHash("sha256").update(body).digest("hex")].join("\n"));
+function signedHeaders(from, key, method, path, body) {
+  const time = (/* @__PURE__ */ new Date()).toISOString();
+  const nonce = randomBytes(16).toString("hex");
+  return { [HEADERS.from]: from, [HEADERS.time]: time, [HEADERS.nonce]: nonce, [HEADERS.signature]: sign(null, bytesToSign(method, path, time, nonce, body), key).toString("base64") };
+}
+function aiVerifier(aiPublicKey) {
+  const key = publicKeyOf(aiPublicKey);
+  const seen = /* @__PURE__ */ new Map();
+  return (request) => {
+    const header = (name) => {
+      const value = request.headers[name];
+      return typeof value === "string" ? value : "";
+    };
+    const time = header(HEADERS.time);
+    const nonce = header(HEADERS.nonce);
+    const at = Date.parse(time);
+    if (header(HEADERS.from) !== AI_SIGNER || !Number.isFinite(at) || Math.abs(Date.now() - at) > SKEW_MS || !NONCE.test(nonce) || seen.has(nonce)) return false;
+    let genuine = false;
+    try {
+      genuine = verify(null, bytesToSign(request.method, request.path, time, nonce, request.body), key, Buffer.from(header(HEADERS.signature), "base64"));
+    } catch {
+      genuine = false;
+    }
+    if (!genuine) return false;
+    const now = Date.now();
+    for (const [old, until] of seen) {
+      if (until > now) break;
+      seen.delete(old);
+    }
+    seen.set(nonce, now + 2 * SKEW_MS);
+    return true;
+  };
+}
+
+// src/http.ts
+var STREAM_TIMEOUT_MS = 11 * 6e4;
+var TIMEOUT_MS = 75e3;
+var MAX_RETRIES = 2;
+var RETRY_DELAY_MS = 500;
+var MAX_DELAY_MS = 8e3;
+var MAX_RETRY_AFTER_S = 60;
+var REPEATABLE = /* @__PURE__ */ new Set(["GET", "PUT", "DELETE"]);
+var fieldOf = (parsed, name) => typeof parsed === "object" && parsed !== null && name in parsed && typeof parsed[name] === "string" ? String(parsed[name]) : "";
+function parseJson(raw) {
+  try {
+    return { ok: true, value: raw ? JSON.parse(raw) : null };
+  } catch {
+    return { ok: false };
+  }
+}
+function retryAfterOf(response) {
+  const header = response.headers.get("retry-after");
+  if (!header) return null;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds);
+  const at = Date.parse(header);
+  return Number.isFinite(at) ? Math.max(0, (at - Date.now()) / 1e3) : null;
+}
+async function failureOf(response) {
+  const raw = await response.text();
+  const parsed = parseJson(raw);
+  const message = (parsed.ok ? fieldOf(parsed.value, "error") : "") || raw.slice(0, 300).trim() || `HTTP ${response.status}`;
+  return errorFor(response.status, message, parsed.ok ? fieldOf(parsed.value, "trace") : "", retryAfterOf(response));
+}
+function client(base, auth, options = {}) {
+  const root = base.replace(/\/+$/, "");
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+  const maxRetries = Math.max(0, options.maxRetries ?? MAX_RETRIES);
+  const firstDelay = options.retryDelayMs ?? RETRY_DELAY_MS;
+  const headersFor = (method, path, text, json) => {
+    const headers = { accept: json ? "application/json" : "*/*", ...typeof text === "string" && text ? { "content-type": "application/json" } : {} };
+    if ("token" in auth) headers.authorization = `Bearer ${auth.token}`;
+    else Object.assign(headers, signedHeaders(auth.from, auth.key, method, path, text));
+    return headers;
+  };
+  const waitBefore = (tryNumber, retryAfter) => {
+    const backoff = Math.min(MAX_DELAY_MS, firstDelay * 2 ** tryNumber) * (0.75 + Math.random() * 0.5);
+    return new Promise((resolve) => setTimeout(resolve, retryAfter === null ? backoff : retryAfter * 1e3));
+  };
+  async function send(method, path, text, json, repeatable, extra = {}, waitMs = timeoutMs) {
+    for (let tryNumber = 0; ; tryNumber++) {
+      const last = tryNumber >= maxRetries;
+      let response;
+      try {
+        response = await fetcher(`${root}${path}`, { method, headers: { ...headersFor(method, path, text, json), ...extra }, ...text.length ? { body: typeof text === "string" ? text : new Uint8Array(text) } : {}, signal: AbortSignal.timeout(waitMs) });
+      } catch (error) {
+        const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+        if (!repeatable || last) {
+          throw timedOut ? new TimeoutError(0, `ai did not answer in ${timeoutMs} ms (${method} ${path}).`) : new ConnectionError(0, `ai could not be reached (${method} ${path}): ${error instanceof Error ? error.message : String(error)}`);
+        }
+        await waitBefore(tryNumber, null);
+        continue;
+      }
+      if (response.ok || last) return response;
+      const retryAfter = retryAfterOf(response);
+      const again = response.status === 429 ? retryAfter !== null && retryAfter <= MAX_RETRY_AFTER_S : repeatable && (response.status === 408 || response.status >= 500);
+      if (!again) return response;
+      await response.body?.cancel();
+      await waitBefore(tryNumber, retryAfter);
+    }
+  }
+  return {
+    async text(method, path) {
+      const response = await send(method, path, "", false, true);
+      if (!response.ok) throw await failureOf(response);
+      return response.text();
+    },
+    async call(method, path, body, callOptions = {}) {
+      const text = body === void 0 ? "" : JSON.stringify(body);
+      const response = await send(method, path, text, true, callOptions.idempotent ?? REPEATABLE.has(method));
+      if (!response.ok) throw await failureOf(response);
+      const parsed = parseJson(await response.text());
+      if (!parsed.ok) throw new SpredrError(response.status, `ai answered ${method} ${path} with something that is not JSON.`);
+      return parsed.value;
+    },
+    async upload(path, data, headers) {
+      const response = await send("PUT", path, data, true, true, { "content-type": "application/octet-stream", ...headers });
+      if (!response.ok) throw await failureOf(response);
+      const parsed = parseJson(await response.text());
+      if (!parsed.ok) throw new SpredrError(response.status, `ai answered PUT ${path} with something that is not JSON.`);
+      return parsed.value;
+    },
+    async *events(path, lastId) {
+      const response = await send("GET", path, "", false, true, { accept: "text/event-stream", ...lastId ? { "last-event-id": String(lastId) } : {} }, STREAM_TIMEOUT_MS);
+      if (!response.ok) throw await failureOf(response);
+      if (!response.body) return;
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffered = "";
+      for (; ; ) {
+        const { value, done } = await reader.read();
+        if (done) return;
+        buffered += decoder.decode(value, { stream: true });
+        for (let end = buffered.indexOf("\n\n"); end >= 0; end = buffered.indexOf("\n\n")) {
+          const block = buffered.slice(0, end);
+          buffered = buffered.slice(end + 2);
+          const field = (name) => block.split("\n").filter((line) => line.startsWith(`${name}:`)).map((line) => line.slice(name.length + 1).trimStart()).join("\n");
+          const data = field("data");
+          if (data) yield { id: Number(field("id")) || 0, event: field("event") || "message", data };
+        }
+      }
+    },
+    async download(path) {
+      const response = await send("GET", path, "", false, true);
+      if (!response.ok) throw await failureOf(response);
+      return { data: new Uint8Array(await response.arrayBuffer()), type: response.headers.get("content-type") ?? "application/octet-stream", headers: response.headers };
+    }
+  };
+}
+function query(values) {
+  const pairs = Object.entries(values).filter((pair) => pair[1] !== void 0).map(([key, value]) => `${key}=${encodeURIComponent(String(value))}`);
+  return pairs.length ? `?${pairs.join("&")}` : "";
+}
+
+// src/usage.ts
+var isRecord = (value) => typeof value === "object" && value !== null;
+var numberAt = (from, ...names) => {
+  for (const name of names) {
+    const value = from[name];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return void 0;
+};
+function usageOf(answer) {
+  if (!isRecord(answer)) return {};
+  const response = isRecord(answer.response) ? answer.response : {};
+  const model = typeof answer.model === "string" ? answer.model : typeof response.modelId === "string" ? response.modelId : void 0;
+  const usage = isRecord(answer.usage) ? answer.usage : {};
+  const tokensIn = numberAt(usage, "input_tokens", "prompt_tokens", "inputTokens", "promptTokens");
+  const tokensOut = numberAt(usage, "output_tokens", "completion_tokens", "outputTokens", "completionTokens");
+  return { ...model ? { model } : {}, ...tokensIn === void 0 ? {} : { tokensIn }, ...tokensOut === void 0 ? {} : { tokensOut } };
+}
+
+// src/context.ts
+function sameJson(a, b) {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && sameJson(Reflect.get(a, key), Reflect.get(b, key)));
+}
+var PAUSED = /* @__PURE__ */ Symbol("paused");
+var MAX_MEMO_BYTES = 256 * 1024;
+var failedStep = (error) => ({ ok: false, detail: error instanceof Error ? error.message.slice(0, 300) : "failed" });
+function memoOf(value) {
+  if (value === void 0) return {};
+  try {
+    const text = JSON.stringify(value);
+    if (text === void 0 || Buffer.byteLength(text) > MAX_MEMO_BYTES) return void 0;
+    return { value: JSON.parse(text) };
+  } catch {
+    return void 0;
+  }
+}
+var STREAM_FLUSH_MS = 150;
+var STREAM_FLUSH_CHARS = 2e3;
+function contextFor(client2, delivery) {
+  const { task } = delivery;
+  const call = client2.call.bind(client2);
+  const began = Date.now();
+  const path = `/agent/tasks/${task.id}`;
+  let pending = "";
+  let flushTimer = null;
+  let sending = Promise.resolve();
+  const flushNow = () => {
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = null;
+    if (pending) {
+      const text = pending;
+      pending = "";
+      sending = sending.then(() => call("POST", `${path}/delta`, { attempt: task.attempt, text })).then(() => void 0, () => void 0);
+    }
+    return sending;
+  };
+  const report = (step) => call("POST", `${path}/steps`, { attempt: task.attempt, steps: [step] }).catch(() => void 0);
+  const answers = delivery.answers ?? (delivery.resume ? [delivery.resume] : []);
+  const memos = delivery.memo ?? [];
+  let nextAnswer = 0;
+  let nextMemo = 0;
+  const replayed = (key) => {
+    const entry = memos[nextMemo];
+    if (!entry) return { hit: false };
+    if (entry.key !== key) {
+      nextMemo = memos.length;
+      return { hit: false };
+    }
+    nextMemo += 1;
+    return { hit: true, value: entry.has ? entry.value : void 0 };
+  };
+  async function once(kind, key, name, work, read2) {
+    const memo = replayed(`${kind}:${key}`);
+    if (memo.hit) return memo.value;
+    const started = Date.now();
+    const at = started - began;
+    try {
+      const value = await work();
+      const kept = memoOf(value);
+      await report({ kind, name: typeof name === "string" ? name : name(value), ms: Date.now() - started, at, ...read2(value), ...kept ? { memo: { key: `${kind}:${key}`, ...kept } } : {} });
+      return value;
+    } catch (error) {
+      await report({ kind, name: typeof name === "string" ? name : kind, ms: Date.now() - started, at, ...failedStep(error) });
+      throw error;
+    }
+  }
+  const tenant = task.tenant ?? "";
+  const thread = task.thread ?? null;
+  return {
+    task,
+    tenant,
+    thread,
+    lessons: delivery.lessons.items,
+    trial: task.trial,
+    async ask(action, question, extra = {}) {
+      const answer = answers[nextAnswer];
+      const sameAsked = answer !== void 0 && answer.action === action && (answer.question === void 0 || answer.question === question) && (answer.data === void 0 || sameJson(answer.data, extra.data ?? null));
+      if (answer && sameAsked) {
+        nextAnswer += 1;
+        return answer;
+      }
+      nextAnswer = answers.length;
+      const { pause } = await call("POST", `${path}/pause`, { attempt: task.attempt, action, question, ...extra });
+      if (pause.status === "answered" && pause.answer) return pause.answer;
+      throw PAUSED;
+    },
+    stream(text) {
+      if (!text) return;
+      pending += text;
+      if (pending.length >= STREAM_FLUSH_CHARS) void flushNow();
+      else if (!flushTimer) flushTimer = setTimeout(() => void flushNow(), STREAM_FLUSH_MS);
+    },
+    flush: () => flushNow(),
+    async progress(data) {
+      await call("POST", `${path}/progress`, { attempt: task.attempt, data });
+    },
+    async step(step) {
+      await call("POST", `${path}/steps`, { attempt: task.attempt, steps: [step] });
+    },
+    track: (kind, name, work, usage) => once(kind, name, name, work, (value) => usage ? usage(value) : {}),
+    model: (work, name) => once("model", name ?? "", (value) => name ?? usageOf(value).model ?? "model", work, usageOf),
+    later: (kind, input, at, key) => once("other", `later:${kind}`, `later ${kind}`, async () => {
+      await call("POST", "/agent/tasks", { kind, input, at: new Date(at).toISOString(), ...key ? { key } : {}, ...tenant ? { tenant } : {}, ...thread ? { thread } : {} }, { idempotent: Boolean(key) });
+    }, () => ({})),
+    files: delivery.files ?? [],
+    async file(idOrName) {
+      const found = (delivery.files ?? []).find((one) => one.id === idOrName || one.name === idOrName);
+      if (!found) throw new Error(`No file \xAB${idOrName}\xBB in this task's session: its files are ${(delivery.files ?? []).map((one) => one.name).join(", ") || "none"}.`);
+      const got = await client2.download(`/agent/files/${encodeURIComponent(found.id)}${query({ task: task.id })}`);
+      return { data: got.data, type: got.type, name: found.name };
+    },
+    memory: {
+      remember: (scope, text, extra = {}) => once("memory", `remember:${scope}`, "remember", async () => {
+        const answer = await call("PUT", "/agent/memory", { task: task.id, scope, text, ...extra }, { idempotent: Boolean(extra.key) });
+        if (!answer.kept) console.warn(`memory: ${answer.why ?? "this fact was not kept"}`);
+        return answer.fact;
+      }, () => ({})),
+      async recall(options) {
+        return (await call("GET", `/agent/memory${query({ ...options, task: task.id })}`)).facts;
+      },
+      async forget(id) {
+        await call("DELETE", `/agent/memory/${id}${query({ task: task.id })}`);
+      }
+    }
+  };
+}
+
+// src/schema.ts
+async function validated(schema, input) {
+  const result = await schema["~standard"].validate(input);
+  if (result.issues === void 0) return result.value;
+  const where = (issue) => issue.path?.length ? `${issue.path.map((part) => String(typeof part === "object" ? part.key : part)).join(".")}: ` : "";
+  throw new Error(`The input does not match: ${result.issues.map((issue) => `${where(issue)}${issue.message}`).join("; ")}`);
+}
+
+// src/tag.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var working = new AsyncLocalStorage();
+var METHODS = ["log", "info", "warn", "error", "debug"];
+var tagged = false;
+function currentTask() {
+  return working.getStore() ?? null;
+}
+function asTask(taskId, work) {
+  return working.run(taskId, work);
+}
+function tagConsole() {
+  if (tagged) return;
+  tagged = true;
+  for (const method of METHODS) {
+    const print = console[method].bind(console);
+    console[method] = (...parts) => {
+      const id = working.getStore();
+      if (!id) return print(...parts);
+      const [first, ...rest] = parts;
+      return typeof first === "string" ? print(`[${id}] ${first}`, ...rest) : print(`[${id}]`, ...parts);
+    };
+  }
+}
+
+// src/agent.ts
+var MAX_BODY = 4 * 1024 * 1024;
+var HELLO_TRIES = 30;
+var SHUTDOWN_GRACE_MS = 25e3;
+function read(request) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let size = 0;
+    request.on("data", (chunk) => {
+      size += chunk.length;
+      if (size <= MAX_BODY) chunks.push(chunk);
+    });
+    request.on("end", () => resolve(size <= MAX_BODY ? Buffer.concat(chunks) : null));
+    request.on("error", () => resolve(null));
+  });
+}
+var need = (value, name) => {
+  const found = value || process.env[name];
+  if (!found) throw new Error(`${name} is not set: register this service as an agent on spredr (it writes the variables), or pass the options.`);
+  return found;
+};
+var Agent = class {
+  #manifest;
+  #id;
+  #client;
+  #verify;
+  #handlers = /* @__PURE__ */ new Map();
+  #taskPath = "/spredr/task";
+  #log;
+  #graceMs;
+  #running = /* @__PURE__ */ new Set();
+  #server = null;
+  #closing = false;
+  constructor(options = {}) {
+    const { id, key, ai, aiKey, fetch, timeoutMs, maxRetries, retryDelayMs, log, shutdownGraceMs, tagLogs, ...manifest } = options;
+    if (tagLogs !== false) tagConsole();
+    this.#manifest = manifest;
+    const clientOptions = { ...fetch ? { fetch } : {}, ...timeoutMs === void 0 ? {} : { timeoutMs }, ...maxRetries === void 0 ? {} : { maxRetries }, ...retryDelayMs === void 0 ? {} : { retryDelayMs } };
+    this.#id = need(id, "SPREDR_AGENT_ID");
+    this.#client = client(need(ai, "SPREDR_AI_URL"), { from: this.#id, key: privateKeyOf(need(key, "SPREDR_AGENT_KEY")) }, clientOptions);
+    this.#verify = aiVerifier(need(aiKey, "SPREDR_AI_KEY"));
+    this.#log = log === false ? () => void 0 : log ?? ((line) => console.log(`spredr agent \xB7 ${line}`));
+    this.#graceMs = shutdownGraceMs ?? SHUTDOWN_GRACE_MS;
+  }
+  on(kind, schemaOrHandler, maybeHandler) {
+    const [schema, handler] = typeof schemaOrHandler === "function" ? [null, schemaOrHandler] : [schemaOrHandler, maybeHandler];
+    if (!handler) throw new Error(`on("${kind}"): a handler is missing.`);
+    const run = async (input, ctx) => handler(schema ? await validated(schema, input) : input, ctx);
+    this.#handlers.set(kind, run);
+    return this;
+  }
+  /** Says hello with the manifest (retrying while ai is not reachable yet). */
+  async hello() {
+    const kinds = [...this.#handlers.keys()].filter((kind) => kind !== this.#manifest.judge);
+    const declared = this.#manifest.tasks ?? kinds.map((kind) => ({ kind }));
+    for (let tries = 1; ; tries++) {
+      try {
+        await this.#client.call("POST", "/agent/hello", { ...this.#manifest, tasks: declared }, { idempotent: true });
+        return;
+      } catch (error) {
+        if (tries >= HELLO_TRIES) throw error;
+        await new Promise((resolve) => setTimeout(resolve, 2e3));
+      }
+    }
+  }
+  /** Listens for tasks (and answers /health), then says hello. On SIGTERM it closes and exits. */
+  async listen(port = Number(process.env.PORT ?? 8080)) {
+    const server = createServer((request, response) => void this.#serve(request, response));
+    await new Promise((resolve) => server.listen(port, resolve));
+    this.#server = server;
+    this.#log(`listening on ${port}`);
+    await this.hello();
+    this.#log("said hello to ai");
+    process.once("SIGTERM", () => void this.close().then(() => process.exit(0)));
+    return server;
+  }
+  /** Takes no new task, and waits for the running ones to finish (up to shutdownGraceMs). */
+  async close() {
+    this.#closing = true;
+    const closed = this.#server ? new Promise((resolve) => this.#server?.close(() => resolve())) : Promise.resolve();
+    const finished = Promise.allSettled([...this.#running]);
+    const late = new Promise((resolve) => setTimeout(() => resolve("late"), this.#graceMs).unref());
+    if (await Promise.race([finished, late]) === "late") this.#log(`closing with ${this.#running.size} task(s) still running: ai gives them again`);
+    this.#server?.closeAllConnections();
+    await closed;
+  }
+  /** Where ai sends its tasks: route this path to `handle()` when the agent lives inside your own server. */
+  get path() {
+    return this.#taskPath;
+  }
+  /** One request from ai, answered: for an agent inside a server you already run (Fastify, Express, Hono). Give it the
+   *  raw body exactly as it arrived, since the signature is over those bytes, and send back what it returns. The task's
+   *  handler runs after the answer, as with listen(). Call start() once to say hello, and close() when your server stops. */
+  async handle(request) {
+    const json = (status, body) => ({ status, headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    if (request.method !== "POST" || request.path !== this.#taskPath) return { status: 404, headers: {}, body: "" };
+    if (!this.#verify(request)) return json(401, { error: "not signed by ai" });
+    if (this.#closing) return json(503, { error: "this agent is closing" });
+    const delivery = JSON.parse(typeof request.body === "string" ? request.body : Buffer.from(request.body).toString("utf8"));
+    if (delivery.to && delivery.to.agent !== this.#id) return json(403, { error: "this task is addressed to another agent" });
+    const handler = this.#handlers.get(delivery.task.kind);
+    if (!handler) return json(200, { error: `this agent does not handle \xAB${delivery.task.kind}\xBB tasks` });
+    const running = this.#run(handler, delivery).finally(() => this.#running.delete(running));
+    this.#running.add(running);
+    return { status: 202, headers: {}, body: "" };
+  }
+  /** Says hello to ai, for an agent inside your own server (listen() does this itself). Your server owns the shutdown:
+   *  call close() in it, and the running tasks get their grace. */
+  async start() {
+    await this.hello();
+    this.#log("said hello to ai");
+  }
+  async #serve(request, response) {
+    if (request.url === "/health") {
+      response.writeHead(this.#closing ? 503 : 200).end(this.#closing ? "closing" : "ok");
+      return;
+    }
+    const body = request.method === "POST" && request.url === this.#taskPath ? await read(request) : Buffer.alloc(0);
+    if (!body) {
+      response.writeHead(413).end();
+      return;
+    }
+    const answer = await this.handle({ method: request.method ?? "", path: request.url ?? "", headers: request.headers, body });
+    response.writeHead(answer.status, answer.headers).end(answer.body);
+  }
+  async #run(handler, delivery) {
+    const { task } = delivery;
+    const path = `/agent/tasks/${task.id}`;
+    const beatMs = Math.max(5e3, (this.#manifest.timeoutSeconds ?? 120) * 1e3 / 3);
+    const beat = setInterval(() => void this.#client.call("POST", `${path}/progress`, { attempt: task.attempt, data: { alive: true } }).catch(() => void 0), beatMs).unref();
+    let outcome;
+    const started = Date.now();
+    try {
+      const ctx = contextFor(this.#client, delivery);
+      try {
+        outcome = { result: await asTask(task.id, () => handler(task.input, ctx)) ?? null };
+      } finally {
+        await ctx.flush();
+      }
+    } catch (error) {
+      if (error === PAUSED) {
+        this.#log(`${task.id} ${task.kind} waits for an answer`);
+        return;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      outcome = { error: message.slice(0, 2e3) || "failed" };
+    } finally {
+      clearInterval(beat);
+    }
+    this.#log("error" in outcome ? `${task.id} ${task.kind} failed: ${outcome.error.slice(0, 200)}` : `${task.id} ${task.kind} done in ${((Date.now() - started) / 1e3).toFixed(1)} s`);
+    try {
+      await this.#client.call("POST", `${path}/result`, { attempt: task.attempt, ...outcome }, { idempotent: true });
+    } catch (error) {
+      if (error instanceof ConflictError) return;
+      this.#log(`could not report ${task.id}: ${error instanceof Error ? error.message : String(error)}; ai gives it again when its lease ends`);
+    }
+  }
+  /** What apps said about this agent's tasks after `after` (a feedback seq): what it learns from. */
+  async feedback(after = 0) {
+    return (await this.#client.call("GET", `/agent/feedback${query({ after: after || void 0 })}`)).feedback;
+  }
+  /** Proposes a lesson to its owner, drawn from feedback. */
+  async propose(text, why = "", sources = []) {
+    await this.#client.call("POST", "/agent/lessons", { text, why, sources });
+  }
+};
+
+// src/tasks.ts
+var MAX_WAIT_S = 60;
+var Tasks = class {
+  #client;
+  #agent;
+  #tenant;
+  constructor(client2, agent, tenant) {
+    this.#client = client2;
+    this.#agent = agent;
+    this.#tenant = tenant;
+  }
+  /** The same agent, working for one tenant: `caller.for('user_42').result('reply', …)`. One agent serves any number
+   *  of tenants at once, each with its own memory, questions, freedom, lessons and caps. */
+  for(tenant) {
+    return new Tenant(this.#client, this.#agent, tenant);
+  }
+  /** Asks the agent for a task. With `wait`, answers once it is done (or when the wait runs out). With a `key`, asking
+   *  again is the same task, so it is safe to retry. */
+  async ask(kind, input, options = {}) {
+    const tenant = options.tenant ?? this.#tenant;
+    const body = {
+      kind,
+      input,
+      ...options.key ? { key: options.key } : {},
+      ...options.wait ? { wait: Math.min(options.wait, MAX_WAIT_S) } : {},
+      ...options.at ? { at: new Date(options.at).toISOString() } : {},
+      ...options.thread ? { thread: options.thread } : {},
+      ...tenant ? { tenant } : {}
+    };
+    return (await this.#client.call("POST", `/agents/${encodeURIComponent(this.#agent)}/tasks`, body, { idempotent: Boolean(options.key) })).task;
+  }
+  /** Asks and waits until the task is done, failed, canceled or paused, however long (in rounds of up to a minute). */
+  async run(kind, input, options = {}) {
+    const task = await this.ask(kind, input, { ...options, wait: MAX_WAIT_S });
+    return this.settle(task.id, options.timeoutMs);
+  }
+  /** Asks, waits, and gives back the result itself; a task that fails, is canceled or waits for an answer throws a
+   *  TaskError carrying the task. */
+  async result(kind, input, options = {}) {
+    const task = await this.run(kind, input, options);
+    if (task.status !== "done") throw new TaskError(task);
+    return task.result;
+  }
+  async get(id, wait = 0) {
+    return (await this.#client.call("GET", `/tasks/${id}${query({ wait: wait || void 0 })}`)).task;
+  }
+  /** Waits for a task to leave the line: done, failed, canceled or paused. */
+  async settle(id, timeoutMs = 10 * 6e4) {
+    const until = Date.now() + timeoutMs;
+    let task = await this.get(id);
+    while ((task.status === "queued" || task.status === "running") && Date.now() < until) task = await this.get(id, MAX_WAIT_S);
+    return task;
+  }
+  async list(options = {}) {
+    const tenant = options.tenant ?? this.#tenant;
+    return (await this.#client.call("GET", `/agents/${encodeURIComponent(this.#agent)}/tasks${query({ ...options, tenant })}`)).tasks;
+  }
+  /** What happened to a task after `after` (its events' seq); with `wait` seconds, waits for the first new one. */
+  async events(id, after = 0, wait = 0) {
+    return (await this.#client.call("GET", `/tasks/${id}/events${query({ after: after || void 0, wait: wait || void 0 })}`)).events;
+  }
+  /** What the agent did inside a task, step by step: its trace. */
+  async steps(id) {
+    return (await this.#client.call("GET", `/tasks/${id}/steps`)).steps;
+  }
+  async cancel(id) {
+    return (await this.#client.call("POST", `/tasks/${id}/cancel`, {})).task;
+  }
+  /** The questions waiting for an answer (a tenant's alone, in a tenant session). */
+  async pauses() {
+    return (await this.#client.call("GET", `/agents/${encodeURIComponent(this.#agent)}/pauses${query({ tenant: this.#tenant })}`)).pauses;
+  }
+  async answer(pauseId, answer) {
+    return (await this.#client.call("POST", `/pauses/${pauseId}/answer`, answer)).pause;
+  }
+  /** How a finished task went: what the agent learns from. A bad one also takes back what it did alone. */
+  async feedback(id, verdict, details = {}) {
+    return (await this.#client.call("POST", `/tasks/${id}/feedback`, { verdict, ...details })).feedback;
+  }
+  /** A task as it happens: each piece of its live answer (the agent's ctx.stream), each of its other events, and last the
+   *  task itself once it is done, paused or failed. A stream that closes before the end is opened again after what
+   *  was seen, so nothing comes twice. */
+  async *stream(id) {
+    let after = 0;
+    for (; ; ) {
+      for await (const sent of this.#client.events(`/tasks/${encodeURIComponent(id)}/stream`, after)) {
+        const parsed = JSON.parse(sent.data);
+        if (sent.event === "task") {
+          yield { type: "end", task: parsed };
+          return;
+        }
+        after = sent.id || after;
+        const event = parsed;
+        const text = typeof event.data === "object" && event.data !== null && !Array.isArray(event.data) && typeof event.data.text === "string" ? event.data.text : "";
+        yield sent.event === "delta" ? { type: "delta", text, seq: event.seq } : { type: "event", event };
+      }
+    }
+  }
+  /** Asks for a task and gives its live answer as it is written: the pieces, then the task. */
+  async *live(kind, input, options = {}) {
+    const task = await this.ask(kind, input, { ...options, wait: 0 });
+    yield* this.stream(task.id);
+  }
+  /** Leaves a file in a session (a thread) for the agent's code to read: a price list, a catalogue, a document. Every
+   *  task of that thread lists it (ctx.files) and the agent downloads it (ctx.file) while it works on one. The same
+   *  name again replaces it. spredr keeps the bytes and never opens them; how the agent reads them is its code's. */
+  async attach(thread, name, data, options = {}) {
+    const tenant = options.tenant ?? this.#tenant;
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const path = `/agents/${encodeURIComponent(this.#agent)}/files${query({ thread, file: name, ...tenant ? { tenant } : {} })}`;
+    return (await this.#client.upload(path, bytes, { "x-spredr-file-type": options.type ?? (typeof data === "string" ? "text/plain" : "application/octet-stream") })).file;
+  }
+  /** A session's files, without their bytes, newest first. */
+  async files(thread, options = {}) {
+    const tenant = options.tenant ?? this.#tenant;
+    return (await this.#client.call("GET", `/agents/${encodeURIComponent(this.#agent)}/files${query({ thread, ...tenant ? { tenant } : {} })}`)).files;
+  }
+  /** Takes a file out of a session. */
+  async detach(thread, name, options = {}) {
+    const tenant = options.tenant ?? this.#tenant;
+    await this.#client.call("DELETE", `/agents/${encodeURIComponent(this.#agent)}/files${query({ thread, file: name, ...tenant ? { tenant } : {} })}`);
+  }
+  /** The client and agent a tenant session works with. */
+  get base() {
+    return { client: this.#client, agent: this.#agent };
+  }
+};
+var Tenant = class extends Tasks {
+  name;
+  #path;
+  constructor(client2, agent, tenant) {
+    super(client2, agent, tenant);
+    this.name = tenant;
+    this.#path = `/agents/${encodeURIComponent(agent)}/tenants/${encodeURIComponent(tenant)}`;
+  }
+  /** What it used today and this month, its caps, the facts it holds and its open questions. */
+  async usage() {
+    return (await this.base.client.call("GET", this.#path)).tenant;
+  }
+  /** Caps this tenant on top of the agent's own; null lifts one. */
+  async setLimits(limits) {
+    return (await this.base.client.call("PUT", `${this.#path}/limits`, limits)).caps;
+  }
+  /** Forgets this tenant whole: its tasks, memory, questions, freedom, lessons and caps. The others stay. */
+  async forget() {
+    return (await this.base.client.call("DELETE", this.#path)).forgotten;
+  }
+  /** How free the agent is with each action for this tenant. */
+  async freedom() {
+    return (await this.base.client.call("GET", `/agents/${encodeURIComponent(this.base.agent)}/freedom${query({ tenant: this.name })}`)).freedom;
+  }
+  /** Lets an action run alone for this tenant (auto), or ask every time (ask): never for another tenant. */
+  async setFreedom(action, level) {
+    return (await this.base.client.call("PUT", `/agents/${encodeURIComponent(this.base.agent)}/freedom/${encodeURIComponent(action)}`, { level, tenant: this.name })).freedom;
+  }
+  /** This tenant's lessons: its own rules, in every one of its tasks from the moment they are written. */
+  async lessons() {
+    return (await this.base.client.call("GET", `/agents/${encodeURIComponent(this.base.agent)}/lessons${query({ tenant: this.name })}`)).lessons;
+  }
+  /** Teaches the agent a rule for this tenant alone («we never book on Sundays»). */
+  async teach(text, why = "") {
+    return (await this.base.client.call("POST", `/agents/${encodeURIComponent(this.base.agent)}/lessons`, { text, why, tenant: this.name })).lesson;
+  }
+  /** Accepts or refuses a lesson the agent proposed for this tenant, or retires one. */
+  async decide(lessonId, decision) {
+    return (await this.base.client.call("POST", `/agents/${encodeURIComponent(this.base.agent)}/lessons/${lessonId}`, { decision })).lesson;
+  }
+};
+
+// src/caller.ts
+function need2(value, name) {
+  const found = value || process.env[name];
+  if (!found) throw new Error(`${name} is not set: link this backend to its agent in spredr (it writes the variables), or pass the options.`);
+  return found;
+}
+var Caller = class _Caller extends Tasks {
+  #id;
+  #verify;
+  constructor(options = {}) {
+    const { id, key, agent, ai, aiKey, ...clientOptions } = options;
+    super(client(need2(ai, "SPREDR_AI_URL"), { from: need2(id, "SPREDR_CALLER_ID"), key: privateKeyOf(need2(key, "SPREDR_CALLER_KEY")) }, clientOptions), need2(agent, "SPREDR_AGENT"));
+    this.#id = need2(id, "SPREDR_CALLER_ID");
+    const checkWith = aiKey || process.env.SPREDR_AI_KEY;
+    this.#verify = checkWith ? aiVerifier(checkWith) : null;
+  }
+  /** The same as `new Caller(overrides)`: from the variables spredr writes into a linked service. */
+  static fromEnv(overrides = {}) {
+    return new _Caller(overrides);
+  }
+  /** The callback, when it really comes from ai (signed, recent, once); null otherwise. Give it the raw body. */
+  callback(request) {
+    if (!this.#verify) throw new Error("Pass aiKey (SPREDR_AI_KEY) to check callbacks.");
+    if (!this.#verify(request)) return null;
+    const text = typeof request.body === "string" ? request.body : Buffer.from(request.body).toString("utf8");
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null || !("event" in parsed) || !("task" in parsed)) return null;
+    const to = "to" in parsed && typeof parsed.to === "object" && parsed.to !== null && "caller" in parsed.to ? parsed.to.caller : void 0;
+    if (to !== void 0 && to !== this.#id) return null;
+    return parsed;
+  }
+};
+
+// src/owner.ts
+var DEFAULT_AI_URL = "https://api.spredr.cloud/ai";
+var Spredr = class {
+  #client;
+  constructor(options = {}) {
+    const { token: given, ai, ...clientOptions } = options;
+    const token = given || process.env.SPREDR_TOKEN;
+    if (!token) throw new Error("SPREDR_TOKEN is not set: make an API token in the panel (Account \u203A API tokens), or pass { token }.");
+    this.#client = client(ai || process.env.SPREDR_AI_URL || DEFAULT_AI_URL, { token }, clientOptions);
+  }
+  async agents() {
+    return (await this.#client.call("GET", "/agents")).agents;
+  }
+  /** Turns a spredr service into an agent: ai writes its keys into the service and deploys it again. A deploy spredr
+   *  refuses (redeploy.status «failed») leaves the agent made: deploy the service again once that is fixed. */
+  async register(name, service, options = {}) {
+    const made = await this.#client.call("POST", "/agents", { name, service, ...options });
+    return { ...made.agent, redeploy: made.redeploy };
+  }
+  /** Leaves a token for ai to wake and put to sleep your agents while nobody is looking. */
+  async keepToken(token) {
+    await this.#client.call("PUT", "/me/key", { token });
+  }
+  /** What waits for a person across every agent: open questions, tasks that failed in the last `hours`, and agents whose
+   *  memory is 80 % full or more. */
+  async inbox(hours = 24) {
+    return this.#client.call("GET", `/inbox${query({ hours })}`);
+  }
+  agent(name) {
+    return new OwnedAgent(this.#client, name);
+  }
+};
+var OwnedAgent = class {
+  #client;
+  #path;
+  tasks;
+  constructor(client2, name) {
+    this.#client = client2;
+    this.#path = `/agents/${encodeURIComponent(name)}`;
+    this.tasks = new Tasks(client2, name);
+  }
+  /** The agent working for one tenant: its tasks, usage, caps, lessons and freedom, and forgetting it. */
+  for(tenant) {
+    return this.tasks.for(tenant);
+  }
+  /** The tenants it worked for in the last `days`, the latest active first, each with what it used. */
+  async tenants(options = {}) {
+    return (await this.#client.call("GET", `${this.#path}/tenants${query(options)}`)).tenants;
+  }
+  /** The caps of every tenant without caps of its own. */
+  async setTenantLimits(limits) {
+    return (await this.#client.call("PUT", `${this.#path}/tenants/*/limits`, limits)).caps;
+  }
+  async info() {
+    return (await this.#client.call("GET", this.#path)).agent;
+  }
+  /** Its last hours at a glance: tasks, failures, times, tokens, cost, tools, and how free it is. */
+  async summary(hours = 24) {
+    return (await this.#client.call("GET", `${this.#path}/summary${query({ hours })}`)).summary;
+  }
+  /** Its conversations: tasks that share a thread. Read one with tasks.list({ thread }). */
+  async threads(limit = 50) {
+    return (await this.#client.call("GET", `${this.#path}/threads${query({ limit })}`)).threads;
+  }
+  /** Every task since a moment with its steps (the export, read line by line). */
+  async export(since) {
+    const text = await this.#client.text("GET", `${this.#path}/export${query({ since: since ? new Date(since).toISOString() : void 0 })}`);
+    return text.split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  }
+  async setLimits(limits) {
+    return (await this.#client.call("PUT", `${this.#path}/limits`, limits)).agent;
+  }
+  /** Sends each finished task to your OpenTelemetry endpoint (OTLP/HTTP: Langfuse, Datadog, Honeycomb, your collector)
+   *  as a trace. headers carry its key (sealed by ai, never shown back); withContent sends the input and result too. */
+  async setTraces(traces) {
+    return (await this.#client.call("PUT", `${this.#path}/traces`, traces)).traces;
+  }
+  /** Where its traces go (the header names only), or null. */
+  async traces() {
+    return (await this.#client.call("GET", `${this.#path}/traces`)).traces;
+  }
+  async stopTraces() {
+    await this.#client.call("DELETE", `${this.#path}/traces`);
+  }
+  async remove() {
+    await this.#client.call("DELETE", this.#path);
+  }
+  /** A new key pair: ai believes the new key at once, whatever the redeploy does (redeploy.status says). */
+  async rotateKey(options = {}) {
+    const rotated = await this.#client.call("POST", `${this.#path}/rotate`, options);
+    return { ...rotated.agent, redeploy: rotated.redeploy };
+  }
+  /** A backend that may give this agent tasks. With `service`, ai writes its key there; with `publicKey`, the private
+   *  one never leaves you; with neither, the private key comes back this once. With `everything` and a `callbackUrl`, it
+   *  is an events webhook: it hears about every task of the agent (task.created, done, failed, paused, canceled). */
+  async addCaller(name, options = {}) {
+    return this.#client.call("POST", `${this.#path}/callers`, { name, ...options });
+  }
+  async callers() {
+    return (await this.#client.call("GET", `${this.#path}/callers`)).callers;
+  }
+  async removeCaller(id) {
+    await this.#client.call("DELETE", `${this.#path}/callers/${id}`);
+  }
+  async schedule(name, kind, cron, options = {}) {
+    return (await this.#client.call("POST", `${this.#path}/schedules`, { name, kind, cron, ...options })).schedule;
+  }
+  /** A secret address that starts a task with whatever is POSTed to it; the address comes back this once. */
+  async hook(name, kind) {
+    return this.#client.call("POST", `${this.#path}/hooks`, { name, kind });
+  }
+  /** Every file its sessions keep, newest first (each with its tenant, conversation and place in the bucket), and how full
+   *  its room for them is. */
+  async storedFiles(options = {}) {
+    return this.#client.call("GET", `${this.#path}/stored-files${query(options)}`);
+  }
+  /** One of them, as its bytes and type: any session's. */
+  async downloadFile(id) {
+    const got = await this.#client.download(`${this.#path}/stored-files/${encodeURIComponent(id)}`);
+    return { data: got.data, type: got.type };
+  }
+  /** Removes one, any session's: its card and its bytes. */
+  async deleteFile(id) {
+    await this.#client.call("DELETE", `${this.#path}/stored-files/${encodeURIComponent(id)}`);
+  }
+  /** How full its memory is (warn from 80 %, full from 95 %), and whether unchanged facts are forgotten. */
+  async memoryUse() {
+    return (await this.#client.call("GET", `${this.#path}/memory/use`)).use;
+  }
+  /** What it remembers; `tenant` narrows it to one tenant's. */
+  async memory(options = {}) {
+    return (await this.#client.call("GET", `${this.#path}/memory${query(options)}`)).facts;
+  }
+  async editFact(id, text, data) {
+    return (await this.#client.call("PATCH", `${this.#path}/memory/${id}`, { text, ...data === void 0 ? {} : { data } })).fact;
+  }
+  /** Erases everything the agent keeps under a scope (a customer who asks to be forgotten): the agent's own, or one
+   *  tenant's. */
+  async forget(scope, tenant) {
+    return (await this.#client.call("POST", `${this.#path}/memory/forget`, { scope, ...tenant ? { tenant } : {} })).forgotten;
+  }
+  /** How free it is with each action in its own work (no tenant); a tenant's is `for(tenant).freedom()`. */
+  async freedom() {
+    return (await this.#client.call("GET", `${this.#path}/freedom`)).freedom;
+  }
+  async setFreedom(action, level) {
+    return (await this.#client.call("PUT", `${this.#path}/freedom/${encodeURIComponent(action)}`, { level })).freedom;
+  }
+  async lessons() {
+    return (await this.#client.call("GET", `${this.#path}/lessons`)).lessons;
+  }
+  async writeLesson(text, why = "") {
+    return (await this.#client.call("POST", `${this.#path}/lessons`, { text, why })).lesson;
+  }
+  async decide(lessonId, decision) {
+    return (await this.#client.call("POST", `${this.#path}/lessons/${lessonId}`, { decision })).lesson;
+  }
+  async versions() {
+    return (await this.#client.call("GET", `${this.#path}/versions`)).versions;
+  }
+  /** Releases the accepted lessons as a new version, tried first on past tasks. */
+  async release() {
+    return (await this.#client.call("POST", `${this.#path}/versions`, {})).version;
+  }
+  async version(version, action) {
+    return (await this.#client.call("POST", `${this.#path}/versions/${version}`, { action })).version;
+  }
+};
+export {
+  Agent,
+  AuthenticationError,
+  BadRequestError,
+  Caller,
+  ConflictError,
+  ConnectionError,
+  DEFAULT_AI_URL,
+  InternalServerError,
+  NotFoundError,
+  OwnedAgent,
+  PermissionDeniedError,
+  RateLimitError,
+  Spredr,
+  SpredrError,
+  TaskError,
+  Tasks,
+  Tenant,
+  TimeoutError,
+  aiVerifier,
+  currentTask,
+  newKeys
+};