@foir/sdk 0.29.0 → 0.30.0

package/dist/auth.js

@@ -1417,6 +1417,11 @@ async function signInWithOTP(adapter, env, vars) {
 async function resetPasswordAndSignIn(adapter, env, vars) {
   return saveSession(adapter, await resetPassword(env, vars));
 }
+async function deleteMyAccountAndSignOut(adapter, env, vars) {
+  const result = await authedOp(adapter, env, AUTH_OPS.deleteMyAccount, vars);
+  await clearSession(adapter);
+  return result;
+}
 async function signOut(adapter, env) {
   const token = await getSessionToken(adapter);
   if (token) {
@@ -1564,6 +1569,12 @@ var GRANT_TABLE = [
   ["operations:write", "none", [], []],
   ["operations:complete", "none", [], []],
   ["status:write", "none", [], []],
+  ["agents:read", "none", [], []],
+  ["agents:execute", "agent", [], []],
+  ["agents:write", "none", [], []],
+  ["agenttools:execute", "agent_tool", [], []],
+  ["brief:read", "none", [], []],
+  ["brief:write", "none", [], []],
   ["appconfig:read", "none", [], []],
   ["schedules:read", "none", [], []],
   ["schedules:write", "none", [], []],
@@ -1613,7 +1624,7 @@ var GRANT_TABLE = [
   ["projects:read", "none", [], []],
   ["projects:write", "none", [], []],
   ["project:stand", "none", [], []],
-  ["project:manage", "none", [], ["project:stand", "records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:setup", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "authclients:read", "authclients:write", "domains:read", "domains:write", "loginpages:read", "loginpages:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "orgsettings:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
+  ["project:manage", "none", [], ["project:stand", "records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:setup", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "agents:read", "agents:execute", "agents:write", "agenttools:execute", "brief:read", "brief:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "authclients:read", "authclients:write", "domains:read", "domains:write", "loginpages:read", "loginpages:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "orgsettings:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
   ["projects:create", "none", [], []],
   ["projects:delete", "none", [], []],
   ["tenants:read", "none", [], []],
@@ -2237,6 +2248,7 @@ export {
   createPersonalAccessToken,
   currentUser,
   deleteMyAccount,
+  deleteMyAccountAndSignOut,
   disconnectSignInMethod,
   endMySession,
   exportMyData,

package/dist/client/platform-client.d.ts

@@ -21,7 +21,7 @@ export declare class PlatformClientError extends Error {
  * });
  *
  * const { data } = await client.query(
- *   `query GetProduct($id: ID!) { product(id: $id) { title } }`,
+ *   `query GetProduct($id: String!) { product(id: $id) { title } }`,
  *   { id: '123' }
  * );
  * ```

package/dist/data/agents.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Talking to a project's agents from a site: send a message, follow the run as
+ * it answers, and keep a visitor's conversation theirs.
+ *
+ * ```ts
+ * const reply = await askAgent(foir, {
+ *   agent: 'ask_about_foir',
+ *   message: 'How do releases work?',
+ *   visitorToken: visitorToken(),
+ *   onText: (delta) => render(delta),
+ * });
+ * // reply.threadId continues the conversation
+ * ```
+ *
+ * The run is the platform's: it charges `agents:execute` for the agent to the
+ * caller, signed in or a visitor through a key that gives it, and a refusal
+ * (a message too long, a limit reached, the safety check) comes back as the
+ * run's answer, not as an error. Only a call the platform could not take at
+ * all throws.
+ */
+import type { FoirAgentAttachment, FoirAgentAttachmentUpload, FoirAgentRun, FoirAgentRunStatus, FoirCreateAgentAttachmentArgs, FoirStartAgentRunArgs } from './builtins';
+import type { FoirAgentRunEvent, FoirAgentRunSubscribeOptions } from './subscriptions';
+import type { FoirSubscription } from './ws-transport';
+/** What `askAgent` needs of a client: the agents namespace a key that runs an agent is given. */
+export interface FoirAgentsClient {
+    ns: {
+        agents: {
+            startAgentRun(args: FoirStartAgentRunArgs): Promise<FoirAgentRun>;
+            onRun(options: FoirAgentRunSubscribeOptions): FoirSubscription;
+        };
+    };
+}
+/** What `uploadAgentFile` needs of a client. */
+export interface FoirAgentFilesClient {
+    ns: {
+        agents: {
+            createAgentAttachment(args: FoirCreateAgentAttachmentArgs): Promise<FoirAgentAttachmentUpload>;
+        };
+    };
+}
+/**
+ * A file to send an agent: a `File` from an input or a paste, or bytes with
+ * their type. An image (PNG, JPEG, GIF or WebP) of at most 5 MB, or a PDF of
+ * at most 10 MB; a visitor may send images only.
+ */
+export type FoirAgentFile = Blob | {
+    data: Blob | ArrayBuffer | Uint8Array;
+    mediaType: string;
+    filename?: string;
+};
+/**
+ * Upload a file to send an agent, and answer with the attachment to pass as
+ * one of `attachmentIds`. The bytes go straight to the project's storage; the
+ * attachment is read only through the conversation it is sent in.
+ */
+export declare function uploadAgentFile(foir: FoirAgentFilesClient | {
+    readonly ns: object;
+}, options: {
+    agent: string;
+    file: FoirAgentFile;
+    visitorToken?: string;
+    fetch?: typeof fetch;
+}): Promise<FoirAgentAttachment>;
+export interface AskAgentOptions extends FoirStartAgentRunArgs {
+    /** Files sent with the message: each is uploaded first, then sent by its id. At most 5. */
+    files?: FoirAgentFile[];
+    /** Each piece of the answer as it is written. */
+    onText?: (delta: string) => void;
+    /** Every event of the run, for a caller that renders its steps. */
+    onEvent?: (event: FoirAgentRunEvent) => void;
+    /** Stop following the run; the run itself goes on. */
+    signal?: AbortSignal;
+}
+export interface AgentReply {
+    runId: string;
+    /** Pass as `threadId` to go on with the conversation. */
+    threadId: string | null;
+    status: FoirAgentRunStatus;
+    /** The answer, or the reason the run was refused. */
+    answer: string;
+    error: string | null;
+    /** An agent with an output schema: its typed answer, a value that fits the schema. */
+    output?: unknown;
+}
+/**
+ * Send an agent a message and follow its run until it has answered, or holds
+ * an act for someone's decision.
+ *
+ * It takes any client `createFoirClient` makes, generated or not: the agents
+ * are offered by the key the client was made with, and a client whose key runs
+ * no agent is refused here, by name.
+ */
+export declare function askAgent(foir: FoirAgentsClient | {
+    readonly ns: object;
+}, options: AskAgentOptions): Promise<AgentReply>;
+/**
+ * The secret a visitor's browser keeps for their runs and threads: made once
+ * and kept, so the conversation they start is theirs when they come back. The
+ * platform keeps only its hash.
+ *
+ * Where nothing can be kept (a private window, a server render), a fresh one
+ * is made for the page, and the conversation lasts as long as it does.
+ */
+export declare function visitorToken(storage?: Pick<Storage, 'getItem' | 'setItem'> | null, key?: string): string;

package/dist/data/builtins.d.ts

@@ -678,3 +678,185 @@ export interface FoirResolveContext {
         longitude: number;
     } | null;
 }
+/**
+ * Where a run, or one step of it, stands. HELD waits for a decision on an act
+ * it holds, or for an operation to answer; SKIPPED was refused or denied and
+ * never ran.
+ */
+export type FoirAgentRunStatus = 'SCHEDULED' | 'STARTED' | 'HELD' | 'COMPLETED' | 'FAILED' | 'SKIPPED' | 'CANCELLED';
+/** An act a run holds until someone decides it. */
+export interface FoirAgentApproval {
+    /** What the act would do, in words. */
+    summary: string;
+    /** CALLER: the person who started the run decides it. TEAM: the project's team does. */
+    approver: 'CALLER' | 'TEAM';
+    decision: 'PENDING' | 'APPROVED' | 'DENIED' | 'EXPIRED';
+    reason?: string | null;
+}
+/** One step of a run: a model turn, a tool call, a check, or a child agent. */
+export interface FoirAgentRunNode {
+    id: string;
+    parentId?: string | null;
+    /**
+     * PAGE_TOOL is a call to a tool the caller's page offered with the message,
+     * HELD until the page answers it with `answerPageTool`; DATA is data sent to
+     * the app's components, delivered as a DATA event.
+     */
+    kind: 'AGENT' | 'OPERATION' | 'VERB' | 'MCP_TOOL' | 'MODEL_TURN' | 'CHECK' | 'PAGE_TOOL' | 'DATA';
+    /** The tool, operation or agent the step is, by its key. */
+    key: string;
+    status: FoirAgentRunStatus;
+    error?: string | null;
+    input?: unknown;
+    result?: unknown;
+    approval?: FoirAgentApproval | null;
+    /** ISO-8601. */
+    startedAt?: string | null;
+    /** ISO-8601. */
+    completedAt?: string | null;
+}
+/**
+ * A run of an agent: its answer, once given, and every step it took. A refusal
+ * is an answer too: a message the agent will not take ends SKIPPED with the
+ * reason as its answer.
+ */
+export interface FoirAgentRun {
+    id: string;
+    /** The agent's key. */
+    agent: string;
+    /** The thread the run answers in. Pass it as `threadId` to go on talking. */
+    threadId?: string | null;
+    status: FoirAgentRunStatus;
+    answer?: string | null;
+    error?: string | null;
+    /** What the run has spent so far, in credits. */
+    spentCredits: number;
+    nodes: FoirAgentRunNode[];
+    /** An agent with an output schema: its typed answer, once the run has finished. */
+    output?: unknown;
+}
+/** One message of a conversation with an agent. */
+export interface FoirAgentThreadMessage {
+    id: string;
+    seq: number;
+    role: 'USER' | 'ASSISTANT';
+    /** Text, tool calls and their answers, as the run kept them. */
+    parts: unknown[];
+    runId?: string | null;
+    /** ISO-8601. */
+    createdAt?: string | null;
+}
+/** A conversation with an agent, kept for the agent's retention and then deleted. */
+export interface FoirAgentThread {
+    id: string;
+    agent: string;
+    title: string;
+    messageCount: number;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    expiresAt?: string | null;
+    /** Present on `agentThread`; absent in a list of threads. */
+    messages?: FoirAgentThreadMessage[] | null;
+    /** A run still answering in the thread: follow it with `foir.ns.agents.onRun`. */
+    runningRunId?: string | null;
+}
+/**
+ * `startAgentRun` arguments. Requires `agents:execute` for the agent, held by
+ * the signed-in user's role or given by the key to whoever comes through it.
+ */
+export interface FoirStartAgentRunArgs {
+    /** The agent's key. */
+    agent: string;
+    message: string;
+    /** Continue this conversation. Omitted starts a new one. */
+    threadId?: string;
+    /** Sent again after a lost answer, the same key answers with the same run. */
+    idempotencyKey?: string;
+    /**
+     * A visitor with nobody signed in: the secret their browser keeps, which
+     * makes the run and its thread theirs. Make it once per browser and keep it
+     * (see `visitorToken` in `@foir/sdk/agents`).
+     */
+    visitorToken?: string;
+    /**
+     * Files sent with the message, each uploaded first with
+     * `createAgentAttachment` (or `uploadAgentFile`). At most 5; the message
+     * may then be empty.
+     */
+    attachmentIds?: string[];
+    /**
+     * What the message points at, by id: the agent reads each with its own
+     * tools, as the caller, so a tag reaches nothing the caller could not. At
+     * most 20.
+     */
+    tags?: FoirMessageTag[];
+    /**
+     * Tools of the caller's own page the agent may call during this run, for
+     * an agent that allows the page's tools. A call is HELD until the page
+     * answers it with `answerPageTool`. At most 20. `foirChatTransport`'s
+     * `pageTools` sends these and answers the calls for you.
+     */
+    pageTools?: FoirPageToolOffer[];
+}
+/** A tool of the caller's page, offered to an agent for one run. */
+export interface FoirPageToolOffer {
+    /** Lowercase letters, digits and _, starting with a letter; not the name of one of the agent's own tools. */
+    name: string;
+    /** What the tool does, as the model is told it. At most 1000 characters. */
+    description?: string;
+    /** The JSON Schema of the tool's input: an object schema. Left out, the tool takes no input. */
+    inputSchema?: Record<string, unknown>;
+}
+/** What a tag in a message points at. */
+export type FoirMessageTagKind = 'RECORD' | 'MODEL' | 'PERSON' | 'FILE' | 'OPERATION' | 'AGENT' | 'HOOK' | 'SCHEDULE' | 'ORGANIZATION' | 'NOTE' | 'FIELD';
+/** One thing a message points at. It is kept by id and never resolved into the message. */
+export interface FoirMessageTag {
+    kind: FoirMessageTagKind;
+    /** The thing's id, or its key where it is addressed by one (a model, an operation, an agent, a schedule). */
+    id: string;
+    /** A record's or a field's model, by key. */
+    model?: string;
+    /** A field's path within its record. */
+    field?: string;
+    /** What the person saw when they picked it. */
+    label?: string;
+}
+/** A file sent an agent with a message: an image or a PDF. */
+export interface FoirAgentAttachment {
+    id: string;
+    filename: string;
+    mediaType: string;
+    /** Its length in bytes. */
+    size: number;
+}
+/**
+ * `createAgentAttachment` arguments: a PNG, JPEG, GIF or WebP image of at most
+ * 5 MB, or a PDF of at most 10 MB. A visitor may send images only, 20 a day.
+ */
+export interface FoirCreateAgentAttachmentArgs {
+    agent: string;
+    filename: string;
+    mediaType: string;
+    /** The file's exact length in bytes. */
+    size: number;
+    visitorToken?: string;
+}
+/** Where a file's bytes go before it is sent. */
+export interface FoirAgentAttachmentUpload {
+    attachment: FoirAgentAttachment;
+    /** An HTTP PUT of exactly `size` bytes, with `mediaType` as its Content-Type. */
+    uploadUrl: string;
+    /** When `uploadUrl` stops taking bytes; an attachment not sent by then is removed. */
+    expiresAt: string;
+}
+/** `agentThreads` — your conversations with the project's agents, newest first. */
+export type FoirAgentThreadsResult = FoirConnection<FoirAgentThread>;
+/** Your own account at a remote server a project's agent calls for you. */
+export interface FoirMcpConnection {
+    id: string;
+    agent: string;
+    server: string;
+    scopes: string[];
+    connectedAt?: string | null;
+    expiresAt?: string | null;
+}

package/dist/data/index.d.ts

@@ -58,8 +58,8 @@ export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManife
 export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
-export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirWriteNoteArgs, FoirUserNote, FoirUserNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteReceipt, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
+export type { FoirFieldMark, FoirFieldMarkAttributes, FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirWriteNoteArgs, FoirUserNote, FoirUserNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirAgentApproval, FoirAgentAttachment, FoirAgentAttachmentUpload, FoirAgentRun, FoirAgentRunNode, FoirAgentRunStatus, FoirAgentThread, FoirAgentThreadMessage, FoirAgentThreadsResult, FoirMcpConnection, FoirStartAgentRunArgs, FoirPageToolOffer, FoirCreateAgentAttachmentArgs, FoirMessageTag, FoirMessageTagKind, FoirNoteConfig, FoirNoteReceipt, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
  * Pre-rename spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each
@@ -76,10 +76,12 @@ export { foirSocketEndpoint, FoirSocketTransport } from './ws-transport';
 export type { FoirReconnectPolicy, FoirSubscribeRequest, FoirSubscription, FoirSubscriptionHandlers, FoirWebSocketFactory, FoirWebSocketLike, } from './ws-transport';
 export { printSubscriptionDocument } from './subscription-document';
 export type { FoirSubscriptionArgument, PrintSubscriptionDocumentInput, } from './subscription-document';
-export type { FoirChangeSubscribeOptions, FoirExecutionSubscribeOptions, FoirJobProgressEvent, FoirModelSubscriptions, FoirNamespaceSubscriptions, FoirNotificationEvent, FoirOperationExecutionEvent, FoirRecordChangedEvent, } from './subscriptions';
+export type { FoirChangeSubscribeOptions, FoirExecutionSubscribeOptions, FoirAgentRunEvent, FoirAgentRunSubscribeOptions, FoirJobProgressEvent, FoirModelSubscriptions, FoirNamespaceSubscriptions, FoirNotificationEvent, FoirOperationExecutionEvent, FoirRecordChangedEvent, } from './subscriptions';
 export type { FoirConnection, FoirFieldsShape, FoirModelDefinition, FoirNamespaceDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirRelationDefinition, FoirReturnDefinition, FoirSchemaDefinition, } from './schema';
 export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, FoirWriteResult, } from './selection';
 export { FoirDecimal, decimal } from './decimal';
 export type { FoirDecimalDivOptions, FoirDecimalInput, FoirDecimalRounding, } from './decimal';
 export { FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, FOIR_VISITOR_IP_HEADER, stepUpRequired, } from '../transport/foir-http';
 export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, FoirStepUp, FoirVisitor, FoirVisitorSource, } from '../transport/foir-http';
+export { askAgent, uploadAgentFile, visitorToken } from './agents';
+export type { AgentReply, AskAgentOptions, FoirAgentFile, FoirAgentFilesClient, FoirAgentsClient } from './agents';

package/dist/data/subjects.d.ts

@@ -140,6 +140,19 @@ export interface FoirSubjectOptions {
      */
     label?: (record: Readonly<Record<string, unknown>>, subject: FoirSubject) => string | null | undefined;
 }
+/** One field of one record, as an element on the page was marked with it. */
+export interface FoirFieldMark {
+    /** The record the field belongs to. */
+    subject: FoirSubject;
+    /** The field's key on the model, e.g. `summary`, or a nested path. */
+    field: string;
+    /** What to call the field on screen, when the host named it. */
+    label?: string;
+}
+/** What `FoirSubjectRegistry.field` returns: spread it onto the element. */
+export interface FoirFieldMarkAttributes {
+    'data-foir-field': string;
+}
 export interface FoirSubjectRegistry {
     /**
      * Record one subject.
@@ -190,6 +203,38 @@ export interface FoirSubjectRegistry {
      * failure is reported rather than dropped (see `recordFoirSubjects`).
      */
     subscribe(listener: () => void): () => void;
+    /**
+     * Mark an element as showing one field of a record, so a widget can let the
+     * reader point at what they mean. Spread the answer onto the element:
+     *
+     * ```tsx
+     * <h1 {...subjects.field(page, 'title', { label: 'Title' })}>{page.title}</h1>
+     * ```
+     *
+     * The attribute is an opaque token, not the model, record or field: the
+     * registry holds what it stands for, as it holds every subject, so the page
+     * does not print the project's vocabulary. It is the same token for the same
+     * field wherever it is computed, so a server-rendered mark hydrates to the
+     * attribute the server wrote. Call it where the browser renders too: a mark
+     * only a server component made has nothing in the browser to resolve it.
+     *
+     * `label` is the only thing about the field a widget shows. Without one, it
+     * names the record and not the field.
+     */
+    field(subject: Pick<FoirSubject, 'modelKey' | 'recordId'> & {
+        label?: string;
+    }, field: string, options?: {
+        label?: string;
+    }): FoirFieldMarkAttributes;
+    /**
+     * The field a marked element points at, by its `data-foir-field` token.
+     * Undefined for a token this registry did not mark.
+     *
+     * `clear()` keeps the marks. A single-page app clears on navigation, and the
+     * next page may already have rendered its marks by then; a stale mark points
+     * at nothing on screen, so it is never offered.
+     */
+    pointedAt(token: string): FoirFieldMark | undefined;
 }
 /**
  * Build a registry.

package/dist/data/subscriptions.d.ts

@@ -50,6 +50,7 @@
  * round trip in front of every query for good reason; in front of a socket that
  * will live for minutes it is noise.
  */
+import type { FoirAgentRunNode, FoirAgentRunStatus, FoirAgentThreadMessage } from './builtins';
 import type { FoirManifest } from './manifest';
 import type { FoirClientConfig } from './transport';
 import { type FoirSubscription, type FoirSubscriptionHandlers } from './ws-transport';
@@ -108,6 +109,40 @@ export interface FoirOperationExecutionEvent {
     /** Present on `status: failed` or `timed_out`. */
     errorJson?: unknown;
 }
+/**
+ * `agentRun` — one event of an agent's run as it answers.
+ *
+ * TEXT and REASONING carry new text; NODE a step that started, changed or
+ * ended (a tool call, a held act, a child agent); MESSAGE a message kept on
+ * the thread; STATUS where the run now stands. The stream ends after a STATUS
+ * that is final.
+ */
+export interface FoirAgentRunEvent {
+    /** Resume a dropped stream from the last seq seen. */
+    seq: string;
+    kind: 'TEXT' | 'REASONING' | 'NODE' | 'MESSAGE' | 'STATUS' | 'DATA';
+    text?: string | null;
+    messageId?: string | null;
+    node?: FoirAgentRunNode | null;
+    message?: FoirAgentThreadMessage | null;
+    status?: FoirAgentRunStatus | null;
+    answer?: string | null;
+    error?: string | null;
+    /** DATA: which of the agent's data parts, and the data, which fits its schema. */
+    dataName?: string | null;
+    data?: unknown;
+    /** STATUS, once a run of an agent with an output schema has completed: its typed answer. */
+    output?: unknown;
+}
+/** Options for `foir.ns.agents.onRun`. */
+export type FoirAgentRunSubscribeOptions = FoirSubscriptionHandlers<FoirAgentRunEvent> & {
+    /** The run's id, as `startAgentRun` answered it. */
+    id: string;
+    /** Only events after this seq, to resume a dropped stream. */
+    after?: string;
+    /** A visitor with nobody signed in: the secret their browser keeps. */
+    visitorToken?: string;
+};
 /** Options for `foir.ns.operations.onExecution`. */
 export type FoirExecutionSubscribeOptions = FoirSubscriptionHandlers<FoirOperationExecutionEvent> & {
     /** Execution id, as returned by `execute<Op>`. */
@@ -168,6 +203,9 @@ export type FoirNamespaceSubscriptions<NK> = NK extends 'notifications' ? {
     onJobProgress(handlers: FoirSubscriptionHandlers<FoirJobProgressEvent>): FoirSubscription;
     /** Stream one operation execution's progress until it reaches a terminal state. */
     onExecution(options: FoirExecutionSubscribeOptions): FoirSubscription;
+} : NK extends 'agents' ? {
+    /** Follow an agent's run as it answers, until its final status. */
+    onRun(options: FoirAgentRunSubscribeOptions): FoirSubscription;
 } : {};
 /** Does this (address, property) pair name a subscription rather than an op? */
 export declare function isModelSubscriptionMethod(name: string): boolean;