akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/common/codeAgentProfile.ts

@@ -0,0 +1,181 @@
+
+
+export type CodeAgentBuiltinTool = "read" | "write" | "edit" | "ls" | "grep" | "find" | "bash";
+
+/** `never` trusts the environment, `all` trusts nothing. */
+export type CodeAgentApprovalPolicy = "never" | "writes" | "commands" | "all";
+
+/** `await` holds the turn open; `suspend` ends it and the host reopens one carrying the answer (survives a restart). */
+export type CodeAgentInteractionMode = "await" | "suspend";
+
+export interface CodeAgentModelInfo {
+  id: string;
+  name: string;
+  contextWindow?: number;
+  /** The model the session is running on. */
+  current: boolean;
+}
+
+export interface CodeAgentProviderInfo {
+  id: string;
+  name: string;
+  authorized: boolean;
+  models: CodeAgentModelInfo[];
+}
+
+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>;
+  headers?: Record<string, string>;
+  /** For a server that answers `401` and whose OAuth client or scopes cannot be discovered. */
+  oauth?: { clientId?: string; clientSecret?: string; scope?: string };
+}
+
+/** `required` is not a failure: the server answered correctly and said who may talk to it. */
+export type CodeAgentMcpAuthState = "none" | "authorized" | "required";
+
+/** One declared MCP server; one that was never reachable is listed too, with its `error`. */
+export interface CodeAgentMcpStatus {
+  name: string;
+  transport: "stdio" | "http";
+  /** The command line or the url. */
+  target: string;
+  /** Published tool names, already prefixed with the server the way the model sees them. */
+  tools: string[];
+  /** Why it published none, when it published none. */
+  error?: string;
+  auth?: CodeAgentMcpAuthState;
+}
+
+export interface CodeAgentSubagentBudget {
+  maxDepth: number;
+  /** Subagents a whole tree may run at once; past it the `task` tool refuses instead of queueing. */
+  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; an array discovers `.akan/code/mcp.json` plus the servers it names. */
+    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 };
+  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: {
+    /** Whether the repo's `AGENTS.md` is loaded. */
+    projectFiles: boolean;
+    /** The akan skill set: only each skill's one-line description sits in the window until a task matches. */
+    skills: boolean;
+  };
+}
+
+const allBuiltins: CodeAgentBuiltinTool[] = ["read", "write", "edit", "ls", "grep", "find", "bash"];
+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 },
+  }),
+  
+  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 },
+  }),
+  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 },
+  }),
+  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;

package/common/codeAgentWire.ts

