pi-agent-replicate 0.0.0-stage → 1.4.1

package/index.ts

@@ -0,0 +1,155 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
+import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { PiRunningChild } from "./pi-extension/subagents/launch.ts";
+import { discoverAgentCatalog, effectiveRoleTools, resolveAgent, type AgentDefinition } from "./pi-extension/subagents/role-catalog.ts";
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+import { resolveRuntimePlan, wrapPiModelRegistry, type ResolvedRuntimePlan } from "./pi-extension/subagents/runtime-routing.ts";
+
+const TREE_REGISTRY = Symbol.for("pi-lpt-herdr-subagents/public-tree/v2");
+const PROCESS_ID = Symbol.for("pi-lpt-herdr-subagents/public-tree/process");
+const MAX_METADATA = 64 * 1024;
+const MAX_ERROR = 4000;
+const MAX_SESSION = 10000;
+const CANCEL_TIMEOUT_MS = 10000;
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+export interface SubagentTreeMetadata {
+  readonly value: unknown;
+  /** Immutable package-owned identity; value is the consumer-owned opaque metadata. */
+  readonly callerId?: string;
+  readonly treeId?: string;
+  readonly ownerId?: string;
+  readonly nodeId?: string;
+  readonly parentId?: string;
+}
+export interface SubagentError { readonly code: string; readonly message: string; }
+export interface SubagentWorktree { readonly path?: string; readonly branch?: string; readonly baseRef?: string; readonly baseSha?: string; readonly workspaceId?: string; readonly paneId?: string; readonly headSha?: string | null; readonly commitsAhead?: number | null; readonly clean?: boolean | null; readonly conflicted?: boolean | null; readonly changedFiles?: string[] | null; readonly untrackedFiles?: string[] | null; readonly manifestFile?: string; }
+export type SubagentChildOutcome = "clean" | "empty" | "error" | "intentional-abort" | "unexpected-abort";
+export interface SubagentChildResult { readonly resultId: string; readonly assistantEntryId: string; readonly answer: string | null; readonly outcome: SubagentChildOutcome; readonly sessionReference?: string; readonly error?: SubagentError; readonly worktree?: SubagentWorktree; readonly metadata?: SubagentTreeMetadata; }
+export interface SubagentNodeResult { readonly nodeId: string; readonly parentId: string; readonly outcome: SubagentChildOutcome; readonly open: boolean; readonly sessionReference?: string; readonly error?: SubagentError; }
+export interface SubagentTreeResult { readonly terminalId: string; readonly state: "completed" | "failed" | "cancelled"; readonly rootResult: SubagentChildResult; readonly callerMetadata: SubagentTreeMetadata; readonly nodes: readonly SubagentNodeResult[]; readonly error?: SubagentError; }
+export interface SubagentChildHandle { readonly nodeId: string; readonly parentId: string; readonly result: Promise<SubagentChildResult>; }
+export interface LaunchChildOptions { readonly parentId: string; readonly name: string; readonly task: string; readonly agent?: string; readonly skills?: string; readonly tools: readonly string[]; readonly cwd?: string; readonly worktree?: { readonly branch: string; readonly base?: string }; readonly metadata?: unknown; }
+export interface SubagentTreeHandle { readonly callerId: string; readonly treeId: string; readonly ownershipToken: string; readonly ownerId: string; readonly children: ReadonlyMap<string, SubagentChildHandle>; readonly result: Promise<SubagentTreeResult>; launchChild(options: LaunchChildOptions): Promise<SubagentChildHandle>; bindFinalCallback(callback: (result: SubagentTreeResult) => void | Promise<void>): void; cancel(): Promise<SubagentTreeResult>; }
+export interface CreateSubagentTreeOptions { readonly pi: ExtensionAPI; readonly ctx: ExtensionContext; readonly metadata?: unknown; }
+export interface ForkLineage { readonly previousSessionFile: string; }
+export interface AttachSubagentTreeOptions { readonly pi: ExtensionAPI; readonly ctx: ExtensionContext; readonly callerId?: string; readonly treeId?: string; readonly ownershipToken?: string; readonly forkLineage?: ForkLineage; }
+export class SubagentTreeError extends Error { constructor(message: string) { super(message); this.name = "SubagentTreeError"; } }
+export class SubagentTreeValidationError extends SubagentTreeError { constructor(message: string) { super(message); this.name = "SubagentTreeValidationError"; } }
+export class SubagentTreeOwnershipError extends SubagentTreeError { constructor(message: string) { super(message); this.name = "SubagentTreeOwnershipError"; } }
+interface NodeRecord { nodeId:string; parentId:string; ownerId:string; name:string; surface?:string; sessionFile?:string; status:"queued"|"running"|"settled"; open?:boolean; resultPath:string; metadata?:SubagentTreeMetadata; }
+interface TreeMeta { version:2; treeId:string; callerId:string; ownershipToken:string; artifactDir:string; treeDir:string; callerMetadata:SubagentTreeMetadata; boundSessionFile:string; acceptedSessionFiles?:Record<string,string[]>; }
+interface Deferred<T> { promise:Promise<T>; resolve:(value:T)=>void; }
+interface State { meta:TreeMeta; ownerId:string; pi:ExtensionAPI; ctx:ExtensionContext; boundSessionFile:string; children:Map<string,SubagentChildHandle>; pending:Map<string,Deferred<SubagentChildResult>>; launchTransactions:Set<Promise<void>>; launchControllers:Set<AbortController>; callback?: (r:SubagentTreeResult)=>void|Promise<void>; callbackVersion:number; deliverySerial:Promise<void>; terminal?:SubagentTreeResult; resolveTree:(r:SubagentTreeResult)=>void; treePromise:Promise<SubagentTreeResult>; cancellation?:Promise<SubagentTreeResult>; branchCancellation?:Promise<void>; cancellationRequested:boolean; }
+function processIdentity():string { const g=globalThis as typeof globalThis & {[PROCESS_ID]?:string}; return g[PROCESS_ID]??= `${process.pid}-${randomUUID()}`; }
+function registry():Map<string,State>{const g=globalThis as typeof globalThis & {[TREE_REGISTRY]?:Map<string,State>};return g[TREE_REGISTRY]??=new Map();}
+const stateKey=(tree:string,owner:string)=>`${tree}:${owner}`;
+const readJson=<T>(path:string):T|undefined=>{try{return JSON.parse(readFileSync(path,"utf8")) as T;}catch{return undefined;}};
+function atomic(path:string,value:unknown):void{mkdirSync(dirname(path),{recursive:true});const tmp=`${path}.${process.pid}.${randomUUID()}.tmp`;writeFileSync(tmp,`${JSON.stringify(value)}\n`);renameSync(tmp,path);}
+function exclusiveAtomic(path:string,value:unknown):boolean{mkdirSync(dirname(path),{recursive:true});const tmp=`${path}.${process.pid}.${randomUUID()}.tmp`;try{writeFileSync(tmp,`${JSON.stringify(value)}\n`);linkSync(tmp,path);return true;}catch(e){if((e as NodeJS.ErrnoException).code==="EEXIST")return false;throw e;}finally{try{unlinkSync(tmp);}catch{}}}
+const bounded=(s:string,n:number)=>s.length<=n?s:s.slice(0,n);
+const message=(e:unknown)=>e instanceof Error?e.message:String(e);
+function metadata(value:unknown):SubagentTreeMetadata{let encoded:string|undefined;try{encoded=JSON.stringify(value);}catch(e){throw new SubagentTreeValidationError(`metadata must be JSON-compatible: ${message(e)}`);}if(encoded===undefined)throw new SubagentTreeValidationError("metadata must be JSON-compatible");if(Buffer.byteLength(encoded,"utf8")>MAX_METADATA)throw new SubagentTreeValidationError("metadata exceeds the 64 KiB limit");return deepFreeze({value:JSON.parse(encoded) as JsonValue});}
+function identityMetadata(base:SubagentTreeMetadata,meta:TreeMeta,ownerId:string,nodeId?:string,parentId?:string):SubagentTreeMetadata{return deepFreeze({...base,callerId:meta.callerId,treeId:meta.treeId,ownerId,...(nodeId?{nodeId}:{}),...(parentId?{parentId}:{})});}
+function context(ctx:ExtensionContext){const m=ctx.sessionManager;const file=m.getSessionFile();if(!file)throw new SubagentTreeValidationError("No session file");return {sessionFile:file,sessionId:m.getSessionId(),sessionDir:m.getSessionDir(),cwd:ctx.cwd??process.cwd(),agentDir:process.env.PI_CODING_AGENT_DIR};}
+function ownerSession(meta:TreeMeta,owner:string){if(owner===meta.callerId)return meta.boundSessionFile;return readJson<NodeRecord>(join(meta.treeDir,"nodes",`${owner}.json`))?.sessionFile;}
+function header(path:string){try{const x=JSON.parse(readFileSync(path,"utf8").split("\n",1)[0]) as {parentSession?:unknown};return typeof x.parentSession==="string"?x.parentSession:undefined;}catch{return undefined;}}
+function findTreeMeta(sessionDir:string,treeId:string):TreeMeta|undefined{const root=join(sessionDir,"artifacts");if(!existsSync(root))return;for(const sid of readdirSync(root)){const p=join(root,sid,"subagent-trees",treeId,"tree.json"),m=readJson<TreeMeta>(p);if(m)return m;}return;}
+function validateLineage(meta:TreeMeta,owner:string,ctx:ExtensionContext,lineage?:ForkLineage,bound?:string){const fresh=context(ctx).sessionFile;if(lineage===undefined)return fresh;if(typeof lineage.previousSessionFile!=="string"||!lineage.previousSessionFile)throw new SubagentTreeOwnershipError("fork lineage previousSessionFile is required");const prior=bound??ownerSession(meta,owner);if(!prior||prior!==lineage.previousSessionFile)throw new SubagentTreeOwnershipError("fork lineage does not match the currently bound session");if(header(fresh)!==lineage.previousSessionFile)throw new SubagentTreeOwnershipError("fork session header does not match the previous session");return fresh;}
+function processAlive(pid: number): boolean { try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code !== "ESRCH"; } }
+/** Reclaim a dead claim without unlinking a newly-created owner claim. */
+function reclaimDeadClaim(path: string, owner: Record<string, unknown>): boolean {
+  for (;;) {
+    if (exclusiveAtomic(path, owner)) return true;
+    const old = readJson<{ process?: string; pid?: number }>(path);
+    if (old?.process === owner.process) return false;
+    if (typeof old?.pid === "number" && processAlive(old.pid)) return false;
+    let before: { dev: number; ino: number };
+    try { const st = statSync(path); before = { dev: st.dev, ino: st.ino }; } catch { continue; }
+    const moved = `${path}.${processIdentity()}.${randomUUID()}.stale`;
+    try { renameSync(path, moved); } catch { continue; }
+    let same = false;
+    try { const st = statSync(moved); same = st.dev === before.dev && st.ino === before.ino; } catch {}
+    if (!same) { try { if (!existsSync(path)) renameSync(moved, path); } catch {} continue; }
+    try { unlinkSync(moved); } catch {}
+  }
+}
+function claimBranch(meta:TreeMeta,owner:string){const p=join(meta.treeDir,"branches",`${owner}.claim`), identity={process:processIdentity(),pid:process.pid,owner,token:randomUUID()};if(reclaimDeadClaim(p,identity))return;throw new SubagentTreeOwnershipError("subagent branch is owned by another process");}
+function claimRoot(s:State):void{const p=join(s.meta.treeDir,"root.claim"),identity={process:processIdentity(),pid:process.pid,token:randomUUID()};if(exclusiveAtomic(p,identity))return;const old=readJson<{process?:string;pid?:number}>(p);if(old?.process===identity.process)throw new SubagentTreeOwnershipError("subagent tree already has a direct root");if(readdirSync(join(s.meta.treeDir,"nodes")).some(x=>x.endsWith(".json")))throw new SubagentTreeOwnershipError("subagent tree already has a direct root");if(reclaimDeadClaim(p,identity))return;throw new SubagentTreeOwnershipError("subagent tree already has a direct root");}
+function deferred<T>():Deferred<T>{let resolve!:(value:T)=>void;const promise=new Promise<T>(r=>{resolve=r;});return {promise,resolve};}
+function nodePath(s:State,id:string){return join(s.meta.treeDir,"nodes",`${id}.json`);}
+function inflightPath(s:State,id:string){return join(s.meta.treeDir,"branches",`${s.ownerId}.${id}.inflight.json`);}
+function clearInflight(s:State,id:string,token:string){const p=inflightPath(s,id),record=readJson<{token?:string}>(p);if(record?.token===token)try{unlinkSync(p);}catch{}}
+type InflightRecord = {path:string;pid?:number;ownerId?:string;nodeId?:string};
+function inflightRecords(s:State):InflightRecord[] {const dir=join(s.meta.treeDir,"branches");if(!existsSync(dir))return [];return readdirSync(dir).filter(x=>x.endsWith(".inflight.json")).flatMap(x=>{const path=join(dir,x),r=readJson<Omit<InflightRecord,"path">>(path);return r?[{path,...r}]:[{path}];});}
+function writeNode(s:State,node:NodeRecord){atomic(nodePath(s,node.nodeId),node);}
+function terminalIntentPath(s:State){return join(s.meta.treeDir,"terminal-intent.json");}
+function claimTerminalIntent(s:State,kind:"completed"|"cancelled"):boolean{return exclusiveAtomic(terminalIntentPath(s),{kind,ownerId:s.ownerId,process:processIdentity(),terminalId:randomUUID(),at:Date.now()});}
+function currentTerminalIntent(s:State):"completed"|"cancelled"|undefined{return readJson<{kind?:unknown}>(terminalIntentPath(s))?.kind as "completed"|"cancelled"|undefined;}
+function branchNodes(s:State):NodeRecord[]{const d=join(s.meta.treeDir,"nodes");if(!existsSync(d))return [];return readdirSync(d).filter(x=>x.endsWith(".json")).flatMap(f=>{const n=readJson<NodeRecord>(join(d,f));return n?.ownerId===s.ownerId?[n]:[];});}
+function allNodes(s:State):NodeRecord[]{const d=join(s.meta.treeDir,"nodes");if(!existsSync(d))return [];return readdirSync(d).filter(x=>x.endsWith(".json")).flatMap(f=>{const n=readJson<NodeRecord>(join(d,f));return n?[n]:[];});}
+function pendingInflightRecords(s:State,ownerId?:string):InflightRecord[]{const nodes=allNodes(s);return inflightRecords(s).filter(r=>{if(ownerId!==undefined&&r.ownerId!==ownerId)return false;const node=r.nodeId?nodes.find(n=>n.nodeId===r.nodeId):undefined;return !node||node.ownerId!==r.ownerId||!node.surface;});}
+function pendingBranchEvidence(s:State,ownerId:string){const nodes=allNodes(s),inflight=pendingInflightRecords(s,ownerId).length,queued=nodes.filter(n=>n.ownerId===ownerId&&n.status==="queued"&&!existsSync(n.resultPath)).length;return {inflight,queued};}
+async function waitBranchTransactions(s:State):Promise<boolean>{const deadline=Date.now()+CANCEL_TIMEOUT_MS;while(s.launchTransactions.size&&Date.now()<deadline)await new Promise(r=>setTimeout(r,25));return s.launchTransactions.size===0;}
+async function cancelBranch(s:State):Promise<void>{
+  if(s.branchCancellation)return s.branchCancellation;
+  s.cancellationRequested=true;
+  s.branchCancellation=(async()=>{
+    const mux=await import("./pi-extension/subagents/terminal.ts");
+    for(const controller of s.launchControllers)controller.abort();
+    const transactionsSettled=await waitBranchTransactions(s),pids=new Set<number>(),nodePids=new Map<string,number[]>();
+    for(const n of branchNodes(s)){
+      if(n.open===false)continue;
+      if(!n.surface){
+        if(n.status!=="settled"){const result=writeResult(s,n,failedResult("tree_cancelled","queued child cancelled",n.metadata));s.pending.get(n.nodeId)?.resolve(result);}
+        continue;
+      }
+      if(n.status!=="settled")try{const info=mux.getPaneProcessInfo(n.surface),captured=info.pids.filter(pid=>Number.isInteger(pid)&&pid>0);for(const pid of captured)pids.add(pid);if(captured.length)nodePids.set(n.nodeId,captured);}catch{}
+      try{mux.closePane(n.surface);}catch{}
+      try{n.open=!(await mux.waitForPaneAbsence(n.surface,{timeoutMs:5000}));}catch(e){n.open=!/pane_not_found|pane not found/i.test(message(e));}
+      if(n.status!=="settled"){const result=writeResult(s,n,failedResult("tree_cancelled","running child cancelled",n.metadata));s.pending.get(n.nodeId)?.resolve(result);}else writeNode(s,n);
+    }
+    let remaining:number[]=[];
+    let processCheckConfirmed=true;
+    try{remaining=await mux.waitForProcessesExit([...pids],{timeoutMs:5000});}catch{processCheckConfirmed=false;}
+    const inflight=pendingInflightRecords(s,s.ownerId),ack={ownerId:s.ownerId,process:processIdentity(),pid:process.pid,at:Date.now(),transactionsSettled,inflight:inflight.length,remainingPids:remaining,nodes:branchNodes(s).map(n=>({nodeId:n.nodeId,open:n.open??false}))};
+    if(!existsSync(join(s.meta.treeDir,"branches",`${s.ownerId}.cancelled.json`)))atomic(join(s.meta.treeDir,"branches",`${s.ownerId}.cancelled.json`),ack);
+    if(s.ownerId===s.meta.callerId&&processCheckConfirmed&&!remaining.length)for(const n of branchNodes(s)){
+    // The root may close a child branch before it can publish its own acknowledgement.
+    // Captured process exit plus pane absence is equivalent termination evidence.
+      const captured=nodePids.get(n.nodeId);
+      if(!captured?.length||n.open!==false||captured.some(pid=>remaining.includes(pid)))continue;
+      const childAckPath=join(s.meta.treeDir,"branches",`${n.nodeId}.cancelled.json`),pending=pendingBranchEvidence(s,n.nodeId);
+      if(!existsSync(childAckPath))atomic(childAckPath,{ownerId:n.nodeId,process:processIdentity(),pid:process.pid,at:Date.now(),synthesized:true,transactionsSettled:pending.inflight===0&&pending.queued===0,inflight:pending.inflight,unresolvedQueued:pending.queued,remainingPids:[],nodes:[{nodeId:n.nodeId,open:false}]});
+    }
+  })();
+  return s.branchCancellation;
+}
+function writeResult(s:State,node:NodeRecord,result:SubagentChildResult){const frozen=deepFreeze(result);if(!exclusiveAtomic(node.resultPath,frozen)){const winner=readJson<SubagentChildResult>(node.resultPath);if(winner){atomic(nodePath(s,node.nodeId),{...node,status:"settled"});return deepFreeze(winner);}return frozen;}atomic(nodePath(s,node.nodeId),{...node,status:"settled"});return frozen;}
+function isCancelled(s:State){return s.cancellationRequested||existsSync(join(s.meta.treeDir,"cancel.request"));}
+function failedResult(code:string,msg:string,meta?:SubagentTreeMetadata):SubagentChildResult{return {resultId:randomUUID(),assistantEntryId:randomUUID(),answer:null,outcome:"unexpected-abort",error:{code,message:bounded(msg,MAX_ERROR)},...(meta?{metadata:meta}:{})};}
+function rows(s:State):SubagentNodeResult[]{const d=join(s.meta.treeDir,"nodes");if(!existsSync(d))return [];return readdirSync(d).filter(x=>x.endsWith(".json")).sort().flatMap(f=>{const n=readJson<NodeRecord>(join(d,f));if(!n)return [];const r=readJson<SubagentChildResult>(n.resultPath);return [{nodeId:n.nodeId,parentId:n.parentId,outcome:r?.outcome??"unexpected-abort",open:n.open??(r?.outcome!=="clean"&&r?.outcome!=="empty"),...(n.sessionFile?{sessionReference:bounded(n.sessionFile,MAX_SESSION)}:{}),...(r?.error?{error:r.error}:{}),}];});}
+function rootResult(s:State){const d=join(s.meta.treeDir,"nodes");if(!existsSync(d))return undefined;const roots=readdirSync(d).filter(x=>x.endsWith(".json")).map(f=>readJson<NodeRecord>(join(d,f))).filter((n):n is NodeRecord=>Boolean(n&&n.parentId===s.meta.callerId));if(roots.length!==1)return undefined;return readJson<SubagentChildResult>(roots[0].resultPath);}
+async function authoritative(s:State,candidate:SubagentTreeResult):Promise<SubagentTreeResult>{const terminalPath=join(s.meta.treeDir,"terminal.json");if(exclusiveAtomic(terminalPath,candidate))return candidate;for(;;){const record=readJson<SubagentTreeResult>(terminalPath);if(record)return record;await new Promise(r=>setTimeout(r,10));}}
+function adopt(s:State,r:SubagentTreeResult){if(s.terminal)return;s.terminal=deepFreeze(r);s.resolveTree(s.terminal);void deliver(s,s.terminal);}
+async function finish(s:State,r:SubagentTreeResult){adopt(s,await authoritative(s,r));}
+async function closeCleanPanes(s:State):Promise<void>{const terminal=await import("./pi-extension/subagents/terminal.ts"),dir=join(s.meta.treeDir,"nodes");for(const f of readdirSync(dir).filter(x=>x.endsWith(".json"))){const n=readJson<NodeRecord>(join(dir,f)),r=n?readJson<SubagentChildResult>(n.resultPath):undefined;if(!n||!r||!n.surface||r.worktree||(r.outcome!=="clean"&&r.outcome!=="empty")||n.open===false)continue;try{terminal.closePane(n.surface);n.open=!(await terminal.waitForPaneAbsence(n.surface,{timeoutMs:5000}));writeNode(s,n);}catch{n.open=true;writeNode(s,n);}}}
+async function maybeFinish(s:State){if(s.terminal||s.ownerId!==s.meta.callerId)return;const existing=readJson<SubagentTreeResult>(join(s.meta.treeDir,"terminal.json"));if(existing){adopt(s,existing);return;}if(isCancelled(s)||currentTerminalIntent(s)==="cancelled")return;const root=rootResult(s);if(!root)return;let all=rows(s);if(all.some(r=>!readJson(join(s.meta.treeDir,"results",`${r.nodeId}.json`))))return;if(!claimTerminalIntent(s,"completed")){if(currentTerminalIntent(s)!=="completed")return;return;}await closeCleanPanes(s);all=rows(s);const state=root.outcome==="clean"||root.outcome==="empty"?"completed":"failed";await finish(s,{terminalId:randomUUID(),state,rootResult:root,callerMetadata:s.meta.callerMetadata,nodes:all});}
+async function deliverAttempt(s:State,r:SubagentTreeResult){if(!s.callback||existsSync(join(s.meta.treeDir,"delivery.done")))return;const claimPath=join(s.meta.treeDir,"delivery.claim"),claim={process:processIdentity(),pid:process.pid,token:randomUUID(),terminalId:r.terminalId,version:s.callbackVersion};if(!reclaimDeadClaim(claimPath,claim))return;const callback=s.callback;try{if(!callback)return;await callback(r);if(!existsSync(join(s.meta.treeDir,"delivery.done")))writeFileSync(join(s.meta.treeDir,"delivery.done"),`${r.terminalId}\n`,{flag:"wx"});}catch{}finally{const held=readJson<{token?:string}>(claimPath);if(!existsSync(join(s.meta.treeDir,"delivery.done"))&&held?.token===claim.token)try{unlinkSync(claimPath);}catch{}}}
+async function deliver(s:State,r:SubagentTreeResult){const attempt=s.deliverySerial.then(()=>deliverAttempt(s,r));s.deliverySerial=attempt.catch(()=>{});return attempt;}
+async function watch(s:State,node:NodeRecord,running:PiRunningChild,pending:Deferred<SubagentChildResult>){const [{waitForCompletion},terminal,session,activity,launchModule]=await Promise.all([import("./pi-extension/subagents/completion.ts"),import("./pi-extension/subagents/terminal.ts"),import("./pi-extension/subagents/session.ts"),import("./pi-extension/subagents/activity.ts"),import("./pi-extension/subagents/launch.ts")]);const abort=new AbortController();try{const completion=await Promise.race([waitForCompletion(abort.signal,{intervalMs:100,sessionFile:running.sessionFile,readTerminalTail:()=>terminal.readPaneAsync(running.surface,5),inspectPane:()=>terminal.inspectPane(running.surface)}),(async()=>{for(;;){if(isCancelled(s))throw new Error("tree cancellation requested");const e=activity.readSubagentSettledEventsFile(running.settledEventsFile,running.id).at(-1);if(e?.outcome==="error")return {reason:"error",exitCode:1,errorMessage:e.errorMessage} as const;if(e?.outcome==="clean"||e?.outcome==="empty")return {reason:"done",exitCode:0} as const;await new Promise(r=>setTimeout(r,100));}})()]);abort.abort();const a=session.inspectNewestAppendedAssistant(running.sessionFile,running.sessionBaseline)??{id:randomUUID(),text:null,empty:true,stopReason:"error",errorMessage:"Subagent produced no settled assistant response"};const bad=completion.reason==="error"||a.stopReason==="error"||completion.exitCode!==0;if(isCancelled(s))return;let open=true;try{const inspection=await terminal.inspectPane(running.surface);const processInfo=terminal.getPaneProcessInfo(running.surface);open=inspection.kind!=="missing"||processInfo.pids.length>0;node.open=open;}catch{node.open=true;}const outcome=a.stopReason==="aborted"?"unexpected-abort":bad?"error":a.empty?"empty":"clean";const result=writeResult(s,node,{resultId:randomUUID(),assistantEntryId:a.id,answer:a.text,outcome,sessionReference:bounded(running.sessionFile,MAX_SESSION),...(outcome==="error"||outcome==="unexpected-abort"?{error:{code:a.stopReason==="error"?"provider_error":"runtime_error",message:bounded(a.errorMessage??completion.errorMessage??"Subagent failed",MAX_ERROR)}}:{}),...(node.metadata?{metadata:node.metadata}:{}),...(running.worktree?{worktree:launchModule.captureWorktreeHandoff(running.worktree)}:{})});pending.resolve(result);if(!isCancelled(s))void maybeFinish(s);}catch(e){if(!readJson(node.resultPath)&&!isCancelled(s)){const result=writeResult(s,node,failedResult("runtime_error",message(e),node.metadata));pending.resolve(result);void maybeFinish(s);}}}
+async function launch(s:State,o:LaunchChildOptions):Promise<SubagentChildHandle>{if(s.terminal||readJson(join(s.meta.treeDir,"terminal.json"))||isCancelled(s))throw new SubagentTreeError("subagent tree is terminal");if(o.parentId!==s.ownerId)throw new SubagentTreeOwnershipError("parent is not owned by this branch");if(!o.name||!o.task)throw new SubagentTreeValidationError("child name and task are required");if(!Array.isArray(o.tools)||!o.tools.length)throw new SubagentTreeValidationError("child tools are required");const consumerMetadata=o.metadata===undefined?metadata(null):metadata(o.metadata);const role=o.agent?resolveAgent(o.agent,s.pi):undefined;if(o.agent&&!role){const d=discoverAgentCatalog(s.pi).diagnostics.find(x=>x.agentName===o.agent);throw new SubagentTreeValidationError(d?.message??`Agent ${JSON.stringify(o.agent)} was not found`);}let tools:string[];try{tools=effectiveRoleTools(o.tools,role);}catch(e){throw new SubagentTreeValidationError(message(e));}if(isCancelled(s))throw new SubagentTreeError("subagent tree is terminal");const parent=context(s.ctx);if(!s.ctx.model)throw new SubagentTreeValidationError("No parent model is selected");const thinking=s.pi.getThinkingLevel();if(typeof thinking!=="string")throw new SubagentTreeValidationError(`Unsupported thinking level: ${thinking}`);const registryAdapter=wrapPiModelRegistry((s.ctx as ExtensionContext & {modelRegistry:Parameters<typeof wrapPiModelRegistry>[0]}).modelRegistry);const plan:ResolvedRuntimePlan=resolveRuntimePlan({model:role?.model,thinking:role?.thinking},{provider:s.ctx.model.provider,modelId:s.ctx.model.id,thinking:thinking as ThinkingLevel},registryAdapter);if(o.parentId===s.meta.callerId)claimRoot(s);const id=randomUUID(),childMetadata=identityMetadata(consumerMetadata,s.meta,s.ownerId,id,o.parentId),node:NodeRecord={nodeId:id,parentId:o.parentId,ownerId:s.ownerId,name:o.name,resultPath:join(s.meta.treeDir,"results",`${id}.json`),status:"queued",metadata:childMetadata},pending=deferred<SubagentChildResult>();s.pending.set(id,pending);s.children.set(id,Object.freeze({nodeId:id,parentId:o.parentId,result:pending.promise}));writeNode(s,node);const transaction=deferred<void>(),controller=new AbortController(),inflightToken=randomUUID();s.launchTransactions.add(transaction.promise);s.launchControllers.add(controller);atomic(inflightPath(s,id),{ownerId:s.ownerId,pid:process.pid,process:processIdentity(),nodeId:id,token:inflightToken});const contextPath=join(s.meta.treeDir,"context",`${id}.json`);atomic(contextPath,{...s.meta,ownerId:id});try{if(isCancelled(s)){const r=writeResult(s,node,failedResult("tree_cancelled","subagent tree cancellation requested",childMetadata));pending.resolve(r);return s.children.get(id)!;}const {launchPiSubagent}=await import("./pi-extension/subagents/launch.ts");const effectiveAutoExit=role?role.autoExit??false:true;const running=await launchPiSubagent({kind:"fresh",id,name:o.name,task:o.task,agent:o.agent,cwd:o.cwd,worktree:o.worktree,parent:{cwd:parent.cwd,invocationCwd:process.cwd(),sessionFile:parent.sessionFile,sessionId:parent.sessionId,sessionDir:parent.sessionDir,agentDir:parent.agentDir},runtimePlan:plan,environment:{PI_SUBAGENT_TREE_CONTEXT:contextPath,PI_SUBAGENT_TREE_OWNER:"1"},signal:controller.signal,behavior:{tools:tools.join(","),skills:o.skills??role?.skills,deniedTools:[],autoExit:effectiveAutoExit,interactive:role?.interactive??!effectiveAutoExit,includeControlTools:false,identity:role?.body,systemPromptMode:role?.systemPromptMode,sessionMode:role?.sessionMode??"standalone",cwd:role?.cwd}});node.surface=running.surface;node.sessionFile=running.sessionFile;node.status="running";writeNode(s,node);if(isCancelled(s)){try{const terminal=await import("./pi-extension/subagents/terminal.ts");terminal.closePane(running.surface);node.open=!(await terminal.waitForPaneAbsence(running.surface,{timeoutMs:5000}));}catch{node.open=true;}const r=writeResult(s,node,failedResult("tree_cancelled","subagent tree cancellation requested",childMetadata));pending.resolve(r);return s.children.get(id)!;}void watch(s,node,running,pending);}catch(e){const r=writeResult(s,node,failedResult(isCancelled(s)?"tree_cancelled":"launch_failed",message(e),childMetadata));pending.resolve(r);maybeFinish(s);return s.children.get(id)!;}finally{clearInflight(s,id,inflightToken);transaction.resolve();s.launchTransactions.delete(transaction.promise);s.launchControllers.delete(controller);}return s.children.get(id)!;}
+async function waitTerminal(s:State){for(;;){const r=readJson<SubagentTreeResult>(join(s.meta.treeDir,"terminal.json"));if(r){adopt(s,r);return r;}await new Promise(r=>setTimeout(r,25));}}
+async function waitBranchAcks(s:State,failures:string[],includeRoot=true):Promise<void>{const owners=new Set<string>();if(includeRoot)owners.add(s.meta.callerId);for(const f of readdirSync(join(s.meta.treeDir,"nodes")).filter(x=>x.endsWith(".json"))){const n=readJson<NodeRecord>(join(s.meta.treeDir,"nodes",f));if(n)owners.add(n.ownerId);}if(!includeRoot)owners.delete(s.meta.callerId);const inspect=()=>{for(const owner of owners){const ack=readJson<{transactionsSettled?:boolean;inflight?:number;unresolvedQueued?:number;synthesized?:boolean;remainingPids?:number[]}>(join(s.meta.treeDir,"branches",`${owner}.cancelled.json`));if(!ack){failures.push(`branch cancellation acknowledgement missing: ${owner}`);continue;}const pending=pendingBranchEvidence(s,owner);if(ack.transactionsSettled===false)failures.push(`branch cancellation transaction did not settle: ${owner}`);if((ack.inflight??0)>0||pending.inflight>0)failures.push(`branch cancellation reservation remains: ${owner}`);if((ack.unresolvedQueued??0)>0||pending.queued>0)failures.push(`branch cancellation queued launch remains: ${owner}`);if(ack.synthesized&&(pending.inflight>0||pending.queued>0))failures.push(`synthesized branch cancellation evidence is incomplete: ${owner}`);if((ack.remainingPids??[]).length)failures.push(`branch processes remain: ${(ack.remainingPids??[]).join(",")}`);}};const deadline=Date.now()+CANCEL_TIMEOUT_MS;while(Date.now()<deadline){const missing=[...owners].some(owner=>!existsSync(join(s.meta.treeDir,"branches",`${owner}.cancelled.json`)));if(!missing){inspect();return;}await new Promise(r=>setTimeout(r,25));}inspect();}
+async function cancelWork(s:State){const mux=await import("./pi-extension/subagents/terminal.ts");atomic(join(s.meta.treeDir,"cancel.request"),{process:processIdentity(),at:Date.now()});const failures:string[]=[],pids=new Set<number>();await cancelBranch(s);await waitBranchAcks(s,failures);const deadline=Date.now()+CANCEL_TIMEOUT_MS;for(const row of rows(s)){const n=readJson<NodeRecord>(join(s.meta.treeDir,"nodes",`${row.nodeId}.json`));if(!n||n.open===false)continue;if(!n.surface){if(n.status==="running"){failures.push(`missing pane identity for ${n.nodeId}`);n.open=true;}else n.open=false;const result=writeResult(s,n,failedResult("tree_cancelled",n.status==="running"?"running child lost its pane":"queued child cancelled",n.metadata));s.pending.get(n.nodeId)?.resolve(result);continue;}try{const info=mux.getPaneProcessInfo(n.surface);if(!info.pids.length&&n.status!=="settled")failures.push(`missing process identity for ${n.nodeId}`);for(const pid of info.pids)pids.add(pid);}catch(e){if(!/pane_not_found|pane not found/i.test(message(e)))failures.push(message(e));}try{mux.closePane(n.surface);}catch{ /* another branch may have closed it */ }}for(const row of rows(s)){const n=readJson<NodeRecord>(join(s.meta.treeDir,"nodes",`${row.nodeId}.json`));if(!n?.surface||n.open===false)continue;try{let absent=false;for(let attempt=0;attempt<3&&!absent;attempt++){if(attempt>0)try{mux.closePane(n.surface);}catch{}absent=await mux.waitForPaneAbsence(n.surface,{timeoutMs:5000});}n.open=!absent;writeNode(s,n);if(!absent)failures.push(`pane ${n.surface} remains`);}catch(e){failures.push(message(e));}}try{const left=await mux.waitForProcessesExit([...pids],{timeoutMs:5000});if(left.length)failures.push(`processes remain: ${left.join(",")}`);}catch(e){failures.push(message(e));}while(Date.now()<deadline&&pendingInflightRecords(s).some(x=>typeof x.pid!=="number"||processAlive(x.pid)))await new Promise(r=>setTimeout(r,25));if(pendingInflightRecords(s).some(x=>typeof x.pid!=="number"||processAlive(x.pid)))failures.push("in-flight launch reservation remains");const error=failures.length?{code:"cancel_termination_failed",message:bounded(failures.join("; "),MAX_ERROR)}:undefined;if(!error)for(const inFlight of inflightRecords(s)){if(typeof inFlight.pid!=="number"||!processAlive(inFlight.pid)){try{unlinkSync(inFlight.path);}catch{}}}const terminal:SubagentTreeResult={terminalId:randomUUID(),state:error?"failed":"cancelled",callerMetadata:s.meta.callerMetadata,rootResult:failedResult(error?error.code:"tree_cancelled",error?.message??"tree cancelled"),...(error?{error}:{}),nodes:error?rows(s).map(r=>({...r,open:true})):rows(s)};await finish(s,terminal);return s.terminal??terminal;}
+function cancel(s:State):Promise<SubagentTreeResult>{const existing=readJson<SubagentTreeResult>(join(s.meta.treeDir,"terminal.json"));if(existing){adopt(s,existing);return Promise.resolve(existing);}if(s.cancellation)return s.cancellation;if(currentTerminalIntent(s)==="completed"){s.cancellation=waitTerminal(s);return s.cancellation;}if(!claimTerminalIntent(s,"cancelled")){if(currentTerminalIntent(s)!=="cancelled"){s.cancellation=waitTerminal(s);return s.cancellation;}}s.cancellationRequested=true;s.cancellation=cancelWork(s);return s.cancellation;}
+function sync(s:State){const terminal=readJson<SubagentTreeResult>(join(s.meta.treeDir,"terminal.json"));if(terminal)adopt(s,terminal);for(const [id,p] of s.pending){const n=readJson<NodeRecord>(nodePath(s,id));const r=n?readJson<SubagentChildResult>(n.resultPath):undefined;if(r)p.resolve(deepFreeze(r));}if(isCancelled(s)&&!s.branchCancellation&&s.ownerId!==s.meta.callerId)void cancelBranch(s);maybeFinish(s);}
+function makeState(meta:TreeMeta,pi:ExtensionAPI,ctx:ExtensionContext,ownerId:string):State{claimBranch(meta,ownerId);let resolveTree!:(r:SubagentTreeResult)=>void;const treePromise=new Promise<SubagentTreeResult>(r=>{resolveTree=r;});const s:State={meta,ownerId,pi,ctx,boundSessionFile:ownerSession(meta,ownerId)??context(ctx).sessionFile,children:new Map(),pending:new Map(),launchTransactions:new Set(),launchControllers:new Set(),callbackVersion:0,deliverySerial:Promise.resolve(),resolveTree,treePromise,cancellationRequested:false};const dir=join(meta.treeDir,"nodes");if(existsSync(dir))for(const f of readdirSync(dir).filter(x=>x.endsWith(".json"))){const n=readJson<NodeRecord>(join(dir,f));if(n?.ownerId===ownerId){const p=deferred<SubagentChildResult>();s.pending.set(n.nodeId,p);const r=readJson<SubagentChildResult>(n.resultPath);if(r)p.resolve(deepFreeze(r));s.children.set(n.nodeId,Object.freeze({nodeId:n.nodeId,parentId:n.parentId,result:p.promise}));}}const terminal=readJson<SubagentTreeResult>(join(meta.treeDir,"terminal.json"));if(terminal)adopt(s,terminal);const timer=setInterval(()=>sync(s),100);timer.unref();return s;}
+function readonlyChildren(s:State):ReadonlyMap<string,SubagentChildHandle>{const view={get size(){return s.children.size;},get:(key:string)=>s.children.get(key),has:(key:string)=>s.children.has(key),keys:()=>s.children.keys(),values:()=>s.children.values(),entries:()=>s.children.entries(),forEach:(fn:(value:SubagentChildHandle,key:string,map:ReadonlyMap<string,SubagentChildHandle>)=>void)=>s.children.forEach((value,key)=>fn(value,key,view)),[Symbol.iterator]:()=>s.children[Symbol.iterator]()};return Object.freeze(view) as ReadonlyMap<string,SubagentChildHandle>;}
+function expose(s:State):SubagentTreeHandle{return Object.freeze({get callerId(){return s.meta.callerId;},get treeId(){return s.meta.treeId;},get ownershipToken(){return s.meta.ownershipToken;},get ownerId(){return s.ownerId;},get children(){return readonlyChildren(s);},get result(){sync(s);return s.treePromise;},launchChild:(o:LaunchChildOptions)=>launch(s,o),bindFinalCallback:(cb:(r:SubagentTreeResult)=>void|Promise<void>)=>{if(s.ownerId!==s.meta.callerId)throw new SubagentTreeOwnershipError("only the original caller may bind the final callback");s.callbackVersion++;s.callback=cb;if(s.terminal)void deliver(s,s.terminal);},cancel:()=>cancel(s)});}
+/** Create a caller-owned tree. Importing this module performs no registration. */
+export function createSubagentTree(options:CreateSubagentTreeOptions):SubagentTreeHandle{const baseMetadata=metadata(options.metadata === undefined ? null : options.metadata),c=context(options.ctx),treeId=randomUUID(),callerId=randomUUID(),token=randomUUID(),treeDir=join(c.sessionDir,"artifacts",c.sessionId,"subagent-trees",treeId),callerMetadata=deepFreeze(identityMetadata(baseMetadata,{callerId,treeId} as TreeMeta,callerId,callerId)),meta:TreeMeta={version:2,treeId,callerId,ownershipToken:token,artifactDir:join(c.sessionDir,"artifacts",c.sessionId),treeDir,callerMetadata,boundSessionFile:c.sessionFile,acceptedSessionFiles:{[callerId]:[c.sessionFile]}};mkdirSync(join(treeDir,"nodes"),{recursive:true});atomic(join(treeDir,"tree.json"),meta);const s=makeState(meta,options.pi,options.ctx,callerId);registry().set(stateKey(treeId,callerId),s);return expose(s);}
+/** Reattach a caller or claim a child branch using its package context. */
+export function attachSubagentTree(options:AttachSubagentTreeOptions):SubagentTreeHandle{const contextPath=process.env.PI_SUBAGENT_TREE_CONTEXT,ctxMeta=contextPath?readJson<TreeMeta&{ownerId?:string}>(contextPath):undefined,values=[options.callerId,options.treeId,options.ownershipToken],has=values.some(x=>x!==undefined);if(has&&values.some(x=>x===undefined))throw new SubagentTreeOwnershipError("callerId, treeId, and ownershipToken must be supplied together");const treeId=options.treeId??ctxMeta?.treeId,callerId=options.callerId??ctxMeta?.callerId,token=options.ownershipToken??ctxMeta?.ownershipToken;if(!treeId||!callerId||!token)throw new SubagentTreeOwnershipError("tree credentials are required");if(ctxMeta&&(treeId!==ctxMeta.treeId||callerId!==ctxMeta.callerId||token!==ctxMeta.ownershipToken))throw new SubagentTreeOwnershipError("invalid tree credentials");const meta=readJson<TreeMeta>(join(ctxMeta?.treeDir??"","tree.json"))??(ctxMeta??findTreeMeta(context(options.ctx).sessionDir,treeId));if(!meta||meta.treeId!==treeId||meta.callerId!==callerId||meta.ownershipToken!==token)throw new SubagentTreeOwnershipError("invalid tree credentials");const ownerId=ctxMeta?.ownerId??callerId;if(ownerId!==callerId&&!readJson<NodeRecord>(join(meta.treeDir,"nodes",`${ownerId}.json`)))throw new SubagentTreeOwnershipError("unknown branch owner");const keyValue=stateKey(treeId,ownerId),existing=registry().get(keyValue)??[...registry().values()].find(v=>v.meta.treeId===treeId&&v.meta.callerId===callerId&&v.ownerId===ownerId),freshSession=context(options.ctx).sessionFile,prior=existing?.boundSessionFile??ownerSession(meta,ownerId),initialContext=Boolean(ctxMeta&&!existing),knownSession=meta.acceptedSessionFiles?.[ownerId]?.includes(freshSession)===true;if(!initialContext&&!knownSession&&options.forkLineage===undefined&&header(freshSession)&&prior!==freshSession)throw new SubagentTreeOwnershipError("fork lineage is required for a fork session");const fresh=initialContext||knownSession?freshSession:validateLineage(meta,ownerId,options.ctx,options.forkLineage,prior);if(initialContext){const claimPath=`${contextPath}.claim`;if(!exclusiveAtomic(claimPath,{process:processIdentity(),ownerId,token:randomUUID()}))throw new SubagentTreeOwnershipError("package tree context was already claimed");}const s=existing??makeState(meta,options.pi,options.ctx,ownerId);s.pi=options.pi;s.ctx=options.ctx;s.boundSessionFile=fresh;meta.acceptedSessionFiles??={};meta.acceptedSessionFiles[ownerId]??=[];if(!meta.acceptedSessionFiles[ownerId].includes(fresh))meta.acceptedSessionFiles[ownerId].push(fresh);if(ownerId===callerId){meta.boundSessionFile=fresh;atomic(join(meta.treeDir,"tree.json"),meta);}else{const node=readJson<NodeRecord>(join(meta.treeDir,"nodes",`${ownerId}.json`));if(node){node.sessionFile=fresh;atomic(join(meta.treeDir,"nodes",`${ownerId}.json`),node);}}registry().set(keyValue,s);return expose(s);}
+function deepFreeze<T>(value:T):T{if(!value||typeof value!=="object"||Object.isFrozen(value))return value;for(const child of Object.values(value as Record<string,unknown>))deepFreeze(child);return Object.freeze(value);}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "pi-agent-replicate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.1",
+  "description": "One Pi agent makes copies of itself to work on independent tasks in parallel",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "herdr",
+    "subagents",
+    "agents",
+    "worktrees"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Giuseppe Rodriguez",
+    "url": "https://github.com/giuseppecrj"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexshpunt/pi-agent-replicate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alexshpunt/pi-agent-replicate/issues"
+  },
+  "homepage": "https://github.com/alexshpunt/pi-agent-replicate#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "scripts": {
+    "changelog": "auto-changelog",
+    "lint": "oxlint pi-extension test",
+    "test": "node --experimental-strip-types --test test/replica-directory-settings.test.ts test/replica-shared-work.test.ts test/replica-startup-cleanup.test.ts test/replica-startup-error.test.ts test/reported-launch.test.ts test/session-work-lifecycle.test.ts test/session-work.test.ts test/test.ts test/replication.test.ts test/delayed-output.test.ts test/replica-branch.test.ts test/source-state.test.ts test/replica-work.test.ts test/replica-background.test.ts test/launch.test.ts test/lineage.test.ts test/session-binding.test.ts test/session-binding-reads.test.ts test/runtime-routing.test.ts test/release-workflow.test.ts test/settled-contract.test.ts test/settled-observer.test.ts test/public-subagent-tree-api.test.ts test/package-skill.test.js test/result-file.test.ts test/delivery-payload.test.ts test/status-framing.test.ts test/delivery-log.test.ts test/delivery-truth.test.ts test/sidecar-ack.test.ts test/delivery-uniformity.test.ts test/delivery-recovery.test.ts test/watchdog.test.ts test/delivery-storm.test.ts",
+    "test:integration": "node --experimental-strip-types test/integration/run-isolated.ts",
+    "test:integration:live": "PI_TEST_LIVE=1 node --experimental-strip-types test/integration/run-isolated.ts",
+    "version": "auto-changelog --package && git add CHANGELOG.md"
+  },
+  "auto-changelog": {
+    "commitLimit": false,
+    "template": "keepachangelog",
+    "unreleased": true
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.4 <0.85.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.4 <0.85.0",
+    "@earendil-works/pi-tui": ">=0.84.4 <0.85.0",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./pi-extension/subagents/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/alexshpunt/pi-agent-replicate/main/assets/banner.png"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "@sinclair/typebox": "^0.34.52",
+    "@types/node": "^26.6.4",
+    "auto-changelog": "^2.6.0",
+    "oxlint": "^1.73.0",
+    "typescript": "^7.0.2"
+  }
+}