akanjs 3.0.0-beta.14 → 3.0.0-beta.15

package/common/CodeAgentClient.ts

@@ -0,0 +1,102 @@
+import {
+  type CodeAgentCommand,
+  type CodeAgentEvent,
+  type CodeAgentFrame,
+  type CodeAgentRequest,
+  isCodeAgentReply,
+} from "./codeAgentWire";
+
+export interface CodeAgentTransport {
+  send(line: string): void | Promise<void>;
+  /** Called once with a handler that receives whole lines. */
+  onLine(handler: (line: string) => void): void;
+  close?(): void | Promise<void>;
+}
+
+interface PendingReply {
+  resolve: (data: unknown) => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Speaks the code-agent wire over any line transport — a child process's stdio, a websocket, an in-process pair.
+ *
+ * It has no dependencies because the browser holds one too. Everything host-specific (spawning, reconnecting,
+ * authenticating) belongs to whoever builds the transport.
+ */
+export class CodeAgentClient {
+  readonly #transport: CodeAgentTransport;
+  readonly #pending = new Map<string, PendingReply>();
+  readonly #listeners = new Set<(event: CodeAgentEvent) => void>();
+  #nextId = 0;
+  #lastSeq = 0;
+  #buffer = "";
+
+  constructor(transport: CodeAgentTransport) {
+    this.#transport = transport;
+    this.#transport.onLine((line) => this.#receive(line));
+  }
+
+  /** The highest sequence accepted. A reconnecting host replays from here. */
+  get lastSeq() {
+    return this.#lastSeq;
+  }
+
+  /** A new session restarts the sequence, so the watermark has to go with it or every frame reads as a duplicate. */
+  resetSeq() {
+    this.#lastSeq = 0;
+  }
+
+  on(listener: (event: CodeAgentEvent) => void) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  async send(command: CodeAgentCommand): Promise<unknown> {
+    this.#nextId += 1;
+    const id = `c${this.#nextId}`;
+    const request: CodeAgentRequest = { id, command };
+    const promise = new Promise<unknown>((resolve, reject) => this.#pending.set(id, { resolve, reject }));
+    await this.#transport.send(`${JSON.stringify(request)}\n`);
+    return await promise;
+  }
+
+  async close() {
+    for (const pending of this.#pending.values()) pending.reject(new Error("code agent transport closed"));
+    this.#pending.clear();
+    await this.#transport.close?.();
+  }
+
+  /** Feed raw chunks when the transport is byte-oriented rather than line-oriented. */
+  push(chunk: string) {
+    this.#buffer += chunk;
+    let index = this.#buffer.indexOf("\n");
+    while (index >= 0) {
+      const line = this.#buffer.slice(0, index);
+      this.#buffer = this.#buffer.slice(index + 1);
+      if (line.trim()) this.#receive(line);
+      index = this.#buffer.indexOf("\n");
+    }
+  }
+
+  #receive(line: string) {
+    let frame: CodeAgentFrame;
+    try {
+      frame = JSON.parse(line) as CodeAgentFrame;
+    } catch {
+      return;
+    }
+    if (isCodeAgentReply(frame)) {
+      const pending = this.#pending.get(frame.id);
+      if (!pending) return;
+      this.#pending.delete(frame.id);
+      if (frame.ok) pending.resolve(frame.data);
+      else pending.reject(new Error(frame.error ?? "code agent command failed"));
+      return;
+    }
+    if (frame.type !== "event") return;
+    if (frame.event.seq <= this.#lastSeq) return;
+    this.#lastSeq = frame.event.seq;
+    for (const listener of this.#listeners) listener(frame.event);
+  }
+}

package/common/CodeTranscript.ts

@@ -0,0 +1,337 @@
+import type {
+  CodeAgentApprovalRequest,
+  CodeAgentEvent,
+  CodeAgentQuestion,
+  CodeAgentSessionInfo,
+  CodeAgentStopReason,
+  CodeAgentToolOutcome,
+  CodeAgentToolSummary,
+} from "akanjs/common";
+
+export type CodeTranscriptPart =
+  | { kind: "user"; id: string; text: string; images?: number }
+  | { kind: "assistant"; id: string; text: string; streaming: boolean; truncated: boolean }
+  | { kind: "thinking"; id: string; text: string }
+  | {
+      kind: "tool";
+      id: string;
+      tool: CodeAgentToolSummary;
+      outcome?: CodeAgentToolOutcome;
+      output?: string;
+      progress?: string;
+    }
+  | { kind: "notice"; id: string; level: "info" | "warning" | "error"; text: string }
+  | { kind: "question"; id: string; question: CodeAgentQuestion; rendered?: string }
+  | { kind: "approval"; id: string; request: CodeAgentApprovalRequest; approved?: boolean }
+  | { kind: "host"; id: string; hostKind: string; text: string };
+
+/**
+ * Folds the akan wire into what a screen shows.
+ *
+ * It reads the contract and nothing else, so the terminal and a browser can share it — and so anything it
+ * cannot render is a hole in the contract rather than a missing feature of one host.
+ *
+ * ⚠️ **Tool and host rows are upserted by id, and the first row of a turn is index `0`.** A truthy check on the
+ * looked-up index sends that first `tool_end` down the append path, and the same call ends up on screen twice.
+ * `undefined` is the only absence here; `== null` would be wrong for the same reason.
+ */
+export class CodeTranscript {
+  readonly #parts: CodeTranscriptPart[] = [];
+  readonly #indexById = new Map<string, number>();
+  #info: CodeAgentSessionInfo | undefined;
+  #context: { used: number; max: number | undefined } | undefined;
+  #streaming = false;
+  #compacting = false;
+  #question: CodeAgentQuestion | undefined;
+  #approval: CodeAgentApprovalRequest | undefined;
+  #stopReason: CodeAgentStopReason | undefined;
+  #queue = { steering: 0, followUp: 0 };
+  #openAssistant: string | undefined;
+  #openThinking: string | undefined;
+  #nextId = 0;
+  #revision = 0;
+
+  get parts(): readonly CodeTranscriptPart[] {
+    return this.#parts;
+  }
+
+  get info() {
+    return this.#info;
+  }
+
+  /**
+   * The one line that says what this session is, derived here rather than by each host.
+   *
+   * The declared context window is on it deliberately: a model descriptor that is wrong but self-consistent —
+   * a 65k window declared for a provider that serves 1M — passes every programmatic check there is, and the
+   * only thing that catches it is a person reading the number.
+   */
+  get headline() {
+    if (!this.#info) return "starting…";
+    return [
+      this.#info.model?.name ?? "no model",
+      this.#info.contextTokens ? `${Math.round(this.#info.contextTokens / 1000)}k ctx` : "unknown ctx",
+      this.#info.profile,
+      this.#info.sessionId.slice(0, 8),
+    ].join(" · ");
+  }
+
+  get context() {
+    return this.#context;
+  }
+
+  get streaming() {
+    return this.#streaming;
+  }
+
+  get compacting() {
+    return this.#compacting;
+  }
+
+  get question() {
+    return this.#question;
+  }
+
+  get approval() {
+    return this.#approval;
+  }
+
+  get stopReason() {
+    return this.#stopReason;
+  }
+
+  get queue() {
+    return this.#queue;
+  }
+
+  /** Bumped on every applied event, so a view can tell "changed" from "same" without comparing arrays. */
+  get revision() {
+    return this.#revision;
+  }
+
+  /**
+   * Drops every row, keeping what the session *is*.
+   *
+   * Only the screen: the model's own window is untouched, so a cleared transcript and a fresh conversation are
+   * two different things and a host that offers this has to say which one it did.
+   */
+  clear() {
+    this.#revision += 1;
+    this.#parts.length = 0;
+    this.#indexById.clear();
+    this.#openAssistant = undefined;
+    this.#openThinking = undefined;
+  }
+
+  /**
+   * A locally typed prompt, shown before the engine echoes it back as a `message`.
+   *
+   * Attachments ride beside the text rather than in it: the engine's echo carries the words only, and the
+   * two rows are matched by text to keep one bubble.
+   */
+  echo(text: string, images = 0) {
+    this.#revision += 1;
+    this.#push({ kind: "user", id: this.#id(), text, ...(images ? { images } : {}) });
+  }
+
+  /** Something the host has to say — a slash-command answer, a key hint — in the same column as the rest. */
+  note(level: "info" | "warning" | "error", text: string) {
+    this.#revision += 1;
+    this.#notice(level, text);
+  }
+
+  apply(event: CodeAgentEvent) {
+    this.#revision += 1;
+    switch (event.type) {
+      case "session":
+        this.#info = event.info;
+        return;
+      case "turn_start":
+        this.#streaming = true;
+        this.#stopReason = undefined;
+        return;
+      case "turn_end":
+        this.#streaming = false;
+        this.#stopReason = event.stopReason;
+        this.#closeStreams(event.stopReason === "truncated");
+        return;
+      case "text_delta":
+        return this.#appendAssistant(event.text);
+      case "thinking_delta":
+        return this.#appendThinking(event.text);
+      case "message":
+        return this.#message(event.role, event.text);
+      case "tool_start":
+
+        this.#closeStreams(false);
+        return this.#upsertTool(event.tool, {});
+      case "tool_progress":
+        return this.#progress(event.toolCallId, event.text);
+      case "tool_end":
+        return this.#upsertTool(event.tool, { outcome: event.outcome, output: event.output });
+      case "question":
+        this.#question = event.question;
+        return this.#push({ kind: "question", id: event.question.questionId, question: event.question });
+      case "question_resolved":
+        if (this.#question?.questionId === event.questionId) this.#question = undefined;
+        return this.#patch(event.questionId, (part) => {
+          if (part.kind === "question") part.rendered = event.rendered;
+        });
+      case "approval":
+        this.#approval = event.request;
+        return this.#push({ kind: "approval", id: event.request.approvalId, request: event.request });
+      case "approval_resolved":
+        if (this.#approval?.approvalId === event.approvalId) this.#approval = undefined;
+        return this.#patch(event.approvalId, (part) => {
+          if (part.kind === "approval") part.approved = event.approved;
+        });
+      case "context":
+        this.#context = { used: event.used, max: event.max };
+        return;
+      case "compaction":
+        this.#compacting = event.phase === "start";
+        if (event.phase === "end") this.#notice("info", `Compacted the conversation (${event.reason}).`);
+        return;
+      case "retry":
+        return this.#notice(
+          "warning",
+          `Retrying (${event.attempt}/${event.maxAttempts}) in ${event.delayMs}ms — ${event.message}`,
+        );
+      case "queue":
+        this.#queue = { steering: event.steering.length, followUp: event.followUp.length };
+        return;
+      case "notice":
+        return this.#notice(event.level, event.message);
+      case "error":
+        return this.#notice("error", event.message);
+      case "idle":
+        this.#streaming = false;
+        this.#queue = { steering: 0, followUp: 0 };
+        this.#closeStreams(false);
+        return;
+      case "host":
+        return this.#host(event.kind, event.id, event.payload);
+      default:
+        return;
+    }
+  }
+
+  #id() {
+    this.#nextId += 1;
+    return `p${this.#nextId}`;
+  }
+
+  #push(part: CodeTranscriptPart) {
+    this.#indexById.set(part.id, this.#parts.length);
+    this.#parts.push(part);
+  }
+
+  #patch(id: string, mutate: (part: CodeTranscriptPart) => void) {
+    const index = this.#indexById.get(id);
+    if (index === undefined) return;
+    const part = this.#parts[index];
+    if (part) mutate(part);
+  }
+
+  #notice(level: "info" | "warning" | "error", text: string) {
+    this.#push({ kind: "notice", id: this.#id(), level, text });
+  }
+
+  #appendAssistant(text: string) {
+    if (this.#openAssistant === undefined) {
+      const id = this.#id();
+      this.#openAssistant = id;
+      this.#push({ kind: "assistant", id, text, streaming: true, truncated: false });
+      return;
+    }
+    this.#patch(this.#openAssistant, (part) => {
+      if (part.kind === "assistant") part.text += text;
+    });
+  }
+
+  #appendThinking(text: string) {
+    if (this.#openThinking === undefined) {
+      const id = this.#id();
+      this.#openThinking = id;
+      this.#push({ kind: "thinking", id, text });
+      return;
+    }
+    this.#patch(this.#openThinking, (part) => {
+      if (part.kind === "thinking") part.text += text;
+    });
+  }
+
+  /**
+   * The final message wins over the deltas that built it.
+   *
+   * A retried request streams its first attempt's tokens too, so a bubble assembled from deltas alone shows
+   * the abandoned answer followed by the real one.
+   */
+  #message(role: "user" | "assistant", text: string) {
+    if (role === "user") {
+
+      const last = this.#parts.at(-1);
+      if (last?.kind === "user" && last.text === text) return;
+      this.#push({ kind: "user", id: this.#id(), text });
+      return;
+    }
+    if (this.#openAssistant !== undefined) {
+      const open = this.#openAssistant;
+      this.#openAssistant = undefined;
+      this.#patch(open, (part) => {
+        if (part.kind !== "assistant") return;
+        part.text = text;
+        part.streaming = false;
+      });
+      return;
+    }
+    this.#push({ kind: "assistant", id: this.#id(), text, streaming: false, truncated: false });
+  }
+
+  #closeStreams(truncated: boolean) {
+    this.#openThinking = undefined;
+    const open = this.#openAssistant;
+    this.#openAssistant = undefined;
+    if (open === undefined) return;
+    this.#patch(open, (part) => {
+      if (part.kind !== "assistant") return;
+      part.streaming = false;
+      part.truncated = truncated;
+    });
+  }
+
+  #upsertTool(tool: CodeAgentToolSummary, result: { outcome?: CodeAgentToolOutcome; output?: string }) {
+    const index = this.#indexById.get(tool.toolCallId);
+    if (index === undefined) {
+      this.#push({ kind: "tool", id: tool.toolCallId, tool, ...result });
+      return;
+    }
+    const part = this.#parts[index];
+    if (part?.kind !== "tool") return;
+    
+    part.tool = tool;
+    if (result.outcome) part.outcome = result.outcome;
+    if (result.output !== undefined) part.output = result.output;
+  }
+
+  #progress(toolCallId: string, text: string) {
+    this.#patch(toolCallId, (part) => {
+      if (part.kind === "tool") part.progress = text;
+    });
+  }
+
+  #host(hostKind: string, id: string | undefined, payload: unknown) {
+    const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+    if (id === undefined) {
+      this.#push({ kind: "host", id: this.#id(), hostKind, text });
+      return;
+    }
+    const index = this.#indexById.get(id);
+    if (index === undefined) {
+      this.#push({ kind: "host", id, hostKind, text });
+      return;
+    }
+    const part = this.#parts[index];
+    if (part?.kind === "host") part.text = text;
+  }
+}

