akanjs 3.0.0-alpha.40 → 3.0.0-alpha.42

package/dictionary/agent.dictionary.ts

@@ -21,11 +21,11 @@ export const agentDictionary = serviceDictionary(["en", "ko"])
   }))
   .error({
     llmUnavailable: [
-      "The agent model is unavailable — no LLM adaptor answered this turn",
-      "에이전트 모델을 사용할 수 없습니다. 이번 턴에 응답한 LLM 어댑터가 없습니다",
+      "The agent is unavailable — this app has no language model configured",
+      "에이전트를 사용할 수 없습니다. 이 앱에 언어 모델이 설정되어 있지 않습니다",
     ],
     deepseekRequestFailed: [
-      "DeepSeek request failed with status {status}",
-      "DeepSeek 요청이 실패했습니다 (status {status})",
+      "DeepSeek refused this turn with status {status}. Reason: {reason}",
+      "DeepSeek가 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
     ],
   });

package/dictionary/base.dictionary.ts

@@ -64,6 +64,7 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     agentKeepGoing: ["Keep going", "계속하기"],
     agentCmdNew: ["Start a new conversation", "새 대화 시작"],
     agentCmdRetry: ["Send the last message again", "마지막 메시지 다시 보내기"],
+    agentCmdCompact: ["Summarize the conversation so far", "지금까지의 대화 요약하기"],
     agentCmdCopy: ["Copy this conversation", "이 대화 복사"],
     agentCmdHelp: ["What you can do here", "여기서 할 수 있는 것"],
     agentCmdTools: ["List this screen's tools", "이 화면의 툴 목록"],
@@ -76,6 +77,9 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       "에이전트는 혼자 결정하면 안 되는 일을 하기 전에 물어보며, 중지는 진행 중인 턴을 끝냅니다.",
     ],
     agentNothingToRetry: ["There is no message to send again.", "다시 보낼 메시지가 없습니다."],
+    agentNothingToCompact: ["There is nothing to summarize yet.", "아직 요약할 대화가 없습니다."],
+    agentCompacted: ["Summarized the conversation so far.", "지금까지의 대화를 요약했습니다."],
+    agentSummary: ["Summary of the earlier conversation", "이전 대화 요약"],
     agentBusy: ["A turn is still running. Stop it first.", "진행 중인 턴이 있습니다. 먼저 중지하세요."],
     agentCopied: ["Conversation copied to the clipboard.", "대화를 클립보드에 복사했습니다."],
     agentCopyFailed: ["Could not reach the clipboard.", "클립보드에 접근할 수 없습니다."],

package/package.json

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

package/server/akanApp.ts

