akanjs 3.1.1-rc.3 → 3.1.1-rc.4

package/client/router.ts

@@ -180,7 +180,7 @@ export const getPathInfo = (requestUrl: string, lang: string, prefix: string) =>
   return { path, pathname, hash, search, href };
 };
 class Router {
-  isInitialized = false;
+  isInitialized: boolean = false;
   #prefix = "";
   #lang = parseAkanI18nEnv().defaultLocale;
   #routePaths = new Set<string>();
@@ -193,6 +193,8 @@ class Router {
   #backsAwaitingPopstate = 0;
   #redirects = 0;
   #navigations = 0;
+  
+  #beforeInit: (() => void)[] = [];
   #instance: RouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
@@ -227,6 +229,7 @@ class Router {
     else if (options.side === "client") this.#initSsrClientRouter(options);
     this.isInitialized = true;
     Logger.verbose("Router initialized");
+    for (const call of this.#beforeInit.splice(0)) call();
   }
   #initSsrClientRouter(options: SsrClientRouterOption) {
     this.#historyWrittenByNavigation = true;
@@ -282,6 +285,27 @@ class Router {
   #checkInitialized() {
     if (!this.isInitialized) throw new Error("Router is not initialized");
   }
+  #deferredUntilInit(call: () => void) {
+    if (this.isInitialized || getEnv().side === "server") return false;
+    this.#track(
+      new Promise<void>((resolve, reject) => {
+        this.#beforeInit.push(() => {
+          const pending = this.#navigation;
+          try {
+            call();
+          } catch (error) {
+            Logger.error(`A navigation made before the router was initialized failed: ${String(error)}`);
+            reject(error);
+            return;
+          }
+          
+          if (this.#navigation === pending) resolve();
+          else this.#navigation.then(resolve, reject);
+        });
+      }),
+    );
+    return true;
+  }
 
   #ensureHistoryState() {
     if (getEnv().side === "server") return;
