@useago/sdk 1.3.2 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -154,6 +154,37 @@ declare class AgoClient {
154
154
  path: string;
155
155
  description: string;
156
156
  }>): void;
157
+ /**
158
+ * Register a "page state" function that lets AGO change the current page's
159
+ * state (filters, sort, view mode, selection…) and reads the current state
160
+ * back as dynamic context. This is the state-mutation mirror of
161
+ * {@link registerNavigationFunction}.
162
+ *
163
+ * It does two things:
164
+ * - Synthesizes ONE client function (default name `setPageState`) whose
165
+ * properties are the controls — all optional, so the agent sets only the
166
+ * ones the user asked for.
167
+ * - Registers a dynamic context provider (keyed `page-state:<fnName>`) that
168
+ * reports each control's current `get()` value on every message.
169
+ *
170
+ * ```ts
171
+ * client.registerPageStateFunction([
172
+ * {
173
+ * name: "statusFilter",
174
+ * description: "Filter the list by review status",
175
+ * schema: { type: "string", enum: ["all", "pending", "approved"] },
176
+ * get: () => filters.status,
177
+ * set: (v) => setFilters({ ...filters, status: v }),
178
+ * },
179
+ * ]);
180
+ * ```
181
+ */
182
+ registerPageStateFunction(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
183
+ /**
184
+ * Unregister a page state function and its dynamic context provider.
185
+ * Mirror of unregistering `navigateToPage`.
186
+ */
187
+ unregisterPageStateFunction(functionName?: string): void;
157
188
  /**
158
189
  * Register or update a piece of client-side context.
159
190
  * This context is sent with every message so the AI understands the user's situation.
@@ -386,9 +417,23 @@ declare interface AgoMessage {
386
417
  followUpReplies?: string[];
387
418
  /** Uploaded files on this message (usually the user's). */
388
419
  attachments?: AgoAttachment[];
420
+ /**
421
+ * True when the backend flagged this message as hidden (e.g. an
422
+ * auto-continuation nudge). Kept in the model's context but not displayed;
423
+ * UI helpers like `useMessages`/`ChatWidget` filter these out.
424
+ */
425
+ hidden?: boolean;
389
426
  createdAt: Date;
390
427
  }
391
428
 
429
+ /**
430
+ * Options for {@link AgoClient.registerPageStateFunction}.
431
+ */
432
+ declare interface AgoPageStateOptions {
433
+ /** Name of the synthesized client function. Defaults to "setPageState". */
434
+ functionName?: string;
435
+ }
436
+
392
437
  /**
393
438
  * Knowledge source citation
394
439
  */
@@ -398,6 +443,32 @@ declare interface AgoSource {
398
443
  url?: string;
399
444
  }
400
445
 
446
+ /**
447
+ * A single editable control on the current page (a filter, a sort, a view mode,
448
+ * a selection…). It becomes one optional property of the synthesized
449
+ * `setPageState` function, and its current value is surfaced back to the agent
450
+ * as dynamic context. This is the state-mutation mirror of a navigation route.
451
+ */
452
+ declare interface AgoStateControl<T = unknown> {
453
+ /** Machine name of the control, e.g. "statusFilter". Becomes a property of the tool. */
454
+ name: string;
455
+ /** Description for the LLM, e.g. "Filter the list by review status". */
456
+ description: string;
457
+ /** JSON schema for a SINGLE field (like one property of navigateToPage). */
458
+ schema: {
459
+ type: "string" | "number" | "boolean" | "array";
460
+ enum?: (string | number)[];
461
+ items?: {
462
+ type: string;
463
+ enum?: (string | number)[];
464
+ };
465
+ };
466
+ /** Current value → pushed as dynamic context so the agent knows what to change. */
467
+ get?: () => T;
468
+ /** Apply the state change on the page. May be async. */
469
+ set: (value: T) => void | Promise<void>;
470
+ }
471
+
401
472
  /**
402
473
  * Single-object function definition — combines name, schema, and handler.
403
474
  *
@@ -444,7 +515,11 @@ declare interface ClientFunctionSchema {
444
515
  properties: Record<string, {
445
516
  type: string;
446
517
  description?: string;
447
- enum?: string[];
518
+ enum?: (string | number)[];
519
+ items?: {
520
+ type: string;
521
+ enum?: (string | number)[];
522
+ };
448
523
  default?: unknown;
449
524
  }>;
450
525
  required?: string[];
@@ -639,6 +714,13 @@ declare interface SendMessageOptions {
639
714
  agentId?: string;
640
715
  /** File attachments */
