Pi
从源码学会它怎么工作

  171  export class AgentHarness<
  172  	TContext extends object | undefined = undefined,
  173  	TSkill extends Skill = Skill,
  174  	TPromptTemplate extends PromptTemplate = PromptTemplate,
  175  	TTool extends AgentHarnessTool<TContext> = AgentHarnessTool<TContext>,
  176  > {
  177  	private session: Session;
  178  	readonly models: Models;
  179  	private phase: AgentHarnessPhase = "idle";
  180  	private runAbortController?: AbortController;
  181  	private runPromise?: Promise<void>;
  182  	private pendingSessionWrites: PendingSessionWrite[] = [];
  183  	private model: Model<any>;
  184  	private thinkingLevel: ThinkingLevel;
  185  	private systemPrompt: AgentHarnessSystemPrompt<TContext, TSkill, TPromptTemplate, TTool> | undefined;
  186  	private toolContext: AgentHarnessToolContextSource<TContext> | undefined;
  187  	private streamOptions: AgentHarnessStreamOptions;
  188  	private retry: RetryPolicy | undefined;
  189  	private resources: AgentHarnessResources<TSkill, TPromptTemplate>;
  190  	private tools = new Map<string, TTool>();
  191  	private activeToolNames: string[];
  192  	private steerQueue: UserMessage[] = [];
  193  	private steeringQueueMode: QueueMode;
  194  	private followUpQueue: UserMessage[] = [];
  195  	private followUpQueueMode: QueueMode;
      … 17 lines omitted; exact range 171–223 …
  213  		}
  214  		this.model = options.model;
  215  		this.thinkingLevel = options.thinkingLevel ?? "off";
  216  		this.activeToolNames = options.activeToolNames
  217  			? [...options.activeToolNames]
  218  			: (options.tools ?? []).map((tool) => tool.name);
  219  		this.validateUniqueNames(this.activeToolNames, "Duplicate active tool name(s)");
  220  		this.validateToolNames(this.activeToolNames);
  221  		this.steeringQueueMode = options.steeringMode ?? "one-at-a-time";
  222  		this.followUpQueueMode = options.followUpMode ?? "one-at-a-time";
  223  	}

  155  async function runLoop(
  156  	initialContext: AgentContext,
  157  	newMessages: AgentMessage[],
  158  	initialConfig: AgentLoopConfig,
  159  	signal: AbortSignal | undefined,
  160  	emit: AgentEventSink,
  161  	streamFunction: StreamFn,
  162  ): Promise<void> {
  163  	let currentContext = initialContext;
  164  	let config = initialConfig;
  165  	let firstTurn = true;
  166  	// Check for steering messages at start (user may have typed while waiting)
  167  	let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];
  168  
  169  	// Outer loop: continues when queued follow-up messages arrive after agent would stop
  170  	while (true) {
  171  		let hasMoreToolCalls = true;
  172  
  173  		// Inner loop: process tool calls and steering messages
  174  		while (hasMoreToolCalls || pendingMessages.length > 0) {
  175  			if (!firstTurn) {
  176  				await emit({ type: "turn_start" });
  177  			} else {
  178  				firstTurn = false;
  179  			}
      … 85 lines omitted; exact range 155–275 …
  265  			// Set as pending so inner loop processes them
  266  			pendingMessages = followUpMessages;
  267  			continue;
  268  		}
  269  
  270  		// No more messages, exit
  271  		break;
  272  	}
  273  
  274  	await emit({ type: "agent_end", messages: newMessages });
  275  }

  208  				// A "length" stop means the output was cut off by the token limit, so
  209  				// every tool call in the message may carry truncated arguments. Fail
  210  				// them all instead of executing potentially borked calls.
  211  				const executedToolBatch =
  212  					message.stopReason === "length"
  213  						? await failToolCallsFromTruncatedMessage(toolCalls, emit)
  214  						: await executeToolCalls(currentContext, message, config, signal, emit);
  215  				toolResults.push(...executedToolBatch.messages);
  216  				hasMoreToolCalls = !executedToolBatch.terminate;
  217  
  218  				for (const result of toolResults) {
  219  					currentContext.messages.push(result);
  220  					newMessages.push(result);
  221  				}
  222  			}
  223  
  224  			await emit({ type: "turn_end", message, toolResults });
  225  
  226  			const nextTurnContext = {
  227  				message,
  228  				toolResults,
  229  				context: currentContext,
  230  				newMessages,
  231  			};
  232  			const nextTurnSnapshot = await config.prepareNextTurn?.(nextTurnContext);
      … 2 lines omitted; exact range 208–245 …
  235  				config = {
  236  					...config,
  237  					model: nextTurnSnapshot.model ?? config.model,
  238  					reasoning:
  239  						nextTurnSnapshot.thinkingLevel === undefined
  240  							? config.reasoning
  241  							: nextTurnSnapshot.thinkingLevel === "off"
  242  								? undefined
  243  								: nextTurnSnapshot.thinkingLevel,
  244  				};
  245  			}

  354  	private async createTurnState(): Promise<AgentHarnessTurnState<TContext, TSkill, TPromptTemplate, TTool>> {
  355  		const context = await this.session.buildContext();
  356  		const resources = this.getResources();
  357  		const sessionMetadata = await this.session.getMetadata();
  358  		const toolContext = await this.resolveToolContext();
  359  		const tools = [...this.tools.values()];
  360  		const activeTools = this.activeToolNames
  361  			.map((name) => this.tools.get(name))
  362  			.filter((tool): tool is TTool => tool !== undefined);
  363  		let systemPrompt = "You are a helpful assistant.";
  364  		if (typeof this.systemPrompt === "string") {
  365  			systemPrompt = this.systemPrompt;
  366  		} else if (this.systemPrompt) {
  367  			systemPrompt = await this.systemPrompt({
  368  				session: this.session,
  369  				model: this.model,
  370  				thinkingLevel: this.thinkingLevel,
  371  				activeTools,
  372  				resources,
  373  			});
  374  		}
  375  		return {
  376  			messages: context.messages,
  377  			resources,
  378  			toolContext,
      … 108 lines omitted; exact range 354–497 …
  487  				const nextTurnState = await this.createTurnState();
  488  				setTurnState(nextTurnState);
  489  				return {
  490  					context: this.createContext(nextTurnState),
  491  					model: nextTurnState.model,
  492  					thinkingLevel: nextTurnState.thinkingLevel,
  493  				};
  494  			},
  495  			getSteeringMessages: async () => this.drainQueuedMessages(this.steerQueue, this.steeringQueueMode),
  496  			getFollowUpMessages: async () => this.drainQueuedMessages(this.followUpQueue, this.followUpQueueMode),
  497  		};

    5  import { amazonBedrockProvider } from "./amazon-bedrock.ts";
    6  import { antLingProvider } from "./ant-ling.ts";
    7  import { anthropicProvider } from "./anthropic.ts";
    8  import { azureOpenAIResponsesProvider } from "./azure-openai-responses.ts";
    9  import { cerebrasProvider } from "./cerebras.ts";
   10  import { cloudflareAIGatewayProvider } from "./cloudflare-ai-gateway.ts";
   11  import { cloudflareWorkersAIProvider } from "./cloudflare-workers-ai.ts";
   12  import modelDataManifest from "./data/.manifest.json" with { type: "json" };
   13  import { deepseekProvider } from "./deepseek.ts";
   14  import { fireworksProvider } from "./fireworks.ts";
   15  import { githubCopilotProvider } from "./github-copilot.ts";
   16  import { googleProvider } from "./google.ts";
   17  import { googleVertexProvider } from "./google-vertex.ts";
   18  import { groqProvider } from "./groq.ts";
   19  import { huggingfaceProvider } from "./huggingface.ts";
   20  import { kimiCodingProvider } from "./kimi-coding.ts";
   21  import { minimaxProvider } from "./minimax.ts";
   22  import { minimaxCnProvider } from "./minimax-cn.ts";
   23  import { mistralProvider } from "./mistral.ts";
   24  import { moonshotaiProvider } from "./moonshotai.ts";
   25  import { moonshotaiCnProvider } from "./moonshotai-cn.ts";
   26  import { nvidiaProvider } from "./nvidia.ts";
   27  import { openaiProvider } from "./openai.ts";
   28  import { openaiCodexProvider } from "./openai-codex.ts";
   29  import { opencodeProvider } from "./opencode.ts";
      … 4 lines omitted; exact range 5–44 …
   34  import { qwenTokenPlanCnProvider } from "./qwen-token-plan-cn.ts";
   35  import { radiusProvider } from "./radius.ts";
   36  import { togetherProvider } from "./together.ts";
   37  import { vercelAIGatewayProvider } from "./vercel-ai-gateway.ts";
   38  import { xaiProvider } from "./xai.ts";
   39  import { xiaomiProvider } from "./xiaomi.ts";
   40  import { xiaomiTokenPlanAmsProvider } from "./xiaomi-token-plan-ams.ts";
   41  import { xiaomiTokenPlanCnProvider } from "./xiaomi-token-plan-cn.ts";
   42  import { xiaomiTokenPlanSgpProvider } from "./xiaomi-token-plan-sgp.ts";
   43  import { zaiProvider } from "./zai.ts";
   44  import { zaiCodingCnProvider } from "./zai-coding-cn.ts";

  193  	private providerIds(): Set<string> {
  194  		return new Set([
  195  			...this.builtins.keys(),
  196  			...this.nativeExtensionProviders.keys(),
  197  			...this.config.getProviderIds(),
  198  			...this.extensionProviders.keys(),
  199  		]);
  200  	}
  201  
  202  	private recomposeProvider(providerId: string): void {
  203  		const base = this.nativeExtensionProviders.get(providerId) ?? this.builtins.get(providerId);
  204  		const extension = this.extensionProviders.get(providerId);
  205  		if (!base && !this.config.getProvider(providerId) && !extension) {
  206  			this.models.deleteProvider(providerId);
  207  			this.compositionErrors.delete(providerId);
  208  			return;
  209  		}
  210  		if (base && !this.config.getProvider(providerId) && !extension) {
  211  			// No overlays: use the builtin untouched so its auth/login/stream behavior is exact.
  212  			this.models.setProvider(base);
  213  			this.compositionErrors.delete(providerId);
  214  			return;
  215  		}
  216  		try {
  217  			this.models.setProvider(composeModelProvider(providerId, base, this.config, extension));
      … 2 lines omitted; exact range 193–230 …
  220  			this.compositionErrors.set(providerId, error instanceof Error ? error.message : String(error));
  221  			if (base) this.models.setProvider(base);
  222  			else this.models.deleteProvider(providerId);
  223  		}
  224  	}
  225  
  226  	private rebuildProviders(): void {
  227  		this.models.clearProviders();
  228  		this.compositionErrors.clear();
  229  		for (const providerId of this.providerIds()) this.recomposeProvider(providerId);
  230  		this.updateModelSnapshot();

   22  /** Mirrors the pinned OpenAI/Anthropic SDK retry policy; review when either SDK is upgraded. */
   23  function isRetryableProviderError(error: ProviderError): boolean {
   24  	const shouldRetry = error.headers?.get("x-should-retry");
   25  	if (shouldRetry === "true") return true;
   26  	if (shouldRetry === "false") return false;
   27  
   28  	if (error.status === undefined) return true;
   29  	return (
   30  		error.status === 408 ||
   31  		error.status === 409 ||
   32  		error.status === 429 ||
   33  		(typeof error.status === "number" && error.status >= 500)
   34  	);
   35  }
   36  
   37  function validateServerRetryDelayMs(
   38  	delayMs: number,
   39  	maxRetryDelayMs: number | undefined,
   40  	providerErrorMessage: string,
   41  ): number {
   42  	const maxDelayMs = maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
   43  	if (maxDelayMs > 0 && delayMs > maxDelayMs) {
   44  		throw new Error(
   45  			`Server requested ${Math.ceil(delayMs / 1000)}s retry delay (max: ${Math.ceil(maxDelayMs / 1000)}s). ${providerErrorMessage}`,
   46  		);
      … 9 lines omitted; exact range 22–66 …
   56  	}
   57  
   58  	const retryAfter = error.headers?.get("retry-after");
   59  	if (retryAfter) {
   60  		const seconds = Number.parseFloat(retryAfter);
   61  		const delayMs = Number.isNaN(seconds) ? Date.parse(retryAfter) - Date.now() : seconds * 1000;
   62  		return validateServerRetryDelayMs(delayMs, maxRetryDelayMs, error.message);
   63  	}
   64  
   65  	const exponentialDelay = Math.min(0.5 * 2 ** retryIndex, 8) * 1000;
   66  	return exponentialDelay * (1 - Math.random() * 0.25);

  411  async function executeToolCalls(
  412  	currentContext: AgentContext,
  413  	assistantMessage: AssistantMessage,
  414  	config: AgentLoopConfig,
  415  	signal: AbortSignal | undefined,
  416  	emit: AgentEventSink,
  417  ): Promise<ExecutedToolCallBatch> {
  418  	const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
  419  	const hasSequentialToolCall = toolCalls.some(
  420  		(tc) => currentContext.tools?.find((t) => t.name === tc.name)?.executionMode === "sequential",
  421  	);
  422  	if (config.toolExecution === "sequential" || hasSequentialToolCall) {
  423  		return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit);
  424  	}
  425  	return executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, signal, emit);
  426  }
  427  
  428  type ExecutedToolCallBatch = {
  429  	messages: ToolResultMessage[];
  430  	terminate: boolean;
  431  };
  432  
  433  async function executeToolCallsSequential(
  434  	currentContext: AgentContext,
  435  	assistantMessage: AssistantMessage,
      … 107 lines omitted; exact range 411–553 …
  543  	const messages: ToolResultMessage[] = [];
  544  	for (const finalized of orderedFinalizedCalls) {
  545  		const toolResultMessage = createToolResultMessage(finalized);
  546  		await emitToolResultMessage(toolResultMessage, emit);
  547  		messages.push(toolResultMessage);
  548  	}
  549  
  550  	return {
  551  		messages,
  552  		terminate: shouldTerminateToolBatch(orderedFinalizedCalls),
  553  	};

   33  const replaceEditSchema = Type.Object(
   34  	{
   35  		oldText: Type.String({
   36  			description:
   37  				"Exact text for one targeted replacement. It must be unique in the original file and must not overlap with any other edits[].oldText in the same call.",
   38  		}),
   39  		newText: Type.String({ description: "Replacement text for this targeted edit." }),
   40  	},
   41  	{},
   42  );
   43  
   44  const editSchema = Type.Object(
   45  	{
   46  		path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
   47  		edits: Type.Array(replaceEditSchema, {
   48  			description:
   49  				"One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.",
   50  		}),
   51  	},
   52  	{},
   53  );

    1  /**
    2   * Shared truncation utilities for tool outputs.
    3   *
    4   * Truncation is based on two independent limits - whichever is hit first wins:
    5   * - Line limit (default: 2000 lines)
    6   * - Byte limit (default: 50KB)
    7   *
    8   * Never returns partial lines (except bash tail truncation edge case).
    9   */
   10  
   11  export const DEFAULT_MAX_LINES = 2000;
   12  export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB

  190  function getLastAssistantUsageInfo(messages: AgentMessage[]): { usage: Usage; index: number } | undefined {
  191  	for (let i = messages.length - 1; i >= 0; i--) {
  192  		const usage = getAssistantUsage(messages[i]);
  193  		if (usage) return { usage, index: i };
  194  	}
  195  	return undefined;
  196  }
  197  
  198  /**
  199   * Estimate context tokens from messages, using the last assistant usage when available.
  200   * If there are messages after the last usage, estimate their tokens with estimateTokens.
  201   */
  202  export function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate {
  203  	const usageInfo = getLastAssistantUsageInfo(messages);
  204  
  205  	if (!usageInfo) {
  206  		let estimated = 0;
  207  		for (const message of messages) {
  208  			estimated += estimateTokens(message);
  209  		}
  210  		return {
  211  			tokens: estimated,
  212  			usageTokens: 0,
  213  			trailingTokens: estimated,
  214  			lastUsageIndex: null,
      … 12 lines omitted; exact range 190–237 …
  227  		trailingTokens,
  228  		lastUsageIndex: usageInfo.index,
  229  	};
  230  }
  231  
  232  /**
  233   * Check if compaction should trigger based on context usage.
  234   */
  235  export function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean {
  236  	if (!settings.enabled) return false;
  237  	return contextTokens > contextWindow - settings.reserveTokens;

  345  /**
  346   * Find valid cut points: indices of context-visible user-like or assistant messages.
  347   * Never cut at tool results (they must follow their tool call).
  348   * When we cut at an assistant message with tool calls, its tool results follow it
  349   * and will be kept.
  350   */
  351  function findValidCutPoints(entries: SessionEntry[], startIndex: number, endIndex: number): number[] {
  352  	const cutPoints: number[] = [];
  353  	for (let i = startIndex; i < endIndex; i++) {
  354  		const entry = entries[i];
  355  		if (entry.type === "compaction") {
  356  			continue;
  357  		}
  358  		if (sessionEntryToContextMessages(entry).some(isCutPointMessage)) {
  359  			cutPoints.push(i);
  360  		}
  361  	}
  362  	return cutPoints;
  363  }
  364  
  365  /**
  366   * Find the context-visible user-role message that starts the turn containing the given entry index.
  367   * Returns -1 if no turn start found before the index.
  368   */
  369  export function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number {
      … 80 lines omitted; exact range 345–460 …
  450  
  451  	// Determine if this is a split turn
  452  	const cutEntry = entries[cutIndex];
  453  	const startsTurn = isTurnStartEntry(cutEntry);
  454  	const turnStartIndex = startsTurn ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
  455  
  456  	return {
  457  		firstKeptEntryIndex: cutIndex,
  458  		turnStartIndex,
  459  		isSplitTurn: !startsTurn && turnStartIndex !== -1,
  460  	};

 1783  	async compact(customInstructions?: string): Promise<CompactionResult> {
 1784  		this._disconnectFromAgent();
 1785  		await this.abort();
 1786  		this._compactionAbortController = new AbortController();
 1787  		this._emit({ type: "compaction_start", reason: "manual" });
 1788  
 1789  		try {
 1790  			if (!this.model) {
 1791  				throw new Error(formatNoModelSelectedMessage());
 1792  			}
 1793  
 1794  			const { apiKey, headers, env } = await this._getSummarizationRequestAuth(this.model);
 1795  
 1796  			const pathEntries = this.sessionManager.getBranch();
 1797  			const settings = this.settingsManager.getCompactionSettings();
 1798  
 1799  			const preparation = prepareCompaction(pathEntries, settings);
 1800  			if (!preparation) {
 1801  				// Check why we can't compact
 1802  				const lastEntry = pathEntries[pathEntries.length - 1];
 1803  				if (lastEntry?.type === "compaction") {
 1804  					throw new Error("Already compacted");
 1805  				}
 1806  				throw new Error("Nothing to compact (session too small)");
 1807  			}
      … 106 lines omitted; exact range 1783–1924 …
 1914  				reason: "manual",
 1915  				result: undefined,
 1916  				aborted,
 1917  				willRetry: false,
 1918  				errorMessage: aborted ? undefined : `Compaction failed: ${message}`,
 1919  			});
 1920  			throw error;
 1921  		} finally {
 1922  			this._compactionAbortController = undefined;
 1923  			this._reconnectToAgent();
 1924  		}

   82  export function createLocalBashOperations(options?: { shellPath?: string }): BashOperations {
   83  	return {
   84  		exec: async (command, cwd, { onData, signal, timeout, env }) => {
   85  			const timeoutMs = resolveTimeoutMs(timeout);
   86  			if (signal?.aborted) {
   87  				throw new Error("aborted");
   88  			}
   89  			const shellConfig = getShellConfig(options?.shellPath);
   90  			try {
   91  				await fsAccess(cwd, constants.F_OK);
   92  			} catch {
   93  				throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
   94  			}
   95  
   96  			const commandFromStdin = shellConfig.commandTransport === "stdin";
   97  			const child = spawn(shellConfig.shell, commandFromStdin ? shellConfig.args : [...shellConfig.args, command], {
   98  				cwd,
   99  				detached: process.platform !== "win32",
  100  				env: env ?? getShellEnv(),
  101  				stdio: [commandFromStdin ? "pipe" : "ignore", "pipe", "pipe"],
  102  				windowsHide: true,
  103  			});
  104  			if (commandFromStdin) {
  105  				child.stdin?.on("error", () => {});
  106  				child.stdin?.end(command);
      … 31 lines omitted; exact range 82–148 …
  138  					throw new Error(`timeout:${timeout}`);
  139  				}
  140  				return { exitCode };
  141  			} finally {
  142  				if (child.pid) untrackDetachedChildPid(child.pid);
  143  				if (timeoutHandle) clearTimeout(timeoutHandle);
  144  				if (signal) signal.removeEventListener("abort", onAbort);
  145  			}
  146  		},
  147  	};
  148  }

   24  function formatProjectTrustPrompt(cwd: string): string {
   25  	return `Trust project folder?\n${cwd}\n\nThis allows pi to load ${CONFIG_DIR_NAME} settings and resources, install missing project packages, and execute project extensions.`;
   26  }
   27  
   28  async function selectProjectTrustOption(
   29  	cwd: string,
   30  	ctx: ProjectTrustContext,
   31  ): Promise<ProjectTrustOption | undefined> {
   32  	const options = getProjectTrustOptions(cwd, { includeSessionOnly: true });
   33  	const selected = await ctx.ui.select(
   34  		formatProjectTrustPrompt(cwd),
   35  		options.map((option) => option.label),
   36  	);
   37  	return options.find((option) => option.label === selected);
   38  }
   39  
   40  function saveProjectTrustPromptResult(trustStore: ProjectTrustStore, result: ProjectTrustOption): void {
   41  	if (result.updates.length > 0) {
   42  		trustStore.setMany(result.updates);
   43  	}
   44  }
   45  
   46  export async function resolveProjectTrusted(options: ResolveProjectTrustedOptions): Promise<boolean> {
   47  	if (options.trustOverride !== undefined) {
   48  		return options.trustOverride;
      … 36 lines omitted; exact range 24–95 …
   85  
   86  	if (!options.projectTrustContext.hasUI) {
   87  		return false;
   88  	}
   89  
   90  	const selected = await selectProjectTrustOption(options.cwd, options.projectTrustContext);
   91  	if (selected !== undefined) {
   92  		saveProjectTrustPromptResult(options.trustStore, selected);
   93  		return selected.trusted;
   94  	}
   95  	return false;

   21  const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf-8", mode: 0o600 } as const;
   22  
   23  export interface AuthStorageBackend {
   24  	withLock<T>(fn: (current: string | undefined) => LockResult<T>): T;
   25  	withLockAsync<T>(fn: (current: string | undefined) => Promise<LockResult<T>>): Promise<T>;
   26  }
   27  
   28  export class FileAuthStorageBackend implements AuthStorageBackend {
   29  	private authPath: string;
   30  
   31  	constructor(authPath: string = join(getAgentDir(), "auth.json")) {
   32  		this.authPath = normalizePath(authPath);
   33  	}
   34  
   35  	private ensureParentDir(): void {
   36  		const dir = dirname(this.authPath);
   37  		if (!existsSync(dir)) {
   38  			mkdirSync(dir, { recursive: true, mode: 0o700 });
   39  		}
   40  	}
   41  
   42  	private ensureFileExists(): void {
   43  		if (!existsSync(this.authPath)) {
   44  			writeFileSync(this.authPath, "{}", AUTH_FILE_WRITE_OPTIONS);
   45  			chmodSync(this.authPath, 0o600);
      … 89 lines omitted; exact range 21–145 …
  135  			return result;
  136  		} finally {
  137  			if (release) {
  138  				try {
  139  					await release();
  140  				} catch {
  141  					// Ignore unlock errors when lock is compromised.
  142  				}
  143  			}
  144  		}
  145  	}

    1  /**
    2   * Sandbox Extension - OS-level sandboxing for bash commands
    3   *
    4   * Uses @anthropic-ai/sandbox-runtime to enforce filesystem and network
    5   * restrictions on bash commands at the OS level (sandbox-exec on macOS,
    6   * bubblewrap on Linux).
    7   *
    8   * Note: this example intentionally overrides the built-in `bash` tool to show
    9   * how built-in tools can be replaced. Alternatively, you could sandbox `bash`
   10   * via `tool_call` input mutation without replacing the tool.
   11   *
   12   * Config files (merged, project takes precedence):
   13   * - ~/.pi/agent/extensions/sandbox.json (global)
   14   * - <cwd>/.pi/sandbox.json (project-local)
   15   *
   16   * Example .pi/sandbox.json:
   17   * ```json
   18   * {
   19   *   "enabled": true,
   20   *   "network": {
   21   *     "allowedDomains": ["github.com", "*.github.com"],
   22   *     "deniedDomains": []
   23   *   },
   24   *   "filesystem": {
   25   *     "denyRead": ["~/.ssh", "~/.aws"],
      … 11 lines omitted; exact range 1–47 …
   37   * Setup:
   38   * 1. Copy sandbox/ directory to ~/.pi/agent/extensions/
   39   * 2. Run `npm install` in ~/.pi/agent/extensions/sandbox/
   40   *
   41   * Linux also requires: bubblewrap, socat, ripgrep
   42   */
   43  
   44  import { spawn } from "node:child_process";
   45  import { existsSync, readFileSync } from "node:fs";
   46  import { join } from "node:path";
   47  import { SandboxManager, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";

   28  export function buildSystemPrompt(options: BuildSystemPromptOptions): string {
   29  	const {
   30  		customPrompt,
   31  		selectedTools,
   32  		toolSnippets,
   33  		promptGuidelines,
   34  		appendSystemPrompt,
   35  		cwd,
   36  		contextFiles: providedContextFiles,
   37  		skills: providedSkills,
   38  	} = options;
   39  	const promptCwd = cwd.replace(/\\/g, "/");
   40  
   41  	const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : "";
   42  
   43  	const contextFiles = providedContextFiles ?? [];
   44  	const skills = providedSkills ?? [];
   45  
   46  	if (customPrompt) {
   47  		let prompt = customPrompt;
   48  
   49  		if (appendSection) {
   50  			prompt += appendSection;
   51  		}
   52  
      … 8 lines omitted; exact range 28–71 …
   61  		}
   62  
   63  		// Append skills section (only if read tool is available)
   64  		const customPromptHasRead = !selectedTools || selectedTools.includes("read");
   65  		if (customPromptHasRead && skills.length > 0) {
   66  			prompt += formatSkillsForPrompt(skills);
   67  		}
   68  
   69  		prompt += `\nCurrent working directory: ${promptCwd}`;
   70  
   71  		return prompt;

  118  	const errors: string[] = [];
  119  
  120  	if (!description || description.trim() === "") {
  121  		errors.push("description is required");
  122  	} else if (description.length > MAX_DESCRIPTION_LENGTH) {
  123  		errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
  124  	}
  125  
  126  	return errors;
  127  }
  128  
  129  export interface LoadSkillsFromDirOptions {
  130  	/** Directory to scan for skills */
  131  	dir: string;
  132  	/** Source identifier for these skills */
  133  	source: string;
  134  }
  135  
  136  function createSkillSourceInfo(filePath: string, baseDir: string, source: string): SourceInfo {
  137  	switch (source) {
  138  		case "user":
  139  			return createSyntheticSourceInfo(filePath, {
  140  				source: "local",
  141  				scope: "user",
  142  				baseDir,
      … 35 lines omitted; exact range 118–188 …
  178  	rootDir?: string,
  179  ): LoadSkillsResult {
  180  	const skills: Skill[] = [];
  181  	const diagnostics: ResourceDiagnostic[] = [];
  182  
  183  	if (!existsSync(dir)) {
  184  		return { skills, diagnostics };
  185  	}
  186  
  187  	const root = rootDir ?? dir;
  188  	const ig = ignoreMatcher ?? ignore();

   66  	"@mariozechner/pi-tui": _bundledPiTui,
   67  	"@mariozechner/pi-ai": _bundledPiAiCompat,
   68  	"@mariozechner/pi-ai/compat": _bundledPiAiCompat,
   69  	"@mariozechner/pi-ai/oauth": _bundledPiAiOauth,
   70  	"@mariozechner/pi-ai/providers/all": _bundledPiAiProviders,
   71  	"@mariozechner/pi-coding-agent": _bundledPiCodingAgent,
   72  };
   73  
   74  const require = createRequire(import.meta.url);
   75  
   76  /**
   77   * Get aliases for jiti (used in Node.js/development mode).
   78   * In Bun binary mode, virtualModules is used instead.
   79   */
   80  let _aliases: Record<string, string> | null = null;
   81  
   82  function getAliases(): Record<string, string> {
   83  	if (_aliases) return _aliases;
   84  
   85  	const __dirname = path.dirname(fileURLToPath(import.meta.url));
   86  	const packageIndex = path.resolve(__dirname, "../..", "index.js");
   87  
   88  	const typeboxEntry = require.resolve("typebox");
   89  	const typeboxCompileEntry = require.resolve("typebox/compile");
   90  	const typeboxValueEntry = require.resolve("typebox/value");
      … 23 lines omitted; exact range 66–124 …
  114  	_aliases = {
  115  		"@earendil-works/pi-coding-agent": piCodingAgentEntry,
  116  		"@earendil-works/pi-agent-core": piAgentCoreEntry,
  117  		"@earendil-works/pi-tui": piTuiEntry,
  118  		"@earendil-works/pi-ai/providers/all": piAiProvidersEntry,
  119  		"@earendil-works/pi-ai/compat": piAiCompatEntry,
  120  		"@earendil-works/pi-ai/oauth": piAiOauthEntry,
  121  		"@earendil-works/pi-ai": piAiCompatEntry,
  122  		"@mariozechner/pi-coding-agent": piCodingAgentEntry,
  123  		"@mariozechner/pi-agent-core": piAgentCoreEntry,
  124  		"@mariozechner/pi-tui": piTuiEntry,

 2454  	private _refreshToolRegistry(options?: { activeToolNames?: string[]; includeAllExtensionTools?: boolean }): void {
 2455  		const previousRegistryNames = new Set(this._toolRegistry.keys());
 2456  		const previousActiveToolNames = this.getActiveToolNames();
 2457  		const allowedToolNames = this._allowedToolNames;
 2458  		const excludedToolNames = this._excludedToolNames;
 2459  		const isAllowedTool = (name: string): boolean =>
 2460  			(!allowedToolNames || allowedToolNames.has(name)) && !excludedToolNames?.has(name);
 2461  
 2462  		const registeredTools = this._extensionRunner.getAllRegisteredTools();
 2463  		const allCustomTools = [
 2464  			...registeredTools,
 2465  			...this._customTools.map((definition) => ({
 2466  				definition,
 2467  				sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, { source: "sdk" }),
 2468  			})),
 2469  		].filter((tool) => isAllowedTool(tool.definition.name));
 2470  		const definitionRegistry = new Map<string, ToolDefinitionEntry>(
 2471  			Array.from(this._baseToolDefinitions.entries())
 2472  				.filter(([name]) => isAllowedTool(name))
 2473  				.map(([name, definition]) => [
 2474  					name,
 2475  					{
 2476  						definition,
 2477  						sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
 2478  					},
      … 55 lines omitted; exact range 2454–2544 …
 2534  				nextActiveToolNames.push(tool.name);
 2535  			}
 2536  		} else if (!options?.activeToolNames) {
 2537  			for (const toolName of this._toolRegistry.keys()) {
 2538  				if (!previousRegistryNames.has(toolName)) {
 2539  					nextActiveToolNames.push(toolName);
 2540  				}
 2541  			}
 2542  		}
 2543  
 2544  		this.setActiveToolsByName([...new Set(nextActiveToolNames)]);

    1  /**
    2   * Subagent Tool - Delegate tasks to specialized agents
    3   *
    4   * Spawns a separate `pi` process for each subagent invocation,
    5   * giving it an isolated context window.
    6   *
    7   * Supports three modes:
    8   *   - Single: { agent: "name", task: "..." }
    9   *   - Parallel: { tasks: [{ agent: "name", task: "..." }, ...] }
   10   *   - Chain: { chain: [{ agent: "name", task: "... {previous} ..." }, ...] }
   11   *
   12   * Uses JSON mode to capture structured output from subagents.
   13   */
   14  
   15  import { spawn } from "node:child_process";
   16  import * as fs from "node:fs";
   17  import * as os from "node:os";
   18  import * as path from "node:path";
   19  import type { AgentToolResult } from "@earendil-works/pi-agent-core";
   20  import type { Message } from "@earendil-works/pi-ai";
   21  import { StringEnum } from "@earendil-works/pi-ai";
   22  import {
   23  	CONFIG_DIR_NAME,
   24  	type ExtensionAPI,
   25  	getAgentDir,
   26  	getMarkdownTheme,
   27  	withFileMutationQueue,
   28  } from "@earendil-works/pi-coding-agent";
   29  import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
   30  import { Type } from "typebox";
   31  import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.ts";
   32  
   33  const MAX_PARALLEL_TASKS = 8;
   34  const MAX_CONCURRENCY = 4;
   35  const COLLAPSED_ITEM_COUNT = 10;
   36  const PER_TASK_OUTPUT_CAP = 50 * 1024;

   30  export const CURRENT_SESSION_VERSION = 3;
   31  
   32  export interface SessionHeader {
   33  	type: "session";
   34  	version?: number; // v1 sessions don't have this
   35  	id: string;
   36  	timestamp: string;
   37  	cwd: string;
   38  	parentSession?: string;
   39  }
   40  
   41  export interface NewSessionOptions {
   42  	id?: string;
   43  	parentSession?: string;
   44  }
   45  
   46  export interface SessionEntryBase {
   47  	type: string;
   48  	id: string;
   49  	parentId: string | null;
   50  	timestamp: string;
   51  }
   52  
   53  export interface SessionMessageEntry extends SessionEntryBase {
   54  	type: "message";
      … 88 lines omitted; exact range 30–153 …
  143  /** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
  144  export type SessionEntry =
  145  	| SessionMessageEntry
  146  	| ThinkingLevelChangeEntry
  147  	| ModelChangeEntry
  148  	| CompactionEntry
  149  	| BranchSummaryEntry
  150  	| CustomEntry
  151  	| CustomMessageEntry
  152  	| LabelEntry
  153  	| SessionInfoEntry;

  138  	/** Thinking level for the next provider request. */
  139  	thinkingLevel?: ThinkingLevel;
  140  }
  141  
  142  export interface PrepareNextTurnContext extends ShouldStopAfterTurnContext {}
  143  
  144  export interface AgentLoopConfig extends SimpleStreamOptions {
  145  	model: Model<any>;
  146  
  147  	/**
  148  	 * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
  149  	 *
  150  	 * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage
  151  	 * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,
  152  	 * status messages) should be filtered out.
  153  	 *
  154  	 * Contract: must not throw or reject. Return a safe fallback value instead.
  155  	 * Throwing interrupts the low-level agent loop without producing a normal event sequence.
  156  	 *
  157  	 * @example
  158  	 * ```typescript
  159  	 * convertToLlm: (messages) => messages.flatMap(m => {
  160  	 *   if (m.role === "custom") {
  161  	 *     // Convert custom message to user message
  162  	 *     return [{ role: "user", content: m.content, timestamp: m.timestamp }];
      … 47 lines omitted; exact range 138–220 …
  210  	 * If it returns true, the loop emits `agent_end` and exits before polling steering or follow-up queues,
  211  	 * without starting another LLM call. The current assistant response and any tool executions finish normally.
  212  	 *
  213  	 * Use this to request a graceful stop after the current turn, e.g. before context gets too full.
  214  	 *
  215  	 * Contract: must not throw or reject. Throwing interrupts the low-level agent loop without producing a normal event sequence.
  216  	 */
  217  	shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;
  218  
  219  	/**
  220  	 * Called after `turn_end` and before the loop decides whether another provider request should start.

   40  	return { provider, model };
   41  }
   42  
   43  function toTranscriptEvents(messages: AgentSession["messages"]): TranscriptEvent[] {
   44  	const events: TranscriptEvent[] = [];
   45  	for (const message of messages) {
   46  		if (message.role === "user") {
   47  			events.push({ type: "message", role: "user", content: contentText(message.content) });
   48  		} else if (message.role === "assistant") {
   49  			const text = contentText(message.content);
   50  			if (text) events.push({ type: "message", role: "assistant", content: text });
   51  			for (const part of message.content) {
   52  				if (part.type === "toolCall") {
   53  					events.push({
   54  						type: "tool_call",
   55  						id: part.id,
   56  						name: part.name,
   57  						arguments: normalizeRecord(part.arguments),
   58  					});
   59  				}
   60  			}
   61  		} else if (message.role === "toolResult") {
   62  			const text = contentText(message.content);
   63  			events.push({
   64  				type: "tool_result",
      … 95 lines omitted; exact range 40–170 …
  160  						outputTokens: stats.tokens.output,
  161  						totalTokens: stats.tokens.total,
  162  						toolCalls: stats.toolCalls,
  163  					},
  164  				},
  165  			};
  166  		} finally {
  167  			signal?.removeEventListener("abort", abort);
  168  		}
  169  	} catch (error) {
  170  		outcome = { success: false, error };