akanjs 3.0.0-alpha.16 → 3.0.0-alpha.18

package/README.ko.md

@@ -26,7 +26,7 @@ generated reference가 같은 의도에서 이어집니다.
 
 ## 요구사항
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript 중심의 애플리케이션 코드
 - React 기반 UI surface
 

package/README.md

@@ -25,7 +25,7 @@ server, app packaging, deployment artifacts, and generated references.
 
 ## Requirements
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript-first application code
 - React-based UI surfaces
 

package/constant/index.ts

@@ -5,6 +5,7 @@ export * from "./deserialize";
 export * from "./fieldInfo";
 export * from "./getDefault";
 export * from "./immerify";
+export * from "./labelOf";
 export * from "./mask";
 export * from "./purify";
 export * from "./serialize";

package/constant/labelOf.ts

@@ -0,0 +1,17 @@
+/**
+ * The one line a human scans for, derived from what the model already declared: the `text: "title"` search role
+ * names exactly that field, so an agent-facing label costs no new declaration. Falls back to the conventional
+ * `title`/`name` keys; the id is the caller's floor.
+ */
+export const labelOf = (model: unknown, value: unknown): string | undefined => {
+  if (!value || typeof value !== "object") return undefined;
+  const source = value as Record<string, unknown>;
+  const paths = (model as { text?: { title?: Iterable<string> } } | null)?.text?.title;
+  const titlePath = [...(paths ?? [])].find((path) => !path.includes(".") && !path.includes("["));
+  for (const key of [titlePath, "title", "name"]) {
+    if (!key) continue;
+    const candidate = source[key];
+    if (typeof candidate === "string" && candidate) return candidate;
+  }
+  return undefined;
+};

package/dictionary/agent.dictionary.ts

@@ -0,0 +1,31 @@
+import type { AgentEndpoint } from "akanjs/signal";
+
+import { serviceDictionary } from "./dictInfo";
+
+export const agentDictionary = serviceDictionary(["en", "ko"])
+  .endpoint<AgentEndpoint>((fn) => ({
+    runAgentTurn: fn(["Run Agent Turn", "에이전트 턴 실행"])
+      .desc([
+        "Relays one in-page agent turn to the model and returns its answer; tools execute in the caller's browser",
+        "인페이지 에이전트 턴 하나를 모델에 릴레이하고 응답을 돌려준다. 툴 실행은 호출자의 브라우저에서 한다",
+      ])
+      .arg((t) => ({
+        messages: t(["Messages", "메시지"]).desc(["The whole transcript in wire shape", "와이어 형태의 전체 대화"]),
+        tools: t(["Tools", "툴"]).desc(["The published tool catalogue, schemas only", "게시된 툴 카탈로그 (스키마만)"]),
+        context: t(["Context", "컨텍스트"]).desc([
+          "Screen context blocks, forwarded as data",
+          "화면 컨텍스트 블록 (데이터로 전달)",
+        ]),
+        instructions: t(["Instructions", "지시문"]).desc(["App-level system instructions", "앱 수준 시스템 지시문"]),
+      })),
+  }))
+  .error({
+    llmUnavailable: [
+      "The agent model is unavailable — no LLM adaptor answered this turn",
+      "에이전트 모델을 사용할 수 없습니다. 이번 턴에 응답한 LLM 어댑터가 없습니다",
+    ],
+    deepseekRequestFailed: [
+      "DeepSeek request failed with status {status}",
+      "DeepSeek 요청이 실패했습니다 (status {status})",
+    ],
+  });

package/dictionary/agentTurn.dictionary.ts

