akanjs 3.0.0-alpha.40 → 3.0.0-alpha.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.41",
   "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/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);
+  }
+}

package/store/agent/StoreSurfaceSource.ts

@@ -4,6 +4,7 @@ import { AgentBridge } from "./AgentBridge";
 import { ScreenReader } from "./ScreenReader";
 import { ScreenSettle } from "./ScreenSettle";
 import { ScreenTarget } from "./ScreenTarget";
+import { StateWait } from "./StateWait";
 
 /**
  * The tools every akan screen has whatever it declares: where it can go, what it is rendering, what one of the
@@ -38,6 +39,7 @@ export class StoreSurfaceSource implements SurfaceSource {
         StoreSurfaceSource.#goBack(),
         StoreSurfaceSource.#readScreen(viewKey),
         this.#readState(viewKey),
+        this.#waitFor(viewKey),
         StoreSurfaceSource.#highlight(viewKey),
       ];
       this.#builtins.set(viewKey, builtins);
@@ -190,6 +192,65 @@ export class StoreSurfaceSource implements SurfaceSource {
     };
   }
 
+  /**
+   * The wait that costs no model turns.
+   *
+   * An agent that started something slow has one way to learn it finished: ask again, and again, a full round trip
+   * per look. That burns the turn budget in seconds and reads to the user as a loop. This parks the call instead —
+   * the session already awaits `run`, so the turn simply takes as long as the work does, and the change report
+   * that follows carries whatever landed while it waited.
+   *
+   * It watches a published state key rather than sleeping for a fixed span. A bare sleep would only make the
+   * polling slower, and a screen that can report progress at all reports it into the store; a screen that reports
+   * none publishes a key with `st.expose`, which is worth doing anyway, since the key is then readable too.
+   */
+  #waitFor(viewKey: string): ToolEntry {
+    return {
+      name: "waitFor",
+      description:
+        "Wait here until one of this page's state keys settles, instead of asking again and again. Use it after starting something slow — a generation, an upload, a long job — whenever a state key reports how it is going: the turn pauses with no model round trip and resumes the moment the key moves. Keys are listed in the state context block. Returns what the key holds when the wait ends.",
+      parameters: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "The state key to watch, spelled as the state context block lists it." },
+          equals: {
+            type: "string",
+            description:
+              "Wait until the key reads exactly this, compared as text. Omit to wait until it changes from whatever it holds now.",
+          },
+          timeoutSeconds: {
+            type: "number",
+            description: `How long to wait before answering with the key's current value. Default ${StateWait.defaultSeconds}, maximum ${StateWait.maxSeconds}. Running out is not a failure — call waitFor again to keep waiting.`,
+          },
+        },
+        required: ["key"],
+        additionalProperties: false,
+      },
+
+      effect: "state",
+      run: async (args) => {
+        this.#bridge ??= AgentBridge.of();
+        const key = typeof args.key === "string" ? args.key.trim() : "";
+        if (!key) throw new Error("waitFor needs a key to watch.");
+        const live = this.#bridge.readableKeys(viewKey);
+        if (!live.includes(key))
+          throw new Error(
+            `No state key named ${key} is read by this screen. ${
+              live.length
+                ? `Keys here: ${live.join(", ")}.`
+                : "This screen reads no state keys, so there is nothing to wait for."
+            }`,
+          );
+        return await new StateWait(this.#bridge, {
+          key,
+          viewKey,
+          equals: typeof args.equals === "string" ? args.equals : null,
+          seconds: args.timeoutSeconds,
+        }).run();
+      },
+    };
+  }
+
   /**
    * The ring goes on once the scroll lands, not when it starts: a smooth scroll across a long page takes most of a
    * second, and a flash begun at the top is already fading by the time the user's eye arrives. Settles on the

package/store/agent/index.ts

@@ -1,9 +1,13 @@
+
+
+export { AgentAbort, AgentProgress } from "../../vendor/use-agentic";
 export * from "./AgentBridge";
 export * from "./AgentContext";
 export * from "./AgentPrompts";
 export * from "./ScreenReader";
 export * from "./ScreenSettle";
 export * from "./ScreenTarget";
+export * from "./StateWait";
 export * from "./StoreCatalogue";
 export * from "./StoreSurfaceSource";
 export * from "./storeSurface";

package/types/server/akanApp.d.ts

@@ -7,6 +7,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[];
 }
 /** Gateway/orchestrator that starts Akan child servers and proxies HTTP/WebSocket traffic. */
 export declare class AkanApp {

package/types/server/akanOption.d.ts

@@ -33,7 +33,8 @@ export declare class AkanOption<Env extends BackendEnv = BackendEnv> {
     setAgentAccess(guards: GuardCls | GuardCls[] | null): this;
     /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
     setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)): this;
