@ryan_nookpi/pi-extension-subagent 0.1.0

package/claude-sdk-runner.ts

@@ -0,0 +1,223 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: SDK stream payloads and tool bridge results are dynamic runtime data. */
+import { AbortError, query } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentConfig } from "./agents.js";
+import { mapThinkingToClaudeEffort } from "./claude-args.js";
+import { createClaudeSdkStreamAdapter } from "./claude-sdk-stream-adapter.js";
+import { createSidecarWriter } from "./claude-sidecar-writer.js";
+import { getFinalOutput } from "./runner.js";
+import type { OnUpdateCallback, SingleResult, SubagentDetails } from "./types.js";
+import { mapPiToolsToClaude, validateClaudeRuntimeModel } from "./utils/agent-utils.js";
+
+function appendStderrDiagnostic(stderr: string, message: string): string {
+	const line = `[runner] ${message}`;
+	return stderr ? `${stderr.trimEnd()}\n${line}\n` : `${line}\n`;
+}
+
+function extractToolNamesFromPrecedingAssistant(messages: SingleResult["messages"]): string[] {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index];
+		if (message.role !== "assistant") continue;
+		const names: string[] = [];
+		for (const part of message.content as any[]) {
+			if (part.type === "toolCall" && typeof part.name === "string") names.push(part.name);
+		}
+		return names;
+	}
+	return [];
+}
+
+function normalizeTaskForSubagentPrompt(task: string): string {
+	if (task.startsWith("/")) return ` \\${task}`;
+	return task;
+}
+
+function resolveClaudeSdkBuiltInTools(requestedTools?: string[]): string[] | undefined {
+	if (!requestedTools || requestedTools.length === 0) return undefined;
+	return mapPiToolsToClaude(requestedTools);
+}
+
+export async function runClaudeAgentViaSdk(
+	defaultCwd: string,
+	agent: AgentConfig,
+	task: string,
+	step: number | undefined,
+	signal: AbortSignal | undefined,
+	onUpdate: OnUpdateCallback | undefined,
+	makeDetails: (results: SingleResult[]) => SubagentDetails,
+	resumeSessionId?: string,
+	sidecarSessionFile?: string,
+): Promise<SingleResult> {
+	try {
+		validateClaudeRuntimeModel(agent.model);
+	} catch (error: any) {
+		return {
+			agent: agent.name,
+			agentSource: agent.source,
+			task,
+			exitCode: 1,
+			messages: [],
+			stderr: error.message,
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			runtime: "claude",
+			step,
+		};
+	}
+
+	const adapter = createClaudeSdkStreamAdapter();
+	const sidecar = sidecarSessionFile ? createSidecarWriter(sidecarSessionFile) : null;
+	const abortController = new AbortController();
+	let stderrBuf = "";
+	let completionMarkerWritten = false;
+	let sidecarInitialUserWritten = false;
+	let externalAbortRequested = false;
+	let sdkFailed = false;
+
+	let enabledTools: string[] | undefined;
+	try {
+		enabledTools = resolveClaudeSdkBuiltInTools(agent.tools);
+	} catch (error: any) {
+		return {
+			agent: agent.name,
+			agentSource: agent.source,
+			task,
+			exitCode: 1,
+			messages: [],
+			stderr: error.message,
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			runtime: "claude",
+			step,
+		};
+	}
+
+	const model = agent.model?.replace(/^anthropic\//, "");
+	const effort = agent.thinking ? mapThinkingToClaudeEffort(agent.thinking) : undefined;
+
+	const emitUpdate = () => {
+		if (!onUpdate) return;
+		const state = adapter.getState();
+		const text = state.liveText ?? getFinalOutput(state.messages) ?? "(running...)";
+		const partial = adapter.toSingleResult(agent.name, agent.source, task, 0, step, stderrBuf);
+		partial.liveText = state.liveText;
+		partial.liveThinking = state.liveThinking;
+		partial.liveToolCalls = state.liveToolCalls;
+		partial.thoughtText = state.thoughtText;
+		onUpdate({
+			content: [{ type: "text", text }],
+			details: makeDetails([partial]),
+		});
+	};
+
+	const writeCompletionMarkerOnce = (exitCode: number, stopReason?: string) => {
+		if (!sidecar || completionMarkerWritten) return;
+		completionMarkerWritten = true;
+		sidecar.writeDone({ exitCode, stopReason, runtime: "claude" });
+	};
+
+	const forwardAbort = () => {
+		externalAbortRequested = true;
+		abortController.abort();
+	};
+
+	if (signal?.aborted) {
+		forwardAbort();
+		writeCompletionMarkerOnce(1, "aborted");
+		throw new Error("Subagent was aborted");
+	}
+	signal?.addEventListener("abort", forwardAbort, { once: true });
+
+	let sdkQuery: ReturnType<typeof query>;
+	try {
+		sdkQuery = query({
+			prompt: normalizeTaskForSubagentPrompt(task),
+			options: {
+				abortController,
+				cwd: defaultCwd,
+				model,
+				effort,
+				systemPrompt: agent.systemPrompt.trim() || undefined,
+				permissionMode: "bypassPermissions",
+				allowDangerouslySkipPermissions: true,
+				settingSources: [],
+				includePartialMessages: true,
+				persistSession: true,
+				...(enabledTools ? { tools: enabledTools, allowedTools: enabledTools } : {}),
+				resume: resumeSessionId,
+				stderr: (data) => {
+					stderrBuf += data;
+				},
+			},
+		});
+	} catch (error) {
+		if (externalAbortRequested) {
+			writeCompletionMarkerOnce(1, "aborted");
+			throw new Error("Subagent was aborted");
+		}
+		sdkFailed = true;
+		stderrBuf = appendStderrDiagnostic(
+			stderrBuf,
+			`claude-sdk error: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		const result = adapter.toSingleResult(agent.name, agent.source, task, 1, step, stderrBuf);
+		result.sessionFile = sidecarSessionFile;
+		result.claudeProjectDir = defaultCwd;
+		return result;
+	}
+
+	try {
+		for await (const message of sdkQuery) {
+			if (sidecar && !sidecarInitialUserWritten) {
+				sidecarInitialUserWritten = true;
+				sidecar.writeUserMessage(task);
+			}
+
+			const state = adapter.getState();
+			const messageCountBefore = state.messages.length;
+			const isResult = adapter.processMessage(message);
+			emitUpdate();
+
+			if (sidecar && state.messages.length > messageCountBefore) {
+				for (let index = messageCountBefore; index < state.messages.length; index++) {
+					const addedMessage = state.messages[index];
+					if (addedMessage.role === "assistant") {
+						sidecar.writeAssistantTurn(state);
+					} else if (addedMessage.role === "user") {
+						const toolNames = extractToolNamesFromPrecedingAssistant(state.messages);
+						const textParts = (addedMessage.content as any[])
+							.filter((part: any) => part.type === "text" && part.text)
+							.map((part: any) => part.text);
+						const content = textParts.join("\n") || "(no output)";
+						sidecar.writeToolResult(toolNames[0] ?? "tool", content);
+					}
+				}
+			}
+
+			if (isResult) {
+				if (sidecar) sidecar.writeFinalAssistant(state);
+				writeCompletionMarkerOnce(state.isError ? 1 : 0, state.stopReason);
+			}
+		}
+	} catch (error) {
+		if (!externalAbortRequested && (!(error instanceof AbortError) || !abortController.signal.aborted)) {
+			sdkFailed = true;
+			stderrBuf = appendStderrDiagnostic(
+				stderrBuf,
+				`claude-sdk error: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	} finally {
+		sdkQuery.close();
+	}
+
+	if (externalAbortRequested) {
+		writeCompletionMarkerOnce(1, "aborted");
+		throw new Error("Subagent was aborted");
+	}
+
+	const state = adapter.getState();
+	const finalExitCode = sdkFailed || state.isError ? 1 : 0;
+	writeCompletionMarkerOnce(finalExitCode, state.stopReason);
+	const result = adapter.toSingleResult(agent.name, agent.source, task, finalExitCode, step, stderrBuf);
+	result.sessionFile = sidecarSessionFile;
+	result.claudeProjectDir = defaultCwd;
+	return result;
+}

package/claude-sdk-stream-adapter.ts

@@ -0,0 +1,49 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: SDK messages are intentionally forwarded into the shared Claude event parser. */
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import {
+	type ClaudeStreamState,
+	createStreamState,
+	processClaudeEvent,
+	stateToSingleResult,
+} from "./claude-stream-parser.js";
+import type { SingleResult } from "./types.js";
+
+export interface ClaudeSdkStreamAdapter {
+	processMessage(message: SDKMessage): boolean;
+	getState(): ClaudeStreamState;
+	toSingleResult(
+		agent: string,
+		agentSource: "user" | "project" | "unknown",
+		task: string,
+		exitCode: number,
+		step: number | undefined,
+		stderr: string,
+	): SingleResult;
+}
+
+class ClaudeSdkStreamAdapterImpl implements ClaudeSdkStreamAdapter {
+	private readonly state = createStreamState();
+
+	processMessage(message: SDKMessage): boolean {
+		return processClaudeEvent(this.state, message as any);
+	}
+
+	getState(): ClaudeStreamState {
+		return this.state;
+	}
+
+	toSingleResult(
+		agent: string,
+		agentSource: "user" | "project" | "unknown",
+		task: string,
+		exitCode: number,
+		step: number | undefined,
+		stderr: string,
+	): SingleResult {
+		return stateToSingleResult(this.state, agent, agentSource, task, exitCode, step, stderr);
+	}
+}
+
+export function createClaudeSdkStreamAdapter(): ClaudeSdkStreamAdapter {
+	return new ClaudeSdkStreamAdapterImpl();
+}

package/claude-sidecar-writer.ts

@@ -0,0 +1,107 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: sidecar JSONL entries use dynamic shapes matching existing session format. */
+import * as fs from "node:fs";
+import type { ClaudeStreamState } from "./claude-stream-parser.js";
+
+export interface SidecarWriter {
+	writeUserMessage(task: string): void;
+	writeAssistantTurn(state: ClaudeStreamState): void;
+	writeToolResult(toolName: string, content: string): void;
+	writeFinalAssistant(state: ClaudeStreamState): void;
+	writeDone(meta: { exitCode: number; stopReason?: string; runtime?: string }): void;
+	readonly filePath: string;
+}
+
+function makeEnvelope(role: string, content: any, extra?: Record<string, any>): string {
+	const entry: any = {
+		type: "message",
+		timestamp: Date.now(),
+		message: {
+			role,
+			content,
+			timestamp: Date.now(),
+			...extra,
+		},
+	};
+	return JSON.stringify(entry);
+}
+
+function buildAssistantContent(state: ClaudeStreamState): any[] {
+	if (state.messages.length === 0) return [];
+
+	const lastAssistant = [...state.messages].reverse().find((m) => m.role === "assistant");
+	if (!lastAssistant) return [];
+
+	const parts: any[] = [];
+	for (const part of lastAssistant.content as any[]) {
+		if (part.type === "text" && part.text) {
+			parts.push({ type: "text", text: part.text });
+		} else if (part.type === "thinking" && (part as any).thinking) {
+			const thinking = (part as any).thinking as string;
+			const preview = thinking.length > 200 ? `${thinking.slice(0, 200)}...` : thinking;
+			parts.push({ type: "thinking", thinking: preview });
+		} else if (part.type === "toolCall") {
+			parts.push({
+				type: "toolCall",
+				name: (part as any).name ?? "tool",
+				arguments: (part as any).arguments ?? {},
+			});
+		}
+	}
+	return parts;
+}
+
+export function createSidecarWriter(filePath: string): SidecarWriter {
+	let lastAssistantTurnIndex = -1;
+
+	function append(line: string): void {
+		fs.appendFileSync(filePath, `${line}\n`, "utf-8");
+	}
+
+	return {
+		get filePath() {
+			return filePath;
+		},
+
+		writeUserMessage(task: string): void {
+			append(makeEnvelope("user", [{ type: "text", text: task }]));
+		},
+
+		writeAssistantTurn(state: ClaudeStreamState): void {
+			const turnIndex = state.messages.filter((m) => m.role === "assistant").length;
+			if (turnIndex <= lastAssistantTurnIndex) return;
+
+			const content = buildAssistantContent(state);
+			if (content.length === 0) return;
+
+			lastAssistantTurnIndex = turnIndex;
+			append(makeEnvelope("assistant", content));
+		},
+
+		writeToolResult(toolName: string, content: string): void {
+			append(makeEnvelope("toolResult", [{ type: "text", text: content }], { toolName }));
+		},
+
+		writeFinalAssistant(state: ClaudeStreamState): void {
+			const turnIndex = state.messages.filter((m) => m.role === "assistant").length;
+			if (turnIndex <= lastAssistantTurnIndex) return;
+
+			const content = buildAssistantContent(state);
+			if (content.length === 0) return;
+
+			lastAssistantTurnIndex = turnIndex;
+			append(makeEnvelope("assistant", content));
+		},
+
+		writeDone(meta: { exitCode: number; stopReason?: string; runtime?: string }): void {
+			append(
+				JSON.stringify({
+					type: "subagent_done",
+					timestamp: Date.now(),
+					exitCode: meta.exitCode,
+					stopReason: meta.stopReason,
+					runtime: meta.runtime,
+				}),
+			);
+		},
+	};
+}