@foir/sdk 0.28.0 → 0.30.0

package/dist/ai.js

@@ -0,0 +1,566 @@
+// src/ai/index.ts
+import { asSchema } from "ai";
+
+// src/data/agents.ts
+async function uploadAgentFile(foir, options) {
+  const agents = foir.ns.agents;
+  if (typeof agents?.createAgentAttachment !== "function") {
+    throw new Error("[foir] uploadAgentFile: this client sends no agent files. Its key runs none of the project's agents, or the project has released none.");
+  }
+  const { blob, mediaType, filename } = fileParts(options.file);
+  const up = await agents.createAgentAttachment({
+    agent: options.agent,
+    filename,
+    mediaType,
+    size: blob.size,
+    ...options.visitorToken ? { visitorToken: options.visitorToken } : {}
+  });
+  const put = await (options.fetch ?? fetch)(up.uploadUrl, { method: "PUT", headers: { "content-type": mediaType }, body: blob });
+  if (!put.ok) throw new Error(`[foir] uploadAgentFile: ${filename} was not uploaded (${put.status}).`);
+  return up.attachment;
+}
+function fileParts(file) {
+  if (typeof Blob !== "undefined" && file instanceof Blob) {
+    const name = file.name;
+    return { blob: file, mediaType: file.type, filename: name || "file" };
+  }
+  const { data, mediaType, filename } = file;
+  const blob = data instanceof Blob ? data : new Blob([data], { type: mediaType });
+  return { blob, mediaType, filename: filename || "file" };
+}
+var VISITOR_KEY = "foir:agents:visitor";
+function visitorToken(storage = browserStorage(), key = VISITOR_KEY) {
+  try {
+    const kept = storage?.getItem(key);
+    if (kept) return kept;
+  } catch {
+  }
+  const made = randomSecret();
+  try {
+    storage?.setItem(key, made);
+  } catch {
+  }
+  return made;
+}
+function browserStorage() {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+function randomSecret() {
+  const bytes = new Uint8Array(24);
+  globalThis.crypto.getRandomValues(bytes);
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+
+// src/ai/index.ts
+var TOOL_KINDS = /* @__PURE__ */ new Set(["VERB", "OPERATION", "MCP_TOOL", "AGENT", "PAGE_TOOL"]);
+var STOPS = /* @__PURE__ */ new Set(["COMPLETED", "FAILED", "SKIPPED", "CANCELLED", "HELD"]);
+var FoirRunChunks = class {
+  /** `runs` names the page's tools the transport runs itself. */
+  constructor(runId, runs = () => false) {
+    this.runId = runId;
+    this.runs = runs;
+  }
+  runId;
+  runs;
+  tools = /* @__PURE__ */ new Map();
+  /** The last event shown, to follow the run again from. */
+  after = "";
+  textId = null;
+  reasoningId = null;
+  opened = false;
+  /** The run stopped for this stream's followers: it ended, or holds an act. */
+  stopped = false;
+  /** Calls to the page's tools waiting for the app's `addToolOutput`. */
+  pageCalls = /* @__PURE__ */ new Set();
+  /** Calls to the page's tools the transport runs and answers itself, until the run hears them. */
+  answering = /* @__PURE__ */ new Set();
+  /** Calls the transport is to run: taken with `takeCalls`. */
+  toRun = [];
+  /** Acts held for a decision, by anyone. */
+  held = /* @__PURE__ */ new Set();
+  /** The calls to the page's tools that arrived for the transport to run. */
+  takeCalls() {
+    const out = this.toRun;
+    this.toRun = [];
+    return out;
+  }
+  /** Starts a new stream of the same run, as after a decision. */
+  resume() {
+    this.opened = false;
+    this.stopped = false;
+    this.textId = null;
+    this.reasoningId = null;
+  }
+  open(out, fresh) {
+    if (this.opened) return;
+    this.opened = true;
+    if (fresh) out.push({ type: "start" });
+    out.push({ type: "start-step" });
+  }
+  closeText(out) {
+    if (this.textId) out.push({ type: "text-end", id: this.textId });
+    this.textId = null;
+  }
+  closeReasoning(out) {
+    if (this.reasoningId) out.push({ type: "reasoning-end", id: this.reasoningId });
+    this.reasoningId = null;
+  }
+  /** The chunks an event makes. `fresh` is a stream that starts a new message. */
+  of(event, fresh = true) {
+    const out = [];
+    if (event.seq) this.after = event.seq;
+    switch (event.kind) {
+      case "TEXT": {
+        if (!event.text) break;
+        this.open(out, fresh);
+        this.closeReasoning(out);
+        if (!this.textId) {
+          this.textId = `${this.runId}:t:${event.seq}`;
+          out.push({ type: "text-start", id: this.textId });
+        }
+        out.push({ type: "text-delta", id: this.textId, delta: event.text });
+        break;
+      }
+      case "REASONING": {
+        if (!event.text) break;
+        this.open(out, fresh);
+        if (!this.reasoningId) {
+          this.reasoningId = `${this.runId}:r:${event.seq}`;
+          out.push({ type: "reasoning-start", id: this.reasoningId });
+        }
+        out.push({ type: "reasoning-delta", id: this.reasoningId, delta: event.text });
+        break;
+      }
+      case "NODE": {
+        const node = event.node;
+        if (!node || !TOOL_KINDS.has(node.kind) || node.id === this.runId) break;
+        this.open(out, fresh);
+        this.closeText(out);
+        this.closeReasoning(out);
+        out.push(...this.toolChunks(node));
+        break;
+      }
+      case "DATA": {
+        if (!event.dataName) break;
+        this.open(out, fresh);
+        out.push({ type: `data-${event.dataName}`, id: `${this.runId}:d:${event.seq}`, data: event.data ?? null });
+        break;
+      }
+      case "STATUS": {
+        if (!event.status || !STOPS.has(event.status)) break;
+        if (event.status === "HELD" && this.answering.size > 0 && this.pageCalls.size === 0 && this.held.size === 0) break;
+        this.open(out, fresh);
+        this.closeText(out);
+        this.closeReasoning(out);
+        if (event.status === "FAILED") {
+          out.push({ type: "error", errorText: event.error || "The answer could not be finished." });
+        }
+        if (event.status === "SKIPPED" && event.answer && this.tools.size === 0) {
+          const id = `${this.runId}:refusal`;
+          out.push({ type: "text-start", id }, { type: "text-delta", id, delta: event.answer }, { type: "text-end", id });
+        }
+        out.push({ type: "finish-step" }, { type: "finish" });
+        this.stopped = true;
+        break;
+      }
+      default:
+        break;
+    }
+    return out;
+  }
+  toolChunks(node) {
+    const out = [];
+    const shown = this.tools.get(node.id);
+    if (shown === node.status) return out;
+    if (shown === void 0) {
+      const input = node.input?.args ?? node.input ?? {};
+      out.push({ type: "tool-input-available", toolCallId: node.id, toolName: node.key, input, dynamic: true });
+    }
+    this.tools.set(node.id, node.status);
+    if (node.kind === "PAGE_TOOL") return this.pageToolChunks(node, out);
+    if (node.status === "HELD" && node.approval) this.held.add(node.id);
+    else this.held.delete(node.id);
+    switch (node.status) {
+      case "COMPLETED":
+        out.push({ type: "tool-output-available", toolCallId: node.id, output: node.result ?? {}, dynamic: true });
+        break;
+      case "HELD":
+        if (node.approval?.approver === "CALLER" && node.approval.decision === "PENDING") {
+          out.push({ type: "tool-approval-request", approvalId: node.id, toolCallId: node.id });
+        } else if (node.approval) {
+          out.push({
+            type: "tool-output-available",
+            toolCallId: node.id,
+            output: { status: "held", approver: node.approval.approver, summary: node.approval.summary },
+            preliminary: true,
+            dynamic: true
+          });
+        }
+        break;
+      case "SKIPPED":
+        if (node.approval?.decision === "DENIED") out.push({ type: "tool-output-denied", toolCallId: node.id });
+        else out.push({ type: "tool-output-error", toolCallId: node.id, errorText: node.error || "Refused.", dynamic: true });
+        break;
+      case "FAILED":
+      case "CANCELLED":
+        out.push({ type: "tool-output-error", toolCallId: node.id, errorText: node.error || "Refused.", dynamic: true });
+        break;
+      default:
+        break;
+    }
+    return out;
+  }
+  /**
+   * A call to one of the page's tools. The transport runs one it has an
+   * `execute` for and shows what it answered; any other waits for the app's
+   * `addToolOutput`. One the page did not answer in time is an error.
+   */
+  pageToolChunks(node, out) {
+    const ours = this.runs(node.key);
+    if (node.status === "HELD") {
+      if (ours) {
+        this.answering.add(node.id);
+        this.toRun.push(node);
+      } else {
+        this.pageCalls.add(node.id);
+      }
+      return out;
+    }
+    this.pageCalls.delete(node.id);
+    const answered = this.answering.delete(node.id);
+    if (node.status === "COMPLETED" && answered) {
+      const result = node.result;
+      out.push(
+        { type: "tool-output-available", toolCallId: node.id, output: result?.result ?? null, dynamic: true },
+        { type: "finish-step" },
+        { type: "start-step" }
+      );
+    } else if (node.status === "FAILED" || node.status === "CANCELLED" || node.status === "SKIPPED") {
+      out.push({ type: "tool-output-error", toolCallId: node.id, errorText: node.error || "The page did not answer.", dynamic: true });
+    }
+    return out;
+  }
+};
+async function pageToolInput(tool, raw) {
+  if (!tool.inputSchema) return raw ?? {};
+  const checked = await asSchema(tool.inputSchema).validate?.(raw);
+  if (!checked) return raw;
+  if (!checked.success) throw checked.error;
+  return checked.value;
+}
+async function pageToolOffers(tools) {
+  return Promise.all(
+    Object.entries(tools).map(async ([name, tool]) => {
+      const offer = { name };
+      if (tool.description) offer.description = tool.description;
+      if (tool.inputSchema) offer.inputSchema = await asSchema(tool.inputSchema).jsonSchema;
+      return offer;
+    })
+  );
+}
+function asAnswer(value) {
+  if (value === void 0) return null;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return { error: "The tool answered something that is not JSON." };
+  }
+}
+function lastUserText(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role !== "user") continue;
+    const text = m.parts.filter((p) => p.type === "text").map((p) => p.text).join("\n");
+    return { id: m.id, text };
+  }
+  return { id: "", text: "" };
+}
+function lastUserFiles(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role !== "user") continue;
+    return m.parts.filter((p) => p.type === "file").map((p) => ({ url: p.url, mediaType: p.mediaType, filename: p.filename }));
+  }
+  return [];
+}
+function lastUserTags(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role !== "user") continue;
+    const out = [];
+    for (const part of m.parts) {
+      const p = part;
+      if (p.type !== "data-tag" || !p.data) continue;
+      const str = (k) => typeof p.data?.[k] === "string" ? p.data[k] : void 0;
+      const kind = str("kind")?.toUpperCase();
+      const id = str("id");
+      if (!kind || !id) continue;
+      out.push({ kind, id, model: str("model"), field: str("field"), label: str("label") });
+    }
+    return out;
+  }
+  return [];
+}
+async function blobOf(url, mediaType) {
+  const resp = await fetch(url);
+  if (!resp.ok) throw new Error(`A file could not be read (${resp.status}).`);
+  const blob = await resp.blob();
+  return blob.type ? blob : new Blob([blob], { type: mediaType });
+}
+function decisionsIn(messages, sent) {
+  const last = messages[messages.length - 1];
+  if (last?.role !== "assistant") return [];
+  const out = [];
+  for (const part of last.parts) {
+    const p = part;
+    if (!(p.type === "dynamic-tool" || p.type.startsWith("tool-")) || p.state !== "approval-responded" || !p.approval) continue;
+    if (sent.has(p.approval.id)) continue;
+    out.push({ id: p.approval.id, approve: p.approval.approved === true, reason: p.approval.reason });
+  }
+  return out;
+}
+function pageAnswersIn(messages, waiting) {
+  const last = messages[messages.length - 1];
+  if (last?.role !== "assistant") return [];
+  const out = [];
+  for (const part of last.parts) {
+    const p = part;
+    if (p.type !== "dynamic-tool" || p.state !== "output-available" || !p.toolCallId || !waiting.has(p.toolCallId)) continue;
+    out.push({ id: p.toolCallId, output: p.output ?? null });
+  }
+  return out;
+}
+function agentsOf(client, caller) {
+  const found = client.ns.agents;
+  if (!found) {
+    const refuse = () => {
+      throw new Error(
+        `[foir] ${caller}: this client offers no agents. Its key runs none of the project's agents (agents:execute), or the project has released none.`
+      );
+    };
+    return {
+      startAgentRun: refuse,
+      onRun: refuse,
+      decideAgentApproval: refuse,
+      answerPageTool: refuse,
+      agentThread: refuse,
+      createAgentAttachment: refuse
+    };
+  }
+  return found;
+}
+function foirChatTransport(options) {
+  const { client, agent } = options;
+  const pageTools = options.pageTools ?? {};
+  const agents = agentsOf(client, "foirChatTransport");
+  let offers = null;
+  const offered = () => offers ??= pageToolOffers(pageTools);
+  const runsItself = (name) => typeof pageTools[name]?.execute === "function";
+  const visitor = options.visitorToken === void 0 ? visitorToken() : options.visitorToken ?? void 0;
+  const store = options.threads === void 0 ? browserStorage2() : options.threads;
+  const pageThreads = /* @__PURE__ */ new Map();
+  const runs = /* @__PURE__ */ new Map();
+  const lastRun = /* @__PURE__ */ new Map();
+  const decided = /* @__PURE__ */ new Set();
+  const uploaded = /* @__PURE__ */ new Map();
+  const threadKey = (chatId) => `foir:agents:thread:${agent}:${chatId}`;
+  const threadOf = (chatId) => {
+    const kept = pageThreads.get(chatId);
+    if (kept) return kept;
+    try {
+      return store?.getItem(threadKey(chatId)) ?? null;
+    } catch {
+      return null;
+    }
+  };
+  const keepThread = (chatId, threadId) => {
+    pageThreads.set(chatId, threadId);
+    try {
+      store?.setItem(threadKey(chatId), threadId);
+    } catch {
+    }
+  };
+  const chunksOf = (runId) => {
+    let c = runs.get(runId);
+    if (!c) {
+      c = new FoirRunChunks(runId, runsItself);
+      runs.set(runId, c);
+    }
+    return c;
+  };
+  const answerCall = async (node, signal) => {
+    const tool = pageTools[node.key];
+    let output;
+    try {
+      const raw = node.input?.args ?? node.input;
+      const input = await pageToolInput(tool, raw);
+      output = asAnswer(await tool.execute(input, { toolCallId: node.id, messages: [], abortSignal: signal }));
+    } catch (err) {
+      output = { error: err instanceof Error ? err.message : String(err) };
+    }
+    await agents.answerPageTool({ id: node.id, output, visitorToken: visitor });
+  };
+  const follow = (runId, fresh, signal) => {
+    const chunks = chunksOf(runId);
+    chunks.resume();
+    let sub = null;
+    let closed = false;
+    return new ReadableStream({
+      start(controller) {
+        const close = () => {
+          if (closed) return;
+          closed = true;
+          sub?.unsubscribe();
+          controller.close();
+        };
+        sub = agents.onRun({
+          id: runId,
+          after: chunks.after || void 0,
+          visitorToken: visitor,
+          onData: (event) => {
+            if (closed) return;
+            for (const c of chunks.of(event, fresh)) controller.enqueue(c);
+            for (const call of chunks.takeCalls()) {
+              answerCall(call, signal).catch((err) => {
+                chunks.answering.delete(call.id);
+                if (closed) return;
+                controller.enqueue({ type: "error", errorText: err instanceof Error ? err.message : String(err) });
+                close();
+              });
+            }
+            if (chunks.stopped) close();
+          },
+          onError: (err) => {
+            if (closed) return;
+            controller.enqueue({ type: "error", errorText: err instanceof Error ? err.message : String(err) });
+            close();
+          },
+          onComplete: close
+        });
+        signal?.addEventListener("abort", close, { once: true });
+      },
+      // The reader went away: stop following, and write nothing more to it.
+      cancel() {
+        closed = true;
+        sub?.unsubscribe();
+      }
+    });
+  };
+  return {
+    async sendMessages({ chatId, messages, abortSignal }) {
+      const decisions = decisionsIn(messages, decided);
+      const waiting = /* @__PURE__ */ new Set();
+      for (const c of runs.values()) for (const id2 of c.pageCalls) waiting.add(id2);
+      const answers = pageAnswersIn(messages, waiting);
+      if (decisions.length > 0 || answers.length > 0) {
+        for (const d of decisions) {
+          await agents.decideAgentApproval(d);
+          decided.add(d.id);
+        }
+        for (const a of answers) {
+          await agents.answerPageTool({ id: a.id, output: a.output, visitorToken: visitor });
+          for (const c of runs.values()) c.pageCalls.delete(a.id);
+        }
+        let runId = lastRun.get(chatId);
+        if (!runId) {
+          const threadId = threadOf(chatId);
+          const thread = threadId ? await agents.agentThread({ id: threadId, visitorToken: visitor }) : null;
+          runId = thread?.runningRunId ?? void 0;
+        }
+        if (!runId) throw new Error("The run these decisions were for could not be found.");
+        return follow(runId, false, abortSignal);
+      }
+      const { id, text } = lastUserText(messages);
+      let attachmentIds = id ? uploaded.get(id) : void 0;
+      if (!attachmentIds) {
+        const files = lastUserFiles(messages);
+        attachmentIds = [];
+        for (const f of files) {
+          const blob = await blobOf(f.url, f.mediaType);
+          const sent = await uploadAgentFile(client, {
+            agent,
+            file: { data: blob, mediaType: f.mediaType, filename: f.filename },
+            visitorToken: visitor
+          });
+          attachmentIds.push(sent.id);
+        }
+        if (id) uploaded.set(id, attachmentIds);
+      }
+      const tags = lastUserTags(messages);
+      const tools = await offered();
+      const run = await agents.startAgentRun({
+        agent,
+        message: text,
+        threadId: threadOf(chatId) ?? void 0,
+        idempotencyKey: id || void 0,
+        visitorToken: visitor,
+        ...attachmentIds.length > 0 ? { attachmentIds } : {},
+        ...tags.length > 0 ? { tags } : {},
+        ...tools.length > 0 ? { pageTools: tools } : {}
+      });
+      if (run.threadId) keepThread(chatId, run.threadId);
+      lastRun.set(chatId, run.id);
+      if (STOPS.has(run.status) && run.status !== "HELD") {
+        const answer = run.answer || run.error || "";
+        const textId = `${run.id}:answer`;
+        return new ReadableStream({
+          start(controller) {
+            controller.enqueue({ type: "start" });
+            if (answer) {
+              controller.enqueue({ type: "text-start", id: textId });
+              controller.enqueue({ type: "text-delta", id: textId, delta: answer });
+              controller.enqueue({ type: "text-end", id: textId });
+            }
+            controller.enqueue({ type: "finish" });
+            controller.close();
+          }
+        });
+      }
+      return follow(run.id, true, abortSignal);
+    },
+    async reconnectToStream({ chatId }) {
+      const threadId = threadOf(chatId);
+      if (!threadId) return null;
+      const thread = await agents.agentThread({ id: threadId, visitorToken: visitor });
+      if (!thread?.runningRunId) return null;
+      lastRun.set(chatId, thread.runningRunId);
+      return follow(thread.runningRunId, true);
+    }
+  };
+}
+async function foirChatMessages(client, threadId, options = {}) {
+  const visitor = options.visitorToken === void 0 ? visitorToken() : options.visitorToken ?? void 0;
+  const thread = await agentsOf(client, "foirChatMessages").agentThread({ id: threadId, visitorToken: visitor });
+  return (thread?.messages ?? []).map((m) => ({
+    id: m.id,
+    role: m.role === "USER" ? "user" : "assistant",
+    parts: (m.parts ?? []).map(asUIPart)
+  }));
+}
+function asUIPart(p) {
+  if (p.type !== "file") return p;
+  return {
+    type: "file",
+    mediaType: String(p.mediaType ?? ""),
+    url: String(p.url ?? ""),
+    ...typeof p.filename === "string" ? { filename: p.filename } : {}
+  };
+}
+function browserStorage2() {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+export {
+  FoirRunChunks,
+  foirChatMessages,
+  foirChatTransport
+};

package/dist/auth/auth.d.ts

@@ -43,11 +43,16 @@ export declare function login(env: FoirEnv, vars: {
     email: string;
     password: string;
 }): Promise<AuthResult>;
-/** Register a new user with email + password. */
+/**
+ * Start an account with email + password. The address is mailed a code, and
+ * signing in with it ({@link loginWithOTP}) proves the address and finishes
+ * the account. Answered the same whether or not the address has an account
+ * already, or the project takes nobody new: its holder is told by email.
+ */
 export declare function register(env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<AuthResult>;
+}): Promise<boolean>;
 /** Request a one-time password be emailed to the user. */
 export declare function requestOTP(env: FoirEnv, email: string): Promise<boolean>;
 /** Complete an OTP login. */