641
716
  files?: File[];
717
+ /**
718
+ * Mark this message as hidden. The backend keeps it in the model's context but
719
+ * flags it so the UI never displays it. Used by auto-continuation to nudge the
720
+ * agent after a navigation without polluting the visible transcript.
721
+ * Requires backend support for the `hidden` flag; older backends ignore it.
722
+ */
723
+ hidden?: boolean;
642
724
  }
643
725
 
644
726
  /**
package/dist/testing.d.ts CHANGED
@@ -154,6 +154,37 @@ declare class AgoClient {
154
154
  path: string;
155
155
  description: string;
156
156
  }>): void;
157
+ /**
158
+ * Register a "page state" function that lets AGO change the current page's
159
+ * state (filters, sort, view mode, selection…) and reads the current state
160
+ * back as dynamic context. This is the state-mutation mirror of
161
+ * {@link registerNavigationFunction}.
162
+ *
163
+ * It does two things:
164
+ * - Synthesizes ONE client function (default name `setPageState`) whose
165
+ * properties are the controls — all optional, so the agent sets only the
166
+ * ones the user asked for.
167
+ * - Registers a dynamic context provider (keyed `page-state:<fnName>`) that
168
+ * reports each control's current `get()` value on every message.
169
+ *
170
+ * ```ts
171
+ * client.registerPageStateFunction([
172
+ * {
173
+ * name: "statusFilter",
174
+ * description: "Filter the list by review status",
175
+ * schema: { type: "string", enum: ["all", "pending", "approved"] },
176
+ * get: () => filters.status,
177
+ * set: (v) => setFilters({ ...filters, status: v }),
178
+ * },
179
+ * ]);
180
+ * ```
181
+ */
182
+ registerPageStateFunction(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
183
+ /**
184
+ * Unregister a page state function and its dynamic context provider.
185
+ * Mirror of unregistering `navigateToPage`.
186
+ */
187
+ unregisterPageStateFunction(functionName?: string): void;
157
188
  /**
158
189
  * Register or update a piece of client-side context.
159
190
  * This context is sent with every message so the AI understands the user's situation.
@@ -386,9 +417,23 @@ declare interface AgoMessage {
386
417
  followUpReplies?: string[];
387
418
  /** Uploaded files on this message (usually the user's). */
388
419
  attachments?: AgoAttachment[];
420
+ /**
421
+ * True when the backend flagged this message as hidden (e.g. an
422
+ * auto-continuation nudge). Kept in the model's context but not displayed;
423
+ * UI helpers like `useMessages`/`ChatWidget` filter these out.
424
+ */
425
+ hidden?: boolean;
389
426
  createdAt: Date;
390
427
  }
391
428
 
429
+ /**
430
+ * Options for {@link AgoClient.registerPageStateFunction}.
431
+ */
432
+ declare interface AgoPageStateOptions {
433
+ /** Name of the synthesized client function. Defaults to "setPageState". */
434
+ functionName?: string;
435
+ }
436
+
392
437
  /**
393
438
  * Knowledge source citation
394
439
  */
@@ -398,6 +443,32 @@ declare interface AgoSource {
398
443
  url?: string;
399
444
  }
400
445
 
