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

package/README.md

@@ -44,6 +44,7 @@ await runner.build();
 - Command/script decorators used by `@akanjs/cli`.
 - AI prompt, guideline, and code-generation support utilities.
 - Capacitor and mobile release helpers.
+- The `akan code` agent engine, the tools it is given, and the shipped akan skills (`@akanjs/devkit/codeAgent`).
 
 ## Dev Server Sizing
 

package/cloud/cloudApi.ts

@@ -2,6 +2,11 @@ import type { Workspace } from "../commandDecorators";
 import type { AccessToken, AccessTokenDto, HostConfig } from "./constants";
 import { GlobalConfig } from "./globalConfig";
 
+interface HttpRequestOptions {
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
 class HttpClient {
   readonly baseUrl: string;
   readonly headers: Record<string, string> = {};
@@ -9,13 +14,14 @@ class HttpClient {
     this.baseUrl = baseUrl;
     this.headers = headers;
   }
-  async get<T>(url: string, { headers }: { headers?: Record<string, string> } = {}): Promise<T> {
+  async get<T>(url: string, { headers, signal }: HttpRequestOptions = {}): Promise<T> {
     const response = await fetch(`${this.baseUrl}${url}`, {
       headers: {
         "Content-Type": "application/json",
         ...this.headers,
         ...headers,
       },
+      ...(signal ? { signal } : {}),
     });
     return await HttpClient.#body<T>(response, url);
   }
@@ -26,7 +32,7 @@ class HttpClient {
     if (!response.ok) throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
     await Bun.write(localPath, response);
   }
-  async post<T>(url: string, data: unknown, { headers }: { headers?: Record<string, string> } = {}): Promise<T> {
+  async post<T>(url: string, data: unknown, { headers, signal }: HttpRequestOptions = {}): Promise<T> {
     const isFormData = data instanceof FormData;
     const response = await fetch(`${this.baseUrl}${url}`, {
       method: "POST",
@@ -34,6 +40,7 @@ class HttpClient {
       headers: isFormData
         ? { ...this.headers, ...headers }
         : { "Content-Type": "application/json", ...this.headers, ...headers },
+      ...(signal ? { signal } : {}),
     });
     return await HttpClient.#body<T>(response, url);
   }
@@ -153,9 +160,15 @@ export class CloudApi {
   async tunnelListInSelf(): Promise<TunnelSummary[]> {
     return await this.#api.get<TunnelSummary[]>(`/tunnel/tunnelListInSelf`);
   }
-  /** Hands the grant back. The CLI calls this "stop", which is what the operator is doing, not what it does. */
+  /**
+   * Hands the grant back. The CLI calls this "stop", which is what the operator is doing, not what it does.
+   *
+   * Bounded because every caller is on the way out: an unreachable control plane is exactly the state a session
+   * ends in, and an unbounded `fetch` there holds the event loop open long after the work is done. Losing the
+   * release costs nothing — the share expires on its own TTL.
+   */
   async revokeTunnel(code: string): Promise<boolean> {
-    return await this.#api.post<boolean>(`/tunnel/revokeTunnel`, { code });
+    return await this.#api.post<boolean>(`/tunnel/revokeTunnel`, { code }, { signal: AbortSignal.timeout(5_000) });
   }
   async getRemoteSelf(): Promise<{ id: string; nickname: string } | null> {
     try {

package/cloud/constants.ts

@@ -1,5 +1,4 @@
 import type { Dayjs } from "dayjs";
-import type { SupportedLlmModel } from "../aiEditor";
 import { GlobalConfig } from "./globalConfig";
 
 export const basePath = `${Bun.env.HOME ?? Bun.env.USERPROFILE}/.akan`;
@@ -28,12 +27,10 @@ export interface RemoteEnvServerConfig {
 export interface AkanGlobalConfig {
   cloudHost: { [key: string]: HostConfigDto };
   remoteEnvServers: Record<string, RemoteEnvServerConfig>;
-  llm: { model: SupportedLlmModel; apiKey: string } | null;
 }
 export const defaultAkanGlobalConfig: AkanGlobalConfig = {
   cloudHost: {},
   remoteEnvServers: {},
-  llm: null,
 };
 
 export interface AccessTokenDto {

package/cloud/globalConfig.ts

@@ -30,7 +30,7 @@ export class GlobalConfig {
     };
   }
   /**
-   * This file holds the cloud jwt, a refresh token that does not expire, and the LLM api key, so it is
+   * This file holds the cloud jwt and a refresh token that does not expire, so it is
    * written owner-only — the same `0600` the runtime gives its control socket. `Bun.write` takes no mode
    * and lands on `0666 & ~umask` (0644 on a default shell), so the mode is applied after the write; an
    * existing world-readable file is tightened by the next write rather than left as it was found.
@@ -49,14 +49,6 @@ export class GlobalConfig {
     akanConfig.cloudHost[config.host] = GlobalConfig.toHostConfigDto(config);
     await GlobalConfig.#setAkanGlobalConfig(akanConfig);
   }
-  static async getLlmConfig(): Promise<AkanGlobalConfig["llm"]> {
-    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
-    return akanConfig.llm ?? null;
-  }
-  static async setLlmConfig(llmConfig: AkanGlobalConfig["llm"]) {
-    const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
-    await GlobalConfig.#setAkanGlobalConfig({ ...akanConfig, llm: llmConfig });
-  }
   static async getRemoteEnvServers(): Promise<AkanGlobalConfig["remoteEnvServers"]> {
     const akanConfig = await GlobalConfig.#getAkanGlobalConfig();
     return akanConfig.remoteEnvServers;

package/codeAgent/agent/AkanAuthStorageBackend.ts

@@ -0,0 +1,105 @@
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import type { AuthStorageBackend } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Credential store for `akan code`, in akan's own file rather than the engine's.
+ *
+ * The engine only asks for a locked read-modify-write over one opaque string, so satisfying its interface with
+ * our own file keeps every key under `~/.akan/` — nothing lands in `~/.pi/` and a user who removes akan takes
+ * their credentials with them.
+ *
+ * The lock is an exclusive-create sentinel rather than an advisory flock: two `akan code` processes refreshing
+ * an OAuth token at the same moment would otherwise each write a token the other invalidates.
+ */
+export class AkanAuthStorageBackend implements AuthStorageBackend {
+  readonly #authPath: string;
+  readonly #lockPath: string;
+
+  constructor(authPath: string) {
+    this.#authPath = authPath;
+    this.#lockPath = `${authPath}.lock`;
+  }
+
+  withLock<T>(fn: (current: string | undefined) => { result: T; next?: string }) {
+    this.#acquire();
+    try {
+      const { result, next } = fn(this.#read());
+      if (next !== undefined) this.#write(next);
+      return result;
+    } finally {
+      this.#release();
+    }
+  }
+
+  async withLockAsync<T>(fn: (current: string | undefined) => Promise<{ result: T; next?: string }>) {
+    this.#acquire();
+    try {
+      const { result, next } = await fn(this.#read());
+      if (next !== undefined) this.#write(next);
+      return result;
+    } finally {
+      this.#release();
+    }
+  }
+
+  #read() {
+    if (!existsSync(this.#authPath)) return undefined;
+    const text = readFileSync(this.#authPath, "utf8");
+    return text.trim() ? text : undefined;
+  }
+
+  #write(next: string) {
+    mkdirSync(path.dirname(this.#authPath), { recursive: true, mode: 0o700 });
+    const temp = `${this.#authPath}.${process.pid}.tmp`;
+    writeFileSync(temp, next, { mode: 0o600 });
+    renameSync(temp, this.#authPath);
+  }
+
+  #acquire() {
+    mkdirSync(path.dirname(this.#lockPath), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + 5_000;
+    for (;;) {
+      try {
+        closeSync(openSync(this.#lockPath, "wx"));
+        return;
+      } catch {
+        // A lock left behind by a killed process would block every later run, so it expires.
+        if (this.#lockIsStale() || Date.now() > deadline) {
+          try {
+            unlinkSync(this.#lockPath);
+          } catch {
+            // Another process won the race to clear it; retry the create.
+          }
+          continue;
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+      }
+    }
+  }
+
+  #lockIsStale() {
+    try {
+      return Date.now() - Bun.file(this.#lockPath).lastModified > 30_000;
+    } catch {
+      return true;
+    }
+  }
+
+  #release() {
+    try {
+      unlinkSync(this.#lockPath);
+    } catch {
+      // Already gone — a stale-lock sweep by another process.
+    }
+  }
+}

package/codeAgent/agent/AkanCodeServices.ts

@@ -0,0 +1,104 @@
+import { existsSync, mkdirSync } from "node:fs";
+import {
+  AuthStorage,
+  type InlineExtension,
+  ModelRegistry,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { CodeAgentProfile } from "akanjs/common";
+import { AkanEnvKeys } from "../tools/AkanEnvKeys";
+import { AkanAuthStorageBackend } from "./AkanAuthStorageBackend";
+import { akanCodePaths } from "./akanCodePaths";
+import { akanSystemPrompt } from "./akanSystemPrompt";
+import { CodeSessionIndex } from "./CodeSessionIndex";
+
+export interface AkanCodeServicesOptions {
+  workspaceRoot: string;
+  cwd: string;
+  profile: CodeAgentProfile;
+  extensions: InlineExtension[];
+  sessionId?: string;
+}
+
+/**
+ * Assembles the engine's injectable services from akan's own storage.
+ *
+ * Every one of the five is passed explicitly. Leave any of them out and the engine falls back to `~/.pi/` —
+ * measured: with all five injected it writes nothing outside the paths named here.
+ */
+export class AkanCodeServices {
+  static settings() {
+    // Settings are in memory on purpose: the engine's file settings would be a second configuration surface
+    // beside `akan.config.ts` with its own precedence, for options akan already decides through the profile.
+    // `enableInstallTelemetry` defaults to true and attaches pi-branded headers to OpenRouter, NVIDIA and
+    // Cloudflare requests, so it is turned off here rather than per host — a host that changes provider later
+    // would otherwise turn it back on without meaning to.
+    return SettingsManager.inMemory({
+      enableInstallTelemetry: false,
+      enableAnalytics: false,
+      quietStartup: true,
+    });
+  }
+
+  static auth(workspaceRoot: string) {
+    mkdirSync(akanCodePaths.globalDir(), { recursive: true, mode: 0o700 });
+    const authStorage = AuthStorage.fromStorage(new AkanAuthStorageBackend(akanCodePaths.authFile()));
+    AkanEnvKeys.apply(authStorage, workspaceRoot);
+    return authStorage;
+  }
+
+  static models(authStorage: AuthStorage) {
+    return ModelRegistry.create(authStorage, akanCodePaths.modelsFile());
+  }
+
+  static sessions(workspaceRoot: string, cwd: string, profile: CodeAgentProfile, resume?: string) {
+    if (profile.session.store !== "file") return SessionManager.inMemory(cwd);
+    const dir = akanCodePaths.sessionsDir(workspaceRoot);
+    mkdirSync(dir, { recursive: true });
+    const manager = SessionManager.create(cwd, dir);
+    if (!resume) return manager;
+    const file = CodeSessionIndex.fileOf(dir, resume);
+    // A mistyped id that quietly opened a new session would look like a session that lost its history.
+    if (!file) throw new Error(`No stored session ${resume} in ${dir}`);
+    manager.setSessionFile(file);
+    return manager;
+  }
+
+  /**
+   * The akan skill set, then the workspace's own.
+   *
+   * A path that does not exist is a reported load error rather than a skip, so both are checked first.
+   */
+  static #skillPaths(profile: CodeAgentProfile, workspaceRoot: string) {
+    if (!profile.context.skills) return [];
+    const workspace = akanCodePaths.skillsDir(workspaceRoot);
+    return [akanCodePaths.builtinSkillsDir(), existsSync(workspace) ? workspace : undefined].filter(
+      (dir): dir is string => !!dir,
+    );
+  }
+
+  /**
+   * What the engine's resource loader may discover. Extensions and skills come from the workspace, never from
+   * the home directory: a coding agent that picks up a globally installed extension behaves differently in two
+   * checkouts of the same repo for reasons nothing in the repo explains.
+   */
+  static resourceOptions(options: AkanCodeServicesOptions) {
+    // A path that does not exist is reported as a load error rather than skipped, and these two are optional.
+    const present = (dir: string) => (existsSync(dir) ? [dir] : []);
+    return {
+      noExtensions: true,
+      // Always on: it turns off the engine's *default* skill locations, which are `~/.pi/skills` and the
+      // checkout's own `.pi/`. Explicit `additionalSkillPaths` are merged either way, so this is the switch
+      // that keeps a skill in whoever's home directory from changing how the agent works here.
+      noSkills: true,
+      noPromptTemplates: true,
+      noThemes: true,
+      noContextFiles: !options.profile.context.projectFiles,
+      appendSystemPrompt: [akanSystemPrompt(options.profile)],
+      additionalExtensionPaths: present(akanCodePaths.extensionsDir(options.workspaceRoot)),
+      additionalSkillPaths: AkanCodeServices.#skillPaths(options.profile, options.workspaceRoot),
+      extensionFactories: options.extensions,
+    };
+  }
+}