@akanjs/devkit 3.1.0-rc.0 → 3.1.0-rc.10

package/cloud/updatePackUpload.test.ts

@@ -13,13 +13,15 @@ interface Put {
   body: Uint8Array;
 }
 
-class FakeAkasys {
+class FakeCloudHost {
   readonly server: ReturnType<typeof Bun.serve>;
   readonly requests: Record<string, unknown>[] = [];
   readonly puts: Put[] = [];
   readonly commits: string[] = [];
-  putStatuses: number[] = [];
-  commitAnswers: number[] = [];
+  readonly registrations: Record<string, string>[] = [];
+  putStatuses: (number | Response)[] = [];
+  stallPuts: boolean = false;
+  commitAnswers: (number | [number, string] | Response)[] = [];
   release: Record<string, unknown> = { id: "release-1", status: "published", problems: [] };
   requestRefusal: Response | null = null;
 
@@ -35,7 +37,9 @@ class FakeAkasys {
     this.requests.length = 0;
     this.puts.length = 0;
     this.commits.length = 0;
+    this.registrations.length = 0;
     this.putStatuses = [];
+    this.stallPuts = false;
     this.commitAnswers = [];
     this.requestRefusal = null;
   }
@@ -59,23 +63,42 @@ class FakeAkasys {
         headers: Object.fromEntries(request.headers),
         body: new Uint8Array(await request.arrayBuffer()),
       });
-      return new Response(null, { status: this.putStatuses.shift() ?? 200 });
+      if (this.stallPuts) return await new Promise<Response>(() => undefined);
+      const answer = this.putStatuses.shift() ?? 200;
+      return answer instanceof Response ? answer : new Response(null, { status: answer });
     }
     if (url.pathname === "/api/commitUpdateUpload/project-1") {
       const { uploadId } = (await request.json()) as { uploadId: string };
       this.commits.push(uploadId);
-      const answer = this.commitAnswers.shift();
-      if (answer) return Response.json({ error: "release.error.uploadCommitInProgress" }, { status: answer });
+      const answer = this.#answer();
+      if (answer) return answer;
       return Response.json({ ...this.release, uploadId });
     }
+    if (url.pathname === "/api/registerAppBinary/project-1") {
+      const form = await request.formData();
+      this.registrations.push(
+        Object.fromEntries(
+          [...form.entries()].map(([key, value]) => [key, typeof value === "string" ? value : "<file>"]),
+        ),
+      );
+      return this.#answer() ?? Response.json({ id: "binary-1" });
+    }
     return new Response("not found", { status: 404 });
   }
+
+  #answer() {
+    const answer = this.commitAnswers.shift();
+    if (!answer) return null;
+    if (answer instanceof Response) return answer;
+    const [status, key] = typeof answer === "number" ? [answer, "release.error.uploadCommitInProgress"] : answer;
+    return Response.json({ error: key }, { status });
+  }
 }
 
 const makeDir = tempDirs("akan-update-upload-");
-const akasys = new FakeAkasys();
+const cloudHost = new FakeCloudHost();
 const api = new CloudApi({} as Workspace, {
-  host: akasys.host,
+  host: cloudHost.host,
   auth: { accessToken: { jwt: "jwt-1", refreshToken: null, expiresAt: null } },
 });
 const fields = { appName: "lu", target: "default", platform: "android" as const, channel: "develop", notes: null };
@@ -87,8 +110,8 @@ const archiveOf = async (bytes: string) => {
   return archive;
 };
 
