@akanjs/devkit 3.0.0-beta.13 → 3.0.0-beta.15

package/codeAgent/agent/CodeMailbox.ts

@@ -0,0 +1,175 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+export interface CodePeer {
+  id: string;
+  name: string;
+  cwd: string;
+  pid: number;
+  /** When the session last said it was alive. */
+  at: number;
+}
+
+export interface CodeMail {
+  at: number;
+  from: string;
+  fromName: string;
+  text: string;
+}
+
+/**
+ * How two `akan code` sessions in one workspace reach each other.
+ *
+ * A directory, not a socket or a daemon: the sessions already share a checkout and already write their
+ * transcripts there, and a mailbox on disk survives one end restarting, needs nothing listening to accept a
+ * message, and is inspectable with `cat` when a message does not arrive.
+ *
+ * Presence is a heartbeat file rather than a registration, because the interesting failure is a session that
+ * died without saying so — a registry would keep listing it forever, while a stale mtime says it is gone.
+ */
+export class CodeMailbox {
+  /** A session older than this said nothing for four heartbeats, so it is not there to answer. */
+  static readonly staleMs = 20_000;
+  static readonly beatMs = 5_000;
+  static readonly pollMs = 1_500;
+  /** How many messages one session may send in a minute, so two agents answering each other cannot run away. */
+  static readonly sendsPerMinute = 20;
+
+  readonly #dir: string;
+  readonly #id: string;
+  #name: string;
+  #read = 0;
+  #sent: number[] = [];
+  #beat: ReturnType<typeof setInterval> | null = null;
+  #poll: ReturnType<typeof setInterval> | null = null;
+
+  constructor(dir: string, id: string, name: string) {
+    this.#dir = dir;
+    this.#id = id;
+    this.#name = name;
+  }
+
+  get inbox() {
+    return path.join(this.#dir, "inbox", `${this.#id}.jsonl`);
+  }
+
+  /** Announces this session and starts delivering what arrives for it. */
+  open(cwd: string, onMail: (mail: CodeMail) => void) {
+    mkdirSync(path.join(this.#dir, "live"), { recursive: true });
+    mkdirSync(path.join(this.#dir, "inbox"), { recursive: true });
+    // Whatever was already in the inbox belongs to an earlier run of this session, which has read it or is
+    // never going to; delivering it now would replay a conversation that already happened.
+    this.#read = CodeMailbox.#lines(this.inbox).length;
+    this.beat(cwd);
+    this.#beat = setInterval(() => this.beat(cwd), CodeMailbox.beatMs);
+    this.#poll = setInterval(() => {
+      for (const mail of this.#drain()) onMail(mail);
+    }, CodeMailbox.pollMs);
+  }
+
+  close() {
+    if (this.#beat) clearInterval(this.#beat);
+    if (this.#poll) clearInterval(this.#poll);
+    this.#beat = null;
+    this.#poll = null;
+    try {
+      rmSync(path.join(this.#dir, "live", `${this.#id}.json`), { force: true });
+    } catch {
+      // A leftover presence file goes stale on its own; failing to remove it is not worth an error.
+    }
+  }
+
+  rename(name: string, cwd: string) {
+    this.#name = name;
+    this.beat(cwd);
+  }
+
+  beat(cwd: string) {
+    const peer: CodePeer = { id: this.#id, name: this.#name, cwd, pid: process.pid, at: Date.now() };
+    try {
+      writeFileSync(path.join(this.#dir, "live", `${this.#id}.json`), JSON.stringify(peer));
+    } catch {
+      // A read-only or missing directory means no presence; messaging then simply finds nobody.
+    }
+  }
+
+  /** The live sessions of this workspace, this one excluded — it is not a peer of itself. */
+  peers(): CodePeer[] {
+    const dir = path.join(this.#dir, "live");
+    if (!existsSync(dir)) return [];
+    const now = Date.now();
+    return readdirSync(dir)
+      .filter((entry) => entry.endsWith(".json"))
+      .map((entry) => CodeMailbox.#peer(path.join(dir, entry)))
+      .filter((peer): peer is CodePeer => !!peer && peer.id !== this.#id && now - peer.at < CodeMailbox.staleMs)
+      .sort((left, right) => right.at - left.at);
+  }
+
+  /** Resolves what a person typed — a name, or the front of an id — to exactly one peer. */
+  find(target: string) {
+    const needle = target.trim().toLowerCase();
+    const peers = this.peers();
+    const byName = peers.filter((peer) => peer.name.toLowerCase() === needle);
+    if (byName.length === 1) return byName[0];
+    const byPrefix = peers.filter((peer) => peer.id.startsWith(needle) || peer.name.toLowerCase().startsWith(needle));
+    return byPrefix.length === 1 ? byPrefix[0] : undefined;
+  }
+
+  send(to: string, text: string) {
+    const now = Date.now();
+    this.#sent = this.#sent.filter((at) => now - at < 60_000);
+    if (this.#sent.length >= CodeMailbox.sendsPerMinute)
+      throw new Error(`Too many messages: ${CodeMailbox.sendsPerMinute} a minute is the ceiling.`);
+    this.#sent.push(now);
+    const mail: CodeMail = { at: now, from: this.#id, fromName: this.#name, text };
+    mkdirSync(path.join(this.#dir, "inbox"), { recursive: true });
+    // Append, never rewrite: two senders may be writing at the same moment, and one line is one write.
+    appendFileSync(path.join(this.#dir, "inbox", `${to}.jsonl`), `${JSON.stringify(mail)}\n`);
+  }
+
+  #drain(): CodeMail[] {
+    const lines = CodeMailbox.#lines(this.inbox);
+    if (lines.length <= this.#read) return [];
+    const fresh = lines.slice(this.#read);
+    this.#read = lines.length;
+    return fresh
+      .map((line) => CodeMailbox.#parse(line))
+      .filter((mail): mail is CodeMail => !!mail?.text && typeof mail.from === "string");
+  }
+
+  static #peer(file: string) {
+    try {
+      const peer = JSON.parse(readFileSync(file, "utf8")) as CodePeer;
+      return typeof peer.id === "string" ? { ...peer, at: peer.at || statSync(file).mtimeMs } : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  static #lines(file: string) {
+    try {
+      return readFileSync(file, "utf8")
+        .split("\n")
+        .filter((line) => !!line.trim());
+    } catch {
+      return [];
+    }
+  }
+
+  static #parse(line: string) {
+    try {
+      return JSON.parse(line) as CodeMail;
+    } catch {
+      return undefined;
+    }
+  }
+}

package/codeAgent/agent/CodeSessionFork.ts

@@ -0,0 +1,71 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { codeAgentSessionName } from "akanjs/common";
+import { CodeSessionIndex } from "./CodeSessionIndex";
+
+interface CodeSessionRecord {
+  [key: string]: unknown;
+  type?: string;
+  id?: string;
+}
+
+/**
+ * Copies a session's file so one conversation can continue two ways.
+ *
+ * A fork is a file copy because that is exactly what a session is: an append-only log the engine replays. The
+ * copy is rewritten in one place — the `session` record's id — and then the two files know nothing about each
+ * other, which is the property that matters. Sharing an id instead would give two live agents one inbox, one
+ * presence entry and one resume target, and the second one to write would win silently.
+ */
+export class CodeSessionFork {
+  static fork(dir: string, id: string, name?: string) {
+    const source = CodeSessionIndex.fileOf(dir, id);
+    if (!source) throw new Error(`No stored session ${id} in ${dir}`);
+    const lines = readFileSync(source, "utf8")
+      .split("\n")
+      .filter((line) => !!line.trim());
+    if (!lines.length) throw new Error(`Session ${id} has nothing in it to fork`);
+    const at = new Date();
+    const forked = Bun.randomUUIDv7();
+    const records = lines
+      .map((line) => CodeSessionFork.#parse(line))
+      .filter((record): record is CodeSessionRecord => !!record);
+    const first = records.find((record) => record.type === "session");
+    if (!first) throw new Error(`Session ${id} carries no session record`);
+    first.id = forked;
+    first.timestamp = at.toISOString();
+    records.push(CodeSessionFork.#named(records, name ?? CodeSessionFork.#nameOf(records), at));
+    // The name is the timestamp the file was created plus the id, which is the shape the engine writes and
+    // what `CodeSessionIndex` matches on when a resume names one.
+    const file = path.join(dir, `${at.toISOString().replace(/[:.]/g, "-")}_${forked}.jsonl`);
+    writeFileSync(file, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`);
+    return { id: forked, file };
+  }
+
+  /** A rename is an appended record, so the fork is named by adding one rather than by editing the original. */
+  static #named(records: CodeSessionRecord[], name: string, at: Date) {
+    const parent = records.at(-1)?.id;
+    return {
+      type: "session_info",
+      id: randomBytes(4).toString("hex"),
+      parentId: typeof parent === "string" ? parent : null,
+      timestamp: at.toISOString(),
+      name,
+    };
+  }
+
+  static #nameOf(records: CodeSessionRecord[]) {
+    const named = records.filter((record) => record.type === "session_info").at(-1);
+    const current = typeof named?.name === "string" ? named.name : "";
+    return codeAgentSessionName(current ? `${current} fork` : "fork");
+  }
+
+  static #parse(line: string) {
+    try {
+      return JSON.parse(line) as CodeSessionRecord;
+    } catch {
+      return undefined;
+    }
+  }
+}

package/codeAgent/agent/CodeSessionIndex.ts

@@ -0,0 +1,104 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+export interface CodeSessionEntry {
+  id: string;
+  file: string;
+  /** What the session calls itself, when it was named. */
+  name: string | undefined;
+  /** The first thing the person asked, which is what a list of sessions is actually scanned for. */
+  opening: string;
+  updatedAt: number;
+  turns: number;
+}
+
+/**
+ * The sessions on disk, read as files rather than through the engine.
+ *
+ * The engine's session manager addresses one session at a time — it can open a file and append to it, and has
+ * nothing that enumerates the directory. The format is self-describing JSONL, so the listing is a read of
+ * lines we already own the shape of, and it costs no engine instance to produce.
+ */
+export class CodeSessionIndex {
+  /** Past this, a file is a session long enough that its opening lines are far from the interesting part. */
+  static readonly readLimit = 512 * 1024;
+
+  static list(dir: string, limit = 30): CodeSessionEntry[] {
+    if (!existsSync(dir)) return [];
+    const files = readdirSync(dir)
+      .filter((entry) => entry.endsWith(".jsonl"))
+      .map((entry) => path.join(dir, entry))
+      .map((file) => ({ file, updatedAt: CodeSessionIndex.#mtime(file) }))
+      .sort((left, right) => right.updatedAt - left.updatedAt)
+      .slice(0, limit);
+    return files
+      .map((entry) => CodeSessionIndex.#read(entry.file, entry.updatedAt))
+      .filter((entry): entry is CodeSessionEntry => !!entry);
+  }
+
+  static fileOf(dir: string, id: string) {
+    if (!existsSync(dir)) return undefined;
+    // The file name carries the id after its timestamp, so the directory is searched without reading anything.
+    const match = readdirSync(dir).find((entry) => entry.endsWith(`${id}.jsonl`) || entry === `${id}.jsonl`);
+    return match ? path.join(dir, match) : undefined;
+  }
+
+  static #mtime(file: string) {
+    try {
+      return statSync(file).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+
+  static #read(file: string, updatedAt: number): CodeSessionEntry | undefined {
+    const lines = CodeSessionIndex.#lines(file);
+    if (!lines.length) return undefined;
+    const entry: CodeSessionEntry = { id: "", file, name: undefined, opening: "", updatedAt, turns: 0 };
+    for (const line of lines) {
+      const record = CodeSessionIndex.#parse(line);
+      if (!record) continue;
+      if (record.type === "session" && typeof record.id === "string") entry.id = record.id;
+      // A rename appends a second entry rather than editing the first, so the last one on the file wins.
+      if (record.type === "session_info" && typeof record.name === "string") entry.name = record.name;
+      if (record.type !== "message") continue;
+      const message = record.message as { role?: string; content?: unknown } | undefined;
+      if (message?.role !== "user") continue;
+      entry.turns += 1;
+      if (!entry.opening) entry.opening = CodeSessionIndex.#text(message.content);
+    }
+    return entry.id ? entry : undefined;
+  }
+
+  static #lines(file: string) {
+    try {
+      if (statSync(file).size > CodeSessionIndex.readLimit) return [];
+      return readFileSync(file, "utf8")
+        .split("\n")
+        .filter((line) => !!line.trim());
+    } catch {
+      return [];
+    }
+  }
+
+  static #parse(line: string): { [key: string]: unknown; type?: string } | undefined {
+    try {
+      return JSON.parse(line) as { type?: string };
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** One line, always: the opening ask is a label in a list, and a pasted stack trace is not a label. */
+  static #text(content: unknown) {
+    const text =
+      typeof content === "string"
+        ? content
+        : Array.isArray(content)
+          ? content
+              .map((part) => (typeof part === "object" && part && "text" in part ? String(part.text) : ""))
+              .join(" ")
+          : "";
+    return text.replace(/\s+/g, " ").trim();
+  }
+}

package/codeAgent/agent/SubagentPool.ts

@@ -0,0 +1,173 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { type CodeAgentProfile, codeAgentReadOnlyBuiltins } from "akanjs/common";
+import { Type } from "typebox";
+import type { Workspace } from "../../commandDecorators";
+
+export interface SubagentPoolOptions {
+  workspace: Workspace;
+  cwd: string;
+  parent: CodeAgentProfile;
+  depth: number;
+  /** Progress and refusals reach the parent's host through this rather than through a new event kind. */
+  onNotice?: (message: string) => void;
+}
+
+const maxResultChars = 8_000;
+
+export type SubagentKind = keyof typeof SubagentPool.kinds;
+
+/**
+ * The `task` tool: run a narrowed copy of the agent on one question and bring back a summary.
+ *
+ * **Only the summary crosses back.** A subagent's whole transcript in the parent's context is the fastest way
+ * to spend a window, and the reason to spawn one is precisely that its reading should not become the parent's
+ * reading.
+ *
+ * **The budget is not optional.** Depth, concurrency and token ceilings are checked before a child exists,
+ * because a recursive `task` with no ceiling is a fork bomb that bills per token.
+ */
+export class SubagentPool {
+  /**
+   * What a sub-agent is allowed to be, and the only axis that matters: whether it can change the tree.
+   *
+   * A reader can be spawned for anything — the worst it costs is tokens. A writer works unwatched on the same
+   * checkout as its parent, so it is the one the parent has to ask for by name rather than get by default.
+   */
+  static readonly kinds = {
+    explore: {
+      readOnly: true,
+      desc: "reads, searches and reports back. It cannot write a file or run a command.",
+    },
+    code: {
+      readOnly: false,
+      desc: "makes the change itself, with the same tools as this session.",
+    },
+  } as const;
+
+  static readonly defaultKind: SubagentKind = "explore";
+
+  readonly #options: SubagentPoolOptions;
+  #running = 0;
+  #spent = 0;
+
+  constructor(options: SubagentPoolOptions) {
+    this.#options = options;
+  }
+
+  static extensionFor(options: SubagentPoolOptions): InlineExtension | undefined {
+    if (!options.parent.tools.subagent) return undefined;
+    if (options.depth >= options.parent.tools.subagent.maxDepth) return undefined;
+    const pool = new SubagentPool(options);
+    return { name: "akan-subagent", factory: (pi: ExtensionAPI) => pool.#register(pi) };
+  }
+
+  static readonly toolName = "task";
+
+  #register(pi: ExtensionAPI) {
+    pi.registerTool({
+      name: SubagentPool.toolName,
+      label: "Task",
+      description:
+        "Run a focused sub-agent on one self-contained question and get back its answer. Use it for searching and reading that would otherwise fill this conversation — the sub-agent's own reading does not come back, only its answer. Give it everything it needs: it cannot see this conversation.",
+      promptSnippet: "task: run a sub-agent on one self-contained question and get back only its answer",
+      parameters: Type.Object({
+        description: Type.String({ description: "Three to five words naming the task, for the activity log." }),
+        prompt: Type.String({
+          description: "The complete instruction. The sub-agent sees nothing of this conversation.",
+        }),
+        type: Type.Optional(
+          Type.Union(
+            Object.entries(SubagentPool.kinds).map(([kind, spec]) => Type.Literal(kind, { description: spec.desc })),
+            { description: `What the sub-agent may do. Defaults to ${SubagentPool.defaultKind}.` },
+          ),
+        ),
+      }),
+      execute: async (_id, params, signal) => {
+        const kind = (params.type ?? SubagentPool.defaultKind) as SubagentKind;
+        const refusal = this.#refuse();
+        if (refusal) return { content: [{ type: "text", text: refusal }], details: undefined, isError: true };
+        this.#running += 1;
+        // Said before it starts, not only when it ends: a turn that goes quiet for a minute while a child
+        // reads the repo is otherwise indistinguishable from a turn that has stopped responding.
+        this.#options.onNotice?.(`${kind} sub-agent · ${params.description}`);
+        try {
+          const text = await this.#run(kind, params.prompt, signal);
+          return { content: [{ type: "text", text }], details: undefined };
+        } finally {
+          this.#running -= 1;
+        }
+      },
+    });
+  }
+
+  #refuse() {
+    const budget = this.#options.parent.tools.subagent;
+    if (!budget) return "Sub-agents are disabled by this profile.";
+    if (this.#running >= budget.maxConcurrent)
+      return `Too many sub-agents are already running (limit ${budget.maxConcurrent}). Wait for one to finish.`;
+    if (this.#spent >= budget.budget)
+      return `The sub-agent token budget (${budget.budget}) is spent. Do the rest of this work yourself.`;
+    return undefined;
+  }
+
+  /**
+   * The child is the parent profile **narrowed** and never widened: in-memory sessions so nothing it does
+   * shows up in the workspace's session tree, no `AGENTS.md` — a sub-agent is asked one narrow question and
+   * the guide is 26k tokens of its budget — and no ability to ask a human, there being nobody on the other
+   * end of a nested turn. The skills stay: they are descriptions until one is needed, and the child writes
+   * code too.
+   */
+  static childOf(parent: CodeAgentProfile, kind: SubagentKind): CodeAgentProfile {
+    const budget = parent.tools.subagent;
+    return {
+      ...parent,
+      name: `${parent.name}:${kind}`,
+      tools: {
+        ...parent.tools,
+        // Filtered rather than replaced, so a kind can only ever take tools away from the parent: a child of
+        // a read-only session must not become the one thing in the tree that can write.
+        builtin: SubagentPool.kinds[kind].readOnly
+          ? parent.tools.builtin.filter((tool) => codeAgentReadOnlyBuiltins.includes(tool))
+          : parent.tools.builtin,
+        subagent: budget ? { ...budget, maxDepth: budget.maxDepth } : false,
+      },
+      session: { store: "memory", crossSession: false },
+      ui: { canPrompt: false },
+      context: { projectFiles: false, skills: parent.context.skills },
+    };
+  }
+
+  async #run(kind: SubagentKind, prompt: string, signal: AbortSignal | undefined) {
+    const { CodeAgent } = await import("./CodeAgent");
+    const budget = this.#options.parent.tools.subagent;
+    const child = SubagentPool.childOf(this.#options.parent, kind);
+    const agent = await CodeAgent.create({
+      workspace: this.#options.workspace,
+      cwd: this.#options.cwd,
+      profile: child,
+      apps: [],
+      depth: this.#options.depth + 1,
+    });
+    const abort = () => void agent.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      let answer = "";
+      agent.on((event) => {
+        if (event.type === "message" && event.role === "assistant") answer = event.text;
+      });
+      await agent.prompt(prompt);
+      await agent.waitForIdle();
+      this.#spent += agent.tokensUsed;
+      const ceiling = budget ? budget.budget : 0;
+      this.#options.onNotice?.(
+        `${kind} sub-agent finished, ${agent.tokensUsed} tokens (${this.#spent} of ${ceiling} spent)`,
+      );
+      return answer.length > maxResultChars
+        ? `${answer.slice(0, maxResultChars)}\n…(truncated)`
+        : answer || "(no answer)";
+    } finally {
+      signal?.removeEventListener("abort", abort);
+      agent.dispose();
+    }
+  }
+}

package/codeAgent/agent/akanCodeModel.ts

@@ -0,0 +1,81 @@
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+/**
+ * The engine's `Model` type lives in `@earendil-works/pi-ai` and is not re-exported from the package we depend
+ * on, so it is recovered from the one public function that returns it rather than by adding a dependency on a
+ * transitive package whose version we do not control.
+ */
+export type CodeAgentModel = NonNullable<ReturnType<ModelRegistry["find"]>>;
+
+export interface CodeAgentModelRef {
+  provider: string;
+  id: string;
+}
+
+/** DeepSeek's million-token window is what makes a 26k-token `AGENTS.md` affordable on every turn. */
+export const akanCodeDefaultModel: CodeAgentModelRef = { provider: "deepseek", id: "deepseek-v4-flash" };
+
+/**
+ * Models the catalogue declares text-only that take a picture anyway.
+ *
+ * `input` is the catalogue's claim, and a stale one is expensive in one direction only: with `image` missing
+ * the `read` tool refuses to hand the model a picture and a paste is refused before it is ever sent, so
+ * nothing ever finds out. Measured 2026-09-20 against the provider — `deepseek-v4-flash` answered "A red
+ * star." to `apps/akan/public/icon-192x192.png` and "Red" to the colour, over two requests.
+ *
+ * ⚠️ `deepseek-v4-pro` is **not** on this list. It answers 200 to the same request and then says it cannot
+ * view the image, which is not the same evidence, and guessing the family from one member is how the
+ * catalogue got it wrong in the first place.
+ */
+const catalogueMissesImages = new Set(["deepseek/deepseek-v4-flash"]);
+
+const correctInputs = (model: CodeAgentModel | undefined) => {
+  if (!model || model.input.includes("image")) return model;
+  if (!catalogueMissesImages.has(`${model.provider}/${model.id}`)) return model;
+  return { ...model, input: [...model.input, "image" as const] };
+};
+
+/**
+ * Resolves the model to run with, preferring an explicit request, then the default, then anything the user has
+ * credentials for.
+ *
+ * An empty API key produces a request that succeeds with no content rather than an error, so a provider with no
+ * configured auth is skipped here instead of answering with nothing three seconds later.
+ */
+export const akanCodeModel = async (registry: ModelRegistry, ref?: CodeAgentModelRef) => {
+  if (ref) {
+    const requested = registry.find(ref.provider, ref.id);
+    if (!requested) throw new Error(`Unknown model: ${ref.provider}/${ref.id}`);
+    if (!registry.hasConfiguredAuth(requested))
+      throw new Error(`No API key configured for ${ref.provider}. Set ${ref.provider.toUpperCase()}_API_KEY.`);
+    return correctInputs(requested);
+  }
+  const fallback = registry.find(akanCodeDefaultModel.provider, akanCodeDefaultModel.id);
+  if (fallback && registry.hasConfiguredAuth(fallback)) return correctInputs(fallback);
+  return correctInputs(registry.getAvailable()[0]);
+};
+
+/** A screenshot is worth attaching only to a model that can see it — after the catalogue has been corrected. */
+export const akanCodeModelSupportsImages = (model: CodeAgentModel | undefined) => !!model?.input.includes("image");
+
+/**
+ * Says so when the chosen model's window is too small for the compaction policy to leave room for a
+ * conversation.
+ *
+ * This is deliberately the **only** descriptor check. Two more obvious ones are wrong here: `maxTokens >=
+ * contextWindow` matches 153 of the engine's own 1,057 catalogue entries (`gpt-4` is declared 8192/8192, and
+ * several qwen models 262000/262000), and `reserveTokens > maxTokens` matches 145 — every model with a small
+ * output cap, which is normal, because the reserve is context headroom and the cap is output length. Both
+ * would cry wolf on one model in seven.
+ *
+ * ⚠️ **A wrong descriptor that is internally consistent cannot be detected here at all.** A custom model
+ * declaring a 65k window for a provider that serves 1M is coherent and simply false, and the only thing that
+ * catches it is a person seeing the number — which is why the session line prints it.
+ */
+export const akanCodeModelWarnings = (model: CodeAgentModel | undefined, compactionFloor: number) => {
+  if (!model) return [];
+  if (model.contextWindow >= compactionFloor) return [];
+  return [
+    `${model.provider}/${model.id} declares a ${model.contextWindow}-token context window, below the ${compactionFloor} the compaction policy needs, so every turn will compact immediately. Check the model entry in ~/.akan/code/models.json.`,
+  ];
+};

package/codeAgent/agent/akanCodePaths.ts

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+/**
+ * Where the shipped akan skills sit, which differs between the source tree and the bundle: the CLI's entry
+ * chunks are flattened into the package root, so `skills/` is a sibling of the caller there and one level up
+ * here, beside this folder. Same two-candidate shape the guidelines lookup uses.
+ */
+const builtinSkillsDir = () => {
+  const candidates = [path.join(import.meta.dir, "skills"), path.join(import.meta.dir, "..", "skills")];
+  return candidates.find((candidate) => existsSync(candidate));
+};
+
+/**
+ * Sessions live in the workspace — they are project history, and a second checkout of the same repo is a
+ * different project. Credentials live in the home directory instead: a repo directory is the one place a key
+ * must never be, because it is the place that gets committed, zipped and shared.
+ */
+export const akanCodePaths = {
+  workspaceDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code"),
+  sessionsDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "sessions"),
+  extensionsDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "extensions"),
+  skillsDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "skills"),
+  mailDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mail"),
+  builtinSkillsDir,
+  mcpFile: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mcp.json"),
+  globalDir: () => path.join(homedir(), ".akan", "code"),
+  authFile: () => path.join(homedir(), ".akan", "code", "auth.json"),
+  modelsFile: () => path.join(homedir(), ".akan", "code", "models.json"),
+} as const;