sygnal 6.1.1 → 6.3.0

package/src/ai.ts

@@ -21,3 +21,9 @@ export {anthropicMessages, agui, fromAISDK, strictSchemas} from './index'
 export {makeMcpAppDriver} from './index'
 // A-3 (3-A3, experimental, D291)
 export {formTool} from './index'
+// PLAN-9 (A)
+export {defineCatalog, compose, composeWith, fromTree, toTree, removeNode} from './index'
+// PLAN-9 H: chat client tools and cards
+export {openToolCalls, askCard} from './index'
+// PLAN-9 M-1
+export {Composed} from './index'

package/src/collection.ts

@@ -1,5 +1,6 @@
 import {h} from './cycle/dom/snabbdom';
-// the core's handler for this marker, registered on import (D157)
+// the core's host for this marker, registered on import (D157): unlike Portal, Transition and
+// Suspense (G-751), not on first use, because the lowercase tag works without an import (docs)
 import './core/hosts/collection';
 
 /** `<Collection of={Item} from="items" />`: a marker vnode the core's Collection host renders */

package/src/core/instance.ts

@@ -52,12 +52,15 @@ function extractSlots(children: any[]): [any[], Record<string, any[]>] {
   return [slots.default || [], slots]
 }
 
-/** an instance's id among its parent's children: its `id` prop, else its path in the view */
+/**
+ * an instance's id among its parent's children (D456): its vnode `key`, else its `id` prop, else
+ * its path in the view
+ */
 const idOf = (n: any, path: string) => {
-  const id = n.data?.props?.id
+  const id = n.key ?? n.data?.props?.id
   let s: any
   // (G-298: an id JSON can't encode, a BigInt, is used as its string)
-  if (id) try { s = JSON.stringify(id) } catch (_) { s = String(id) }
+  if (id != null) try { s = JSON.stringify(id) } catch (_) { s = String(id) }
   return `${n.sel}::${(s && s.replace(/"/g, '')) || path}`
 }
 

package/src/core/markers/lazy.ts

@@ -1,5 +1,5 @@
 /**
- * PLAN-4.6 core: lazy() components (R2), registered on import by the public `lazy` module.
+ * PLAN-4.6 core: lazy() components (R2), registered by the first `lazy()` call (G-751).
  * A view resolver (registry `resolvers`): until the import resolves, the LazyWrapper itself is
  * the component (it renders the data-sygnal-lazy="loading" placeholder Suspense waits for, or
  * the error placeholder); once it has, the loaded component replaces it under the same id (a
@@ -15,7 +15,7 @@ import {resolvers} from '../registry'
 /** wrapper -> the owners waiting for it (`done`: settled, nobody waits any more) */
 export const waiting = new WeakMap<any, Set<any> & {done?: boolean}>()
 