@@ -0,0 +1,29 @@
+import type { AgentStop, AgentTurn } from "akanjs/signal";
+
+import { scalarDictionary } from "./dictInfo";
+
+export const agentTurnDictionary = scalarDictionary(["en", "ko"])
+  .of((t) =>
+    t(["Agent Turn", "에이전트 턴"]).desc([
+      "One assistant answer of an in-page agent turn",
+      "인페이지 에이전트 턴의 어시스턴트 응답 하나",
+    ]),
+  )
+  .model<AgentTurn>((t) => ({
+    text: t(["Text", "텍스트"]).desc([
+      "What the assistant said; empty when the turn is only tool calls",
+      "어시스턴트가 말한 내용. 툴 호출뿐인 턴에서는 비어 있다",
+    ]),
+    toolCalls: t(["Tool Calls", "툴 호출"]).desc([
+      "Tool calls the client should execute, as { id, name, args }",
+      "클라이언트가 실행할 툴 호출 목록 ({ id, name, args })",
+    ]),
+    stop: t(["Stop", "종료 사유"]).desc([
+      "Why the turn ended — end, or toolUse when tool results are awaited",
+      "턴이 끝난 이유 — end 또는 툴 결과를 기다리는 toolUse",
+    ]),
+  }))
+  .enum<AgentStop>("agentStop", (t) => ({
+    end: t(["End", "종료"]).desc(["The final answer", "최종 응답"]),
+    toolUse: t(["Tool Use", "툴 사용"]).desc(["The model awaits tool results", "모델이 툴 결과를 기다린다"]),
+  }));

package/dictionary/base.dictionary.ts

@@ -48,6 +48,14 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     ok: ["OK", "확인"],
     cancel: ["Cancel", "취소"],
     unauthorized: ["Unauthorized", "권한 없음"],
+    agent: ["Agent", "에이전트"],
+    agentIntro: ["Ask about this page or tell the agent what to do.", "이 화면에 대해 묻거나 할 일을 지시해 보세요."],
+    agentPlaceholder: ["Message the agent...", "에이전트에게 메시지..."],
+    agentClear: ["Clear conversation", "대화 비우기"],
+    send: ["Send", "보내기"],
+    stop: ["Stop", "중지"],
+    approve: ["Approve", "승인"],
+    decline: ["Decline", "거절"],
     confirmClose: ["Are you sure you want to close the modal?", "모달을 닫으시겠습니까?"],
     textTooShortError: ["More than {minlength} characters needed.", "{minlength}자 이상 필요합니다."],
     textTooLongError: ["Less than {maxlength} characters needed.", "{maxlength}자 이하로 필요합니다."],

package/dictionary/dictionary.ts

@@ -1,10 +1,16 @@
-import type { BaseEndpoint } from "akanjs/signal";
+import type { AgentEndpoint, AgentTurn, BaseEndpoint } from "akanjs/signal";
 
+import { agentDictionary } from "./agent.dictionary";
+import { agentTurnDictionary } from "./agentTurn.dictionary";
 import { baseDictionary } from "./base.dictionary";
-import { registerServiceTrans } from "./locale";
+import { registerScalarTrans, registerServiceTrans } from "./locale";
 import { makeTrans } from "./trans";
 
-export const dictionary = { base: registerServiceTrans<"base", BaseEndpoint, typeof baseDictionary>(baseDictionary) };
+export const dictionary = {
+  base: registerServiceTrans<"base", BaseEndpoint, typeof baseDictionary>(baseDictionary),
+  agentTurn: registerScalarTrans<"agentTurn", AgentTurn, typeof agentTurnDictionary>(agentTurnDictionary),
+  agent: registerServiceTrans<"agent", AgentEndpoint, typeof agentDictionary>(agentDictionary),
+};
 
 export const { Err, translate, msg, getDictionary, getAllDictionary, __Dict_Key__, __Error_Key__ } =
   makeTrans(dictionary);

package/fetch/agentTurn.ts