@@ -389,7 +413,9 @@ class Router {
     const target = `${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
     return dedupedStack.map((candidate, index) => (index === dedupedStack.length - 1 ? target : candidate));
   }
+  /** Before init the link waits for it, and the answer is `true`: the manifest that could refuse it is not loaded yet. */
   enterDeepLink(href: string, options: DeepLinkOptions = {}) {
+    if (this.#deferredUntilInit(() => this.enterDeepLink(href, options))) return true;
     this.#checkInitialized();
     if (!options.resetStack) {
       this.push(normalizeDeepLinkHref(href), options);
@@ -405,6 +431,7 @@ class Router {
     return true;
   }
   push(href: string, routeOptions?: RouteOptions) {
+    if (this.#deferredUntilInit(() => this.push(href, routeOptions))) return undefined as never;
     this.#checkInitialized();
     if (this.#refusesOffsite("push", href, routeOptions)) return undefined as never;
     this.#navigations += 1;
@@ -414,6 +441,7 @@ class Router {
     return undefined as never;
   }
   replace(href: string, routeOptions?: RouteOptions) {
+    if (this.#deferredUntilInit(() => this.replace(href, routeOptions))) return undefined as never;
     this.#checkInitialized();
     if (this.#refusesOffsite("replace", href, routeOptions)) return undefined as never;
     this.#navigations += 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.1.1-rc.3",
+  "version": "3.1.1-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/service/agent.service.ts

@@ -35,13 +35,16 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
 
   /**
    * Prepended to the app's instructions here, not per adaptor, where forgetting it would be silent. The batching and
-   * no-re-read sentences were measured to cut turns against a provider; do not shorten them.
+   * no-re-read sentences were measured to cut turns against a provider; do not shorten them. The navigation sentence
+   * carves the batching rule: a call batched behind `navigate` was written against the screen being left.
    */
   static readonly preamble = [
     "You are an in-page assistant. Use the published tools to read and drive the screen the user is looking at.",
     "Issue every tool call that does not need another call's result in the same turn, rather than one call per turn.",
     "Prefer the tool that does the whole job in one call, such as a form's fill tool over one call per field.",
     "A tool result already reports what it changed, so never call a read afterwards to confirm work you have just done — answer the user from the results you already have.",
+    "Tools belong to the screen on display: navigate and goBack replace the screen's own tools, and the new screen's are listed only on your next turn, so end the turn at a navigation and call them once they are listed.",
+    "Call a tool only by a name listed to you — never compose or guess one.",
   ].join(" ");
 
   static instructed(request: LlmTurnRequest): LlmTurnRequest {

package/service/predefinedAdaptor/openaiLlm.ts

@@ -1,5 +1,13 @@
 import { adapt } from "../adapt";
-import type { LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import {
+  type LlmAccepts,
+  type LlmAdaptor,
+  type LlmLimits,
+  type LlmOption,
+  type LlmTurnAnswer,
+  type LlmTurnRequest,
+  llmProviderOf,
+} from "./llm.adaptor";
 import { LlmOverflow } from "./llmOverflow";
 import { type OpenaiAnswer, OpenaiDialect } from "./openaiDialect";
 
@@ -24,10 +32,18 @@ export class OpenaiLlm
     return this.llmOption.contextWindow ? { window: this.llmOption.contextWindow } : {};
   }
 
-  /** A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn. */
   get accepts(): LlmAccepts | undefined {
-    if (this.llmOption.accepts) return this.llmOption.accepts;
-    return this.llmOption.host ? undefined : { image: true };
+    return OpenaiLlm.acceptsOf(this.llmOption);
+  }
+
+  /**
+   * A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn.
+   * OpenAI's own endpoint named outright is still OpenAI rather than a gateway. Static, so an app's own
+   * chat-completions adaptor claims what this one does instead of forking the rule.
+   */
+  static acceptsOf({ accepts, host }: LlmOption): LlmAccepts | undefined {
+    if (accepts) return accepts;
+    return !host || llmProviderOf(host) === llmProviderOf(OpenaiLlm.defaultHost) ? { image: true } : undefined;
   }
 
   async chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null> {

package/store/agent/AgentVisual.ts

@@ -1,4 +1,3 @@
-import { router } from "akanjs/client";
 import type { ToolActivity } from "../../vendor/use-agentic";
 import { AgentCursor } from "./AgentCursor";
 import { ScreenFlash } from "./ScreenFlash";
@@ -108,28 +107,17 @@ export class AgentVisual {
   }
 
   static #linkTo(path: unknown): HTMLElement[] {
-    const wanted = AgentVisual.#routeOf(typeof path === "string" ? path : "");
+    const wanted = ScreenTarget.routeOf(typeof path === "string" ? path : "");
     if (!wanted || !document.body) return [];
     const links = [...document.body.querySelectorAll<HTMLAnchorElement>("a[href]")].filter(
       (link) =>
-        AgentVisual.#routeOf(link.getAttribute("href") ?? "") === wanted &&
+        ScreenTarget.routeOf(link.getAttribute("href") ?? "") === wanted &&
         ScreenTarget.visible(link) &&
         ScreenFlash.inView(link),
     );
     return AgentVisual.#only(links);
   }
 
-  static #routeOf(href: string) {
-    if (!href || href.startsWith("#")) return "";
-    try {
-      const url = new URL(href, window.location.href);
-      if (url.origin !== window.location.origin) return "";
-      return router.routeOf(url.pathname);
-    } catch {
-      return "";
-    }
-  }
-
   static #navigating(name: string) {
     return name.slice(name.lastIndexOf(".") + 1) === "navigate";
   }

package/store/agent/ScreenTarget.ts

@@ -1,3 +1,4 @@
+import { router } from "akanjs/client";
 import { ScreenReader } from "./ScreenReader";
 
 const containerAttrs = ["data-agent-zone", "data-agent-scope", "data-agent-skip"] as const;
@@ -75,6 +76,30 @@ export class ScreenTarget {
     );
   }
 
+  static linkedRoutes(root?: HTMLElement | null): string[] {
+    const scope = root ?? ScreenTarget.#body();
+    if (!scope) return [];
+    const routes = new Set<string>();
+    for (const link of scope.querySelectorAll<HTMLAnchorElement>("a[href]")) {
+      const route = ScreenTarget.visible(link) ? ScreenTarget.routeOf(link.getAttribute("href") ?? "") : "";
+      if (route) routes.add(route);
+      if (routes.size >= nameCap) break;
+    }
+    return [...routes];
+  }
+
+  /** Through `router.routeOf`: an href carries locale and base-path segments a tool argument lacks. */
+  static routeOf(href: string) {
+    if (!href || href.startsWith("#")) return "";
+    try {
+      const url = new URL(href, window.location.href);
+      if (url.origin !== window.location.origin) return "";
+      return router.routeOf(url.pathname);
+    } catch {
+      return "";
+    }
+  }
+
   static #names(attrs: readonly string[], root?: HTMLElement | null): string[] {
     const scope = root ?? ScreenTarget.#body();
     if (!scope) return [];

package/store/agent/StoreSurfaceSource.ts

@@ -1,4 +1,4 @@
-import { router } from "akanjs/client";
+import { csrLocation, router } from "akanjs/client";
 import { AgenticSurface, type SurfaceSource, type ToolEntry, ToolReturn } from "../../vendor/use-agentic";
 import { AgentBridge } from "./AgentBridge";
 import { ScreenFlash } from "./ScreenFlash";
@@ -58,17 +58,38 @@ export class StoreSurfaceSource implements SurfaceSource {
           router.push(path);
           await router.navigation();
         } catch {
-          throw new Error(
-            `There is no route at ${path}, so the page did not move. Call readScreen — it prints each link on this screen with its own path — and navigate to one of those.`,
-          );
+          throw new Error(`There is no route at ${path}, so the page did not move. ${StoreSurfaceSource.#linked()}`);
         }
         
         await ScreenSettle.wait({ appearMs: 800, timeoutMs: 5000 });
-        return `Now on ${path}. Call readScreen to see it; this screen's own tools and state are listed from the next turn.`;
+        const landed = StoreSurfaceSource.#redirected(path);
+        return `${landed ? `Asked for ${path}, but the app sent the page to ${landed} instead.` : `Now on ${path}.`} ${StoreSurfaceSource.#arrived}`;
       },
     };
   }
 