446
+ /**
447
+ * A single editable control on the current page (a filter, a sort, a view mode,
448
+ * a selection…). It becomes one optional property of the synthesized
449
+ * `setPageState` function, and its current value is surfaced back to the agent
450
+ * as dynamic context. This is the state-mutation mirror of a navigation route.
451
+ */
452
+ declare interface AgoStateControl<T = unknown> {
453
+ /** Machine name of the control, e.g. "statusFilter". Becomes a property of the tool. */
454
+ name: string;
455
+ /** Description for the LLM, e.g. "Filter the list by review status". */
456
+ description: string;
457
+ /** JSON schema for a SINGLE field (like one property of navigateToPage). */
458
+ schema: {
459
+ type: "string" | "number" | "boolean" | "array";
460
+ enum?: (string | number)[];
461
+ items?: {
462
+ type: string;
463
+ enum?: (string | number)[];
464
+ };
465
+ };
466
+ /** Current value → pushed as dynamic context so the agent knows what to change. */
467
+ get?: () => T;
468
+ /** Apply the state change on the page. May be async. */
469
+ set: (value: T) => void | Promise<void>;
470
+ }
471
+
401
472
  /**
402
473
  * Single-object function definition — combines name, schema, and handler.
403
474
  *
@@ -444,7 +515,11 @@ declare interface ClientFunctionSchema {
444
515
  properties: Record<string, {
445
516
  type: string;
446
517
  description?: string;
447
- enum?: string[];
518
+ enum?: (string | number)[];
519
+ items?: {
520
+ type: string;
521
+ enum?: (string | number)[];
522
+ };
448
523
  default?: unknown;
449
524
  }>;
450
525
  required?: string[];
@@ -639,6 +714,13 @@ declare interface SendMessageOptions {
639
714
  agentId?: string;
640
715
  /** File attachments */
641
716
  files?: File[];
717
+ /**
718
+ * Mark this message as hidden. The backend keeps it in the model's context but
719
+ * flags it so the UI never displays it. Used by auto-continuation to nudge the
720
+ * agent after a navigation without polluting the visible transcript.
721
+ * Requires backend support for the `hidden` flag; older backends ignore it.
722
+ */
723
+ hidden?: boolean;
642
724
  }
643
725
 
