@colixsystems/widget-sdk 0.147.0 → 0.148.0

package/README.md

@@ -47,6 +47,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
+| **AGENTS** | `useAgent(agentRef)` | `{ send, reset, messages, sending, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance). **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
 | **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
@@ -71,7 +72,29 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.147.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.148.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.148.0 (contract 1.116.0)
+
+**New `useAgent(agentRef)` hook — a widget can talk to the WORKSPACE's own AI agent (sc-7991).** A new `agents` host client (`@colixsystems/agents-client`), a new `agentRef` propertySchema type and a new `ai.invoke:*` scope. Everything is additive; nothing existing changes shape.
+
+A workspace **agent** is a name plus a system prompt its author wrote in the Studio. This hook lets any widget hold a conversation with one, without touching HTTP and without ever holding an API key.
+
+```js
+const { send, reset, messages, sending, error, available } = useAgent(props.agentId);
+```
+
+**What a widget deliberately cannot do.** You cannot set the system prompt, send your own transcript, or pick a model, and no API surface returns the prompt. The server assembles every turn from the stored prompt plus the stored history, and `content` is the only field that reaches the wire — not because the rest is filtered out, but because nothing else is ever sent. That guarantee is about the WIRE, not about secrecy: a model can be talked into repeating its own prompt, so an agent's prompt is not a secret store — never put credentials, or data the app's users may not see, in one. `messages` is the transcript this widget has seen; the real one is the server's.
+
+**Imperative, like `useInterpretDraft`.** It never fires on mount, and the FIRST `send` opens the conversation — so a widget an author places and nobody types into costs the workspace nothing.
+
+**Bind it with an `agentRef` property.** Declare `{ type: "agentRef" }` in your `propertySchema` and the Studio renders an agent picker; the value is the agent id you pass to `useAgent`. It is a bare UUID like `pageRef` / `groupRef`, so Copy Workspace carries a bound widget over to the copied workspace's own agent.
+
+**Every send spends the workspace's AI credits**, and is rate-limited per caller *and* per workspace. Branch on `AgentError.code`: `AI_QUOTA_EXCEEDED` (429) is the credit ceiling and will **not** clear on a retry — offering "try again" there is worse than useless — where `RATE_LIMITED` (429) will. `AGENT_DISABLED` (409) means the author switched the agent off, so hide the affordance rather than retrying. Never show an app user a raw error or the workspace's billing state: they have not heard of an AI credit and cannot buy one.
+
+**`available: false` is a render state, not an error.** It means no agent is bound, or this host brokers no agents client (an unbound canvas preview). Render a visible unbound state — never a blank box.
+
+The linter rejects `useAgent()` unless your manifest declares `ai.invoke:*` in `requestedScopes`.
 
 ### What's new in 0.147.0 (contract 1.115.0)
 
@@ -84,6 +107,7 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 **No shipped app moved.** A backfill (`20270123000000_sc8033_footer_tokens_uncouple`) materialised into each workspace's `footer` block exactly what it had been inheriting, and split every stored `activeColor` onto the key that says which half it meant. Nothing is written where the old chain ended in a default the new one also ends in.
 
+
 ### What's new in 0.146.0 (contract 1.114.0)
 
 **The chrome divider's width is bounded in the resolver, so both hosts agree (sc-7965).** `resolveFooterTokens` and `resolveSidebarTokens` returned `borderWidth` as any finite number. Only the export bounded it — on its way into the StyleSheet — so a stored `1e9` ruled a **billion-pixel border across the published web app** and a normal one in the exported app. The clamp moved into the shared resolver, where both hosts inherit it.

package/dist/contract.cjs

@@ -1172,6 +1172,47 @@ const HOOKS = [
     requiredContextSlice: ["datastore.interpret"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useAgent",
+    signature: "useAgent(agentRef)",
+    description:
+      "sc-7991 — hold a conversation with one of the WORKSPACE's own AI " +
+      "agents (an author-written name + system prompt). IMPERATIVE: call " +
+      "send(text) from an event handler, never on mount — the first send " +
+      "opens the conversation, so a widget nobody types into costs nothing. " +
+      "`messages` is the running transcript, oldest first, each " +
+      "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
+      "You CANNOT set the system prompt, replay an edited transcript, " +
+      "or pick a model. No API returns the prompt — but that is a guarantee " +
+      "about the WIRE, not secrecy: a model can be talked into repeating its " +
+      "own prompt, so never put credentials or hidden data in one. " +
+      "or pick a model: the server assembles every turn from the stored " +
+      "prompt plus the stored history, and `content` is the only thing that " +
+      "goes on the wire. `agentRef` is an agent id an author bound through an " +
+      "`agentRef` property — when it is missing, or the host brokers no " +
+      "agents client, `available` is false and send() rejects UNAVAILABLE; " +
+      "render a visible unbound state, NEVER a blank box. reset() drops the " +
+      "thread and clears the transcript (a 'new chat' affordance). " +
+      "Every send spends the workspace's AI CREDITS and is rate-limited per " +
+      "caller AND per workspace, so call it once per user action. " +
+      "AgentError.code distinguishes the refusals that share a status: " +
+      "AI_QUOTA_EXCEEDED (429) is the workspace's credit ceiling and will " +
+      "NOT clear on a retry — never offer 'try again' for it — where " +
+      "RATE_LIMITED (429) will; AGENT_DISABLED (409) means the author turned " +
+      "it off, so hide the affordance rather than retrying. NEVER surface a " +
+      "raw error or the workspace's billing state to an app user. " +
+      "Reads ctx.agents.",
+    returnShape: {
+      send: "(text) => Promise<{ id, role, content, created_at } | null>",
+      reset: "() => void",
+      messages: "Array<{ id, conversation_id, role, content, created_at }>",
+      sending: "boolean",
+      error: "AgentError | null",
+      available: "boolean  // false when no agent is bound, or the host brokers none",
+    },
+    requiredContextSlice: ["agents.conversations"],
+    scopes: ["ai.invoke:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -2271,6 +2312,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { params: "object", set: "function" },
   },
+  agents: {
+    description:
+      "sc-7991 — injected @colixsystems/agents-client instance. " +
+      "{ conversations(agentId) -> { create(), list(query), remove(conversationId), " +
+      "messages(conversationId) -> { list(query), send({ content }) } } }. " +
+      "Backs useAgent(). The workspace's agent owns the system prompt and the " +
+      "server owns the transcript, so `send` puts ONLY `content` on the wire — " +
+      "a prompt, a history or a model id cannot be smuggled through. " +
+      "A conversation belongs to the CALLER (the app user, or the studio user " +
+      "previewing on the canvas); another user's id is a 404, never a 403. " +
+      "Absent on a host that brokers no agents (an unbound preview), where " +
+      "useAgent() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { conversations: "function" },
+  },
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
@@ -4054,6 +4110,10 @@ const CONTRACT = deepFreeze({
   //    and the inherited colours are hex-guarded on the way out as well as in.
   //    Every colour still falls back to the sidebar's: an untouched workspace is
   //    unchanged.
+  // 1.116.0: additive (sc-7991) — `useAgent(agentRef)` + the `agents` host
+  // client + the `agentRef` propertySchema type + the `ai.invoke:*` scope. A
+  // widget can hold a conversation with one of the WORKSPACE's own AI agents.
+  // Nothing existing changes shape.
   // 1.114.0: behaviour (sc-7965) — `resolveFooterTokens` / `resolveSidebarTokens`
   //    now return a `borderWidth` CLAMPED to 1-8 instead of any finite number.
   //    The bound lived only in the export (`coerceBorderWidth(...) ?? 1`), so a
@@ -4080,7 +4140,7 @@ const CONTRACT = deepFreeze({
   //    where the rail's and the header's keep sc-7965's 1-8 clamp. A backfill
   //    (`20270123000000_sc8033_footer_tokens_uncouple`) materialised what each
   //    workspace was inheriting, so no shipped app moved.
-  version: "1.115.0",
+  version: "1.116.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1172,6 +1172,47 @@ const HOOKS = [
     requiredContextSlice: ["datastore.interpret"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useAgent",
+    signature: "useAgent(agentRef)",
+    description:
+      "sc-7991 — hold a conversation with one of the WORKSPACE's own AI " +
+      "agents (an author-written name + system prompt). IMPERATIVE: call " +
+      "send(text) from an event handler, never on mount — the first send " +
+      "opens the conversation, so a widget nobody types into costs nothing. " +
+      "`messages` is the running transcript, oldest first, each " +
+      "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
+      "You CANNOT set the system prompt, replay an edited transcript, " +
+      "or pick a model. No API returns the prompt — but that is a guarantee " +
+      "about the WIRE, not secrecy: a model can be talked into repeating its " +
+      "own prompt, so never put credentials or hidden data in one. " +
+      "or pick a model: the server assembles every turn from the stored " +
+      "prompt plus the stored history, and `content` is the only thing that " +
+      "goes on the wire. `agentRef` is an agent id an author bound through an " +
+      "`agentRef` property — when it is missing, or the host brokers no " +
+      "agents client, `available` is false and send() rejects UNAVAILABLE; " +
+      "render a visible unbound state, NEVER a blank box. reset() drops the " +
+      "thread and clears the transcript (a 'new chat' affordance). " +
+      "Every send spends the workspace's AI CREDITS and is rate-limited per " +
+      "caller AND per workspace, so call it once per user action. " +
+      "AgentError.code distinguishes the refusals that share a status: " +
+      "AI_QUOTA_EXCEEDED (429) is the workspace's credit ceiling and will " +
+      "NOT clear on a retry — never offer 'try again' for it — where " +
+      "RATE_LIMITED (429) will; AGENT_DISABLED (409) means the author turned " +
+      "it off, so hide the affordance rather than retrying. NEVER surface a " +
+      "raw error or the workspace's billing state to an app user. " +
+      "Reads ctx.agents.",
+    returnShape: {
+      send: "(text) => Promise<{ id, role, content, created_at } | null>",
+      reset: "() => void",
+      messages: "Array<{ id, conversation_id, role, content, created_at }>",
+      sending: "boolean",
+      error: "AgentError | null",
+      available: "boolean  // false when no agent is bound, or the host brokers none",
+    },
+    requiredContextSlice: ["agents.conversations"],
+    scopes: ["ai.invoke:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -2267,6 +2308,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { params: "object", set: "function" },
   },
+  agents: {
+    description:
+      "sc-7991 — injected @colixsystems/agents-client instance. " +
+      "{ conversations(agentId) -> { create(), list(query), remove(conversationId), " +
+      "messages(conversationId) -> { list(query), send({ content }) } } }. " +
+      "Backs useAgent(). The workspace's agent owns the system prompt and the " +
+      "server owns the transcript, so `send` puts ONLY `content` on the wire — " +
+      "a prompt, a history or a model id cannot be smuggled through. " +
+      "A conversation belongs to the CALLER (the app user, or the studio user " +
+      "previewing on the canvas); another user's id is a 404, never a 403. " +
+      "Absent on a host that brokers no agents (an unbound preview), where " +
+      "useAgent() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { conversations: "function" },
+  },
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
@@ -4050,6 +4106,10 @@ const CONTRACT = deepFreeze({
   //    and the inherited colours are hex-guarded on the way out as well as in.
   //    Every colour still falls back to the sidebar's: an untouched workspace is
   //    unchanged.
+  // 1.116.0: additive (sc-7991) — `useAgent(agentRef)` + the `agents` host
+  // client + the `agentRef` propertySchema type + the `ai.invoke:*` scope. A
+  // widget can hold a conversation with one of the WORKSPACE's own AI agents.
+  // Nothing existing changes shape.
   // 1.114.0: behaviour (sc-7965) — `resolveFooterTokens` / `resolveSidebarTokens`
   //    now return a `borderWidth` CLAMPED to 1-8 instead of any finite number.
   //    The bound lived only in the export (`coerceBorderWidth(...) ?? 1`), so a
@@ -4076,7 +4136,7 @@ const CONTRACT = deepFreeze({
   //    where the rail's and the header's keep sc-7965's 1-8 clamp. A backfill
   //    (`20270123000000_sc8033_footer_tokens_uncouple`) materialised what each
   //    workspace was inheriting, so no shipped app moved.
-  version: "1.115.0",
+  version: "1.116.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2694,6 +2694,196 @@ export function useInterpretDraft(tableId) {
   return { interpret, interpreting, error, result, available };
 }
 
+/**
+ * sc-7991 — structured error thrown by `useAgent().send`. Carries a stable
+ * `code` so widgets branch without parsing message strings; mirrors the shape
+ * of `TranslateError` / `NotificationError`.
+ *
+ * `code` is one of:
+ *   - "UNAVAILABLE"           — the host brokers no agents client, or no agent
+ *                               is bound (the widget should render its unbound
+ *                               state, not an error)
+ *   - "AGENT_NOT_FOUND"       — 404 (the bound agent was deleted)
+ *   - "AGENT_DISABLED"        — 409 (the author turned it off; it still exists)
+ *   - "CONVERSATION_NOT_FOUND"— 404 (a stale thread; `reset()` starts a new one)
+ *   - "INVALID_MESSAGE"       — 400 (empty, or past the length cap)
+ *   - "AI_QUOTA_EXCEEDED"     — 429 (the WORKSPACE is out of AI credit; this
+ *                               does NOT clear by retrying — say so)
+ *   - "RATE_LIMITED"          — 429 (too many turns — retry shortly)
+ *   - "AI_UNAVAILABLE"        — 503 (no AI provider configured)
+ *   - "AI_GENERATION_FAILED"  — 502 (the provider did not answer)
+ *   - "AUTH_REQUIRED"         — 401 (no signed-in app user)
+ *   - "INTERNAL"              — anything else (network, 5xx)
+ */
+export class AgentError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "AgentError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toAgentError(err) {
+  if (err instanceof AgentError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : err && typeof err.status === "number"
+        ? err.status
+        : null;
+  const bodyCode =
+    (err && err.response && err.response.data && err.response.data.code) ||
+    (err && typeof err.code === "string" ? err.code : null);
+  const bodyMessage =
+    (err && err.response && err.response.data && err.response.data.message) ||
+    (err && err.message) ||
+    "The agent could not answer";
+  let code = "INTERNAL";
+  if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
+  else if (status === 401) code = "AUTH_REQUIRED";
+  else if (status === 429) code = "RATE_LIMITED";
+  else if (status === 400) code = "INVALID_MESSAGE";
+  else if (status === 409) code = "AGENT_DISABLED";
+  else if (status === 404) code = "AGENT_NOT_FOUND";
+  else if (status === 502) code = "AI_GENERATION_FAILED";
+  else if (status === 503) code = "AI_UNAVAILABLE";
+  return new AgentError(code, bodyMessage, { cause: err });
+}
+
+/**
+ * sc-7991 — hold a conversation with a workspace-authored AI agent.
+ * Returns `{ send, reset, messages, sending, error, available }`.
+ *
+ *   send(text) → Promise<{ role, content }>   the agent's reply
+ *
+ * The hook is IMPERATIVE — it NEVER fires on mount; the widget calls `send`
+ * from an event handler. The first `send` opens the conversation, so an author
+ * who places the widget and never types costs the workspace nothing.
+ *
+ * `messages` is the running transcript this widget has seen, oldest first,
+ * each `{ id, role, content, created_at }` with `role` of "user" | "assistant".
+ * The SERVER owns the real transcript and the system prompt: the widget sends
+ * one message and can neither read nor set the prompt.
+ *
+ * `agentRef` is the agent id an author bound through an `agentRef` property.
+ * When it is absent, or the host brokers no agents client (an unbound canvas
+ * preview), `available` is false and `send` rejects UNAVAILABLE rather than
+ * throwing at render — the widget must render a visible unbound state, never a
+ * blank box (CLAUDE.md §8).
+ *
+ * Routes through the injected `@colixsystems/agents-client` at `ctx.agents`,
+ * so the Player and the Expo export resolve against the identical client.
+ */
+export function useAgent(agentRef) {
+  const ctx = useWidgetContextOrThrow("useAgent");
+  const available =
+    Boolean(agentRef) &&
+    Boolean(ctx.agents) &&
+    typeof ctx.agents.conversations === "function";
+
+  const clientRef = useRef(available ? ctx.agents : null);
+  clientRef.current = available ? ctx.agents : null;
+  const agentIdRef = useRef(agentRef);
+  agentIdRef.current = agentRef;
+  // The open thread, held as the in-flight PROMISE rather than the id.
+  //
+  // A ref alone only fixes the SEQUENTIAL case. `if (!id) { id = await create() }`
+  // reads the guard before the await and writes it after, so two overlapping
+  // sends — a double-tap, or a widget sending on each keystroke — both see null,
+  // both open a conversation, and both spend a paid turn. Latching the promise
+  // makes the second caller await the FIRST create instead of starting another.
+  const conversationRef = useRef(null);
+
+  const [messages, setMessages] = useState([]);
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState(null);
+
+  // Set during render when the binding changes; consumed below. A setState in
+  // the render body would be a cascading re-render, so the flag is applied to
+  // the value this render returns instead.
+  const pendingResetRef = useRef(false);
+
+  // A changed binding is a different agent, so neither the open thread nor the
+  // transcript carries — leaving the messages would render agent A's
+  // conversation underneath agent B.
+  const boundRef = useRef(agentRef);
+  if (boundRef.current !== agentRef) {
+    boundRef.current = agentRef;
+    conversationRef.current = null;
+    pendingResetRef.current = true;
+  }
+
+  const reset = useCallback(() => {
+    conversationRef.current = null;
+    setMessages([]);
+    setError(null);
+  }, []);
+
+  const send = useCallback(async (text) => {
+    const client = clientRef.current;
+    const agentId = agentIdRef.current;
+    if (!client || !agentId) {
+      throw new AgentError("UNAVAILABLE", "No agent is available for this host");
+    }
+    const content = typeof text === "string" ? text.trim() : "";
+    if (!content) {
+      throw new AgentError("INVALID_MESSAGE", "A message is required");
+    }
+
+    setSending(true);
+    setError(null);
+    try {
+      const thread = client.conversations(agentId);
+      if (!conversationRef.current) {
+        // Assigned BEFORE the first await, so a concurrent send joins this one.
+        conversationRef.current = thread.create().then((created) => {
+          const id = created && created.id ? created.id : null;
+          if (!id) {
+            throw new AgentError("INTERNAL", "The conversation could not be opened");
+          }
+          return id;
+        });
+      }
+      let conversationId;
+      try {
+        conversationId = await conversationRef.current;
+      } catch (err) {
+        // A failed open must not wedge the widget on a rejected promise.
+        conversationRef.current = null;
+        throw err;
+      }
+      const turn = await thread.messages(conversationId).send({ content });
+      const userMessage = turn && turn.user_message ? turn.user_message : null;
+      const reply = turn && turn.reply ? turn.reply : null;
+      setMessages((prior) =>
+        prior.concat(userMessage ? [userMessage] : [], reply ? [reply] : []),
+      );
+      setSending(false);
+      return reply;
+    } catch (err) {
+      const e = toAgentError(err);
+      // A stale thread is recoverable on the next send rather than permanently
+      // broken: drop it so the widget opens a fresh one.
+      if (e.code === "CONVERSATION_NOT_FOUND") conversationRef.current = null;
+      setError(e);
+      setSending(false);
+      throw e;
+    }
+  }, []);
+
+  // The binding changed this render: hand back the empty transcript now rather
+  // than one frame of the previous agent's conversation.
+  let visibleMessages = messages;
+  if (pendingResetRef.current) {
+    pendingResetRef.current = false;
+    visibleMessages = [];
+    if (messages.length > 0) setMessages([]);
+  }
+
+  return { send, reset, messages: visibleMessages, sending, error, available };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Routes through the injected

package/dist/index.d.ts

@@ -663,6 +663,8 @@ export interface WidgetContext<TProps = unknown> {
   notifications: NotificationsClient;
   /** Injected @colixsystems/identification-client; backs useIdentification. */
   identification: IdentificationClient;
+  /** sc-7991 — injected @colixsystems/agents-client backing useAgent(). */
+  agents?: { conversations(agentId: string): unknown };
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
   renderer: { renderNode(node: unknown): unknown };
   events: { emit(eventName: string, payload?: unknown): void };
@@ -1204,6 +1206,36 @@ export function useInterpretDraft(
   tableId: string | null | undefined,
 ): InterpretDraftApi;
 
+export interface AgentMessage {
+  id: string;
+  conversation_id: string;
+  /** The system prompt is NOT part of the transcript — it lives on the agent. */
+  role: "user" | "assistant";
+  content: string;
+  created_at: string;
+}
+
+export interface AgentApi {
+  /** Imperative — call from an event handler. The first send opens the thread. */
+  send(text: string): Promise<AgentMessage | null>;
+  /** Drop the open thread and clear the transcript this widget has seen. */
+  reset(): void;
+  /** Oldest first. The SERVER owns the real transcript. */
+  messages: AgentMessage[];
+  sending: boolean;
+  error: AgentError | null;
+  /** False when no agent is bound, or the host brokers no agents client. */
+  available: boolean;
+}
+
+/**
+ * sc-7991 — hold a conversation with a workspace-authored AI agent.
+ * IMPERATIVE: never fires on mount, so an unused widget costs nothing. The
+ * widget sends ONE message; the system prompt and the real transcript stay
+ * server-side and are never readable or settable from here.
+ */
+export function useAgent(agentRef: string | null | undefined): AgentApi;
+
 // REQ-RT-07 realtime subscription transport state.
 export type DatastoreSubscriptionStatus =
   | "connecting"
@@ -1926,10 +1958,29 @@ export class DirectoryError extends Error {
 }
 
 /**
- * sc-3783 — error class thrown by `useTranslate().translate`. The `code` is a
- * stable categorisation widgets can branch on. TRANSLATION_QUOTA_EXCEEDED and
- * TRANSLATE_NOT_CONFIGURED will not clear on a retry — show the original text.
+ * sc-7991 — structured error thrown by `useAgent().send`. Branch on `code`:
+ * `AI_QUOTA_EXCEEDED` is the workspace's credit ceiling and will NOT clear on
+ * a retry, unlike `RATE_LIMITED`; `AGENT_DISABLED` means the author switched
+ * the agent off; `AI_AGENTS_DISABLED` means the feature is not released for
+ * this workspace. Never show an app user a raw code or the billing state.
  */
+export class AgentError extends Error {
+  code:
+    | "UNAVAILABLE"
+    | "AGENT_NOT_FOUND"
+    | "AGENT_DISABLED"
+    | "CONVERSATION_NOT_FOUND"
+    | "INVALID_MESSAGE"
+    | "AI_QUOTA_EXCEEDED"
+    | "RATE_LIMITED"
+    | "AI_UNAVAILABLE"
+    | "AI_GENERATION_FAILED"
+    | "AUTH_REQUIRED"
+    | "INTERNAL"
+    | (string & {});
+  constructor(code: string, message: string, opts?: { cause?: unknown });
+}
+
 export class TranslateError extends Error {
   code:
     | "UNSUPPORTED"

package/dist/index.js

@@ -28,6 +28,7 @@ export {
   NotificationError,
   DirectoryError,
   PermissionError,
+  AgentError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -35,6 +36,7 @@ export {
   useStableQuery,
   useCanWrite,
   useInterpretDraft,
+  useAgent,
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,

package/dist/index.native.js

@@ -28,6 +28,7 @@ export {
   NotificationError,
   DirectoryError,
   PermissionError,
+  AgentError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -35,6 +36,7 @@ export {
   useStableQuery,
   useCanWrite,
   useInterpretDraft,
+  useAgent,
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,

package/dist/linter.cjs

@@ -565,6 +565,26 @@ function _scopeRules(source, manifest) {
       });
     }
   }
+
+  // sc-7991 — every send spends the workspace's AI credits, so the manifest has
+  // to declare the capability. This gate is ADVISORY, not an authorization
+  // boundary: unlike users/groups (minted into X-Widget-Scopes and checked
+  // server-side), nothing re-checks ai.invoke at call time, so a widget that
+  // evades this regex still reaches the endpoint. What actually bounds abuse is
+  // the app-user JWT, the per-actor and per-tenant limiters and the AI quota
+  // gate. The scope's real job is DISCLOSURE — it is what the marketplace
+  // install consent screen shows.
+  if (/\buseAgent\s*\(/.test(source)) {
+    const invokes = declared.has("ai.invoke:*") || declared.has("ai.invoke");
+    if (!invokes) {
+      findings.push({
+        rule: "scope-required-for-useAgent",
+        label: "useAgent() requires `ai.invoke:*` in manifest.requestedScopes",
+        line: 0,
+        snippet: "",
+      });
+    }
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;

package/dist/linter.js

@@ -528,6 +528,26 @@ function _scopeRules(source, manifest) {
       });
     }
   }
+
+  // sc-7991 — every send spends the workspace's AI credits, so the manifest has
+  // to declare the capability. This gate is ADVISORY, not an authorization
+  // boundary: unlike users/groups (minted into X-Widget-Scopes and checked
+  // server-side), nothing re-checks ai.invoke at call time, so a widget that
+  // evades this regex still reaches the endpoint. What actually bounds abuse is
+  // the app-user JWT, the per-actor and per-tenant limiters and the AI quota
+  // gate. The scope's real job is DISCLOSURE — it is what the marketplace
+  // install consent screen shows.
+  if (/\buseAgent\s*\(/.test(source)) {
+    const invokes = declared.has("ai.invoke:*") || declared.has("ai.invoke");
+    if (!invokes) {
+      findings.push({
+        rule: "scope-required-for-useAgent",
+        label: "useAgent() requires `ai.invoke:*` in manifest.requestedScopes",
+        line: 0,
+        snippet: "",
+      });
+    }
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;

package/dist/property-schema.js

@@ -23,6 +23,11 @@ const VALID_TYPES = new Set([
   // value is the raw uuid string so the tenant-copy walker can remap it
   // through `_remapJson` without per-prop hooks.
   "groupRef",
+  // sc-7991: `agentRef` is a picker for one of the workspace's AI agents,
+  // emitting a bare TenantAiAgent UUID into the page JSON. A widget reads it
+  // and calls `useAgent(agentRef)`. Bare uuid string like `groupRef`/`pageRef`,
+  // so tenant-copy remaps it through the layout walk's merged id map.
+  "agentRef",
   // REQ-WDG-PAGEREF: `pageRef` is a page picker that emits a bare AppPage
   // UUID into the page JSON. Renders a page `<select>` in the Studio
   // Properties Panel; a widget reads it and navigates via
@@ -148,6 +153,7 @@ function coerceLeaf(def, value, path, errors) {
     case "recordBinding":
     case "groupRef":
     case "pageRef":
+    case "agentRef":
     case "richText":
     case "asset":
     case "folderRef":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.147.0",
+  "version": "0.148.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",