import { isAbsolute, resolve } from "node:path"; import type { AssistantMessage, ImageContent, JsonValue, Usage, } from "@earendil-works/pi-ai"; import { type AgentSession, type AgentSessionEvent, type BuildSystemPromptOptions, createAgentSession, createCodemodeExtension, createMcpExtension, createToolSearchExtension, DefaultResourceLoader, defineTool, type ExtensionAPI, type ExtensionToolContext, getAgentDir, ModelRuntime, type SessionEntry, SessionManager, } from "@earendil-works/pi-coding-agent"; import { Type } from "typebox"; import { type Config, discover, effectiveTiers, instructions, selectModel, type TierSettings, } from "./config.ts"; import { childResources } from "./resources.ts"; import { dbg, span } from "./src/debug.ts"; export interface TaskRequest extends Config { prompt: string; images?: ImageContent[]; agent?: string; cwd?: string; sessionId?: string; fork?: boolean; } export interface Inheritance { tools: string[]; availableTools: string[]; extensions: string[]; prompt: Pick< BuildSystemPromptOptions, | "sections" | "customPrompt" | "appendSystemPrompt" | "forceSystemPrompt" | "contextFiles" >; } export interface Progress { phase: string; preview: string; tool?: { name: string; args: string }; } export interface TaskResult { outputMode: "message" | "structured"; outcome: "completed" | "aborted" | "error" | "failed"; output: JsonValue; assistantMessage: AssistantMessage | null; sessionId: string; sessionFile: string | null; durationMs: number; turns: number; usage: Usage; requested: Config; effective: { cwd: string; model: string | null; thinkingLevel: string; tools: string[]; excludedTools?: string[]; extensions: string[]; skills?: string[]; prompts?: string[]; flagNames?: string[]; sections?: string[]; }; diagnostics: string[]; } export function emptyUsage(): Usage { return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, }; } function addUsage(total: Usage, value: Usage): void { const totalFromProvider = total.cost.totalFromProvider; const valueFromProvider = value.cost.totalFromProvider === true; for (const key of [ "input", "output", "cacheRead", "cacheWrite", "totalTokens", ] as const) total[key] += value[key]; for (const key of [ "input", "output", "cacheRead", "cacheWrite", "total", ] as const) total.cost[key] += value.cost[key]; total.cost.totalFromProvider = totalFromProvider === undefined ? valueFromProvider : totalFromProvider && valueFromProvider; if (value.reasoning !== undefined) total.reasoning = (total.reasoning ?? 0) + value.reasoning; if (value.cacheWrite1h !== undefined) total.cacheWrite1h = (total.cacheWrite1h ?? 0) + value.cacheWrite1h; } export function newUsage(entries: SessionEntry[], before: Set): Usage { const total = emptyUsage(); for (const entry of entries) { if (before.has(entry.id)) continue; if (entry.type === "message") { const message = entry.message; if ( (message.role === "assistant" || message.role === "toolResult") && message.usage ) addUsage(total, message.usage); } else if ("usage" in entry && entry.usage) addUsage(total, entry.usage); } return total; } export function json(value: unknown): JsonValue { return JSON.parse(JSON.stringify(value)) as JsonValue; } /** Upper bound on child teardown; a wedged child is disposed forcefully after it. */ const TEARDOWN_TIMEOUT_MS = 5_000; function delay(ms: number): Promise { return new Promise((resolve) => { const timer = setTimeout(resolve, ms); timer.unref(); }); } const OUTPUT_GUIDANCE = "Submit the result with pipi_output, alone as your final action. Do not substitute an ordinary final answer. Submit only after completing the task. Corrections are allowed: the last valid submission wins."; const OUTPUT_SUFFIX = "\n\n" + OUTPUT_GUIDANCE + "\n"; export function outputParameters( schema: Record, ): ReturnType { // A resource boundary preserves caller-local references without rewriting schema or literal data. return Type.Unsafe({ type: "object", properties: { output: { $id: "https://pi.local/pipi/output/", ...schema } }, required: ["output"], additionalProperties: false, }); } export function snapshotPrompt( options: Inheritance["prompt"], ): Inheritance["prompt"] { const force = options.forceSystemPrompt; return structuredClone({ contextFiles: options.contextFiles ?? [], sections: Object.fromEntries( Object.entries(options.sections ?? {}).filter( ([name]) => name !== "pipi_output" && name !== "pipi_library" && name !== "pipi_tiers", ), ), ...(options.customPrompt !== undefined ? { customPrompt: options.customPrompt } : {}), ...(options.appendSystemPrompt !== undefined ? { appendSystemPrompt: options.appendSystemPrompt } : {}), ...(force !== undefined ? { forceSystemPrompt: force.endsWith(OUTPUT_SUFFIX) ? force.slice(0, -OUTPUT_SUFFIX.length) : force, } : {}), }); } const builtins = [ { name: "codemode", factory: createCodemodeExtension(), builtin: true, replaceable: true, }, { name: "tool-search", factory: createToolSearchExtension(), builtin: true, replaceable: true, }, { name: "mcp", factory: createMcpExtension(), builtin: true, replaceable: true, }, ]; async function managerFor( ctx: ExtensionToolContext, request: TaskRequest, cwdOverride: string | undefined, ): Promise { const end = span?.( request.sessionId ? request.fork ? "session.fork" : "session.open" : "session.create", ); try { const parentSession = ctx.sessionManager.getSessionFile(); const directory = ctx.sessionManager.getSessionDir() || undefined; if (!request.sessionId) { if (request.fork) { if (!parentSession) throw new Error("pipi: cannot fork an unpersisted parent session"); return SessionManager.forkFrom( parentSession, cwdOverride ?? ctx.cwd, directory, { parentSession, }, ); } return SessionManager.create( cwdOverride ?? ctx.cwd, directory, parentSession ? { parentSession } : undefined, ); } let file = request.sessionId; if (!isAbsolute(file) && !file.includes("/") && !file.includes("\\")) { const found = SessionManager.findById(cwdOverride ?? ctx.cwd, file, directory) ?? (await SessionManager.listAll(directory, undefined, ctx.signal)).find( (session) => session.id === file, )?.path; if (!found) throw new Error( `pipi: sessionId not found: ${file}; use the returned sessionFile for another workspace`, ); file = found; } return request.fork ? SessionManager.forkFrom( file, cwdOverride ?? ctx.cwd, directory, parentSession ? { parentSession } : undefined, ) : SessionManager.open(file, directory, cwdOverride); } finally { end?.(); } } function copyProviders(ctx: ExtensionToolContext, runtime: ModelRuntime): void { for (const id of ctx.modelRegistry.getRegisteredProviderIds()) { const native = ctx.modelRegistry.getRegisteredNativeProvider(id); if (native) runtime.registerNativeProvider(native); else { const config = ctx.modelRegistry.getRegisteredProviderConfig(id); if (config) runtime.registerProvider(id, config); } } } async function inheritAuthentication( ctx: ExtensionToolContext, runtime: ModelRuntime, signal?: AbortSignal, ): Promise { // Delegate resolution, not credential storage: parent owns OAuth refresh and runtime-key precedence. const models = ctx.modelRegistry.getAll(); for (const id of new Set(models.map((model) => model.provider))) { if (!ctx.modelRegistry.getProviderAuthStatus(id).configured) continue; const provider = runtime.getProvider(id) ?? ctx.modelRegistry.getProvider(id); if (!provider) continue; const model = models.find((value) => value.provider === id); runtime.registerNativeProvider({ ...provider, auth: { ...provider.auth, apiKey: { name: "Parent session authentication", check: async () => ctx.modelRegistry.getProviderAuthStatus(id).configured ? { type: model && ctx.modelRegistry.isUsingOAuth(model) ? ("oauth" as const) : ("api_key" as const), source: "parent session", } : undefined, resolve: async () => ctx.modelRegistry.getProviderAuth(id), }, }, }); } await runtime.refresh({ allowNetwork: false, ...(signal ? { signal } : {}) }); } function applyFlags( loader: DefaultResourceLoader, overrides: Config["flags"], inherited: Map, ): void { const loaded = loader.getExtensions(); const registered = new Map( loaded.extensions.flatMap((extension) => [...extension.flags]), ); for (const [name, value] of inherited) { const flag = registered.get(name); if (flag?.type === "boolean") loaded.runtime.flagValues.set(name, true); else if (flag?.type === "string" && typeof value === "string") loaded.runtime.flagValues.set(name, value); } for (const [name, value] of Object.entries(overrides ?? {})) { const flag = registered.get(name); if (!flag) throw new Error(`pipi: flag --${name} not registered in child`); if (typeof value !== flag.type) throw new Error(`pipi: flag --${name} expects ${flag.type}`); loaded.runtime.flagValues.set(name, value); } } const SESSION_NAME_MAX = 120; // Mirrors dilemma's named children so `pi --resume` shows recognisable entries. export function sessionName(request: TaskRequest, config: Config): string { const kind = request.agent ?? config.tier ?? config.model ?? "task"; const task = request.prompt.replace(/\s+/gu, " ").trim(); return `PiPi · ${kind} · ${task}`.slice(0, SESSION_NAME_MAX); } export async function runTask( ctx: ExtensionToolContext, request: TaskRequest, inherited: Inheritance, tiers: TierSettings, defaultTimeoutMs: number, signal?: AbortSignal, progress?: (value: Progress) => void, activity?: (event: AgentSessionEvent, child: AgentSession) => void, ): Promise { const started = performance.now(); const taskEnd = span?.("task", { hasSchema: !!request.outputSchema, resumed: !!request.sessionId, }); try { const agentDir = getAgentDir(); const requestedCwd = request.cwd === undefined ? undefined : resolve(ctx.cwd, request.cwd); const catalog = await discover(agentDir); const presetEnd = span?.("preset"); const preset = request.agent ? catalog.agents.find((value) => value.name === request.agent) : undefined; if (request.agent && !preset) throw new Error(`pipi: preset unavailable: ${request.agent}`); const { prompt: _prompt, images: _images, agent: _agent, cwd: _cwd, sessionId: _sessionId, fork: _fork, ...overrides } = request; const presetConfig = preset?.config ?? {}; const { model: _presetModel, ...withoutModel } = presetConfig; const config: Config = structuredClone({ ...(request.tier !== undefined && request.model === undefined ? withoutModel : presetConfig), ...overrides, }); for (const kind of ["extensions", "skills", "prompts"] as const) { if (presetConfig[kind] && overrides[kind]) config[kind] = [...presetConfig[kind], ...overrides[kind]]; } const body = await instructions(preset); if (body !== undefined && config.sections?.["pipi_agent"] === undefined) config.sections = { ...config.sections, pipi_agent: body }; presetEnd?.(); const deadline = config.timeoutMs === null ? undefined : (config.timeoutMs ?? defaultTimeoutMs); const timeoutSignal = deadline === undefined ? undefined : AbortSignal.timeout(deadline); const taskSignal = timeoutSignal ? signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal : signal; const schema = config.outputSchema; let effectivePrompt: BuildSystemPromptOptions | undefined; let submitted = false, output: JsonValue = null, reminded = false; let outcome: TaskResult["outcome"] = "completed"; let assistantMessage: AssistantMessage | null = null; let turns = 0, firstModel = true; const diagnostics = [...catalog.diagnostics]; const manager = await managerFor(ctx, request, requestedCwd); if (!request.sessionId || request.fork) manager.appendSessionInfo(sessionName(request, config)); const cwd = manager.getCwd(); const before = new Set(manager.getEntries().map((entry) => entry.id)); let child: | Awaited>["session"] | undefined; let unsubscribe: (() => void) | undefined; let modelEnd: ReturnType> | undefined; const toolSpans = new Map>>(); const abort = () => { void child?.abort(); }; let effective: TaskResult["effective"] = { cwd, model: null, thinkingLevel: "off", tools: [], extensions: [], }; try { taskSignal?.throwIfAborted(); const runtime = await ModelRuntime.create({ authPath: resolve(agentDir, "auth.json"), modelsPath: resolve(agentDir, "models.json"), refreshOnCreate: false, ...(taskSignal ? { signal: taskSignal } : {}), }); copyProviders(ctx, runtime); const loadEnd = span?.("resources"); const { cli, settingsManager, extensions, skills, prompts } = await childResources(ctx, cwd, inherited, config); const controller = (pi: ExtensionAPI) => { if (schema) pi.registerTool( defineTool({ name: "pipi_output", label: "Submit result", description: OUTPUT_GUIDANCE, promptGuidelines: [OUTPUT_GUIDANCE], exposure: "model-only", parameters: outputParameters(schema), async execute(_id, args) { output = json((args as { output: unknown }).output); submitted = true; dbg?.("output.submit", { hasSchema: true }); return { content: [{ type: "text", text: "Result accepted." }], details: {}, terminate: true, }; }, }), ); pi.on("before_agent_start", (event) => { const options = event.systemPromptOptions; effectivePrompt = options; const base = inherited.prompt; if (base.customPrompt !== undefined) options.customPrompt = base.customPrompt; if (base.forceSystemPrompt !== undefined) options.forceSystemPrompt = base.forceSystemPrompt; if ( base.appendSystemPrompt && options.appendSystemPrompt !== base.appendSystemPrompt ) options.appendSystemPrompt += "\n" + base.appendSystemPrompt; Object.assign(options.sections, base.sections); // Submission state and instructions never cross the parent/child boundary. delete options.sections["pipi_output"]; if (config.customPrompt !== undefined) options.customPrompt = config.customPrompt; if (config.appendSystemPrompt) options.appendSystemPrompt += "\n" + config.appendSystemPrompt; Object.assign(options.sections, config.sections); if (config.forceSystemPrompt !== undefined) options.forceSystemPrompt = config.forceSystemPrompt; if (schema) { options.sections["pipi_output"] = OUTPUT_GUIDANCE; if (options.forceSystemPrompt !== undefined) options.forceSystemPrompt += OUTPUT_SUFFIX; } }); pi.on("agent_before_settle", (event) => { outcome = event.outcome; if (event.outcome !== "completed" || !schema || submitted || reminded) return undefined; reminded = true; dbg?.("output.reminder", { hasSchema: true }); return { entries: [ { type: "custom_message", customType: "pipi_output_reminder", content: OUTPUT_GUIDANCE, display: false, }, ], continue: true, }; }); }; const loader = new DefaultResourceLoader({ cwd, agentDir, settingsManager, noExtensions: config.noExtensions ?? cli.noExtensions ?? false, noSkills: config.noSkills ?? cli.noSkills ?? false, noPromptTemplates: config.noPromptTemplates ?? cli.noPromptTemplates ?? false, noContextFiles: config.noContextFiles ?? cli.noContextFiles ?? false, additionalExtensionPaths: extensions, additionalSkillPaths: skills, additionalPromptTemplatePaths: prompts, agentsFilesOverride: (base) => ({ agentsFiles: (config.noContextFiles ?? cli.noContextFiles) ? [] : [ ...new Map( [ ...(inherited.prompt.contextFiles ?? []), ...base.agentsFiles, ].map((file) => [file.path, file]), ).values(), ], }), extensionFactories: [...builtins, controller], ...(cli.noMcp ? { disabledBuiltinExtensions: ["mcp"] } : {}), }); await loader.reload(); loadEnd?.(); for (const error of loader.getExtensions().errors) diagnostics.push(`Extension unavailable: ${error.path}`); for (const issue of [ ...loader.getSkills().diagnostics, ...loader.getPrompts().diagnostics, ]) diagnostics.push( `${issue.message}${issue.path ? ": " + issue.path : ""}`, ); applyFlags(loader, config.flags, cli.unknownFlags); effective.extensions = loader .getExtensions() .extensions.map((extension) => extension.path); const ref = selectModel(config, tiers, ctx.model?.provider); const thinkingLevel = config.thinkingLevel ?? (config.tier ? effectiveTiers(tiers, ctx.model?.provider)[config.tier] .thinkingLevel : undefined); let model = request.sessionId || request.fork ? undefined : ctx.model; if (ref) { const slash = ref.indexOf("/"); if (slash <= 0) throw new Error("pipi: model must be provider/model"); model = ctx.modelRegistry .getAll() .find((candidate) => `${candidate.provider}/${candidate.id}` === ref); if (!model) throw new Error(`pipi: model unavailable: ${ref}`); } taskSignal?.throwIfAborted(); await inheritAuthentication(ctx, runtime, taskSignal); const created = await createAgentSession({ cwd, agentDir, resourceLoader: loader, modelRuntime: runtime, settingsManager, sessionManager: manager, ...(model ? { model } : {}), ...(thinkingLevel !== undefined ? { thinkingLevel: thinkingLevel as NonNullable< ExtensionToolContext["thinkingLevel"] >, } : !request.sessionId && !request.fork && ctx.thinkingLevel ? { thinkingLevel: ctx.thinkingLevel } : {}), // Tool selection is applied to the complete registry before native startup hooks. }); child = created.session; if (created.modelFallbackMessage) diagnostics.push(created.modelFallbackMessage); taskSignal?.addEventListener("abort", abort, { once: true }); const activeChild = child; unsubscribe = child.subscribe((event) => { activity?.(event, activeChild); if (event.type === "agent_start" && taskSignal?.aborted) abort(); if (event.type === "turn_start") { modelEnd = span?.("model.request"); progress?.({ phase: "running", preview: "" }); } if ( event.type === "message_update" && event.assistantMessageEvent.type.endsWith("_delta") && firstModel ) { firstModel = false; dbg?.("model.first", { elapsedMs: performance.now() - started }); } if ( event.type === "message_end" && event.message.role === "assistant" ) { assistantMessage = event.message; modelEnd?.( event.message.stopReason === "error" || event.message.stopReason === "aborted" ? "error" : "finish", ); modelEnd = undefined; turns++; } if (event.type === "tool_execution_start") { dbg?.("tool.start"); const end = span?.("tool"); if (end) toolSpans.set(event.toolCallId, end); progress?.({ phase: "tool", preview: "", tool: { name: event.toolName, args: JSON.stringify(event.args, null, 2).slice(0, 6000), }, }); } if (event.type === "tool_execution_end") { dbg?.("tool.finish"); toolSpans.get(event.toolCallId)?.(event.isError ? "error" : "finish"); toolSpans.delete(event.toolCallId); if (event.toolName === "pipi_output" && event.isError) dbg?.("output.invalid", { count: 1 }); } if ( event.type === "message_update" && event.message.role === "assistant" && event.assistantMessageEvent.type === "text_delta" ) progress?.({ phase: "answering", preview: event.message.content .filter((part) => part.type === "text") .map((part) => part.text) .join("\n") .slice(-6000), }); }); // Recreate tools without an SDK registry allowlist, so native late registration remains possible. const { resolveToolNames } = await import("./tools.ts"); const enhanced = child .getActiveToolNames() .filter((name) => !inherited.availableTools.includes(name)); const baseline = [...new Set([...inherited.tools, ...enhanced])]; child.setActiveToolsByName( config.tools ? resolveToolNames(config.tools, baseline) : baseline, ); const extensionEnd = span?.("extensions"); await child.bindExtensions({ mode: "print", onError: (error) => diagnostics.push( `Child extension failed: ${error.extensionPath} (${error.event}): ${error.error}`, ), }); extensionEnd?.(); await inheritAuthentication(ctx, runtime, taskSignal); if (schema) child.setActiveToolsByName([ ...new Set([...child.getActiveToolNames(), "pipi_output"]), ]); effective = { cwd, model: child.model ? `${child.model.provider}/${child.model.id}` : null, thinkingLevel: child.thinkingLevel, tools: child.getActiveToolNames(), extensions: effective.extensions, skills: loader.getSkills().skills.map((skill) => skill.filePath), prompts: loader.getPrompts().prompts.map((prompt) => prompt.filePath), flagNames: [...loader.getExtensions().runtime.flagValues.keys()], }; const requestedTools = config.tools ? resolveToolNames(config.tools, baseline) : inherited.tools; const registered = new Map( child.getAllTools().map((tool) => [tool.name, tool]), ); const explicit = new Set( (config.tools ?? []).map((name) => name.startsWith("+") ? name.slice(1) : name, ), ); const excluded: string[] = []; const hidden: string[] = []; const inactive: string[] = []; const unavailable: string[] = []; for (const name of requestedTools) { if (effective.tools.includes(name)) continue; const tool = registered.get(name); if (!tool) unavailable.push(name); else if (tool.exposure === "hidden") (explicit.has(name) ? hidden : excluded).push(name); else inactive.push(name); } if (excluded.length) effective.excludedTools = excluded; if (hidden.length) diagnostics.push( `Requested tools hidden by child extension: ${hidden.join(", ")}`, ); if (inactive.length) diagnostics.push(`Requested tools inactive: ${inactive.join(", ")}`); if (unavailable.length) diagnostics.push( `Requested tools unavailable: ${unavailable.join(", ")}`, ); progress?.({ phase: "running", preview: "" }); taskSignal?.throwIfAborted(); const settleEnd = span?.("settlement"); let settle: Promise | undefined; try { settle = child.prompt(request.prompt, { source: "extension", ...(request.images ? { images: request.images } : {}), }); if (timeoutSignal) { const deadlineRace = new Promise<"deadline">((resolve) => { timeoutSignal.addEventListener("abort", () => resolve("deadline"), { once: true, }); }); const winner = await Promise.race([ settle.then(() => "settled" as const), deadlineRace, ]); if (winner === "deadline") settle.catch(() => {}); } else { await settle; } } finally { settleEnd?.(); } if (taskSignal?.aborted) outcome = "aborted"; if (outcome === "completed" && schema && !submitted) { outcome = "failed"; diagnostics.push( "Child completed without a valid current-call pipi_output submission after one reminder.", ); } } catch (error) { outcome = taskSignal?.aborted ? "aborted" : "error"; diagnostics.push( error instanceof Error ? error.message : "Child task failed", ); } finally { taskSignal?.removeEventListener("abort", abort); unsubscribe?.(); modelEnd?.("error"); for (const end of toolSpans.values()) end("error"); const disposeEnd = span?.("dispose"); if (child) { effective.model = child.model ? `${child.model.provider}/${child.model.id}` : null; effective.thinkingLevel = child.thinkingLevel; effective.tools = child.getActiveToolNames(); effective.sections = Object.keys(effectivePrompt?.sections ?? {}); try { const teardown = (async () => { if (!child.isIdle) await child.abort(); await child.extensionRunner.emit({ type: "session_shutdown", reason: "quit", }); })(); const forced = await Promise.race([ teardown.then(() => false), delay(TEARDOWN_TIMEOUT_MS).then(() => true), ]); teardown.catch(() => {}); if (forced) diagnostics.push( `Child teardown exceeded ${TEARDOWN_TIMEOUT_MS}ms; disposed forcefully.`, ); } catch { diagnostics.push("Child shutdown hook failed"); } finally { try { child.dispose(); } catch { diagnostics.push("Child dispose failed"); } } } disposeEnd?.(); } if (timeoutSignal?.aborted && !signal?.aborted && deadline !== undefined) diagnostics.push( `pipi deadline exceeded after ${deadline}ms; child aborted, session preserved for continuation.`, ); const result: TaskResult = { outputMode: schema ? "structured" : "message", outcome, output: schema ? output : json(assistantMessage), assistantMessage: schema ? assistantMessage : null, sessionId: manager.getSessionId(), sessionFile: manager.getSessionFile() ?? null, durationMs: performance.now() - started, turns, usage: newUsage(manager.getEntries(), before), requested: config, effective, diagnostics, }; taskEnd?.(outcome === "completed" ? "finish" : "error", { outcome }); return result; } catch (error) { taskEnd?.("error", { outcome: "error" }); throw error; } }