@@ -54,6 +54,11 @@ export interface AkanAppOptions {
   port?: number;
   wsBasePort?: number;
   openapi?: boolean;
+  /**
+   * Boot only these modules and the ones they reach, in every child. Omitted or empty mounts every enabled
+   * module. Handed down as `AKAN_MODULES`, since each replica builds its own container.
+   */
+  modules?: string[];
 }
 
 interface AkanReplicaConfig {
@@ -86,6 +91,7 @@ export class AkanApp {
   readonly #port: number;
   readonly #wsBasePort: number;
   readonly #openapi?: boolean;
+  readonly #modules: string[];
   readonly #children = new Map<number, ChildState>();
   readonly #roomChildren = new Map<string, Set<number>>();
   readonly #childRooms = new Map<number, Set<string>>();
@@ -127,6 +133,7 @@ export class AkanApp {
     this.#port = Number(resolvedOptions.port ?? process.env.PORT ?? 8282);
     this.#wsBasePort = Number(resolvedOptions.wsBasePort ?? process.env.AKAN_WS_BASE_PORT ?? this.#port + 10_000);
     this.#openapi = resolvedOptions.openapi;
+    this.#modules = resolvedOptions.modules ?? [];
   }
 
   static #resolveServerPath(serverPath: string) {
@@ -297,6 +304,7 @@ export class AkanApp {
         AKAN_CHILD_SOCKET: upstream.http.socketPath,
         AKAN_CHILD_WS_PORT: upstream.ws ? String(upstream.ws.port) : "",
         ...(this.#openapi === undefined ? {} : { AKAN_OPENAPI: this.#openapi ? "true" : "false" }),
+        ...(this.#modules.length ? { AKAN_MODULES: this.#modules.join(",") } : {}),
       },
       ipc: (message) => this.#handleMessage(idx, message as AkanIpcMessage, proc),
       stdout: "pipe",

package/server/akanOption.ts

@@ -68,9 +68,9 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
     else this.#getLlms.push(() => llmOrFn);
     return this;
   }
-  getUses(env: Env): Record<string, PromiseOrObject<unknown>> {
-    const uses = this.#getUses.map((fn) => fn(env));
-    return Object.assign({}, ...uses);
+  /** Every entry in declaration order, duplicates kept: the boot stage rejects a key claimed twice. */
+  getUses(env: Env): [string, PromiseOrObject<unknown>][] {
+    return this.#getUses.flatMap((fn) => Object.entries(fn(env)));
   }
   getMiddlewares(): MiddlewareCls[] {
     return this.#middlewares;

package/server/akanServer.ts

@@ -41,6 +41,11 @@ export interface AkanServerOptions {
   openapi?: boolean;
   /** `/mcp` is mounted by default; `false` takes it off, and the object form carries the rest of its settings. */
   mcp?: boolean | McpServerOption;
+  /**
+   * Boot only these modules and the ones they reach; every other module stays out of the container, so its
+   * services, signals, routes and schedules do not exist. Omitted or empty mounts every enabled module.
+   */
+  modules?: string[];
 }
 
 export interface McpServerOption {
@@ -122,6 +127,7 @@ export class AkanServer {
   mcpAuth: McpAuthOption = AkanServer.#mcpAuthFromEnv();
   mcpOption: Omit<McpServerOption, "enabled" | "readOnly" | "auth"> = AkanServer.#mcpOptionFromEnv();
   serverMode: "federation" | "batch" | "all";
+  modules: string[];
   shutdownTimeoutMs = AkanServer.#defaultShutdownTimeoutMs();
 
   #di: DiLifecycle;
@@ -152,7 +158,9 @@ export class AkanServer {
     });
     this.setMcp(options?.mcp ?? this.mcp);
     this.serverMode = serverMode;
-    this.#di = new DiLifecycle(this.env, serverMode, ...libs);
+    
+    this.modules = options?.modules ?? AkanServer.#envList("AKAN_MODULES") ?? [];
+    this.#di = new DiLifecycle({ env: this.env, modules: this.modules }, ...libs);
   }
   setPrefix(prefix: string) {
     this.prefix = prefix;
@@ -591,7 +599,7 @@ export class AkanServer {
         !("database" in value) &&
         !("service" in value) &&
         !("scalar" in value) &&
-        ("openapi" in value || "mcp" in value),
+        ("openapi" in value || "mcp" in value || "modules" in value),
     );
   }
 

package/server/di/diLifecycle.ts

@@ -29,17 +29,29 @@ import { getPredefinedAdaptor, predefinedAdaptorRole } from "./predefinedAdaptor
 import { collectAdaptors, resolveAdaptorHierarchy } from "./resolveAdaptorHierarchy";
 import { resolveServiceHierarchy } from "./resolveServiceHierarchy";
 import {
+  assertUniqueRegistrations,
   type DiModuleCandidate,
+  getModuleCascadeRefNames,
   getModuleDependencyRefNames,
   isDestroyableUse,
   normalizeAdaptorRefName,
   normalizeServiceRefName,
   normalizeSignalRefName,
+  type Registration,
   reasonMessage,
   runStage,
   toError,
 } from "./utils";
 
+export interface DiLifecycleProps {
+  env: BackendEnv;
+  /**
+   * Boot only these modules and the ones they reach, leaving every other module out of the container. Omitted or
+   * empty mounts every module whose service is enabled.
+   */
+  modules?: string[];
+}
+
 /**
  * Owns the app's DI container state (registry + live maps + init order) and
  * encapsulates every init / destroy step. `AkanServer` delegates to this so the
@@ -88,7 +100,7 @@ export class DiLifecycle {
     return !names.some((name) => process.env[name] === "false" || process.env[name] === "0");
   }
 
-  constructor(env: BackendEnv, serverMode: "federation" | "batch" | "all", ...libs: AkanLib[]) {
+  constructor({ env, modules = [] }: DiLifecycleProps, ...libs: AkanLib[]) {
     this.#env = env;
     
     this.#predefinedAdaptor = { ...getPredefinedAdaptor(getEnv().databaseMode ?? "single") };
@@ -133,7 +145,7 @@ export class DiLifecycle {
         this.#scalar.set(mod.constant.refName, mod);
       });
     });
-    const disabledModules = this.#resolveDisabledModules(databaseCandidates, serviceCandidates);
+    const disabledModules = this.#resolveDisabledModules(databaseCandidates, serviceCandidates, modules);
     databaseCandidates.forEach(({ refName, module }) => {
       if (disabledModules.has(refName)) return;
       this.#database.set(refName, module as DatabaseModule);
@@ -146,23 +158,40 @@ export class DiLifecycle {
       this.logger.info("agent relay is provided by a lib module — the framework's is skipped");
     if (!this.#scalar.has("agentTurn"))
       this.#scalar.set("agentTurn", { constant: agentTurnConstant, database: agentTurnDocument });
+    const adaptorClaims = new Map<string, AdaptorCls>();
+    const adaptorRegistrations: Registration[] = [];
+    
+    const claimAdaptor = (adaptorCls: AdaptorCls, owner: string) => {
+      const claimed = adaptorClaims.get(adaptorCls.refName);
+      if (claimed === adaptorCls) return;
+      if (!claimed) adaptorClaims.set(adaptorCls.refName, adaptorCls);
+      adaptorRegistrations.push({ key: adaptorCls.refName, owner });
+    };
+    for (const [role, adaptorCls] of Object.entries(this.#predefinedAdaptor))
+      claimAdaptor(adaptorCls, `predefined adaptor "${role}"`);
     this.#database.forEach((mod) => {
       const { adaptor, schema } = DatabaseResolver.resolveDatabase(mod.constant, mod.database);
       this.#adaptor.set(adaptor.refName, adaptor);
+      claimAdaptor(adaptor, `database module "${mod.constant.refName}"`);
       this.#cascade.register(mod.constant, schema, mod.service.srv);
     });
     const services = [
       ...[...this.#service.values()].map((mod) => mod.service.srv),
       ...[...this.#database.values()].map((mod) => mod.service.srv),
     ];
-    for (const adaptor of collectAdaptors(services)) {
-      this.#adaptor.set(adaptor.refName, adaptor);
+    for (const service of services) {
+      for (const adaptor of collectAdaptors([service])) {
+        this.#adaptor.set(adaptor.refName, adaptor);
+        claimAdaptor(adaptor, `service "${service.refName}"`);
+      }
     }
+    assertUniqueRegistrations("adaptor", adaptorRegistrations);
   }
 
   #resolveDisabledModules(
     databaseCandidates: Map<string, DiModuleCandidate>,
     serviceCandidates: Map<string, DiModuleCandidate>,
+    modules: string[],
   ) {
     const candidates = new Map<string, DiModuleCandidate>([...databaseCandidates, ...serviceCandidates]);
     const disabledReasons = new Map<string, string>();
@@ -171,6 +200,14 @@ export class DiLifecycle {
       if (!module.service.srv.enabled) disabledReasons.set(refName, "service disabled");
     });
 
+    const selected = this.#resolveSelectedModules(candidates, modules);
+    if (selected) {
+      candidates.forEach(({ refName }) => {
+        if (!selected.has(refName) && !disabledReasons.has(refName))
+          disabledReasons.set(refName, 'not named by the "modules" option');
+      });
+    }
+
     let changed = true;
     while (changed) {
       changed = false;
@@ -194,6 +231,42 @@ export class DiLifecycle {
     return new Set(disabledReasons.keys());
   }
 
+  /**
+   * The named modules closed over everything they reach: the services and signals they inject, and the cascade
+   * edges whose absence fails `CascadeRunner.seal`. `null` means no selection was asked for.
+   *
+   * An unknown name is refused rather than ignored, because a typo would otherwise boot an app with the module
+   * silently missing — the one failure this option exists to make impossible.
+   */
+  #resolveSelectedModules(candidates: Map<string, DiModuleCandidate>, modules: string[]) {
+    if (!modules.length) return null;
+    const known = new Set([...candidates.keys(), ...this.#service.keys()]);
+    const unknown = modules.filter((refName) => !known.has(refName));
+    if (unknown.length) {
+      const registered = [...known].sort((a, b) => a.localeCompare(b)).join(", ");
+      throw new Error(
+        `[DI:modules] unknown module ${unknown.map((refName) => `"${refName}"`).join(", ")}. Registered: ${registered}`,
+      );
+    }
+    const selected = new Set<string>();
+    const pending = modules.filter((refName) => candidates.has(refName));
+    while (pending.length) {
+      const refName = pending.pop();
+      if (!refName || selected.has(refName)) continue;
+      selected.add(refName);
+      const candidate = candidates.get(refName);
+      if (!candidate) continue;
+      const dependencies = [
+        ...getModuleDependencyRefNames(candidate.module),
+        ...getModuleCascadeRefNames(candidate.module),
+      ];
+      for (const dependency of dependencies) if (candidates.has(dependency)) pending.push(dependency);
+    }
+    const mounted = [...selected].sort((a, b) => a.localeCompare(b)).join(", ");
+    this.logger.info(`Mounting ${selected.size} of ${candidates.size} module(s): ${mounted}`);
+    return selected;
+  }
+
   /** Run every init stage in dependency order and collect the generated routes. */
   async initializeAll(): Promise<SignalRoutes> {
     await this.#initializeUses();
@@ -393,14 +466,20 @@ export class DiLifecycle {
 
   async #initializeUses() {
     
-    const uses = Object.assign(
-      { llmOption: Object.assign({}, ...this.#libs.map((lib) => lib.option.getLlm(this.#env))) },
-      ...this.#libs.map((lib) => lib.option.getUses(this.#env)),
-    );
-    const entries = Object.entries(uses);
+    const entries = [
+      {
+        key: "llmOption",
+        owner: "the framework",
+        value: Object.assign({}, ...this.#libs.map((lib) => lib.option.getLlm(this.#env))) as unknown,
+      },
+      ...this.#libs.flatMap((lib) =>
+        lib.option.getUses(this.#env).map(([key, value]) => ({ key, owner: `lib "${lib.name}"`, value })),
+      ),
+    ];
+    assertUniqueRegistrations("use", entries);
     await runStage(
       "uses",
-      entries.map(([key, value]) => ({
+      entries.map(({ key, value }) => ({
         label: `uses:${key}`,
         run: async () => {
           const useValue = value instanceof Promise ? await value : value;

package/server/di/utils.ts

@@ -1,5 +1,6 @@
 import { INJECT_META } from "akanjs/base";
 import { lowerlize } from "akanjs/common";
+import { ConstantRegistry } from "akanjs/constant";
 import type { InjectInfo } from "akanjs/service";
 import type { DatabaseModule, ServiceModule } from "../akanLib";
 
@@ -67,6 +68,45 @@ export const getModuleDependencyRefNames = (mod: DatabaseModule | ServiceModule)
   return dependencies;
 };
 
+/**
+ * The modules a cascade edge forces this one to be mounted with: a `removeRef` target and a monomorphic
+ * `removeWith` owner both fail `CascadeRunner.seal` when they are absent, so they are boot dependencies the
+ * inject graph cannot see. A polymorphic owner list is exempt — it spans optional modules by design.
+ */
+export const getModuleCascadeRefNames = (mod: DatabaseModule | ServiceModule) => {
+  const dependencies = new Set<string>();
+  if (!("constant" in mod)) return dependencies;
+  const { cascade } = mod.constant.full;
+  for (const modelRef of cascade.removeRef.values()) dependencies.add(ConstantRegistry.getRefName(modelRef));
+  for (const path of cascade.removeWith.values()) {
+    if (path.typeValues.length) continue;
+    dependencies.add(path.refName ?? ConstantRegistry.getRefName(path.modelRef as never));
+  }
+  return dependencies;
+};
+
+export interface Registration {
+  key: string;
+  /** What claimed the key, phrased for a boot error: `predefined adaptor "storage"`, `lib "shared"`. */
+  owner: string;
+}
+
+/**
+ * A key registered twice is silently last-write-wins everywhere downstream — an app that meant to add a second
+ * adaptor gets one, and the other's `onInit` never runs. Refuse the boot instead, naming both claimants.
+ */
+export const assertUniqueRegistrations = (kind: string, registrations: Registration[]) => {
+  const claimed = new Map<string, string>();
+  const clashes: string[] = [];
+  for (const { key, owner } of registrations) {
+    const previous = claimed.get(key);
+    if (previous) clashes.push(`  • "${key}" is registered by ${previous} and by ${owner}`);
+    else claimed.set(key, owner);
+  }
+  if (!clashes.length) return;
+  throw new Error(`[DI:${kind}] ${clashes.length} duplicate registration(s):\n${clashes.join("\n")}`);
+};
+
 /**
  * Run every task in parallel and, if any rejects, throw a single
  * `AggregateError` that enumerates every failing label + cause. This replaces

package/service/predefinedAdaptor/deepseekLlm.ts

@@ -54,8 +54,9 @@ export class DeepseekLlm
       const body = await this.#apiStream("/chat/completions", DeepseekLlm.requestBody(this.#model, request, true));
       return await DeepseekLlm.consumeStream(body, onDelta);
     } catch (error) {
+
       this.logger.error(`DeepSeek turn failed: ${error instanceof Error ? error.message : String(error)}`);
-      return null;
+      throw error;
     }
   }
 
@@ -67,7 +68,7 @@ export class DeepseekLlm
       
       signal: AbortSignal.timeout(120_000),
     });
-    if (!response.ok) throw new Err("agent.error.deepseekRequestFailed", { status: String(response.status) });
+    if (!response.ok) throw await DeepseekLlm.refusal(response);
     return (await response.json()) as T;
   }
 
@@ -78,11 +79,31 @@ export class DeepseekLlm
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(120_000),
     });
-    if (!response.ok || !response.body)
-      throw new Err("agent.error.deepseekRequestFailed", { status: String(response.status) });
+    if (!response.ok || !response.body) throw await DeepseekLlm.refusal(response);
     return response.body;
   }
 
+  /**
+   * The dialect answers a refusal as `{ error: { message } }`, and that sentence is the useful half — a request
+   * past the context window says exactly which limit it passed. Carried on the `Err` so the chat can print it.
+   */
+  static async refusal(response: Response): Promise<Error> {
+    return new Err("agent.error.deepseekRequestFailed", {
+      status: String(response.status),
+      reason: await DeepseekLlm.reasonOf(response),
+    });
+  }
+
+  static async reasonOf(response: Response): Promise<string> {
+    try {
+      const body = (await response.json()) as { error?: { message?: unknown } | string };
+      const message = typeof body.error === "string" ? body.error : body.error?.message;
+      if (typeof message === "string" && message) return message;
+    } catch {
+    }
+    return response.statusText || "no reason given";
+  }
+
   /**
    * The dialect streams `data: {chunk}` SSE lines ending with `data: [DONE]`. Tool calls arrive fragmented — the
    * first fragment of an index carries id/name, later ones append to the arguments string — so they are assembled
@@ -175,6 +196,14 @@ export class DeepseekLlm
   }
 
   static providerMessages(message: AgentWireMessage): DeepseekMessage[] {
+
+    if (message.summary)
+      return [
+        {
+          role: "system" as const,
+          content: `Summary of the earlier conversation, standing in for the messages it replaced:\n\n${message.text ?? ""}`,
+        },
+      ];
     if (message.role === "tool")
       return (message.toolResults ?? []).map((result) => ({
         role: "tool" as const,

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -37,6 +37,11 @@ export interface AgentWireMessage {
   toolCalls?: AgentWireToolCall[];
   toolResults?: AgentWireToolResult[];
   error?: string;
+  /**
+   * Stands in for the messages the client's own compaction replaced. It arrives with the user's role because the
+   * wire has no other, but it is history rather than an ask, so a provider mapping frames it as one.
+   */
+  summary?: boolean;
 }
 
 export interface AgentWireTool {
@@ -68,8 +73,12 @@ export interface LlmTurnAnswer {
 /**
  * The provider seam for one stateless agent turn: the whole transcript in, one assistant answer out. The server
  * relays — it never executes a client tool — so this is the only surface a provider integration fills. An
- * implementation is an `adapt()` class in a lib's `srvkit/` and follows the adapter convention: failures are
- * logged and answered as `null`, and the calling service decides what that means.
+ * implementation is an `adapt()` class in a lib's `srvkit/`.
+ *
+ * `null` means this provider is not configured, and the caller turns it into the one sentence that says so. A
+ * failure the provider explained is logged and **thrown** instead, as an `Err` whose text the chat prints: a
+ * refused turn and an unconfigured app are different things to be told, and collapsing both into `null` left a
+ * user reading "no model is configured" about a conversation that had merely outgrown the context window.
  */
 export interface LlmAdaptor {
   /**

package/signal/agentTurnStream.ts

@@ -16,6 +16,18 @@ export class AgentTurnStream {
     return !!request.headers.get("accept")?.includes("text/event-stream");
   }
 
+  /**
+   * A domain `Err` carries its dictionary key as the message and the values its text interpolates as `data`, so
+   * both travel: the key alone would reach the chat as `agent.error.…` with its placeholders unfilled.
+   */
+  static failure(error: unknown): { message: string; data?: Record<string, string | number> } {
+    const message = error instanceof Error ? error.message : String(error);
+    const data = (error as { data?: unknown } | null)?.data;
+    return data && typeof data === "object" && !Array.isArray(data)
+      ? { message, data: data as Record<string, string | number> }
+      : { message };
+  }
+
   static response(run: (onDelta: (delta: string) => void) => Promise<StreamedTurn>): Response {
     const encoder = new TextEncoder();
     const stream = new ReadableStream<Uint8Array>({
@@ -35,7 +47,7 @@ export class AgentTurnStream {
           send({ type: "done", stop: turn.stop === "toolUse" || toolCalls.length ? "toolUse" : "end" });
         } catch (error) {
           
-          send({ type: "error", message: error instanceof Error ? error.message : String(error) });
+          send({ type: "error", ...AgentTurnStream.failure(error) });
         } finally {
           controller.close();
         }

package/store/agent/StateWait.ts

@@ -0,0 +1,139 @@
+import { AgentAbort, AgentProgress } from "../../vendor/use-agentic";
+
+/** The reading half of the store an in-page wait needs. `AgentBridge` is one; a test can be another. */
+export interface StateSource {
+  read(key: string, viewKey?: string): unknown;
+  subscribe(listener: () => void): () => void;
+}
+
+export interface StateWaitOptions {
+  key: string;
+  viewKey?: string;
+  /** Settle when the key reads exactly this. Null waits for it to change from whatever it holds now. */
+  equals?: string | null;
+  /** Straight off the tool argument, so it may be anything; `StateWait.seconds` is what makes it a number. */
+  seconds?: unknown;
+}
+
+/**
+ * One `waitFor` call: park until a published state key settles, or until the timeout says how it is going.
+ *
+ * Two clocks, because neither covers the other. The store's own subscription catches the value changing, which is
+ * the whole point of the tool and has to land immediately. The tick catches what the store never announces —
+ * `retainLive` / `releaseLive` mutate the live-key map without notifying any listener, so a page navigated away
+ * from mid-wait would otherwise hold the turn until the timeout — and the countdown row needs a tick anyway.
+ *
+ * Nothing here throws on a wait that ran out. A key still reading `generating` after two minutes is an answer, not
+ * a failure, and the model is the one that decides whether to wait again.
+ */
+export class StateWait {
+  static readonly tickMs = 1000;
+  static readonly defaultSeconds = 120;
+  static readonly maxSeconds = 600;
+
+  /** Clamped rather than refused: a model that asks for an hour gets the longest wait on offer and reads how long. */
+  static seconds(value: unknown): number {
+    if (typeof value !== "number" || !Number.isFinite(value)) return StateWait.defaultSeconds;
+    return Math.min(Math.max(Math.round(value), 1), StateWait.maxSeconds);
+  }
+
+  /** A string is itself; everything else is JSON, so a number, a boolean and null each compare as they are written. */
+  static print(value: unknown): string {
+    if (typeof value === "string") return value;
+    try {
+      return JSON.stringify(value) ?? String(value);
+    } catch {
+      return String(value);
+    }
+  }
+
+  readonly #source: StateSource;
+  readonly #key: string;
+  readonly #viewKey: string;
+  readonly #equals: string | null;
+  readonly #seconds: number;
+  #was = "";
+  #now = "";
+  #elapsed = 0;
+  #settled: boolean = false;
+  #ticker: ReturnType<typeof setInterval> | undefined;
+  #unsubscribe: (() => void) | undefined;
+  #signal: AbortSignal | null = null;
+  #resolve: ((message: string) => void) | null = null;
+  #reject: ((error: Error) => void) | null = null;
+
+  constructor(source: StateSource, { key, viewKey = "", equals = null, seconds }: StateWaitOptions) {
+    this.#source = source;
+    this.#key = key;
+    this.#viewKey = viewKey;
+    this.#equals = equals;
+    this.#seconds = StateWait.seconds(seconds);
+  }
+
+  run(): Promise<string> {
+    this.#was = StateWait.print(this.#source.read(this.#key, this.#viewKey));
+    this.#now = this.#was;
+    if (this.#equals !== null && this.#was === this.#equals)
+      return Promise.resolve(`${this.#key} is already ${this.#was}.`);
+    return new Promise<string>((resolve, reject) => {
+      this.#resolve = resolve;
+      this.#reject = reject;
+      this.#signal = AgentAbort.current;
+      if (this.#signal?.aborted) {
+        this.#abort();
+        return;
+      }
+      this.#signal?.addEventListener("abort", this.#abort);
+      this.#unsubscribe = this.#source.subscribe(this.#check);
+      this.#ticker = setInterval(this.#tick, StateWait.tickMs);
+      AgentProgress.report("", { done: 0, total: this.#seconds });
+    });
+  }
+
+  /** The session races every call against the same signal; honouring it here is what stops the timer. */
+  #abort = () => {
+    this.#stop();
+    this.#reject?.(new Error("The user aborted the turn."));
+  };
+
+  #check = () => {
+    if (this.#settled) return;
+    let now: string;
+    try {
+      now = StateWait.print(this.#source.read(this.#key, this.#viewKey));
+    } catch (error) {
+      
+      this.#end(`Stopped waiting: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    this.#now = now;
+    if (this.#equals === null ? now !== this.#was : now === this.#equals) this.#end(`${this.#key} is now ${now}.`);
+  };
+
+  #tick = () => {
+    this.#check();
+    if (this.#settled) return;
+    this.#elapsed += 1;
+    if (this.#elapsed >= this.#seconds) {
+      this.#end(
+        `${this.#key} is still ${this.#now} after ${this.#seconds}s. Call waitFor again to keep waiting, or tell the user it is taking longer than expected.`,
+      );
+      return;
+    }
+    AgentProgress.report("", { done: this.#elapsed, total: this.#seconds });
+  };
+
+  #end(message: string) {
+    this.#stop();
+    this.#resolve?.(message);
+  }
+
+  #stop() {
+    this.#settled = true;
+    clearInterval(this.#ticker);
+    this.#ticker = undefined;
+    this.#unsubscribe?.();
+    this.#unsubscribe = undefined;
+    this.#signal?.removeEventListener("abort", this.#abort);
+  }
+}