@akanjs/devkit 3.1.0-rc.8 → 3.1.0

package/applicationBuildRunner.ts

@@ -18,6 +18,7 @@ import { Spinner } from "./spinner";
 import { createServerEnvPlugin } from "./transforms/serverEnvPlugin";
 import { ServerEnvProfile } from "./transforms/serverEnvProfile";
 import { ProjectTypecheck } from "./typecheck/projectTypecheck";
+import type { BaseDevEnv } from "./types";
 
 export interface TypecheckOptions {
   clean?: boolean;
@@ -97,14 +98,34 @@ export class ApplicationBuildRunner {
     return path.join(this.#app.cwdPath, "env");
   }
 
+  //? Bundles bake AKAN_PUBLIC_* from process.env, where the shell outranks the .env that the server env and the
+  //? Dockerfile read: a page built otherwise drops the image's tokens as foreign or dials another serve domain.
+  #pinImageEnv(baseDevEnv: BaseDevEnv, environment: string) {
+    const imageEnv = {
+      AKAN_PUBLIC_ENV: environment,
+      AKAN_PUBLIC_REPO_NAME: baseDevEnv.repoName,
+      AKAN_PUBLIC_SERVE_DOMAIN: baseDevEnv.serveDomain,
+    };
+    const outranked = Object.entries(imageEnv).filter(([key, value]) => {
+      const given = process.env[key];
+      return !!given && given !== value && !(key === "AKAN_PUBLIC_ENV" && this.#environment);
+    });
+    if (outranked.length)
+      this.#app.logger.warn(
+        `The workspace .env outranks this process's environment: the bundles and the image take ${outranked
+          .map(([key, value]) => `${key}=${value} (not ${process.env[key]})`)
+          .join(", ")}.`,
+      );
+    Object.assign(process.env, imageEnv);
+  }
+
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
     // serial build is needed because of Bun.build is unstable for parallel build
     this.#spinner = spinner;
     const { web, assets, baseDevEnv } = await this.#app.getConfig();
     const environment = this.#environment ?? baseDevEnv.env;
     WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, "akan build");