+  static readonly #arrived =
+    "This screen's own tools and state replace the previous screen's and are listed on your next turn — call them then, by the names listed. Call readScreen to see the page.";
+
+  static #linked() {
+    const routes = ScreenTarget.linkedRoutes();
+    return routes.length
+      ? `Paths this screen links to: ${routes.join(", ")}. Navigate to one of those rather than composing a path.`
+      : "Call readScreen — it prints each link on this screen with its own path — and navigate to one of those.";
+  }
+
+  /** A redirect or the app's not-found page moves the page somewhere other than the path it was sent to. */
+  static #redirected(path: string): string | null {
+    const trimmed = (route: string) => (route.length > 1 ? route.replace(/\/+$/, "") : route);
+    try {
+      const landed = router.routeOf(csrLocation.pathname);
+      const wanted = router.routeOf(new URL(path, "http://route.invalid").pathname);
+      return trimmed(landed) === trimmed(wanted) ? null : landed;
+    } catch {
+      return null;
+    }
+  }
+
   static #goBack(): ToolEntry {
     return {
       name: "goBack",
@@ -79,7 +100,7 @@ export class StoreSurfaceSource implements SurfaceSource {
       run: async () => {
         router.back();
         await ScreenSettle.wait({ appearMs: 800, timeoutMs: 5000 });
-        return `Back on ${router.getPath()}. Call readScreen to see it; this screen's own tools and state are listed from the next turn.`;
+        return `Back on ${router.getPath()}. ${StoreSurfaceSource.#arrived}`;
       },
     };
   }

package/types/client/router.d.ts

@@ -87,6 +87,7 @@ declare class Router {
         page: number;
     }): void;
     resolveDeepLinkStack(href: string): string[];
+    /** Before init the link waits for it, and the answer is `true`: the manifest that could refuse it is not loaded yet. */
     enterDeepLink(href: string, options?: DeepLinkOptions): boolean;
     push(href: string, routeOptions?: RouteOptions): never;
     replace(href: string, routeOptions?: RouteOptions): never;

package/types/service/agent.service.d.ts

@@ -13,7 +13,8 @@ export declare class AgentService extends AgentService_base {
     }>;
     /**
      * Prepended to the app's instructions here, not per adaptor, where forgetting it would be silent. The batching and
-     * no-re-read sentences were measured to cut turns against a provider; do not shorten them.
+     * no-re-read sentences were measured to cut turns against a provider; do not shorten them. The navigation sentence
+     * carves the batching rule: a call batched behind `navigate` was written against the screen being left.
      */
     static readonly preamble: string;
     static instructed(request: LlmTurnRequest): LlmTurnRequest;

