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

package/codeAgent/agent/CodeAgent.ts

@@ -0,0 +1,543 @@
+import {
+  type AgentSession,
+  createAgentSession,
+  DEFAULT_COMPACTION_SETTINGS,
+  DefaultResourceLoader,
+  type ExtensionAPI,
+  type InlineExtension,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import {
+  type CodeAgentAnswer,
+  type CodeAgentEffort,
+  type CodeAgentEvent,
+  type CodeAgentEventBody,
+  type CodeAgentImage,
+  type CodeAgentProfile,
+  type CodeAgentQuestion,
+  type CodeAgentSessionInfo,
+  type CodeAgentState,
+  codeAgentClip,
+  codeAgentLabelChars,
+  codeAgentRenderAnswer,
+  codeAgentSessionName,
+} from "akanjs/common";
+import type { Workspace } from "../../commandDecorators";
+import { AkanCodePlugins } from "../tools/AkanCodePlugins";
+import { AkanCodeServices } from "./AkanCodeServices";
+import {
+  akanCodeModel,
+  akanCodeModelSupportsImages,
+  akanCodeModelWarnings,
+  type CodeAgentModelRef,
+} from "./akanCodeModel";
+import { akanCodePaths } from "./akanCodePaths";
+import { CodeAgentAsks } from "./CodeAgentAsks";
+import { CodeAgentEventMapper } from "./CodeAgentEventMapper";
+import { CodeAgentGate } from "./CodeAgentGate";
+import { CodeAgentUi } from "./CodeAgentUi";
+import { CodeMailbox } from "./CodeMailbox";
+import { CodeSessionFork } from "./CodeSessionFork";
+import { CodeSessionIndex } from "./CodeSessionIndex";
+
+/**
+ * What the engine calls a run mode. It is not re-exported from the package entry, so the literal set is
+ * restated here; it is the whole type, and a mismatch is a type error at the one call site that uses it.
+ */
+export type CodeAgentHostMode = "tui" | "rpc" | "json" | "print";
+
+export interface CodeAgentOptions {
+  workspace: Workspace;
+  cwd?: string;
+  profile: CodeAgentProfile;
+  model?: CodeAgentModelRef;
+  /** Apps whose dev server and preview the turn-end feedback loop watches. */
+  apps?: string[];
+  /** Extra capability packs, layered on top of the profile gate and the akan pack. */
+  extensions?: InlineExtension[];
+  customTools?: ToolDefinition[];
+  /** `print` for a one-shot stream, `rpc` when a host drives this process over stdio. */
+  mode?: CodeAgentHostMode;
+  /** How many `task` tools deep this agent already is. A sub-agent is created one level down. */
+  depth?: number;
+  /** Id of a stored session to continue instead of opening a new one. */
+  resume?: string;
+}
+
+/**
+ * The code agent core: one engine session, gated by a profile, emitting the akan wire.
+ *
+ * Nothing here knows what a host is. A host receives events, sends commands and injects a profile — which is
+ * what lets one core serve a terminal, an RPC child and a browser without three copies of the loop.
+ */
+export class CodeAgent {
+  readonly #profile: CodeAgentProfile;
+  readonly #gate: CodeAgentGate;
+  readonly #mapper = new CodeAgentEventMapper();
+  readonly #asks = new CodeAgentAsks();
+  readonly #listeners = new Set<(event: CodeAgentEvent) => void>();
+  #session: AgentSession | undefined;
+  #disposePlugins: (() => void) | undefined;
+  #seq = 0;
+  #disposed = false;
+  #sessionDir: string | undefined;
+  #mailbox: CodeMailbox | undefined;
+  /**
+   * The frames of the turn in flight, so a host that reconnects mid-turn can be handed what it missed.
+   *
+   * Bounded and cleared at `idle`: the completed messages of an earlier turn are in the transcript, and the
+   * only thing that exists nowhere else is the bubble still being written.
+   */
+  readonly #replay: CodeAgentEvent[] = [];
+  #replayFrom = 0;
+  #lastContextTokens: number | undefined;
+
+  private constructor(profile: CodeAgentProfile) {
+    this.#profile = profile;
+    this.#gate = new CodeAgentGate(profile);
+  }
+
+  static async create(options: CodeAgentOptions) {
+    const workspaceRoot = options.workspace.workspaceRoot;
+    const cwd = options.cwd ?? workspaceRoot;
+    const agent = new CodeAgent(options.profile);
+    const settingsManager = AkanCodeServices.settings();
+    const authStorage = AkanCodeServices.auth(workspaceRoot);
+    const modelRegistry = AkanCodeServices.models(authStorage);
+    const model = await akanCodeModel(modelRegistry, options.model);
+    const compaction = DEFAULT_COMPACTION_SETTINGS;
+    const modelWarnings = akanCodeModelWarnings(model, compaction.reserveTokens + compaction.keepRecentTokens);
+
+    const akan = await AkanCodePlugins.build({
+      workspace: options.workspace,
+      cwd,
+      profile: options.profile,
+      apps: options.apps ?? [],
+      canSeeImages: akanCodeModelSupportsImages(model),
+      depth: options.depth ?? 0,
+      currentSessionId: () => agent.sessionId,
+      mailbox: () => agent.#mailbox,
+      onNotice: (message) => agent.#emit({ type: "notice", level: "warning", message }),
+    });
+
+    const resourceLoader = new DefaultResourceLoader({
+      cwd,
+      agentDir: akanCodePaths.globalDir(),
+      settingsManager,
+      ...AkanCodeServices.resourceOptions({
+        workspaceRoot,
+        cwd,
+        profile: options.profile,
+        extensions: [agent.#gateExtension(), ...akan.extensions, ...(options.extensions ?? [])],
+      }),
+    });
+    await resourceLoader.reload();
+
+    const { session } = await createAgentSession({
+      cwd,
+      agentDir: akanCodePaths.globalDir(),
+      authStorage,
+      modelRegistry,
+      settingsManager,
+      resourceLoader,
+      model,
+      sessionManager: AkanCodeServices.sessions(workspaceRoot, cwd, options.profile, options.resume),
+      noTools: "builtin",
+      tools: [...options.profile.tools.builtin, ...akan.toolNames],
+      customTools: options.customTools,
+    });
+    agent.#disposePlugins = akan.dispose;
+    if (options.profile.session.store === "file") agent.#sessionDir = akanCodePaths.sessionsDir(workspaceRoot);
+    await agent.#attach(session, options.mode ?? "print");
+    if (agent.#sessionDir) agent.#openMail(akanCodePaths.mailDir(workspaceRoot), cwd);
+    for (const message of modelWarnings) agent.#emit({ type: "notice", level: "warning", message });
+    return agent;
+  }
+
+  get profile() {
+    return this.#profile;
+  }
+
+  /** Whether the model can be handed a picture at all, which decides whether offering to attach one is honest. */
+  get canSeeImages() {
+    const model = this.#session?.model;
+    return model ? akanCodeModelSupportsImages(model) : false;
+  }
+
+  /** The workspace's stored sessions, newest first. Empty on a profile that keeps none. */
+  sessions() {
+    return this.#sessionDir ? CodeSessionIndex.list(this.#sessionDir) : [];
+  }
+
+  /** The other `akan code` sessions running in this workspace right now. */
+  peers() {
+    return this.#mailbox?.peers() ?? [];
+  }
+
+  /**
+   * Hands a message to another session, which receives it as a prompt of its own.
+   *
+   * It is a prompt rather than a note on its screen because the point of reaching another session is to set
+   * it working — and it goes in as a follow-up, so a peer in the middle of a turn finishes that turn first.
+   */
+  send(target: string, text: string) {
+    const mailbox = this.#mailbox;
+    if (!mailbox) throw new Error("This profile keeps no shared mailbox, so it has no peers.");
+    const peer = mailbox.find(target);
+    if (!peer) throw new Error(`No live session matches "${target}". Ask for the list first.`);
+    mailbox.send(peer.id, text);
+    return peer;
+  }
+
+  #openMail(dir: string, cwd: string) {
+    const session = this.#session;
+    if (!session) return;
+    this.#mailbox = new CodeMailbox(dir, session.sessionId, session.sessionName ?? session.sessionId.slice(0, 8));
+    this.#mailbox.open(cwd, (mail) => {
+      const from = `${mail.fromName} (${mail.from.slice(0, 8)})`;
+      this.#emit({ type: "notice", level: "info", message: `message from ${from}` });
+      void this.prompt(`Message from another session — ${from}:\n${mail.text}`).catch((error: unknown) =>
+        this.#emit({ type: "notice", level: "error", message: String(error) }),
+      );
+    });
+  }
+
+  get sessionId() {
+    return this.#session?.sessionId ?? "";
+  }
+
+  get isStreaming() {
+    return this.#session?.isStreaming ?? false;
+  }
+
+  /** Total tokens this session has spent, which is what a sub-agent budget is drawn down against. */
+  get tokensUsed() {
+    return this.#session?.getSessionStats().tokens.total ?? 0;
+  }
+
+  get info(): CodeAgentSessionInfo {
+    const session = this.#require();
+    const model = session.model;
+    return {
+      sessionId: session.sessionId,
+      cwd: this.#profile.paths.root,
+      profile: this.#profile.name,
+      model: model ? { provider: model.provider, id: model.id, name: model.name } : undefined,
+      tools: session.getActiveToolNames(),
+      contextTokens: model?.contextWindow,
+      // A model that does no reasoning has no level to report, and `off` is a level — one of them is a
+      // capability and the other is a setting, so they cannot share a spelling.
+      effort: session.supportsThinking() ? session.thinkingLevel : undefined,
+      name: session.sessionName,
+      interaction: this.#profile.interaction,
+    };
+  }
+
+  /**
+   * Emits the opening `session` frame through the same counter as everything else.
+   *
+   * A frame minted outside it would carry `seq: 0`, which every client drops — their watermark starts there.
+   */
+  announce() {
+    this.#emit({ type: "session", info: this.info });
+    this.#restore();
+  }
+
+  /**
+   * Replays a resumed session's conversation onto the wire.
+   *
+   * The model gets its context back from the session file; a host gets nothing, because the wire only carries
+   * what happens live. Without this a resumed session is a blank screen in front of an agent that remembers
+   * everything — which reads as a resume that failed.
+   *
+   * Prose only: the tool traffic of a past turn is in the file, but replaying it would redraw calls nobody is
+   * waiting on, against a working tree that has moved since.
+   */
+  #restore() {
+    const session = this.#session;
+    if (!session) return;
+    const turnId = `restored:${session.sessionId}`;
+    for (const message of session.messages) {
+      if (message.role !== "user" && message.role !== "assistant") continue;
+      const text = CodeAgent.#textOf(message.content);
+      if (text) this.#emit({ type: "message", turnId, role: message.role, text });
+    }
+  }
+
+  static #textOf(content: unknown) {
+    if (typeof content === "string") return content.trim();
+    if (!Array.isArray(content)) return "";
+    return content
+      .map((part) => (typeof part === "object" && part && "text" in part ? String(part.text) : ""))
+      .join("")
+      .trim();
+  }
+
+  on(listener: (event: CodeAgentEvent) => void) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  /** One turn's worth of frames is kept for reconnection; a client further behind reloads the transcript. */
+  static readonly replayLimit = 2_000;
+
+  /**
+   * Current state, and the frames after `sinceSeq` when a reconnecting host asks for them.
+   *
+   * `replayFrom` says how far back the buffer reaches. A client behind it cannot be caught up frame by frame
+   * and has to reload — saying so is better than silently handing it a gap.
+   */
+  async state({ sinceSeq }: { sinceSeq?: number } = {}): Promise<CodeAgentState> {
+    const base = { info: this.info, streaming: this.isStreaming, replayFrom: this.#replayFrom };
+    if (sinceSeq === undefined) return base;
+    return { ...base, frames: this.#replay.filter((event) => event.seq > sinceSeq) };
+  }
+
+  async prompt(message: string, images?: CodeAgentImage[]) {
+    const session = this.#require();
+    // Named from the first thing asked of it, not from the answer: the name is derived, so waiting for the
+    // turn to end would only mean the session is nameless for exactly as long as it is interesting to watch.
+    if (!session.sessionName && message.trim()) this.setName(codeAgentSessionName(message));
+    const attachments = await CodeAgent.#attachments(images);
+    const options = attachments.length ? { images: attachments } : {};
+    if (session.isStreaming) return await session.prompt(message, { ...options, streamingBehavior: "followUp" });
+    await session.prompt(message, { ...options, source: "extension" });
+  }
+
+  async abort() {
+    // The engine finalizes an interrupted message as an ordinary stop, so the only party that knows this was
+    // an abort is the one that asked for it.
+    this.#mapper.noteOutcome("aborted");
+    this.#asks.clear();
+    await this.#require().abort();
+  }
+
+  /**
+   * Answering is not prompting. Routing an answer through `prompt` would open a turn while the question slot is
+   * still filled, leaving a card on screen that still looks clickable — the library does not stop that.
+   */
+  async answer(questionId: string, answer: CodeAgentAnswer) {
+    const question = this.#asks.questionOf(questionId);
+    const rendered = question ? codeAgentRenderAnswer(question, answer) : (answer.text ?? "");
+    if (this.#asks.answer(questionId, rendered)) {
+      this.#emit({ type: "question_resolved", questionId, answer, rendered });
+      return true;
+    }
+    if (this.#profile.interaction.question !== "suspend") return false;
+    this.#emit({ type: "question_resolved", questionId, answer, rendered });
+    // The answer has to reach the model as prose: compaction and the next turn read message content only, so
+    // an answer that exists solely as structure is one the agent will not remember being given.
+    await this.prompt(`The user answered: ${rendered}\nContinue the task.`);
+    return true;
+  }
+
+  async approve(approvalId: string, approved: boolean) {
+    if (this.#asks.resolveApproval(approvalId, approved)) {
+      this.#emit({ type: "approval_resolved", approvalId, approved });
+      return true;
+    }
+    if (this.#profile.interaction.approval !== "suspend") return false;
+    this.#emit({ type: "approval_resolved", approvalId, approved });
+    if (approved) await this.prompt("The user approved the pending action. Retry it and continue.");
+    return true;
+  }
+
+  async compact(instructions?: string) {
+    await this.#require().compact(instructions);
+  }
+
+  /** Renames the session and says so on the wire, because a host draws the name from the session frame. */
+  setName(name: string) {
+    const clean = name.trim();
+    if (!clean) return;
+    this.#require().setSessionName(clean);
+    this.#mailbox?.rename(clean, this.#profile.paths.root);
+    this.#emit({ type: "session", info: this.info });
+  }
+
+  /**
+   * Copies this session under a new id, so the conversation can be continued two ways.
+   *
+   * The copy is taken off disk rather than out of memory: the file is what a resume replays, so forking it is
+   * the only version of "the same conversation" that both agents will actually agree on.
+   */
+  fork(name?: string) {
+    if (!this.#sessionDir) throw new Error("This profile keeps no sessions on disk, so there is nothing to fork");
+    return CodeSessionFork.fork(this.#sessionDir, this.sessionId, name);
+  }
+
+  /** The reasoning levels this model offers, clamped by the engine to what the provider actually serves. */
+  efforts(): CodeAgentEffort[] {
+    const session = this.#session;
+    if (!session?.supportsThinking()) return [];
+    return session.getAvailableThinkingLevels();
+  }
+
+  setEffort(effort: CodeAgentEffort) {
+    const session = this.#require();
+    if (!session.supportsThinking()) throw new Error(`${session.model?.id ?? "this model"} does no reasoning`);
+    // The engine clamps rather than refuses, so the frame that follows is the level that took, not the one asked.
+    session.setThinkingLevel(effort);
+    this.#emit({ type: "session", info: this.info });
+  }
+
+  async setModel(ref: CodeAgentModelRef) {
+    const session = this.#require();
+    const model = await akanCodeModel(session.modelRegistry, ref);
+    if (!model) throw new Error(`Unknown model: ${ref.provider}/${ref.id}`);
+    await session.setModel(model);
+    this.#emit({ type: "session", info: this.info });
+  }
+
+  async waitForIdle() {
+    await this.#require().waitForIdle();
+  }
+
+  dispose() {
+    this.#mailbox?.close();
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.#asks.clear();
+    this.#listeners.clear();
+    this.#disposePlugins?.();
+    this.#session?.dispose();
+  }
+
+  async #attach(session: AgentSession, mode: CodeAgentHostMode) {
+    this.#session = session;
+    session.subscribe((event) => {
+      for (const body of this.#mapper.map(event)) this.#emit(body);
+      this.#emitContextUsage(event.type);
+    });
+    await session.bindExtensions({
+      mode,
+      uiContext: this.#ui().context(),
+      abortHandler: () => void session.abort(),
+      onError: (error: unknown) => this.#emit({ type: "error", message: String(error), fatal: false }),
+    });
+  }
+
+  /** A path is read here rather than by the host, so a browser and a terminal hand the core the same thing. */
+  static async #attachments(images: CodeAgentImage[] | undefined) {
+    if (!images?.length) return [];
+    return await Promise.all(
+      images.map(async (image) => {
+        if ("data" in image) return { type: "image" as const, data: image.data, mimeType: image.mime };
+        const file = Bun.file(image.path);
+        return {
+          type: "image" as const,
+          data: Buffer.from(await file.arrayBuffer()).toString("base64"),
+          mimeType: file.type || "image/png",
+        };
+      }),
+    );
+  }
+
+  /**
+   * Reports how full the window is, once per turn and after a compaction.
+   *
+   * Per turn rather than per delta: the number moves only when a provider response lands, and a frame per
+   * token delta would be thousands of frames saying the same thing. `tokens` is null right after a compaction
+   * and before the next response — that is "unknown", not zero, so nothing is emitted for it.
+   */
+  #emitContextUsage(eventType: string) {
+    if (eventType !== "agent_end" && eventType !== "compaction_end") return;
+    const usage = this.#session?.getContextUsage();
+    // `== null`, not `=== null`: the field is typed `number | null`, and a strict null check sails straight
+    // past an `undefined` the way the mirror of this bug does — which would emit `used: undefined`.
+    if (usage?.tokens == null) return;
+    if (usage.tokens === this.#lastContextTokens) return;
+    this.#lastContextTokens = usage.tokens;
+    this.#emit({ type: "context", used: usage.tokens, max: usage.contextWindow || undefined });
+  }
+
+  #require() {
+    if (!this.#session) throw new Error("CodeAgent is not started");
+    return this.#session;
+  }
+
+  #emit(body: CodeAgentEventBody) {
+    this.#seq += 1;
+    const event = { ...body, seq: this.#seq } as CodeAgentEvent;
+    this.#remember(event);
+    for (const listener of this.#listeners) listener(event);
+  }
+
+  #remember(event: CodeAgentEvent) {
+    if (event.type === "idle") {
+      this.#replay.length = 0;
+      this.#replayFrom = event.seq;
+      return;
+    }
+    this.#replay.push(event);
+    while (this.#replay.length > CodeAgent.replayLimit) {
+      const dropped = this.#replay.shift();
+      this.#replayFrom = dropped?.seq ?? this.#replayFrom;
+    }
+  }
+
+  #gateExtension(): InlineExtension {
+    return {
+      name: "akan-profile-gate",
+      factory: (pi: ExtensionAPI) => {
+        pi.on("tool_call", async (event) => {
+          const verdict = this.#gate.verdict(event.toolName, event.input);
+          if (verdict.block) return this.#refuse(event.toolCallId, event.toolName, event.input, verdict.block);
+          if (!verdict.approval) return undefined;
+          const approved = await this.#requestApproval(event.toolCallId, event.toolName, event.input, verdict.approval);
+          if (approved) return undefined;
+          return this.#refuse(event.toolCallId, event.toolName, event.input, "The user declined this action.");
+        });
+      },
+    };
+  }
+
+  #refuse(toolCallId: string, toolName: string, args: unknown, reason: string) {
+    for (const body of this.#mapper.markBlocked(toolCallId, toolName, args, reason)) this.#emit(body);
+    return { block: true, reason };
+  }
+
+  async #requestApproval(toolCallId: string, name: string, args: unknown, summary: string) {
+    // Nobody to ask means nobody to refuse: a pod would otherwise deny every write it was created to make.
+    if (!this.#profile.ui.canPrompt) return true;
+    const approvalId = this.#asks.nextId("a");
+    this.#emit({
+      type: "approval",
+      request: {
+        approvalId,
+        toolCallId,
+        name,
+        summary: codeAgentClip(summary, codeAgentLabelChars),
+        policy: this.#profile.approval,
+      },
+    });
+    if (this.#profile.interaction.approval === "suspend") {
+      this.#mapper.noteOutcome("awaiting");
+      return false;
+    }
+    return await this.#asks.openApproval(approvalId);
+  }
+
+  #ui() {
+    return new CodeAgentUi({
+      ask: async (prompt, kind, choices) => {
+        if (!this.#profile.ui.canPrompt) return undefined;
+        const questionId = this.#asks.nextId("q");
+        const question: CodeAgentQuestion = {
+          questionId,
+          prompt,
+          kind,
+          ...(choices ? { options: choices.map((label) => ({ key: label, label })) } : {}),
+          freeText: kind === "text",
+        };
+        this.#emit({ type: "question", question });
+        if (this.#profile.interaction.question === "suspend") {
+          this.#mapper.noteOutcome("awaiting");
+          return undefined;
+        }
+        return (await this.#asks.openQuestion(question)) || undefined;
+      },
+      notify: (level, message) => this.#emit({ type: "notice", level, message }),
+    });
+  }
+}

package/codeAgent/agent/CodeAgentAsks.ts

@@ -0,0 +1,87 @@
+import type { CodeAgentQuestion } from "akanjs/common";
+
+interface Deferred<T> {
+  resolve: (value: T) => void;
+  promise: Promise<T>;
+}
+
+/**
+ * Holds what the agent is waiting on a person for.
+ *
+ * A question is a **single slot**: asking one ends the turn, so a second cannot exist. An approval is a
+ * **queue**: "may I write this file" naturally arrives twice in a row while a turn is still running, and a
+ * single slot would drop the second silently.
+ *
+ * Idempotency is by id. Two browser tabs, or answering after a refresh, both produce a second answer for an id
+ * that is already resolved — which must be ignored rather than applied to whatever is pending now.
+ */
+export class CodeAgentAsks {
+  #question: { question: CodeAgentQuestion; deferred: Deferred<string> } | undefined;
+  readonly #approvals = new Map<string, Deferred<boolean>>();
+  #nextId = 0;
+
+  get pendingQuestionId() {
+    return this.#question?.question.questionId;
+  }
+
+  /** The open question, so an answer can be rendered against the options it was asked with. */
+  questionOf(questionId: string) {
+    return this.#question?.question.questionId === questionId ? this.#question.question : undefined;
+  }
+
+  get hasPendingApproval() {
+    return this.#approvals.size > 0;
+  }
+
+  nextId(prefix: string) {
+    this.#nextId += 1;
+    return `${prefix}${this.#nextId}`;
+  }
+
+  openQuestion(question: CodeAgentQuestion) {
+    // A question opened while one is already pending replaces it: the old turn is gone, so nobody is left to
+    // receive the old answer, and leaving it would strand the caller forever.
+    this.#question?.deferred.resolve("");
+    const deferred = CodeAgentAsks.#defer<string>();
+    this.#question = { question, deferred };
+    return deferred.promise;
+  }
+
+  answer(id: string, text: string) {
+    if (this.#question?.question.questionId !== id) return false;
+    const { deferred } = this.#question;
+    this.#question = undefined;
+    deferred.resolve(text);
+    return true;
+  }
+
+  openApproval(id: string) {
+    const deferred = CodeAgentAsks.#defer<boolean>();
+    this.#approvals.set(id, deferred);
+    return deferred.promise;
+  }
+
+  resolveApproval(id: string, approved: boolean) {
+    const deferred = this.#approvals.get(id);
+    if (!deferred) return false;
+    this.#approvals.delete(id);
+    deferred.resolve(approved);
+    return true;
+  }
+
+  /** Every pending ask dies with its turn — an approval outlives nothing, and a question is reopened on resume. */
+  clear() {
+    this.#question?.deferred.resolve("");
+    this.#question = undefined;
+    for (const deferred of this.#approvals.values()) deferred.resolve(false);
+    this.#approvals.clear();
+  }
+
+  static #defer<T>(): Deferred<T> {
+    let resolve: (value: T) => void = () => {};
+    const promise = new Promise<T>((r) => {
+      resolve = r;
+    });
+    return { resolve, promise };
+  }
+}