644
726
  /**
package/dist/vue.cjs CHANGED
@@ -1 +1 @@
1
- Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const P=require("./rolldown-runtime-16Nf8qvH.cjs"),p=require("./AgoClient-CzSmJQxl.cjs");let t=require("vue");var I=Symbol("ago-client"),y={install(o,n){const e=new p.AgoClient(n);o.provide(I,e)}};function g(o){if(o)return new p.AgoClient(o);const n=(0,t.inject)(I);if(!n)throw new Error("useAgo(): no AgoClient found. Either pass config or install AgoPlugin.");return n}function E(o={}){const n=o.client??g(),e=(0,t.ref)([]),s=(0,t.ref)(o.conversationId),i=(0,t.ref)(!1),r=(0,t.ref)(null),c=a=>{s.value||(s.value=a.conversationId)},f=a=>{const u=e.value.findIndex(v=>v.id===a.messageId);u>=0&&(e.value[u]={...e.value[u],content:e.value[u].content+a.content})},m=a=>{const u=e.value.findIndex(v=>v.id===a.id);u>=0?e.value[u]=a:e.value.push(a),i.value=!1},C=a=>{r.value=new Error(a.error),i.value=!1};(0,t.onMounted)(()=>{n.on("message:start",c),n.on("message:chunk",f),n.on("message:complete",m),n.on("message:error",C)}),(0,t.onUnmounted)(()=>{n.off("message:start",c),n.off("message:chunk",f),n.off("message:complete",m),n.off("message:error",C)});async function d(a,u){i.value=!0,r.value=null;const v={id:`temp-${Date.now()}`,conversationId:s.value||"",content:a,role:"user",status:"DONE",createdAt:new Date},L={id:`temp-assistant-${Date.now()}`,conversationId:s.value||"",content:"",role:"assistant",status:"IN_PROGRESS",createdAt:new Date};e.value.push(v,L);try{const l=await n.sendMessage(a,{conversationId:s.value,files:u});l.conversationId&&!s.value&&(s.value=l.conversationId),e.value=e.value.filter(w=>!w.id.startsWith("temp-"));const A={...v,id:v.id.replace("temp-","user-"),conversationId:l.conversationId};return e.value.some(w=>w.id===l.id)?e.value.push(A):e.value.push(A,l),l}catch(l){return r.value=l instanceof Error?l:new Error("Failed to send"),i.value=!1,e.value=e.value.filter(A=>!A.id.startsWith("temp-")),null}}function h(){e.value=[],s.value=void 0,r.value=null}return{messages:e,isLoading:i,error:r,conversationId:s,sendMessage:d,clearMessages:h}}function M(o={}){const n=o.client??g(),e=o.autoLoad??!0,s=(0,t.ref)([]),i=(0,t.ref)(null),r=(0,t.ref)(!1),c=(0,t.ref)(null);async function f(){r.value=!0,c.value=null;try{s.value=await n.getConversations()}catch(d){c.value=d instanceof Error?d:new Error("Failed to load conversations")}finally{r.value=!1}}async function m(d){r.value=!0,c.value=null;try{i.value=await n.getConversation(d)}catch(h){c.value=h instanceof Error?h:new Error("Failed to load conversation")}finally{r.value=!1}}function C(){i.value=null}return(0,t.onMounted)(()=>{e&&f()}),{conversations:s,currentConversation:i,isLoading:r,error:c,selectConversation:m,startNewConversation:C,refreshConversations:f}}function N(o={}){const n=E({client:o.client,conversationId:o.conversationId}),e=M({client:o.client,autoLoad:o.autoLoad}),s=(0,t.computed)(()=>n.error.value||e.error.value);return{messages:n.messages,isLoading:n.isLoading,error:s,sendMessage:n.sendMessage,clearMessages:n.clearMessages,conversationId:n.conversationId,conversations:e.conversations,currentConversation:e.currentConversation,isConversationsLoading:e.isLoading,selectConversation:e.selectConversation,startNewConversation:e.startNewConversation,refreshConversations:e.refreshConversations}}function F(o,n){const e=g();(0,t.onMounted)(()=>{e.registerFunction(o,n.handler,{description:n.description,parameters:n.parameters})}),(0,t.onUnmounted)(()=>{e.unregisterFunction(o)})}function S(o,n){const e=g();(0,t.onMounted)(()=>{e.registerNavigationFunction(o,n)}),(0,t.onUnmounted)(()=>{e.unregisterFunction("navigateToPage")})}function _(o,n){const e=g();(0,t.onMounted)(()=>{e.on(o,n)}),(0,t.onUnmounted)(()=>{e.off(o,n)})}function D(o){const n=(0,t.shallowRef)(o.get());return(0,t.onScopeDispose)(o.subscribe(e=>{n.value=e})),n}exports.AGO_CLIENT_KEY=I;exports.AgoPlugin=y;exports.useAgo=g;exports.useAgoEvents=_;exports.useAgoFunction=F;exports.useAgoNavigation=S;exports.useAgoStore=D;exports.useChat=N;exports.useConversation=M;exports.useMessages=E;
1
+ Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const U=require("./rolldown-runtime-16Nf8qvH.cjs"),p=require("./AgoClient-B2BU8tfB.cjs");let o=require("vue");var I=Symbol("ago-client"),N={install(t,n){const e=new p.AgoClient(n);t.provide(I,e)}};function d(t){if(t)return new p.AgoClient(t);const n=(0,o.inject)(I);if(!n)throw new Error("useAgo(): no AgoClient found. Either pass config or install AgoPlugin.");return n}function E(t={}){const n=t.client??d(),e=(0,o.ref)([]),s=(0,o.ref)(t.conversationId),i=(0,o.ref)(!1),r=(0,o.ref)(null),c=a=>{s.value||(s.value=a.conversationId)},f=a=>{const u=e.value.findIndex(v=>v.id===a.messageId);u>=0&&(e.value[u]={...e.value[u],content:e.value[u].content+a.content})},m=a=>{const u=e.value.findIndex(v=>v.id===a.id);u>=0?e.value[u]=a:e.value.push(a),i.value=!1},C=a=>{r.value=new Error(a.error),i.value=!1};(0,o.onMounted)(()=>{n.on("message:start",c),n.on("message:chunk",f),n.on("message:complete",m),n.on("message:error",C)}),(0,o.onUnmounted)(()=>{n.off("message:start",c),n.off("message:chunk",f),n.off("message:complete",m),n.off("message:error",C)});async function g(a,u){i.value=!0,r.value=null;const v={id:`temp-${Date.now()}`,conversationId:s.value||"",content:a,role:"user",status:"DONE",createdAt:new Date},S={id:`temp-assistant-${Date.now()}`,conversationId:s.value||"",content:"",role:"assistant",status:"IN_PROGRESS",createdAt:new Date};e.value.push(v,S);try{const l=await n.sendMessage(a,{conversationId:s.value,files:u});l.conversationId&&!s.value&&(s.value=l.conversationId),e.value=e.value.filter(w=>!w.id.startsWith("temp-"));const A={...v,id:v.id.replace("temp-","user-"),conversationId:l.conversationId};return e.value.some(w=>w.id===l.id)?e.value.push(A):e.value.push(A,l),l}catch(l){return r.value=l instanceof Error?l:new Error("Failed to send"),i.value=!1,e.value=e.value.filter(A=>!A.id.startsWith("temp-")),null}}function h(){e.value=[],s.value=void 0,r.value=null}return{messages:e,isLoading:i,error:r,conversationId:s,sendMessage:g,clearMessages:h}}function M(t={}){const n=t.client??d(),e=t.autoLoad??!0,s=(0,o.ref)([]),i=(0,o.ref)(null),r=(0,o.ref)(!1),c=(0,o.ref)(null);async function f(){r.value=!0,c.value=null;try{s.value=await n.getConversations()}catch(g){c.value=g instanceof Error?g:new Error("Failed to load conversations")}finally{r.value=!1}}async function m(g){r.value=!0,c.value=null;try{i.value=await n.getConversation(g)}catch(h){c.value=h instanceof Error?h:new Error("Failed to load conversation")}finally{r.value=!1}}function C(){i.value=null}return(0,o.onMounted)(()=>{e&&f()}),{conversations:s,currentConversation:i,isLoading:r,error:c,selectConversation:m,startNewConversation:C,refreshConversations:f}}function L(t={}){const n=E({client:t.client,conversationId:t.conversationId}),e=M({client:t.client,autoLoad:t.autoLoad}),s=(0,o.computed)(()=>n.error.value||e.error.value);return{messages:n.messages,isLoading:n.isLoading,error:s,sendMessage:n.sendMessage,clearMessages:n.clearMessages,conversationId:n.conversationId,conversations:e.conversations,currentConversation:e.currentConversation,isConversationsLoading:e.isLoading,selectConversation:e.selectConversation,startNewConversation:e.startNewConversation,refreshConversations:e.refreshConversations}}function y(t,n){const e=d();(0,o.onMounted)(()=>{e.registerFunction(t,n.handler,{description:n.description,parameters:n.parameters})}),(0,o.onUnmounted)(()=>{e.unregisterFunction(t)})}function F(t,n){const e=d();(0,o.onMounted)(()=>{e.registerNavigationFunction(t,n)}),(0,o.onUnmounted)(()=>{e.unregisterFunction("navigateToPage")})}function P(t,n){const e=d(),s=n?.functionName??"setPageState";(0,o.onMounted)(()=>{e.registerPageStateFunction(t,{functionName:s})}),(0,o.onUnmounted)(()=>{e.unregisterPageStateFunction(s)})}function _(t,n){const e=d();(0,o.onMounted)(()=>{e.on(t,n)}),(0,o.onUnmounted)(()=>{e.off(t,n)})}function D(t){const n=(0,o.shallowRef)(t.get());return(0,o.onScopeDispose)(t.subscribe(e=>{n.value=e})),n}exports.AGO_CLIENT_KEY=I;exports.AgoPlugin=N;exports.useAgo=d;exports.useAgoEvents=_;exports.useAgoFunction=y;exports.useAgoNavigation=F;exports.useAgoPageState=P;exports.useAgoStore=D;exports.useChat=L;exports.useConversation=M;exports.useMessages=E;
package/dist/vue.d.cts CHANGED
@@ -162,6 +162,37 @@ declare class AgoClient {
162
162
  path: string;
163
163
  description: string;
164
164
  }>): void;
165
+ /**
166
+ * Register a "page state" function that lets AGO change the current page's
167
+ * state (filters, sort, view mode, selection…) and reads the current state
168
+ * back as dynamic context. This is the state-mutation mirror of
169
+ * {@link registerNavigationFunction}.
170
+ *
171
+ * It does two things:
172
+ * - Synthesizes ONE client function (default name `setPageState`) whose
173
+ * properties are the controls — all optional, so the agent sets only the
174
+ * ones the user asked for.
175
+ * - Registers a dynamic context provider (keyed `page-state:<fnName>`) that
176
+ * reports each control's current `get()` value on every message.
177
+ *
178
+ * ```ts
179
+ * client.registerPageStateFunction([
180
+ * {
181
+ * name: "statusFilter",
182
+ * description: "Filter the list by review status",
183
+ * schema: { type: "string", enum: ["all", "pending", "approved"] },
184
+ * get: () => filters.status,
185
+ * set: (v) => setFilters({ ...filters, status: v }),
186
+ * },
187
+ * ]);
188
+ * ```
189
+ */
190
+ registerPageStateFunction(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
191
+ /**
192
+ * Unregister a page state function and its dynamic context provider.
193
+ * Mirror of unregistering `navigateToPage`.
194
+ */
195
+ unregisterPageStateFunction(functionName?: string): void;
165
196
  /**
166
197
  * Register or update a piece of client-side context.
167
198
  * This context is sent with every message so the AI understands the user's situation.
@@ -394,9 +425,23 @@ export declare interface AgoMessage {
394
425
  followUpReplies?: string[];
395
426
  /** Uploaded files on this message (usually the user's). */
396
427
  attachments?: AgoAttachment[];
428
+ /**
429
+ * True when the backend flagged this message as hidden (e.g. an
430
+ * auto-continuation nudge). Kept in the model's context but not displayed;
431
+ * UI helpers like `useMessages`/`ChatWidget` filter these out.
432
+ */
433
+ hidden?: boolean;
397
434
  createdAt: Date;
398
435
  }