@@ -0,0 +1,19 @@
+import { Any, enumOf } from "akanjs/base";
+import { ConstantRegistry, via } from "akanjs/constant";
+
+export class AgentStop extends enumOf("agentStop", ["end", "toolUse"] as const) {}
+
+export class AgentTurn extends via((field) => ({
+  text: field(String, { default: "" }), // the assistant's words; empty when the turn is only tool calls
+  toolCalls: field([Any]), // { id, name, args } per call — args carries the tool's own schema, not a model's
+  stop: field(AgentStop, { default: "end" }),
+})) {
+  isToolUse() {
+    return this.stop === "toolUse";
+  }
+}
+
+export const agentTurnConstant = ConstantRegistry.buildScalar("agentTurn" as const, AgentTurn, {
+  AgentTurn,
+  AgentStop,
+});

package/fetch/client/fetchClient.ts

@@ -10,6 +10,7 @@ import type {
   SerializedSlice,
   ServiceSignal,
 } from "akanjs/signal";
+import { agentTurnConstant } from "../agentTurn";
 import type { ClientSignal, FetchClientType, FetchSignalInput, MergeAllFetchTypes, SliceMeta } from "../fetchType";
 import { memoizeRequestQuery, cookies as requestCookies, headers as requestHeaders } from "../requestStorage";
 import type { GetSliceMetaObjFromDatabaseSignals } from "../types";