@@ -0,0 +1,305 @@
+import type { CodeAgentApprovalPolicy, CodeAgentInteractionMode, CodeAgentProfile } from "./codeAgentProfile";
+
+export const codeAgentWireVersion = 1;
+
+export const codeAgentLabelChars = 200;
+/** Clip length of a tool result on the wire; the model's own copy is not clipped. */
+export const codeAgentOutputChars = 2_000;
+
+export type CodeAgentEffort = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export interface CodeAgentSessionInfo {
+  sessionId: string;
+  cwd: string;
+  profile: string;
+  model: { provider: string; id: string; name: string } | undefined;
+  tools: string[];
+  /** Absent when the model reports no window, which is not a window of zero. */
+  contextTokens: number | undefined;
+  /** Absent when the model does no reasoning at all, which is not reasoning turned `off`. */
+  effort: CodeAgentEffort | undefined;
+  /** Absent until the session has been asked something. */
+  name: string | undefined;
+  /** `await` keeps a question inside its turn; `suspend` ends the turn (`awaiting`) and the answer opens a new one. */
+  interaction: { question: CodeAgentInteractionMode; approval: CodeAgentInteractionMode };
+}
+
+/**
+ * `awaiting` only comes from a profile whose `interaction` suspends; `truncated` is a partial success (keep the text,
+ * offer "continue"); only a host with its own ceiling emits `maxTurns`. A turn's `message` precedes its `turn_end`.
+ */
+export type CodeAgentStopReason = "done" | "aborted" | "truncated" | "error" | "awaiting" | "maxTurns";
+
+/** A `blocked` call never executed, so it is not an `error`. */
+export type CodeAgentToolOutcome = "ok" | "error" | "blocked";
+
+export type CodeAgentToolOp = "read" | "write" | "delete" | "list" | "search" | "execute" | "other";
+
+/** Carried on both the start and the end frame; a host folding by `toolCallId` keeps the end frame's. */
+export interface CodeAgentToolSummary {
+  toolCallId: string;
+  name: string;
+  op: CodeAgentToolOp;
+  /** Progress, not a change list: a `bash` edit names no path and a `blocked` call names one it never wrote. */
+  path?: string;
+  /** Clipped to {@link codeAgentLabelChars}. */
+  title: string;
+}
+
+export interface CodeAgentQuestionOption {
+  key: string;
+  label: string;
+  detail?: string;
+  /** The one to take when the user says "you decide". */
+  recommended?: boolean;
+}
+
+export interface CodeAgentQuestion {
+  questionId: string;
+  prompt: string;
+  kind: "text" | "select" | "confirm";
+  options?: CodeAgentQuestionOption[];
+  multiSelect?: boolean;
+  freeText?: boolean;
+}
+
+/** Structured so a reconnecting client can restore a multi-select; the prose is {@link codeAgentRenderAnswer}. */
+export interface CodeAgentAnswer {
+  keys?: string[];
+  text?: string;
+}
+
+export interface CodeAgentApprovalRequest {
+  approvalId: string;
+  toolCallId: string;
+  name: string;
+  /** Rendered and clipped. */
+  summary: string;
+  policy: CodeAgentApprovalPolicy;
+}
+
+/** A running `task` sub-agent; `tokens` is read when the frame is made, and a finished one leaves the list. */
+export interface CodeAgentSubagent {
+  /** The `toolCallId` of the `task` call that opened it. */
+  id: string;
+  kind: string;
+  description: string;
+  startedAt: number;
+  tokens: number;
+}
+
+export type CodeAgentEventBody =
+  | { type: "session"; info: CodeAgentSessionInfo }
+  | { type: "turn_start"; turnId: string }
+  | { type: "turn_end"; turnId: string; stopReason: CodeAgentStopReason }
+  | { type: "text_delta"; turnId: string; text: string }
+  | { type: "thinking_delta"; turnId: string; text: string }
+  | { type: "message"; turnId: string; role: "user" | "assistant"; text: string }
+  | { type: "tool_start"; turnId: string; tool: CodeAgentToolSummary }
+  | { type: "tool_progress"; turnId: string; toolCallId: string; text: string }
+  | {
+      type: "tool_end";
+      turnId: string;
+      tool: CodeAgentToolSummary;
+      outcome: CodeAgentToolOutcome;
+      output: string;
+      truncated: boolean;
+    }
+  | { type: "question"; question: CodeAgentQuestion }
+  | { type: "question_resolved"; questionId: string; answer: CodeAgentAnswer; rendered: string }
+  /** A question nobody could be asked — no host attached — answered with nothing; the model continued on its own. */
+  | { type: "question_skipped"; question: CodeAgentQuestion; reason: "no-host" }
+  | { type: "approval"; request: CodeAgentApprovalRequest }
+  | { type: "approval_resolved"; approvalId: string; approved: boolean }
+  | { type: "context"; used: number; max: number | undefined }
+  /** An `end` carrying neither `error` nor `aborted` is the only one that compacted anything. */
+  | {
+      type: "compaction";
+      phase: "start" | "end";
+      reason: "manual" | "threshold" | "overflow";
+      error?: string;
+      aborted?: boolean;
+    }
+  | { type: "retry"; attempt: number; maxAttempts: number; delayMs: number; message: string }
+  | { type: "queue"; steering: string[]; followUp: string[] }
+  | { type: "notice"; level: "info" | "warning" | "error"; message: string }
+  /** The whole list of running sub-agents, re-sent on every change and on a slow tick while any runs. */
+  | { type: "subagent"; agents: CodeAgentSubagent[] }
+  | { type: "error"; message: string; fatal: boolean }
+  | { type: "idle" }
+  /** A host-made frame in the core's sequence: `kind` is opaque, a client upserts by `id`, `persist` defaults false. */
+  | { type: "host"; kind: string; id?: string; persist?: boolean; payload: unknown };
+
+export type CodeAgentEvent = CodeAgentEventBody & { seq: number };
+
+export type CodeAgentEventType = CodeAgentEventBody["type"];
+
+/** A `host` row is only the default: the frame's own `persist` decides, via {@link codeAgentShouldPersist}. */
+export const codeAgentEventPersistence: { [key in CodeAgentEventType]: "live" | "persist" } = {
+  session: "live",
+  turn_start: "persist",
+  turn_end: "persist",
+  text_delta: "live",
+  thinking_delta: "live",
+  message: "persist",
+  tool_start: "live",
+  tool_progress: "live",
+  tool_end: "persist",
+  question: "persist",
+  question_resolved: "persist",
+  question_skipped: "persist",
+  approval: "live",
+  approval_resolved: "live",
+  context: "live",
+  compaction: "persist",
+  retry: "live",
+  queue: "live",
+  notice: "live",
+  subagent: "live",
+  error: "persist",
+  idle: "live",
+  host: "live",
+};
+
+export type CodeAgentImage = { path: string } | { data: string; mime: string };
+
+export const codeAgentSessionName = (text: string, max = 40) => {
+  const words = text
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((word) => !!word);
+  const name: string[] = [];
+  for (const word of words) {
+    if (name.length && [...name, word].join("-").length > max) break;
+    name.push(word);
+  }
+  return name.join("-").slice(0, max) || "session";
+};
+
+export type CodeAgentCommand =
+  | { type: "prompt"; message: string; images?: CodeAgentImage[]; deliverAs?: "steer" | "followUp" }
+  | { type: "answer"; questionId: string; answer: CodeAgentAnswer }
+  | { type: "approve"; approvalId: string; approved: boolean }
+  | { type: "abort" }
+  | { type: "compact"; instructions?: string }
+  | { type: "set_model"; provider: string; modelId: string }
+  | { type: "fork"; entryId: string }
+  | { type: "new_session" }
+  /** Current state, plus every frame after `sinceSeq` when one is given. */
+  | { type: "get_state"; sinceSeq?: number }
+  | { type: "shutdown" };
+
+export type CodeAgentCommandType = CodeAgentCommand["type"];
+
+export interface CodeAgentRequest {
+  id: string;
+  command: CodeAgentCommand;
+}
+
+export interface CodeAgentReply {
+  type: "reply";
+  id: string;
+  ok: boolean;
+  error?: string;
+  data?: unknown;
+}
+
+export type CodeAgentFrame = ({ type: "event" } & { event: CodeAgentEvent }) | CodeAgentReply;
+
+export const isCodeAgentReply = (frame: CodeAgentFrame): frame is CodeAgentReply => frame.type === "reply";
+
+export const codeAgentShouldPersist = (event: CodeAgentEventBody) =>
+  event.type === "host" ? event.persist === true : codeAgentEventPersistence[event.type] === "persist";
+
+export const codeAgentClip = (text: string, max: number) => (text.length <= max ? text : `${text.slice(0, max - 1)}…`);
+
+export const codeAgentRenderAnswer = (question: CodeAgentQuestion, answer: CodeAgentAnswer) => {
+  const labels = (answer.keys ?? []).map((key) => question.options?.find((option) => option.key === key)?.label ?? key);
+  return [labels.join(", "), answer.text].filter(Boolean).join(" — ");
+};
+
+const toolOutcomeMark: { [key in CodeAgentToolOutcome]: string } = { ok: "✓", error: "✗", blocked: "⦸" };
+
+export const codeAgentEventLabel = (event: CodeAgentEventBody): string => {
+  switch (event.type) {
+    case "session":
+      
+      return [
+        `session ${event.info.sessionId}`,
+        event.info.model?.name ?? "no model",
+        event.info.contextTokens ? `${Math.round(event.info.contextTokens / 1000)}k ctx` : "unknown ctx",
+        event.info.profile,
+      ].join(" · ");
+    case "turn_start":
+      return "turn start";
+    case "turn_end":
+      return event.stopReason === "truncated"
+        ? "turn end — the answer was cut off at the model's output limit"
+        : `turn end (${event.stopReason})`;
+    case "text_delta":
+    case "thinking_delta":
+      return event.text;
+    case "message":
+      return `${event.role}: ${event.text}`;
+    case "tool_start":
+      return `→ ${event.tool.title}`;
+    case "tool_end":
+      return `${toolOutcomeMark[event.outcome]} ${event.tool.title}`;
+    case "tool_progress":
+      return `  ${event.text}`;
+    case "question":
+      return `? ${event.question.prompt}`;
+    case "question_resolved":
+      return `= ${event.rendered}`;
+    case "question_skipped":
+      return `? ${event.question.prompt} (skipped: ${event.reason})`;
+    case "approval":
+      return `approve? ${event.request.summary}`;
+    case "approval_resolved":
+      return event.approved ? "approved" : "denied";
+    case "context":
+      return `context ${event.used}${event.max ? `/${event.max}` : ""}`;
+    case "compaction": {
+      const outcome = event.error ? ` — ${event.error}` : event.aborted ? " — cancelled" : "";
+      return `compaction ${event.phase} (${event.reason})${outcome}`;
+    }
+    case "retry":
+      return `retry ${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms — ${event.message}`;
+    case "queue":
+      return `queued ${event.steering.length} steering, ${event.followUp.length} follow-up`;
+    case "notice":
+      return `[${event.level}] ${event.message}`;
+    case "subagent":
+      return event.agents.length
+        ? event.agents.map((agent) => `${agent.kind} · ${agent.description}`).join(" | ")
+        : "no sub-agent running";
+    case "error":
+      return `error: ${event.message}`;
+    case "idle":
+      return "idle";
+    case "host":
+      return `${event.kind}${event.id ? ` ${event.id}` : ""}`;
+    default:
+      return "";
+  }
+};
+
+export interface CodeAgentState {
+  info: CodeAgentSessionInfo;
+  streaming: boolean;
+  /** Present only when `get_state` asked for a replay; empty when nothing was missed. */
+  frames?: CodeAgentEvent[];
+  /** How far back a replay reaches; a client behind this reloads the transcript instead. */
+  replayFrom: number;
+}
+
+export interface CodeAgentStartOptions {
+  cwd: string;
+  profile: CodeAgentProfile;
+  model?: { provider: string; id: string };
+  /** Resume this session instead of opening a new one. */
+  sessionId?: string;
+}

