@colixsystems/widget-sdk 0.147.0 → 0.149.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.
@@ -1602,7 +1626,20 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 - **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners — `radii.lg` for cards and hero surfaces, `radii.md` for controls nested inside one. Don't hardcode raw pixel values.
 - **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve full-strength `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
-- **Set the theme font on every `Text`.** React Native `Text` does not inherit `fontFamily` from a parent, so a text element that omits it falls back to the system font and ignores the workspace's configured font. Put `theme.typography.fontFamily` on every text style (a shared `StyleSheet` built from `theme` keeps it in one place) and size text with `theme.typography.sizes`. Use `theme.typography.headingFontFamily` instead on your widget's HEADING-tier text — titles and display numbers — so a workspace that pairs a display face with a body face gets that pairing inside your widget too. It defaults to `fontFamily`, so an unpaired workspace looks identical.
+- **Style text by its ROLE, not by inventing a size and weight.** `theme.typography.roles` carries the workspace's type scale as six semantic tiers — `display`, `title`, `subtitle`, `body`, `caption`, `overline` — each already resolved to a `fontSize`, `fontWeight`, `fontStyle`, `lineHeight` (a MULTIPLE of the size), `letterSpacing`, `textTransform` and a `colorToken`. Pick the tier the text IS, rather than choosing `fontSize: 16, fontWeight: "600"` yourself: your widget's section title is `title`, each card or row title is `subtitle`, running text is `body`, timestamps and helper text are `caption`, a small kicker or column label is `overline`, and a headline stat is `display`. This is what stops one widget rendering a subtitle bold while the widget beside it renders one italic, and it lets the workspace re-tune every subtitle in the app from Theme Settings in one edit. **Two tokens need converting rather than copying** — `lineHeight` is a multiple (React Native wants absolute pixels, so the raw `1.15` gives you a one-pixel line box) and `colorToken` names a colour rather than being one:
+
+  ```js
+  const r = theme.typography.roles.subtitle;
+  const titleStyle = {
+    fontSize: r.fontSize,
+    fontWeight: r.fontWeight,
+    letterSpacing: r.letterSpacing,
+    textTransform: r.textTransform,
+    lineHeight: Math.round(r.fontSize * r.lineHeight),
+    color: r.color || theme.colors[r.colorToken],
+  };
+  ```
+- **Set the theme font on every `Text`.** React Native `Text` does not inherit `fontFamily` from a parent, so a text element that omits it falls back to the system font and ignores the workspace's configured font. Put `theme.typography.fontFamily` on every text style (a shared `StyleSheet` built from `theme` keeps it in one place). A role already names its face for you — `display` and `title` take `theme.typography.headingFontFamily`, the rest take `fontFamily` — so a workspace that pairs a display face with a body face gets that pairing inside your widget without you naming a family. `headingFontFamily` defaults to `fontFamily`, so an unpaired workspace looks identical.
 - **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.lg` + `...theme.elevation.sm`. Give it the elevation **or** a `colors.border` hairline, not both — and prefer the elevation, because a hairline-only card reads as a wireframe. `theme.elevation` is a token table you spread into a style (`...theme.elevation.md`), covering `none / sm / md / lg / xl`; never hand-write `shadowOpacity` / `shadowRadius` / `boxShadow`. Use the status roles (`danger / success / warning / info`) for state.
 - **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.

package/dist/contract.cjs

@@ -108,6 +108,58 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     headingFontFamily:
       'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
     sizes: Object.freeze({ xs: 12, sm: 14, md: 16, lg: 20, xl: 24, xxl: 32 }),
