@foir/sdk 0.28.0 → 0.30.0

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;

package/dist/data/transport.d.ts

@@ -725,4 +725,5 @@ export declare function executeFoirDocument<T>(config: FoirClientConfig, plan: F
 export declare function executeFoirRawDocument<T>(config: FoirClientConfig, document: string, mutation: boolean, variables?: Record<string, unknown>, options?: {
     strict?: boolean;
 }): Promise<T>;
+export declare function renewBearerOnce(refresh: () => Promise<string | null>): Promise<string | null>;
 export {};

package/dist/data/ws-transport.d.ts

@@ -149,6 +149,7 @@ export declare class FoirSocketTransport {
     private disposed;
     private keepAlive;
     private retryTimer;
+    private renewedBearer;
     constructor(config: FoirRequestConfig);
     /**
      * Start a subscription.
@@ -167,6 +168,14 @@ export declare class FoirSocketTransport {
     private ensureConnected;
     private sendConnectionInit;
     private handleClose;
+    /**
+     * Reconnect after the socket's credential lapsed: with the bearer renewed
+     * through the client's `refreshBearer` where it has one, failing every
+     * subscription with `FoirSessionExpiredError` when the session is over. A
+     * client without one reconnects at once, presenting what its bearer
+     * provider gives now.
+     */
+    private reconnectWithARenewedBearer;
     private scheduleReconnect;
     private teardownSocket;
     private receive;

package/dist/data.js

@@ -1380,6 +1380,8 @@ function printSubscriptionDocument(input) {
 }
 
 // src/data/ws-transport.ts
+var CLOSE_CREDENTIAL_ENDED = 4402;
+var CLOSE_FORBIDDEN = 4403;
 var GQL = {
   connectionInit: "connection_init",
   connectionAck: "connection_ack",
@@ -1414,6 +1416,9 @@ var FoirSocketTransport = class {
   disposed = false;
   keepAlive = null;
   retryTimer = null;
+  // A bearer renewed after the socket's lapsed (4402), presented from the next
+  // connect on in place of the client's own.
+  renewedBearer = null;
   constructor(config) {
     if (config.dispatch !== void 0) {
       throw new FoirRequestError(
@@ -1486,12 +1491,14 @@ var FoirSocketTransport = class {
     socket.onmessage = (event) => this.receive(event.data);
     socket.onerror = () => {
     };
-    socket.onclose = () => this.handleClose();
+    socket.onclose = (event) => this.handleClose(event);
   }
   async sendConnectionInit(socket) {
     this.connecting = false;
     try {
-      const { headers } = await resolveFoirAuth(this.config);
+      const { headers } = await resolveFoirAuth(
+        this.renewedBearer ? { ...this.config, bearerToken: this.renewedBearer } : this.config
+      );
       const { "Content-Type": _contentType, ...params } = headers;
       const extra = await this.config.connectionParams?.() ?? {};
       this.send(socket, {
@@ -1505,19 +1512,53 @@ var FoirSocketTransport = class {
       this.teardownSocket(true);
     }
   }
-  handleClose() {
+  handleClose(event) {
+    const code = event?.code;
     const wasAcknowledged = this.acknowledged;
     this.teardownSocket(false);
     if (this.disposed || this.registrations.size === 0) return;
     for (const registration of this.registrations.values()) {
       registration.sent = false;
     }
+    if (code === CLOSE_FORBIDDEN) {
+      this.failAll(
+        new FoirRequestError(
+          "[foir] the subscription socket was refused where it asked to stand: the signed-in user is no member of the organization this client names"
+        )
+      );
+      return;
+    }
+    if (code === CLOSE_CREDENTIAL_ENDED) {
+      void this.reconnectWithARenewedBearer();
+      return;
+    }
     this.scheduleReconnect(
       new FoirRequestError(
         wasAcknowledged ? "[foir] the subscription socket closed and could not be re-established" : "[foir] the subscription socket closed before the credential was accepted"
       )
     );
   }
+  /**
+   * Reconnect after the socket's credential lapsed: with the bearer renewed
+   * through the client's `refreshBearer` where it has one, failing every
+   * subscription with `FoirSessionExpiredError` when the session is over. A
+   * client without one reconnects at once, presenting what its bearer
+   * provider gives now.
+   */
+  async reconnectWithARenewedBearer() {
+    const refresh = this.config.refreshBearer;
+    if (refresh) {
+      const token = await renewBearerOnce(refresh).catch(() => null);
+      if (this.disposed) return;
+      if (!token) {
+        this.failAll(new FoirSessionExpiredError());
+        return;
+      }
+      this.renewedBearer = token;
+    }
+    this.attempt = 0;
+    this.ensureConnected();
+  }
   scheduleReconnect(error) {
     if (this.disposed || this.registrations.size === 0) return;
     if (this.attempt >= this.policy.maxAttempts) {
@@ -1741,7 +1782,8 @@ function describe(payload) {
 var MODEL_SUBSCRIPTION_METHODS = /* @__PURE__ */ new Set(["onChange"]);
 var NAMESPACE_SUBSCRIPTION_METHODS = {
   notifications: /* @__PURE__ */ new Set(["onNotification"]),
-  operations: /* @__PURE__ */ new Set(["onJobProgress", "onExecution"])
+  operations: /* @__PURE__ */ new Set(["onJobProgress", "onExecution"]),
+  agents: /* @__PURE__ */ new Set(["onRun"])
 };
 function isModelSubscriptionMethod(name) {
   return MODEL_SUBSCRIPTION_METHODS.has(name);
@@ -1825,6 +1867,25 @@ var FoirSubscriptionRouter = class {
         { ...handlers, onData: (event) => handlers.onData(executionEventWithEnumStatus(event)) }
       );
     }
+    if (namespace === "agents" && method === "onRun") {
+      const id = input.id;
+      if (typeof id !== "string" || id === "") {
+        throw new FoirRequestError("[foir] onRun requires a run `id`");
+      }
+      const args = [{ name: "id", type: "String!" }];
+      const variables = { id };
+      for (const name of ["after", "visitorToken"]) {
+        const v = input[name];
+        if (typeof v === "string" && v !== "") {
+          args.push({ name, type: "String" });
+          variables[name] = v;
+        }
+      }
+      return this.open(
+        { field: "agentRun", operationName: "FoirAgentRun", args, variables },
+        handlers
+      );
+    }
     throw new FoirRequestError(`[foir] ns.${namespace}.${method} is not a subscription`);
   }
   /**
@@ -1908,12 +1969,24 @@ function normalise(value) {
 }
 
 // src/data/subjects.ts
+function markToken(modelKey, recordId, field) {
+  const text = `${modelKey}\0${recordId}\0${field}`;
+  let fnv = 2166136261;
+  let djb = 5381;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    fnv = Math.imul(fnv ^ code, 16777619) >>> 0;
+    djb = (Math.imul(djb, 33) ^ code) >>> 0;
+  }
+  return `f${fnv.toString(36)}${djb.toString(36)}`;
+}
 var keyOf = (modelKey, recordId) => `${modelKey}\0${recordId}`;
 function createFoirSubjectRegistry(options = {}) {
   const held = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
   const pinned = { subject: null };
   const latest = { key: null };
+  const marks = /* @__PURE__ */ new Map();
   const notify = () => {
     const failures = [];
     for (const listener of [...listeners]) {
@@ -1984,6 +2057,25 @@ function createFoirSubjectRegistry(options = {}) {
       return () => {
         listeners.delete(listener);
       };
+    },
+    field(subject, field, fieldOptions = {}) {
+      if (!subject.modelKey || !subject.recordId || !field) {
+        throw new FoirRequestError(
+          "[foir] a field mark needs a modelKey, a recordId and a field \u2014 a mark missing one points at nothing a note can be filed against"
+        );
+      }
+      const token = markToken(subject.modelKey, subject.recordId, field);
+      const mark = {
+        subject: { modelKey: subject.modelKey, recordId: subject.recordId },
+        field
+      };
+      if (subject.label) mark.subject.label = subject.label;
+      if (fieldOptions.label) mark.label = fieldOptions.label;
+      marks.set(token, mark);
+      return { "data-foir-field": token };
+    },
+    pointedAt(token) {
+      return marks.get(token);
     }
   };
 }
@@ -2675,6 +2767,119 @@ var FoirDecimal = class _FoirDecimal {
 function decimal(value) {
   return new FoirDecimal(value);
 }
+
+// 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 FINAL = /* @__PURE__ */ new Set(["COMPLETED", "FAILED", "SKIPPED", "CANCELLED", "HELD"]);
+async function askAgent(foir, options) {
+  const agents = foir.ns.agents;
+  if (typeof agents?.startAgentRun !== "function" || typeof agents.onRun !== "function") {
+    throw new Error(
+      "[foir] askAgent: this client offers no agents. Its key runs none of the project's agents (agents:execute), or the project has released none."
+    );
+  }
+  const { onText, onEvent, signal, files, ...args } = options;
+  if (files?.length) {
+    const sent = await Promise.all(files.map((file) => uploadAgentFile(foir, { agent: args.agent, file, visitorToken: args.visitorToken })));
+    args.attachmentIds = [...args.attachmentIds ?? [], ...sent.map((a) => a.id)];
+  }
+  const run = await agents.startAgentRun(args);
+  const reply = {
+    runId: run.id,
+    threadId: run.threadId ?? null,
+    status: run.status,
+    answer: run.answer ?? "",
+    error: run.error ?? null,
+    ...run.output === void 0 || run.output === null ? {} : { output: run.output }
+  };
+  if (FINAL.has(run.status) && run.status !== "HELD") return reply;
+  let written = "";
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (sub2, err) => {
+      if (settled) return;
+      settled = true;
+      sub2?.unsubscribe();
+      if (err !== void 0) reject(err);
+      else resolve({ ...reply, answer: reply.answer || written });
+    };
+    let sub = null;
+    sub = agents.onRun({
+      id: run.id,
+      visitorToken: args.visitorToken,
+      onData: (event) => {
+        onEvent?.(event);
+        if (event.kind === "TEXT" && event.text) {
+          written += event.text;
+          onText?.(event.text);
+        }
+        if (event.kind === "STATUS" && event.status) {
+          reply.status = event.status;
+          if (event.answer) reply.answer = event.answer;
+          if (event.error) reply.error = event.error;
+          if (event.output !== void 0 && event.output !== null) reply.output = event.output;
+          if (FINAL.has(event.status)) finish(sub);
+        }
+      },
+      onError: (err) => finish(sub, err),
+      onComplete: () => finish(sub)
+    });
+    signal?.addEventListener("abort", () => finish(sub), { once: true });
+  });
+}
+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;
+}
 export {
   FOIR_VISITOR_IP_HEADER,
   FoirAuthDowngradedError,
@@ -2683,6 +2888,7 @@ export {
   FoirSchemaDriftError,
   FoirSessionExpiredError,
   FoirSocketTransport,
+  askAgent,
   createFoirClient,
   createFoirClientFromEnv,
   createFoirSubjectRegistry,
@@ -2696,5 +2902,7 @@ export {
   planFoirNamespaceCall,
   printSubscriptionDocument,
   recordFoirSubjects,
-  stepUpRequired
+  stepUpRequired,
+  uploadAgentFile,
+  visitorToken
 };