399
436
 
437
+ /**
438
+ * Options for {@link AgoClient.registerPageStateFunction}.
439
+ */
440
+ export declare interface AgoPageStateOptions {
441
+ /** Name of the synthesized client function. Defaults to "setPageState". */
442
+ functionName?: string;
443
+ }
444
+
400
445
  /**
401
446
  * Vue plugin that provides an AgoClient to the entire app via inject/provide.
402
447
  *
@@ -427,6 +472,32 @@ export declare interface AgoSource {
427
472
  url?: string;
428
473
  }
429
474
 
475
+ /**
476
+ * A single editable control on the current page (a filter, a sort, a view mode,
477
+ * a selection…). It becomes one optional property of the synthesized
478
+ * `setPageState` function, and its current value is surfaced back to the agent
479
+ * as dynamic context. This is the state-mutation mirror of a navigation route.
480
+ */
481
+ export declare interface AgoStateControl<T = unknown> {
482
+ /** Machine name of the control, e.g. "statusFilter". Becomes a property of the tool. */
483
+ name: string;
484
+ /** Description for the LLM, e.g. "Filter the list by review status". */
485
+ description: string;
486
+ /** JSON schema for a SINGLE field (like one property of navigateToPage). */
487
+ schema: {
488
+ type: "string" | "number" | "boolean" | "array";
489
+ enum?: (string | number)[];
490
+ items?: {
491
+ type: string;
492
+ enum?: (string | number)[];
493
+ };
494
+ };
495
+ /** Current value → pushed as dynamic context so the agent knows what to change. */
496
+ get?: () => T;
497
+ /** Apply the state change on the page. May be async. */
498
+ set: (value: T) => void | Promise<void>;
499
+ }
500
+
430
501
  /**
431
502
  * Single-object function definition — combines name, schema, and handler.
432
503
  *
@@ -473,7 +544,11 @@ declare interface ClientFunctionSchema {
473
544
  properties: Record<string, {
474
545
  type: string;
475
546
  description?: string;
476
- enum?: string[];
547
+ enum?: (string | number)[];
548
+ items?: {
549
+ type: string;
550
+ enum?: (string | number)[];
551
+ };
477
552
  default?: unknown;
478
553
  }>;
479
554
  required?: string[];
@@ -635,6 +710,13 @@ declare interface SendMessageOptions {
635
710
  agentId?: string;
636
711
  /** File attachments */