+    // REQ-THEME-ROLE (sc-8058): the app's type scale as six SEMANTIC roles.
+    // Typography carried two faces and a size scale and nothing else, so a
+    // widget needing a "subtitle" had nothing to reach for and each invented
+    // its own literal — bold in Notifications, italic in User Management,
+    // unweighted in Files. A role names the TIER; the theme owns its look.
+    //
+    // Which FACE a role takes lives in `_shared/textStyle.js` ROLE_FACES —
+    // structural, not themeable, so it resolves without theme data. `colorToken` is
+    // the SURFACE token the role is painted with, resolved per render against
+    // the surface-aware theme (REQ-THEME-DARK / REQ-THEME-SURFACE) rather than
+    // frozen as a hex — a theme may override it with an explicit `color`.
+    roles: Object.freeze({
+      display: Object.freeze({
+        fontSize: 32,
+        fontWeight: "700",
+        lineHeight: 1.05,
+        letterSpacing: -0.5,
+        colorToken: "onSurface",
+      }),
+      title: Object.freeze({
+        fontSize: 24,
+        fontWeight: "700",
+        lineHeight: 1.15,
+        letterSpacing: -0.2,
+        colorToken: "onSurface",
+      }),
+      subtitle: Object.freeze({
+        fontSize: 16,
+        fontWeight: "600",
+        lineHeight: 1.3,
+        colorToken: "onSurface",
+      }),
+      body: Object.freeze({
+        fontSize: 16,
+        fontWeight: "400",
+        lineHeight: 1.5,
+        colorToken: "onSurface",
+      }),
+      caption: Object.freeze({
+        fontSize: 12,
+        fontWeight: "400",
+        lineHeight: 1.4,
+        colorToken: "onSurfaceMuted",
+      }),
+      overline: Object.freeze({
+        fontSize: 12,
+        fontWeight: "600",
+        lineHeight: 1.4,
+        letterSpacing: 1.5,
+        colorToken: "onSurfaceMuted",
+      }),
+    }),
   }),
   // REQ-THEME-15: the tenant's per-component style tokens, folded in by the
   // host so ONE channel carries them to the Player and the export. Empty by
@@ -172,6 +224,44 @@ const THEME_COMPONENT_TEXT_TRANSFORMS = Object.freeze([
   "capitalize",
 ]);
 
+// REQ-THEME-ROLE (sc-8058) -- the THEME side of the six semantic text tiers, in
+// the order the widgets' own TEXT_ROLES lists them. `themeTokens.typography.roles`
+// carries the seeded values; this names what a TENANT may override, so the Studio
+// control, the Mason `set_theme` coercion and the docs read ONE vocabulary --
+// exactly as `themeComponents` already is for the per-component tokens.
+const THEME_TEXT_ROLES = Object.freeze([
+  "display",
+  "title",
+  "subtitle",
+  "body",
+  "caption",
+  "overline",
+]);
+
+// Mirrors the backend's SITE_HEADER_FONT_WEIGHTS so one theme speaks one weight
+// vocabulary. Strings, because that is what both hosts' `fontWeight` takes.
+const THEME_TEXT_ROLE_FONT_WEIGHTS = Object.freeze([
+  "100", "200", "300", "400", "500", "600", "700", "800", "900",
+]);
+
+const THEME_TEXT_ROLE_FONT_STYLES = Object.freeze(["normal", "italic"]);
+
+// The per-role token vocabulary, declared like a `themeComponents` scope's
+// `tokens`: each field's value type and bounds stated ONCE, so the Studio
+// control, the set_theme coercion and the host validator cannot disagree.
+// `lineHeight` is a MULTIPLE of `fontSize` (REQ-THEME-13's grammar), so one
+// value is right at every size; `color` overrides the role's surface-aware
+// `colorToken`, which is why no role seeds a literal colour.
+const THEME_TEXT_ROLE_FIELDS = Object.freeze({
+  fontSize: Object.freeze({ type: "size", min: 8, max: 96 }),
+  fontWeight: Object.freeze({ type: "enum", values: THEME_TEXT_ROLE_FONT_WEIGHTS }),
+  fontStyle: Object.freeze({ type: "enum", values: THEME_TEXT_ROLE_FONT_STYLES }),
+  lineHeight: Object.freeze({ type: "decimal", min: 0.8, max: 3, step: 0.05 }),
+  letterSpacing: Object.freeze({ type: "decimal", min: -2, max: 20, step: 0.1 }),
+  textTransform: Object.freeze({ type: "textTransform" }),
+  color: Object.freeze({ type: "color" }),
+});
+
 // sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
 // angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
 // variant (a component fill projects through `<Gradient>`, which is linear-only
