@foir/sdk 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -108,10 +108,94 @@ nobody asking for `@foir/sdk` gets it early. The push that carries the commit to
 
 Changes on `dev` that have not been published to npm.
 
+### Added
+
+- **Tags in a message** (`@foir/sdk/ai`, `@foir/sdk/data`): a message can
+  point at a record, a field, a model, a person, a file, an operation, an
+  agent, a hook, a schedule, an organisation or a note, by id. The `useChat`
+  transport sends each `data-tag` part of the message as a tag, and
+  `startAgentRun` (and so `askAgent`) takes `tags`, typed `FoirMessageTag`.
+  The agent reads what a tag points at with its own tools, as the caller.
+- **Images and PDFs in a message** (`@foir/sdk/ai`, `@foir/sdk/data`): the
+  `useChat` transport sends the files of `sendMessage({ text, files })`, and
+  `askAgent` takes `files`. Each is uploaded first with the new
+  `uploadAgentFile` (or the `createAgentAttachment` mutation) and sent by its
+  id in `startAgentRun`'s `attachmentIds`. `foirChatMessages` reads a sent
+  file back as a `file` part with a link that lasts an hour. An image (PNG,
+  JPEG, GIF or WebP) may be up to 5 MB and a PDF up to 10 MB, at most five a
+  message; a visitor may send images only, 20 a day.
+- **Field marks** (`@foir/sdk/data`): `subjects.field(record, 'title', { label })`
+  returns `{ 'data-foir-field': token }` to spread onto the element that shows
+  that field, and `subjects.pointedAt(token)` reads it back as a
+  `FoirFieldMark`. The token is opaque, so the page prints none of the model,
+  record or field, and the same field gets the same token on the server and in
+  the browser.
+- **`<FoirFeedback pointing>`** (`@foir/sdk/react`): the reader points at the
+  part of the page they mean, by clicking a marked field or by Tab and Enter,
+  and the note is filed against that record and names the field
+  (`anchorField`). A page showing two records files each comment against the
+  right one. A visitor may name a field they can read; the data API refuses
+  any other. Offered only while the page shows a marked field. `writeNote`
+  takes the anchor from this release of the data API; a client generated
+  before it needs `foir types` re-run before it can send one.
+- **`<FoirFeedback launcher="bottom-right" | "bottom-left">`**: the button is
+  fixed in that corner of the viewport, and the inline panel opens above it.
+- **`@foir/sdk/ai`**: `foirChatTransport({ client, agent })` puts a project's
+  agent behind the AI SDK's `useChat`, with no backend of the app's own. Text
+  and reasoning stream into their parts, each step the agent takes is a
+  `dynamic-tool` part, and an act held for the person is the AI SDK's
+  approval step, decided with `addToolApprovalResponse`. The chat keeps its
+  thread in the browser's storage; `foirChatMessages` reads a thread back as
+  `useChat`'s messages. `ai` (7.x) is an optional peer, which
+  `@foir/sdk/ai` needs. Data an agent sends the app arrives as `data-<name>`
+  parts.
+- **Tools of the page** (`@foir/sdk/ai`): `foirChatTransport({ pageTools })`
+  defines the page's own tools, each with a `description`, an `inputSchema`
+  (a Zod schema, a Standard Schema or `jsonSchema()`) and an `execute`, as an
+  AI SDK `tool()` has. They are sent with every message to an agent that
+  allows the page's tools. When the agent calls one, the transport runs
+  `execute` and the run carries on in the same answer with what it returned;
+  what it throws is answered as `{ error }`. A tool with no `execute` is a
+  tool part the app answers with `addToolOutput`. `startAgentRun` takes
+  `pageTools`, typed `FoirPageToolOffer`.
+- **Typed answers** (`@foir/sdk/data`): `askAgent` resolves with `output`, the
+  value a run of an agent with an output schema answers with. `FoirAgentRun`
+  carries `output`, and a run's events carry `DATA` (a data part sent to the
+  app) and the final `STATUS` event's `output`. A run's nodes can be
+  `PAGE_TOOL` (a tool the page offered, held until `answerPageTool`) and
+  `DATA`.
+
+### Fixed
+
+- **`CodeFlowConfig.issuer` names Foir's issuer as `https://api.foir.dev`** in
+  its description, where it said `https://api.foir.io`. The comments of
+  `@foir/sdk/auth` and `<SignIn>` call the hosted page hosted sign-in.
+- **`foirChatTransport` and `foirChatMessages` take any client
+  `createFoirClient` returns**, typed by the project's schema or not, as
+  `askAgent` does. The documented example passed such a client and did not
+  typecheck. A client whose key runs no agent is refused when the first
+  message is sent, saying so.
+- **A `useChat` answer that is cancelled stops following its run.** The
+  transport kept the run's subscription open and wrote each later event to a
+  stream nobody read, which threw. A page loaded again still picks the answer
+  up from the stored run with `resume`.
+
 ## [0.29.0] — 2026-10-21
 
 ### Added
 
