@akanjs/devkit 3.1.0-rc.2 → 3.1.0-rc.20

package/abstractDoc.ts

@@ -26,7 +26,7 @@ export class AbstractDoc {
   static async findAll(sys: SysExecutor, { module }: { module?: string | null } = {}) {
     const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`))
       .map((filePath) => filePath.split(path.sep).join("/"))
-      .sort();
+      .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
     if (!module) return docs;
     return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);

package/agentsIndex.test.ts

@@ -86,6 +86,9 @@ describe("collectScopeRecipeSources", () => {
     await write("libs/shared/ui/Recipe/panel.ts", `export const panelRecipe = recipe(tv({ base: "y" }));`);
     await write("pkgs/akanjs/ui/recipe/buttonRecipe.ts", `export const buttonRecipe = recipe(tv({ base: "z" }));`);
     const sources = await collectScopeRecipeSources(root, { type: "app", name: "minimal" }, ["shared"]);
-    expect(sources.map((source) => source.importFrom).sort()).toEqual(["@apps/minimal/ui", "@libs/shared/ui"]);
+    expect(sources.map((source) => source.importFrom).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual([
+      "@apps/minimal/ui",
+      "@libs/shared/ui",
+    ]);
   });
 });

package/akanConfig/akanConfig.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import type { ServerPolicy } from "@akanjs/native/api";
 import type { AkanPlugin } from "akanjs";
 import { DatabaseModes, normalizeRoutePrefix } from "akanjs/base";
-import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
+import { type AkanI18nConfig, resolveAkanI18nConfig, trimSlashes } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
 import { LibExecutor, WorkspaceExecutor } from "../executors";
@@ -567,7 +567,7 @@ export class AkanAppConfig implements AppConfigResult {
   }
   #applyRoutes(routes: AkanRouteConfig[] = []) {
     for (const route of routes) {
-      const basePath = route.basePath ? route.basePath.replace(/^\/+|\/+$/g, "") : null;
+      const basePath = route.basePath ? trimSlashes(route.basePath) : null;
       if (basePath !== null) this.basePaths.add(basePath);
       const domains = basePath !== null ? this.subRoutes.getOrInsert(basePath, new Set()) : this.domains;
       for (const branch of Object.keys(route.domains)) this.branches.add(branch);

package/akanContext.ts

@@ -209,7 +209,7 @@ export const upsertCodexMcpServerBlock = (
   const match = existing.match(codexAkanTablePattern);
   if (!match) {
     if (!existing.trim()) return nextBlock;
-    return `${existing.replace(/\s*$/, "")}\n\n${nextBlock}`;
+    return `${existing.trimEnd()}\n\n${nextBlock}`;
   }
   if (match[0].trim() === nextBlock.trim()) return existing;
   if (!force)
@@ -847,8 +847,8 @@ export class AkanContextAnalyzer {
       const listed = listedByImport(sectionOf(agentsMd, "## Recipes")).get("akanjs/ui") ?? new Set<string>();
       pushIndexDiagnostic(
         "AGENTS.md",
-        [...frameworkDeclared].filter((name) => !listed.has(name)).sort(),
-        [...listed].filter((name) => !frameworkDeclared.has(name)).sort(),
+        [...frameworkDeclared].filter((name) => !listed.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+        [...listed].filter((name) => !frameworkDeclared.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
         "akan agent install agents-md",
       );
     }
@@ -859,7 +859,7 @@ export class AkanContextAnalyzer {
         .catch(() => "");
       const groups = listedByImport(sectionOf(scopeMd, "## Recipes In Scope"));
       const ownListed = groups.get(`@${sys.path}/ui`) ?? new Set<string>();
-      const missing = [...own].filter((name) => !ownListed.has(name)).sort();
+      const missing = [...own].filter((name) => !ownListed.has(name)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
       // Every listed name — the scope's own and its dependency libs' — must still exist at its owner.
       const stale = [...groups.entries()]
         .flatMap(([importFrom, names]) =>

package/akanMcpContract.ts

@@ -113,7 +113,7 @@ const slugPart = (value: unknown) =>
     ? value
         .trim()
         .replace(/[^a-zA-Z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
+        .replace(/^-|-$/g, "")
         .toLowerCase()
     : "";
 

package/applicationBuildRunner.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
@@ -110,4 +110,27 @@ console.info(new SampleService().name);
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("a build for a real environment stops before any phase when the serve domain is only the local default", async () => {
+    const { root, workspace } = await createTempApp("portal");
+    await writeFile(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=repo\n");
+    const shellDomain = process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    delete process.env.AKAN_PUBLIC_SERVE_DOMAIN;
+    const app = AppExecutor.from(workspace, "portal");
+    let prepared = false;
+    app.prepareCommand = async () => {
+      prepared = true;
+      throw new Error("prepared");
+    };
+    try {
+      await expect(new ApplicationBuildRunner(app, { environment: "main" }).build()).rejects.toThrow(
+        'akan build for the "main" environment needs AKAN_PUBLIC_SERVE_DOMAIN (would be "localhost") set',
+      );
+      expect(prepared).toBe(false);
+      await expect(new ApplicationBuildRunner(app, { environment: "local" }).build()).rejects.toThrow("prepared");
+    } finally {
+      if (shellDomain !== undefined) process.env.AKAN_PUBLIC_SERVE_DOMAIN = shellDomain;
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -6,6 +6,7 @@ import type {
   ApplicationBuildResult,
 } from "./applicationBuildReporter";
 import type { App } from "./commandDecorators";
+import { WorkspaceExecutor } from "./executors";
 import {
   AllRoutesBuilder,
   CsrArtifactBuilder,
@@ -101,6 +102,7 @@ export class ApplicationBuildRunner {
     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;
     //? Before any phase: a profile that would ship a secret stops the build, not the image after it.
@@ -362,9 +364,17 @@ void run().catch((error) => {
     return { base, allRoutes };
   }
 
+  //? 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 result = await Bun.build(config);
+    const metafileDir = process.env.AKAN_BUILD_METAFILE
+      ? 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) {
+      const entry = path.parse(String(config.entrypoints[0] ?? label)).name;
+      await Bun.write(path.join(metafileDir, `${entry}.json`), JSON.stringify(result.metafile));
+    }
     return result;
   }
 

package/artifact/implicitRootLayout.test.ts

@@ -46,6 +46,8 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;");
     expect(generatedSource).toContain("export const Error = userLayout.Error ?? inheritedLayout.Error;");
     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;");
     expect(generatedSource).toContain(
       "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>",
     );

package/artifact/implicitRootLayout.ts

@@ -201,6 +201,7 @@ async function writeGeneratedRootLayoutFile(opts: {
 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;
 
 ${layoutSignature}({ children, params, searchParams }: LayoutProps) {
 ${layoutBinding}  return `;

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",
@@ -85,16 +85,6 @@
   "overrides": [
     {
       "includes": [
-        "**/env.client.local.ts",
-        "**/env.client.debug.ts",
-        "**/env.client.develop.ts",
-        "**/env.client.main.ts",
-        "**/env.client.testing.ts",
-        "**/env.server.local.ts",
-        "**/env.server.develop.ts",
-        "**/env.server.main.ts",
-        "**/env.server.testing.ts",
-        "**/env.server.type.ts",
         "apps/*/lib/cnst.ts",
         "apps/*/lib/dict.ts",
         "apps/*/lib/db.ts",

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/cloud/configLock.ts

@@ -36,7 +36,8 @@ export class ConfigLock {
 
   static async #take(lockPath: string) {
     const handle = await open(lockPath, "wx", 0o600).catch((error: NodeJS.ErrnoException) => {
-      if (error.code === "EEXIST") return null;
+      // Windows answers EPERM, not EEXIST, while a released lock file is still pending delete behind an open handle.
+      if (error.code === "EEXIST" || (process.platform === "win32" && error.code === "EPERM")) return null;
       throw error;
     });
     if (!handle) return false;

package/cloud/globalConfig.ts

@@ -1,4 +1,5 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
+import { trimTrailingSlashes } from "akanjs/common";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
 import { ConfigLock } from "./configLock";
@@ -60,8 +61,8 @@ export class GlobalConfig {
   static #normalizeHost(host: string) {
     const url = URL.canParse(host) ? new URL(host) : null;
     return url && (url.protocol === "https:" || url.protocol === "http:")
-      ? `${url.origin}${url.pathname.replace(/\/+$/, "")}`
-      : host.replace(/\/+$/, "");
+      ? `${url.origin}${trimTrailingSlashes(url.pathname)}`
+      : trimTrailingSlashes(host);
   }
   static async getHostConfig(host = GlobalConfig.akanCloudHost): Promise<HostConfig> {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();

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/CodeAgentProxy.ts

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
-import type { CodeAgentProfile } from "akanjs/common";
+import { type CodeAgentProfile, trimTrailingSlashes } from "akanjs/common";
 import { akanCodeDefaultModel } from "./akanCodeModel";
 
 interface PreparedRequest {
@@ -27,7 +27,7 @@ export class CodeAgentProxy {
   readonly #token?: string;
 
   constructor({ baseUrl, providers, tokenFile, token }: CodeAgentProxyOptions) {
-    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.baseUrl = trimTrailingSlashes(baseUrl);
     this.providers = providers;
     this.#tokenFile = tokenFile;
     this.#token = token;

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/akanCodeModel.ts

@@ -8,7 +8,7 @@ export interface CodeAgentModelRef {
   id: string;
 }
 
-/** DeepSeek's million-token window is what makes a 26k-token `AGENTS.md` affordable on every turn. */
+/** DeepSeek's million-token window is what makes the always-loaded `AGENTS.md` affordable on every turn. */
 export const akanCodeDefaultModel: CodeAgentModelRef = { provider: "deepseek", id: "deepseek-flash" };
 
 // Declared text-only by the catalogue, yet verified against the provider to see images.

package/codeAgent/agent/akanContextFiles.test.ts

@@ -73,7 +73,9 @@ describe("workspace context files", () => {
   test("a rule with no frontmatter at all is unconditional, and so is .cursorrules", () => {
     const root = workspace({ ".cursor/rules/plain.mdc": "just do it", ".cursorrules": "the legacy file" });
     const files = AkanContextFiles.extend(loaded(root), { workspaceRoot: root, cwd: root });
-    expect(namesOf(files, root).sort()).toEqual([".cursorrules", ".cursor/rules/plain.mdc", "AGENTS.md"].sort());
+    expect(namesOf(files, root).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))).toEqual(
+      [".cursorrules", ".cursor/rules/plain.mdc", "AGENTS.md"].sort(),
+    );
   });
 
   test("rules nested under the rules directory are found, in a stable order", () => {

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

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

@@ -26,7 +26,8 @@ For a model `comment` (`<Slice>` is a signal slice suffix, e.g. `InPublic`):
 
 ## Generated state — `st.use.*`
 
-`comment`, `commentLoading`, `commentForm`, `commentFormLoading`, `commentSubmit`, `commentModal`,
+`comment`, `commentLoading`, `commentForm`, `commentFormLoading`, `commentFormUploading` (uploads in flight, per
+`File` field — non-empty means do not submit), `commentSubmit`, `commentModal`,
 `commentViewAt`, `commentOperation`; per slice `commentList<Slice>`, `commentListLoading<Slice>`,
 `commentInitList<Slice>`, `commentSelection<Slice>`, `commentInsight<Slice>`, `pageOfComment<Slice>`,
 `lastPageOfComment<Slice>`, `hasMoreOfComment<Slice>`, `limitOfComment<Slice>`, `sortOfComment<Slice>`.