@colixsystems/widget-sdk 0.154.0 → 0.155.0

package/README.md

@@ -72,7 +72,17 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.154.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.155.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.155.0 (contract 1.121.0)
+
+**`useAgent()` returns `cancel()` — and two error codes that tell the truth about a slow turn (sc-8519).** A turn can legitimately run for minutes; the client used to give up after 10 seconds and report it as `NETWORK`, so a widget showed "you appear to be offline" to a user whose connection was fine, while the server finished the turn and the workspace paid for a reply nobody saw.
+
+- **`cancel()`** stops WAITING for the turn in flight. The abort never reaches the server, which finishes and bills the turn either way — so label the control **stop**, not *cancel*, and never imply the work was called off.
+- **`TIMEOUT`** — the client stopped waiting. Still running, still billed: say it is taking longer than usual, never that it failed.
+- **`CANCELLED`** — the user pressed your stop control. Render no error at all.
+
+Additive: `send` is unchanged for callers who ignore the new return key, and a widget that never calls `cancel()` behaves exactly as before.
 
 ### What's new in 0.154.0 (contract 1.120.0)
 

package/dist/contract.cjs

@@ -1308,7 +1308,12 @@ const HOOKS = [
       "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 " +
+      "it off, so hide the affordance rather than retrying; TIMEOUT means the " +
+      "client stopped waiting and the turn is STILL running and billed, so " +
+      "say it is taking longer, never that it failed or that they are " +
+      "offline; CANCELLED is the user pressing your stop control, so render " +
+      "no error at all. Call cancel() to stop waiting -- it ends the WAIT, " +
+      "not the turn. NEVER surface a " +
       "raw error or the workspace's billing state to an app user. " +
       "Reads ctx.agents.",
     returnShape: {
@@ -4232,6 +4237,12 @@ 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.121.0: additive (sc-8519) — `useAgent()` returns `cancel()`, which
+  // stops WAITING for the turn in flight. The abort is client-side: the
+  // server finishes the turn and the workspace is billed, so label the
+  // control 'stop', never 'cancel'. Two new AgentError codes ride with it —
+  // TIMEOUT (the client stopped waiting; still running, still billed) and
+  // CANCELLED (the user pressed stop; render no error at all).
   // 1.120.0: additive (sc-8332) — an assistant `AgentMessage` may carry
   // `activity`, a compact record of what the agent DID with the user's data
   // (the table it read; the table and columns it CHANGED). Absent on a
@@ -4298,7 +4309,7 @@ const CONTRACT = deepFreeze({
   //    untouched and renders byte-identically, and an unresolvable binding
   //    fails the existing hex guard, dropping the wash rather than painting it
   //    blank.
-  version: "1.120.0",
+  version: "1.121.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1308,7 +1308,12 @@ const HOOKS = [
       "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 " +
+      "it off, so hide the affordance rather than retrying; TIMEOUT means the " +
+      "client stopped waiting and the turn is STILL running and billed, so " +
+      "say it is taking longer, never that it failed or that they are " +
+      "offline; CANCELLED is the user pressing your stop control, so render " +
+      "no error at all. Call cancel() to stop waiting -- it ends the WAIT, " +
+      "not the turn. NEVER surface a " +
       "raw error or the workspace's billing state to an app user. " +
       "Reads ctx.agents.",
     returnShape: {
@@ -4228,6 +4233,12 @@ 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.121.0: additive (sc-8519) — `useAgent()` returns `cancel()`, which
+  // stops WAITING for the turn in flight. The abort is client-side: the
+  // server finishes the turn and the workspace is billed, so label the
+  // control 'stop', never 'cancel'. Two new AgentError codes ride with it —
+  // TIMEOUT (the client stopped waiting; still running, still billed) and
+  // CANCELLED (the user pressed stop; render no error at all).
   // 1.120.0: additive (sc-8332) — an assistant `AgentMessage` may carry
   // `activity`, a compact record of what the agent DID with the user's data
   // (the table it read; the table and columns it CHANGED). Absent on a
@@ -4294,7 +4305,7 @@ const CONTRACT = deepFreeze({
   //    untouched and renders byte-identically, and an unresolvable binding
   //    fails the existing hex guard, dropping the wash rather than painting it
   //    blank.
-  version: "1.120.0",
+  version: "1.121.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2713,7 +2713,15 @@ export function useInterpretDraft(tableId) {
  *   - "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)
+ *   - "NETWORK"               — the request never reached the server
+ *   - "TIMEOUT"               — the client stopped waiting. NOT a failed
+ *                               turn: the server finishes it and the
+ *                               workspace is billed, so say "still
+ *                               working", never "failed"
+ *   - "CANCELLED"             — `cancel()` was called. The user chose it,
+ *                               so render no error at all (the turn is
+ *                               still billed — never imply it stopped)
+ *   - "INTERNAL"              — anything else (a 5xx carrying no code)
  */
 export class AgentError extends Error {
   constructor(code, message, opts) {
@@ -2816,12 +2824,21 @@ export function useAgent(agentRef) {
     pendingResetRef.current = true;
   }
 
+  const abortRef = useRef(null);
+
   const reset = useCallback(() => {
     conversationRef.current = null;
     setMessages([]);
     setError(null);
   }, []);
 
+  // Ends the WAIT, not the turn: the abort never reaches the server, which
+  // finishes and bills it either way. Never imply the work was stopped.
+  const cancel = useCallback(() => {
+    const controller = abortRef.current;
+    if (controller) controller.abort();
+  }, []);
+
   const send = useCallback(async (text) => {
     const client = clientRef.current;
     const agentId = agentIdRef.current;
@@ -2855,7 +2872,13 @@ export function useAgent(agentRef) {
         conversationRef.current = null;
         throw err;
       }
-      const turn = await thread.messages(conversationId).send({ content });
+      const controller =
+        typeof AbortController === "function" ? new AbortController() : null;
+      abortRef.current = controller;
+      const turn = await thread
+        .messages(conversationId)
+        .send({ content }, controller ? { signal: controller.signal } : undefined);
+      abortRef.current = null;
       // A rebind during the round trip makes this the PREVIOUS agent's reply;
       // writing it now would render it under the new one.
       if (agentIdRef.current !== agentId) {
@@ -2874,8 +2897,10 @@ export function useAgent(agentRef) {
       // 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;
+      abortRef.current = null;
       // Same rebind guard: a new agent must not inherit the old one's error.
-      if (agentIdRef.current === agentId) setError(e);
+      // A cancel is the user's own choice, so it is not a failure to report.
+      if (e.code !== "CANCELLED" && agentIdRef.current === agentId) setError(e);
       setSending(false);
       throw e;
     }
@@ -2897,6 +2922,7 @@ export function useAgent(agentRef) {
 
   return {
     send,
+    cancel,
     reset,
     messages: visibleMessages,
     sending,

package/dist/index.d.ts

@@ -1239,6 +1239,12 @@ export interface AgentActivity {
 export interface AgentApi {
   /** Imperative — call from an event handler. The first send opens the thread. */
   send(text: string): Promise<AgentMessage | null>;
+  /**
+   * Stop WAITING for the turn in flight. The abort never reaches the server,
+   * which finishes and bills it either way — label the control "stop", not
+   * "cancel", and show no error when the user presses it.
+   */
+  cancel(): void;
   /** Drop the open thread and clear the transcript this widget has seen. */
   reset(): void;
   /** Oldest first. The SERVER owns the real transcript. */
@@ -1997,6 +2003,9 @@ export class AgentError extends Error {
     | "AI_UNAVAILABLE"
     | "AI_GENERATION_FAILED"
     | "AUTH_REQUIRED"
+    | "NETWORK"
+    | "TIMEOUT"
+    | "CANCELLED"
     | "INTERNAL"
     | (string & {});
   constructor(code: string, message: string, opts?: { cause?: unknown });

package/package.json

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