+- **Agents** (`@foir/sdk/data`): a project's agents through the data API.
+  `foir.ns.agents.startAgentRun`, `cancelAgentRun`, `agentRun`, `agentThreads`
+  and the approvals verbs are offered where the key runs some agent, and
+  `foir.ns.agents.onRun({ id })` follows a run as it is written, from its start
+  so nothing is missed. `askAgent(foir, { agent, message, threadId, onText })`
+  starts a run and resolves with the answer, the thread to go on with and how
+  the run ended; `visitorToken()` is a visitor's own secret, kept in the
+  browser, which makes a conversation theirs. Types: `FoirAgentRun`,
+  `FoirAgentRunEvent`, `FoirAgentRunNode`, `FoirAgentRunStatus`,
+  `FoirAgentThread`, `FoirAgentThreadMessage`, `FoirAgentApproval`,
+  `FoirMcpConnection`, `FoirStartAgentRunArgs`, `FoirAgentsClient`,
+  `AskAgentOptions`, `AgentReply`.
 - **`AuthorizedApp` says whose app it is**: `clientLogoUrl`, `clientLogoAlt`
   and `clientHomepageUrl`, where the app set them.
 - **`beginSignIn` and `completeSignIn`** (`@foir/sdk/auth`): the OpenID Connect

package/dist/ai/index.d.ts

