akanjs 3.1.1-rc.3 → 3.1.1-rc.5

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/document/by.ts

@@ -1,6 +1,7 @@
 import { type Cls, FIELD_META, type GetActionObject } from "akanjs/base";
 import { applyMixins } from "akanjs/common";
 import { ConstantRegistry, type DocumentConstantModelRef, type DocumentModel, type FieldObject } from "akanjs/constant";
+import type { DocumentTouchOptions } from "./documentQuery";
 
 export type DatabaseCls<Schema = unknown> = Cls<Schema, { refName: string; [FIELD_META]: FieldObject }>;
 export type DatabaseInstanceOf<DatabaseRef extends DatabaseCls> = DatabaseRef extends new (
@@ -14,7 +15,7 @@ export interface DefaultDocMtds<TDocument> {
   refresh(): Promise<this>;
   isModified(field?: keyof TDocument & string): boolean;
   set(data: Partial<TDocument>): this;
-  save(): Promise<this>;
+  save(options?: DocumentTouchOptions): Promise<this>;
   toJSON(): DocumentModel<TDocument>;
   toObject(): DocumentModel<TDocument>;
 }
@@ -25,7 +26,7 @@ type HydratedDocumentMethods<TDocument, Self> = Omit<
   refresh(): Promise<Self>;
   isModified(field?: keyof TDocument & string): boolean;
   set(data: Partial<TDocument>): Self;
-  save(): Promise<Self>;
+  save(options?: DocumentTouchOptions): Promise<Self>;
 };
 type HydratedDocumentWithId<TDocument> = TDocument & { id: string } & HydratedDocumentMethods<TDocument, TDocument>;
 interface ChainableHydratedMethods<TDocument>
@@ -33,7 +34,7 @@ interface ChainableHydratedMethods<TDocument>
   refresh(): Promise<this>;
   isModified(field?: keyof TDocument & string): boolean;
   set(data: Partial<TDocument>): this;
