@akanjs/devkit 3.1.1 → 3.1.2-rc.1

package/codeAgent/agent/akanSystemPrompt.ts

@@ -31,6 +31,10 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
     lines.push(
       `- Some tool calls need the user's approval (policy: ${profile.approval}). A refusal is an answer; do not retry it a different way.`,
     );
+  if (profile.network.askOutside)
+    lines.push(
+      "- `web_fetch` to a host outside a short list of documentation sites, and a shell command that reaches the network (`curl`, `wget`, `ssh`, …), wait for the user's approval. A refusal is an answer; do not retry it a different way.",
+    );
   lines.push(
     "- Secrets are refused at the tool boundary. If you need a value from `.env`, ask the user for it rather than looking for another way to read the file.",
     "",

package/codeAgent/agent/codeAgentContract.test.ts

@@ -1,4 +1,7 @@
 import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import {
   CodeAgentClient,
   type CodeAgentEvent,
@@ -119,6 +122,12 @@ describe("codeAgentPresets", () => {
     expect(codeAgentPresets.pod(root).tools.mcp).toBe("off");
   });
 
+  test("only the local profile asks before reaching a host off its list", () => {
+    expect(codeAgentPresets.local(root).network.askOutside).toContain("github.com");
+    for (const name of ["pod", "review", "web"] as const)
+      expect(codeAgentPresets[name](root).network.askOutside).toBeUndefined();
+  });
+
   test("isCodeAgentPresetName refuses an unknown name", () => {
     expect(isCodeAgentPresetName("local")).toBe(true);
     expect(isCodeAgentPresetName("prod")).toBe(false);
@@ -407,6 +416,116 @@ describe("CodeAgentGate bash", () => {
   });
 });
 
+describe("CodeAgentGate secrets", () => {
+  const gate = () => new CodeAgentGate(codeAgentPresets.local(root));
+
+  test("a per-environment server env file is refused for read, write and shell, and its loader is not", () => {
+    const file = "apps/a/env/env.server.main.ts";
+    expect(gate().verdict("read", { path: file }).block).toContain("deny list");
+    expect(gate().verdict("write", { path: file }).block).toContain("deny list");
+    expect(gate().verdict("bash", { command: `cat ${file}` }).block).toBeDefined();
+    expect(gate().verdict("read", { path: "apps/a/env/env.server.ts" })).toEqual({});
+    expect(gate().verdict("read", { path: "apps/a/env/env.server.type.ts" })).toEqual({});
+  });
+
+  test("the engine's own spellings of a path are read as the path they name", () => {
+    expect(gate().verdict("read", { path: "@.env" }).block).toContain("deny list");
+    expect(gate().verdict("read", { path: `file://${root}/apps/a/.env` }).block).toContain("deny list");
+    expect(gate().verdict("read", { path: "~/notes.md" }).block).toContain("outside the agent root");
+  });
+
+  test("a shell command naming the home credential stores or a wildcard for a secret file is refused", () => {
+    expect(gate().verdict("bash", { command: "cat ~/.akan/code/auth.json" }).block).toBeDefined();
+    expect(gate().verdict("bash", { command: "cat $HOME/.ssh/id_ed25519" }).block).toBeDefined();
+    expect(gate().verdict("bash", { command: "cat .e?v" }).block).toBeDefined();
+    expect(gate().verdict("bash", { command: "cat .akan/code/mcp.json" }).block).toBeDefined();
+    expect(gate().verdict("bash", { command: "grep -r TODO --include=*.ts ." })).toEqual({});
+  });
+
+  test("a link inside the root is judged by the file it points at", () => {
+    const linked = mkdtempSync(path.join(tmpdir(), "akan-gate-"));
+    try {
+      mkdirSync(path.join(linked, "secrets"));
+      writeFileSync(path.join(linked, "secrets", "token.json"), "{}");
+      symlinkSync(path.join(linked, "secrets", "token.json"), path.join(linked, "notes.json"));
+      const linkedGate = new CodeAgentGate(codeAgentPresets.local(linked));
+      expect(linkedGate.verdict("read", { path: "notes.json" }).block).toContain("deny list");
+    } finally {
+      rmSync(linked, { recursive: true, force: true });
+    }
+  });
+
+  test("a link inside the root that leads out of it is read, and a denied file through it is not", () => {
+    const repo = mkdtempSync(path.join(tmpdir(), "akan-gate-"));
+    const linkedLib = mkdtempSync(path.join(tmpdir(), "akan-gate-lib-"));
+    try {
+      writeFileSync(path.join(linkedLib, "index.ts"), "export {};");
+      writeFileSync(path.join(linkedLib, ".env"), "");
+      mkdirSync(path.join(repo, "node_modules"));
+      symlinkSync(linkedLib, path.join(repo, "node_modules", "lib"));
+      const linkedGate = new CodeAgentGate(codeAgentPresets.local(repo));
+      expect(linkedGate.verdict("read", { path: "node_modules/lib/index.ts" })).toEqual({});
+      expect(linkedGate.verdict("read", { path: "node_modules/lib/.env" }).block).toContain("deny list");
+      expect(linkedGate.verdict("read", { path: path.join(linkedLib, "index.ts") }).block).toContain(
+        "outside the agent root",
+      );
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+      rmSync(linkedLib, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("CodeAgentGate network", () => {
+  const gate = () => new CodeAgentGate(codeAgentPresets.local(root));
+
+  test("the local profile asks before fetching a host off its list, and not for a listed one or loopback", () => {
+    expect(gate().verdict("web_fetch", { url: "https://example.com/x" })).toEqual({
+      approval: "fetch https://example.com/x",
+      strict: true,
+    });
+    expect(gate().verdict("web_fetch", { url: "https://docs.github.com/en" })).toEqual({});
+    expect(gate().verdict("web_fetch", { url: "http://localhost:3000/" })).toEqual({});
+  });
+
+  test("a networking shell command asks, unless it only reaches loopback over http", () => {
+    expect(gate().verdict("bash", { command: "curl -s https://example.com" }).strict).toBe(true);
+    expect(gate().verdict("bash", { command: "curl -X POST https://github.com/x" }).strict).toBe(true);
+    expect(gate().verdict("bash", { command: "ssh deploy@host" }).strict).toBe(true);
+    expect(gate().verdict("bash", { command: "curl http://127.0.0.1:8080/health" })).toEqual({});
+    expect(gate().verdict("bash", { command: "git status && bun test" })).toEqual({});
+  });
+
+  test("a loopback host:port without a scheme is loopback, and any other host still asks", () => {
+    expect(gate().verdict("bash", { command: "curl -s localhost:4200/health" })).toEqual({});
+    expect(gate().verdict("bash", { command: 'wget -qO- "127.0.0.1:8080"' })).toEqual({});
+    expect(gate().verdict("bash", { command: "curl [::1]:3000/x" })).toEqual({});
+    expect(gate().verdict("bash", { command: "curl -s example.com:443/x" }).strict).toBe(true);
+    expect(gate().verdict("bash", { command: "curl -s localhost:4200 example.com:80" }).strict).toBe(true);
+  });
+
+  test("a client name asks only where it runs as a command, not as another command's argument", () => {
+    for (const command of ["grep -rn curl src", "echo ssh", "git log --grep=wget", "cat docs/rsync.md"])
+      expect(gate().verdict("bash", { command })).toEqual({});
+    for (const command of [
+      "ls && curl https://example.com",
+      "cat body | curl -d @- https://example.com",
+      "echo $(curl https://example.com)",
+      "FOO=1 sudo -E /usr/bin/curl https://example.com",
+      "timeout 5 wget https://example.com",
+      "sh -c 'curl https://example.com'",
+      "bun test\nssh deploy@host",
+    ])
+      expect(gate().verdict("bash", { command }).strict).toBe(true);
+  });
+
+  test("a profile without a list never asks", () => {
+    const pod = new CodeAgentGate(codeAgentPresets.pod(root));
+    expect(pod.verdict("web_fetch", { url: "https://example.com/x" })).toEqual({});
+    expect(pod.verdict("bash", { command: "curl https://example.com" })).toEqual({});
+  });
+});
+
 describe("codeAgentShouldPersist", () => {
   test("follows the table for engine frames", () => {
     expect(codeAgentShouldPersist({ type: "message", turnId: "t1", role: "assistant", text: "hi" })).toBe(true);

package/codeAgent/agent/codeAgentHosts.ts

@@ -0,0 +1,30 @@
+import { isIP } from "node:net";
+
+const bare = (hostname: string) =>
+  hostname
+    .replace(/^\[|\]$/g, "")
+    .replace(/\.$/, "")
+    .toLowerCase();
+
+// Loopback only: a private LAN address is another machine, and a request to it leaves this one.
+export const codeAgentIsLoopback = (hostname: string) => {
+  const host = bare(hostname);
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  if (isIP(host) === 4) return host.startsWith("127.");
+  if (isIP(host) === 6) return host === "::1" || /^::ffff:(127\.\d+\.\d+\.\d+|7f[0-9a-f]{2}:[0-9a-f]{1,4})$/.test(host);
+  return false;
+};
+
+export const codeAgentHostListed = (hostname: string, hosts: readonly string[]) => {
+  const host = bare(hostname);
+  return hosts.some((entry) => host === entry || host.endsWith(`.${entry}`));
+};
+
+export const codeAgentHostOf = (url: string) => {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.hostname : undefined;
+  } catch {
+    return undefined;
+  }
+};

package/codeAgent/agent/codeAgentProxy.test.ts

@@ -1,9 +1,11 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { AkanCodeEnv } from "./AkanCodeEnv";
 import { AkanCodeServices } from "./AkanCodeServices";
 import { akanCodeDefaultModel, akanCodeModel } from "./akanCodeModel";
+import { akanCodePaths } from "./akanCodePaths";
 import { CodeAgentProxy } from "./CodeAgentProxy";
 
 const seen: { path: string; auth: string | null }[] = [];
@@ -72,3 +74,53 @@ describe("CodeAgentProxy", () => {
     expect(() => new CodeAgentProxy({ baseUrl: "https://proxy", providers: ["deepseek"] })).toThrow("TOKEN");
   });
 });
+
+describe("AkanCodeEnv", () => {
+  const inRepo = (dotenv: string | null, run: () => void) => {
+    const repo = mkdtempSync(path.join(tmpdir(), "akan-code-env-"));
+    const cwd = process.cwd();
+    const had = process.env.AKAN_CODE_PROXY_URL;
+    try {
+      if (dotenv !== null) writeFileSync(path.join(repo, ".env"), dotenv);
+      process.chdir(repo);
+      process.env.AKAN_CODE_PROXY_URL = "https://proxy.example/{provider}";
+      run();
+    } finally {
+      process.chdir(cwd);
+      if (had === undefined) delete process.env.AKAN_CODE_PROXY_URL;
+      else process.env.AKAN_CODE_PROXY_URL = had;
+      rmSync(repo, { recursive: true, force: true });
+    }
+  };
+
+  test("a setting the repo's own dotenv file names is ignored, and the start warning says so", () => {
+    inRepo("export AKAN_CODE_PROXY_URL=placeholder\n", () => {
+      expect(AkanCodeEnv.get("AKAN_CODE_PROXY_URL")).toBeUndefined();
+      expect(CodeAgentProxy.fromEnv()).toBeNull();
+      expect(AkanCodeEnv.ignored()).toEqual([expect.stringContaining("AKAN_CODE_PROXY_URL is set in .env")]);
+    });
+  });
+
+  test("a setting from the shell is read when no dotenv file names it", () => {
+    inRepo("OTHER_KEY=placeholder\n", () => {
+      expect(AkanCodeEnv.get("AKAN_CODE_PROXY_URL")).toBe("https://proxy.example/{provider}");
+      expect(AkanCodeEnv.ignored()).toEqual([]);
+    });
+  });
+
+  test.skipIf(process.platform === "win32")(
+    "the home directory is made owner-only, even one made looser before",
+    () => {
+      const loose = path.join(home, "loose-home");
+      mkdirSync(loose, { mode: 0o755 });
+      chmodSync(loose, 0o755);
+      process.env.AKAN_CODE_HOME = loose;
+      try {
+        akanCodePaths.ensureGlobalDir();
+        expect(statSync(loose).mode & 0o777).toBe(0o700);
+      } finally {
+        process.env.AKAN_CODE_HOME = home;
+      }
+    },
+  );
+});

package/codeAgent/agent/codeAgentRpcListener.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import type { CodeAgentEvent } from "akanjs/common";
@@ -44,23 +44,28 @@ class FakeAgent {
 
 class Client {
   lines: unknown[] = [];
+  readonly closed = Promise.withResolvers<void>();
   #buffer = "";
   #socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
-  static async connect(unix: string) {
+  static async connect(target: string | { port: number }) {
     const client = new Client();
-    client.#socket = await Bun.connect({
-      unix,
-      socket: {
-        data: (_socket, data) => {
-          client.#buffer += data.toString();
-          const parts = client.#buffer.split("\n");
-          client.#buffer = parts.pop() ?? "";
-          for (const part of parts) if (part) client.lines.push(JSON.parse(part));
-        },
+    const socket = {
+      data: (_socket: unknown, data: Buffer) => {
+        client.#buffer += data.toString();
+        const parts = client.#buffer.split("\n");
+        client.#buffer = parts.pop() ?? "";
+        for (const part of parts) if (part) client.lines.push(JSON.parse(part));
       },
-    });
+      close: () => client.closed.resolve(),
+    };
+    client.#socket = await (typeof target === "string"
+      ? Bun.connect({ unix: target, socket })
+      : Bun.connect({ hostname: "127.0.0.1", port: target.port, socket }));
     return client;
   }
+  raw(text: string) {
+    this.#socket?.write(text);
+  }
   send(id: string, command: object) {
     this.#socket?.write(`${JSON.stringify({ id, command })}\n`);
   }
@@ -81,10 +86,17 @@ describe("CodeAgentRpcListener", () => {
   test("parses unix and tcp addresses, defaulting tcp to loopback", () => {
     expect(CodeAgentRpcListener.parse("unix:/tmp/a.sock")).toEqual({ unix: "/tmp/a.sock" });
     expect(CodeAgentRpcListener.parse("tcp:7000")).toEqual({ hostname: "127.0.0.1", port: 7000 });
-    expect(CodeAgentRpcListener.parse("0.0.0.0:7000")).toEqual({ hostname: "0.0.0.0", port: 7000 });
+    expect(CodeAgentRpcListener.parse("tcp::7000")).toEqual({ hostname: "127.0.0.1", port: 7000 });
+    expect(CodeAgentRpcListener.parse("localhost:7000")).toEqual({ hostname: "localhost", port: 7000 });
     expect(() => CodeAgentRpcListener.parse("tcp:nope")).toThrow("--rpc-listen");
   });
 
+  test("a bind other machines could reach is refused unless it is asked for", () => {
+    expect(() => CodeAgentRpcListener.parse("0.0.0.0:7000")).toThrow("--rpc-bind-any");
+    expect(() => CodeAgentRpcListener.parse("tcp:192.168.0.2:7000")).toThrow("--rpc-bind-any");
+    expect(CodeAgentRpcListener.parse("0.0.0.0:7000", { anyHost: true })).toEqual({ hostname: "0.0.0.0", port: 7000 });
+  });
+
   test("the agent outlives a dropped client, and the next one catches up by seq", async () => {
     const agent = new FakeAgent();
     const unix = path.join(dir, "agent.sock");
@@ -110,4 +122,94 @@ describe("CodeAgentRpcListener", () => {
     await served;
     expect(agent.disposed).toBe(true);
   });
+
+  describe("over tcp", () => {
+    const opened = () => {
+      const agent = new FakeAgent();
+      const listener = new CodeAgentRpcListener(new CodeAgentRpcHost(agent as unknown as CodeAgent, null), {
+        hostname: "127.0.0.1",
+        port: 0,
+      }).listen();
+      return { agent, listener, port: listener.port ?? 0 };
+    };
+
+    test("a connection opened with the token is answered, and one without it is closed unheard", async () => {
+      const { agent, listener, port } = opened();
+      try {
+        expect(listener.token).toMatch(/^[A-Za-z0-9_-]{43}$/);
+        const anonymous = await Client.connect({ port });
+        anonymous.send("1", { type: "prompt", message: "hi" });
+        await anonymous.closed.promise;
+        expect(anonymous.lines).toEqual([{ type: "reply", id: "auth", ok: false, error: "unauthorized" }]);
+
+        const wrong = await Client.connect({ port });
+        wrong.raw(`${JSON.stringify({ auth: "not-the-token" })}\n`);
+        await wrong.closed.promise;
+        expect(agent.seq).toBe(1);
+
+        const client = await Client.connect({ port });
+        client.raw(
+          `${JSON.stringify({ auth: listener.token })}\n${JSON.stringify({ id: "2", command: { type: "prompt", message: "hi" } })}\n`,
+        );
+        expect((await client.reply("auth")).ok).toBe(true);
+        expect((await client.reply("2")).ok).toBe(true);
+        expect(client.lines.findIndex((line) => (line as { id?: string }).id === "auth")).toBe(0);
+        client.close();
+      } finally {
+        listener.stop();
+      }
+    });
+
+    test("a connection that speaks anything but a JSON frame is dropped at its first byte", async () => {
+      const { listener, port } = opened();
+      try {
+        const browser = await Client.connect({ port });
+        browser.raw("GET / HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n");
+        await browser.closed.promise;
+        expect(browser.lines).toEqual([]);
+      } finally {
+        listener.stop();
+      }
+    });
+
+    test("a connection that has not authenticated does not displace the client that has", async () => {
+      const { listener, port } = opened();
+      try {
+        const client = await Client.connect({ port });
+        client.raw(`${JSON.stringify({ auth: listener.token })}\n`);
+        await client.reply("auth");
+        const other = await Client.connect({ port });
+        other.raw("{");
+        await Bun.sleep(30);
+        client.send("3", { type: "get_state", sinceSeq: 0 });
+        expect((await client.reply("3")).ok).toBe(true);
+        other.close();
+        client.close();
+      } finally {
+        listener.stop();
+      }
+    });
+  });
+
+  test.skipIf(process.platform === "win32")(
+    "a unix socket is its owner's alone, and needs no token, though one is accepted",
+    async () => {
+      const agent = new FakeAgent();
+      const unix = path.join(dir, "owned.sock");
+      const listener = new CodeAgentRpcListener(new CodeAgentRpcHost(agent as unknown as CodeAgent, null), { unix });
+      listener.listen();
+      try {
+        expect(listener.token).toBeNull();
+        expect(statSync(unix).mode & 0o777).toBe(0o600);
+        const client = await Client.connect(unix);
+        client.raw(`${JSON.stringify({ auth: "anything" })}\n`);
+        expect((await client.reply("auth")).ok).toBe(true);
+        client.send("4", { type: "get_state", sinceSeq: 0 });
+        expect((await client.reply("4")).ok).toBe(true);
+        client.close();
+      } finally {
+        listener.stop();
+      }
+    },
+  );
 });

package/codeAgent/agent/stringArg.ts

@@ -1,4 +1,4 @@
-export const stringArg = (args: unknown, key: "path" | "command") => {
+export const stringArg = (args: unknown, key: "path" | "command" | "url") => {
   if (!args || typeof args !== "object") return undefined;
   const value = (args as Record<string, unknown>)[key];
   return typeof value === "string" && value ? value : undefined;

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

@@ -14,7 +14,10 @@ agent nothing, and only the current page's declarations are live.
 1. Mount `<Agent.Chat />` once, in a layout. It never executes tools: every tool runs in the caller's browser,
    gated by guards and the approval card.
 2. It refuses every call until `option.setAgentAccess(<guard>)` in `lib/option.ts` names who may use it
-   (`SignedIn` for a product with accounts). What a turn may ask is `option.setAgentRequestPolicy`.
+   (`SignedIn` for a product with accounts). What a turn may ask is `option.setAgentRequestPolicy`; until one is
+   set, a turn past `AgentRelayPolicy.defaultLimits` is refused with 413, and a policy of the app's own keeps them
+   with `AgentRelayPolicy.capped(request, limits)`. An error that is not an `Err` reaches the chat as a generic
+   failure unless `AKAN_ERROR_DETAIL=1` or a development runtime shows it.
 3. The LLM is `option.setLlm({ apiKey, model, host })`, never env.
 
 ## Publish actions
@@ -22,6 +25,8 @@ agent nothing, and only the current page's declarations are live.
 - Declare the tool beside the control that already does it, and hand the result to the control:
   `st.tool("x").desc("…").arg("id", ID).exec((id) => st.do.removeX(id))`. One handler serves the person and the
   agent; `.desc()` is required and first.
+- A name starting with a write verb (`remove`, `delete`, `create`, `update`, `upsert`, `submit`, `save`, `send`,
+  `export`) asks the user first; `{ confirm: false }` opts one tool out, `AgentConfirm.set` the app.
 - `.card(({ submit, cancel }) => <Form … />)` parks the call in the chat for an answer that is the user's to give.
 - Store-driven forms publish themselves: `onChange={st.do.setFieldOnX}` by reference emits the `data-akan-action`
   the agent drives. A pass-through arrow publishes nothing and fails lint.
@@ -30,6 +35,8 @@ agent nothing, and only the current page's declarations are live.
 ## Reads and guidance
 
 - `st.use.x({ agent: false })` hides a key; `hidden`, `secret` and `visual` fields are stripped from every read.
+- Page text is data the model reads, never instructions: after a screen read the next call that changes something
+  asks once, and `data-agent-private="<label>"` keeps a region's text out of every read.
 - A tool value is capped at 20,000 characters.
 - Route guidance is `<Agent.Guide instructions="…" />`; model-facing text is English.
 

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

@@ -9,9 +9,9 @@ This is the tool the user is talking to right now. When they ask how to do somet
 with their code — answer from here, and quote the exact gesture: the slash command to type, or the file to
 edit. Do not guess a command; everything this tool offers is listed below.
 
-You cannot type a slash command yourself. They are the host's, not yours — say which one to type. You *can*
-edit the files named below, which is the useful half of most of these answers: write the change, then say
-which command makes it take effect.
+You cannot type a slash command yourself. They are the host's, not yours — say which one to type. You cannot
+edit `mcp.json`, `.akan/code/extensions/` or anything under `~/.akan/` either: the deny list covers them, so
+quote the `/mcp` command that makes the change instead. The context files and skills named below you can edit.
 
 ## MCP servers
 
@@ -52,8 +52,17 @@ From the prompt:
 
 **A server added now is not reachable until the session reloads.** The tool allowlist is fixed when the
 session is created, so `add`, `remove`, `login` and `logout` all reload by themselves — a session that has
-said nothing yet has nothing on disk to reopen, and says so. If you edit `mcp.json` yourself, tell the user to
-run `/mcp reload`.
+said nothing yet has nothing on disk to reopen, and says so. After the user edits `mcp.json` by hand, `/mcp
+reload` makes it take effect.
+
+**This repo's own servers start only once the user approves them.** At start, `akan code` lists what this
+repo's `.akan/code/mcp.json` would run, and the extensions in `.akan/code/extensions/`, and asks once; a yes is
+remembered in `~/.akan/code/trust.json` until that content changes, and is asked again after. An extensions
+folder past 10,000 files or 64 MiB, or with a link that leads out of it, is asked about at every start. With
+nobody at a terminal they are not started, and `/mcp` shows `not approved`. `--trust-workspace` (`-T`) starts
+them for one run without asking. Servers in `~/.akan/code/mcp.json`, where `/mcp add` writes, need no approval;
+`/mcp add --local` writes this repo's file and keeps the approval it had, so a server added while that file
+waits for approval waits with it.
 
 `/mcp remove` on a name both files declare takes this repo's entry and leaves the home file's in force; its
 notice says so, and running it again removes that one too.
@@ -61,8 +70,9 @@ notice says so, and running it again removes that one too.
 Sign-in is discovered, not configured: the server's `401` names its resource metadata, that names the
 authorization server, and most hosted servers register a client on demand — so a url is usually the whole
 entry. For a provider that issues client ids by hand, add `"oauth": { "clientId": "…", "scope": "…" }`.
-Tokens are stored per server in `~/.akan/code/mcpAuth.json` at mode 0600, never in the repo, and refreshed
-silently — at connect when one has expired, and mid-session when a server refuses one, after which the call is
+Tokens are stored in `~/.akan/code/mcpAuth.json` at mode 0600, never in the repo, bound to the server's origin
+rather than its name — a server renamed in the file keeps its sign-in, and one moved to another url signs in
+again. They are refreshed silently — at connect when one has expired, and mid-session when a server refuses one, after which the call is
 retried once. When a refresh cannot fix it, `/mcp` shows `sign-in needed` and that server's tools answer with
 `/mcp login <name>` until the user signs in; the sign-in reloads the session, which brings the server back.
 
@@ -89,16 +99,19 @@ Stored under `.akan/code/sessions` — project history, so a second checkout of
 - A provider is authorized by **`<PROVIDER>_API_KEY`** — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`. The
   workspace's own `.env` is read as well as the environment, and a key found there is used for the run and
   never copied anywhere.
-- Credentials and the model catalogue live in `~/.akan/code/` (`auth.json`, `models.json`). **`AKAN_CODE_HOME`
-  moves the whole directory** — for a container with no home, or a checkout that wants its own.
+- Credentials and the model catalogue live in `~/.akan/code/` (`auth.json`, `models.json`), mode 0700.
+  **`AKAN_CODE_HOME` moves the whole directory** — for a container with no home, or a checkout that wants its
+  own. It, `AKAN_CODE_CAN_PROMPT`, the `AKAN_CODE_PROXY_*` settings and `AKAN_CODE_RPC_TOKEN_FILE` are read
+  from the shell only: one a repo's `.env` names is ignored, with a warning at start.
 
 ## What the agent reads, and how to change it
 
 - Every `AGENTS.md` / `CLAUDE.md` from the workspace root down to the working directory, `.cursorrules`, and
   any `.cursor/rules/*.mdc` that applies unconditionally (`alwaysApply: true`, or no frontmatter at all).
   Edit those to change how this agent behaves in this repo — they are the files the editor beside it reads.
-- Skills: drop a `<name>/SKILL.md` into `.akan/code/skills`. Extensions: `.akan/code/extensions`. Neither is
-  read from a home directory, so a session behaves the same in two checkouts.
+- Skills: drop a `<name>/SKILL.md` into `.akan/code/skills`. Extensions: `.akan/code/extensions`, loaded once
+  the user approves them (see MCP servers). Neither is read from a home directory, so a session behaves the
+  same in two checkouts.
 
 ## Keys
 
@@ -124,8 +137,21 @@ akan code -i "<prompt>"         open the session with the prompt already sent
 --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)
+--trust-workspace               start this repo's MCP servers and extensions without asking
+--no-ask-network                never ask before an unlisted host (local profile)
+--rpc-listen unix:<path>|tcp:[host:]<port>   serve the RPC wire on a socket instead of stdio
 ```
 
+`local` runs as the user: it refuses known secret files and the home credential stores, and asks before it
+fetches a page from a host off a short documentation list or a shell command that reaches the network
+(`curl`, `ssh`, …) — refused outright where nobody can answer, as in a one-shot `akan code "<prompt>"`. It is
+not a sandbox; `pod` in a container is.
+
+A `tcp:` listener asks every connection to open with `{"auth":"<token>"}` on its first line; the token is a
+fresh one in `~/.akan/code/rpc/<port>.token`, or the one in the file `AKAN_CODE_RPC_TOKEN_FILE` names.
+`--no-rpc-token` drops it, and only a loopback address is bound unless `--rpc-bind-any` is given. A unix
+socket is created owner-only and asks for no token.
+
 `review` reads and never writes, loads no project context files, and keeps no session on disk. `pod` has
 nobody in front of it: it cannot ask a question. MCP is off in both.
 

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

@@ -14,7 +14,8 @@ the server errors logged meanwhile, console errors and warnings, and layout smel
 - It uses the dev server that answers for this app and checkout. With none, it starts one for the run and
   stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a
   running one.
-- Paths are comma-separated and get the default locale when they lack one: `akan preview <app> /board,/board/new`.
+- Paths are comma-separated (`akan preview <app> /board,/board/new`) and get the default locale when they lack
+  one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off.
   `--changed` adds the pages your uncommitted page and layout edits reach. A dynamic route needs a concrete
   path (`/memo/1`); `akan context --app <app>` lists every route with its params and search names.
 - The viewport is a 390x844 phone; `--desktop` is 1280x800. `--csr` loads each page in the CSR boot the native

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

@@ -28,7 +28,8 @@ import path at all**, so keep throwing code out of them entirely rather than rea
 
 Best-effort code returns a sentinel (`null`, `undefined`, `{}`) instead of throwing. `try/catch` is rare and
 always converts an exception into a decision: a guard catches, warns, and returns `false`; an adapter
-catches, logs, and returns `null`. A store action never catches — let the framework toast the `Err`.
+catches, logs, and returns `null`. A store action never catches — let the framework toast the `Err`, or list it in
+the store's `static silent` when no screen waits on it and its caller handles the rejection.
 Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
 
 **A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(…, { origin })`

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

@@ -25,8 +25,9 @@ description: "Write filters, slices and list loading: query descriptors, init pa
   `purgeMany`, for data past retention.
 - A filter's `remove*` / `update*`, `updateById` and `removeById` run no hooks and no cascade. A model with a
   cascade or `_postRemove` removes through `remove<Model>(id)`.
-- Load a set once (`load<Model>Many`, one filter query) instead of one call per item in a loop — lint fails a
-  per-item service call an endpoint reaches.
+- Load a set once (`load<Model>Many`, one filter query) and create one with `create<Model>Many(rows)` instead of one
+  call per item in a loop — lint fails a per-item service call an endpoint reaches. `create<Model>Many` runs every
+  row's `_preCreate` before writing any, so a check there does not see the batch's own rows.
 
 ## Search and cascade
 

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

@@ -17,6 +17,7 @@ Domain code reaches none of them.
 | The production image | `docker: string \| { image, preRuns, postRuns, command }` |
 | iOS, Android, desktop | the `native` section; `desktop: { server: true }` carries the server |
 | SQLite, several databases, a cluster | `database: { modes: [...] }`, picked by `AKAN_DATABASE_MODE` |
+| URLs without `/<locale>/`: one language, or paths fixed from outside (OAuth callback, QR code, mail link) | `i18n: { localePrefix: "as-needed" }` — the default locale's pages and `<Link>` hrefs drop the prefix, other locales keep it |
 
 - `main.ts` imports `AkanApp` from `akanjs/server/akanApp`, never the barrel.
 - Never write `/api` or `/ws` literally, and never pass a prefix as a prop.
@@ -28,6 +29,8 @@ Domain code reaches none of them.
 - `akan start <app>` (`a,b` or `all` for several) runs the dev server; `akan build <app>` checks the production
   build. A supervised session writes `local/apps/<app>/runtime/dev.log` — hand over that path, not a paste of the
   live view. Tail with `akan logs <app>`.
+- Run a build without Docker with `cd dist/apps/<app> && bun main.js`: it boots with the env the Dockerfile sets,
+  read from `akan.env.json` beside it, and a variable you set yourself (`PORT=3000`) wins.
 - Give every log sink a floor (`Logger.addSink(sink, { minLevel })`) and never log once per delivered record.
 
 ## Native and desktop

package/codeAgent/tools/McpServerConfig.ts

@@ -42,16 +42,18 @@ export class McpServerConfig {
     ];
   }
 
-  static read(workspaceRoot: string): CodeAgentMcpServerRef[] {
-    return McpServerConfig.declared(workspaceRoot)
+  static read(workspaceRoot: string, scopes?: McpServerScope[]): CodeAgentMcpServerRef[] {
+    return McpServerConfig.declared(workspaceRoot, scopes)
       .filter((entry) => !entry.disabled)
       .map((entry) => entry.ref);
   }
 
   /** Every declared server including the disabled ones, which is what a listing has to show. */
-  static declared(workspaceRoot: string): McpDeclaredServer[] {
+  static declared(workspaceRoot: string, scopes?: McpServerScope[]): McpDeclaredServer[] {
     const byName = new Map<string, McpDeclaredServer>();
-    for (const { scope } of McpServerConfig.files(workspaceRoot))
+    for (const { scope } of McpServerConfig.files(workspaceRoot).filter(
+      (file) => !scopes || scopes.includes(file.scope),
+    ))
       for (const [name, entry] of Object.entries(McpServerConfig.#parse(workspaceRoot, scope).map))
         byName.set(name, { ref: McpServerConfig.#refOf(name, entry), disabled: !!entry.disabled, scope });
     return [...byName.values()];