@@ -0,0 +1,190 @@
+/**
+ * A Fóir agent behind the AI SDK's `useChat`.
+ *
+ * ```tsx
+ * import { useChat } from '@ai-sdk/react';
+ * import { lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai';
+ * import { createFoirClient } from '@foir/sdk/data';
+ * import { foirChatTransport } from '@foir/sdk/ai';
+ *
+ * const foir = createFoirClient({ apiUrl, apiKey });
+ * const transport = foirChatTransport({ client: foir, agent: 'support' });
+ *
+ * const { messages, sendMessage, addToolApprovalResponse } = useChat({
+ *   transport,
+ *   sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+ * });
+ * ```
+ *
+ * Each message starts a run of the agent on Fóir. Nothing runs in the app's
+ * own backend, and the app holds no model key. The run's events arrive as the
+ * message parts `useChat` renders: text and reasoning as they are written, and
+ * each step the agent takes as a tool part. An act the agent holds for the
+ * person's decision is the AI SDK's approval step: `addToolApprovalResponse`
+ * decides it, and the run carries on. An act held for the project's team shows
+ * as waiting, since the person cannot decide it.
+ *
+ * Data the agent sends the app's own components arrives as `data-<name>`
+ * parts. The page's own tools are defined once, in `pageTools`, and sent with
+ * each message to an agent that allows them:
+ *
+ * ```ts
+ * const transport = foirChatTransport({
+ *   client: foir,
+ *   agent: 'shop',
+ *   pageTools: {
+ *     show_product: {
+ *       description: 'Open a product on the page.',
+ *       inputSchema: z.object({ id: z.string() }),
+ *       execute: ({ id }) => {
+ *         router.push(`/products/${id}`);
+ *         return { shown: id };
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * The transport runs a tool's `execute` when the agent calls it, and the run
+ * carries on with what it returned. A tool with no `execute` is a tool part
+ * waiting for its output: answer it in `onToolCall` with `addToolOutput`.
+ *
+ * Fóir keeps the conversation. A chat goes on in its thread for as long as
+ * `threads` keeps the thread's id (the browser's storage by default), and a
+ * visitor's thread is theirs by the secret their browser keeps.
+ * `foirChatMessages` reads a thread back as `useChat`'s messages.
+ */
+import type { ChatTransport, FlexibleSchema, UIMessage, UIMessageChunk } from 'ai';
+import type { FoirAgentAttachmentUpload, FoirAgentRun, FoirAgentRunNode, FoirAgentThread, FoirCreateAgentAttachmentArgs, FoirStartAgentRunArgs } from '../data/builtins';
+import type { FoirAgentRunEvent, FoirAgentRunSubscribeOptions } from '../data/subscriptions';
+import type { FoirSubscription } from '../data/ws-transport';
+/** What the transport needs of a client: the agents namespace a key that runs an agent is given. */
+export interface FoirChatClient {
+    ns: {
+        agents: {
+            startAgentRun(args: FoirStartAgentRunArgs): Promise<FoirAgentRun>;
+            onRun(options: FoirAgentRunSubscribeOptions): FoirSubscription;
+            decideAgentApproval(args: {
+                id: string;
+                approve: boolean;
+                reason?: string;
+            }): Promise<FoirAgentRunNode | null>;
+            answerPageTool(args: {
+                id: string;
+                output: unknown;
+                visitorToken?: string;
+            }): Promise<FoirAgentRunNode | null>;
+            agentThread(args: {
+                id: string;
+                visitorToken?: string;
+            }): Promise<FoirAgentThread | null>;
+            createAgentAttachment(args: FoirCreateAgentAttachmentArgs): Promise<FoirAgentAttachmentUpload>;
+        };
+    };
+}
+/**
+ * A tool of the app's own page, which the agent may call while it answers. An
+ * AI SDK `tool({ ... })` is one.
+ */
+export interface FoirPageTool<INPUT = any> {
+    /** What the tool does, as the model is told it. At most 1000 characters. */
+    description?: string;
+    /**
+     * The tool's input: a Zod schema, a Standard Schema, or a JSON Schema
+     * through the AI SDK's `jsonSchema()`. It must describe an object. Left
+     * out, the tool takes no input.
+     */
+    inputSchema?: FlexibleSchema<INPUT>;
+    /**
+     * Does what the tool does on the page, and answers what it did: JSON, as
+     * the model is told it, at most 64 KB. What it throws is answered as
+     * `{ error }`. Left out, the call waits for `addToolOutput`.
+     */
+    execute?(input: INPUT, options: {
+        toolCallId: string;
+        messages: unknown[];
+        abortSignal?: AbortSignal;
+    }): unknown;
+}
+/** Where a chat's thread id is kept between page loads. */
+export type FoirThreadStore = Pick<Storage, 'getItem' | 'setItem'>;
+export interface FoirChatTransportOptions {
+    /**
+     * A Fóir client whose key runs the agent: `createFoirClient`'s, typed by
+     * the project's schema or not. A client that offers no agents is refused
+     * when the first message is sent, saying so.
+     */
+    client: FoirChatClient | {
+        readonly ns: object;
+    };
+    /** The agent's key. */
+    agent: string;
+    /**
+     * A visitor with nobody signed in: the secret their browser keeps. Defaults
+     * to the one `visitorToken()` keeps; pass `null` for a signed-in person.
+     */
+    visitorToken?: string | null;
+    /** Where each chat's thread id is kept. The browser's storage by default; `null` keeps it for the page. */
+    threads?: FoirThreadStore | null;
+    /**
+     * The page's own tools, by name: lowercase letters, digits and _. Each is
+     * sent with every message, and the agent must allow the page's tools. At
+     * most 20.
+     */
+    pageTools?: Record<string, FoirPageTool>;
+}
+/**
+ * One run's events as `useChat`'s chunks. A run outlives a stream: it stops
+ * for a decision and carries on once it is made, so what the person has
+ * already been shown (the steps, the last event) is kept per run, and each
+ * stream only opens and closes its own text.
+ */
+export declare class FoirRunChunks {
+    private readonly runId;
+    private readonly runs;
+    private readonly tools;
+    /** The last event shown, to follow the run again from. */
+    after: string;
+    private textId;
+    private reasoningId;
+    private opened;
+    /** The run stopped for this stream's followers: it ended, or holds an act. */
+    stopped: boolean;
+    /** Calls to the page's tools waiting for the app's `addToolOutput`. */
+    readonly pageCalls: Set<string>;
+    /** Calls to the page's tools the transport runs and answers itself, until the run hears them. */
+    readonly answering: Set<string>;
+    /** Calls the transport is to run: taken with `takeCalls`. */
+    private toRun;
+    /** Acts held for a decision, by anyone. */
+    private readonly held;
+    /** `runs` names the page's tools the transport runs itself. */
+    constructor(runId: string, runs?: (tool: string) => boolean);
+    /** The calls to the page's tools that arrived for the transport to run. */
+    takeCalls(): FoirAgentRunNode[];
+    /** Starts a new stream of the same run, as after a decision. */
+    resume(): void;
+    private open;
+    private closeText;
+    private closeReasoning;
+    /** The chunks an event makes. `fresh` is a stream that starts a new message. */
+    of(event: FoirAgentRunEvent, fresh?: boolean): UIMessageChunk[];
+    private toolChunks;
+    /**
+     * 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.
+     */
+    private pageToolChunks;
+}
+/** The transport `useChat` sends through: each message is a run of a Fóir agent. */
+export declare function foirChatTransport(options: FoirChatTransportOptions): ChatTransport<UIMessage>;
+/**
+ * A thread read back as `useChat`'s messages, to open a chat where it was left.
+ * Fóir keeps each message's parts as the run wrote them.
+ */
+export declare function foirChatMessages(client: FoirChatClient | {
+    readonly ns: object;
+}, threadId: string, options?: {
+    visitorToken?: string | null;
+}): Promise<UIMessage[]>;