Oh My Pi
从源码学会它怎么工作

  879  /**
  880   * Main loop logic shared by agentLoop and agentLoopContinue.
  881   */
  882  async function runLoop(
  883  	currentContext: AgentContext,
  884  	newMessages: AgentMessage[],
  885  	config: AgentLoopConfig,
  886  	signal: AbortSignal | undefined,
  887  	stream: EventStream<AgentEvent, AgentMessage[]>,
  888  	streamFn?: StreamFn,
  889  	initialMessages: AgentMessage[] = [],
  890  ): Promise<void> {
  891  	const telemetry = resolveTelemetry(config.telemetry, config.sessionId);
  892  	const invokeAgentSpan = startInvokeAgentSpan(telemetry, config.model);
  893  	const stepCounter = { count: 0 };
  894  	let caughtError: unknown;
  895  	try {
  896  		await runInActiveSpan(invokeAgentSpan, () =>
  897  			runLoopBody(
  898  				currentContext,
  899  				newMessages,
  900  				config,
  901  				signal,
  902  				stream,
  903  				telemetry,
      … 4 lines omitted; exact range 879–918 …
  908  			),
  909  		);
  910  	} catch (err) {
  911  		caughtError = err;
  912  		throw err;
  913  	} finally {
  914  		finishInvokeAgentSpan(telemetry, invokeAgentSpan, {
  915  			stepCount: stepCounter.count,
  916  			errorObject: caughtError,
  917  		});
  918  	}

  999  		// Check for steering messages at start (user may have typed while waiting).
 1000  		// Skip when the run is already externally aborted — dequeuing would strand
 1001  		// the messages in a run that is about to die.
 1002  		let pendingMessages: AgentMessage[];
 1003  		try {
 1004  			pendingMessages = signal?.aborted ? [] : (await config.getSteeringMessages?.()) || [];
 1005  		} catch (error) {
 1006  			stream.push({ type: "turn_start" });
 1007  			emitInputMessages(stream, messagesToEmit);
 1008  			throw error;
 1009  		}
 1010  		let harmonyRetryAttempt = 0;
 1011  		let harmonyTruncateResumeCount = 0;
 1012  		let pausedTurnContinuations = 0;
 1013  
 1014  		// Soft tool requirement lifecycle (reminder then escalation; see SoftToolRequirement).
 1015  		// The host-owned state survives only a gate stop between Agent.prompt calls.
 1016  		// Resolved once per logical turn at the fetch site below and reused across
 1017  		// Harmony-leak re-samples (which re-enter the same turn) so the consuming
 1018  		// getToolChoice is never advanced twice; the flag resets at the message boundary.
 1019  		let hostToolChoice: ToolChoice | undefined;
 1020  		let softRequiredTool: string | undefined;
 1021  		let softSatisfies: SoftToolRequirement["satisfies"];
 1022  		let directiveResolvedForTurn = false;
 1023  		let turnOpen = false;
      … 14 lines omitted; exact range 999–1048 …
 1038  				await yieldIfDue();
 1039  				// Park at the turn boundary while the process-wide pause gate is
 1040  				// engaged (host /pause). An external abort releases the park so a
 1041  				// cancelled run still unwinds while everything else stays frozen.
 1042  				if (agentPauseGate.paused) await agentPauseGate.waitUntilResumed(signal);
 1043  
 1044  				// Build the provider-bound context before opening the turn. Queue
 1045  				// messages are added now but their events remain deferred until
 1046  				// provider preparation either succeeds or opens an error turn.
 1047  				const turnMessages = messagesToEmit;
 1048  				messagesToEmit = [];

 2067  /** Per-call outcome of the pre-dispatch prepare phase (validation + `beforeToolCall`). */
 2068  interface PreparedToolCall {
 2069  	tool: AgentTool<any> | undefined;
 2070  	/** Validated (possibly hook-revised) execution args; raw args when validation failed. */
 2071  	args: Record<string, unknown>;
 2072  	validationErrorMessage?: string;
 2073  	blocked?: boolean;
 2074  	blockReason?: string;
 2075  	prepareError?: unknown;
 2076  }
 2077  
 2078  /**
 2079   * Prepare results computed in the stream-done branch (before `message_start`/
 2080   * `message_end`) so a `beforeToolCall` args revision is baked into the message
 2081   * every consumer snapshots. `executeToolCalls` consumes them; a message that
 2082   * bypassed the streamed path (e.g. Harmony-recovered) is prepared at dispatch
 2083   * time instead.
 2084   */
 2085  const preparedDispatchByMessage = new WeakMap<AssistantMessage, Map<string, PreparedToolCall>>();
 2086  
 2087  function resolveToolForCall(
 2088  	tools: AgentTool<any>[] | undefined,
 2089  	toolCall: AgentToolCall,
 2090  	resolveFallbackTool: AgentLoopConfig["resolveFallbackTool"],
 2091  ): AgentTool<any> | undefined {
      … 98 lines omitted; exact range 2067–2200 …
 2190  			// the call anywhere downstream.
 2191  			toolCall.arguments = beforeResult.args;
 2192  			entry.args = revised;
 2193  		}
 2194  	}
 2195  	return prepared;
 2196  }
 2197  /**
 2198   * Execute tool calls from an assistant message.
 2199   */
 2200  async function executeToolCalls(

   26  import {
   27  	type Dialect,
   28  	encodeInbandToolHistory,
   29  	renderInbandToolPrompt,
   30  	renderToolExamples,
   31  	wrapInbandToolStream,
   32  } from "@oh-my-pi/pi-ai/dialect";
   33  import * as AIError from "@oh-my-pi/pi-ai/error";
   34  import { type CursorExecResolvedCarrier, kCursorExecResolved } from "@oh-my-pi/pi-ai/utils/block-symbols";
   35  import {
   36  	createHarmonyAuditEvent,
   37  	detectHarmonyLeakInAssistantMessage,
   38  	extractHarmonyRemoved,
   39  	type HarmonyDetection,
   40  	type HarmonyRecoveredToolCall,
   41  	isHarmonyLeakMitigationTarget,
   42  	recoverHarmonyToolCall,
   43  	signalListLabel,
   44  } from "@oh-my-pi/pi-ai/utils/harmony-leak";
   45  import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";

    1  /**
    2   * The provider catalog table: one entry per chat-model provider, carrying the
    3   * catalog half of what used to live in `@oh-my-pi/pi-ai`'s registry definitions
    4   * (default model, runtime model-manager factory, discovery wiring). The auth
    5   * half (env keys, OAuth login/refresh) stays in the pi-ai registry, which
    6   * type-checks itself against `KnownProvider` from this table.
    7   */
    8  import type { ModelManagerConfig, ProviderCatalogEntry, ProviderDescriptor } from "./descriptor-types";
    9  import { googleModelManagerOptions, googleVertexModelManagerOptions } from "./google";
   10  import { ollamaCloudModelManagerOptions } from "./ollama";
   11  import {
   12  	aimlApiModelManagerOptions,
   13  	alibabaCodingPlanModelManagerOptions,
   14  	alibabaTokenPlanModelManagerOptions,
   15  	anthropicModelManagerOptions,
   16  	basetenModelManagerOptions,
   17  	cerebrasModelManagerOptions,
   18  	cloudflareAiGatewayModelManagerOptions,
   19  	coreWeaveModelManagerOptions,
   20  	deepseekModelManagerOptions,
   21  	firepassModelManagerOptions,
   22  	fireworksModelManagerOptions,
   23  	githubCopilotModelManagerOptions,
   24  	groqModelManagerOptions,
   25  	huggingfaceModelManagerOptions,
      … 30 lines omitted; exact range 1–66 …
   56  	zenmuxModelManagerOptions,
   57  	zhipuCodingPlanModelManagerOptions,
   58  } from "./openai-compat";
   59  import {
   60  	cursorModelManagerOptions,
   61  	devinModelManagerOptions,
   62  	gitLabDuoWorkflowModelManagerOptions,
   63  	zaiModelManagerOptions,
   64  } from "./special";
   65  
   66  export const CATALOG_PROVIDERS = [

  181  const LAZY_STREAM_IDLE_TIMEOUT_ERROR = "Provider stream stalled while waiting for the next event";
  182  const LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR = "Provider stream timed out while waiting for the first event";
  183  
  184  function hasFinalResult(
  185  	source: AsyncIterable<AssistantMessageEvent>,
  186  ): source is AsyncIterable<AssistantMessageEvent> & { result(): Promise<AssistantMessage> } {
  187  	return typeof (source as { result?: unknown }).result === "function";
  188  }
  189  
  190  /**
  191   * floor used when neither caller option nor env var pins a value. Generic env
  192   * vars (`PI_STREAM_FIRST_EVENT_TIMEOUT_MS`, `PI_STREAM_IDLE_TIMEOUT_MS`) still
  193   * take precedence unless a provider opts into OpenAI-family idle flooring for
  194   * local backends that users historically tuned with `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS`.
  195   */
  196  interface LazyStreamLimits {
  197  	defaultFirstEventTimeoutMs?: number;
  198  	defaultIdleTimeoutMs?: number;
  199  	/**
  200  	 * The provider implementation already wraps its upstream transport with
  201  	 * stream timeouts. Keep the lazy loader from racing it with generic errors.
  202  	 */
  203  	providerHandlesStreamTimeouts?: boolean;
  204  	/**
  205  	 * Apply OpenAI-family idle timeout precedence in the lazy wrapper. Used by
      … 14 lines omitted; exact range 181–230 …
  220  const GOOGLE_GEMINI_CLI_LAZY_STREAM_LIMITS: LazyStreamLimits = {
  221  	defaultFirstEventTimeoutMs: 300_000,
  222  };
  223  
  224  const PROVIDER_HANDLED_STREAM_TIMEOUTS: LazyStreamLimits = {
  225  	providerHandlesStreamTimeouts: true,
  226  };
  227  
  228  const OPENAI_IDLE_FLOORED_LAZY_STREAM_LIMITS: LazyStreamLimits = {
  229  	openAIIdleEnvFloorsFirstEvent: true,
  230  };

   38  import { AskTool } from "./ask";
   39  import { AstEditTool } from "./ast-edit";
   40  import { AstGrepTool } from "./ast-grep";
   41  import { BashTool } from "./bash";
   42  import { BrowserTool } from "./browser";
   43  import { type BuiltinToolName, type HiddenToolName, normalizeToolNames } from "./builtin-names";
   44  import { type CheckpointState, CheckpointTool, type CompletedRewindState, RewindTool } from "./checkpoint";
   45  import { ComputerTool } from "./computer";
   46  import { DebugTool } from "./debug";
   47  import { EvalTool } from "./eval";
   48  import { resolveEvalBackends } from "./eval-backends";
   49  import { GithubTool } from "./gh";
   50  import { GlobTool } from "./glob";
   51  import { GrepTool } from "./grep";
   52  import { HubTool, isIrcEnabled } from "./hub";
   53  import { InspectImageTool } from "./inspect-image";
   54  import { LearnTool } from "./learn";
   55  import { ManageSkillTool } from "./manage-skill";
   56  import { MemoryEditTool } from "./memory-edit";
   57  import { MemoryRecallTool } from "./memory-recall";
   58  import { MemoryReflectTool } from "./memory-reflect";
   59  import { MemoryRetainTool } from "./memory-retain";
   60  import { wrapToolWithMetaNotice } from "./output-meta";
   61  import { ReadTool } from "./read";
   62  import type { PlanProposalHandler } from "./resolve";
      … 32 lines omitted; exact range 38–105 …
   95  export * from "./memory-recall";
   96  export * from "./memory-reflect";
   97  export * from "./memory-retain";
   98  export * from "./read";
   99  export * from "./report-tool-issue";
  100  export * from "./resolve";
  101  export * from "./review";
  102  export * from "./todo";
  103  export * from "./tts";
  104  export * from "./vibe";
  105  export * from "./write";

   13  export type ApprovalPolicy = "allow" | "deny" | "prompt";
   14  export type ApprovalMode = "always-ask" | "write" | "yolo";
   15  
   16  type ApprovalSubject = Pick<AgentTool, "name" | "approval" | "formatApprovalDetails">;
   17  
   18  export interface ResolvedApproval {
   19  	policy: ApprovalPolicy;
   20  	tier: ToolTier;
   21  	reason?: string;
   22  	override: boolean;
   23  	source?: "tool" | "user" | "mode";
   24  }
   25  
   26  const POLICY_VALUES: ReadonlySet<ApprovalPolicy> = new Set(["allow", "deny", "prompt"]);
   27  const TIER_VALUES: ReadonlySet<ToolTier> = new Set(["read", "write", "exec"]);
   28  
   29  const TIER_RANK: Record<ToolTier, number> = {
   30  	read: 0,
   31  	write: 1,
   32  	exec: 2,
   33  };
   34  
   35  const APPROVAL_MODE_MAX_TIER: Record<ApprovalMode, ToolTier> = {
   36  	"always-ask": "read",
   37  	write: "write",
   38  	yolo: "exec",
   39  };

    1  import * as path from "node:path";
    2  import type { Agent } from "@oh-my-pi/pi-agent-core";
    3  import { logger } from "@oh-my-pi/pi-utils";
    4  import type { Settings } from "../config/settings";
    5  import { type BashResult, executeBash as executeBashCommand } from "../exec/bash-executor";
    6  import type { ExtensionRunner } from "../extensibility/extensions";
    7  import { outputMeta } from "../tools/output-meta";
    8  import { clampTimeout } from "../tools/tool-timeouts";
    9  import type { BashExecutionMessage } from "./messages";
   10  import type { SessionManager } from "./session-manager";
   11  
   12  /** Destination that owns a bash result after a session or branch transition. */
   13  export type BashAppendDestination =
   14  	| { kind: "current"; manager: SessionManager }
   15  	| { kind: "detached"; manager: SessionManager }
   16  	| { kind: "branch"; manager: SessionManager; parentId: string | null };
   17  
   18  /** Reference-counted session target captured when a bash execution starts. */
   19  export interface BashSessionTarget {
   20  	sessionId: string;
   21  	refs: number;
   22  	destination?: BashAppendDestination;
   23  	pending?: Promise<BashAppendDestination>;
   24  }
   25  
      … 184 lines omitted; exact range 1–220 …
  210  
  211  	/** Resolves destinations opened by beginSessionTransition. */
  212  	finishSessionTransition(transition: BashSessionTransition, success: boolean): void {
  213  		const manager = this.#host.sessionManager;
  214  		const currentDestination: BashAppendDestination = { kind: "current", manager };
  215  		let oldDestination: BashAppendDestination = currentDestination;
  216  		if (success && transition.resolveOld) {
  217  			const currentFile = manager.getSessionFile();
  218  			const sameFile =
  219  				transition.oldSessionFile === currentFile ||
  220  				(transition.oldSessionFile !== undefined &&

  148  	summary: string;
  149  	/** Short PR-style summary for display purposes. */
  150  	shortSummary?: string;
  151  	firstKeptEntryId: string;
  152  	tokensBefore: number;
  153  	/** Hook-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
  154  	details?: T;
  155  	/** Hook-provided data to persist alongside compaction entry. */
  156  	preserveData?: Record<string, unknown>;
  157  }
  158  
  159  // ============================================================================
  160  // Types
  161  // ============================================================================
  162  
  163  export interface CompactionSettings {
  164  	enabled: boolean;
  165  	strategy?: "context-full" | "handoff" | "shake" | "snapcompact" | "off";
  166  	thresholdPercent?: number;
  167  	thresholdTokens?: number;
  168  	midTurnEnabled?: boolean;
  169  	/**
  170  	 * Tokens reserved below the context window for the next prompt + response.
  171  	 *
  172  	 * Leave unset to use {@link DEFAULT_RESERVE_TOKENS}; the unset state is the
      … 6 lines omitted; exact range 148–189 …
  179  	autoContinue?: boolean;
  180  	remoteEnabled?: boolean;
  181  	remoteEndpoint?: string;
  182  	remoteStreamingV2Enabled?: boolean;
  183  	v2RetainedMessageBudget?: number;
  184  }
  185  
  186  /** Reserve applied when {@link CompactionSettings.reserveTokens} is unset. */
  187  export const DEFAULT_RESERVE_TOKENS = 16384;
  188  
  189  // reserveTokens is deliberately absent: an unset reserve is what marks it as

  501  	const cutPoints: number[] = [];
  502  	for (let i = startIndex; i < endIndex; i++) {
  503  		const entry = entries[i];
  504  		switch (entry.type) {
  505  			case "message": {
  506  				const role = entry.message.role as string;
  507  				switch (role) {
  508  					case "bashExecution":
  509  					case "hookMessage":
  510  					case "branchSummary":
  511  					case "compactionSummary":
  512  					case "user":
  513  					case "assistant":
  514  						cutPoints.push(i);
  515  						break;
  516  					case "toolResult":
  517  						break;
  518  				}
  519  				break;
  520  			}
  521  			case "thinking_level_change":
  522  			case "model_change":
  523  			case "compaction":
  524  			case "branch_summary":
  525  			case "custom":
      … 100 lines omitted; exact range 501–636 …
  626  			break;
  627  		}
  628  		if (prevEntry.type === "message") {
  629  			// Stop if we hit any message
  630  			break;
  631  		}
  632  		// Include this non-message entry (bash, settings change, etc.)
  633  		cutIndex--;
  634  	}
  635  
  636  	// Determine if this is a split turn

    1  /**
    2   * Tool output pruning utilities for compaction.
    3   */
    4  
    5  import type { ToolResultMessage } from "@oh-my-pi/pi-ai";
    6  import type { AgentMessage, AgentToolCall } from "../types";
    7  import { estimateTokens } from "./compaction";
    8  import type { SessionEntry, SessionMessageEntry } from "./entries";
    9  import { invalidateMessageCache } from "./message-cache";
   10  import {
   11  	collectToolCallsById,
   12  	isProtectedToolResult,
   13  	isSkillReadToolResult,
   14  	type ProtectedToolMatcher,
   15  } from "./tool-protection";
   16  import { splitReadSelector } from "./utils";
   17  
   18  export interface PruneConfig {
   19  	/** Keep the most recent tool output tokens intact. */
   20  	protectTokens: number;
   21  	/** Only prune if total savings meets this threshold. */
   22  	minimumSavings: number;
   23  	/** Tool-result protection matchers. String entries protect every result from that tool; predicates may inspect the paired tool call. */
   24  	protectedTools: ProtectedToolMatcher[];
   25  	/**
      … 224 lines omitted; exact range 1–260 …
  250  	const toolCallsById = collectToolCallsById(entries);
  251  	const candidates = config.supersedeKey
  252  		? collectSupersededResults(entries, toolCallsById, config.supersedeKey, config.protectedTools)
  253  		: [];
  254  	if (config.pruneUseless) {
  255  		const exclude = new Set(candidates.map(candidate => candidate.message));
  256  		candidates.push(...collectUselessResults(entries, toolCallsById, config.protectedTools, exclude));
  257  		candidates.sort((a, b) => a.index - b.index);
  258  	}
  259  	if (candidates.length === 0) return { prunedCount: 0, tokensSaved: 0 };
  260  

    6  /**
    7   * Pick the active memory backend for a Settings instance.
    8   *
    9   * Selection rules (single source of truth — every memory consumer routes
   10   * through this):
   11   *   - `memory.backend === "hindsight"`  → Hindsight remote memory
   12   *   - `memory.backend === "mnemopi"`  → local Mnemopi SQLite memory
   13   *   - `memory.backend === "local"`      → local rollout summary pipeline
   14   *   - everything else                   → no-op
   15   *
   16   * `memories.enabled` remains accepted only as a legacy migration input. Once
   17   * a config is loaded, `memory.backend` is the sole runtime selector.
   18   */
   19  export async function resolveMemoryBackend(settings: Settings): Promise<MemoryBackend> {
   20  	const id = settings.get("memory.backend");
   21  	if (id === "hindsight") return (await import("../hindsight/backend")).hindsightBackend;
   22  	if (id === "mnemopi") return (await import("../mnemopi/backend")).mnemopiBackend;
   23  	if (id === "local") return localBackend;
   24  	return offBackend;

  282  	setNotificationsEnabled(enabled: boolean): void {
  283  		const wasEnabled = this.#notificationsEnabled;
  284  		this.#notificationsEnabled = enabled;
  285  		if (enabled === wasEnabled) return;
  286  
  287  		this.#notificationsEpoch += 1;
  288  		const notificationEpoch = this.#notificationsEpoch;
  289  
  290  		if (enabled) {
  291  			// Subscribe to all connected servers that support it
  292  			for (const [name, connection] of this.#connections) {
  293  				if (connection.capabilities.resources?.subscribe && connection.resources) {
  294  					const uris = connection.resources.map(r => r.uri);
  295  					this.#subscribeAndTrack(name, connection, uris, notificationEpoch);
  296  				}
  297  			}
  298  			return;
  299  		}
  300  
  301  		// Unsubscribe from all servers
  302  		for (const [name, connection] of this.#connections) {
  303  			const uris = this.#subscribedResources.get(name);
  304  			if (uris && uris.size > 0) {
  305  				void unsubscribeFromResources(connection, Array.from(uris)).catch(error => {
  306  					logger.debug("Failed to unsubscribe MCP resources", { path: `mcp:${name}`, error });
      … 63 lines omitted; exact range 282–380 …
  370  		const validationFailures: Array<{ name: string; message: string }> = [];
  371  
  372  		// Prepare connection tasks
  373  		const connectionTasks: ConnectionTask[] = [];
  374  
  375  		for (const [name, config] of Object.entries(configs)) {
  376  			if (sources[name]) {
  377  				this.#sources.set(name, sources[name]);
  378  				const existing = this.#connections.get(name);
  379  				if (existing) {
  380  					existing._source = sources[name];

   88  // MCP Servers (opencode.json → mcp)
   89  // =============================================================================
   90  
   91  /** OpenCode MCP server config (from opencode.json "mcp" key) */
   92  interface OpenCodeMCPConfig {
   93  	type?: "local" | "remote";
   94  	command?: string | string[];
   95  	args?: string[];
   96  	env?: Record<string, string>;
   97  	environment?: Record<string, string>;
   98  	url?: string;
   99  	headers?: Record<string, string>;
  100  	enabled?: boolean;
  101  	timeout?: number;
  102  }
  103  
  104  function stringArray(value: unknown): string[] | undefined {
  105  	if (!Array.isArray(value)) return undefined;
  106  	for (const item of value) {
  107  		if (typeof item !== "string") return undefined;
  108  	}
  109  	return value;
  110  }
  111  
  112  function stringRecord(value: unknown): Record<string, string> | undefined {
      … 44 lines omitted; exact range 88–167 …
  157  
  158  	// Project-level: opencode.json in project root
  159  	const projectConfigPath = path.join(ctx.cwd, "opencode.json");
  160  	const projectConfig = await loadJsonConfig(projectConfigPath);
  161  	if (projectConfig) {
  162  		const result = extractMCPServers(projectConfig, projectConfigPath, "project");
  163  		items.push(...result.items);
  164  		if (result.warnings) warnings.push(...result.warnings);
  165  	}
  166  
  167  	return { items, warnings };

  332  export interface LoadContextFilesOptions {
  333  	/** Working directory to start walking up from. Default: getProjectDir() */
  334  	cwd?: string;
  335  }
  336  
  337  function dedupeExactContextFiles(
  338  	contextFiles: Array<{ path: string; content: string; depth?: number }>,
  339  ): Array<{ path: string; content: string; depth?: number }> {
  340  	const lastIndexByContent = new Map<string, number>();
  341  	for (const [index, file] of contextFiles.entries()) {
  342  		// Keep the closest matching context entry when content is byte-for-byte identical.
  343  		lastIndexByContent.set(file.content, index);
  344  	}
  345  
  346  	return contextFiles.filter((file, index) => lastIndexByContent.get(file.content) === index);
  347  }
  348  
  349  /**
  350   * Load all project context files using the capability API.
  351   * Returns {path, content, depth} entries for all discovered context files.
  352   * Files are sorted by depth (descending) so files closer to cwd appear last/more prominent.
  353   */
  354  export async function loadProjectContextFiles(
  355  	options: LoadContextFilesOptions = {},
  356  ): Promise<Array<{ path: string; content: string; depth?: number }>> {
      … 38 lines omitted; exact range 332–405 …
  395  
  396  	if (result.items.length === 0) return null;
  397  
  398  	const projectLevel = result.items.find(item => item.level === "project");
  399  	if (projectLevel) {
  400  		return projectLevel.content;
  401  	}
  402  
  403  	const userLevel = result.items.find(item => item.level === "user");
  404  	return userLevel?.content ?? null;
  405  }

  120  		throw new ExtensionRuntimeNotInitializedError();
  121  	}
  122  
  123  	setServiceTier(): void {
  124  		throw new ExtensionRuntimeNotInitializedError();
  125  	}
  126  
  127  	getSessionName(): string | undefined {
  128  		throw new ExtensionRuntimeNotInitializedError();
  129  	}
  130  
  131  	setSessionName(): Promise<void> {
  132  		throw new ExtensionRuntimeNotInitializedError();
  133  	}
  134  }
  135  
  136  /**
  137   * ExtensionAPI implementation for an extension.
  138   * Registration methods write to the extension object.
  139   * Action methods delegate to the shared runtime.
  140   */
  141  class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
  142  	readonly logger = logger;
  143  	readonly typebox = TypeBox;
  144  	readonly arktype = Type;
      … 75 lines omitted; exact range 120–230 …
  220  	}
  221  
  222  	sendMessage<T = unknown>(
  223  		message: CustomMessagePayload<T>,
  224  		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
  225  	): void {
  226  		this.runtime.sendMessage(message, options);
  227  	}
  228  
  229  	sendUserMessage(
  230  		content: string | (TextContent | ImageContent)[],

    1  /**
    2   * Task tool - Delegate tasks to specialized agents.
    3   *
    4   * Discovers agent definitions from:
    5   *   - Bundled agents (shipped with omp-coding-agent)
    6   *   - ~/.omp/agent/agents/*.md (user-level)
    7   *   - .omp/agents/*.md (project-level)
    8   *
    9   * Supports:
   10   *   - Single agent spawn per call (parallelism = parallel task calls)
   11   *   - Batch spawning + shared context per call when `task.batch` is enabled
   12   *   - Background execution through AsyncJobManager when `async.enabled` is enabled
   13   *   - Progress tracking via JSON events
   14   *   - Session artifacts for debugging
   15   */
   16  import path from "node:path";
   17  import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
   18  import type { Usage } from "@oh-my-pi/pi-ai";
   19  import { $env, logger, prompt } from "@oh-my-pi/pi-utils";
   20  import type { ToolSession } from "..";
   21  import type { Theme } from "../modes/theme/theme";
   22  import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.md" with { type: "text" };
   23  import taskDescriptionTemplate from "../prompts/tools/task.md" with { type: "text" };
   24  import taskAsyncContractTemplate from "../prompts/tools/task-async-contract.md" with { type: "text" };
   25  import taskSummaryTemplate from "../prompts/tools/task-summary.md" with { type: "text" };
      … 17 lines omitted; exact range 1–53 …
   43  import "../tools/review";
   44  import type { AsyncJobManager } from "../async";
   45  import { hasResolvableTranscript } from "../internal-urls/registry-helpers";
   46  import { AgentRegistry } from "../registry/agent-registry";
   47  import { type DiscoveryResult, discoverAgents } from "./discovery";
   48  import { generateTaskName } from "./name-generator";
   49  import { AgentOutputManager } from "./output-manager";
   50  import { mapWithConcurrencyLimitAllSettled, Semaphore } from "./parallel";
   51  import { renderResult, renderCall as renderTaskCall } from "./render";
   52  import { repairTaskParams } from "./repair-args";
   53  import { resolveEffectiveSubagentPolicy, runStructuredSubagent, StructuredSubagentError } from "./structured-subagent";

 4505  	"task.maxConcurrency": {
 4506  		type: "number",
 4507  		default: 32,
 4508  		ui: {
 4509  			tab: "tasks",
 4510  			group: "Subagents",
 4511  			label: "Max Concurrent Tasks",
 4512  			description: "Maximum number of subagents running concurrently",
 4513  			options: [
 4514  				{ value: "0", label: "Unlimited" },
 4515  				{ value: "1", label: "1 task" },
 4516  				{ value: "2", label: "2 tasks" },
 4517  				{ value: "4", label: "4 tasks" },
 4518  				{ value: "8", label: "8 tasks" },
 4519  				{ value: "16", label: "16 tasks" },
 4520  				{ value: "32", label: "32 tasks" },
 4521  				{ value: "64", label: "64 tasks" },
 4522  			],
 4523  		},
 4524  	},
 4525  
 4526  	"task.enableLsp": {
 4527  		type: "boolean",
 4528  		default: false,
 4529  		ui: {
      … 74 lines omitted; exact range 4505–4614 …
 4604  
 4605  	"task.softRequestBudgetNotice": {
 4606  		type: "boolean",
 4607  		default: true,
 4608  		ui: {
 4609  			tab: "tasks",
 4610  			group: "Subagents",
 4611  			label: "Soft Request Budget Notice",
 4612  			description:
 4613  				"Inject one steering notice when a subagent crosses its soft request budget, asking it to wrap up before the 1.5x forced-yield stop.",
 4614  		},

  412  /**
  413   * Suggestion — never a rejection — nudging the spawner to coordinate via the
  414   * hub when one call creates ≥2 live siblings and it still holds spawn
  415   * capacity. Returns undefined when there is nothing to coordinate or peer
  416   * messaging is unavailable.
  417   */
  418  export function buildCoordinationAdvisory(
  419  	items: TaskItem[],
  420  	depthCapacity: boolean,
  421  	ircEnabled: boolean,
  422  ): string | undefined {
  423  	if (!depthCapacity || !ircEnabled || items.length < 2) return undefined;
  424  	return (
  425  		`Coordinate: ${items.length} siblings are running together. If their work overlaps, have them ` +
  426  		`message each other via \`hub\` (by id, or "all" to broadcast) before editing shared files — ` +
  427  		`live coordination beats a serial handoff. Check \`hub\` op:"list" to see who is doing what.`
  428  	);
  429  }

    1  import * as fs from "node:fs";
    2  import * as fsp from "node:fs/promises";
    3  import * as path from "node:path";
    4  import { hasFsCode, isEnoent, logger, peekFileEnds, Snowflake, toError } from "@oh-my-pi/pi-utils";
    5  import { overlayTitleSlotContent, type SessionTitleUpdate, serializeTitleSlot } from "./session-title-slot";
    6  
    7  const utf8Decoder = new TextDecoder("utf-8");
    8  
    9  export interface SessionStorageStat {
   10  	size: number;
   11  	mtimeMs: number;
   12  	mtime: Date;
   13  }
   14  
   15  export interface SessionStorageWriter {
   16  	/**
   17  	 * Append one newline-terminated line. File and memory storage perform the
   18  	 * write synchronously in-body; indexed backends queue in call order.
   19  	 *
   20  	 * `line` MUST include the trailing newline.
   21  	 */
   22  	append(line: string): Promise<void>;
   23  	/** Resolve once all queued appends complete. No fsync. */
   24  	flush(): Promise<void>;
   25  	/** False once close() has begun/finished. */
      … 224 lines omitted; exact range 1–260 …
  250  		await Bun.write(path, content, { createPath: true });
  251  	}
  252  
  253  	async writeTextAtomic(fpath: string, content: string, options?: WriteTextAtomicOptions): Promise<void> {
  254  		const dir = path.resolve(fpath, "..");
  255  		const tempPath = path.join(dir, `.${path.basename(fpath)}.${Snowflake.next()}.tmp`);
  256  		await fs.promises.mkdir(dir, { recursive: true });
  257  		try {
  258  			await fs.promises.writeFile(tempPath, content);
  259  		} catch (err) {
  260  			this.#discardTemp(tempPath, fpath);

    1  /**
    2   * OpenTelemetry instrumentation for the agent loop.
    3   *
    4   * Implements the OpenTelemetry GenAI semantic conventions
    5   * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `pi.gen_ai.*`
    6   * extension attributes for run summaries, dashboard summaries, and cost hints
    7   * that are useful to downstream observability UIs.
    8   *
    9   * Span hierarchy emitted by the loop:
   10   *
   11   *   invoke_agent {agent.name}         (one per runLoop, gen_ai.operation.name=invoke_agent)
   12   *   ├── chat {model}                  (one per LLM call, gen_ai.operation.name=chat)
   13   *   ├── execute_tool {tool.name}      (one per tool call, gen_ai.operation.name=execute_tool)
   14   *   └── ...
   15   *
   16   * The `handoff` operation is emitted via the public {@link recordHandoff}
   17   * helper for hosts that route work between named agents.
   18   *
   19   * Activation is opt-in: callers pass an {@link AgentTelemetryConfig} on
   20   * `AgentLoopConfig.telemetry`. When unset, every helper short-circuits and
   21   * the loop performs zero tracer lookups. When set but no OTEL SDK is
   22   * registered, `@opentelemetry/api` returns a no-op tracer and all calls are
   23   * cheap pass-throughs.
   24   */

    1  import { afterEach, describe, expect, it, vi } from "bun:test";
    2  import * as fs from "node:fs/promises";
    3  import * as os from "node:os";
    4  import * as path from "node:path";
    5  import * as executorModule from "@oh-my-pi/pi-coding-agent/task/executor";
    6  import {
    7  	applyEligibleNestedPatches,
    8  	mergeIsolatedChanges,
    9  	runIsolatedSubprocess,
   10  } from "@oh-my-pi/pi-coding-agent/task/isolation-runner";
   11  import type { SingleResult } from "@oh-my-pi/pi-coding-agent/task/types";
   12  import * as worktreeModule from "@oh-my-pi/pi-coding-agent/task/worktree";
   13  import * as gitModule from "@oh-my-pi/pi-coding-agent/utils/git";
   14  import * as natives from "@oh-my-pi/pi-natives";
   15  import { $ } from "bun";
   16  
   17  function result(overrides: Partial<SingleResult> = {}): SingleResult {
   18  	return {
   19  		index: 0,
   20  		id: "NestedOnly",
   21  		agent: "task",
   22  		agentSource: "bundled",
   23  		task: "Do nested work",
   24  		assignment: "Do nested work",
   25  		exitCode: 0,
      … 64 lines omitted; exact range 1–100 …
   90  				untracked: [],
   91  				untrackedPatch: "",
   92  			},
   93  			nested: [],
   94  		};
   95  		const rootPatch = "diff --git a/task.txt b/task.txt\n--- a/task.txt\n+++ b/task.txt\n@@ -1 +1 @@\n-old\n+new\n";
   96  
   97  		vi.spyOn(worktreeModule, "ensureIsolation").mockResolvedValue({
   98  			mergedDir: isolationDir,
   99  			backend: natives.IsoBackendKind.Rcopy,
  100  			fellBack: false,