@@ -1172,6 +1262,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 +2402,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 +4200,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 +4230,20 @@ 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",
+  // 1.117.0: additive (sc-8058) -- the six SEMANTIC text roles.
+  //    `themeTokens.typography.roles` seeds display / title / subtitle / body /
+  //    caption / overline, and `themeTextRoles` + `themeTextRoleFields` publish
+  //    the tier names and the per-role token vocabulary (each field's type and
+  //    bounds) a TENANT may override -- the single source the Studio control,
+  //    the Mason `set_theme` coercion and the docs read, exactly as
+  //    `themeComponents` already is. Typography carried two faces and a size
+  //    scale and nothing else, so every widget drawing a "subtitle" invented its
+  //    own literal and no theme edit could move them together. Which FACE a role
+  //    takes is deliberately absent -- that is structural (`ROLE_FACES` in the
+  //    hosts' shared textStyle module), not a theme token. Additive: no export
+  //    changed signature, and a theme carrying no `roles` renders on the seeded
+  //    defaults exactly as before.
+  version: "1.117.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4096,6 +4259,8 @@ const CONTRACT = deepFreeze({
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
+  themeTextRoles: THEME_TEXT_ROLES,
+  themeTextRoleFields: THEME_TEXT_ROLE_FIELDS,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,

package/dist/contract.js

@@ -108,6 +108,58 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     headingFontFamily:
       'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
     sizes: Object.freeze({ xs: 12, sm: 14, md: 16, lg: 20, xl: 24, xxl: 32 }),
+    // REQ-THEME-ROLE (sc-8058): the app's type scale as six SEMANTIC roles.
+    // Typography carried two faces and a size scale and nothing else, so a
+    // widget needing a "subtitle" had nothing to reach for and each invented
+    // its own literal — bold in Notifications, italic in User Management,
+    // unweighted in Files. A role names the TIER; the theme owns its look.
+    //
+    // Which FACE a role takes lives in `_shared/textStyle.js` ROLE_FACES —
+    // structural, not themeable, so it resolves without theme data. `colorToken` is
+    // the SURFACE token the role is painted with, resolved per render against
+    // the surface-aware theme (REQ-THEME-DARK / REQ-THEME-SURFACE) rather than
+    // frozen as a hex — a theme may override it with an explicit `color`.
+    roles: Object.freeze({
+      display: Object.freeze({
+        fontSize: 32,
+        fontWeight: "700",
+        lineHeight: 1.05,
+        letterSpacing: -0.5,
+        colorToken: "onSurface",
+      }),
+      title: Object.freeze({
+        fontSize: 24,
+        fontWeight: "700",
+        lineHeight: 1.15,
+        letterSpacing: -0.2,
+        colorToken: "onSurface",
+      }),
+      subtitle: Object.freeze({
+        fontSize: 16,
+        fontWeight: "600",
+        lineHeight: 1.3,
+        colorToken: "onSurface",
+      }),
+      body: Object.freeze({
+        fontSize: 16,
+        fontWeight: "400",
+        lineHeight: 1.5,
+        colorToken: "onSurface",
+      }),
+      caption: Object.freeze({
+        fontSize: 12,
+        fontWeight: "400",
+        lineHeight: 1.4,
+        colorToken: "onSurfaceMuted",
+      }),
+      overline: Object.freeze({
+        fontSize: 12,
+        fontWeight: "600",
+        lineHeight: 1.4,
+        letterSpacing: 1.5,
+        colorToken: "onSurfaceMuted",
+      }),
+    }),
   }),
   // REQ-THEME-15: the tenant's per-component style tokens, folded in by the
   // host so ONE channel carries them to the Player and the export. Empty by
@@ -172,6 +224,44 @@ const THEME_COMPONENT_TEXT_TRANSFORMS = Object.freeze([
   "capitalize",
 ]);
 
