pygienium/tasks/03-agent-runner.md

03. Sub-agent runner with createAgentSession

meta: id: pygienium-03 feature: pygienium priority: P1 depends_on: [pygienium-01] tags: [infrastructure, core]

objective:

• Build src/agent-runner.ts: spawn isolated child pi sessions via createAgentSession, capture transcripts/results, and return a typed result — the engine that powers every check's sub-agent phases.

deliverables:

• src/agent-runner.ts exporting runAgent(options), AgentRuntimeModel, RunAgentResult, AgentRunError, buildRuntimeHeader, RuntimeContext
• Each run writes pygienium/runs/<runId>/{prompt.md, transcript.jsonl, result.md, error.txt}
• Inherits parent model + modelRegistry + thinkingLevel (so child phases reason at the same depth)
• AbortSignal support; onEvent forwarding hook for UI streaming
• Child tools: the built-in edit/write/read/bash surface; noExtensions: true (avoid recursion)

steps:

• Port piolium's agent-runner.ts shape: composed system prompt = runtime header + agent systemPrompt; DefaultResourceLoader with noExtensions/noThemes/noContextFiles; in-memory SessionManager
• Define AgentDefinition interface (name, description, systemPrompt, allowedTools, sourcePath) consumed here
• Wire session.subscribe to capture final assistant text + stopReason + errorMessage
• Handle abort: add/remove abort listener, call session.agent.abort()

tests:

• Unit: buildRuntimeHeader includes cwd, mode, phase, assigned output paths
• Integration: run a smoke agent (no-tools, replies with a fixed string) via runAgent; assert result.text non-empty and transcript.jsonl exists

acceptance_criteria:

• runAgent returns RunAgentResult with text + transcriptPath + durationMs
• Aborting the signal cancels the child session without leaving it running
• A child that errors throws AgentRunError carrying the result

validation:

• Invoke a smoke run from a temporary command and inspect the runs dir

notes:

• This is the most direct piolium port; keep it faithful to reduce risk
• Do NOT load extensions in the child (footgun) — noExtensions: true