sygnal 6.1.1 → 6.2.0

package/dist/index.cjs.js

@@ -744,6 +744,9 @@ const DEV_CODE_SEVERITY = {
     SYG240: 'error',
     SYG241: 'error',
     SYG243: 'warn',
+    SYG246: 'error',
+    SYG247: 'warn',
+    SYG248: 'warn',
     // PLAN-6 A-2 (WebMCP, reported with the severity passed)
     SYG242: 'warn',
     SYG244: 'warn',
@@ -12688,7 +12691,8 @@ async function parseInput(schema, args, options = {}) {
  * `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:
@@ -12707,12 +12711,24 @@ async function parseInput(schema, args, options = {}) {
  *   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.
  */
 const snake = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/\W+/g, '_').toLowerCase();
 const keyOf$1 = (iv) => iv.state?.id;
@@ -12725,9 +12741,9 @@ const dev$2 = (code, decl, what, component, message) => {
     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
+    // 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' ? 'error' : 'warn' });
+        report(code, { component, message, severity: code < 'SYG242' || code == 'SYG246' ? 'error' : 'warn' });
     }
     catch (e) {
         queueMicrotask(() => { throw e; });
@@ -12826,6 +12842,17 @@ function agentTools(target, options = {}) {
     const owners = new Map();
     const listeners = new Set();
     let last, 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(), cancels = new Set();
+    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++;
         if (!listeners.size || scheduled || stopped)
@@ -12836,10 +12863,10 @@ function agentTools(target, options = {}) {
     };
     const hooks = {
         onCreate: dirty,
-        onPatch: dirty,
-        onReducer: dirty,
+        onPatch: changed,
+        onReducer: changed,
         onDispose: (iv) => {
-            dirty();
+            changed();
             // HMR: run()'s hmr() disposes this app, starts its successor and swaps __runtime
             if (iv.isRoot && isApp)
                 queueMicrotask(rebind);
@@ -13009,24 +13036,39 @@ function agentTools(target, options = {}) {
             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 = [];
+            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$2('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$2('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 = { name, description: a.description, inputSchema: c?.schema || { type: 'object', properties: {} }, annotations: a.consequential ? { consequentialHint: true } : {} };
-                const rec = { e, action, a, tool };
+                const tool = { name, description: a.description, inputSchema: c?.schema || { type: 'object', properties: {} },
+                    annotations: isQuery ? { readOnlyHint: true, ...(d.untrusted && { untrustedContentHint: true }) } : a.consequential ? { consequentialHint: true } : {} };
+                const 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 });
+                    seen.set(name, { ...rec, e: { ...e, ivs: [] } });
                 if (c?.error) {
                     tool.error = `SYG240 ${c.error}`;
                     rec.off = 1;
-                    dev$2('SYG240', d, action, comp, `agent.actions.${action}.input: ${c.error}; the tool is not offered`);
+                    dev$2('SYG240', d, action, comp, `${where}.input: ${c.error}; the tool is not offered`);
                     continue;
                 }
                 if (c?.lossy)
-                    dev$2('SYG243', d, action, comp, `agent.actions.${action}.input: the model doesn't see ${c.lossy}`);
+                    dev$2('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;
@@ -13124,8 +13166,8 @@ function agentTools(target, options = {}) {
         }
         if (r.tool.error)
             return { ok: false, error: r.tool.error };
-        const { e, a, action } = r;
-        if (!action)
+        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;
@@ -13150,22 +13192,25 @@ function agentTools(target, options = {}) {
         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))
+        if (query)
+            return ask(name, iv, query, a, data);
+        const type = action;
+        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 = { tool: name, component: iv.name, action, description: a.description, input: data, ...(e.item && { key: k, label: labelOf(iv) }) };
+            const info = { 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))
+            if (!whenOk(iv, type, a.when))
                 return { ok: false, error: `${name} is not available any more`, state: resultState(iv) };
         }
-        const rec = pending = { id: iv.id, type: action, data, ran: false, out: [] };
-        api.dispatch(iv.id, action, data, 'agent');
+        const rec = pending = { id: iv.id, type, data, ran: false, out: [] };
+        api.dispatch(iv.id, type, data, 'agent');
         await api.flushed();
         if (pending === rec)
             pending = null;
@@ -13182,12 +13227,76 @@ function agentTools(target, options = {}) {
         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 };