package/common/codeAgentProfile.ts

@@ -0,0 +1,175 @@
+/**
+ * What a code agent is allowed to be, as one value.
+ *
+ * The profile is read by both the host and the core, so it lives here rather than in the CLI. Most of it is
+ * applied at **assembly time** — a tool outside `tools` is never constructed, so the model cannot call it and
+ * it costs no prompt tokens either. The runtime hooks (`approval`, `paths`, `limits`) are the second gate, for
+ * the things assembly cannot decide in advance.
+ */
+
+export type CodeAgentBuiltinTool = "read" | "write" | "edit" | "ls" | "grep" | "find" | "bash";
+
+/** `never` trusts the environment, `all` trusts nothing. The middle two are the useful ones. */
+export type CodeAgentApprovalPolicy = "never" | "writes" | "commands" | "all";
+
+/**
+ * How the core behaves while a human is being asked something.
+ *
+ * `await` holds the turn open until the answer arrives. `suspend` resolves the request with a sentinel, ends the
+ * turn, and expects the host to reopen one carrying the answer — which is the only form that survives a process
+ * restart and does not hold a shared workspace for the minutes or days a person may take to answer.
+ */
+export type CodeAgentInteractionMode = "await" | "suspend";
+
+export interface CodeAgentMcpServerRef {
+  name: string;
+  transport: "stdio" | "http";
+  /** stdio: the executable and its argv. http: the endpoint. */
+  command?: string;
+  args?: string[];
+  url?: string;
+  env?: Record<string, string>;
+}
+
+export interface CodeAgentSubagentBudget {
+  maxDepth: number;
+  maxConcurrent: number;
+  /** Tokens a whole subagent tree may spend before the `task` tool refuses to open another. */
+  budget: number;
+}
+
+export interface CodeAgentProfile {
+  name: string;
+  tools: {
+    builtin: CodeAgentBuiltinTool[];
+    /** Workflow, context and self-verification tools built on devkit. */
+    akan: boolean;
+    /**
+     * `"off"` reaches no server at all. An array turns discovery on: the workspace's `.akan/code/mcp.json`
+     * plus whatever the array names, so the common case is an empty array.
+     */
+    mcp: "off" | CodeAgentMcpServerRef[];
+    subagent: false | CodeAgentSubagentBudget;
+    web: { fetch: boolean; search: boolean };
+  };
+  approval: CodeAgentApprovalPolicy;
+  paths: { root: string; allow?: string[]; deny?: string[] };
+  session: { store: "file" | "memory" | "remote"; crossSession: boolean };
+  interaction: { question: CodeAgentInteractionMode; approval: CodeAgentInteractionMode };
+  network: { allowHosts?: string[]; proxyBaseUrl?: string };
+  /** Whether the host can answer a question at all. A pod has nobody in front of it. */
+  ui: { canPrompt: boolean };
+  limits: {
+    turnMs: number;
+    toolOutputBytes: number;
+    contextTokens: number;
+    /** How many times one turn-end plugin may reopen a turn with the same finding before it gives up. */
+    feedback: number;
+  };
+  context: {
+    /** The repo's `AGENTS.md` is ~26k tokens; a read-only reviewer does not need it. */
+    projectFiles: boolean;
+    /**
+     * The akan skill set — the scaffolding chain, the store surface, the validation loop.
+     *
+     * Only each skill's one-line description sits in the window; the body is read when a task matches. That
+     * makes it the cheapest context of the three, and the most valuable to a profile carrying no `AGENTS.md`.
+     */
+    skills: boolean;
+  };
+}
+
+const allBuiltins: CodeAgentBuiltinTool[] = ["read", "write", "edit", "ls", "grep", "find", "bash"];
+/** The builtins that cannot change anything, which is what a profile is narrowed to when it must not. */
+export const codeAgentReadOnlyBuiltins: CodeAgentBuiltinTool[] = ["read", "ls", "grep", "find"];
+
+const baseLimits = { turnMs: 900_000, toolOutputBytes: 200_000, contextTokens: 0, feedback: 2 };
+
+/** Paths no profile may read, whatever its allowlist says. */
+export const codeAgentDeniedPaths = ["**/.env", "**/.env.*", "**/secrets/**", "**/*.pem", "**/*.key"];
+
+export const codeAgentPresets = {
+  local: (root: string): CodeAgentProfile => ({
+    name: "local",
+    tools: {
+      builtin: allBuiltins,
+      akan: true,
+      mcp: [],
+      subagent: { maxDepth: 2, maxConcurrent: 3, budget: 200_000 },
+      web: { fetch: true, search: true },
+    },
+    approval: "never",
+    paths: { root, deny: codeAgentDeniedPaths },
+    session: { store: "file", crossSession: true },
+    interaction: { question: "await", approval: "await" },
+    network: {},
+    ui: { canPrompt: true },
+    limits: baseLimits,
+    context: { projectFiles: true, skills: true },
+  }),
+  /**
+   * An isolated container. Everything is on because the container is the boundary, but nobody is watching it:
+   * a question that waits for an answer would hang the pod, so both interactions suspend. MCP is off because
+   * a pod's egress goes through a proxy and a stdio server started inside it is a process nobody vetted.
+   */
+  pod: (root: string): CodeAgentProfile => ({
+    name: "pod",
+    tools: {
+      builtin: allBuiltins,
+      akan: true,
+      mcp: "off",
+      subagent: { maxDepth: 2, maxConcurrent: 3, budget: 200_000 },
+      web: { fetch: true, search: true },
+    },
+    approval: "never",
+    paths: { root, deny: codeAgentDeniedPaths },
+    session: { store: "remote", crossSession: true },
+    interaction: { question: "suspend", approval: "suspend" },
+    network: {},
+    ui: { canPrompt: false },
+    limits: baseLimits,
+    context: { projectFiles: true, skills: true },
+  }),
+  /** A reviewer reads the repo and nothing else, so it reaches no external service. */
+  review: (root: string): CodeAgentProfile => ({
+    name: "review",
+    tools: {
+      builtin: codeAgentReadOnlyBuiltins,
+      akan: true,
+      mcp: "off",
+      subagent: { maxDepth: 1, maxConcurrent: 4, budget: 120_000 },
+      web: { fetch: false, search: false },
+    },
+    approval: "never",
+    paths: { root, deny: codeAgentDeniedPaths },
+    session: { store: "memory", crossSession: false },
+    interaction: { question: "await", approval: "await" },
+    network: {},
+    ui: { canPrompt: true },
+    limits: baseLimits,
+    context: { projectFiles: false, skills: true },
+  }),
+  /** Isolation and approval are different axes: a pod is safe and its user may still want to be asked. */
+  web: (root: string): CodeAgentProfile => ({
+    name: "web",
+    tools: {
+      builtin: allBuiltins,
+      akan: true,
+      mcp: [],
+      subagent: { maxDepth: 2, maxConcurrent: 3, budget: 200_000 },
+      web: { fetch: true, search: true },
+    },
+    approval: "writes",
+    paths: { root, deny: codeAgentDeniedPaths },
+    session: { store: "file", crossSession: true },
+    interaction: { question: "suspend", approval: "suspend" },
+    network: {},
+    ui: { canPrompt: true },
+    limits: baseLimits,
+    context: { projectFiles: true, skills: true },
+  }),
+} as const;
+
+export type CodeAgentPresetName = keyof typeof codeAgentPresets;
+
+export const isCodeAgentPresetName = (name: string): name is CodeAgentPresetName => name in codeAgentPresets;