@@ -47,6 +48,19 @@ const globalWithSharedClient = globalThis as typeof globalThis & { [SHARED_CLIEN
 const sharedClientState: SharedClientState = globalWithSharedClient[SHARED_CLIENT_KEY] ?? { proxy: null, origin: null };
 globalWithSharedClient[SHARED_CLIENT_KEY] = sharedClientState;
 
+interface SharedSignalRegistry {
+  signal: { [key: string]: SerializedSignal };
+  version: number;
+}
+
+const SHARED_SIGNAL_KEY = Symbol.for("akanjs.fetch.sharedSignalRegistry");
+const globalWithSharedSignal = globalThis as typeof globalThis & { [SHARED_SIGNAL_KEY]?: SharedSignalRegistry };
+const sharedSignalRegistry: SharedSignalRegistry = globalWithSharedSignal[SHARED_SIGNAL_KEY] ?? {
+  signal: {},
+  version: 0,
+};
+globalWithSharedSignal[SHARED_SIGNAL_KEY] = sharedSignalRegistry;
+
 type ClientSignalMap<SigType extends { fetch: any }> = {
   [K in keyof SigType as SigType[K] extends DatabaseSignal<any, any, any, any>
     ? K
@@ -57,8 +71,9 @@ type ClientSignalMap<SigType extends { fetch: any }> = {
 
 /** Runtime fetch client that registers serialized Akan signals as HTTP/WebSocket methods. */
 export class FetchClient {
-  static #sharedSerializedSignal: { [key: string]: SerializedSignal } = {};
-  static #sharedRegistryVersion = 0;
+  static {
+    ConstantRegistry.setScalar(agentTurnConstant.refName, agentTurnConstant);
+  }
   readonly logger = new Logger("FetchClient");
   readonly origin: string;
   readonly http: HttpClient;
@@ -93,11 +108,11 @@ export class FetchClient {
    * would change what the next client applies. Read by the agent catalogue, which needs the argument schemas.
    */
   static get sharedSerializedSignal(): { [key: string]: SerializedSignal } {
-    return { ...FetchClient.#sharedSerializedSignal };
+    return { ...sharedSignalRegistry.signal };
   }
   static resetSharedRegistry() {
-    FetchClient.#sharedSerializedSignal = {};
-    FetchClient.#sharedRegistryVersion++;
+    sharedSignalRegistry.signal = {};
+    sharedSignalRegistry.version++;
   }
   static resetSharedClient() {
     sharedClientState.proxy = null;
@@ -147,9 +162,9 @@ export class FetchClient {
   applySignal(serializedSignal: { [key: string]: SerializedSignal }, { share = true }: { share?: boolean } = {}) {
     if (share && Object.keys(serializedSignal).length > 0) {
       for (const [refName, signal] of Object.entries(serializedSignal))
-        FetchClient.#mergeSerializedSignalInto(FetchClient.#sharedSerializedSignal, refName, signal);
-      FetchClient.#sharedRegistryVersion++;
-      this.#sharedRegistryAppliedVersion = FetchClient.#sharedRegistryVersion;
+        FetchClient.#mergeSerializedSignalInto(sharedSignalRegistry.signal, refName, signal);
+      sharedSignalRegistry.version++;
+      this.#sharedRegistryAppliedVersion = sharedSignalRegistry.version;
     }
     for (const [refName, signal] of Object.entries(serializedSignal))
       FetchClient.#mergeSerializedSignalInto(this.serializedSignal, refName, signal);
@@ -183,9 +198,9 @@ export class FetchClient {
     });
   }
   #syncSharedRegistry() {
-    if (this.#sharedRegistryAppliedVersion === FetchClient.#sharedRegistryVersion) return;
-    this.applySignal(FetchClient.#sharedSerializedSignal, { share: false });
-    this.#sharedRegistryAppliedVersion = FetchClient.#sharedRegistryVersion;
+    if (this.#sharedRegistryAppliedVersion === sharedSignalRegistry.version) return;
+    this.applySignal(sharedSignalRegistry.signal, { share: false });
+    this.#sharedRegistryAppliedVersion = sharedSignalRegistry.version;
   }
   #getOrCreateHandler(key: string): FetchHandler | undefined {
     const current = this.#handlerStore[key];
@@ -719,9 +734,16 @@ export class FetchClient {
         });
       }
     });
-    const instance = new FetchClient(getEnv().serverHttpUri, handler, serializedSignal);
+    const instance = new FetchClient(FetchClient.#originFromEnv(), handler, serializedSignal);
     return FetchClient.#makeProxy<MergeAllFetchTypes<Signals>, GetSliceMetaObjFromDatabaseSignals<Signals>>(instance);
   }
+  static #originFromEnv() {
+    try {
+      return getEnv().serverHttpUri;
+    } catch {
+      return "";
+    }
+  }
   static build<SigType extends { fetch: any }>(
     constant: object,
     serializedSignal: { [key: string]: SerializedSignal },

package/fetch/index.ts

@@ -1,3 +1,4 @@
+export * from "./agentTurn";
 export * from "./client";
 export * from "./fetchType";
 export * from "./requestStorage";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.16",
+  "version": "3.0.0-alpha.18",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -180,7 +180,6 @@
   "dependencies": {
     "dayjs": "^1.11.20",
     "immer": "^11.1.8",
-    "sharp": "^0.34.5",
     "tailwind-merge": "^3.3.1",
     "tailwind-variants": "^3.3.0"
   },
@@ -202,6 +201,7 @@
     "@capacitor/preferences": "^8.0.1",
     "@capacitor/push-notifications": "^8.1.1",
     "@capgo/capacitor-updater": "^8.46.1",
+    "@happy-dom/global-registrator": "^20.11.2",
     "@libsql/client": "^0.17.3",
     "@playwright/test": "^1.60.0",
     "@react-spring/web": "^10.1.0",
@@ -210,8 +210,8 @@
     "capacitor-plugin-safe-area": "^5.0.0",
     "chance": "^1.1.13",
     "cordova-plugin-purchase": "^13.16.0",
-    "croner": "^10.0.1",
     "firebase": "^12.13.0",
+    "happy-dom": "^20.11.2",
     "ioredis": "^5.10.1",
     "mermaid": "^11.15.0",
     "postgres": "^3.4.9",
@@ -225,7 +225,6 @@
     "react-simple-pull-to-refresh": "^1.3.4",
     "react-spring": "^10.0.4",
     "scheduler": "^0.27.0",
-    "sharp": "^0.34.5",
     "tailwind-scrollbar": "^4.0.2",
     "typescript": "^6.0.3"
   },
@@ -281,6 +280,9 @@
     "@capgo/capacitor-updater": {
       "optional": true
     },
+    "@happy-dom/global-registrator": {
+      "optional": true
+    },
     "@libsql/client": {
       "optional": true
     },
@@ -305,10 +307,10 @@
     "cordova-plugin-purchase": {
       "optional": true
     },
-    "croner": {
+    "firebase": {
       "optional": true
     },
-    "firebase": {
+    "happy-dom": {
       "optional": true
     },
     "ioredis": {
@@ -359,13 +361,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.8",
-    "@types/bun": "^1.3.14"
+    "@types/bun": "^1.4.0"
   },
   "bun": {
     "platform": "bun"
   },
   "engines": {
-    "bun": ">=1.3.13"
+    "bun": ">=1.4.0"
   },
   "main": "./index.ts"
 }

package/server/akanApp.ts

@@ -6,7 +6,6 @@ import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
 import { isTraceEnabled } from "akanjs/signal";
 import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
-import type { McpServerOption } from "./akanServer";
 import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { resolveEncodedSidecar } from "./assetEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
@@ -55,11 +54,6 @@ export interface AkanAppOptions {
   port?: number;
   wsBasePort?: number;
   openapi?: boolean;
-  /**
-   * MCP server config for the children, which are the processes that actually mount `/mcp`. Declared here
-   * because `server.ts` is generated and takes no options, so `main.ts` is the only app-authored place left.
-   */
-  mcp?: boolean | McpServerOption;
 }
 
 interface AkanReplicaConfig {
@@ -92,7 +86,6 @@ export class AkanApp {
   readonly #port: number;
   readonly #wsBasePort: number;
   readonly #openapi?: boolean;
-  readonly #mcpEnv: Record<string, string>;
   readonly #children = new Map<number, ChildState>();
   readonly #roomChildren = new Map<string, Set<number>>();
   readonly #childRooms = new Map<number, Set<string>>();
@@ -134,30 +127,6 @@ 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.#mcpEnv = AkanApp.#toMcpEnv(resolvedOptions.mcp);
-  }
-
-  /**
-   * `McpServerOption`, spelled as the environment a child is spawned with — the only channel the gateway has to
-   * a process it starts, and the same one a deployment configures MCP through when it sets nothing in code.
-   */
-  static #toMcpEnv(mcp: boolean | McpServerOption | undefined): Record<string, string> {
-    if (mcp === undefined) return {};
-    if (typeof mcp === "boolean") return { AKAN_MCP: String(mcp) };
-    const { enabled, readOnly, path: mcpPath, version, instructions, allowedOrigins, pageSize, language, auth } = mcp;
-    return {
-      AKAN_MCP: String(enabled ?? true),
-      ...(readOnly === undefined ? {} : { AKAN_MCP_READONLY: String(readOnly) }),
-      ...(mcpPath ? { AKAN_MCP_PATH: mcpPath } : {}),
-      ...(version ? { AKAN_MCP_VERSION: version } : {}),
-      ...(instructions ? { AKAN_MCP_INSTRUCTIONS: instructions } : {}),
-      ...(allowedOrigins?.length ? { AKAN_MCP_ALLOWED_ORIGINS: allowedOrigins.join(",") } : {}),
-      ...(pageSize === undefined ? {} : { AKAN_MCP_PAGE_SIZE: String(pageSize) }),
-      ...(language ? { AKAN_MCP_LANGUAGE: language } : {}),
-      ...(auth?.authorizationServers?.length ? { AKAN_MCP_AUTH_SERVERS: auth.authorizationServers.join(",") } : {}),
-      ...(auth?.scopes?.length ? { AKAN_MCP_SCOPES: auth.scopes.join(",") } : {}),
-      ...(auth?.resource ? { AKAN_MCP_RESOURCE: auth.resource } : {}),
-    };
   }
 
   static #resolveServerPath(serverPath: string) {
@@ -328,7 +297,6 @@ 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.#mcpEnv,
       },
       ipc: (message) => this.#handleMessage(idx, message as AkanIpcMessage, proc),
       stdout: "pipe",
@@ -626,7 +594,11 @@ export class AkanApp {
       const result = ws.send(event.data as string | ArrayBuffer);
       if (result === 0) upstream.close();
     });
-    upstream.addEventListener("close", (event) => ws.close(event.code, event.reason));
+    upstream.addEventListener("close", (event) => {
+      const code = AkanApp.#sendableCloseCode(event.code);
+      if (code === undefined) ws.close();
+      else ws.close(code, event.reason);
+    });
     upstream.addEventListener("error", () => ws.close(1011, "upstream websocket error"));
     Object.assign(ws.data, { pending });
   }
@@ -646,8 +618,15 @@ export class AkanApp {
     else ws.data.pending?.push(payload as string | ArrayBuffer);
   }
 
+  static #sendableCloseCode(code: number): number | undefined {
+    const sendable = (code >= 1000 && code <= 1014 && (code < 1004 || code > 1006)) || (code >= 3000 && code <= 4999);
+    return sendable ? code : undefined;
+  }
+
   #handleWsClose(ws: Bun.ServerWebSocket<GatewayWsData>, code: number, reason: string) {
-    ws.data.upstream.close(code, reason);
+    const upstreamCode = AkanApp.#sendableCloseCode(code);
+    if (upstreamCode === undefined) ws.data.upstream.close();
+    else ws.data.upstream.close(upstreamCode, reason);
     const child = this.#children.get(ws.data.childIdx);
     if (child) child.metrics.activeWebSockets = Math.max(0, (child.metrics.activeWebSockets ?? 1) - 1);
   }

package/server/akanOption.ts

@@ -1,13 +1,27 @@
 import type { BaseEnv, PromiseOrObject } from "akanjs/base";
-import type { MiddlewareCls } from "akanjs/signal";
+import type { Adaptor, AdaptorCls, LlmOption } from "akanjs/service";
+import type { AgentRelayPolicy, MiddlewareCls } from "akanjs/signal";
+import type { McpServerOption } from "./akanServer";
 import type { WebProxyRegistration } from "./proxy";
 import { HostBasePathWebProxy, LocaleWebProxy } from "./proxy";
 
-/** App/library server option builder for use objects, signal middleware, and web proxies. */
+export interface AdaptorOverride {
+  role: AdaptorCls;
+  adaptor: AdaptorCls;
+}
+
+/**
+ * App/library server option builder: use objects, signal middleware, adaptor overrides, web proxies, and the
+ * server settings an app owns — MCP, the agent relay's access policy, and the LLM the relay speaks to.
+ */
 export class AkanOption<Env extends BaseEnv = BaseEnv> {
   readonly #getUses: ((env: Env) => Record<string, PromiseOrObject<unknown>>)[];
   readonly #middlewares: MiddlewareCls[] = [];
+  readonly #adaptorOverrides: AdaptorOverride[] = [];
   readonly #webProxies: WebProxyRegistration[] = [];
+  readonly #getLlms: ((env: Env) => LlmOption)[] = [];
+  #mcp: boolean | McpServerOption | undefined;
+  #agentAccess: AgentRelayPolicy | null | undefined;
   constructor() {
     this.#getUses = [];
   }
@@ -21,10 +35,38 @@ export class AkanOption<Env extends BaseEnv = BaseEnv> {
     this.#middlewares.push(...middlewares);
     return this;
   }
+  /** Rebinds a predefined adaptor role (e.g. `LlmAdaptorRole`) to the app's own implementation. Last writer wins. */
+  applyAdaptor<T extends Adaptor>(role: AdaptorCls<T>, adaptor: AdaptorCls<T>) {
+    this.#adaptorOverrides.push({ role: role as AdaptorCls, adaptor: adaptor as AdaptorCls });
+    return this;
+  }
   applyWebProxy(...proxies: WebProxyRegistration[]) {
     this.#webProxies.push(...proxies);
     return this;
   }
+  /**
+   * MCP server settings for the app mounting this option, merged over the `AKAN_MCP_*` environment and under an
+   * option the server is constructed with. The app's own `option.ts` is the last lib the server reads, so it wins
+   * over every library it depends on.
+   */
+  setMcp(mcp: boolean | McpServerOption = true) {
+    this.#mcp = mcp;
+    return this;
+  }
+  /**
+   * Who may spend the LLM key through the `runAgentTurn` relay — the `AgentRelayAccess` policy, which defaults to
+   * allowing everyone because the framework has no account model to gate on. `null` reopens it.
+   */
+  setAgentAccess(policy: AgentRelayPolicy | null) {
+    this.#agentAccess = policy;
+    return this;
+  }
+  /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
+  setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)) {
+    if (typeof llmOrFn === "function") this.#getLlms.push(llmOrFn);
+    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);
@@ -32,9 +74,21 @@ export class AkanOption<Env extends BaseEnv = BaseEnv> {
   getMiddlewares(): MiddlewareCls[] {
     return this.#middlewares;
   }
+  getAdaptorOverrides(): AdaptorOverride[] {
+    return this.#adaptorOverrides;
+  }
   getWebProxies(): WebProxyRegistration[] {
     return this.#webProxies;
   }
+  getMcp(): boolean | McpServerOption | undefined {
+    return this.#mcp;
+  }
+  getAgentAccess(): AgentRelayPolicy | null | undefined {
+    return this.#agentAccess;
+  }
+  getLlm(env: Env): LlmOption {
+    return Object.assign({}, ...this.#getLlms.map((fn) => fn(env)));
+  }
 }
 
 export function createDefaultAkanOption() {

package/server/akanServer.ts

@@ -11,6 +11,7 @@ import type {
   SolidConfig,
 } from "akanjs/service";
 import type { ServerSignal, ServerSignalCls, WebsocketPublishData } from "akanjs/signal";
+import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
 import type { AkanLib, AkanLibProps } from "./akanLib";
@@ -142,6 +143,13 @@ export class AkanServer {
     this.libs = libs;
     this.env = { ...env };
     this.openapi = options?.openapi ?? this.openapi;
+    
+    libs.forEach((lib) => {
+      const mcp = lib.option.getMcp();
+      if (mcp !== undefined) this.setMcp(mcp);
+      const agentAccess = lib.option.getAgentAccess();
+      if (agentAccess !== undefined) AgentRelayAccess.use(agentAccess);
+    });
     this.setMcp(options?.mcp ?? this.mcp);
     this.serverMode = serverMode;
     this.#di = new DiLifecycle(this.env, serverMode, ...libs);
@@ -616,12 +624,9 @@ export class AkanServer {
   }
 
   /**
-   * The rest of `McpServerOption`, in the one channel that reaches this process.
-   *
-   * `server.ts` is generated and constructs `AkanServer` with no options, and a child of the gateway is handed
-   * nothing but its environment — so without an env spelling per field, the only settable parts were the two
-   * booleans and `instructions` / `allowedOrigins` / `path` / `version` / `pageSize` / `language` had no path
-   * from an app at all. An option passed in code still wins: `setMcp` merges over this.
+   * The rest of `McpServerOption`, spelled as environment — the channel a deployment configures what the source
+   * does not through, and the only one a child of the gateway is handed. An app writes these in its `option.ts`,
+   * which merges over this: a value written in code wins over the env of the same name.
    */
   /**
    * Keys whose value is `undefined` are dropped before the merge. "An option written in code wins over the env of