-    //? Bundles bake AKAN_PUBLIC_ENV from process.env, where the shell outranks the .env that picked the server env.
-    process.env.AKAN_PUBLIC_ENV = environment;
+    this.#pinImageEnv(baseDevEnv, environment);
     //? Before any phase: a profile that would ship a secret stops the build, not the image after it.
     if (this.#profile)
       await ServerEnvProfile.assertShippable({ envDir: this.#envDir, environment, profile: this.#profile });
@@ -366,9 +387,11 @@ void run().catch((error) => {
 
   //? Opt-in and outside `dist/`: a metafile is the size of the module graph, and `dist/` is what the image copies.
   async #buildOrThrow(label: string, config: Bun.BuildConfig): Promise<Bun.BuildOutput> {
-    const metafileDir = process.env.AKAN_BUILD_METAFILE
-      ? path.join(this.#app.workspace.workspaceRoot, "local", "build-meta", path.basename(this.#app.cwdPath))
-      : null;
+    const flag = process.env.AKAN_BUILD_METAFILE;
+    const metafileDir =
+      flag && flag !== "0" && flag !== "false"
+        ? path.join(this.#app.workspace.workspaceRoot, "local", "build-meta", path.basename(this.#app.cwdPath))
+        : null;
     const result = await Bun.build(metafileDir ? { ...config, metafile: true } : config);
     if (!result.success) throw new AggregateError(result.logs, `[${label}] Bun.build failed`);
     if (metafileDir && result.metafile) {

package/artifact/implicitRootLayout.test.ts

@@ -36,7 +36,9 @@ describe("resolveSsrPageEntries", () => {
     const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
     // Both user modules go through the route resolver, so a `rootLayout()` chain and the legacy exports read alike.
     expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
-    expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
+    expect(generatedSource).toContain(
+      'const inheritedLayout = assertGuardOnChain("page/_layout.tsx", resolveRouteModule(inheritedModule as never',
+    );
     expect(generatedSource).not.toContain("<System.Provider");
     expect(generatedSource).toContain("export async function generateHead(props: PageProps)");
     // The ancestor root is a level of the route tree, which merges its head; this boundary returns only its own.
@@ -48,6 +50,9 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;");
     // The ancestor root is its own level of the stack, so inheriting its loading would nest it inside itself.
     expect(generatedSource).toContain("export const Loading = userLayout.Loading;");
+    // Its guard runs from that level too, ahead of this one, and an MCP view takes its providers from there.
+    expect(generatedSource).toContain("export const guard = userLayout.guard;");
+    expect(generatedSource).not.toContain("McpAppRoot");
     expect(generatedSource).toContain(
       "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>",
     );
@@ -77,6 +82,11 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const viewport = userLayout.viewport ?? inheritedLayout.viewport;");
     expect(generatedSource).toContain("viewport={viewport}");
     expect(generatedSource).toContain("[inheritedLayout, userLayout].map((layout)");
+    expect(generatedSource).toContain(
+      "export const guard = RouteGuards.compose(inheritedLayout.guard, userLayout.guard);",
+    );
+    expect(generatedSource).toContain("export function McpAppRoot({ children, params, path }: McpAppRootProps) {");
+    expect(generatedSource).toContain("<System.App");
     expect(generatedSource).toContain('import { allDictionary } from "../dict/useDict.ts";');
     expect(generatedSource).toContain(
       'allDictionary={process.env.AKAN_PUBLIC_RENDER_ENV === "ssr" ? allDictionary : undefined}',

package/artifact/implicitRootLayout.ts

@@ -16,8 +16,11 @@ const IMPLICIT_DICT_DIR = path.join(".akan", "generated", "dict");
 const IMPLICIT_OVERRIDES_DIR = path.join(".akan", "generated", "overrides");
 const OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
 
+const posixRelative = (fromDir: string, toAbsPath: string) =>
+  path.relative(fromDir, toAbsPath).split(path.sep).join("/");
+
 const importSpecifier = (fromAbsPath: string, toAbsPath: string) => {
-  const rel = path.relative(path.dirname(fromAbsPath), toAbsPath).split(path.sep).join("/");
+  const rel = posixRelative(path.dirname(fromAbsPath), toAbsPath);
   return rel.startsWith(".") ? rel : `./${rel}`;
 };
 
@@ -162,14 +165,14 @@ async function writeGeneratedRootLayoutFile(opts: {
     ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
     : `import "@apps/${opts.appName}/client";\n`;
   //? resolveRouteModule reads a rootLayout() chain and the legacy named exports alike.
-  const inheritedLabel = inheritedSourceAbsPath ? path.relative(opts.appCwdPath, inheritedSourceAbsPath) : "";
+  const inheritedLabel = inheritedSourceAbsPath ? posixRelative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
-    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)}).module as LayoutModule;\n`
+    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = assertGuardOnChain(${JSON.stringify(inheritedLabel)}, resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)})).module as LayoutModule;\n`
     : "const inheritedLayout: LayoutModule = {};\n";
   const prefix = opts.boundary.segments.find((segment) => !/^\(.+\)$/.test(segment)) ?? null;
-  const userLabel = opts.boundary.sourceAbsPath ? path.relative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
+  const userLabel = opts.boundary.sourceAbsPath ? posixRelative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
   const userImport = sourceSpecifier
-    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)}).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
+    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = assertGuardOnChain(${JSON.stringify(userLabel)}, resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)})).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
     : "const UserLayout = ({ children }: LayoutProps) => children;\nconst userLayout: LayoutModule = {};\n";
   const isAsyncUserLayout = opts.boundary.sourceAbsPath
     ? await AsyncDefaultExportDetector.detect(opts.boundary.sourceAbsPath)
@@ -191,6 +194,10 @@ async function writeGeneratedRootLayoutFile(opts: {
   const layoutReturn = isAsyncUserLayout ? "layout" : userLayoutElement;
   //? Under an ancestor root boundary the route tree merges that root's head itself; merging it here would repeat it.
   const headLayouts = opts.includeSystemProvider ? "[inheritedLayout, userLayout]" : "[userLayout]";
+  //? Likewise for the guard: an ancestor root boundary runs its own from its own layer.
+  const guardExport = opts.includeSystemProvider
+    ? "export const guard = RouteGuards.compose(inheritedLayout.guard, userLayout.guard);"
+    : "export const guard = userLayout.guard;";
   const layoutExports = `export async function generateHead(props: PageProps) {
   const heads = await Promise.all(
     ${headLayouts}.map((layout) => (layout.generateHead ? layout.generateHead(props) : layout.head)),
@@ -202,14 +209,16 @@ export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
 export const Loading = userLayout.Loading;
+${guardExport}
 
 ${layoutSignature}({ children, params, searchParams }: LayoutProps) {
 ${layoutBinding}  return `;
   const source = opts.includeSystemProvider
     ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
-import { loadFonts, resolveRouteModule, RouteHead } from "akanjs/client";
+import { assertGuardOnChain, loadFonts, RouteGuards, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
 import { System } from "akanjs/ui";
+import type { McpAppRootProps } from "akanjs/webkit";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};
 ${clientImport}${inheritedImport}${userImport}
@@ -242,9 +251,25 @@ ${layoutExports}(
     </System.Provider>
   );
 }
+
+export function McpAppRoot({ children, params, path }: McpAppRootProps) {
+  return (
+    <System.App
+      params={params}
+      path={path}
+      env={env}
+      theme={theme}
+      viewport={viewport}
+      fonts={loadFonts(userFonts)}
+      className={defaultFontClassName}
+    >
+      {children}
+    </System.App>
+  );
+}
 `
     : `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
-import { resolveRouteModule, RouteHead } from "akanjs/client";
+import { assertGuardOnChain, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
 ${inheritedImport}${userImport}
 ${layoutExports}${layoutReturn};

package/biome.base.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.12/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.14/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",
@@ -128,7 +128,8 @@
         "!**/*.constant.ts",
         "!**/common/**",
         "!**/env/**",
-        "!{apps,libs}/*/native/**"
+        "!{apps,libs}/*/native/**",
+        "!apps/*/script/migration/**"
       ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
     },
@@ -195,7 +196,11 @@
     },
     {
       "includes": ["{apps,libs}/**/*.tsx", "!**/*.test.tsx", "!**/*.spec.tsx"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit"]
+      "linter": { "rules": { "correctness": { "useHookAtTopLevel": "error" } } },
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit",
+        "./node_modules/@akanjs/devkit/lint/no-conditional-st-hook.grit"
+      ]
     },
     {
       "includes": [

package/biomeBase.test.ts

@@ -0,0 +1,78 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { biomeBaseConfig } from "./biomeBase";
+import { Linter, parseBiomeReport } from "./linter";
+
+const devkitDir = import.meta.dir;
+const biomeBin = path.resolve(devkitDir, "../../../node_modules/.bin", Linter.biomeBinName);
+
+const hookProbe = `export const Early = ({ id }: { id?: string }) => {
+  if (!id) return null;
+  const [count] = useState(0);
+  return <p>{count}</p>;
+};
+export const Branch = ({ open }: { open: boolean }) => {
+  if (open) useEffect(() => {}, []);
+  return null;
+};
+`;
+
+const tempDirs: string[] = [];
+
+afterAll(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+const runBiome = (args: string[], cwd: string) =>
+  new Promise<string>((resolve, reject) => {
+    const proc = spawn(biomeBin, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk: Buffer) => (stdout += chunk.toString()));
+    proc.stderr.on("data", (chunk: Buffer) => (stderr += chunk.toString()));
+    proc.on("error", reject);
+    proc.on("close", () => resolve(stdout || stderr));
+  });
+
+const lintWorkspace = async (files: string[]) => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "biome-base-"));
+  tempDirs.push(dir);
+  //? The base config names its plugins as `./node_modules/@akanjs/devkit/…`, resolved from the extending config's
+  //? folder. A junction needs no privilege on Windows, and the type is ignored elsewhere.
+  await mkdir(path.join(dir, "node_modules", "@akanjs"), { recursive: true });
+  await symlink(devkitDir, path.join(dir, "node_modules", "@akanjs", "devkit"), "junction");
+  await writeFile(path.join(dir, "biome.json"), JSON.stringify({ extends: [biomeBaseConfig] }));
+  for (const file of files) {
+    await mkdir(path.dirname(path.join(dir, file)), { recursive: true });
+    await writeFile(path.join(dir, file), hookProbe);
+  }
+  const output = await runBiome(["lint", "--reporter=json", "--max-diagnostics=none", ...files], dir);
+  return parseBiomeReport(output).diagnostics ?? [];
+};
+
+describe("biome.base.json", () => {
+  test("reports a conditional React hook in app and lib components, not in their tests or in packages", async () => {
+    const diagnostics = await lintWorkspace([
+      "apps/demo/ui/Probe.tsx",
+      "libs/demo/ui/Probe.tsx",
+      "apps/demo/ui/Probe.test.tsx",
+      "pkgs/demo/Probe.tsx",
+    ]);
+    const hookReports = diagnostics
+      .filter((diagnostic) => diagnostic.category === "lint/correctness/useHookAtTopLevel")
+      .map(
+        (diagnostic) =>
+          `${diagnostic.location?.path?.replaceAll("\\", "/")}:${diagnostic.location?.start?.line} ${diagnostic.severity}`,
+      )
+      .sort();
+    expect(hookReports).toEqual([
+      "apps/demo/ui/Probe.tsx:3 error",
+      "apps/demo/ui/Probe.tsx:7 error",
+      "libs/demo/ui/Probe.tsx:3 error",
+      "libs/demo/ui/Probe.tsx:7 error",
+    ]);
+  });
+});

package/biomeBase.ts

@@ -3,4 +3,4 @@ export const biomeBaseConfig = "@akanjs/devkit/biome.base.json";
 
 // Pinned: Biome moves rules between groups across minors and a stale position is a hard config error. Bump it with
 // `biome.base.json` in one commit, running `biome migrate --write` in the workspace root and in this package.
-export const biomeVersion = "2.5.12";
+export const biomeVersion = "2.5.14";

package/codeAgent/agent/AkanCodeCompaction.ts

@@ -0,0 +1,49 @@
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { CodeAgentModel } from "./akanCodeModel";
+
+type CompactedModel = Pick<CodeAgentModel, "provider" | "id" | "contextWindow">;
+
+// The engine compacts above `contextWindow - reserveTokens`, so a share of the window becomes a reserve per model.
+export class AkanCodeCompaction {
+  // Twice the engine's 16,384: at 16k a reasoning model stops mid-thought at the compaction threshold,
+  // and the recovery re-sends a near-full window to retry the turn.
+  static readonly reserveFloor = 32_768;
+  static readonly steps = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100] as const;
+
+  static isStep(percent: number) {
+    return AkanCodeCompaction.steps.some((step) => step === percent);
+  }
+
+  /** `100` is the default itself, so it is stored as no choice at all. */
+  static normalize(percent: number | undefined) {
+    if (percent === undefined) return undefined;
+    if (!AkanCodeCompaction.isStep(percent))
+      throw new Error(`Autocompact takes a percent in steps of 10: ${AkanCodeCompaction.steps.join(", ")}.`);
+    return percent === 100 ? undefined : percent;
+  }
+
+  static thresholdOf(contextWindow: number, percent: number | undefined) {
+    const share = percent ? Math.floor((contextWindow * percent) / 100) : contextWindow;
+    return Math.min(share, contextWindow - AkanCodeCompaction.reserveFloor);
+  }
+
+  static apply(settings: SettingsManager, model: CompactedModel, percent: number | undefined) {
+    const threshold = AkanCodeCompaction.thresholdOf(model.contextWindow, percent);
+    // Keyed by model, so the next model is never checked against a reserve sized for this one's window.
+    settings.applyOverrides({
+      compaction: {
+        modelOverrides: { [`${model.provider}/${model.id}`]: { reserveTokens: model.contextWindow - threshold } },
+      },
+    });
+  }
+
+  /** Why `percent` cannot work on `model`, or undefined when it can. */
+  static problemOf(model: CompactedModel, percent: number, keepRecentTokens: number) {
+    const name = `${model.provider}/${model.id}`;
+    if (model.contextWindow <= 0) return `${name} declares no context window, so it has no share to compact at.`;
+    const threshold = AkanCodeCompaction.thresholdOf(model.contextWindow, percent);
+    if (threshold >= keepRecentTokens) return undefined;
+    const k = (tokens: number) => `${Math.round(tokens / 1000)}k`;
+    return `Compacting at ${percent}% of the ${k(model.contextWindow)} window of ${name} starts at ${k(threshold)}, under the ${k(keepRecentTokens)} of recent turns every compaction keeps, so every turn would compact again.`;
+  }
+}

package/codeAgent/agent/AkanCodeServices.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { type InlineExtension, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { CodeAgentProfile } from "akanjs/common";
 import { AkanEnvKeys } from "../tools/AkanEnvKeys";
+import { AkanCodeCompaction } from "./AkanCodeCompaction";
 import { type AkanContextFile, AkanContextFiles } from "./AkanContextFiles";
 import { akanCodePaths } from "./akanCodePaths";
 import { akanSystemPrompt } from "./akanSystemPrompt";
@@ -27,9 +28,7 @@ export class AkanCodeServices {
       enableInstallTelemetry: false,
       enableAnalytics: false,
       quietStartup: true,
-      // Twice the engine's 16,384: at 16k a reasoning model stops mid-thought at the compaction threshold,
-      // and the recovery re-sends a near-full window to retry the turn.
-      compaction: { reserveTokens: 32_768 },
+      compaction: { reserveTokens: AkanCodeCompaction.reserveFloor },
     });
   }
 

package/codeAgent/agent/CodeAgent.ts

@@ -25,6 +25,8 @@ import {
 } from "akanjs/common";
 import type { Workspace } from "../../commandDecorators";
 import { AkanCodePlugins } from "../tools/AkanCodePlugins";
+import { DeepSeekWeb } from "../tools/DeepSeekWeb";
+import { AkanCodeCompaction } from "./AkanCodeCompaction";
 import { AkanCodeServices } from "./AkanCodeServices";
 import {
   akanCodeModel,
@@ -52,6 +54,8 @@ export interface CodeAgentOptions {
   cwd?: string;
   profile: CodeAgentProfile;
   model?: CodeAgentModelRef;
+  /** Percent of the context window that starts a compaction, in steps of 10. */
+  autoCompactAt?: number;
   /** Apps whose dev server and preview the turn-end feedback loop watches. */
   apps?: string[];
   extensions?: InlineExtension[];
@@ -85,6 +89,7 @@ export class CodeAgent {
   readonly #replay: CodeAgentEvent[] = [];
   #replayFrom = 0;
   #lastContextTokens: number | undefined;
+  #autoCompactAt: number | undefined;
 
   private constructor(profile: CodeAgentProfile) {
     this.#profile = profile;
@@ -95,8 +100,10 @@ export class CodeAgent {
     const workspaceRoot = options.workspace.workspaceRoot;
     const cwd = options.cwd ?? workspaceRoot;
     const agent = new CodeAgent(options.profile);
+    const autoCompactAt = AkanCodeCompaction.normalize(options.autoCompactAt);
     const settingsManager = AkanCodeServices.settings();
-    const modelRuntime = await AkanCodeServices.runtime(workspaceRoot, CodeAgentProxy.fromEnv(options.profile));
+    const proxy = CodeAgentProxy.fromEnv(options.profile);
+    const modelRuntime = await AkanCodeServices.runtime(workspaceRoot, proxy);
     const model = await akanCodeModel(modelRuntime, options.model);
     const compaction = settingsManager.getCompactionSettings(model);
     const modelWarnings = akanCodeModelWarnings(model, compaction.reserveTokens + compaction.keepRecentTokens);
@@ -107,6 +114,7 @@ export class CodeAgent {
       profile: options.profile,
       apps: options.apps ?? [],
       canSeeImages: akanCodeModelSupportsImages(model),
+      deepseek: await DeepSeekWeb.fromRuntime(modelRuntime, !!proxy),
       depth: options.depth ?? 0,
       ...(options.subagentSpend ? { subagentSpend: options.subagentSpend } : {}),
       currentSessionId: () => agent.sessionId,
@@ -146,10 +154,12 @@ export class CodeAgent {
     agent.#workspaceRoot = workspaceRoot;
     if (options.profile.session.store !== "memory") agent.#sessionDir = akanCodePaths.sessionsDir(workspaceRoot);
     await agent.#attach(session, options.mode ?? "print");
+    const autoCompactWarning = agent.#fitAutoCompact(autoCompactAt);
     agent.#suspended = new CodeAgentSuspended(CodeAgentSuspended.fileOf(agent.#sessionDir, agent.sessionId));
     if (agent.#sessionDir && options.profile.session.store === "file")
       agent.#openMail(akanCodePaths.mailDir(workspaceRoot), cwd);
-    for (const message of modelWarnings) agent.#emit({ type: "notice", level: "warning", message });
+    for (const message of [...modelWarnings, ...autoCompactWarning])
+      agent.#emit({ type: "notice", level: "warning", message });
     return agent;
   }
 
@@ -232,6 +242,7 @@ export class CodeAgent {
       contextTokens: model?.contextWindow,
       // Not `off`: that is a setting of a reasoning model, not the absence of reasoning.
       effort: session.supportsThinking() ? session.thinkingLevel : undefined,
+      autoCompactAt: this.#autoCompactAt,
       name: session.sessionName,
       interaction: this.#profile.interaction,
     };
@@ -396,9 +407,42 @@ export class CodeAgent {
     const model = await akanCodeModel(session.modelRuntime, ref);
     if (!model) throw new Error(`Unknown model: ${ref.provider}/${ref.id}`);
     await session.setModel(model);
+    for (const message of this.#fitAutoCompact(this.#autoCompactAt))
+      this.#emit({ type: "notice", level: "warning", message });
     this.#emit({ type: "session", info: this.info });
   }
 
+  setAutoCompactAt(percent: number | undefined) {
+    const wanted = AkanCodeCompaction.normalize(percent);
+    const problem = this.#autoCompactProblem(wanted);
+    if (problem) throw new Error(problem);
+    this.#autoCompactAt = wanted;
+    this.#applyAutoCompact();
+    this.#emit({ type: "session", info: this.info });
+  }
+
+  // A share that fit one window can fall under the kept turns of a smaller one, and would compact every turn.
+  #fitAutoCompact(percent: number | undefined) {
+    const problem = this.#autoCompactProblem(percent);
+    this.#autoCompactAt = problem ? undefined : percent;
+    this.#applyAutoCompact();
+    return problem ? [`${problem} Autocompact is back to the default.`] : [];
+  }
+
+  #autoCompactProblem(percent: number | undefined) {
+    const session = this.#require();
+    const model = session.model;
+    if (!model || !percent) return undefined;
+    const { keepRecentTokens } = session.settingsManager.getCompactionSettings(model);
+    return AkanCodeCompaction.problemOf(model, percent, keepRecentTokens);
+  }
+
+  // Never before `create` has built the session: `settingsManager.reload()` drops whatever `applyOverrides` set.
+  #applyAutoCompact() {
+    const session = this.#require();
+    if (session.model) AkanCodeCompaction.apply(session.settingsManager, session.model, this.#autoCompactAt);
+  }
+
   async waitForIdle() {
     await this.#require().waitForIdle();
   }

package/codeAgent/agent/CodeAgentRpcHost.ts

@@ -83,6 +83,9 @@ export class CodeAgentRpcHost {
       case "set_model":
         await this.#agent.setModel({ provider: command.provider, id: command.modelId });
         return await this.#agent.state();
+      case "set_auto_compact":
+        this.#agent.setAutoCompactAt(command.percent);
+        return await this.#agent.state();
       case "get_state":
         return await this.#agent.state(command.sinceSeq === undefined ? {} : { sinceSeq: command.sinceSeq });
       case "shutdown":

package/codeAgent/agent/akanCodeCompaction.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { AkanCodeCompaction } from "./AkanCodeCompaction";
+import { AkanCodeServices } from "./AkanCodeServices";
+
+const big = { provider: "deepseek", id: "deepseek-flash", contextWindow: 1_000_000 };
+const small = { provider: "openai", id: "small", contextWindow: 128_000 };
+
+describe("AkanCodeCompaction", () => {
+  test("a percent is a share of the window, never closer to the edge than the reply's floor", () => {
+    expect(AkanCodeCompaction.thresholdOf(1_000_000, 60)).toBe(600_000);
+    expect(AkanCodeCompaction.thresholdOf(128_000, 90)).toBe(128_000 - AkanCodeCompaction.reserveFloor);
+    expect(AkanCodeCompaction.thresholdOf(1_000_000, undefined)).toBe(1_000_000 - AkanCodeCompaction.reserveFloor);
+  });
+
+  test("only steps of 10 are taken, and 100 is the default rather than a choice", () => {
+    expect(AkanCodeCompaction.normalize(60)).toBe(60);
+    expect(AkanCodeCompaction.normalize(100)).toBeUndefined();
+    expect(AkanCodeCompaction.normalize(undefined)).toBeUndefined();
+    for (const wrong of [0, 55, 110, Number.NaN]) expect(() => AkanCodeCompaction.normalize(wrong)).toThrow();
+  });
+
+  test("the engine reads the share back as this model's reserve and leaves other models at the floor", () => {
+    const settings = AkanCodeServices.settings();
+    AkanCodeCompaction.apply(settings, big, 60);
+    expect(settings.getCompactionSettings(big).reserveTokens).toBe(400_000);
+    expect(settings.getCompactionSettings(small).reserveTokens).toBe(AkanCodeCompaction.reserveFloor);
+    AkanCodeCompaction.apply(settings, big, undefined);
+    expect(settings.getCompactionSettings(big).reserveTokens).toBe(AkanCodeCompaction.reserveFloor);
+  });
+
+  test("a share under the turns every compaction keeps is refused, since each turn would compact again", () => {
+    expect(AkanCodeCompaction.problemOf(big, 10, 20_000)).toBeUndefined();
+    expect(AkanCodeCompaction.problemOf(small, 10, 20_000)).toContain("every turn would compact again");
+    expect(AkanCodeCompaction.problemOf({ ...small, contextWindow: 0 }, 50, 20_000)).toContain("no context window");
+  });
+});

package/codeAgent/agent/codeAgent.test.ts

@@ -24,16 +24,31 @@ const chunk = (delta: object, finish: string | null = null) =>
     choices: [{ index: 0, delta, finish_reason: finish }],
   })}\n\n`;
 
+const usageChunk = (promptTokens: number) =>
+  `data: ${JSON.stringify({
+    id: "c1",
+    object: "chat.completion.chunk",
+    created: 0,
+    model: akanCodeDefaultModel.id,
+    choices: [],
+    usage: { prompt_tokens: promptTokens, completion_tokens: 1, total_tokens: promptTokens + 1 },
+  })}\n\n`;
+
 let llm: ReturnType<typeof Bun.serve>;
 let llmCalls = 0;
+let reportedTokens = 0;
 beforeAll(() => {
   llm = Bun.serve({
     port: 0,
     fetch: () => {
       llmCalls += 1;
-      return new Response(`${chunk({ role: "assistant", content: "ok" })}${chunk({}, "stop")}data: [DONE]\n\n`, {
-        headers: { "content-type": "text/event-stream" },
-      });
+      const usage = reportedTokens ? usageChunk(reportedTokens) : "";
+      return new Response(
+        `${chunk({ role: "assistant", content: "ok" })}${chunk({}, "stop")}${usage}data: [DONE]\n\n`,
+        {
+          headers: { "content-type": "text/event-stream" },
+        },
+      );
     },
   });
 });
@@ -84,6 +99,49 @@ describe("CodeAgent", () => {
     }
   });
 
+  test("autocompact is carried from creation, announced on the session frame, and refuses a step it lacks", async () => {
+    const root = await makeTempRoot();
+    const agent = await createAgent(root, { autoCompactAt: 60 });
+    try {
+      const events: CodeAgentEvent[] = [];
+      agent.on((event) => events.push(event));
+      expect(agent.info.autoCompactAt).toBe(60);
+      expect(() => agent.setAutoCompactAt(55)).toThrow("steps of 10");
+      expect(agent.info.autoCompactAt).toBe(60);
+      agent.setAutoCompactAt(100);
+      expect(agent.info.autoCompactAt).toBeUndefined();
+      expect(events.filter((event) => event.type === "session")).toHaveLength(1);
+    } finally {
+      agent.dispose();
+    }
+  });
+
+  test("a chosen share reaches the engine: a reply reported past it compacts, and the default lets it pass", async () => {
+    const compactions = async (options: Partial<CodeAgentOptions>) => {
+      const agent = await createAgent(await makeTempRoot(), options);
+      const reasons: string[] = [];
+      agent.on((event) => {
+        if (event.type === "compaction" && event.phase === "start") reasons.push(event.reason);
+      });
+      try {
+        // The 20k most recent tokens are kept, so a summary needs an older turn behind the filler.
+        for (const text of ["hello", "filler ".repeat(20_000)]) {
+          await agent.prompt(text);
+          await agent.waitForIdle();
+        }
+        reportedTokens = 650_000;
+        await agent.prompt("next");
+        await agent.waitForIdle();
+      } finally {
+        reportedTokens = 0;
+        agent.dispose();
+      }
+      return reasons;
+    };
+    expect(await compactions({})).toEqual([]);
+    expect(await compactions({ autoCompactAt: 60 })).toEqual(["threshold"]);
+  });
+
   test("a sub-agent hands its plugins the token tally of the tree that opened it", async () => {
     const root = await makeTempRoot();
     const build = AkanCodePlugins.build;

package/codeAgent/agent/codeAgentContract.test.ts

@@ -349,6 +349,7 @@ describe("codeAgentEventLabel", () => {
           tools: [],
           contextTokens: undefined,
           effort: undefined,
+          autoCompactAt: undefined,
           name: undefined,
           interaction: { question: "await", approval: "await" },
         },

package/codeAgent/index.ts

@@ -1,5 +1,6 @@
 // Importing this barrel loads the engine (~122MiB resident); a host needing cheap pieces imports the owning module.
 // agent/consoleToStderr is deliberately absent: it takes over globalThis.console, so an RPC entry imports it first.
+export * from "./agent/AkanCodeCompaction";
 export * from "./agent/AkanCodeServices";
 export * from "./agent/akanCodeModel";
 export * from "./agent/akanCodePaths";

package/codeAgent/skills/akan-code/SKILL.md

@@ -78,6 +78,9 @@ Stored under `.akan/code/sessions` — project history, so a second checkout of
 - `/peers` lists other `akan code` sessions running in this workspace; `/msg <peer> <text>` hands one a
   message.
 - `/clear` wipes the screen and keeps the conversation; `/compact [notes]` shortens what the model carries.
+- `/autocompact <percent>` compacts on its own once the window is that full, in steps of 10 (`/autocompact 60`);
+  `100` is the default, which waits until 32k remain for the reply. `akan code --compact-at 60` (`-c`) starts
+  with it, and a share under the 20k every compaction keeps is refused.
 
 ## Model, effort, keys
 
@@ -119,6 +122,7 @@ akan code -i "<prompt>"         open the session with the prompt already sent
 --app <name>                    narrow the agent to one app
 --profile local|pod|review|web  what it may do (default local)
 --model <provider>/<id>         --thinking, --json, --rpc, --resume <id>
+--compact-at <percent>          compact once the window is this full (10, 20, … 100)
 ```
 
 `review` reads and never writes, loads no project context files, and keeps no session on disk. `pod` has