package/{server/routing → common}/eventStream.ts

@@ -4,11 +4,6 @@ export interface EventStreamOptions {
   keepAliveChunk?: string;
 }
 
-/**
- * One `text/event-stream` response. `write` frames a JSON `data:` event, with an `id:` when the caller has one
- * so a client can resume with `Last-Event-ID`; `retry` tells it how long to wait before doing so. A keep-alive
- * comment goes out on an interval below common proxy idle timeouts, so a quiet stream is not reaped mid-life.
- */
 export class EventStream {
   static readonly defaultKeepAliveMs = 15_000;
 
@@ -44,7 +39,7 @@ export class EventStream {
     return new Response(this.#stream, {
       headers: {
         "content-type": "text/event-stream",
-
+        
         "cache-control": "no-cache, no-transform",
         connection: "keep-alive",
         "x-accel-buffering": "no",

package/common/fileUpload.ts

@@ -1,13 +1,3 @@
-interface FileUploadSerializedEndpoint {
-  fileUpload?: boolean;
-}
-
-interface FileUploadSerializedSignal {
-  prefix?: string;
-  endpoint: Record<string, FileUploadSerializedEndpoint>;
-}
-
-/** Framework-owned file-upload contract shared by client-safe packages. */
 export const fileUploadContract = {
   fields: { files: "files", metas: "metas", type: "type", parentId: "parentId" },
   buildMetas: (fileList: FileList | File[]) =>
@@ -20,9 +10,8 @@ export interface FileUploadCapability {
   prefix?: string;
 }
 
-/** Discovers the upload endpoint marked with `{ fileUpload: true }` from the serialized signal. */
 export const resolveFileUploadCapability = (
-  serializedSignal: Record<string, FileUploadSerializedSignal>,
+  serializedSignal: Record<string, { prefix?: string; endpoint: Record<string, { fileUpload?: boolean }> }>,
 ): FileUploadCapability | null => {
   const matches: FileUploadCapability[] = [];
   for (const [refName, signal] of Object.entries(serializedSignal))

package/common/formatNumber.ts

@@ -1,14 +1,5 @@
 export const formatNumber = (numString: string) => {
-  
-  if (typeof numString !== "string") {
-    numString = String(numString);
-  }
-
-  const parts = numString.split(".");
-  const integerPart = parts[0]?.replace(/[^\d]/g, "") ?? ""; 
-  const decimalPart = parts.length > 1 ? `.${parts[1]}` : "";
-
-  const formattedInteger = Number(integerPart).toLocaleString("ko-KR");
-
-  return formattedInteger + decimalPart;
+  const [integerPart = "", decimalPart] = String(numString).split(".");
+  const formattedInteger = Number(integerPart.replace(/[^\d]/g, "")).toLocaleString("ko-KR");
+  return decimalPart === undefined ? formattedInteger : `${formattedInteger}.${decimalPart}`;
 };