@akanjs/devkit 3.0.0-beta.14 → 3.0.0-beta.16

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/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,
+    };
+  }
+}