@akanjs/devkit 3.1.0-rc.11 → 3.1.0-rc.12

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,7 @@ import {
 } from "akanjs/common";
 import type { Workspace } from "../../commandDecorators";
 import { AkanCodePlugins } from "../tools/AkanCodePlugins";
+import { AkanCodeCompaction } from "./AkanCodeCompaction";
 import { AkanCodeServices } from "./AkanCodeServices";
 import {
   akanCodeModel,
@@ -52,6 +53,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 +88,7 @@ export class CodeAgent {
   readonly #replay: CodeAgentEvent[] = [];
   #replayFrom = 0;
   #lastContextTokens: number | undefined;
+  #autoCompactAt: number | undefined;
 
   private constructor(profile: CodeAgentProfile) {
     this.#profile = profile;
@@ -95,6 +99,7 @@ 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 model = await akanCodeModel(modelRuntime, options.model);
@@ -146,10 +151,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 +239,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 +404,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

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>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.11",
+  "version": "3.1.0-rc.12",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.0-rc.11",
+    "akanjs": "3.1.0-rc.12",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",