akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/common/Logger.ts

@@ -81,28 +81,18 @@ const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`,
 
 const redactedAttrKey = /password|passwd|token|jwt|authorization|cookie|secret|api[-_]?key|private[-_]?key/i;
 
-/**
- * `process.env?.X` guards only `env` being absent, never `process` itself — an undeclared `process` is a
- * ReferenceError, and at module scope that takes the whole client bundle with it. This is the most widely
- * imported file in `common/`, and the unguarded form works today only because the browser build ships a shim.
- */
 const envValue = (key: string): string | undefined => (typeof process === "undefined" ? undefined : process.env?.[key]);
 
-/** Log-level aware logger used by Akan runtime, CLI, and application services. */
 export class Logger {
-  /** `AKAN_LOG_STDOUT_LEVEL` names what the container's stdout carries; without it the console level is that. */
   static level: LogLevel = Logger.#levelFromEnv(
     envValue("AKAN_LOG_STDOUT_LEVEL"),
     Logger.#levelFromEnv(envValue("AKAN_PUBLIC_LOG_LEVEL"), "info"),
   );
   static fileLevel: LogLevel = Logger.#levelFromEnv(envValue("AKAN_LOG_FILE_LEVEL"), "trace");
   static format: LogFormat = Logger.#formatFromEnv(envValue("AKAN_LOG_FORMAT"));
-  /** Which process this is (`gateway`, `all`, `batch`, `rsc-worker`); the owner sets it at boot. */
+  /** `gateway`, `all`, `batch` or `rsc-worker`; the owner sets it at boot. */
   static role: string | null = envValue("SERVER_MODE") ?? null;
-  /**
-   * Whether this process writes its own lines to the terminal. Off in every server process of an ndjson
-   * deployment: the hub owner writes the one JSON stream, and a text line from anyone would corrupt it.
-   */
+  /** Off in every server process of an ndjson deployment but the hub owner, whose JSON stream a text line corrupts. */
   static consoleOutput = true;
   /** Set by the trace layer when a flight recorder or a per-request debug floor can be active. */
   static contextGate = false;
@@ -136,14 +126,12 @@ export class Logger {
   static get isNdjson() {
     return Logger.format !== "text";
   }
-  /** For hot-path callers that would otherwise build a message the level is about to discard. */
   static shouldLog(logLevel: LogLevelInput) {
     return Logger.#shouldLog(Logger.normalizeLevel(logLevel));
   }
   static normalizeLevel(level: LogLevelInput): LogLevel {
     return level === "log" ? "info" : level;
   }
-  /** The lowest named level whose severity is at least `sev`. */
   static levelAtOrAbove(sev: number): LogLevel {
     return logLevels.find((level) => logSeverity[level] >= sev) ?? "error";
   }
@@ -151,16 +139,15 @@ export class Logger {
     const level = record.level;
     if (level === null) return record.message;
     const replicaMsg = record.replicaIdx === null ? "" : `#${record.replicaIdx} `;
-    const processMsg = Logger.#colorize(`[${record.name}] ${replicaMsg}${record.pid ?? "window"} -`, level);
+    const processMsg = colorizeMap[level](`[${record.name}] ${replicaMsg}${record.pid ?? "window"} -`);
     const timestampMsg = dayjs(record.at).format("MM/DD/YYYY, HH:mm:ss A");
-    const logLevelMsg = Logger.#colorize(level.toUpperCase().padStart(7, " "), level);
+    const logLevelMsg = colorizeMap[level](level.toUpperCase().padStart(7, " "));
     const contextMsg = record.context ? clc.yellow(`[${record.context}] `) : "";
-    const contentMsg = Logger.#colorize(record.message, level);
+    const contentMsg = colorizeMap[level](record.message);
     const attrsMsg = record.attrs ? Logger.formatAttrs(record.attrs) : "";
     const timeDiffMsg = clc.yellow(`+${record.elapsedMs}ms`);
     return `${processMsg} ${timestampMsg} ${logLevelMsg} ${contextMsg} ${contentMsg}${attrsMsg ? ` ${attrsMsg}` : ""} ${timeDiffMsg}\n`;
   }
