Prime Agent
从源码学会它怎么工作

  178   * Start an agent loop with a new prompt message.
  179   * The prompt is added to the context and events are emitted for it.
  180   */
  181  export function agentLoop(
  182  	prompts: AgentMessage[],
  183  	context: AgentContext,
  184  	config: AgentLoopConfig,
  185  	signal?: AbortSignal,
  186  	streamFn?: StreamFn,
  187  ): EventStream<AgentEvent, AgentMessage[]> {
  188  	const stream = createAgentStream();
  189  
  190  	endAgentStreamOnError(
  191  		stream,
  192  		runAgentLoop(
  193  			prompts,
  194  			context,
  195  			config,
  196  			async (event) => {
  197  				stream.push(event);
  198  			},
  199  			signal,
  200  			streamFn,
  201  		),
  202  	);
  203  
  204  	return stream;
  205  }

  317  	// Check for steering messages at start (user may have typed while waiting)
  318  	let pendingMessages: AgentMessage[] = await pollMessagesUnlessAborted(config.getSteeringMessages, signal);
  319  
  320  	const shouldStopBeforeTurn = (): boolean => !firstTurn && (config.shouldStopBeforeTurn?.() ?? false);
  321  
  322  	// Outer loop: continues when queued follow-up messages arrive after agent would stop
  323  	while (true) {
  324  		throwIfAborted(signal);
  325  		let hasMoreToolCalls = true;
  326  
  327  		// Inner loop: process tool calls and steering messages
  328  		while (hasMoreToolCalls || pendingMessages.length > 0) {
  329  			throwIfAborted(signal);
  330  			if (!firstTurn) {
  331  				await emit({ type: "turn_start" });
  332  			} else {
  333  				firstTurn = false;
  334  			}
  335  
  336  			// Process pending messages (inject before next assistant response)
  337  			if (pendingMessages.length > 0) {
  338  				for (const message of pendingMessages) {
  339  					await emit({ type: "message_start", message });
  340  					await emit({ type: "message_end", message });
  341  					currentContext.messages.push(message);
  342  					newMessages.push(message);
  343  				}
  344  				pendingMessages = [];
  345  			}

    1  /**
    2   * AgentSession - Core abstraction for agent lifecycle and session management.
    3   *
    4   * This class is shared between all run modes (interactive, print, rpc).
    5   * It encapsulates:
    6   * - Agent state access
    7   * - Event subscription with automatic session persistence
    8   * - Model and thinking level management
    9   * - Compaction (manual and auto)
   10   * - Bash execution
   11   * - Session switching and branching
   12   *
   13   * Modes use this class and add their own I/O layer on top.

  467  async function streamAssistantResponse(
  468  	context: AgentContext,
  469  	config: AgentLoopConfig,
  470  	signal: AbortSignal | undefined,
  471  	emit: AgentEventSink,
  472  	streamFn?: StreamFn,
  473  ): Promise<AssistantMessage> {
  474  	let partialMessage: AssistantMessage | null = null;
  475  	let addedPartial = false;
  476  	const finishAbortedMessage = async () => {
  477  		const finalMessage = createAbortedAssistantMessage(config, partialMessage);
  478  		if (addedPartial) {
  479  			context.messages[context.messages.length - 1] = finalMessage;
  480  		} else {
  481  			context.messages.push(finalMessage);
  482  			await emit({ type: "message_start", message: { ...finalMessage } });
  483  		}
  484  		await emit({ type: "message_end", message: finalMessage });
  485  		return finalMessage;
  486  	};
  487  
  488  	try {
  489  		throwIfAborted(signal);
  490  		// Apply context transform if configured (AgentMessage[] → AgentMessage[])
  491  		let messages = context.messages;
      … 19 lines omitted; exact range 467–521 …
  511  			tools: context.tools,
  512  		};
  513  
  514  		const response = await maybePromiseWithAbort(
  515  			streamFunction(config.model, llmContext, {
  516  				...config,
  517  				apiKey: resolvedApiKey,
  518  				signal,
  519  			}),
  520  			signal,
  521  		);

  170  	transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
  171  
  172  	/** Resolves the system prompt immediately before each LLM call. */
  173  	getSystemPrompt?: () => string;
  174  
  175  	/**
  176  	 * Resolves an API key dynamically for each LLM call.
  177  	 *
  178  	 * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire
  179  	 * during long-running tool execution phases.
  180  	 *
  181  	 * Contract: must not throw or reject. Return undefined when no key is available.
  182  	 */
  183  	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;

  608  async function executeToolCalls(
  609  	currentContext: AgentContext,
  610  	assistantMessage: AssistantMessage,
  611  	config: AgentLoopConfig,
  612  	signal: AbortSignal | undefined,
  613  	emit: AgentEventSink,
  614  ): Promise<ExecutedToolCallBatch> {
  615  	const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
  616  	const hasSequentialToolCall = toolCalls.some(
  617  		(tc) => currentContext.tools?.find((t) => t.name === tc.name)?.executionMode === "sequential",
  618  	);
  619  	if (config.toolExecution === "sequential" || hasSequentialToolCall) {
  620  		return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit);
  621  	}
  622  	return executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, signal, emit);
  623  }

  122  export interface CompactionSettings {
  123  	enabled: boolean;
  124  	reserveTokens: number;
  125  	keepRecentTokens: number;
  126  }
  127  
  128  export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
  129  	enabled: true,
  130  	reserveTokens: 16384,
  131  	keepRecentTokens: 20000,
  132  };

  138  /**
  139   * Calculate total context tokens from usage.
  140   * Uses the native totalTokens field when available, falls back to computing from components.
  141   *
  142   * Includes output: the assistant's response becomes part of the prompt on the next
  143   * request, so it counts toward the context the next turn will send.
  144   */
  145  export function calculateContextTokens(usage: Usage): number {
  146  	return usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
  147  }

  303  /**
  304   * Find valid cut points: indices of user, assistant, custom, or bashExecution messages.
  305   * Never cut at tool results (they must follow their tool call).
  306   * When we cut at an assistant message with tool calls, its tool results follow it
  307   * and will be kept.
  308   * BashExecutionMessage is treated like a user message (user-initiated context).
  309   */
  310  function findValidCutPoints(entries: SessionEntry[], startIndex: number, endIndex: number): number[] {
  311  	const cutPoints: number[] = [];
  312  	for (let i = startIndex; i < endIndex; i++) {
  313  		const entry = entries[i];
  314  		switch (entry.type) {
  315  			case "message": {
  316  				const role = entry.message.role;
  317  				switch (role) {
  318  					case "bashExecution":
  319  					case "custom":
  320  					case "branchSummary":
  321  					case "compactionSummary":
  322  					case "user":
  323  					case "assistant":
  324  						cutPoints.push(i);
  325  						break;
  326  					case "toolResult":
  327  						break;
      … 1 lines omitted; exact range 303–339 …
  329  				break;
  330  			}
  331  			case "thinking_level_change":
  332  			case "model_change":
  333  			case "compaction":
  334  			case "branch_summary":
  335  			case "custom":
  336  			case "custom_message":
  337  			case "label":
  338  			case "session_info":
  339  				break;

  465  const SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
  466  
  467  Use this EXACT format:
  468  
  469  ## Goal
  470  [What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
  471  
  472  ## Constraints & Preferences
  473  - [Any constraints, preferences, or requirements mentioned by user]
  474  - [Or "(none)" if none were mentioned]
  475  
  476  ## Progress
  477  ### Done
  478  - [x] [Completed tasks/changes]
  479  
  480  ### In Progress
  481  - [ ] [Current work]
  482  
  483  ### Blocked
  484  - [Issues preventing progress, if any]
  485  
  486  ## Key Decisions
  487  - **[Decision]**: [Brief rationale]
  488  
  489  ## Next Steps
  490  1. [Ordered list of what should happen next]
  491  
  492  ## Critical Context
  493  - [Any data, examples, or references needed to continue]
  494  - [Or "(none)" if not applicable]
  495  
  496  Keep each section concise. Preserve exact file paths, function names, and error messages.`;

  636  export function prepareCompaction(
  637  	pathEntries: SessionEntry[],
  638  	settings: CompactionSettings,
  639  ): CompactionPreparation | undefined {
  640  	if (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === "compaction") {
  641  		return undefined;
  642  	}
  643  
  644  	let prevCompactionIndex = -1;
  645  	for (let i = pathEntries.length - 1; i >= 0; i--) {
  646  		if (pathEntries[i].type === "compaction") {
  647  			prevCompactionIndex = i;
  648  			break;
  649  		}
  650  	}
  651  
  652  	let previousSummary: string | undefined;
  653  	let boundaryStart = 0;
  654  	if (prevCompactionIndex >= 0) {
  655  		const prevCompaction = pathEntries[prevCompactionIndex] as CompactionEntry;
  656  		previousSummary = prevCompaction.summary;
  657  		const firstKeptEntryIndex = pathEntries.findIndex((entry) => entry.id === prevCompaction.firstKeptEntryId);
  658  		boundaryStart = firstKeptEntryIndex >= 0 ? firstKeptEntryIndex : prevCompactionIndex + 1;
  659  	}
  660  	const boundaryEnd = pathEntries.length;
      … 41 lines omitted; exact range 636–712 …
  702  		for (const msg of turnPrefixMessages) {
  703  			extractFileOpsFromMessage(msg, fileOps);
  704  		}
  705  	}
  706  
  707  	return {
  708  		firstKeptEntryId,
  709  		messagesToSummarize,
  710  		turnPrefixMessages,
  711  		isSplitTurn: cutPoint.isSplitTurn,
  712  		tokensBefore,

  795  async function prepareToolCall(
  796  	currentContext: AgentContext,
  797  	assistantMessage: AssistantMessage,
  798  	toolCall: AgentToolCall,
  799  	config: AgentLoopConfig,
  800  	signal: AbortSignal | undefined,
  801  ): Promise<PreparedToolCall | ImmediateToolCallOutcome> {
  802  	const tool = currentContext.tools?.find((t) => t.name === toolCall.name);
  803  	if (!tool) {
  804  		return {
  805  			kind: "immediate",
  806  			result: createErrorToolResult(`Tool ${toolCall.name} not found`),
  807  			isError: true,
  808  		};
  809  	}
  810  
  811  	try {
  812  		const preparedToolCall = prepareToolCallArguments(tool, toolCall);
  813  		const validatedArgs = validateToolArguments(tool, preparedToolCall);
  814  		if (config.beforeToolCall) {
  815  			const beforeResult = await maybePromiseWithAbort(
  816  				config.beforeToolCall(
  817  					{
  818  						assistantMessage,
  819  						toolCall,
      … 18 lines omitted; exact range 795–848 …
  838  			tool,
  839  			args: validatedArgs,
  840  		};
  841  	} catch (error) {
  842  		return {
  843  			kind: "immediate",
  844  			result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
  845  			isError: true,
  846  		};
  847  	}
  848  }

   36  /**
   37   * Pluggable operations for the bash tool.
   38   * Override these to delegate command execution to remote systems (for example SSH).
   39   */
   40  export interface BashOperations {
   41  	/**
   42  	 * Execute a command and stream output.
   43  	 * @param command The command to execute
   44  	 * @param cwd Working directory
   45  	 * @param options Execution options
   46  	 * @returns Promise resolving to exit code (null if killed)
   47  	 */
   48  	exec: (
   49  		command: string,
   50  		cwd: string,
   51  		options: {
   52  			onData: (data: Buffer) => void;
   53  			signal?: AbortSignal;
   54  			timeout?: number;
   55  			env?: NodeJS.ProcessEnv;
   56  		},
   57  	) => Promise<{ exitCode: number | null }>;
   58  }

  250  	const truncation = result.details?.truncation;
  251  	const fullOutputPath = result.details?.fullOutputPath;
  252  	if (truncation?.truncated || fullOutputPath) {
  253  		const warnings: string[] = [];
  254  		if (fullOutputPath) {
  255  			warnings.push(`Full output: ${fullOutputPath}`);
  256  		}
  257  		if (truncation?.truncated) {
  258  			if (truncation.truncatedBy === "lines") {
  259  				warnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);
  260  			} else {
  261  				warnings.push(
  262  					`Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)`,
  263  				);
  264  			}
  265  		}
  266  		component.addChild(new Text(`\n${theme.fg("warning", `[${warnings.join(". ")}]`)}`, 0, 0));

  670  	private isSessionBeforeEvent(event: RunnerEmitEvent): event is SessionBeforeEvent {
  671  		return (
  672  			event.type === "session_before_switch" ||
  673  			event.type === "session_before_fork" ||
  674  			event.type === "session_before_compact" ||
  675  			event.type === "session_before_tree"
  676  		);
  677  	}
  678  
  679  	async emit<TEvent extends RunnerEmitEvent>(event: TEvent): Promise<RunnerEmitResult<TEvent>> {
  680  		const ctx = this.createContext();
  681  		let result: SessionBeforeEventResult | undefined;
  682  
  683  		for (const ext of this.extensions) {
  684  			const handlers = ext.handlers.get(event.type);
  685  			if (!handlers || handlers.length === 0) continue;
  686  
  687  			for (const handler of handlers) {
  688  				try {
  689  					const handlerResult = await handler(event, ctx);
  690  
  691  					if (this.isSessionBeforeEvent(event) && handlerResult) {
  692  						result = handlerResult as SessionBeforeEventResult;
  693  						if (result.cancel) {
  694  							return result as RunnerEmitResult<TEvent>;
      … 6 lines omitted; exact range 670–711 …
  701  						extensionPath: ext.path,
  702  						event: event.type,
  703  						error: message,
  704  						stack,
  705  					});
  706  				}
  707  			}
  708  		}
  709  
  710  		return result as RunnerEmitResult<TEvent>;
  711  	}

 1080  	/** Register a tool that the LLM can call. */
 1081  	registerTool<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>(
 1082  		tool: ToolDefinition<TParams, TDetails, TState>,
 1083  	): void;
 1084  
 1085  	// =========================================================================
 1086  	// Command, Shortcut, Flag Registration
 1087  	// =========================================================================
 1088  
 1089  	/** Register a custom command. */
 1090  	registerCommand(name: string, options: Omit<RegisteredCommand, "name" | "sourceInfo">): void;
 1091  
 1092  	/** Register a keyboard shortcut. */
 1093  	registerShortcut(
 1094  		shortcut: KeyId,
 1095  		options: {
 1096  			description?: string;
 1097  			handler: (ctx: ExtensionContext) => Promise<void> | void;
 1098  		},
 1099  	): void;
 1100  
 1101  	/** Register a CLI flag. */
 1102  	registerFlag(
 1103  		name: string,
 1104  		options: {
      … 48 lines omitted; exact range 1080–1163 …
 1153  	/** Set or clear a label on an entry. Labels are user-defined markers for bookmarking/navigation. */
 1154  	setLabel(entryId: string, label: string | undefined): void;
 1155  
 1156  	/** Execute a shell command. */
 1157  	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
 1158  
 1159  	/** Get the list of currently active tool names. */
 1160  	getActiveTools(): string[];
 1161  
 1162  	/** Get all configured tools with parameter schema and source metadata. */
 1163  	getAllTools(): ToolInfo[];

   23  export interface ResourceExtensionPaths {
   24  	skillPaths?: Array<{ path: string; metadata: PathMetadata }>;
   25  	promptPaths?: Array<{ path: string; metadata: PathMetadata }>;
   26  	themePaths?: Array<{ path: string; metadata: PathMetadata }>;
   27  }
   28  
   29  export interface ResourceLoader {
   30  	getExtensions(): LoadExtensionsResult;
   31  	getSkills(): { skills: Skill[]; diagnostics: ResourceDiagnostic[] };
   32  	getPrompts(): { prompts: PromptTemplate[]; diagnostics: ResourceDiagnostic[] };
   33  	getThemes(): { themes: Theme[]; diagnostics: ResourceDiagnostic[] };
   34  	getAgentsFiles(): { agentsFiles: Array<{ path: string; content: string }> };
   35  	getSystemPrompt(): string | undefined;
   36  	getAppendSystemPrompt(): string[];
   37  	extendResources(paths: ResourceExtensionPaths): void;
   38  	reload(): Promise<void>;
   39  }

  646  		const normalizedPath = resolve(filePath);
  647  		const agentRoots = [
  648  			join(this.agentDir, "skills"),
  649  			join(this.agentDir, "prompts"),
  650  			join(this.agentDir, "themes"),
  651  			join(this.agentDir, "extensions"),
  652  		];
  653  		const projectRoots = [
  654  			join(this.cwd, CONFIG_DIR_NAME, "skills"),
  655  			join(this.cwd, CONFIG_DIR_NAME, "prompts"),
  656  			join(this.cwd, CONFIG_DIR_NAME, "themes"),
  657  			join(this.cwd, CONFIG_DIR_NAME, "extensions"),
  658  		];
  659  
  660  		for (const root of agentRoots) {
  661  			if (this.isUnderPath(normalizedPath, root)) {
  662  				return { path: filePath, source: "local", scope: "user", origin: "top-level", baseDir: root };
  663  			}
  664  		}
  665  
  666  		for (const root of projectRoots) {
  667  			if (this.isUnderPath(normalizedPath, root)) {
  668  				return { path: filePath, source: "local", scope: "project", origin: "top-level", baseDir: root };
  669  			}
  670  		}
  671  
  672  		return {
  673  			path: filePath,
  674  			source: "local",
  675  			scope: "temporary",
  676  			origin: "top-level",
  677  			baseDir: statSync(normalizedPath).isDirectory() ? normalizedPath : resolve(normalizedPath, ".."),
  678  		};

 1024  /** Handler function type for events */
 1025  // biome-ignore lint/suspicious/noConfusingVoidType: void allows bare return statements
 1026  export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
 1027  
 1028  /**
 1029   * ExtensionAPI passed to extension factory functions.
 1030   */
 1031  export interface ExtensionAPI {
 1032  	// =========================================================================
 1033  	// Event Subscription
 1034  	// =========================================================================
 1035  
 1036  	on(event: "resources_discover", handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>): void;
 1037  	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
 1038  	on(
 1039  		event: "session_before_switch",
 1040  		handler: ExtensionHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>,
 1041  	): void;
 1042  	on(event: "session_before_fork", handler: ExtensionHandler<SessionBeforeForkEvent, SessionBeforeForkResult>): void;
 1043  	on(
 1044  		event: "session_before_compact",
 1045  		handler: ExtensionHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>,
 1046  	): void;
 1047  	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
 1048  	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
      … 15 lines omitted; exact range 1024–1074 …
 1064  	on(event: "message_end", handler: ExtensionHandler<MessageEndEvent, MessageEndEventResult>): void;
 1065  	on(event: "tool_execution_start", handler: ExtensionHandler<ToolExecutionStartEvent>): void;
 1066  	on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): void;
 1067  	on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): void;
 1068  	on(event: "model_select", handler: ExtensionHandler<ModelSelectEvent>): void;
 1069  	on(event: "thinking_level_select", handler: ExtensionHandler<ThinkingLevelSelectEvent>): void;
 1070  	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
 1071  	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
 1072  	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
 1073  	on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): void;
 1074  	on(event: "refine_complete", handler: ExtensionHandler<RefineCompleteEvent>): void;

   36  export class McpManager {
   37  	private readonly authStorage: AuthStorage;
   38  	private readonly getUserServers: () => Record<string, McpServerConfig> | undefined;
   39  	private readonly beginLogin?: (server: string) => Promise<void>;
   40  	private integrations = new Map<string, ResolvedIntegration>();
   41  	/** Provider ids we registered for user servers, so refresh can drop removed ones. */
   42  	private registeredUserProviderIds = new Set<string>();
   43  
   44  	constructor(options: McpManagerOptions) {
   45  		this.authStorage = options.authStorage;
   46  		this.getUserServers = options.getUserServers ?? (() => undefined);
   47  		this.beginLogin = options.beginLogin;
   48  		this.resolveIntegrations();
   49  		this.registerProviders();
   50  	}
   51  
   52  	/** Re-read settings and re-register providers; call after a session reload. */
   53  	refresh(): void {
   54  		this.resolveIntegrations();
   55  		this.registerProviders();
   56  	}
   57  
   58  	private providerId(server: string): string {
   59  		return `mcp:${server}`;
   60  	}
      … 7 lines omitted; exact range 36–78 …
   68  				url: entry.url,
   69  				usesOAuth: entry.oauth?.kind === "oauth",
   70  			});
   71  		}
   72  		for (const [server, config] of Object.entries(this.getUserServers() ?? {})) {
   73  			if (config.type !== "http") continue; // stdio servers self-manage in Python
   74  			integrations.set(server, {
   75  				server,
   76  				label: server,
   77  				url: config.url,
   78  				usesOAuth: config.oauth === true,

   14  export interface RlmSpawnHandle {
   15  	rlm_child_id: string;
   16  	name: string;
   17  	session_dir: string;
   18  	model: string;
   19  }
   20  
   21  export type RlmSubagentRegistryStatus = "running" | "completed" | "error";
   22  
   23  export interface RlmSubagentRegistryEntry {
   24  	rlm_child_id: string;
   25  	active_session_id: string | null;
   26  	session_id: string | null;
   27  	session_name: string;
   28  	session_dir: string;
   29  	status: RlmSubagentRegistryStatus;
   30  }
   31  
   32  export interface RlmListSubagentsResult {
   33  	subagents: RlmSubagentRegistryEntry[];
   34  }
   35  
   36  export interface RlmDeleteSubagentResult {
   37  	subagent: RlmSubagentRegistryEntry;
   38  	outcome?: "deleted" | "skipped_running";
   39  }

  158  	"list_saved_sessions",
  159  	"create",
  160  	"attach",
  161  	"reattach",
  162  	"detach",
  163  	"complete_owned_session",
  164  	"promote_owned_session",
  165  	"kill",
  166  	"rename",
  167  	"prompt",
  168  	"cancel_prompt_admission",
  169  	"prompt_and_wait",
  170  	"steer",
  171  	"follow_up",
  172  	"restore_next_turn",
  173  	"restore_actions",
  174  	"append_custom_message",
  175  	"resume_queue",
  176  	"send_message",
  177  	"agent_messages_status",
  178  	"agent_messages_pause",
  179  	"agent_messages_resume",
  180  	"agent_messages_clear",
  181  	"abort",
  182  	"start_side_question",
      … 19 lines omitted; exact range 158–212 …
  202  	"mutate_queued_message",
  203  	"clear_queue",
  204  	"abort_and_clear_queue",
  205  	"cron_list",
  206  	"heartbeats_list",
  207  	"heartbeat_manage",
  208  	"cron_add",
  209  	"cron_cancel",
  210  	"heartbeat_get",
  211  	"heartbeat_set",
  212  	"heartbeat_update",

 1125  	private promptAdmissionKey(activeSessionId: string, publicAdmissionId: string): string {
 1126  		return `${activeSessionId}\0${publicAdmissionId}`;
 1127  	}
 1128  
 1129  	private promptAdmissionsFor(client: DaemonSocketClient): Map<string, SupervisorPromptAdmission> {
 1130  		let admissions = this.promptAdmissions.get(client);
 1131  		if (!admissions) {
 1132  			admissions = new Map();
 1133  			this.promptAdmissions.set(client, admissions);
 1134  		}
 1135  		return admissions;
 1136  	}
 1137  
 1138  	private getPromptAdmission(
 1139  		client: DaemonSocketClient,
 1140  		activeSessionId: string,
 1141  		publicAdmissionId: string,
 1142  	): SupervisorPromptAdmission | undefined {
 1143  		return this.promptAdmissions.get(client)?.get(this.promptAdmissionKey(activeSessionId, publicAdmissionId));
 1144  	}
 1145  
 1146  	private deletePromptAdmission(admission: SupervisorPromptAdmission): void {
 1147  		const admissions = this.promptAdmissions.get(admission.client);
 1148  		const key = this.promptAdmissionKey(admission.activeSessionId, admission.publicAdmissionId);
 1149  		if (admissions?.get(key) !== admission) return;
      … 24 lines omitted; exact range 1125–1184 …
 1174  							: undefined;
 1175  					if (status === "owned") admission.status = "owned";
 1176  					else if (status === "cancelled") admission.status = "cancelled";
 1177  				})
 1178  				.catch((error: unknown) => {
 1179  					this.log(
 1180  						`Could not cancel prompt admission ${admission.workerAdmissionId} on disconnected client: ${String(error)}`,
 1181  					);
 1182  				});
 1183  		}
 1184  	}

   49  import type { PrivateFrame } from "../session-worker/private-framing.js";
   50  import { createActiveSessionId, type DaemonSocketClient } from "./active-session-state.js";
   51  import { CommandRecoveryJournal, createCommandIdempotencyKey } from "./command-recovery-journal.js";
   52  import { CompactAssistantStreamReconstructor, isCompactAssistantDelta } from "./compact-session-stream.js";
   53  import { DAEMON_CATALOG_ROLE_ENV, DaemonCatalogClient } from "./daemon-catalog-process.js";

   33  export const CURRENT_SESSION_VERSION = 3;
   34  const SESSION_LIST_SEARCH_TEXT_MAX_CHARS = 64 * 1024;
   35  const SESSION_LIST_PARSE_MAX_LINE_CHARS = 1024 * 1024;
   36  const SESSION_LIST_LARGE_MESSAGE_PREVIEW_MAX_CHARS = 256;
   37  const SESSION_STREAMING_LOAD_THRESHOLD_BYTES = 128 * 1024 * 1024;
   38  const SESSION_ASYNC_PARSE_YIELD_BYTES = 4 * 1024 * 1024;
   39  
   40  // Entry types that can represent user intent (vs. daemon bookkeeping like
   41  // session_state/agent_status/git_state/child_usage_attributed). Used by
   42  // hasUserContent to decide whether a message-less draft is safe to discard.
   43  const CONTENT_ENTRY_TYPES = new Set([
   44  	"message",
   45  	"custom_message",
   46  	"custom",
   47  	"model_change",
   48  	"thinking_level_change",
   49  	"service_tier_change",
   50  	"session_info",
   51  	"label",
   52  	"compaction",
   53  	"branch_summary",
   54  ]);

  472  /**
  473   * Build the session context from entries using tree traversal.
  474   * If leafId is provided, walks from that entry to root.
  475   * Handles compaction and branch summaries along the path.
  476   */
  477  export function buildSessionContext(
  478  	entries: SessionEntry[],
  479  	leafId?: string | null,
  480  	byId?: Map<string, SessionEntry>,
  481  ): SessionContext {
  482  	// Build uuid index if not available
  483  	if (!byId) {
  484  		byId = new Map<string, SessionEntry>();
  485  		for (const entry of entries) {
  486  			byId.set(entry.id, entry);
  487  		}
  488  	}
  489  
  490  	// Find leaf
  491  	let leaf: SessionEntry | undefined;
  492  	if (leafId === null) {
  493  		// Explicitly null - return no messages (navigated to before first entry)
  494  		return { messages: [], thinkingLevel: "off", serviceTier: "default", model: null };
  495  	}
  496  	if (leafId) {
      … 28 lines omitted; exact range 472–535 …
  525  			thinkingLevel = entry.thinkingLevel;
  526  		} else if (entry.type === "service_tier_change") {
  527  			serviceTier = entry.serviceTier;
  528  		} else if (entry.type === "model_change") {
  529  			model = { provider: entry.provider, modelId: entry.modelId };
  530  		} else if (entry.type === "message" && entry.message.role === "assistant") {
  531  			model = { provider: entry.message.provider, modelId: entry.message.model };
  532  		} else if (entry.type === "compaction") {
  533  			compaction = entry;
  534  		}
  535  	}

 1345  	private _rewriteFile(): void {
 1346  		if (!this.persist || !this.sessionFile) return;
 1347  		const content = `${this.fileEntries.map((e) => JSON.stringify(e)).join("\n")}\n`;
 1348  		const targetPath = realpathIfPresent(this.sessionFile);
 1349  		const directory = dirname(targetPath);
 1350  		mkdirSync(directory, { recursive: true });
 1351  		const tempPath = join(directory, `.${basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`);
 1352  		try {
 1353  			const metadata = statMetadataIfPresent(targetPath);
 1354  			writeFileSync(tempPath, content, metadata === undefined ? undefined : { mode: metadata.mode });
 1355  			if (metadata !== undefined) {
 1356  				chownSync(tempPath, metadata.uid, metadata.gid);
 1357  				chmodSync(tempPath, metadata.mode);
 1358  			}
 1359  			renameSync(tempPath, targetPath);
 1360  		} finally {
 1361  			rmSync(tempPath, { force: true });
 1362  		}
 1363  		this._notifyPersistListeners();
 1364  	}

  399  /**
  400   * Events emitted by the Agent for UI updates.
  401   *
  402   * `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`
  403   * listeners for that event are still part of run settlement. The agent becomes
  404   * idle only after those listeners finish.
  405   */
  406  export type AgentEvent =
  407  	// Agent lifecycle
  408  	| { type: "agent_start" }
  409  	| { type: "agent_end"; messages: AgentMessage[] }
  410  	// Turn lifecycle - a turn is one assistant response + any tool calls/results
  411  	| { type: "turn_start" }
  412  	| { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
  413  	// Message lifecycle - emitted for user, assistant, and toolResult messages
  414  	| { type: "message_start"; message: AgentMessage }
  415  	// Only emitted for assistant messages during streaming
  416  	| { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
  417  	| { type: "message_end"; message: AgentMessage }
  418  	// Tool execution lifecycle
  419  	| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
  420  	| { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
  421  	| { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };

    1  import { mkdirSync, rmSync } from "node:fs";
    2  import { tmpdir } from "node:os";
    3  import { join } from "node:path";
    4  import * as acp from "@agentclientprotocol/sdk";
    5  import { Agent } from "@earendil-works/pi-agent-core";
    6  import {
    7  	type AssistantMessage,
    8  	type Context,
    9  	createAssistantMessageEventStream,
   10  	getModel,
   11  	type TextContent,
   12  	type Usage,