+            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, action, u) => {
+        if (typeof u == 'function')
+            return u;
+        if (typeof u != 'string')
+            return;
+        const res = iv.def.view.resources;
+        if (!res || !(u in res)) {
+            dev$2('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) => { 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, iv, action, a) {
+        const test = doneTest(iv, action, a.until);
+        const holds = () => {
+            if (!test)
+                return true;
+            try {
+                return !!test(iv.state);
+            }
+            catch (err) {
+                dev$2('SYG241', declOf(iv), 'until' + action, iv.name, `agent.actions.${action}.until threw: ${err?.message ?? err}`);
+                return true;
+            }
+        };
+        const result = (extra) => ({ ok: true, ...extra, state: iv.disposed ? resultState(api.get(iv.parentId)) : resultState(iv) });
+        if (holds())
+            return result();
+        return new Promise(resolve => {
+            const finish = (extra) => { 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, iv, query, q, data) {
+        if (!whenOk(iv, query, q.when))
+            return { ok: false, error: `${name} is not available now` };
+        let result;
+        try {
+            result = q.run(iv.state, data);
+        }
+        catch (err) {
+            const m = err?.message ?? err;
+            dev$2('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$2('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 */
@@ -13199,7 +13308,8 @@ function agentTools(target, options = {}) {
             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() {
             const rs = [...build().values()];
@@ -17722,15 +17832,15 @@ function experimentalExposeWebMcp(app, options = {}) {
                 o[k] = params(s[k], tool, path);
         return o;
     };
-    /** a result within 1,500 characters of JSON: `state` and long fields are cut first */
+    /** a result within 1,500 characters of JSON: `state`, a query's `result` and long fields are cut first */
     const fit = (r, tool) => {
         if (!r || typeof r != 'object')
             r = { ok: false, error: 'no result' };
         let s = JSON.stringify(r);
         if (s.length <= OUT)
             return r;
-        dev('SYG242', tool + 'out', `a result of ${tool} is ${s.length} characters of JSON, over the budget of ${OUT}; its state is cut (make the agent.read projection smaller)`);
-        const { state, issues, keys, ...rest } = r;
+        dev('SYG242', tool + 'out', `a result of ${tool} is ${s.length} characters of JSON, over the budget of ${OUT}; its ${'result' in r ? 'result' : 'state'} is cut (make ${'result' in r ? "the query's result" : 'the agent.read projection'} smaller)`);
+        const { state, result, issues, keys, ...rest } = r;
         const o = { ...rest, truncated: true };
         if (typeof o.error == 'string')
             o.error = cut(o.error, 400);
@@ -17739,10 +17849,13 @@ function experimentalExposeWebMcp(app, options = {}) {
         for (let room = OUT; room > 20; room = room / 2 | 0) {
             if (state !== undefined)
                 o.state = cut(JSON.stringify(state), room);
+            if (result !== undefined)
+                o.result = cut(JSON.stringify(result), room);
             if (JSON.stringify(o).length <= OUT)
                 return o;
         }
         delete o.state;
+        delete o.result;
         delete o.issues;
         return o;
     };
@@ -18039,7 +18152,8 @@ function checkLinked(sources, name, without) {
  *
  * Actions ('assistant.X'): SEND (the form's submit: the prompt; or a string as data), STOP (aborts
  * the stream, keeps the partial text and reasoning; calls that already ran keep their results,
- * G-626), REGENERATE (replays the last user turn), APPROVE, DENY,
+ * G-626; a call waiting on an action's `until` answers as pending: the tool set's cancel(), as on
+ * FAILED and a new turn), REGENERATE (replays the last user turn), APPROVE, DENY,
  * DONE (the turn is over: `{ message, text, finishReason, usage, steps }`; a host entry
  * 'assistant.DONE' runs after it, like 'form.DONE'). Internal: PROMPT (typing), DELTA / REPLY /
  * FAILED (the chat driver's reply actions), ASK (a consequential call waits), RESULTS (the tool
@@ -18099,8 +18213,14 @@ const askInfo = (p) => {
     const name = p.type.slice(5);
     return { tool: name, component: 'server', action: name, description: p.approval?.requestReason ?? `Run the ${name} tool`, input: p.input, approvalId: p.approval?.id };
 };
-/** a tool part with an A-1 result (`{ output }` or `{ error }`) */
-const withResult = (p, r) => 'error' in r ? { ...p, state: 'output-error', errorText: r.error } : { ...p, state: 'output-available', output: r.output };
+/**
+ * a tool part with an A-1 result (`{ output }` or `{ error }`); the other side's field goes (a late
+ * result replaces the "not run" error of a stopped turn, G-626)
+ */
+const withResult = (p, r) => {
+    const { output: _o, errorText: _e, ...rest } = p;
+    return 'error' in r ? { ...rest, state: 'output-error', errorText: r.error } : { ...rest, state: 'output-available', output: r.output };
+};
 /**
  * The last message with its open tool parts closed (a turn stopped, failed or capped): a call
  * that already ran gets its result (`ran`, G-626), the others `why`; a server approval still
@@ -18215,10 +18335,12 @@ function appState(t, groups, labels) {
 function request(e, o, k, messages, fresh) {
     const t = e && toolsOf$1(e);
     if (e) {
+        // a new turn: a call still waiting on `until` answers now, as pending
         if (fresh) {
             e.turn++;
             e.steps = 0;
             e.answer?.(false);
+            e.tools?.cancel();
         }
         e.steps++;
     }
@@ -18354,6 +18476,7 @@ const chat = (options = {}) => {
                 EFFECT: (s, _d, _n, p, o, k) => { const e = busy$1(s) && E(p, k, o); if (e) {
                     e.turn++;
                     e.answer?.(false);
+                    e.tools?.cancel();
                 } },
             },
             FAILED: {
@@ -18361,6 +18484,7 @@ const chat = (options = {}) => {
                 EFFECT: (_s, _d, _n, p, o, k) => { const e = E(p, k, o); if (e) {
                     e.turn++;
                     e.answer?.(false);
+                    e.tools?.cancel();
                 } },
             },
             // (REPLY already set ready: a host entry gets the finished state)