package/types/service/predefinedAdaptor/openaiLlm.d.ts

@@ -1,4 +1,4 @@
-import type { LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import { type LlmAccepts, type LlmAdaptor, type LlmLimits, type LlmOption, type LlmTurnAnswer, type LlmTurnRequest } from "./llm.adaptor";
 declare const OpenaiLlm_base: import("..").AdaptorCls<{}, {
     llmOption: import("..").InjectInfo<"use", LlmOption, never, never>;
 }>;
@@ -11,8 +11,13 @@ export declare class OpenaiLlm extends OpenaiLlm_base implements LlmAdaptor {
     static readonly defaultHost = "https://api.openai.com/v1";
     /** No answer ceiling: the dialect sends none, so the provider's own default is the one that applies. */
     get limits(): LlmLimits;
-    /** A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn. */
     get accepts(): LlmAccepts | undefined;
+    /**
+     * A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn.
+     * OpenAI's own endpoint named outright is still OpenAI rather than a gateway. Static, so an app's own
+     * chat-completions adaptor claims what this one does instead of forking the rule.
+     */
+    static acceptsOf({ accepts, host }: LlmOption): LlmAccepts | undefined;
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
     static refusal(host: string, response: Response): Promise<Error>;
 }

package/types/store/agent/ScreenTarget.d.ts

@@ -10,5 +10,8 @@ export declare class ScreenTarget {
     static containerNames(root?: HTMLElement | null): string[];
     static anchorNames(root?: HTMLElement | null): string[];
     static targetNames(root?: HTMLElement | null): string[];
+    static linkedRoutes(root?: HTMLElement | null): string[];
+    /** Through `router.routeOf`: an href carries locale and base-path segments a tool argument lacks. */
+    static routeOf(href: string): string;
     static visible(el: HTMLElement): boolean;
 }

package/vendor/use-agentic/AgentSession.ts

@@ -192,6 +192,8 @@ export class AgentSession {
   #limits: TurnLimits = {};
   /** What the tools, the screen context and the instructions cost the last request, for a host's gauge. */
   #overhead = 0;
+  /** The tool names the model was handed on the turn now running — what its calls were written against. */
+  #listed: readonly string[] = [];
 
   constructor(surface: SurfaceView, runner: AgentRunner, options: AgentSessionOptions = {}) {
     this.#surface = surface;
@@ -211,7 +213,7 @@ export class AgentSession {
       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}` },
+          : { id: call.id, name: call.name, error: this.#unknown(call.name) },
     });
     this.#history = options.history;
     this.#onCompact = options.onCompact;
@@ -746,6 +748,7 @@ export class AgentSession {
   ): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop; overflow?: { message: string; limit?: number } }> {
     const frame = this.#frame();
     this.#overhead = AgentSession.#tokensOfFrame(frame);
+    this.#listed = frame.tools.map((tool) => tool.name);
     const request: RunnerRequest = { messages: Transcript.wire(this.#messages), ...frame, signal };
     this.#append({ role: "assistant" });
     let text = "";
@@ -780,6 +783,20 @@ export class AgentSession {
     return Array.isArray(settled.result) ? settled.result.join(", ") : settled.result;
   }
 
+  /**
+   * Answered with the names that exist: a bare refusal sends a model guessing the next name. A screen that moved
+   * since the turn's list was written is said so, since that call was written against the screen it left.
+   */
+  #unknown(name: string): string {
+    const shown = this.#surface.snapshot().tools.map((tool) => tool.name);
+    const now = shown.includes(AgentSession.askUserTool.name) ? shown : [...shown, AgentSession.askUserTool.name];
+    const listed = new Set(this.#listed);
+    const moved = now.length !== listed.size || now.some((one) => !listed.has(one));
+    return moved
+      ? `Unknown tool: ${name}. The screen changed during this turn, so this call was written against tools that are no longer on it. The tools on screen now are listed with their arguments on your next turn — call one then by its exact name: ${now.join(", ")}.`
+      : `Unknown tool: ${name}. Call only a tool listed to you, by its exact name — never a guessed one. Listed now: ${now.join(", ")}.`;
+  }
+
   /** No surface call and so no diff to report: the only thing this changes is what the model knows. */
   async #ask(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult> {
     const base = { id: call.id, name: call.name };