-beforeEach(() => akasys.reset());
-afterAll(() => akasys.server.stop(true));
+beforeEach(() => cloudHost.reset());
+afterAll(() => cloudHost.server.stop(true));
 
 describe("UpdatePackUpload", () => {
   test("announces the archive's size and digest, PUTs it with nothing but its content type, then commits", async () => {
@@ -97,7 +120,7 @@ describe("UpdatePackUpload", () => {
     const release = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
 
     expect(release).toEqual({ id: "release-1", status: "published", problems: [], uploadId: "upload-1" });
-    expect(akasys.requests).toEqual([
+    expect(cloudHost.requests).toEqual([
       {
         ...fields,
         size: 10,
@@ -105,91 +128,178 @@ describe("UpdatePackUpload", () => {
         authorization: "Bearer jwt-1",
       },
     ]);
-    const [put] = akasys.puts;
+    const [put] = cloudHost.puts;
     expect(new TextDecoder().decode(put?.body)).toBe("pack bytes");
     expect(put?.headers["content-type"]).toBe("application/gzip");
     expect(put?.headers["content-length"]).toBe("10");
     expect(put?.headers.authorization).toBeUndefined();
     expect(Object.keys(put?.headers ?? {}).filter((name) => name.startsWith("x-amz-"))).toEqual([]);
-    expect(akasys.commits).toEqual(["upload-1"]);
+    expect(cloudHost.commits).toEqual(["upload-1"]);
   });
 
   test("takes one fresh ticket when storage answers 403, and gives up on the second without naming the URL", async () => {
     const archive = await archiveOf("pack");
-    akasys.putStatuses = [403];
+    cloudHost.putStatuses = [403];
 
     await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
-    expect(akasys.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-2"]);
-    expect(akasys.commits).toEqual(["upload-2"]);
+    expect(cloudHost.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-2"]);
+    expect(cloudHost.commits).toEqual(["upload-2"]);
 
-    akasys.reset();
-    akasys.putStatuses = [403, 403];
+    cloudHost.reset();
+    cloudHost.putStatuses = [403, 403];
     const refusal = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields).catch((e: Error) => e);
     expect(String(refusal)).toContain("HTTP 403");
     expect(String(refusal)).not.toContain("secret-signature");
-    expect(akasys.commits).toEqual([]);
+    expect(cloudHost.commits).toEqual([]);
   });
 
   test("retries a PUT the way curl --retry does, and stops at a refusal that is not transient", async () => {
     const archive = await archiveOf("pack");
-    akasys.putStatuses = [503, 502];
+    cloudHost.putStatuses = [503, 502];
     await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
-    expect(akasys.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-1", "upload-1"]);
+    expect(cloudHost.puts.map(({ uploadId }) => uploadId)).toEqual(["upload-1", "upload-1", "upload-1"]);
 
-    akasys.reset();
-    akasys.putStatuses = [400];
+    cloudHost.reset();
+    cloudHost.putStatuses = [400];
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("HTTP 400");
-    expect(akasys.puts).toHaveLength(1);
+    expect(cloudHost.puts).toHaveLength(1);
   });
 
   test("asks again with the same id while the commit is cut off or still running, but not past a real answer", async () => {
     const archive = await archiveOf("pack");
-    akasys.commitAnswers = [524, 409, 502];
+    cloudHost.commitAnswers = [524, 409, 502];
     await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
-    expect(akasys.commits).toEqual(["upload-1", "upload-1", "upload-1", "upload-1"]);
+    expect(cloudHost.commits).toEqual(["upload-1", "upload-1", "upload-1", "upload-1"]);
 
-    akasys.reset();
-    akasys.commitAnswers = [404];
+    cloudHost.reset();
+    cloudHost.commitAnswers = [404];
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("404");
-    expect(akasys.commits).toEqual(["upload-1"]);
+    expect(cloudHost.commits).toEqual(["upload-1"]);
 
-    akasys.reset();
-    akasys.commitAnswers = Array.from({ length: 100 }, () => 524);
+    cloudHost.reset();
+    cloudHost.commitAnswers = Array.from({ length: 100 }, () => 524);
     const cutOff = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 35, commitLimitMs: 10_000 };
     await expect(new UpdatePackUpload(api, "project-1", cutOff).send(archive, fields)).rejects.toThrow("524");
-    expect(akasys.commits.length).toBeLessThan(6);
+    expect(cloudHost.commits.length).toBeLessThan(6);
   });
 
   test("keeps waiting on a live claim past the cut-off window, up to the overall limit", async () => {
     const archive = await archiveOf("pack");
-    akasys.commitAnswers = [...Array.from({ length: 6 }, () => 409), 524, ...Array.from({ length: 6 }, () => 409)];
+    cloudHost.commitAnswers = [...Array.from({ length: 6 }, () => 409), 524, ...Array.from({ length: 6 }, () => 409)];
     const timing = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 25, commitLimitMs: 10_000 };
     await new UpdatePackUpload(api, "project-1", timing).send(archive, fields);
-    expect(akasys.commits).toHaveLength(14);
+    expect(cloudHost.commits).toHaveLength(14);
 
-    akasys.reset();
-    akasys.commitAnswers = Array.from({ length: 100 }, () => 409);
+    cloudHost.reset();
+    cloudHost.commitAnswers = Array.from({ length: 100 }, () => 409);
     const limited = { putRetryMs: 1, commitRetryMs: 10, cutOffWindowMs: 10_000, commitLimitMs: 35 };
     await expect(new UpdatePackUpload(api, "project-1", limited).send(archive, fields)).rejects.toThrow("409");
-    expect(akasys.commits.length).toBeLessThan(6);
+    expect(cloudHost.commits.length).toBeLessThan(6);
+  });
+
+  test("gives up a stalled PUT after a time its size sets, and tries it again as a dropped one", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.stallPuts = true;
+
+    await expect(
+      new UpdatePackUpload(api, "project-1", { ...quick, putTimeoutMs: 50 }).send(archive, fields),
+    ).rejects.toThrow("no response");
+    expect(cloudHost.puts).toHaveLength(4);
+    expect(cloudHost.commits).toEqual([]);
+  });
+
+  test("asks again past a gateway's 503, but not past one the server answers with its own refusal", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.commitAnswers = [
+      new Response("No healthy federation child is ready", { status: 503 }),
+      [503, "base.error.serverUnavailable"],
+    ];
+    await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
+    expect(cloudHost.commits).toEqual(["upload-1", "upload-1", "upload-1"]);
+
+    cloudHost.reset();
+    cloudHost.commitAnswers = [[503, "release.error.signingUnavailable"]];
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow(
+      "release.error.signingUnavailable",
+    );
+    expect(cloudHost.commits).toEqual(["upload-1"]);
   });
 
   test("tells a server without staged uploads apart from one whose 404 is a refusal", async () => {
     const archive = await archiveOf("pack");
-    akasys.requestRefusal = new Response("Not Found", { status: 404 });
+    cloudHost.requestRefusal = new Response("Not Found", { status: 404 });
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow(
       "does not take direct pack uploads yet",
     );
 
-    akasys.requestRefusal = Response.json({ error: "devProject.error.appNotFound", statusCode: 404 }, { status: 404 });
+    cloudHost.requestRefusal = Response.json(
+      { error: "devProject.error.appNotFound", statusCode: 404 },
+      { status: 404 },
+    );
     const refusal = await new UpdatePackUpload(api, "project-1", quick).send(archive, fields).catch((e: Error) => e);
     expect(String(refusal)).toContain("devProject.error.appNotFound");
-    expect(akasys.puts).toEqual([]);
+    expect(cloudHost.puts).toEqual([]);
+  });
+
+  test("stops at once on a 409 that is not a commit in progress: the upload is already used", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.commitAnswers = [[409, "release.error.uploadEmbedded"]];
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("uploadEmbedded");
+    expect(cloudHost.commits).toHaveLength(1);
+  });
+
+  test("stages a binary's pack and registers it by upload id, asking again while the server is still at it", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.commitAnswers = [524, 409];
+    const upload = new UpdatePackUpload(api, "project-1", quick);
+    const binary = await upload.stage(archive, fields).then((packUploadId) =>
+      upload.settle(() =>
+        api.registerAppBinary("project-1", {
+          appName: "lu",
+          target: "default",
+          distribution: "playTesting",
+          bundle: new Blob(["{}"]),
+          packUploadId,
+          channel: "develop",
+        }),
+      ),
+    );
+
+    expect(binary).toEqual({ id: "binary-1" });
+    expect(cloudHost.commits).toEqual([]);
+    expect(cloudHost.registrations).toHaveLength(3);
+    expect(cloudHost.registrations[2]).toEqual({
+      appName: "lu",
+      target: "default",
+      distribution: "playTesting",
+      channel: "develop",
+      bundle: "<file>",
+      packUploadId: "upload-1",
+    });
+  });
+
+  test("waits as long as storage's Retry-After asks before trying a PUT again", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.putStatuses = [new Response(null, { status: 429, headers: { "Retry-After": "1" } })];
+    const startedAt = performance.now();
+
+    await new UpdatePackUpload(api, "project-1", quick).send(archive, fields);
+
+    expect(performance.now() - startedAt).toBeGreaterThanOrEqual(950);
+    expect(cloudHost.puts).toHaveLength(2);
+  });
+
+  test("never asks again sooner than the server's Retry-After, nor past the limit it would wait to", async () => {
+    const archive = await archiveOf("pack");
+    cloudHost.commitAnswers = [new Response("busy", { status: 503, headers: { "Retry-After": "120" } })];
+
+    await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("503");
+    expect(cloudHost.commits).toEqual(["upload-1"]);
   });
 
   test("refuses an empty archive before asking for a ticket", async () => {
     const archive = await archiveOf("");
     await expect(new UpdatePackUpload(api, "project-1", quick).send(archive, fields)).rejects.toThrow("0 bytes");
-    expect(akasys.requests).toEqual([]);
+    expect(cloudHost.requests).toEqual([]);
   });
 });

package/cloud/updatePackUpload.ts

@@ -1,22 +1,30 @@
 import { Logger, sleep } from "akanjs/common";
 import type { BunFile } from "bun";
-import { CloudApi, type CloudRecord, type UpdateUploadRequest } from "./cloudApi";
+import type { CloudApi, CloudRecord, UpdateUploadRequest } from "./cloudApi";
+import { CloudHttpError } from "./cloudHttpError";
 
 interface UpdatePackUploadOptions {
   putRetryMs?: number;
+  putTimeoutMs?: number;
   commitRetryMs?: number;
   cutOffWindowMs?: number;
   commitLimitMs?: number;
 }
 
 //* akasys sits behind Cloudflare's 100 s request cut, so the pack goes straight to its staging bucket and akasys
-//* only sees two small JSON calls: request a presigned PUT, then commit the object, which akasys re-hashes.
+//* only sees small calls: request a presigned PUT, then commit the object, or register a binary with it as its
+//* embedded pack; either re-hashes it, and an upload is used once, one way.
 export class UpdatePackUpload {
   static readonly maxBytes = 200 * 1024 * 1024;
   static readonly #transientPut = new Set([0, 408, 429, 500, 502, 503, 504]);
+  //? A stalled PUT never fails on its own, so each try ends once the pack would be through even at this crawl.
+  static readonly #putFloorBytesPerSecond = 64 * 1024;
+  //? Storage's Retry-After is honoured up to this: past it the presigned URL may lapse, and a fresh one is asked for.
+  static readonly #maxPutRetryAfterMs = 60_000;
   readonly #api: CloudApi;
   readonly #devProjectId: string;
   readonly #putRetryMs: number;
+  readonly #putTimeoutMs: number;
   readonly #commitRetryMs: number;
   readonly #cutOffWindowMs: number;
   readonly #commitLimitMs: number;
@@ -26,6 +34,7 @@ export class UpdatePackUpload {
     devProjectId: string,
     {
       putRetryMs = 1_000,
+      putTimeoutMs = 60_000,
       commitRetryMs = 10_000,
       cutOffWindowMs = 15 * 60_000,
       commitLimitMs = 60 * 60_000,
@@ -34,12 +43,19 @@ export class UpdatePackUpload {
     this.#api = api;
     this.#devProjectId = devProjectId;
     this.#putRetryMs = putRetryMs;
+    this.#putTimeoutMs = putTimeoutMs;
     this.#commitRetryMs = commitRetryMs;
     this.#cutOffWindowMs = cutOffWindowMs;
     this.#commitLimitMs = commitLimitMs;
   }
 
   async send(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<CloudRecord> {
+    const uploadId = await this.stage(archive, fields);
+    return await this.settle(() => this.#api.commitUpdateUpload(this.#devProjectId, uploadId));
+  }
+
+  /** Puts the pack in the project's staging storage and answers the upload id a commit or a registration names. */
+  async stage(archive: string, fields: Omit<UpdateUploadRequest, "size" | "sha256">): Promise<string> {
     const file = Bun.file(archive);
     if (file.size < 1 || file.size > UpdatePackUpload.maxBytes)
       throw new Error(`The pack archive is ${file.size} bytes; a project takes 1 byte to 200 MiB.`);
@@ -50,7 +66,7 @@ export class UpdatePackUpload {
     for (let ticket = 1; ; ticket++) {
       const { uploadId, uploadUrl, contentType } = await this.#request(upload);
       const status = await this.#put(uploadUrl, contentType, file);
-      if (status >= 200 && status < 300) return await this.#commit(uploadId);
+      if (status >= 200 && status < 300) return uploadId;
       if (status !== 403 || ticket === 2)
         throw new Error(`The storage refused the pack upload (${status ? `HTTP ${status}` : "no response"}).`);
     }
@@ -59,10 +75,9 @@ export class UpdatePackUpload {
   async #request(upload: UpdateUploadRequest) {
     return await this.#api.requestUpdateUpload(this.#devProjectId, upload).catch((error: unknown) => {
       //? A server older than staged uploads has no such route: its 404 is a page, where every refusal is an Err key.
-      const message = error instanceof Error ? error.message : String(error);
-      if (CloudApi.statusOf(error) === 404 && !/"error"\s*:\s*"[\w$-]+\.error\.[\w$-]+"/.test(message))
+      if (error instanceof CloudHttpError && error.status === 404 && !error.errKey)
         throw new Error(
-          "The project's server does not take direct pack uploads yet: update akasys and try again, or upload the pack from the project's release screen.",
+          "The project's server does not take direct pack uploads yet: update Akan Cloud and try again, or upload the pack from the project's release screen.",
         );
       throw error;
     });
@@ -71,45 +86,67 @@ export class UpdatePackUpload {
   // The URL signs only its host: an unsigned x-amz-* header (a checksum included) makes storage refuse the PUT.
   // A Bun fetch error names the URL, a bearer credential, so nothing but the status leaves this method.
   async #put(url: string, contentType: string, file: BunFile) {
+    const timeoutMs = this.#putTimeoutMs + Math.ceil((file.size / UpdatePackUpload.#putFloorBytesPerSecond) * 1000);
     for (let retry = 0; ; retry++) {
-      const status = await fetch(url, { method: "PUT", body: file, headers: { "Content-Type": contentType } })
+      const { status, retryAfterMs } = await fetch(url, {
+        method: "PUT",
+        body: file,
+        headers: { "Content-Type": contentType },
+        signal: AbortSignal.timeout(timeoutMs),
+      })
         .then(async (response) => {
           await response.arrayBuffer().catch(() => undefined);
-          return response.status;
+          return {
+            status: response.status,
+            retryAfterMs: CloudHttpError.retryAfterMs(response.headers.get("retry-after")),
+          };
         })
-        .catch(() => 0);
+        .catch(() => ({ status: 0, retryAfterMs: null }));
       if (retry === 3 || !UpdatePackUpload.#transientPut.has(status)) return status;
-      await sleep(this.#putRetryMs * (retry + 1));
+      await sleep(
+        Math.max(this.#putRetryMs * (retry + 1), Math.min(retryAfterMs ?? 0, UpdatePackUpload.#maxPutRetryAfterMs)),
+      );
     }
   }
 
-  // The server finishes a commit whoever stopped listening, and the same id answers the same release afterwards.
-  // A 409 is a live claim the server heartbeats, so only the overall limit bounds it; a run of cut-offs with no 409
-  // between them may be a server that died, whose claim lapses within minutes, so that run gets the shorter window.
-  async #commit(uploadId: string) {
+  /**
+   * Sends `call`, which consumes a staged upload, until the server answers it: the server finishes whoever stopped
+   * listening, and the same upload id answers the same record afterwards.
+   */
+  // `uploadCommitInProgress` is a live claim the server heartbeats, so only the overall limit bounds it; a run of
+  // cut-offs with none between them may be a server that died, whose claim lapses within minutes: the shorter window.
+  async settle<T>(call: () => Promise<T>): Promise<T> {
     const limit = performance.now() + this.#commitLimitMs;
     let cutOffSince: number | null = null;
     for (;;) {
       try {
-        return await this.#api.commitUpdateUpload(this.#devProjectId, uploadId);
+        return await call();
       } catch (error) {
         const now = performance.now();
-        if (CloudApi.statusOf(error) === 409) cutOffSince = null;
+        if (UpdatePackUpload.#inProgress(error)) cutOffSince = null;
         else if (UpdatePackUpload.#cutOff(error)) cutOffSince ??= now;
         else throw error;
         const deadline = cutOffSince === null ? limit : Math.min(limit, cutOffSince + this.#cutOffWindowMs);
-        if (now + this.#commitRetryMs > deadline) throw error;
-        Logger.rawLog(
-          `The project is still taking the pack; asking again in ${Math.round(this.#commitRetryMs / 1000)}s.`,
-        );
-        await sleep(this.#commitRetryMs);
+        const waitMs = Math.max(this.#commitRetryMs, (error instanceof CloudHttpError && error.retryAfterMs) || 0);
+        if (now + waitMs > deadline) throw error;
+        Logger.rawLog(`The project is still taking the pack; asking again in ${Math.round(waitMs / 1000)}s.`);
+        await sleep(waitMs);
       }
     }
   }
 
+  //? Not every 409: an upload already committed or embedded is answered 409 too, and asking again changes nothing.
+  static #inProgress(error: unknown) {
+    return (
+      error instanceof CloudHttpError && error.status === 409 && !!error.errKey?.endsWith(".uploadCommitInProgress")
+    );
+  }
+
   static #cutOff(error: unknown) {
-    const status = CloudApi.statusOf(error);
-    if (status === null) return !(error instanceof SyntaxError);
+    if (!(error instanceof CloudHttpError)) return !(error instanceof SyntaxError);
+    const { status, errKey } = error;
+    //? A gateway with no replica ready answers 503; the server's own 503 names an Err key and is a final refusal.
+    if (status === 503) return errKey === null || errKey === "base.error.serverUnavailable";
     return status === 502 || status === 504 || (status >= 520 && status <= 527);
   }
 }

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/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/tools/WebToolPack.ts

@@ -132,14 +132,14 @@ export class WebToolPack {
   /** Enough to read a documentation page; a full HTML parser is not worth a dependency for that. */
   static #readable(html: string) {
     return html
-      .replace(/<script[\s\S]*?<\/script>/gi, " ")
-      .replace(/<style[\s\S]*?<\/style>/gi, " ")
-      .replace(/<[^>]+>/g, " ")
+      .replace(/<script[\s\S]*?<\/script[^<>]*>/gi, " ")
+      .replace(/<style[\s\S]*?<\/style[^<>]*>/gi, " ")
+      .replace(/<[^<>]+>/g, " ")
       .replace(/&nbsp;/g, " ")
-      .replace(/&amp;/g, "&")
       .replace(/&lt;/g, "<")
       .replace(/&gt;/g, ">")
       .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, "&")
       .replace(/[ \t]+/g, " ")
       .replace(/\n{3,}/g, "\n\n")
       .trim();

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -247,22 +247,26 @@ describe("PreviewView", () => {
     expect(typeof PreviewView.available).toBe("boolean");
   });
 
-  test.skipIf(!PreviewView.available)("finds an empty body and a console error on a real page", async () => {
-    const server = Bun.serve({
-      port: 0,
-      fetch: () =>
-        new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
-          headers: { "content-type": "text/html" },
-        }),
-    });
-    try {
-      const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
-      expect(probe.pageErrors.join(" ")).toContain("rendered empty");
-      expect(probe.consoleErrors.join(" ")).toContain("boom");
-    } finally {
-      server.stop(true);
-    }
-  });
+  test.skipIf(!PreviewView.available)(
+    "finds an empty body and a console error on a real page",
+    async () => {
+      const server = Bun.serve({
+        port: 0,
+        fetch: () =>
+          new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
+            headers: { "content-type": "text/html" },
+          }),
+      });
+      try {
+        const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
+        expect(probe.pageErrors.join(" ")).toContain("rendered empty");
+        expect(probe.consoleErrors.join(" ")).toContain("boom");
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
 });
 
 describe("SubagentPool", () => {

package/commandDecorators/argMeta.ts

@@ -49,11 +49,15 @@ export interface ArgMeta<Context = CommandContext> {
   idx: number;
   type: ArgType;
 }
+export interface InternalArgOption {
+  nullable?: boolean;
+  onlyApp?: boolean;
+}
 export interface InternalArgMeta {
   key: string;
   idx: number;
   type: InternalArgType;
-  option?: { nullable?: boolean };
+  option?: InternalArgOption;
 }
 
 export const getArgMetas = (
@@ -69,9 +73,11 @@ export const getArgMetas = (
 export interface InternalArgToken<T = unknown, Type extends InternalArgType = InternalArgType> {
   type: Type;
   _value: T;
+  option?: InternalArgOption;
 }
 
-const createInternalArgToken = <T, Type extends InternalArgType>(type: Type) => ({ type }) as InternalArgToken<T, Type>;
+const createInternalArgToken = <T, Type extends InternalArgType>(type: Type, option?: InternalArgOption) =>
+  (option ? { type, option } : { type }) as InternalArgToken<T, Type>;
 
 export const normalizePrimitiveArgType = (type: PrimitiveArgType): NormalizedPrimitiveArgType => {
   if (type === String) return "string";
@@ -93,6 +99,9 @@ export type Lib = LibExecutor;
 export const Sys = createInternalArgToken<SysExecutor, "Sys">("Sys");
 export type Sys = SysExecutor;
 
+/** Sys, except that a one-app workspace given no name means its app, as with App. */
+export const SysOrOnlyApp = createInternalArgToken<SysExecutor, "Sys">("Sys", { onlyApp: true });
+
 export const Exec = createInternalArgToken<Executor, "Exec">("Exec");
 export type Exec = Executor;