@@ -194,7 +199,11 @@ export declare function logout(env: FoirEnv, options?: AuthOpOptions): Promise<b
  * Irreversible. `password` is required for an account that holds one. An
  * account with none sets `confirm`, on a sign-in made in the last ten minutes:
  * an older one is refused, and the user signs in again. The server enforces
- * the re-auth gate and fails closed.
+ * the re-auth gate and fails closed. The answer counts the records and files
+ * the user owns, which are destroyed just after it.
+ *
+ * This does NOT clear local session state: {@link deleteMyAccountAndSignOut}
+ * is the pairing that does both.
  */
 export declare function deleteMyAccount(env: FoirEnv, vars: {
     confirm: boolean;
@@ -444,11 +453,15 @@ export declare function signInWithPassword(adapter: SessionAdapter, env: FoirEnv
     email: string;
     password: string;
 }): Promise<FoirUser>;
-/** Register with email + password and persist the session. */
-export declare function signUpWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
+/**
+ * Start a sign-up with email + password: the address is mailed a code, and
+ * {@link signInWithOTP} with it finishes the account and persists the
+ * session. Nobody is signed in until then.
+ */
+export declare function signUpWithPassword(env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<FoirUser>;
+}): Promise<void>;
 /** Complete an OTP login and persist the session. */
 export declare function signInWithOTP(adapter: SessionAdapter, env: FoirEnv, vars: {
     email: string;
@@ -463,6 +476,16 @@ export declare function resetPasswordAndSignIn(adapter: SessionAdapter, env: Foi
     token: string;
     newPassword: string;
 }): Promise<FoirUser>;
+/**
+ * Delete the signed-in user's account with the session's token, then clear the
+ * session, which the deletion ended server-side. A refusal (a wrong password,
+ * a sign-in too old to confirm with) leaves the session as it was, since the
+ * account is not deleted.
+ */
+export declare function deleteMyAccountAndSignOut(adapter: SessionAdapter, env: FoirEnv, vars: {
+    confirm: boolean;
+    password?: string;
+}): Promise<DeleteAccountResult>;
 /**
  * End the session on both sides: revoke it server-side, then clear local state.
  *