akanjs 3.0.0-beta.15 → 3.0.0-beta.17

package/common/CodeTranscript.ts

@@ -4,6 +4,7 @@ import type {
   CodeAgentQuestion,
   CodeAgentSessionInfo,
   CodeAgentStopReason,
+  CodeAgentSubagent,
   CodeAgentToolOutcome,
   CodeAgentToolSummary,
 } from "akanjs/common";
@@ -46,6 +47,7 @@ export class CodeTranscript {
   #approval: CodeAgentApprovalRequest | undefined;
   #stopReason: CodeAgentStopReason | undefined;
   #queue = { steering: 0, followUp: 0 };
+  #subagents: CodeAgentSubagent[] = [];
   #openAssistant: string | undefined;
   #openThinking: string | undefined;
   #nextId = 0;
@@ -104,6 +106,11 @@ export class CodeTranscript {
     return this.#queue;
   }
 
+  /** The sub-agents running right now. Not a transcript row: they are a state, and the state is the list. */
+  get subagents() {
+    return this.#subagents;
+  }
+
   /** Bumped on every applied event, so a view can tell "changed" from "same" without comparing arrays. */
   get revision() {
     return this.#revision;
@@ -202,11 +209,16 @@ export class CodeTranscript {
         return;
       case "notice":
         return this.#notice(event.level, event.message);
+      case "subagent":
+        this.#subagents = event.agents;
+        return;
       case "error":
         return this.#notice("error", event.message);
       case "idle":
         this.#streaming = false;
         this.#queue = { steering: 0, followUp: 0 };
+
+        this.#subagents = [];
         this.#closeStreams(false);
         return;
       case "host":

package/common/codeAgentProfile.ts

@@ -31,6 +31,24 @@ export interface CodeAgentMcpServerRef {
   env?: Record<string, string>;
 }
 
+/**
+ * One declared MCP server, as the session found it.
+ *
+ * A server that answered and one that was never reachable are both here: an integration that is silently
+ * absent is indistinguishable from one the model simply chose not to use, and the tool names are the only
+ * evidence of which of the two happened.
+ */
+export interface CodeAgentMcpStatus {
+  name: string;
+  transport: "stdio" | "http";
+  /** The command line or the url — what tells two entries of the same shape apart without opening the file. */
+  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;
+}
+
 export interface CodeAgentSubagentBudget {
   maxDepth: number;
   maxConcurrent: number;

package/common/codeAgentWire.ts

@@ -154,6 +154,23 @@ export interface CodeAgentApprovalRequest {
   policy: CodeAgentApprovalPolicy;
 }
 
+/**
+ * One sub-agent the `task` tool is currently running.
+ *
+ * `tokens` is read at the moment the frame is made, so a host that draws this rail sees the child's spend
+ * climb rather than learning it only once the child is gone — which is the number that decides whether to
+ * let it keep going. A finished sub-agent leaves the list: what it did is already in the tool row it closed.
+ */
+export interface CodeAgentSubagent {
+  /** The `task` call that opened it, so a host can line the row up with the tool row above. */
+  id: string;
+  kind: string;
+  /** The three-to-five words the model named the task with. */
+  description: string;
+  startedAt: number;
+  tokens: number;
+}
+
 export type CodeAgentEventBody =
   | { type: "session"; info: CodeAgentSessionInfo }
   | { type: "turn_start"; turnId: string }
@@ -180,6 +197,15 @@ export type CodeAgentEventBody =
   | { type: "retry"; attempt: number; maxAttempts: number; delayMs: number; message: string }
   | { type: "queue"; steering: string[]; followUp: string[] }
   | { type: "notice"; level: "info" | "warning" | "error"; message: string }
+  /**
+   * Every sub-agent running right now, whole rather than as a delta.
+   *
+   * A list is re-sent on every change and on a slow tick while any child runs, so a host that missed a frame
+   * converges on the next one instead of holding a row for a child that finished. It is the one thing a turn
+   * does that the transcript cannot show: a `task` call is one tool row that stays open for minutes while its
+   * child spends tokens nobody watching sees spent.
+   */
+  | { type: "subagent"; agents: CodeAgentSubagent[] }
   | { type: "error"; message: string; fatal: boolean }
   | { type: "idle" }
   /**
@@ -236,6 +262,7 @@ export const codeAgentEventPersistence: { [key in CodeAgentEventType]: "live" |
   retry: "live",
   queue: "live",
   notice: "live",
+  subagent: "live",
   error: "persist",
   idle: "live",
   host: "live",
@@ -380,6 +407,10 @@ export const codeAgentEventLabel = (event: CodeAgentEventBody): string => {
       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":

package/common/index.ts

@@ -22,6 +22,7 @@ export {
   type CodeAgentBuiltinTool,
   type CodeAgentInteractionMode,
   type CodeAgentMcpServerRef,
+  type CodeAgentMcpStatus,
   type CodeAgentPresetName,
   type CodeAgentProfile,
   type CodeAgentSubagentBudget,
@@ -49,6 +50,7 @@ export {
   type CodeAgentStartOptions,
   type CodeAgentState,
   type CodeAgentStopReason,
+  type CodeAgentSubagent,
   type CodeAgentToolOp,
   type CodeAgentToolOutcome,
   type CodeAgentToolSummary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.15",
+  "version": "3.0.0-beta.17",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/types/common/CodeTranscript.d.ts

@@ -1,4 +1,4 @@
-import type { CodeAgentApprovalRequest, CodeAgentEvent, CodeAgentQuestion, CodeAgentSessionInfo, CodeAgentStopReason, CodeAgentToolOutcome, CodeAgentToolSummary } from "akanjs/common";
+import type { CodeAgentApprovalRequest, CodeAgentEvent, CodeAgentQuestion, CodeAgentSessionInfo, CodeAgentStopReason, CodeAgentSubagent, CodeAgentToolOutcome, CodeAgentToolSummary } from "akanjs/common";
 export type CodeTranscriptPart = {
     kind: "user";
     id: string;
@@ -77,6 +77,8 @@ export declare class CodeTranscript {
         steering: number;
         followUp: number;
     };
+    /** The sub-agents running right now. Not a transcript row: they are a state, and the state is the list. */
+    get subagents(): CodeAgentSubagent[];
     /** Bumped on every applied event, so a view can tell "changed" from "same" without comparing arrays. */
     get revision(): number;
     /**

package/types/common/codeAgentProfile.d.ts

@@ -26,6 +26,23 @@ export interface CodeAgentMcpServerRef {
     url?: string;
     env?: Record<string, string>;
 }
+/**
+ * One declared MCP server, as the session found it.
+ *
+ * A server that answered and one that was never reachable are both here: an integration that is silently
+ * absent is indistinguishable from one the model simply chose not to use, and the tool names are the only
+ * evidence of which of the two happened.
+ */
+export interface CodeAgentMcpStatus {
+    name: string;
+    transport: "stdio" | "http";
+    /** The command line or the url — what tells two entries of the same shape apart without opening the file. */
+    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;
+}
 export interface CodeAgentSubagentBudget {
     maxDepth: number;
     maxConcurrent: number;

package/types/common/codeAgentWire.d.ts

@@ -147,6 +147,22 @@ export interface CodeAgentApprovalRequest {
     summary: string;
     policy: CodeAgentApprovalPolicy;
 }
+/**
+ * One sub-agent the `task` tool is currently running.
+ *
+ * `tokens` is read at the moment the frame is made, so a host that draws this rail sees the child's spend
+ * climb rather than learning it only once the child is gone — which is the number that decides whether to
+ * let it keep going. A finished sub-agent leaves the list: what it did is already in the tool row it closed.
+ */
+export interface CodeAgentSubagent {
+    /** The `task` call that opened it, so a host can line the row up with the tool row above. */
+    id: string;
+    kind: string;
+    /** The three-to-five words the model named the task with. */
+    description: string;
+    startedAt: number;
+    tokens: number;
+}
 export type CodeAgentEventBody = {
     type: "session";
     info: CodeAgentSessionInfo;
@@ -223,6 +239,18 @@ export type CodeAgentEventBody = {
     type: "notice";
     level: "info" | "warning" | "error";
     message: string;
+}
+/**
+ * Every sub-agent running right now, whole rather than as a delta.
+ *
+ * A list is re-sent on every change and on a slow tick while any child runs, so a host that missed a frame
+ * converges on the next one instead of holding a row for a child that finished. It is the one thing a turn
+ * does that the transcript cannot show: a `task` call is one tool row that stays open for minutes while its
+ * child spends tokens nobody watching sees spent.
+ */
+ | {
+    type: "subagent";
+    agents: CodeAgentSubagent[];
 } | {
     type: "error";
     message: string;

package/types/common/index.d.ts

@@ -5,8 +5,8 @@ export { CodeTranscript, type CodeTranscriptPart } from "./CodeTranscript.d.ts";
 export { capitalize } from "./capitalize.d.ts";
 export { clamp } from "./clamp.d.ts";
 export { clientAddressFromHeaders, clientPortFromHeaders, forwardedHeaders, normalizeIpAddress, } from "./clientAddress.d.ts";
-export { type CodeAgentApprovalPolicy, type CodeAgentBuiltinTool, type CodeAgentInteractionMode, type CodeAgentMcpServerRef, type CodeAgentPresetName, type CodeAgentProfile, type CodeAgentSubagentBudget, codeAgentDeniedPaths, codeAgentPresets, codeAgentReadOnlyBuiltins, isCodeAgentPresetName, } from "./codeAgentProfile.d.ts";
-export { type CodeAgentAnswer, type CodeAgentApprovalRequest, type CodeAgentCommand, type CodeAgentCommandType, type CodeAgentEffort, type CodeAgentEvent, type CodeAgentEventBody, type CodeAgentEventType, type CodeAgentFrame, type CodeAgentImage, type CodeAgentQuestion, type CodeAgentQuestionOption, type CodeAgentReply, type CodeAgentRequest, type CodeAgentSessionInfo, type CodeAgentStartOptions, type CodeAgentState, type CodeAgentStopReason, type CodeAgentToolOp, type CodeAgentToolOutcome, type CodeAgentToolSummary, codeAgentClip, codeAgentEventLabel, codeAgentEventPersistence, codeAgentLabelChars, codeAgentOutputChars, codeAgentRenderAnswer, codeAgentSessionName, codeAgentShouldPersist, codeAgentWireVersion, isCodeAgentReply, } from "./codeAgentWire.d.ts";
+export { type CodeAgentApprovalPolicy, type CodeAgentBuiltinTool, type CodeAgentInteractionMode, type CodeAgentMcpServerRef, type CodeAgentMcpStatus, type CodeAgentPresetName, type CodeAgentProfile, type CodeAgentSubagentBudget, codeAgentDeniedPaths, codeAgentPresets, codeAgentReadOnlyBuiltins, isCodeAgentPresetName, } from "./codeAgentProfile.d.ts";
+export { type CodeAgentAnswer, type CodeAgentApprovalRequest, type CodeAgentCommand, type CodeAgentCommandType, type CodeAgentEffort, type CodeAgentEvent, type CodeAgentEventBody, type CodeAgentEventType, type CodeAgentFrame, type CodeAgentImage, type CodeAgentQuestion, type CodeAgentQuestionOption, type CodeAgentReply, type CodeAgentRequest, type CodeAgentSessionInfo, type CodeAgentStartOptions, type CodeAgentState, type CodeAgentStopReason, type CodeAgentSubagent, type CodeAgentToolOp, type CodeAgentToolOutcome, type CodeAgentToolSummary, codeAgentClip, codeAgentEventLabel, codeAgentEventPersistence, codeAgentLabelChars, codeAgentOutputChars, codeAgentRenderAnswer, codeAgentSessionName, codeAgentShouldPersist, codeAgentWireVersion, isCodeAgentReply, } from "./codeAgentWire.d.ts";
 export { deepObjectify } from "./deepObjectify.d.ts";
 export type { DynamicRecord } from "./dynamicRecord.d.ts";
 export { EventStream, type EventStreamOptions } from "./eventStream.d.ts";