-  save(): Promise<this>;
+  save(options?: DocumentTouchOptions): Promise<this>;
 }
 type ChainableHydratedDocument<TDocument> = TDocument & {
   id: string;

package/document/into.ts

@@ -25,8 +25,8 @@ interface DefaultMdlStats<
   _FilterQuery extends DocumentQuery<TSchema> = DocumentQuery<TSchema>,
   _Projection = DocumentProjection<TSchema>,
 > {
-  pickOneAndWrite: (query: _FilterQuery, rawData: _Partial) => Promise<TDocument>;
-  pickAndWrite: (docId: string, rawData: _Partial) => Promise<TDocument>;
+  pickOneAndWrite: (query: _FilterQuery, rawData: _Partial, options?: DocumentTouchOptions) => Promise<TDocument>;
+  pickAndWrite: (docId: string, rawData: _Partial, options?: DocumentTouchOptions) => Promise<TDocument>;
   pickOne: (query: _FilterQuery, projection?: _Projection) => Promise<TDocument>;
   pickById: (docId: string | undefined, projection?: _Projection) => Promise<TDocument>;
   sample: (query: _FilterQuery, size?: number) => Promise<TDocument[]>;

package/package.json

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

package/server/akanApp.ts

@@ -24,6 +24,7 @@ import type { OpsRoute } from "./ops/opsRoute";
 import { StatusAccess } from "./ops/statusAccess";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { HostAllowlist } from "./routing/hostAllowlist";
+import { WsUpgrade } from "./routing/wsUpgrade";
 import { SelfExec } from "./selfExec";
 import { resolveStaticPath } from "./staticPath";
 import { getWebConfigFromEnv } from "./types";
@@ -670,6 +671,7 @@ export class AkanApp {
     } catch {
       return new Response("Forbidden", { status: 403 });
     }
+    if (!WsUpgrade.isRequested(req)) return WsUpgrade.required();
     const upstreamWs = new WebSocket(`ws://${upstream.host}:${upstream.port}${url.pathname}${url.search}`, {
       headers: makeAkanChildProxyHeaders(req, child.idx, server.requestIP(req)),
     } as unknown as string[]);

package/server/resolver/database.resolver.ts

@@ -278,9 +278,10 @@ export class DatabaseResolver {
             timedQuery(() => store.pickOne(query, { select: projection })),
           pickById,
           
-          pickAndWrite: async (id: string, rawData: any) => await (await pickById(id)).set(rawData).save(),
-          pickOneAndWrite: async (query: QueryOf<any>, rawData: any) =>
-            await (await timedQuery(() => store.pickOne(query))).set(rawData).save(),
+          pickAndWrite: async (id: string, rawData: any, options?: DocumentTouchOptions) =>
+            await (await pickById(id)).set(rawData).save(...touchArgs(options)),
+          pickOneAndWrite: async (query: QueryOf<any>, rawData: any, options?: DocumentTouchOptions) =>
+            await (await timedQuery(() => store.pickOne(query))).set(rawData).save(...touchArgs(options)),
           exists: async (query: QueryOf<any>, options?: DocumentScopeOptions) =>
             await timedQuery(() => store.exists(query, ...scopeArgs(options))),
           sample: (query: QueryOf<any>, size = 1) => timedQuery(() => store.find(query, { sample: size, limit: size })),

package/server/routing/apiRouter.ts

@@ -15,6 +15,7 @@ import { SignalResolver } from "../resolver";
 import type { HttpRoutes, SignalRouteOptions, WebsocketRoutes } from "../types";
 import { AppWsData } from "./appWsData";
 import type { HostAllowlist } from "./hostAllowlist";
+import { WsUpgrade } from "./wsUpgrade";
 
 export interface HmrStateSource {
   readonly state: {
@@ -93,6 +94,7 @@ export class ApiRouter {
         }
         const upgraded = upgradeAppWs(req, AppWsData.fromRequest(req));
         if (upgraded) return;
+        if (!WsUpgrade.isRequested(req)) return WsUpgrade.required();
         return new Response("Failed to upgrade to WebSocket", { status: 500 });
       },
       ...Object.fromEntries(endpointEntries),

package/server/routing/wsUpgrade.ts

@@ -0,0 +1,10 @@
+
+export class WsUpgrade {
+  static isRequested(req: Request) {
+    return req.headers.get("upgrade")?.toLowerCase() === "websocket";
+  }
+
+  static required() {
+    return new Response("Upgrade Required", { status: 426, headers: { Upgrade: "websocket", Connection: "Upgrade" } });
+  }
+}

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/service/predefinedAdaptor/sql/SqlDocumentStore.ts

@@ -412,7 +412,7 @@ export class SqlDocumentStore {
 
   async update(id: string, patch: DocumentRecord, options: WriteHookOptions = {}) {
     const current = await this.pickByIdForWrite(id);
-    return await this.writeUpdatedDocument(id, { ...current, ...patch, id, updatedAt: dayjs() }, current, options);
+    return await this.writeUpdatedDocument(id, { ...current, ...patch, id }, current, options);
   }
 
   async remove(id: string) {
@@ -957,9 +957,9 @@ export class SqlDocumentStore {
     id: string,
     data: DocumentRecord,
     originalData: DocumentRecord,
-    { runSaveHooks = true, crudType = "update" }: WriteHookOptions = {},
+    { runSaveHooks = true, crudType = "update", touch = true }: WriteHookOptions = {},
   ) {
-    const prepared = this.prepareDocument({ ...data, id, updatedAt: dayjs() });
+    const prepared = this.prepareDocument({ ...data, id, updatedAt: touch ? dayjs() : originalData.updatedAt });
     this.#assertImmutableUnchanged(prepared, originalData);
     const doc = this.hydrate(prepared, originalData);
     
@@ -968,7 +968,7 @@ export class SqlDocumentStore {
     await this.runHooks(crudType, crudType, doc, "pre", previous);
     const row = this.toRow(doc);
     const stored = (originalData as Record<symbol, StoredRow | undefined>)[SqlDocumentStore.#storedRow];
-    await this.#writeChanges(id, stored ?? this.toRow(originalData), row);
+    await this.#writeChanges(id, stored ?? this.toRow(originalData), row, touch);
     await this.runHooks(crudType, crudType, doc, "post", previous);
     if (runSaveHooks) await this.runHooks("save", crudType, doc, "post", previous);
     return this.#withStoredRow(doc, row);
@@ -978,11 +978,12 @@ export class SqlDocumentStore {
    * Merges only the fields that changed into the stored `_doc`, so a concurrent write to another field survives. A key
    * the stored row lacks is written out, which is what `q.missing` tells rows from before a field existed apart by.
    */
-  async #writeChanges(id: string, read: StoredRow, written: StoredRow) {
+  async #writeChanges(id: string, read: StoredRow, written: StoredRow, touch: boolean) {
     const before = SqlDocumentStore.#encodedFields(read);
     const after = SqlDocumentStore.#encodedFields(written);
-    const assignments = [`"updatedAt" = ?`];
-    const params: unknown[] = [written.updatedAt];
+    
+    const assignments = [touch ? `"updatedAt" = ?` : `"updatedAt" = "updatedAt"`];
+    const params: unknown[] = touch ? [written.updatedAt] : [];
     for (const column of ["createdAt", "removedAt"] as const) {
       if (before.get(column) === after.get(column)) continue;
       assignments.push(`${quoteIdent(column)} = ?`);
@@ -1201,10 +1202,10 @@ export class SqlDocumentStore {
         },
       },
       save: {
-        async value(this: DocumentRecord) {
+        async value(this: DocumentRecord, { touch }: DocumentTouchOptions = {}) {
           if (!this.id) return store.create(this);
           store.#assertLiveRow(this);
-          return store.update(this.id as string, store.#changesOf(this));
+          return store.update(this.id as string, store.#changesOf(this), touch === false ? { touch } : {});
         },
       },
       refresh: {

package/service/predefinedAdaptor/sql/types.ts

@@ -170,7 +170,7 @@ export type FindOneOptions = DocumentScopeOptions & {
   select?: ProjectionOption;
 };
 export type FindIdOptions = DocumentScopeOptions & { sort?: SortOption; skip?: number | null; sample?: boolean };
-export type WriteHookOptions = { runSaveHooks?: boolean; crudType?: "update" | "remove" };
+export type WriteHookOptions = DocumentTouchOptions & { runSaveHooks?: boolean; crudType?: "update" | "remove" };
 export type QueryOperatorName = Extract<DocumentQueryNode, { kind: "op" }>["op"];
 export interface SqliteDocumentRow {
   id: string;

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/document/by.d.ts

@@ -1,5 +1,6 @@
 import { type Cls, FIELD_META, type GetActionObject } from "akanjs/base";
 import { type DocumentConstantModelRef, type DocumentModel, type FieldObject } from "akanjs/constant";
+import type { DocumentTouchOptions } from "./documentQuery.d.ts";
 export type DatabaseCls<Schema = unknown> = Cls<Schema, {
     refName: string;
     [FIELD_META]: FieldObject;
@@ -10,7 +11,7 @@ export interface DefaultDocMtds<TDocument> {
     refresh(): Promise<this>;
     isModified(field?: keyof TDocument & string): boolean;
     set(data: Partial<TDocument>): this;
-    save(): Promise<this>;
+    save(options?: DocumentTouchOptions): Promise<this>;
     toJSON(): DocumentModel<TDocument>;
     toObject(): DocumentModel<TDocument>;
 }
@@ -18,7 +19,7 @@ type HydratedDocumentMethods<TDocument, Self> = Omit<DefaultDocMtds<TDocument>,
     refresh(): Promise<Self>;
     isModified(field?: keyof TDocument & string): boolean;
     set(data: Partial<TDocument>): Self;
-    save(): Promise<Self>;
+    save(options?: DocumentTouchOptions): Promise<Self>;
 };
 type HydratedDocumentWithId<TDocument> = TDocument & {
     id: string;
@@ -27,7 +28,7 @@ interface ChainableHydratedMethods<TDocument> extends Omit<DefaultDocMtds<TDocum
     refresh(): Promise<this>;
     isModified(field?: keyof TDocument & string): boolean;
     set(data: Partial<TDocument>): this;
-    save(): Promise<this>;
+    save(options?: DocumentTouchOptions): Promise<this>;
 }
 type ChainableHydratedDocument<TDocument> = TDocument & {
     id: string;

package/types/document/into.d.ts

@@ -10,8 +10,8 @@ export type CRUDEventType = "create" | "update" | "remove";
 export type SaveEventType = "save" | CRUDEventType;
 export type SaveEventListener<Doc> = (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>;
 interface DefaultMdlStats<TDocument, TSchema, _Partial extends Partial<TSchema> = Partial<TSchema>, _FilterQuery extends DocumentQuery<TSchema> = DocumentQuery<TSchema>, _Projection = DocumentProjection<TSchema>> {
-    pickOneAndWrite: (query: _FilterQuery, rawData: _Partial) => Promise<TDocument>;
-    pickAndWrite: (docId: string, rawData: _Partial) => Promise<TDocument>;
+    pickOneAndWrite: (query: _FilterQuery, rawData: _Partial, options?: DocumentTouchOptions) => Promise<TDocument>;
+    pickAndWrite: (docId: string, rawData: _Partial, options?: DocumentTouchOptions) => Promise<TDocument>;
     pickOne: (query: _FilterQuery, projection?: _Projection) => Promise<TDocument>;
     pickById: (docId: string | undefined, projection?: _Projection) => Promise<TDocument>;
     sample: (query: _FilterQuery, size?: number) => Promise<TDocument[]>;

package/types/server/routing/wsUpgrade.d.ts

@@ -0,0 +1,4 @@
+export declare class WsUpgrade {
+    static isRequested(req: Request): boolean;
+    static required(): Response;
+}

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/service/predefinedAdaptor/sql/types.d.ts

@@ -170,7 +170,7 @@ export type FindIdOptions = DocumentScopeOptions & {
     skip?: number | null;
     sample?: boolean;
 };
-export type WriteHookOptions = {
+export type WriteHookOptions = DocumentTouchOptions & {
     runSaveHooks?: boolean;
     crudType?: "update" | "remove";
 };

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 };