akanjs 3.0.0-alpha.65 → 3.0.0-alpha.67

package/index.ts

@@ -4,14 +4,37 @@ import type { AkanImageConfig } from "akanjs/server";
 export const archs = ["amd64", "arm64"] as const;
 export type Arch = (typeof archs)[number];
 
-export interface DockerConfig {
-  content: string;
+/** One image step. The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
+export type DockerRun = string | { [key in Arch]?: string };
+
+/** The pieces Akan assembles a Dockerfile from. */
+export interface DockerImageConfig {
   image: string | { [key in Arch]?: string };
-  preRuns: (string | { [key in Arch]?: string })[];
-  postRuns: (string | { [key in Arch]?: string })[];
+  /** Runs before `bun install`, so a system package a native dependency needs is there for the install. */
+  preRuns: DockerRun[];
+  /** Runs after `bun install`, before the app files are copied. */
+  postRuns: DockerRun[];
   command: string[];
 }
 
+/**
+ * A whole Dockerfile as a string, or the parts Akan assembles one from. The string form is taken verbatim —
+ * nothing is merged into it, including the steps a lib contributes through its own `docker`.
+ */
+export type DockerConfig = string | DockerImageConfig;
+
+/** What an `akan.config.ts` may write for `docker`: a whole Dockerfile, or any subset of the parts. */
+export type DockerOption = string | Partial<DockerImageConfig>;
+
+/**
+ * A lib's contribution to the image of every app that mounts it — a lib never picks the base image or the
+ * command, only the steps its own runtime needs.
+ */
+export interface LibDockerConfig {
+  preRuns: DockerRun[];
+  postRuns: DockerRun[];
+}
+
 export interface AkanRouteDomains {
   main?: string[];
   develop?: string[];
@@ -201,6 +224,8 @@ export interface AppConfigResult {
 
 export interface LibConfigResult {
   externalLibs: string[];
+  /** Image steps every app that mounts this lib inherits, unless that app declares a whole Dockerfile. */
+  docker: LibDockerConfig;
 }
 
 export type DeepPartial<T> = {
@@ -217,7 +242,8 @@ export interface LibConfigContext {
   readonly type: "lib";
 }
 
-export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "web"> & {
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+  docker?: DockerOption;
   web?: AkanWebOption;
   plugins?: AkanPlugin[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.65",
+  "version": "3.0.0-alpha.67",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -166,6 +166,11 @@
       "import": "./server/rscWorker.tsx",
       "default": "./server/rscWorker.tsx"
     },
+    "./server/akanApp": {
+      "types": "./types/server/akanApp.d.ts",
+      "import": "./server/akanApp.ts",
+      "default": "./server/akanApp.ts"
+    },
     "./server/memoryLimit": {
       "types": "./types/server/memoryLimit.d.ts",
       "import": "./server/memoryLimit.ts",

package/server/akanApp.ts

@@ -4,11 +4,12 @@ import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
-import { isTraceEnabled } from "akanjs/signal";
+import { isTraceEnabled } from "../signal/trace";
 import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { resolveEncodedSidecar } from "./assetEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
+import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { getWebConfigFromEnv } from "./types";
@@ -36,6 +37,11 @@ interface ChildState {
   lastErrorMessage?: string;
 }
 
+/** The shape `#startSolo` needs off `server.ts`; the module itself is loaded by path, so it has no type here. */
+interface SoloServer {
+  start: (options: { listen: boolean }) => Promise<unknown>;
+}
+
 interface GatewayWsData {
   childIdx: number;
   upstream: WebSocket;
@@ -72,6 +78,13 @@ export interface AkanAppOptions {
    * module. Handed down as `AKAN_MODULES`, since each replica builds its own container.
    */
   modules?: string[];
+  /**
+   * Run the one replica in this process instead of spawning it — see `#startSolo`. Defaults on for a single
+   * traffic replica the environment configured, and off whenever `replica` is passed here, because code that
+   * states a topology is asking for the gateway that serves it. `AKAN_SOLO=false` turns it off; like
+   * `AKAN_SSR`, the env can only narrow, so it cannot force a gateway's replicas into one process.
+   */
+  solo?: boolean;
 }
 
 interface AkanReplicaConfig {
@@ -107,6 +120,7 @@ export class AkanApp {
   /** The gateway hands `/_akan/client|styles|fonts` straight off disk, so it needs the same answer its children do. */
   readonly #web = getWebConfigFromEnv();
   readonly #modules: string[];
+  readonly #solo: boolean;
   readonly #children = new Map<number, ChildState>();
   readonly #roomChildren = new Map<string, Set<number>>();
   readonly #childRooms = new Map<number, Set<string>>();
@@ -138,17 +152,29 @@ export class AkanApp {
     this.#serverPath = AkanApp.#resolveServerPath(resolvedOptions.serverPath ?? serverPath);
     this.#artifactDir = path.resolve(path.dirname(this.#serverPath), ".akan", "artifact");
     this.#replica = AkanApp.#parseReplicaConfig(resolvedOptions.replica);
-    this.#runtimeDir = path.resolve(
-      resolvedOptions.runtimeDir ??
-        process.env.AKAN_RUNTIME_DIR ??
-        (process.env.NODE_ENV === "production"
-          ? path.resolve(process.cwd(), "runtime")
-          : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime")),
-    );
+    this.#runtimeDir = resolveRuntimeDir(resolvedOptions.runtimeDir);
     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 ?? [];
+    this.#solo = AkanApp.#resolveSolo(resolvedOptions, this.#replica);
+  }
+
+  /**
+   * One replica that serves traffic means there is nothing to balance and nothing to fan pubsub out to, so the
+   * gateway is a second Bun runtime and a proxy hop in front of the only server there is. Measured on
+   * `apps/akan`: 28MB of RSS and half the requests per second.
+   *
+   * A batch-only replica is excluded because it never listens — keeping the gateway is what leaves something
+   * bound to answer `/_akan/app/health`. `akan start` is excluded because the gateway is also the dev host's
+   * builder relay, its crash page, and what holds the port across a child restart.
+   */
+  static #resolveSolo(options: AkanAppOptions, replica: AkanReplicaConfig) {
+    if (options.solo !== undefined) return options.solo;
+    if (process.env.AKAN_SOLO === "false" || process.env.AKAN_SOLO === "0") return false;
+    if (process.env.AKAN_COMMAND_TYPE === "start") return false;
+    if (options.replica !== undefined) return false;
+    return replica.total === 1 && replica.batch === 0;
   }
 
   static #resolveServerPath(serverPath: string) {
@@ -215,6 +241,7 @@ export class AkanApp {
   }
 
   async start() {
+    if (this.#solo) return await this.#startSolo();
     await this.#prepareRuntimeDir();
     this.#startFileLogging();
     for (let idx = 0; idx < this.#replica.total; idx++) this.#spawn(idx);
@@ -242,6 +269,25 @@ export class AkanApp {
     });
   }
 
+  async #startSolo() {
+    const role = this.#getRole(0);
+
+    Object.assign(process.env, {
+      NODE_ENV: AkanApp.#defaultChildNodeEnv(),
+      AKAN_REPLICA: this.#replica.value,
+      AKAN_REPLICA_IDX: "0",
+      AKAN_APP_DIR: path.dirname(this.#serverPath),
+      SERVER_MODE: role,
+      ...(this.#openapi === undefined ? {} : { AKAN_OPENAPI: this.#openapi ? "true" : "false" }),
+      ...(this.#modules.length ? { AKAN_MODULES: this.#modules.join(",") } : {}),
+    });
+    this.logger.info(`Starting ${role} replica in this process (solo); set AKAN_SOLO=false for the gateway`);
+    const mod = (await import(this.#serverPath)) as { server?: SoloServer; app?: SoloServer };
+    const server = mod.server ?? mod.app;
+    if (!server?.start) throw new Error("server.ts must export server or app with start()");
+    await server.start({ listen: true });
+  }
+
   async stop(signal = "SIGTERM") {
     if (this.#stopping) return;
     this.#stopping = true;

package/server/akanServer.ts

@@ -6,6 +6,7 @@ import type {
   Adaptor,
   AdaptorCls,
   AkanIpcMessage,
+  AkanMetricsReport,
   DatabaseConfig,
   Service,
   ServiceCls,
@@ -15,6 +16,7 @@ import type { ServerSignal, ServerSignalCls, WebsocketPublishData } from "akanjs
 import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
+import { SignalContext } from "../signal/signalContext";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import type { BuilderRpc } from "./artifact";
 import { BinaryPubsub } from "./binaryPubsub";
@@ -22,13 +24,16 @@ import { DevtoolsRouter } from "./devtools";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { isPortInUseError } from "./lifecycle/portInUse";
+import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
 import { ShutdownManager } from "./lifecycle/shutdownManager";
+import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { type McpAuthOption, McpRouter } from "./mcp";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { WebProxyRunner } from "./proxy";
 import { SignalResolver } from "./resolver";
 import { ApiRouter } from "./routing/apiRouter";
 import type { AppWsData } from "./routing/appWsData";
+import { createSoloAppRoutes } from "./routing/soloAppRoutes";
 import {
   getWebConfigFromEnv,
   type HttpRoutes,
@@ -151,6 +156,16 @@ export class AkanServer {
   #localPublish: LocalPublish | null = null;
   readonly #binaryPubsub = new BinaryPubsub();
   #metricsTimer: Timer | null = null;
+  /**
+   * No gateway socket means nothing is proxying this process, so it owns the whole surface: the
+   * `/_akan/app/*` observability routes the gateway would have answered, and the rotating log file the
+   * gateway would have written. Derived rather than declared — a spawned child always carries the socket,
+   * so the two modes cannot disagree about which one this is.
+   */
+  readonly #solo = !process.env.AKAN_CHILD_SOCKET;
+  #logWriter: RotatingLogWriter | null = null;
+  #removeLogSink: (() => void) | null = null;
+  #lastMetrics: AkanMetricsReport = {};
   constructor(
     name = "AkanServer",
     env: BackendEnv = {},
@@ -313,7 +328,7 @@ export class AkanServer {
       return noWeb();
     }
     this.web = webRouter.web;
-    this.logger.info(`web on: ssr=${this.web.ssr} csr=${this.web.csr}`);
+    this.logger.verbose(`web on: ssr=${this.web.ssr} csr=${this.web.csr}`);
     const { renderEnvRoutes, hmrHub, builderRpc } = await webRouter.initializeRoute();
     const webProxyRunner = WebProxyRunner.create(this.#di.webProxies);
     this.#prepared = {
@@ -336,6 +351,7 @@ export class AkanServer {
       throw new Error("AkanServer is not able to listen. Call `init` first.");
     }
     this.status = "starting";
+    this.#startFileLogging();
     const port = process.env.AKAN_CHILD_SOCKET
       ? undefined
       : Number(process.env.AKAN_CHILD_WS_PORT || process.env.PORT || 8282);
@@ -401,6 +417,8 @@ export class AkanServer {
 
     const server = this.#server;
     const wsServer = this.#wsServer;
+
+    SignalContext.setHttpPeerResolver((req) => server?.requestIP(req as Bun.BunRequest) ?? null);
     hmrHub?.setPublisher((topic, payload) => {
       server?.publish(topic, payload);
       wsServer?.publish(topic, payload);
@@ -484,9 +502,11 @@ export class AkanServer {
       this.#wsServer?.stop(true);
       this.#server = null;
       this.#wsServer = null;
+      SignalContext.setHttpPeerResolver(null);
 
       this.#prepared?.webRouter?.dispose();
       await this.#withShutdownTimeout(this.#di.destroyAll());
+      await this.#stopFileLogging();
       this.#prepared = null;
       this.status = "stopped";
       this.logger.info(`Shutdown completed successfully in ${Date.now() - now}ms`);
@@ -547,6 +567,7 @@ export class AkanServer {
       pubsubCoalesceCount: this.#binaryPubsub.coalescedCount,
       ...(this.#prepared?.webRouter?.getMetrics() ?? {}),
     });
+    this.#lastMetrics = metrics;
     process.send?.({ type: "metrics.report", pid: process.pid, metrics } satisfies AkanIpcMessage);
     if (process.env.AKAN_MEMORY_LOG === "1") {
       this.logger.info(`memory role=${this.serverMode} ${ProcessMetricsCollector.format(metrics)}`);
@@ -600,6 +621,15 @@ export class AkanServer {
           })
         : null;
     const mcpRoutes: HttpRoutes = mcpRouter?.createRoutes() ?? {};
+    const soloRoutes: HttpRoutes = this.#solo
+      ? createSoloAppRoutes(() => ({
+          role: this.serverMode,
+          running: this.status === "running",
+          status: this.status,
+          port: this.#server?.port ?? null,
+          metrics: this.#lastMetrics,
+        }))
+      : {};
 
     mcpRouter?.report();
 
@@ -613,7 +643,24 @@ export class AkanServer {
       openapi: this.openapi,
       getStatus: () => this.status,
     }).createRoutes();
-    return { ...openapiRoutes, ...mcpRoutes, ...devtoolsRoutes };
+    return { ...openapiRoutes, ...mcpRoutes, ...devtoolsRoutes, ...soloRoutes };
+  }
+
+  #startFileLogging() {
+    if (!this.#solo || this.#logWriter) return;
+    this.#logWriter = RotatingLogWriter.fromRuntimeDir(resolveRuntimeDir());
+    if (!this.#logWriter) return;
+    this.#removeLogSink = Logger.addSink((entry) => {
+      this.#logWriter?.write(this.serverMode, entry.plainMessage);
+    });
+  }
+
+  async #stopFileLogging() {
+    this.#removeLogSink?.();
+    this.#removeLogSink = null;
+    const writer = this.#logWriter;
+    this.#logWriter = null;
+    await writer?.close();
   }
 
   /**

package/server/lifecycle/runtimeDir.ts

@@ -0,0 +1,14 @@
+import path from "node:path";
+
+/**
+ * Where a replica keeps its child sockets and rotating logs. Both the gateway and a solo server resolve it,
+ * and they must land on the same directory: switching between the two modes must not move the log file.
+ */
+export const resolveRuntimeDir = (runtimeDir?: string): string =>
+  path.resolve(
+    runtimeDir ??
+      process.env.AKAN_RUNTIME_DIR ??
+      (process.env.NODE_ENV === "production"
+        ? path.resolve(process.cwd(), "runtime")
+        : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime")),
+  );

package/server/processMetricsCollector.ts

@@ -1,5 +1,5 @@
 import type { AkanMetricsReport } from "akanjs/service";
-import { getTraceSnapshot, isTraceEnabled } from "akanjs/signal";
+import { getTraceSnapshot, isTraceEnabled } from "../signal/trace";
 
 type BunJscHeapStats = {
   heapSize?: number;

package/server/routing/soloAppRoutes.ts

@@ -0,0 +1,46 @@
+import type { AkanChildRole, AkanMetricsReport } from "akanjs/service";
+import type { HttpRoutes } from "../types";
+
+export interface SoloAppStatus {
+  role: AkanChildRole;
+  running: boolean;
+  status: string;
+  port: number | null;
+  metrics: AkanMetricsReport;
+}
+
+/**
+ * The gateway's `/_akan/app/*` surface, answered by a process nothing is proxying. The payload keeps the
+ * gateway's own shape — a `children` array with this process as its only entry — so a probe, a k8s check and
+ * `akan` tooling read one contract whether or not a gateway is in front.
+ */
+export const createSoloAppRoutes = (read: () => SoloAppStatus): HttpRoutes => {
+  const child = () => {
+    const { role, running, status, port } = read();
+    return {
+      idx: 0,
+      role,
+      status: running ? "healthy" : status,
+      ready: running,
+      pid: process.pid,
+      upstream: { type: "tcp" as const, host: "127.0.0.1", port },
+    };
+  };
+  return {
+    "/_akan/app/health": {
+      GET: () => Response.json({ status: read().status, pid: process.pid, solo: true, children: [child()] }),
+    },
+    "/_akan/app/metrics": {
+      GET: () =>
+        Response.json({
+          rooms: 0,
+          sockets: 0,
+          solo: true,
+          gateway: null,
+          proxyHop: null,
+          children: [{ ...child(), metrics: read().metrics }],
+        }),
+    },
+    "/_akan/bench/ping": { GET: () => new Response("ok") },
+  };
+};

package/signal/signalContext.ts

@@ -27,6 +27,9 @@ import { isTraceEnabled, runWithTrace, SignalTrace, traceSpan } from "./trace";
 
 export type SignalTransportType = "http" | "websocket";
 
+/** What `Bun.Server.requestIP` reports for the socket a request arrived on. */
+export type HttpPeerResolver = (req: Request) => { address: string; port: number } | null;
+
 const httpEndpointTypes = new Set<EndpointType>(["query", "mutation", "prompt"]);
 
 interface WebSocketRequest {
@@ -203,6 +206,16 @@ export class SignalContext<
    * hold for the life of the process. Building both per request cost an instance, a handler and a closure on every
    * call for every registered middleware — and `Logging` is registered by default.
    */
+  static #httpPeer: HttpPeerResolver | null = null;
+  /**
+   * Lets the http branch of `getClientIp` reach the socket the way the websocket branch already reaches
+   * `ws.remoteAddress`. Registered by whichever `Bun.serve` is listening, because only the server can answer
+   * `requestIP`. Behind the federation gateway this never fires — the gateway always writes `x-real-ip` —
+   * so it is the answer for a process nothing is proxying.
+   */
+  static setHttpPeerResolver(resolve: HttpPeerResolver | null) {
+    SignalContext.#httpPeer = resolve;
+  }
   static #middlewareHandlers = new WeakMap<MiddlewareCls, WeakMap<object, Promise<MiddlewareHandler>>>();
   static #getMiddlewareHandler(MiddlewareCls: MiddlewareCls, env: BackendEnv): Promise<MiddlewareHandler> {
     const byEnv =
@@ -440,14 +453,23 @@ export class SignalContext<
    * because a loopback-looking address for an unknown caller is the failure this replaced.
    */
   getClientIp(): string | null {
-    if (this.transport === "http") return clientAddressFromHeaders(this.getHttpContext().req.headers);
+    if (this.transport === "http") {
+      const { req } = this.getHttpContext();
+      const forwarded = clientAddressFromHeaders(req.headers);
+      if (forwarded) return forwarded;
+      const peer = SignalContext.#httpPeer?.(req);
+      return peer ? normalizeIpAddress(peer.address) : null;
+    }
     const { ws } = this.getWebSocketContext<{ headers?: Headers }>();
     const forwarded = ws.data.headers ? clientAddressFromHeaders(ws.data.headers) : null;
     return forwarded ?? (ws.remoteAddress ? normalizeIpAddress(ws.remoteAddress) : null);
   }
   /** The caller's source port as the nearest proxy recorded it, else this socket's own. */
   getClientPort(): number | null {
-    if (this.transport === "http") return clientPortFromHeaders(this.getHttpContext().req.headers);
+    if (this.transport === "http") {
+      const { req } = this.getHttpContext();
+      return clientPortFromHeaders(req.headers) ?? SignalContext.#httpPeer?.(req)?.port ?? null;
+    }
     const { ws } = this.getWebSocketContext<{ headers?: Headers }>();
     return (ws.data.headers ? clientPortFromHeaders(ws.data.headers) : null) ?? null;
   }

package/types/index.d.ts

@@ -2,19 +2,36 @@ import type { AkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 export declare const archs: readonly ["amd64", "arm64"];
 export type Arch = (typeof archs)[number];
-export interface DockerConfig {
-    content: string;
+/** One image step. The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
+export type DockerRun = string | {
+    [key in Arch]?: string;
+};
+/** The pieces Akan assembles a Dockerfile from. */
+export interface DockerImageConfig {
     image: string | {
         [key in Arch]?: string;
     };
-    preRuns: (string | {
-        [key in Arch]?: string;
-    })[];
-    postRuns: (string | {
-        [key in Arch]?: string;
-    })[];
+    /** Runs before `bun install`, so a system package a native dependency needs is there for the install. */
+    preRuns: DockerRun[];
+    /** Runs after `bun install`, before the app files are copied. */
+    postRuns: DockerRun[];
     command: string[];
 }
+/**
+ * A whole Dockerfile as a string, or the parts Akan assembles one from. The string form is taken verbatim —
+ * nothing is merged into it, including the steps a lib contributes through its own `docker`.
+ */
+export type DockerConfig = string | DockerImageConfig;
+/** What an `akan.config.ts` may write for `docker`: a whole Dockerfile, or any subset of the parts. */
+export type DockerOption = string | Partial<DockerImageConfig>;
+/**
+ * A lib's contribution to the image of every app that mounts it — a lib never picks the base image or the
+ * command, only the steps its own runtime needs.
+ */
+export interface LibDockerConfig {
+    preRuns: DockerRun[];
+    postRuns: DockerRun[];
+}
 export interface AkanRouteDomains {
     main?: string[];
     develop?: string[];
@@ -198,6 +215,8 @@ export interface AppConfigResult {
 }
 export interface LibConfigResult {
     externalLibs: string[];
+    /** Image steps every app that mounts this lib inherits, unless that app declares a whole Dockerfile. */
+    docker: LibDockerConfig;
 }
 export type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends unknown[] ? T[P] : T[P] extends object ? DeepPartial<T[P]> : T[P];
@@ -210,7 +229,8 @@ export interface LibConfigContext {
     readonly name: string;
     readonly type: "lib";
 }
-export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "web"> & {
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+    docker?: DockerOption;
     web?: AkanWebOption;
     plugins?: AkanPlugin[];
 };

package/types/server/akanApp.d.ts

@@ -12,6 +12,13 @@ export interface AkanAppOptions {
      * module. Handed down as `AKAN_MODULES`, since each replica builds its own container.
      */
     modules?: string[];
+    /**
+     * Run the one replica in this process instead of spawning it — see `#startSolo`. Defaults on for a single
+     * traffic replica the environment configured, and off whenever `replica` is passed here, because code that
+     * states a topology is asking for the gateway that serves it. `AKAN_SOLO=false` turns it off; like
+     * `AKAN_SSR`, the env can only narrow, so it cannot force a gateway's replicas into one process.
+     */
+    solo?: boolean;
 }
 /** Gateway/orchestrator that starts Akan child servers and proxies HTTP/WebSocket traffic. */
 export declare class AkanApp {

package/types/server/lifecycle/runtimeDir.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Where a replica keeps its child sockets and rotating logs. Both the gateway and a solo server resolve it,
+ * and they must land on the same directory: switching between the two modes must not move the log file.
+ */
+export declare const resolveRuntimeDir: (runtimeDir?: string) => string;

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

@@ -0,0 +1,15 @@
+import type { AkanChildRole, AkanMetricsReport } from "akanjs/service";
+import type { HttpRoutes } from "../types.d.ts";
+export interface SoloAppStatus {
+    role: AkanChildRole;
+    running: boolean;
+    status: string;
+    port: number | null;
+    metrics: AkanMetricsReport;
+}
+/**
+ * The gateway's `/_akan/app/*` surface, answered by a process nothing is proxying. The payload keeps the
+ * gateway's own shape — a `children` array with this process as its only entry — so a probe, a k8s check and
+ * `akan` tooling read one contract whether or not a gateway is in front.
+ */
+export declare const createSoloAppRoutes: (read: () => SoloAppStatus) => HttpRoutes;

package/types/signal/signalContext.d.ts

@@ -5,6 +5,11 @@ import type { Internal, InternalInfo, MiddlewareCls } from ".";
 import type { EndpointInfo } from "./endpointInfo.d.ts";
 import { SignalTrace } from "./trace.d.ts";
 export type SignalTransportType = "http" | "websocket";
+/** What `Bun.Server.requestIP` reports for the socket a request arrived on. */
+export type HttpPeerResolver = (req: Request) => {
+    address: string;
+    port: number;
+} | null;
 interface WebSocketRequest {
     ws: Bun.ServerWebSocket<unknown>;
     data: unknown[];
@@ -53,6 +58,13 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
      * closed with no arguments, so evaluating one here would delete every legitimate entry from the listing.
      */
     canListForAccount(): Promise<boolean>;
+    /**
+     * Lets the http branch of `getClientIp` reach the socket the way the websocket branch already reaches
+     * `ws.remoteAddress`. Registered by whichever `Bun.serve` is listening, because only the server can answer
+     * `requestIP`. Behind the federation gateway this never fires — the gateway always writes `x-real-ip` —
+     * so it is the answer for a process nothing is proxying.
+     */
+    static setHttpPeerResolver(resolve: HttpPeerResolver | null): void;
     exec(): Promise<Response | undefined>;
     static try(endpoint: Adaptor, endpointInfo: EndpointInfo, key: string, fn: () => Promise<Response | undefined>): Promise<Response | undefined>;
     static resolveReturn(value: unknown, { signalContext, returnRef, arrDepth, registry, live, }: {

package/types/ui/Agent/Context.d.ts

@@ -7,7 +7,7 @@ interface ContextProps {
  *
  * The tool list leads, by name only: a zone publishes its tools scope-prefixed, and instructions that name a tool
  * without its prefix name a tool that does not exist. That is invisible in the source of either file and obvious
- * here.
+ * here. Renders nothing on `AKAN_PUBLIC_ENV=main`.
  */
-export default function Context({ className }: ContextProps): import("react/jsx-runtime").JSX.Element;
+export default function Context({ className }: ContextProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/types/ui/Agent/Dock.d.ts

@@ -12,6 +12,6 @@ export interface DockProps {
  * The in-page surface of the agent: what this screen declared an agent may do, what it may read, and what it has
  * done. Tools come from the surface rather than from the store, because a tool exists only where a component
  * declared one — the dock is the way to see that this screen published what its author thought it did, which is
- * the one thing no amount of reading the source answers.
+ * the one thing no amount of reading the source answers. Renders nothing on `AKAN_PUBLIC_ENV=main`.
  */
-export declare const Dock: ({ className, bridge, surface, open }: DockProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Dock: ({ className, bridge, surface, open }: DockProps) => import("react/jsx-runtime").JSX.Element | null;

package/types/ui/Agent/index.d.ts

@@ -6,7 +6,7 @@ import Transcript from "./Transcript.d.ts";
 export declare const Agent: {
     Chat: import("react").ComponentType<import("./Chat.d.ts").ChatProps>;
     Context: typeof Context;
-    Dock: ({ className, bridge, surface, open }: import("./Dock.d.ts").DockProps) => import("react/jsx-runtime").JSX.Element;
+    Dock: ({ className, bridge, surface, open }: import("./Dock.d.ts").DockProps) => import("react/jsx-runtime").JSX.Element | null;
     Guide: ({ instructions }: import("./Guide.d.ts").GuideProps) => null;
     History: ({ load, save, clear, onCompact }: import("./History.d.ts").HistoryProps) => null;
     Scope: ({ id, label, kind, children }: import("../../vendor/use-agentic.d.ts").AgentScopeProps) => import("react/jsx-runtime").JSX.Element;

package/ui/Agent/Context.tsx

@@ -14,10 +14,12 @@ interface ContextProps {
  *
  * The tool list leads, by name only: a zone publishes its tools scope-prefixed, and instructions that name a tool
  * without its prefix name a tool that does not exist. That is invisible in the source of either file and obvious
- * here.
+ * here. Renders nothing on `AKAN_PUBLIC_ENV=main`.
  */
 export default function Context({ className }: ContextProps) {
   const [shown, setShown] = useState("");
+  
+  if (process.env.AKAN_PUBLIC_ENV === "main" || process.env.NODE_ENV === "develop") return null;
   const assemble = () => {
     try {
       const { guides, tools } = AgenticSurface.shared.snapshot();

package/ui/Agent/Dock.tsx

@@ -22,7 +22,7 @@ export interface DockProps {
  * The in-page surface of the agent: what this screen declared an agent may do, what it may read, and what it has
  * done. Tools come from the surface rather than from the store, because a tool exists only where a component
  * declared one — the dock is the way to see that this screen published what its author thought it did, which is
- * the one thing no amount of reading the source answers.
+ * the one thing no amount of reading the source answers. Renders nothing on `AKAN_PUBLIC_ENV=main`.
  */
 export const Dock = ({ className, bridge, surface, open = false }: DockProps) => {
   const held = useRef<{ bridge: AgentBridge; surface: AgenticSurface } | null>(null);
@@ -37,6 +37,8 @@ export const Dock = ({ className, bridge, surface, open = false }: DockProps) =>
     if (liveA !== liveB) return liveA ? -1 : 1;
     return a < b ? -1 : 1;
   });
+  
+  if (process.env.AKAN_PUBLIC_ENV === "main") return null;
   return (
     <aside
       data-agent-ui=""