akanjs 3.0.0-alpha.102 → 3.0.0-alpha.103

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.102",
+  "version": "3.0.0-alpha.103",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/signal/serializer/fetch.serializer.ts

@@ -3,7 +3,6 @@ import { Logger } from "akanjs/common";
 import { ConstantRegistry, type ConstantType } from "akanjs/constant";
 import { type FilterArgInfo, getFilterArgInfos, getFilterMeta } from "akanjs/document";
 import type { LiveRegistry } from "akanjs/service";
-import { refusesAgents } from "../guard";
 import type {
   ArgInfo,
   EndpointArgProps,
@@ -19,6 +18,7 @@ import type {
   SliceCls,
   SliceInfo,
 } from "akanjs/signal";
+import { refusesAgents } from "../guard";
 
 export class FetchSerializer {
   static logger = new Logger("FetchSerializer");

package/store/agent/AgentBridge.ts

@@ -61,9 +61,11 @@ export class AgentBridge {
    */
   read(key: string, viewKey = ""): unknown {
     const entry = this.#state[key];
-    if (!entry) throw new Error(`Unknown state key: ${key}`);
+    if (!entry) throw new Error(`Unknown state key: ${key}.${this.#readableInstead(viewKey)}`);
     if (!this.#instance.liveKeysIn(viewKey).has(key))
-      throw new Error(`State key "${key}" is not read by this screen, so it is not part of its surface.`);
+      throw new Error(
+        `State key "${key}" is not read by this screen, so it is not part of its surface.${this.#readableInstead(viewKey)}`,
+      );
     const value = AgentBridge.#unwrap(this.#instance.get()[key]);
     if (entry.refName && entry.modelType) {
       const model = ConstantRegistry.getModelRef(entry.refName, entry.modelType) as MaskModel;
@@ -75,6 +77,12 @@ export class AgentBridge {
     );
   }
 
+  /** Named the way `readScreen` and `highlight` name theirs: a refusal with no way forward costs a whole turn. */
+  #readableInstead(viewKey: string): string {
+    const keys = this.readableKeys(viewKey);
+    return keys.length ? ` Readable here: ${keys.join(", ")}.` : " This screen reads no state keys.";
+  }
+
   static #unwrap(value: unknown) {
     return value instanceof DataList ? value.values : value;
   }

package/types/vendor/use-agentic/AgentSession.d.ts

@@ -1,4 +1,4 @@
-import { type AgentProgressReport } from "./AgentProgress.d.ts";
+import type { AgentProgressReport } from "./AgentProgress.d.ts";
 import { type CompactOptions } from "./Compaction.d.ts";
 import type { AgentRunner, ChatMessage, ContextBlock, PublishedTool, SurfaceView } from "./types.d.ts";
 export interface PendingApproval {

package/types/vendor/use-agentic/ToolRunner.d.ts

@@ -0,0 +1,70 @@
+import { type AgentProgressReport } from "./AgentProgress.d.ts";
+import type { SurfaceView, ToolCallRequest, ToolCallResult, ToolEntry } from "./types.d.ts";
+export interface ToolApprovalRequest {
+    callId: string;
+    name: string;
+    args: Record<string, unknown>;
+    /** What the user is asked, already resolved from the entry's `confirm`. */
+    message: string;
+}
+/** `report` is `null` once the call is over, carrying the id so a host can ignore a clear that is not its own. */
+export interface ToolProgress {
+    callId: string;
+    report: AgentProgressReport | null;
+}
+/**
+ * What a consumer of the runner has to answer for. Every field is optional and every omission is a narrowing,
+ * never a widening: a host that cannot ask the user refuses the calls that need asking.
+ */
+export interface ToolRunnerHost {
+    /**
+     * Parks the call until the user decides — `true` runs it, a string is the refusal the model reads.
+     *
+     * Omitting it does **not** run the tool unasked. A tool reaches this only when its own declaration said a
+     * person has to agree first (`confirm`, or a `remove*` name), so a host with nowhere to render the question is
+     * a host that may not perform the action, and the refusal says so rather than silently downgrading the gate.
+     */
+    approve?: (request: ToolApprovalRequest, signal: AbortSignal) => Promise<true | string>;
+    /**
+     * Awaited after a tool that changed something and before its change report is taken. A surface is read
+     * synchronously and a screen does not settle synchronously, so without this the report describes the moment
+     * before the change landed.
+     */
+    settle?: () => Promise<void> | void;
+    progress?: (progress: ToolProgress) => void;
+    /**
+     * Answers a name the surface does not carry — where a consumer puts a built-in of its own. Reached only after
+     * the surface came up empty, so a registered tool of the same name shadows it.
+     */
+    fallback?: (call: ToolCallRequest, signal: AbortSignal) => Promise<ToolCallResult> | ToolCallResult;
+}
+/**
+ * One tool call, start to finish: look the name up, gate it on the user, run it, wait for the screen, report what
+ * changed, and bound what all of that may add to a transcript.
+ *
+ * It lives apart from `AgentSession` because the pipeline is not the conversation's — the same six steps have to
+ * happen for any caller that drives this surface, and the steps that can be skipped are the ones that must not
+ * be: an approval, a settle, a change report and an output ceiling are each invisible by absence. A second
+ * consumer assembling them again would not fail, it would quietly do less, which is how the session and a zone
+ * came to disagree about which options they honoured.
+ */
+export declare class ToolRunner {
+    #private;
+    constructor(surface: SurfaceView, host?: ToolRunnerHost);
+    /** Never throws: a refused guard, a declined approval and an unknown name are all results the model reads. */
+    run(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult>;
+    /**
+     * The call, or the abort — whichever lands first.
+     *
+     * A tool is handed the signal through `AgentAbort` and may stop itself, but nothing obliges it to, and a tool
+     * that waits on a two-minute job is exactly the one a user reaches for Stop during. Without this race the
+     * caller stays parked inside the call for those two minutes with the chat still showing a turn in flight.
+     *
+     * The losing promise is left running rather than cancelled: the work is usually a job a server is already
+     * doing, and throwing away a result that is about to land helps nobody. Both of its outcomes are handled here,
+     * so a late failure settles nothing instead of surfacing as an unhandled rejection.
+     */
+    static raced<T>(work: Promise<T>, signal: AbortSignal): Promise<T>;
+    /** `null` when this call needs no asking — an absent `confirm`, or one that decided against it per arguments. */
+    static confirmMessage(name: string, entry: ToolEntry, args: Record<string, unknown>): string | null;
+}

package/types/vendor/use-agentic/index.d.ts

@@ -10,6 +10,7 @@ export * from "./httpRunner.d.ts";
 export * from "./sharedContext.d.ts";
 export * from "./surfaceContext.d.ts";
 export * from "./ToolOutput.d.ts";
+export * from "./ToolRunner.d.ts";
 export * from "./Transcript.d.ts";
 export * from "./types.d.ts";
 export * from "./useAgent.d.ts";

package/vendor/use-agentic/AgentSession.ts

@@ -1,7 +1,6 @@
-import { AgentAbort } from "./AgentAbort";
-import { AgentProgress, type AgentProgressReport } from "./AgentProgress";
+import type { AgentProgressReport } from "./AgentProgress";
 import { Compaction, type CompactOptions } from "./Compaction";
-import { ToolOutput } from "./ToolOutput";
+import { type ToolApprovalRequest, ToolRunner } from "./ToolRunner";
 import { Transcript } from "./Transcript";
 import type {
   AgentRunner,
@@ -12,7 +11,6 @@ import type {
   SurfaceView,
   ToolCallRequest,
   ToolCallResult,
-  ToolEntry,
 } from "./types";
 
 export interface PendingApproval {
@@ -127,6 +125,7 @@ export class AgentSession {
   readonly #surface: SurfaceView;
   readonly #runner: AgentRunner;
   readonly #options: AgentSessionOptions;
+  readonly #tools: ToolRunner;
   #messages: ChatMessage[] = [];
   #running = false;
   #pending: PendingApproval | null = null;
@@ -150,6 +149,20 @@ export class AgentSession {
     this.#surface = surface;
     this.#runner = runner;
     this.#options = options;
+    this.#tools = new ToolRunner(surface, {
+      approve: (request, signal) => this.#awaitApproval(request, signal),
+      settle: () => this.#options.settle?.(),
+      progress: ({ callId, report }) => {
+        if (report) this.#progress = { ...report, callId };
+        else if (this.#progress?.callId === callId) this.#progress = null;
+        else return;
+        this.#notify();
+      },
+      fallback: async (call, signal) =>
+        call.name === AgentSession.askUserTool.name
+          ? await this.#ask(call, signal)
+          : { id: call.id, name: call.name, error: `Unknown tool: ${call.name}` },
+    });
     this.#history = options.history;
     this.#onCompact = options.onCompact;
     const restored = AgentSession.#restored(options.history);
@@ -256,9 +269,7 @@ export class AgentSession {
           toolResults.push(
             controller.signal.aborted
               ? { id: call.id, name: call.name, error: Transcript.unanswered }
-              : 
-                
-                ToolOutput.clipped(await this.#execute(call, controller.signal)),
+              : await this.#tools.run(call, controller.signal),
           );
         this.#append({ role: "tool", toolResults });
       }
@@ -495,47 +506,6 @@ export class AgentSession {
     return { toolCalls, stop };
   }
 
-  async #execute(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult> {
-    const base = { id: call.id, name: call.name };
-    const entry = this.#surface.tool(call.name);
-    if (!entry) {
-      if (call.name === AgentSession.askUserTool.name) return await this.#ask(call, signal);
-      return { ...base, error: `Unknown tool: ${call.name}` };
-    }
-    const message = AgentSession.#confirmMessage(call.name, entry, call.args);
-    if (message) {
-      const approved = await this.#awaitApproval(call, message, signal);
-      if (approved !== true) return { ...base, error: approved };
-    }
-    const before = this.#surface.snapshot();
-    try {
-      const result = await AgentAbort.run(signal, () =>
-        AgentProgress.run(
-          (report) => {
-            this.#progress = { ...report, callId: call.id };
-            this.#notify();
-          },
-          () => AgentSession.#raced(this.#surface.call(call.name, call.args), signal),
-        ),
-      );
-
-      if (entry.settle !== false) await this.#options.settle?.();
-      const changes = this.#surface.diffSince(before);
-      return {
-        ...base,
-        ...(result !== undefined ? { result } : {}),
-        ...(changes.length ? { changes } : {}),
-      };
-    } catch (error) {
-      return { ...base, error: error instanceof Error ? error.message : String(error) };
-    } finally {
-      if (this.#progress?.callId === call.id) {
-        this.#progress = null;
-        this.#notify();
-      }
-    }
-  }
-
   /** `null` when the user declined or no ask is configured: both mean stop and record why. */
   async #askToContinue(turns: number, signal: AbortSignal): Promise<string | null> {
     const ask = this.#options.continueAsk?.();
@@ -591,7 +561,7 @@ export class AgentSession {
     });
   }
 
-  #awaitApproval(call: ToolCallRequest, message: string, signal: AbortSignal): Promise<true | string> {
+  #awaitApproval(request: ToolApprovalRequest, signal: AbortSignal): Promise<true | string> {
     return new Promise((resolve) => {
       const settle = (value: true | string) => {
         this.#pending = null;
@@ -602,10 +572,7 @@ export class AgentSession {
       const onAbort = () => settle("The user aborted the turn.");
       signal.addEventListener("abort", onAbort);
       this.#pending = {
-        callId: call.id,
-        name: call.name,
-        args: call.args,
-        message,
+        ...request,
         approve: () => settle(true),
         reject: (reason) => settle(reason ?? "The user declined."),
       };
@@ -613,44 +580,6 @@ export class AgentSession {
     });
   }
 
-  /**
-   * The call, or the abort — whichever lands first.
-   *
-   * A tool is handed the signal through `AgentAbort` and may stop itself, but nothing obliges it to, and a tool
-   * that waits on a two-minute job is exactly the one a user reaches for Stop during. Without this race the loop
-   * stays parked inside the call for those two minutes with the chat still showing a turn in flight.
-   *
-   * The losing promise is left running rather than cancelled: the work is usually a job a server is already
-   * doing, and throwing away a result that is about to land helps nobody. Both of its outcomes are handled here,
-   * so a late failure settles nothing instead of surfacing as an unhandled rejection.
-   */
-  static #raced<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
-    return new Promise<T>((resolve, reject) => {
-      const onAbort = () => reject(new Error("The user aborted the turn."));
-      work.then(
-        (value) => {
-          signal.removeEventListener("abort", onAbort);
-          resolve(value);
-        },
-        (error: unknown) => {
-          signal.removeEventListener("abort", onAbort);
-          reject(error instanceof Error ? error : new Error(String(error)));
-        },
-      );
-      if (signal.aborted) onAbort();
-      else signal.addEventListener("abort", onAbort, { once: true });
-    });
-  }
-
-  static #confirmMessage(name: string, entry: ToolEntry, args: Record<string, unknown>): string | null {
-    const confirm = entry.confirm;
-    if (confirm === undefined || confirm === false) return null;
-    if (typeof confirm === "string") return confirm;
-    const verdict = confirm === true ? true : confirm(args);
-    if (verdict === false) return null;
-    return verdict === true ? `Run ${name}?` : verdict;
-  }
-
   static #defaultContext(surface: SurfaceView): ContextBlock[] {
     const { resources, scopes } = surface.snapshot();
     return [

package/vendor/use-agentic/ToolRunner.ts

@@ -0,0 +1,174 @@
+import { AgentAbort } from "./AgentAbort";
+import { AgentProgress, type AgentProgressReport } from "./AgentProgress";
+import { ToolOutput } from "./ToolOutput";
+import type { SurfaceView, ToolCallRequest, ToolCallResult, ToolEntry } from "./types";
+
+export interface ToolApprovalRequest {
+  callId: string;
+  name: string;
+  args: Record<string, unknown>;
+  /** What the user is asked, already resolved from the entry's `confirm`. */
+  message: string;
+}
+
+/** `report` is `null` once the call is over, carrying the id so a host can ignore a clear that is not its own. */
+export interface ToolProgress {
+  callId: string;
+  report: AgentProgressReport | null;
+}
+
+/**
+ * What a consumer of the runner has to answer for. Every field is optional and every omission is a narrowing,
+ * never a widening: a host that cannot ask the user refuses the calls that need asking.
+ */
+export interface ToolRunnerHost {
+  /**
+   * Parks the call until the user decides — `true` runs it, a string is the refusal the model reads.
+   *
+   * Omitting it does **not** run the tool unasked. A tool reaches this only when its own declaration said a
+   * person has to agree first (`confirm`, or a `remove*` name), so a host with nowhere to render the question is
+   * a host that may not perform the action, and the refusal says so rather than silently downgrading the gate.
+   */
+  approve?: (request: ToolApprovalRequest, signal: AbortSignal) => Promise<true | string>;
+  /**
+   * Awaited after a tool that changed something and before its change report is taken. A surface is read
+   * synchronously and a screen does not settle synchronously, so without this the report describes the moment
+   * before the change landed.
+   */
+  settle?: () => Promise<void> | void;
+  progress?: (progress: ToolProgress) => void;
+  /**
+   * Answers a name the surface does not carry — where a consumer puts a built-in of its own. Reached only after
+   * the surface came up empty, so a registered tool of the same name shadows it.
+   */
+  fallback?: (call: ToolCallRequest, signal: AbortSignal) => Promise<ToolCallResult> | ToolCallResult;
+}
+
+/**
+ * One tool call, start to finish: look the name up, gate it on the user, run it, wait for the screen, report what
+ * changed, and bound what all of that may add to a transcript.
+ *
+ * It lives apart from `AgentSession` because the pipeline is not the conversation's — the same six steps have to
+ * happen for any caller that drives this surface, and the steps that can be skipped are the ones that must not
+ * be: an approval, a settle, a change report and an output ceiling are each invisible by absence. A second
+ * consumer assembling them again would not fail, it would quietly do less, which is how the session and a zone
+ * came to disagree about which options they honoured.
+ */
+export class ToolRunner {
+  /**
+   * Tool execution is serialized across every runner in the page, because `AgentAbort` and `AgentProgress` reach
+   * the running call through a module slot rather than a parameter — two calls in flight restore each other's
+   * slot and the second one's progress goes nowhere. Two agents on one screen (a zone and the root chat) are
+   * already two callers, so the invariant those slots assume has to be kept somewhere they both pass through.
+   *
+   * A call that neither settles nor aborts holds the queue; every consumer races the call against its own abort
+   * signal, and an abort releases it. Approval waits outside the queue on purpose — a question parked in front of
+   * the user is not work, and holding the lock across it would let one agent's unanswered card freeze the other's.
+   */
+  static #queue: Promise<void> = Promise.resolve();
+
+  readonly #surface: SurfaceView;
+  readonly #host: ToolRunnerHost;
+
+  constructor(surface: SurfaceView, host: ToolRunnerHost = {}) {
+    this.#surface = surface;
+    this.#host = host;
+  }
+
+  /** Never throws: a refused guard, a declined approval and an unknown name are all results the model reads. */
+  async run(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult> {
+    
+    return ToolOutput.clipped(await this.#answer(call, signal));
+  }
+
+  async #answer(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult> {
+    const base = { id: call.id, name: call.name };
+    const entry = this.#surface.tool(call.name);
+    if (!entry) {
+      const fallback = this.#host.fallback;
+      return fallback ? await fallback(call, signal) : { ...base, error: `Unknown tool: ${call.name}` };
+    }
+    const message = ToolRunner.confirmMessage(call.name, entry, call.args);
+    if (message) {
+      const approve = this.#host.approve;
+      if (!approve)
+        return { ...base, error: `${call.name} needs the user's approval, and nothing here can ask them for it.` };
+      const approved = await approve({ callId: call.id, name: call.name, args: call.args, message }, signal);
+      if (approved !== true) return { ...base, error: approved };
+    }
+    return await ToolRunner.#serialized(() => this.#execute(call, entry, signal));
+  }
+
+  async #execute(call: ToolCallRequest, entry: ToolEntry, signal: AbortSignal): Promise<ToolCallResult> {
+    const base = { id: call.id, name: call.name };
+    const before = this.#surface.snapshot();
+    try {
+      const result = await AgentAbort.run(signal, () =>
+        AgentProgress.run(
+          (report) => this.#host.progress?.({ callId: call.id, report }),
+          () => ToolRunner.raced(this.#surface.call(call.name, call.args), signal),
+        ),
+      );
+
+      if (entry.settle !== false) await this.#host.settle?.();
+      const changes = this.#surface.diffSince(before);
+      return {
+        ...base,
+        ...(result !== undefined ? { result } : {}),
+        ...(changes.length ? { changes } : {}),
+      };
+    } catch (error) {
+      return { ...base, error: error instanceof Error ? error.message : String(error) };
+    } finally {
+      this.#host.progress?.({ callId: call.id, report: null });
+    }
+  }
+
+  static #serialized<T>(work: () => Promise<T>): Promise<T> {
+    const run = ToolRunner.#queue.then(work);
+    ToolRunner.#queue = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  /**
+   * The call, or the abort — whichever lands first.
+   *
+   * A tool is handed the signal through `AgentAbort` and may stop itself, but nothing obliges it to, and a tool
+   * that waits on a two-minute job is exactly the one a user reaches for Stop during. Without this race the
+   * caller stays parked inside the call for those two minutes with the chat still showing a turn in flight.
+   *
+   * The losing promise is left running rather than cancelled: the work is usually a job a server is already
+   * doing, and throwing away a result that is about to land helps nobody. Both of its outcomes are handled here,
+   * so a late failure settles nothing instead of surfacing as an unhandled rejection.
+   */
+  static raced<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const onAbort = () => reject(new Error("The user aborted the turn."));
+      work.then(
+        (value) => {
+          signal.removeEventListener("abort", onAbort);
+          resolve(value);
+        },
+        (error: unknown) => {
+          signal.removeEventListener("abort", onAbort);
+          reject(error instanceof Error ? error : new Error(String(error)));
+        },
+      );
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
+  /** `null` when this call needs no asking — an absent `confirm`, or one that decided against it per arguments. */
+  static confirmMessage(name: string, entry: ToolEntry, args: Record<string, unknown>): string | null {
+    const confirm = entry.confirm;
+    if (confirm === undefined || confirm === false) return null;
+    if (typeof confirm === "string") return confirm;
+    const verdict = confirm === true ? true : confirm(args);
+    if (verdict === false) return null;
+    return verdict === true ? `Run ${name}?` : verdict;
+  }
+}

package/vendor/use-agentic/index.ts

@@ -11,6 +11,7 @@ export * from "./httpRunner";
 export * from "./sharedContext";
 export * from "./surfaceContext";
 export * from "./ToolOutput";
+export * from "./ToolRunner";
 export * from "./Transcript";
 export * from "./types";
 export * from "./useAgent";