+// REQ-THEME-ROLE (sc-8058) -- the THEME side of the six semantic text tiers, in
+// the order the widgets' own TEXT_ROLES lists them. `themeTokens.typography.roles`
+// carries the seeded values; this names what a TENANT may override, so the Studio
+// control, the Mason `set_theme` coercion and the docs read ONE vocabulary --
+// exactly as `themeComponents` already is for the per-component tokens.
+const THEME_TEXT_ROLES = Object.freeze([
+  "display",
+  "title",
+  "subtitle",
+  "body",
+  "caption",
+  "overline",
+]);
+
+// Mirrors the backend's SITE_HEADER_FONT_WEIGHTS so one theme speaks one weight
+// vocabulary. Strings, because that is what both hosts' `fontWeight` takes.
+const THEME_TEXT_ROLE_FONT_WEIGHTS = Object.freeze([
+  "100", "200", "300", "400", "500", "600", "700", "800", "900",
+]);
+
+const THEME_TEXT_ROLE_FONT_STYLES = Object.freeze(["normal", "italic"]);
+
+// The per-role token vocabulary, declared like a `themeComponents` scope's
+// `tokens`: each field's value type and bounds stated ONCE, so the Studio
+// control, the set_theme coercion and the host validator cannot disagree.
+// `lineHeight` is a MULTIPLE of `fontSize` (REQ-THEME-13's grammar), so one
+// value is right at every size; `color` overrides the role's surface-aware
+// `colorToken`, which is why no role seeds a literal colour.
+const THEME_TEXT_ROLE_FIELDS = Object.freeze({
+  fontSize: Object.freeze({ type: "size", min: 8, max: 96 }),
+  fontWeight: Object.freeze({ type: "enum", values: THEME_TEXT_ROLE_FONT_WEIGHTS }),
+  fontStyle: Object.freeze({ type: "enum", values: THEME_TEXT_ROLE_FONT_STYLES }),
+  lineHeight: Object.freeze({ type: "decimal", min: 0.8, max: 3, step: 0.05 }),
+  letterSpacing: Object.freeze({ type: "decimal", min: -2, max: 20, step: 0.1 }),
+  textTransform: Object.freeze({ type: "textTransform" }),
+  color: Object.freeze({ type: "color" }),
+});
+
 // sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
 // angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
 // variant (a component fill projects through `<Gradient>`, which is linear-only
@@ -1172,6 +1262,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 +2398,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 +4196,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 +4226,20 @@ 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",
+  // 1.117.0: additive (sc-8058) -- the six SEMANTIC text roles.
+  //    `themeTokens.typography.roles` seeds display / title / subtitle / body /
+  //    caption / overline, and `themeTextRoles` + `themeTextRoleFields` publish
+  //    the tier names and the per-role token vocabulary (each field's type and
+  //    bounds) a TENANT may override -- the single source the Studio control,
+  //    the Mason `set_theme` coercion and the docs read, exactly as
+  //    `themeComponents` already is. Typography carried two faces and a size
+  //    scale and nothing else, so every widget drawing a "subtitle" invented its
+  //    own literal and no theme edit could move them together. Which FACE a role
+  //    takes is deliberately absent -- that is structural (`ROLE_FACES` in the
+  //    hosts' shared textStyle module), not a theme token. Additive: no export
+  //    changed signature, and a theme carrying no `roles` renders on the seeded
+  //    defaults exactly as before.
+  version: "1.117.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4092,6 +4255,8 @@ const CONTRACT = deepFreeze({
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
+  themeTextRoles: THEME_TEXT_ROLES,
+  themeTextRoleFields: THEME_TEXT_ROLE_FIELDS,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,

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/dist/theme-background.cjs

@@ -75,7 +75,7 @@ function normaliseImageUrl(raw) {
 
 // A single tint laid over the image. Alpha lives in the 8-digit hex, so the
 // author controls opacity with the colour itself rather than a second field —
-// the same way `siteHeader.backgroundColor` already floats a header.
+// the same way `siteHeader.backgroundColor` already tints a header.
 function normaliseOverlay(raw) {
   return hexOrNull(raw);
 }

package/dist/theme-background.js

@@ -67,7 +67,7 @@ function normaliseImageUrl(raw) {
 
 // A single tint laid over the image. Alpha lives in the 8-digit hex, so the
 // author controls opacity with the colour itself rather than a second field —
-// the same way `siteHeader.backgroundColor` already floats a header.
+// the same way `siteHeader.backgroundColor` already tints a header.
 function normaliseOverlay(raw) {
   return hexOrNull(raw);
 }

package/package.json

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