637
712
  files?: File[];
713
+ /**
714
+ * Mark this message as hidden. The backend keeps it in the model's context but
715
+ * flags it so the UI never displays it. Used by auto-continuation to nudge the
716
+ * agent after a navigation without polluting the visible transcript.
717
+ * Requires backend support for the `hidden` flag; older backends ignore it.
718
+ */
719
+ hidden?: boolean;
638
720
  }
639
721
 
640
722
  /**
@@ -798,6 +880,26 @@ export declare function useAgoFunction(name: string, options: {
798
880
  */
799
881
  export declare function useAgoNavigation(navigate: (path: string) => void, routes: AgoRoute[]): void;
800
882
 
883
+ /**
884
+ * Register editable page-state controls with auto-cleanup on unmount.
885
+ * The state-mutation mirror of `useAgoNavigation`: the agent can change the
886
+ * current page's state (filters, sort, view mode…) and read it back.
887
+ *
888
+ * ```ts
889
+ * const status = ref("all");
890
+ * useAgoPageState([
891
+ * {
892
+ * name: "statusFilter",
893
+ * description: "Filter the list by review status",
894
+ * schema: { type: "string", enum: ["all", "pending", "approved"] },
895
+ * get: () => status.value,
896
+ * set: (v) => { status.value = v as string; },
897
+ * },
898
+ * ]);
899
+ * ```
900
+ */
901
+ export declare function useAgoPageState(controls: AgoStateControl[], opts?: AgoPageStateOptions): void;
902
+
801
903
  /**
802
904
  * Read a framework-agnostic AGO store (`createStore`) as a reactive Vue ref.
803
905
  *
@@ -864,6 +966,7 @@ export declare function useChat(options?: UseChatOptions): {
864
966
  url?: string | undefined;
865
967
  isSafeImage: boolean;
866
968
  }[] | undefined;
969
+ hidden?: boolean | undefined;
867
970
  createdAt: Date;
868
971
  }[], AgoMessage[] | {
869
972
  id: string;
@@ -906,6 +1009,7 @@ export declare function useChat(options?: UseChatOptions): {
906
1009
  url?: string | undefined;
907
1010
  isSafeImage: boolean;
908
1011
  }[] | undefined;
1012
+ hidden?: boolean | undefined;
909
1013
  createdAt: Date;
910
1014
  }[]>;
911
1015
  isLoading: Ref<boolean, boolean>;
@@ -958,6 +1062,7 @@ export declare function useChat(options?: UseChatOptions): {
958
1062
  url?: string | undefined;
959
1063
  isSafeImage: boolean;
960
1064
  }[] | undefined;
1065
+ hidden?: boolean | undefined;
961
1066
  createdAt: Date;
962
1067
  }[] | undefined;
963
1068
  }[], Conversation[] | {
@@ -1005,6 +1110,7 @@ export declare function useChat(options?: UseChatOptions): {
1005
1110
  url?: string | undefined;
1006
1111
  isSafeImage: boolean;
1007
1112
  }[] | undefined;
1113
+ hidden?: boolean | undefined;
1008
1114
  createdAt: Date;
1009
1115
  }[] | undefined;
1010
1116
  }[]>;
@@ -1053,6 +1159,7 @@ export declare function useChat(options?: UseChatOptions): {
1053
1159
  url?: string | undefined;
1054
1160
  isSafeImage: boolean;
1055
1161
  }[] | undefined;
1162
+ hidden?: boolean | undefined;
1056
1163
  createdAt: Date;
1057
1164
  }[] | undefined;
1058
1165
  } | null, Conversation | {
@@ -1100,6 +1207,7 @@ export declare function useChat(options?: UseChatOptions): {
1100
1207
  url?: string | undefined;
1101
1208
  isSafeImage: boolean;
1102
1209
  }[] | undefined;
1210
+ hidden?: boolean | undefined;
1103
1211
  createdAt: Date;
1104
1212
  }[] | undefined;
1105
1213
  } | null>;
@@ -1168,6 +1276,7 @@ export declare function useConversation(options?: UseConversationOptions): {
1168
1276
  url?: string | undefined;
1169
1277
  isSafeImage: boolean;
1170
1278
  }[] | undefined;
1279
+ hidden?: boolean | undefined;
1171
1280
  createdAt: Date;
1172
1281
  }[] | undefined;
1173
1282
  }[], Conversation[] | {
@@ -1215,6 +1324,7 @@ export declare function useConversation(options?: UseConversationOptions): {
1215
1324
  url?: string | undefined;
1216
1325
  isSafeImage: boolean;
1217
1326
  }[] | undefined;
1327
+ hidden?: boolean | undefined;
1218
1328
  createdAt: Date;
1219
1329
  }[] | undefined;
1220
1330
  }[]>;
@@ -1263,6 +1373,7 @@ export declare function useConversation(options?: UseConversationOptions): {
1263
1373
  url?: string | undefined;
1264
1374
  isSafeImage: boolean;
1265
1375
  }[] | undefined;
1376
+ hidden?: boolean | undefined;
1266
1377
  createdAt: Date;
1267
1378
  }[] | undefined;
1268
1379
  } | null, Conversation | {
@@ -1310,6 +1421,7 @@ export declare function useConversation(options?: UseConversationOptions): {
1310
1421
  url?: string | undefined;
1311
1422
  isSafeImage: boolean;
1312
1423
  }[] | undefined;
1424
+ hidden?: boolean | undefined;
1313
1425
  createdAt: Date;
1314
1426
  }[] | undefined;
1315
1427
  } | null>;
@@ -1374,6 +1486,7 @@ export declare function useMessages(options?: UseMessagesOptions): {
1374
1486
  url?: string | undefined;
1375
1487
  isSafeImage: boolean;
1376
1488
  }[] | undefined;
1489
+ hidden?: boolean | undefined;
1377
1490
  createdAt: Date;
1378
1491
  }[], AgoMessage[] | {
1379
1492
  id: string;
@@ -1416,6 +1529,7 @@ export declare function useMessages(options?: UseMessagesOptions): {
1416
1529
  url?: string | undefined;
1417
1530
  isSafeImage: boolean;
1418
1531
  }[] | undefined;
1532
+ hidden?: boolean | undefined;
1419
1533
  createdAt: Date;
1420
1534
  }[]>;
1421
1535
  isLoading: Ref<boolean, boolean>;