-    getUses(env: Env): Record<string, PromiseOrObject<unknown>>;
+    /** Every entry in declaration order, duplicates kept: the boot stage rejects a key claimed twice. */
+    getUses(env: Env): [string, PromiseOrObject<unknown>][];
     getMiddlewares(): MiddlewareCls[];
     getAdaptorOverrides(): AdaptorOverride[];
     getWebProxies(): WebProxyRegistration[];

package/types/server/akanServer.d.ts

@@ -14,6 +14,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 {
     enabled?: boolean;
@@ -77,6 +82,7 @@ export declare class AkanServer {
     mcpAuth: McpAuthOption;
     mcpOption: Omit<McpServerOption, "enabled" | "readOnly" | "auth">;
     serverMode: "federation" | "batch" | "all";
+    modules: string[];
     shutdownTimeoutMs: number;
     constructor(name?: string, env?: BackendEnv, serverMode?: "federation" | "batch" | "all", ...libsOrOptions: (AkanLib | AkanServerOptions)[]);
     setPrefix(prefix: string): this;

package/types/server/di/diLifecycle.d.ts

@@ -6,6 +6,14 @@ import type { ServerSignal, ServerSignalCls } from "../../signal/serverSignal.d.
 import type { AkanLib, DatabaseModule, ScalarModule, ServiceModule } from "../akanLib.d.ts";
 import type { WebProxyRegistration } from "../proxy.d.ts";
 import type { SignalRoutes } from "../types.d.ts";
+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
@@ -31,7 +39,7 @@ export declare class DiLifecycle {
         adaptor: ReadonlyMap<string, AdaptorCls>;
         middleware: ReadonlyMap<string, MiddlewareCls>;
     };
-    constructor(env: BackendEnv, serverMode: "federation" | "batch" | "all", ...libs: AkanLib[]);
+    constructor({ env, modules }: DiLifecycleProps, ...libs: AkanLib[]);
     /** Run every init stage in dependency order and collect the generated routes. */
     initializeAll(): Promise<SignalRoutes>;
     destroyAll(): Promise<void>;

package/types/server/di/utils.d.ts

@@ -15,6 +15,22 @@ export declare const normalizeServiceRefName: (refName: string) => string;
 export declare const normalizeSignalRefName: (refName: string) => string;
 export declare const normalizeAdaptorRefName: (refName: string) => string;
 export declare const getModuleDependencyRefNames: (mod: DatabaseModule | ServiceModule) => Set<string>;
+/**
+ * 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 declare const getModuleCascadeRefNames: (mod: DatabaseModule | ServiceModule) => Set<string>;
+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 declare const assertUniqueRegistrations: (kind: string, registrations: Registration[]) => void;
 /**
  * Run every task in parallel and, if any rejects, throw a single
  * `AggregateError` that enumerates every failing label + cause. This replaces

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

@@ -0,0 +1,36 @@
+/** 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 declare class StateWait {
+    #private;
+    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;
+    /** 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;
+    constructor(source: StateSource, { key, viewKey, equals, seconds }: StateWaitOptions);
+    run(): Promise<string>;
+}

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

@@ -1,9 +1,11 @@
+export { AgentAbort, AgentProgress } from "../../vendor/use-agentic.d.ts";
 export * from "./AgentBridge.d.ts";
 export * from "./AgentContext.d.ts";
 export * from "./AgentPrompts.d.ts";
 export * from "./ScreenReader.d.ts";
 export * from "./ScreenSettle.d.ts";
 export * from "./ScreenTarget.d.ts";
+export * from "./StateWait.d.ts";
 export * from "./StoreCatalogue.d.ts";
 export * from "./StoreSurfaceSource.d.ts";
 export * from "./storeSurface.d.ts";

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

@@ -0,0 +1,17 @@
+/**
+ * The abort signal of the tool call running now.
+ *
+ * Reached through a module slot rather than a parameter for the same reason `AgentProgress` is — work several
+ * frames down, a store action or a poll loop, reads it without every signature between here and there growing a
+ * channel argument, and a session executes tool calls one at a time. Outside a call `current` is null, so a tool
+ * that honours it runs unchanged in a test, under the dock, and on the server.
+ *
+ * Honouring it is optional: the session races every call against the same signal, so Stop lands whatever a tool
+ * does. What reading it buys is the tool's own cleanup — a timer that would otherwise keep ticking for the rest of
+ * its timeout with nobody left to answer.
+ */
+export declare class AgentAbort {
+    #private;
+    static get current(): AbortSignal | null;
+    static run<T>(signal: AbortSignal, exec: () => Promise<T> | T): Promise<T>;
+}

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

@@ -1,3 +1,4 @@
+export * from "./AgentAbort.d.ts";
 export * from "./Agentic.d.ts";
 export * from "./AgenticSurface.d.ts";
 export * from "./AgentProgress.d.ts";

package/vendor/use-agentic/AgentAbort.ts

@@ -0,0 +1,29 @@
+/**
+ * The abort signal of the tool call running now.
+ *
+ * Reached through a module slot rather than a parameter for the same reason `AgentProgress` is — work several
+ * frames down, a store action or a poll loop, reads it without every signature between here and there growing a
+ * channel argument, and a session executes tool calls one at a time. Outside a call `current` is null, so a tool
+ * that honours it runs unchanged in a test, under the dock, and on the server.
+ *
+ * Honouring it is optional: the session races every call against the same signal, so Stop lands whatever a tool
+ * does. What reading it buys is the tool's own cleanup — a timer that would otherwise keep ticking for the rest of
+ * its timeout with nobody left to answer.
+ */
+export class AgentAbort {
+  static #signal: AbortSignal | null = null;
+
+  static get current(): AbortSignal | null {
+    return AgentAbort.#signal;
+  }
+
+  static async run<T>(signal: AbortSignal, exec: () => Promise<T> | T): Promise<T> {
+    const outer = AgentAbort.#signal;
+    AgentAbort.#signal = signal;
+    try {
+      return await exec();
+    } finally {
+      AgentAbort.#signal = outer;
+    }
+  }
+}

package/vendor/use-agentic/AgentSession.ts

@@ -1,3 +1,4 @@
+import { AgentAbort } from "./AgentAbort";
 import { AgentProgress, type AgentProgressReport } from "./AgentProgress";
 import type {
   AgentRunner,
@@ -300,12 +301,14 @@ export class AgentSession {
     }
     const before = this.#surface.snapshot();
     try {
-      const result = await AgentProgress.run(
-        (report) => {
-          this.#progress = { ...report, callId: call.id };
-          this.#notify();
-        },
-        () => this.#surface.call(call.name, call.args),
+      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.effect !== "query") await this.#options.settle?.();
@@ -402,6 +405,35 @@ 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;

package/vendor/use-agentic/index.ts

@@ -1,4 +1,5 @@
 "use client";
+export * from "./AgentAbort";
 export * from "./Agentic";
 export * from "./AgenticSurface";
 export * from "./AgentProgress";