-  /** `key=value` pairs; a string with whitespace is quoted so the line stays splittable. */
   static formatAttrs(attrs: LogAttrs): string {
     return Object.entries(attrs)
       .map(
@@ -169,10 +156,7 @@ export class Logger {
       )
       .join(" ");
   }
-  /**
-   * A record somebody asked for below the level — a failed call's flight recorder, a request carrying
-   * `x-akan-debug` — passes every floor between here and the reader; the floors exist to drop what nobody asked for.
-   */
+  /** A flight-recorder or `x-akan-debug` record passes every floor between here and the reader. */
   static isPromoted(record: LogRecord) {
     return record.attrs?.flight === true || record.attrs?.debug === true;
   }
@@ -185,15 +169,10 @@ export class Logger {
     }
     return redacted ?? attrs;
   }
-  /** A structured record from a caller that has more than a sentence to say — the canonical request line. */
   static emit({ level, name, message, context = "", attrs }: LoggerEmitInput) {
     if (Logger.#shouldLog(level)) Logger.#write(name, message, context, level, attrs);
   }
-  /**
-   * Writes records that were captured below the gate and are now promoted — a failed request's flight
-   * recorder. They bypass the console level, since not showing them is what the recorder was for, and reach
-   * sinks under their own floors; each is marked `flight` so a reader knows why a trace line appears at info.
-   */
+  /** Writes a failed request's flight-recorder records past the console level, each marked `flight`. */
   static replay(records: LogRecord[], { evicted = 0 }: { evicted?: number } = {}) {
     records.forEach((record, idx) => {
       const attrs: LogAttrs = { ...record.attrs, flight: true };
@@ -231,7 +210,7 @@ export class Logger {
     if (Logger.#shouldLog("error")) Logger.#write(name, msg, context, "error");
   }
   raw(msg: string, method?: "console" | "process") {
-    Logger.rawLog(msg, method);
+    Logger.raw(msg, method);
   }
   rawLog(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
@@ -270,9 +249,6 @@ export class Logger {
     for (const minSev of Logger.#sinks.values()) floor = Math.min(floor, minSev ?? Logger.#fileSev);
     Logger.#sinkFloorSev = floor;
   }
-  static #colorize(msg: string, logLevel: LogLevel) {
-    return colorizeMap[logLevel](msg);
-  }
   static stripAnsi(msg: string) {
     return msg.replace(ansiPattern, "");
   }
@@ -286,7 +262,6 @@ export class Logger {
   static #shouldEmitSink(logLevel: LogLevel) {
     return logSeverity[logLevel] >= Logger.#sinkFloorSev;
   }
-  /** The lowest severity the ambient request wants captured or shown, or +∞ outside one. */
   static #contextFloor(ctx: LogContextSnapshot | undefined) {
     if (!ctx) return Number.POSITIVE_INFINITY;
     return Math.min(ctx.flight?.minSev ?? Number.POSITIVE_INFINITY, ctx.debugSev ?? Number.POSITIVE_INFINITY);
@@ -364,7 +339,7 @@ export class Logger {
     const ctx = readLogContext();
     const sev = logSeverity[logLevel];
     const debug = ctx?.debugSev !== undefined && ctx.debugSev !== null && sev >= ctx.debugSev;
-
+    
     const promoted = debug && sev < Logger.#consoleSev;
     const record = Logger.#buildRecord(
       name,

package/common/TrustedProxy.ts

@@ -1,18 +1,5 @@
-import { normalizeIpAddress } from "./clientAddress";
+import { clientAddressFromHeaders, normalizeIpAddress } from "./clientAddress";
 
-/**
- * Whether the hop that connected is allowed to name the caller.
- *
- * `x-real-ip` and `x-forwarded-for` are just request headers: anyone can send them. They are the truth only when
- * the peer that sent them is a proxy we put there — otherwise a client forges its own address and walks past
- * every `.with(Ip)` guard, rate limit and audit line at once.
- *
- * The default trusts a private, loopback or link-local peer and nothing else, because that is exactly the shape
- * of a proxy on the same network: an ingress, a service mesh, the dev machine. A gateway reachable from the
- * internet sees a public peer, so a header from there is dropped rather than believed. `AKAN_TRUSTED_PROXIES`
- * takes a comma-separated CIDR list for the case the proxy is not private — and `*` for "the deployment
- * guarantees nothing untrusted can reach this port", which is the old behaviour, written down.
- */
 export class TrustedProxy {
   static #cidrs: { bytes: Uint8Array; bits: number }[] | null = null;
   static #trustAll: boolean | null = null;
@@ -48,31 +35,16 @@ export class TrustedProxy {
     return (TrustedProxy.#cidrs ?? []).some((cidr) => TrustedProxy.#inRange(bytes, cidr));
   }
 
-  /**
-   * The caller's address as recorded by a proxy, but only when the peer is one. Falls back to the peer itself,
-   * which is the right answer for a process nothing is proxying, and `null` when there is no peer either.
-   *
-   * `null` and `undefined` mean different things here. `null` is what `Server.requestIP` answers for a socket
-   * that has no address — a unix socket, which is how a gateway reaches its children — and only a process on
-   * this machine can open one, so the headers it wrote are a local proxy's and are believed. `undefined` is
-   * "nobody asked": no resolver was registered, and a header from an unknown peer is a header the client wrote.
-   */
+  /** A `null` peer is a unix socket, which only a local proxy opens, so its headers count; `undefined` is not. */
   static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null {
     if (peerAddress === null || TrustedProxy.isTrusted(peerAddress)) {
-      const realIp = headers.get("x-real-ip")?.trim();
-      if (realIp) return normalizeIpAddress(realIp);
-      const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
-      if (forwarded) return normalizeIpAddress(forwarded);
+      const recorded = clientAddressFromHeaders(headers);
+      if (recorded) return recorded;
     }
     return peerAddress ? normalizeIpAddress(peerAddress) : null;
   }
 
-  /**
-   * Whether an address is one no public name should resolve to: the local ranges `isTrusted` reads, plus the
-   * unspecified address, the carrier-grade NAT block `100.64/10`, multicast and the reserved top of IPv4. Used
-   * to refuse a fetch whose destination a caller chose by name, so it judges the address alone and never the
-   * configured proxy list — a trusted proxy is still not somewhere to send an outbound request.
-   */
+  /** For refusing an outbound fetch to a caller-chosen name: judges the address alone, never the proxy list. */
   static isPrivateAddress(address: string): boolean {
     const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
     if (!bytes) return true;
@@ -134,7 +106,7 @@ export class TrustedProxy {
   }
 
   static #ipv6ToBytes(address: string): Uint8Array | null {
-
+    
     const bare = address.split("%")[0] ?? "";
     const halves = bare.split("::");
     if (halves.length > 2) return null;

package/common/applyMixins.ts

@@ -1,7 +1,18 @@
-import { getAllPropertyDescriptors } from "./getAllPropertyDescriptors";
-
 type Cls<T = unknown> = new (...args: never[]) => T;
 
+export const getAllPropertyDescriptors = (objRef: Cls): { [key: string]: PropertyDescriptor } => {
+  const descriptors: Record<string, PropertyDescriptor> = {};
+  let current = objRef.prototype as object | null;
+  while (current) {
+    Object.getOwnPropertyNames(current).forEach((name) => {
+      const descriptor = Object.getOwnPropertyDescriptor(current, name);
+      if (descriptor) descriptors[name] ??= descriptor;
+    });
+    current = Object.getPrototypeOf(current) as Cls | object;
+  }
+  return descriptors;
+};
+
 export const applyMixins = (derivedCtor: Cls, constructors: (Cls | undefined)[], avoidKeys?: Set<string>) => {
   constructors.forEach((baseCtor) => {
     if (!baseCtor) return;

package/common/authToken.ts

@@ -4,11 +4,6 @@ import { decodeJwtPayload } from "./jwtDecode";
 /** The pre-scoping key. Read as a fallback, never written; drop it once deployments have rotated past it. */
 export const legacyAuthTokenKey = "jwt";
 
-/**
- * Cookies carry no port (RFC 6265), so every app served from one host shares a jar — which on localhost is
- * every app in the workspace at once. Under a global `jwt` key each signin overwrites the neighbour's
- * session, and the JWT's own `appName` check only turns the stolen cookie into a failing credential.
- */
 export const authTokenKey = (): string => `${legacyAuthTokenKey}:${getEnv().appName}`;
 
 /** Matches both spellings so a signout can sweep a jar written before and after the key was scoped. */
@@ -17,11 +12,9 @@ export const isAuthTokenKey = (key: string): boolean =>
 
 const authCookiePattern = new RegExp(`(?:^|;\\s*)${legacyAuthTokenKey}(?::[^=\\s;]+)?=`);
 
-/** Whether a raw `cookie` header carries an auth token under either spelling. */
 export const cookieHeaderHasAuthToken = (cookieHeader: string | null | undefined): boolean =>
   !!cookieHeader && authCookiePattern.test(cookieHeader);
 
-/** Whether a token was minted for this app and environment — the same pair the server's account check makes. */
 export const isOwnAuthToken = (jwt: string): boolean => {
   const { appName, environment } = getEnv();
   try {
@@ -32,10 +25,6 @@ export const isOwnAuthToken = (jwt: string): boolean => {
   }
 };
 
-/**
- * Reads the app-scoped token, falling back to a leftover global one only when its payload names this app —
- * a neighbour's token would decode fine here and fail every guard, so adopting it is worse than none.
- */
 export const readAuthToken = (read: (key: string) => string | null | undefined): string | undefined => {
   const scoped = read(authTokenKey());
   if (scoped) return scoped;

package/common/capitalize.ts

@@ -1,4 +1,3 @@
-/** Uppercases only the first character of a string. */
-export const capitalize = (str: string) => {
-  return str.charAt(0).toUpperCase() + str.slice(1);
-};
+export const capitalize = (str: string) => str.charAt(0).toUpperCase() + str.slice(1);
+
+export const lowerlize = (str: string) => str.charAt(0).toLowerCase() + str.slice(1);

package/common/clamp.ts

@@ -1,2 +1 @@
-/** Constrains a value to `[min, max]`. */
 export const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);

package/common/clientAddress.ts

@@ -1,4 +1,3 @@
-/** Headers a proxy hop writes so the next hop can still name the original caller. */
 export const forwardedHeaders = [
   "x-real-ip",
   "x-forwarded-for",
@@ -7,25 +6,13 @@ export const forwardedHeaders = [
   "x-forwarded-proto",
 ] as const;
 
-/**
- * An IPv4 client reaching a dual-stack listener is reported as `::ffff:203.0.113.10`. That form is not a
- * valid destination for a `udp4` socket and does not compare equal to the same address written plainly, so
- * it is unwrapped at every boundary rather than at each call site that happens to remember.
- */
 export const normalizeIpAddress = (address: string): string => {
   const trimmed = address.trim();
   const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(trimmed);
   return mapped?.[1] ?? trimmed;
 };
 
-/**
- * The caller's address as the nearest proxy recorded it. `x-real-ip` is one hop's word for who the client is
- * and wins; `x-forwarded-for` is a chain appended left to right, so its *first* entry is the original client
- * and everything after it is a proxy.
- *
- * Returns `null` rather than a placeholder. A socket peer behind a proxy is the proxy, so `127.0.0.1` here
- * would be indistinguishable from a genuinely local caller — and that is the failure this exists to prevent.
- */
+/** `x-real-ip`, else the first `x-forwarded-for` entry; `null`, never a placeholder, when neither is set. */
 export const clientAddressFromHeaders = (headers: Headers): string | null => {
   const realIp = headers.get("x-real-ip")?.trim();
   if (realIp) return normalizeIpAddress(realIp);
@@ -33,7 +20,6 @@ export const clientAddressFromHeaders = (headers: Headers): string | null => {
   return forwarded ? normalizeIpAddress(forwarded) : null;
 };
 
-/** The client port the nearest proxy recorded, for correlating a connection with a peer's own logs. */
 export const clientPortFromHeaders = (headers: Headers): number | null => {
   const port = Number(headers.get("x-forwarded-port"));
   return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;

package/common/codeAgentProfile.ts

@@ -0,0 +1,181 @@
+
+
+export type CodeAgentBuiltinTool = "read" | "write" | "edit" | "ls" | "grep" | "find" | "bash";
+
+/** `never` trusts the environment, `all` trusts nothing. */
+export type CodeAgentApprovalPolicy = "never" | "writes" | "commands" | "all";
+
+/** `await` holds the turn open; `suspend` ends it and the host reopens one carrying the answer (survives a restart). */
+export type CodeAgentInteractionMode = "await" | "suspend";
+
+export interface CodeAgentModelInfo {
+  id: string;
+  name: string;
+  contextWindow?: number;
+  /** The model the session is running on. */
+  current: boolean;
+}
+
+export interface CodeAgentProviderInfo {
+  id: string;
+  name: string;
+  authorized: boolean;
+  models: CodeAgentModelInfo[];
+}
+
+export interface CodeAgentMcpServerRef {
+  name: string;
+  transport: "stdio" | "http";
+  /** stdio: the executable and its argv. http: the endpoint. */
+  command?: string;
+  args?: string[];
+  url?: string;
+  env?: Record<string, string>;
+  headers?: Record<string, string>;
+  /** For a server that answers `401` and whose OAuth client or scopes cannot be discovered. */
+  oauth?: { clientId?: string; clientSecret?: string; scope?: string };
+}
+
+/** `required` is not a failure: the server answered correctly and said who may talk to it. */
+export type CodeAgentMcpAuthState = "none" | "authorized" | "required";
+
+/** One declared MCP server; one that was never reachable is listed too, with its `error`. */
+export interface CodeAgentMcpStatus {
+  name: string;
+  transport: "stdio" | "http";
+  /** The command line or the url. */
+  target: string;
+  /** Published tool names, already prefixed with the server the way the model sees them. */
+  tools: string[];
+  /** Why it published none, when it published none. */
+  error?: string;
+  auth?: CodeAgentMcpAuthState;
+}
+
+export interface CodeAgentSubagentBudget {
+  maxDepth: number;
+  /** Subagents a whole tree may run at once; past it the `task` tool refuses instead of queueing. */
+  maxConcurrent: number;
+  /** Tokens a whole subagent tree may spend before the `task` tool refuses to open another. */
+  budget: number;
+}
+
+export interface CodeAgentProfile {
+  name: string;
+  tools: {
+    builtin: CodeAgentBuiltinTool[];
+    /** Workflow, context and self-verification tools built on devkit. */
+    akan: boolean;
+    /** `"off"` reaches no server; an array discovers `.akan/code/mcp.json` plus the servers it names. */
+    mcp: "off" | CodeAgentMcpServerRef[];
+    subagent: false | CodeAgentSubagentBudget;
+    web: { fetch: boolean; search: boolean };
+  };
+  approval: CodeAgentApprovalPolicy;
+  paths: { root: string; allow?: string[]; deny?: string[] };
+  session: { store: "file" | "memory" | "remote"; crossSession: boolean };
+  interaction: { question: CodeAgentInteractionMode; approval: CodeAgentInteractionMode };
+  network: { allowHosts?: string[]; proxyBaseUrl?: string };
+  ui: { canPrompt: boolean };
+  limits: {
+    turnMs: number;
+    toolOutputBytes: number;
+    contextTokens: number;
+    /** How many times one turn-end plugin may reopen a turn with the same finding before it gives up. */
+    feedback: number;
+  };
+  context: {
+    /** Whether the repo's `AGENTS.md` is loaded. */
+    projectFiles: boolean;
+    /** The akan skill set: only each skill's one-line description sits in the window until a task matches. */
+    skills: boolean;
+  };
+}
+
+const allBuiltins: CodeAgentBuiltinTool[] = ["read", "write", "edit", "ls", "grep", "find", "bash"];
+export const codeAgentReadOnlyBuiltins: CodeAgentBuiltinTool[] = ["read", "ls", "grep", "find"];
+
+const baseLimits = { turnMs: 900_000, toolOutputBytes: 200_000, contextTokens: 0, feedback: 2 };
+
+/** Paths no profile may read, whatever its allowlist says. */
+export const codeAgentDeniedPaths = ["**/.env", "**/.env.*", "**/secrets/**", "**/*.pem", "**/*.key"];
+
+export const codeAgentPresets = {
+  local: (root: string): CodeAgentProfile => ({
+    name: "local",
+    tools: {
+      builtin: allBuiltins,
+      akan: true,
+      mcp: [],
+      subagent: { maxDepth: 2, maxConcurrent: 3, budget: 200_000 },
+      web: { fetch: true, search: true },
+    },
+    approval: "never",
+    paths: { root, deny: codeAgentDeniedPaths },
+    session: { store: "file", crossSession: true },
+    interaction: { question: "await", approval: "await" },
+    network: {},
+    ui: { canPrompt: true },
+    limits: baseLimits,
+    context: { projectFiles: true, skills: true },
+  }),
+  
+  pod: (root: string): CodeAgentProfile => ({
+    name: "pod",
+    tools: {
+      builtin: allBuiltins,
+      akan: true,
+      mcp: "off",
+      subagent: { maxDepth: 2, maxConcurrent: 3, budget: 200_000 },
+      web: { fetch: true, search: true },
+    },
+    approval: "never",
+    paths: { root, deny: codeAgentDeniedPaths },
+    session: { store: "remote", crossSession: true },
+    interaction: { question: "suspend", approval: "suspend" },
+    network: {},
+    ui: { canPrompt: false },
+    limits: baseLimits,
+    context: { projectFiles: true, skills: true },
+  }),
+  review: (root: string): CodeAgentProfile => ({
+    name: "review",
+    tools: {
+      builtin: codeAgentReadOnlyBuiltins,
+      akan: true,
+      mcp: "off",
+      subagent: { maxDepth: 1, maxConcurrent: 4, budget: 120_000 },
+      web: { fetch: false, search: false },
+    },
+    approval: "never",
+    paths: { root, deny: codeAgentDeniedPaths },
+    session: { store: "memory", crossSession: false },
+    interaction: { question: "await", approval: "await" },
+    network: {},
+    ui: { canPrompt: true },
+    limits: baseLimits,
+    context: { projectFiles: false, skills: true },
+  }),
+  web: (root: string): CodeAgentProfile => ({
+    name: "web",
+    tools: {
+      builtin: allBuiltins,
+      akan: true,
+      mcp: [],
+      subagent: { maxDepth: 2, maxConcurrent: 3, budget: 200_000 },
+      web: { fetch: true, search: true },
+    },
+    approval: "writes",
+    paths: { root, deny: codeAgentDeniedPaths },
+    session: { store: "file", crossSession: true },
+    interaction: { question: "suspend", approval: "suspend" },
+    network: {},
+    ui: { canPrompt: true },
+    limits: baseLimits,
+    context: { projectFiles: true, skills: true },
+  }),
+} as const;
+
+export type CodeAgentPresetName = keyof typeof codeAgentPresets;
+
+export const isCodeAgentPresetName = (name: string): name is CodeAgentPresetName => name in codeAgentPresets;