-resolvers.push((view, owner) => {
+const resolve = (view: any, owner: any) => {
   if (!view.__sygnalLazy) return
   if (view.__sygnalLazyLoaded()) return view.__sygnalLazyLoadedComponent || undefined
   let w = waiting.get(view)
@@ -37,4 +37,8 @@ resolvers.push((view, owner) => {
     set.add(owner)
     owner.dispose$?.().addListener({next: () => set.delete(owner)})
   }
-})
+}
+
+let on: any
+/** G-751: registers the resolver once; `lazy()` calls it, not the module's import */
+export const enableLazy = () => { on ||= resolvers.push(resolve) }

package/src/core/markers/portal.ts

@@ -1,5 +1,5 @@
 /**
- * PLAN-4.6 core: the Portal marker (R2), registered on import by the public `Portal` module.
+ * PLAN-4.6 core: the Portal marker (R2), registered by the public `Portal` when used (G-751).
  * A template rewrite (registry `pres`): the `portal` marker becomes a hidden placeholder whose
  * hooks patch its children into the target with a separate snabbdom patch function. As today
  * (the 5.x core's createPortalPlaceholder):
@@ -93,4 +93,7 @@ export function portalPlaceholder(target: string, children: any[]): any {
   }
 }
 
-pres.portal = (n) => portalPlaceholder(n.data?.props?.target, n.children || [])
+// (widgets among its children: `pres.widget.$k` rewrites them, extra/widget.ts; the core doesn't walk them)
+const pre = (n: any, o: any, x: string) => portalPlaceholder(n.data?.props?.target, (pres.widget as any)?.$k(n.children || [], o, x) || n.children || [])
+/** G-751: registers the rewrite; the public `Portal` calls it when used (its `$reg`), not on import */
+export const enablePortal = () => { pres.portal = pre }

package/src/core/markers/suspense.ts

@@ -1,5 +1,5 @@
 /**
- * PLAN-4.6 core: Suspense (R2), registered on import by the public `Suspense` module. A
+ * PLAN-4.6 core: Suspense (R2), registered by the public `Suspense` when used (G-751). A
  * post-processor (registry `posts`) of the injected vnode of an instance whose template has a
  * `suspense` marker (the 5.x core's processSuspensePost):
  * - the core injects a child whose READY is false with data-sygnal-ready="false", and a lazy
@@ -38,4 +38,5 @@ export function suspensePost(v: any): any {
   return out ? {...v, children: out} : v
 }
 
-posts.suspense = suspensePost
+/** G-751: registers the post-processor; the public `Suspense` calls it when used (its `$reg`) */
+export const enableSuspense = () => { posts.suspense = suspensePost }

package/src/core/markers/transition.ts

@@ -1,6 +1,6 @@
 /**
- * PLAN-4.6 core: the Transition marker (R2), registered on import by the public `Transition`
- * module. A template rewrite (registry `pres`): the `transition` marker is replaced by its first
+ * PLAN-4.6 core: the Transition marker (R2), registered by the public `Transition`
+ * when used (G-751). A template rewrite (registry `pres`): the `transition` marker is replaced by its first
  * child (walked on, at the marker's path), with snabbdom hooks that add the classes as today
  * (the 5.x core's applyTransitionHooks):
  * `${name}-enter|leave-from` + `-active`, two frames later `-from` becomes `-to`, and at the end
@@ -57,7 +57,7 @@ export function transitionHooks(vnode: any, p: {name?: string, duration?: number
 // (no global symbol registry entry per name)
 const T = Symbol()
 
-pres.transition = (n) => {
+const pre = (n: any) => {
   const child = n.children?.[0], p = n.data?.props || {}, k = p.name + ' ' + p.duration
   // no element child: the text child (or the marker itself, left as it is: today's behaviour)
   if (!child?.sel) return child || n
@@ -68,3 +68,6 @@ pres.transition = (n) => {
   // fragment or text has no element to animate: nothing happens
   return child.sel == 'collection' ? {...child, data: {...child.data, tr: (v: any) => (v[T] ||= {})[k] ||= transitionHooks(v, p)}} : transitionHooks(child, p)
 }
+
+/** G-751: registers the rewrite; the public `Transition` calls it when used (its `$reg`) */
+export const enableTransition = () => { pres.transition = pre }

package/src/core/registry.ts

@@ -1,9 +1,13 @@
 /**
- * PLAN-4.6 core: the module registries (04-hooks-contract §2.1). A feature module fills them
- * when it is imported; the core only looks them up, so an app that never imports the module pays
- * nothing (D157). R2 fills hosts (core/hosts: Collection, Switchable) and the markers
- * (core/markers: Portal, Transition, ClientOnly, Suspense, lazy), each imported by its public
- * module; R3 adds the definition hooks (behaviors, undo, selection, pager, persist, resources).
+ * PLAN-4.6 core: the module registries (04-hooks-contract §2.1). A feature fills them when it is
+ * used; the core only looks them up, so an app that never uses the feature pays nothing (D157).
+ * R2 fills hosts (core/hosts: Collection, Switchable) and the markers (core/markers: Portal,
+ * Transition, ClientOnly, Suspense, lazy). G-751: Portal, Transition and Suspense register their
+ * handler when a tag uses them (the pragma calls the marker's `$reg`) and `lazy()` its resolver,
+ * not on import: a module-level registration is kept by every bundle of the single-file build.
+ * Collection and Switchable register on import (the lowercase `<collection>` / `<switchable>`
+ * work without one); ClientOnly's is in runtime.ts (sygnal/vike can't reach the registry). R3
+ * adds the definition hooks (behaviors, undo, selection, pager, persist, resources).
  *
  * The entries are core modules: they get the owner's raw instance (hooks get InstanceViews).
  */

package/src/cycle/dom/IsolateModule.ts

@@ -81,25 +81,25 @@ export class IsolateModule {
 
   public createModule() {
     const self = this;
-    // G-564: a vnode can be in the old tree and the new one (a component's cached vnode, a
-    // Collection item's copy, a hoisted vnode). When an ancestor is recreated (`alt ? <ol>{c}</ol>
-    // : <ul>{c}</ul>`, a new key), snabbdom creates it again and gives it the new element before it
-    // destroys the old subtree, so destroy hooks saw the new element (a widget inside wasn't
-    // unmounted, its scope lost the new element). A created element notes its children's elements
-    // (M: a child with one is mounted, or was), before they are created; a destroyed vnode gives
-    // its noted children their old elements back for their destroy hooks (and theirs, down the
-    // subtree), and they get the new ones again when the removal starts (S), before the insert
-    // hooks. (A vnode that moves to another parent still gives its own destroy hook the new one)
-    const M = new Map<any, any>(), S: any[] = [];
-    // G-573: a vnode in the new tree twice: its first note (its element before the patch) wins.
-    // A destroy hook that throws ends the patch before remove / post: the next patch first gives
-    // the vnodes their new elements back and forgets the notes (pre)
-    const back = (c: any) => M.has(c) && (S.push(c, c.elm), c.elm = M.get(c));
-    const ret = () => { for (let e; S.length; ) e = S.pop(), S.pop().elm = e; };
+    // G-564, G-750, G-753: a vnode can be in the old tree and the new one (a component's cached
+    // vnode, a Collection item's copy, a hoisted vnode). Under another parent element (a recreated
+    // ancestor: `alt ? <ol>{c}</ol> : <ul>{c}</ul>`; a keyed instance moved to another column, or
+    // into a new row that takes its old place among its siblings) snabbdom created it again and
+    // gave it the new element while the old tree still had it: its destroy hooks saw the new
+    // element (a widget inside wasn't unmounted, its scope lost the new element), its old parent
+    // removed the new element and left the old one (G-750), or inserted a new sibling before it,
+    // inside that sibling (NotFoundError, the patch stopped: G-753). Now an element that is
+    // created or patched takes a copy of each child that has an element and isn't one of its old
+    // children (only a mounted vnode has one), before it is created: the old tree keeps the vnode
+    // and its element. The copy's children array is its own, so its children are copied when it
+    // is created. After the patch (post) each vnode takes its copy's fields (its element) and its
+    // place again, so the next patch sees the same vnode (snabbdom's shortcut). A patch that
+    // throws keeps the copies (pre forgets them): they still work, as copies
+    const R: any[] = [];
+    const copy = (a: any[], i: number) => { R.push(a, i, a[i]); a[i] = {...a[i], children: a[i].children?.slice()} };
     return {
       pre() {
-        ret();
-        M.clear();
+        R.length = 0;
       },
 
       create(emptyVNode: VNode, vNode: VNode) {
@@ -109,7 +109,7 @@ export class IsolateModule {
         if (Array.isArray(namespace)) {
           self.insertElement(namespace, elm as Element);
         }
-        children?.forEach((c: any) => c?.elm && M.set(c, M.get(c) || c.elm));
+        children?.forEach((c: any, i: number) => c?.elm && copy(children, i));
       },
 
       update(oldVNode: VNode, vNode: VNode) {
@@ -126,21 +126,25 @@ export class IsolateModule {
         if (Array.isArray(namespace)) {
           self.insertElement(namespace, elm as Element);
         }
+        // (oldVNode !== vNode here: snabbdom returns early for the same vnode; the Set only when a
+        // child isn't at its old index)
+        const oc = oldVNode.children, nc: any = vNode.children
+        let o: any
+        nc?.forEach((c: any, i: number) => c?.elm && c !== oc?.[i] && !(o ||= new Set(oc)).has(c) && copy(nc, i));
       },
 
-      // (the elements as they are now: post runs after the vnodes got their new ones back)
       destroy(vNode: VNode) {
-        vNode.children?.forEach(back);
         self.vnodesBeingRemoved.push(vNode.elm as Element);
       },
 
       remove(vNode: VNode, cb: Function) {
         self.vnodesBeingRemoved.push(vNode.elm as Element);
-        ret();
         cb();
       },
 
       post() {
+        for (let i = 0; i < R.length; i += 3) R[i][R[i + 1]] = Object.assign(R[i + 2], R[i][R[i + 1]]);
+        R.length = 0;
         // G-144: a removed root element is no longer one of its scope's roots (an element no
         // scope has as a root isn't in any set: removing it does nothing)
         for (const elm of self.vnodesBeingRemoved) {
@@ -148,7 +152,6 @@ export class IsolateModule {
           (self.eventDelegator as EventDelegator).removeElement(elm);
         }
         self.vnodesBeingRemoved = [];
-        M.clear();
       },
     };
   }

package/src/extra/ai/agent/index.ts

@@ -6,7 +6,8 @@
  * `t.tools()` / `t.callTool()` / `t.agentContext()` (A-4) all use it.
  *
  *   Comp.agent = { name, description?, read?, label?, untrusted?,
- *                  actions: { ACTION: { description, input?, consequential?, when?, idempotent? } } }
+ *                  actions: { ACTION: { description, input?, consequential?, when?, idempotent?, until?, timeout? } },
+ *                  queries: { find: { description, input?, when?, run: (state, input) => result } } }
  *
  * It reaches the app only through the runtime API (`root`, `get`, `dispatch`, `flushed`,
  * `addHooks`) and one hook layer, so the core pays 0 bytes:
@@ -25,12 +26,24 @@
  *   outcome measured by `wrapHandler` on that action only: success when a STATE handler changed
  *   the state structurally, a sink got a value or an EFFECT ran; `abort(reason)` refuses with the
  *   reason; otherwise "changed nothing" (`idempotent: true`: `{ ok: true, unchanged: true }`, D256);
+ * - `until`: an action whose result arrives later (a `resources` entry, a driver reply) answers
+ *   once it is in state: `until: 'search'` (the resource is neither loading nor refreshing) or
+ *   `until: (state) => boolean`, checked after the action's flush and after every flush that
+ *   changed something; `{ ok: true, pending: true, note, state }` after `timeout` (default 10 s) or
+ *   `cancel()` (the chat behavior's STOP / new turn); `removed: true` when the instance went away.
+ *   Calls run one at a time, so a waiting call delays the next one;
+ * - queries: read-only tools (`readOnlyHint`) that take an input, for data too large for `read`
+ *   or answers computed from the state: `run(state, input)` is a pure, synchronous function of the
+ *   instance's state; a call validates the input as for actions, checks `when`, and returns
+ *   `{ ok: true, result }` without dispatching anything (no confirm, no flush);
  * - `when` and `read`: cached by state identity per instance (reducers are immutable);
  * - HMR: given the `run()` result, it re-binds to `app.__runtime` after the root's dispose.
  * Diagnostics (dev, once each): SYG240 an input with no JSON Schema form (the tool is left out;
- * `list({ all: true })` shows it with `error`), SYG241 `read` / `when` / `label` threw, SYG243 a
- * lossy input schema, SYG440 two declarations with one name, SYG441 Collection items with no or
- * duplicate keys.
+ * `list({ all: true })` shows it with `error`), SYG241 `read` / `when` / `until` / `label` / a query threw,
+ * SYG243 a lossy input schema, SYG246 a query whose `run` is not a function or returned a promise,
+ * SYG247 a query with the tool name of an action (not offered), SYG248 `until` names no resource of
+ * the component (the call answers at once), SYG440 two declarations with one
+ * name, SYG441 Collection items with no or duplicate keys.
  */
 import {abortReason, isAbort, ORIGINAL} from '../../../shared'
 import {objIsEqual} from '../../../cycle/state/objIsEqual'
@@ -73,8 +86,8 @@ const dev = (code: string, decl: any, what: string, component: string, message:
   if (!s) done.set(decl, s = new Set())
   if (s.has(code + what)) return
   s.add(code + what)
-  // severities are passed (DEV_CODE_SEVERITY, kept out of the main bundle's table): 240 / 241 error, 243 / 440 / 441 warn
-  try { report(code, {component, message, severity: code < 'SYG242' ? 'error' : 'warn'}) } catch (e) { queueMicrotask(() => { throw e }) }
+  // severities are passed (DEV_CODE_SEVERITY, kept out of the main bundle's table): 240 / 241 / 246 error, 243 / 247 / 248 / 440 / 441 warn
+  try { report(code, {component, message, severity: code < 'SYG242' || code == 'SYG246' ? 'error' : 'warn'}) } catch (e) { queueMicrotask(() => { throw e }) }
 }
 
 /** the string `enum` / `const` values anywhere in a JSON Schema (the app's own words: filter names, statuses) */
@@ -144,7 +157,7 @@ export const lookUp = (d: string, g: AgentGroup, read: string) => {
 }
 
 interface Entry {name: string; decl: any; ivs: any[]; item: boolean; view: any; enums: Set<string>}
-interface Rec {tool: AgentTool; e: Entry; action?: string; a?: any; key?: string; off?: 1}
+interface Rec {tool: AgentTool; e: Entry; action?: string; query?: string; a?: any; key?: string; off?: 1}
 interface Call {id: number; type: string; data: any; ran: boolean; out: Array<{kind: string; reason?: string; error?: any}>}
 
 /**
@@ -164,6 +177,15 @@ export function agentTools(target: any, options: AgentToolsOptions = {}) {
   const owners = new Map<any, Map<any, any>>()
   const listeners = new Set<(change: {tools: AgentTool[]; context: Record<string, any>}) => void>()
   let last: any, scheduled = false
+  // `until`: calls waiting for their action's result to land in state, checked after each flush that changed something
+  const waiters = new Set<() => void>(), cancels = new Set<() => void>()
+  let waking = false
+  const wake = () => {
+    if (!waiters.size || waking) return
+    waking = true
+    queueMicrotask(() => api.flushed().then(() => { waking = false; for (const w of [...waiters]) w() }))
+  }
+  const changed = () => { dirty(); wake() }
 
   const dirty = () => {
     ver++
@@ -174,10 +196,10 @@ export function agentTools(target: any, options: AgentToolsOptions = {}) {
   }
   const hooks = {
     onCreate: dirty,
-    onPatch: dirty,
-    onReducer: dirty,
+    onPatch: changed,
+    onReducer: changed,
     onDispose: (iv: any) => {
-      dirty()
+      changed()
       // HMR: run()'s hmr() disposes this app, starts its successor and swaps __runtime
       if (iv.isRoot && isApp) queueMicrotask(rebind)
     },
@@ -301,21 +323,28 @@ export function agentTools(target: any, options: AgentToolsOptions = {}) {
     for (const e of entries) {
       const d = e.decl
       if (d.read) recs.set(e.name + '_read', {e, tool: {name: e.name + '_read', description: `Read ${e.name}` + (d.description ? `: ${d.description}` : ''), inputSchema: {type: 'object', properties: {}}, annotations: {readOnlyHint: true, ...(d.untrusted && {untrustedContentHint: true})}}})
-      for (const action in d.actions) {
-        const a = d.actions[action], name = e.name + '_' + snake(action), comp = e.ivs[0].name
+      // the actions, then the queries (read-only, `run(state, input)`): one tool each
+      const defs: Array<[string, any, boolean]> = []
+      for (const k in d.actions) defs.push([k, d.actions[k], false])
+      for (const k in d.queries) defs.push([k, d.queries[k], true])
+      for (const [action, a, isQuery] of defs) {
+        const name = e.name + '_' + snake(action), comp = e.ivs[0].name, where = `agent.${isQuery ? 'queries' : 'actions'}.${action}`
+        if (isQuery && recs.has(name)) { dev('SYG247', d, action, comp, `${where} has the tool name ${name} of an action; the query is not offered (rename it)`); continue }
+        if (isQuery && typeof a?.run != 'function') { dev('SYG246', d, action, comp, `${where}.run is not a function; the query is not offered`); continue }
         const c = a.input ? toJsonSchema(a.input) : undefined
         if (c?.schema) enumsOf(c.schema, e.enums)
-        const tool: AgentTool = {name, description: a.description, inputSchema: c?.schema || {type: 'object', properties: {}}, annotations: a.consequential ? {consequentialHint: true} : {}}
-        const rec: Rec = {e, action, a, tool}
+        const tool: AgentTool = {name, description: a.description, inputSchema: c?.schema || {type: 'object', properties: {}},
+          annotations: isQuery ? {readOnlyHint: true, ...(d.untrusted && {untrustedContentHint: true})} : a.consequential ? {consequentialHint: true} : {}}
+        const rec: Rec = isQuery ? {e, query: action, a, tool} : {e, action, a, tool}
         recs.set(name, rec)
-        if (e.item) seen.set(name, {e: {...e, ivs: []}, action, a, tool})
+        if (e.item) seen.set(name, {...rec, e: {...e, ivs: []}})
         if (c?.error) {
           tool.error = `SYG240 ${c.error}`
           rec.off = 1
-          dev('SYG240', d, action, comp, `agent.actions.${action}.input: ${c.error}; the tool is not offered`)
+          dev('SYG240', d, action, comp, `${where}.input: ${c.error}; the tool is not offered`)
           continue
         }
-        if (c?.lossy) dev('SYG243', d, action, comp, `agent.actions.${action}.input: the model doesn't see ${c.lossy}`)
+        if (c?.lossy) dev('SYG243', d, action, comp, `${where}.input: the model doesn't see ${c.lossy}`)
         const live = e.ivs.filter(iv => whenOk(iv, action, a.when))
         if (!live.length) { rec.off = 1; continue }
         if (e.item) {
@@ -396,8 +425,8 @@ export function agentTools(target: any, options: AgentToolsOptions = {}) {
       return r ? {ok: false, error: `${name} is not available now`, state: resultState(r.e.ivs[0])} : {ok: false, error: `no tool ${name}; tools: ${list().map(t => t.name).join(', ')}`}
     }
     if (r.tool.error) return {ok: false, error: r.tool.error}
-    const {e, a, action} = r
-    if (!action) return {ok: true, state: context()[e.name]}
+    const {e, a, action, query} = r
+    if (!action && !query) return {ok: true, state: context()[e.name]}
     const key = r.key || 'id', view = e.view
     let raw = args ?? {}, k: any
     if (e.item) {
@@ -418,18 +447,20 @@ export function agentTools(target: any, options: AgentToolsOptions = {}) {
     }
     let iv = resolve()
     if (!iv) return e.item ? missing(e, view, k) : {ok: false, error: `${e.name} is not on the page`}
-    if (!whenOk(iv, action, a.when)) return {ok: false, error: `${name} is not available now`, state: resultState(iv)}
+    if (query) return ask(name, iv, query, a, data)
+    const type = action as string
+    if (!whenOk(iv, type, a.when)) return {ok: false, error: `${name} is not available now`, state: resultState(iv)}
     if (a.consequential) {
       const c = 'confirm' in o ? o.confirm : options.confirm
-      const info: ConfirmInfo = {tool: name, component: iv.name, action, description: a.description, input: data, ...(e.item && {key: k, label: labelOf(iv)})}
+      const info: ConfirmInfo = {tool: name, component: iv.name, action: type, description: a.description, input: data, ...(e.item && {key: k, label: labelOf(iv)})}
       if (!(typeof c == 'function' ? await c(info) : c === true)) return {ok: false, error: 'the user declined'}
       // the app may have changed while the user decided: resolve and check again
       iv = resolve()
       if (!iv) return e.item ? {...missing(e, view, k), error: `the ${e.name} with id ${JSON.stringify(k)} is gone`} : {ok: false, error: `${e.name} is not on the page any more`}
-      if (!whenOk(iv, action, a.when)) return {ok: false, error: `${name} is not available any more`, state: resultState(iv)}
+      if (!whenOk(iv, type, a.when)) return {ok: false, error: `${name} is not available any more`, state: resultState(iv)}
     }
-    const rec: Call = pending = {id: iv.id, type: action, data, ran: false, out: []}
-    api.dispatch(iv.id, action, data, 'agent')
+    const rec: Call = pending = {id: iv.id, type, data, ran: false, out: []}
+    api.dispatch(iv.id, type, data, 'agent')
     await api.flushed()
     if (pending === rec) pending = null
     if (current === rec) current = null
@@ -440,12 +471,66 @@ export function agentTools(target: any, options: AgentToolsOptions = {}) {
     if (iv.disposed && e.item) iv = resolve() || iv
     const gone = iv.disposed
     const state = gone ? resultState(api.get(iv.parentId)) : resultState(iv)
-    if (out.some(x => x.kind == 'changed' || x.kind == 'sent' || x.kind == 'effect')) return gone ? {ok: true, removed: true, state} : {ok: true, state}
+    if (out.some(x => x.kind == 'changed' || x.kind == 'sent' || x.kind == 'effect')) return gone ? {ok: true, removed: true, state} : a.until ? settle(name, iv, type, a) : {ok: true, state}
     if (refused) return {ok: false, error: `${action} was refused: ${refused.reason}`, state}
     return a.idempotent ? {ok: true, unchanged: true, state} : {ok: false, error: `${action} changed nothing (already so, or the input matched nothing)`, state}
   }
 
+  /** `until` as a predicate: a resource name is done when that resource is neither loading nor refreshing */
+  const doneTest = (iv: any, action: string, u: any): ((s: any) => boolean) | undefined => {
+    if (typeof u == 'function') return u
+    if (typeof u != 'string') return
+    const res = iv.def.view.resources
+    if (!res || !(u in res)) {
+      dev('SYG248', declOf(iv), 'until' + action, iv.name, `agent.actions.${action}.until names '${u}', which is not one of ${iv.name}'s resources${res ? ` (${Object.keys(res).join(', ')})` : ''}; the call answers at once`)
+      return
+    }
+    return (s: any) => { const r = s?.[u]; return !r || (r.status != 'loading' && !r.refreshing) }
+  }
+  /**
+   * `until`: answer once the action's result is in state (after this flush or a later one), or
+   * with `pending` on `timeout` / `cancel()`; `removed` when the instance went away meanwhile
+   */
+  function settle(name: string, iv: any, action: string, a: any): AgentResult | Promise<AgentResult> {
+    const test = doneTest(iv, action, a.until)
+    const holds = () => {
+      if (!test) return true
+      try { return !!test(iv.state) } catch (err: any) {
+        dev('SYG241', declOf(iv), 'until' + action, iv.name, `agent.actions.${action}.until threw: ${err?.message ?? err}`)
+        return true
+      }
+    }
+    const result = (extra?: any): AgentResult => ({ok: true, ...extra, state: iv.disposed ? resultState(api.get(iv.parentId)) : resultState(iv)})
+    if (holds()) return result()
+    return new Promise(resolve => {
+      const finish = (extra?: any) => { waiters.delete(check); cancels.delete(cancel); clearTimeout(timer); resolve(result(extra)) }
+      const cancel = () => finish({pending: true, note: `${name} is still in progress: its result will be in the app state later`})
+      const check = () => stopped ? cancel() : iv.disposed ? finish({removed: true}) : holds() && finish()
+      const timer = setTimeout(cancel, a.timeout ?? 10000)
+      waiters.add(check)
+      cancels.add(cancel)
+    })
+  }
+
+  /** a query call: `run(state, input)` on the instance's state now; nothing is dispatched */
+  function ask(name: string, iv: any, query: string, q: any, data: any): AgentResult {
+    if (!whenOk(iv, query, q.when)) return {ok: false, error: `${name} is not available now`}
+    let result: any
+    try { result = q.run(iv.state, data) } catch (err: any) {
+      const m = err?.message ?? err
+      dev('SYG241', declOf(iv), 'query' + query, iv.name, `agent.queries.${query}.run threw: ${m}`)
+      return {ok: false, error: `${name} failed: ${m}`}
+    }
+    if (result && typeof result.then == 'function') {
+      dev('SYG246', declOf(iv), 'promise' + query, iv.name, `agent.queries.${query}.run returned a promise: a query is a pure, synchronous function of the state`)
+      return {ok: false, error: `${name} is not available: it returned a promise`}
+    }
+    return {ok: true, result}
+  }
+
   return {
+    /** answer every call waiting on `until` now, as `pending` (a chat turn stopped or replaced) */
+    cancel() { for (const c of [...cancels]) c() },
     /** the offered tools; `{ all: true }` adds declared tools that can't be offered (`error`, SYG240) */
     list,
     /** run a tool as an agent: resolves with the result after the action's flush */
@@ -457,7 +542,7 @@ export function agentTools(target: any, options: AgentToolsOptions = {}) {
       dirty()
       return () => { listeners.delete(fn) }
     },
-    stop() { stopped = true; off?.(); listeners.clear() },
+    stop() { stopped = true; off?.(); listeners.clear(); for (const c of [...cancels]) c() },
     /** internal (A-2, WebMCP; chat; the command bar): the offered tools grouped by declaration, with `untrusted` as declared and an item declaration's live labels (id → `agent.label`) */
     groups(): AgentGroup[] {
       const rs = [...build().values()]