pi-pstack-native 0.0.0-stage → 1.0.1

package/src/templates/build.ts

@@ -0,0 +1,172 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { resolveRoleModel, resolvePanelSeats, selectJudgeFromPool, suggestedPanels, modelFamily } from '../models/router.ts';
+import { loadModels } from '../runtime/config.ts';
+import type { WorkflowNodeSpec } from '../runtime/types.ts';
+import type { TaskBrief, Budget } from '../contracts/types.ts';
+import { validateBrief } from '../contracts/brief.ts';
+import { validateGraph } from '../workflow/graph.ts';
+import { planArtifacts } from '../workflow/artifacts.ts';
+
+export interface TemplateSpec {
+  kind: 'arena' | 'architect' | 'interrogate' | 'swarm' | 'review' | 'autopilot-stack' | 'autopilot-full';
+  brief: TaskBrief;
+  models?: string[]; panel?: string; judgeModel?: string; rubric?: { criterion: string; weight: number }[];
+  candidateCount?: number; swarmMode?: 'race' | 'partition'; slices?: { key: string; task: string; brief: TaskBrief }[];
+  selectionPolicy?: 'best-of' | 'first-pass' | 'rank-all';
+  judgeMode?: 'cross' | 'per-candidate';
+  independencePolicy?: 'different-model' | 'different-family' | 'explicit-waiver' | 'independent-session';
+  modelFamilies?: Record<string, string>; budget?: Budget;
+}
+
+function panelModels(name: string, ctx?: ExtensionContext, notes: string[] = []): string[] {
+  const models = loadModels().panels?.[name];
+  if ((!Array.isArray(models) || !models.length) && ctx) {
+    const suggested = suggestedPanels(ctx)[name];
+    if (suggested) { notes.push(`Panel ${name} was not configured; using session-available suggested seats: ${suggested.join(', ')}.`); return suggested; }
+  }
+  if (!Array.isArray(models) || !models.length || models.length > 16 || models.some(m => typeof m !== 'string' || !m.trim())) {
+    throw new Error(`PANEL_NOT_CONFIGURED: ${name}. Run /setup-pstack and configure its model seats.`);
+  }
+  return models;
+}
+
+function canonicalModel(selector: string, ctx?: ExtensionContext, notes: string[] = []): string {
+  if (typeof selector !== 'string' || !selector.trim()) throw new Error('EXPLICIT_MODEL_PANEL_REQUIRED');
+  const value = selector.trim();
+  if (!ctx) {
+    if (!value.includes('/') && value !== 'auto' && value !== 'inherit-parent') throw new Error('EXPLICIT_MODEL_PANEL_REQUIRED');
+    return value;
+  }
+  const resolved = resolveRoleModel(ctx, 'panel', value);
+  const { model } = resolved;
+  notes.push(...resolved.notes);
+  if (!model) throw new Error(`PARENT_MODEL_UNAVAILABLE: ${value}`);
+  return `${model.provider}/${model.id}`;
+}
+
+/** Configured panels become explicit node models before a workflow is created. */
+export function buildTemplate(input: TemplateSpec, ctx?: ExtensionContext): {
+  nodes: WorkflowNodeSpec[]; estimatedAgents: number; budget: Budget | undefined;
+  notes: string[]; deliveryContract: 'local-dag' | 'candidate-only' | 'remote-stack-required'; completionPolicy?: 'first-pass';
+} {
+  validateBrief(input.brief);
+  if (input.selectionPolicy && (!['best-of', 'first-pass', 'rank-all'].includes(input.selectionPolicy) || input.kind !== 'swarm' || input.swarmMode !== 'race')) throw new Error('INVALID_SWARM_SELECTION_POLICY');
+  if (input.brief.contractLevel !== 'strict') throw new Error('TEMPLATE_REQUIRES_STRICT_BRIEF');
+  const defaultPanel = input.kind === 'arena' ? 'arena' : input.kind === 'architect' ? 'architect' :
+    input.kind === 'review' || input.kind === 'interrogate' ? 'interrogate' : undefined;
+  const panel = input.panel ?? (!input.models?.length ? defaultPanel : undefined);
+  const config = loadModels();
+  const notes = ['Strict deterministic gates run on each artifact. Fallbacks and failed panels are reported.',
+    'Model cost estimate is unknown until provider usage is available.'];
+  const selectors = panel ? panelModels(panel, ctx, notes) : input.models?.length ? input.models :
+    input.kind === 'swarm' ? [config.workflows?.swarm?.worker ?? config.roles.worker ?? 'inherit-parent'] : undefined;
+  if (!selectors?.length) throw new Error('EXPLICIT_MODEL_PANEL_REQUIRED');
+  const tolerantPanel = Boolean(ctx && ['arena', 'architect', 'interrogate', 'review'].includes(input.kind));
+  const minimum = selectors.length === 1 && ['interrogate', 'review'].includes(input.kind) ? 1 : 2;
+  const models = tolerantPanel ? resolvePanelSeats(ctx!, selectors, minimum, notes) : selectors.map(selector => canonicalModel(selector, ctx, notes));
+  let judgeModel = input.judgeModel ? canonicalModel(input.judgeModel, ctx, notes) : undefined;
+  let policy = input.independencePolicy ?? (['arena', 'architect'].includes(input.kind) ? 'independent-session' : undefined);
+  if (judgeModel && ctx && ['arena', 'architect'].includes(input.kind)) {
+    const parent = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+    if (parent && modelFamily(parent) && (!modelFamily(judgeModel) || modelFamily(parent) === modelFamily(judgeModel))) {
+      notes.push('The requested judge is not known to be from a different family than the parent and was skipped.'); judgeModel = undefined;
+    }
+  }
+  if (!judgeModel && (input.kind === 'arena' || input.kind === 'architect')) {
+    const pool = panelModels('arena-judges', ctx, notes);
+    if (ctx) {
+      const selection = selectJudgeFromPool(ctx, pool);
+      judgeModel = selection.model;
+      notes.push(...selection.notes);
+    } else judgeModel = canonicalModel(pool[0]!);
+    policy ??= 'independent-session';
+    if (judgeModel) notes.push('The configured judge is a separate session.');
+  }
+  if ((input.kind === 'review' || input.kind === 'interrogate') && new Set(models).size < 2) {
+    notes.push('The review panel has fewer than two distinct models; multiple sessions do not establish model diversity.');
+  } else if ((input.kind === 'review' || input.kind === 'interrogate') && new Set(models).size < models.length) {
+    notes.push('Some review seats resolve to the same model; those seats do not add model diversity.');
+  }
+  const node = (key: string, profile: string, task: string, dependsOn: string[] = [], model?: string, brief = input.brief): WorkflowNodeSpec =>
+    ({ key, profile, task, dependsOn, model, brief, isolation: profile === 'worker' || profile === 'adversary' ? 'worktree' : profile === 'integrator' || profile === 'repro-verifier' ? 'shared' : 'readonly' });
+  let nodes: WorkflowNodeSpec[];
+  let candidateOnly = false;
+  if (input.kind === 'interrogate') {
+    const adversaries = models.map((model, i) => node(`adversary-${i + 1}`, 'adversary',
+      'Break the stated change. Run a reproduction for every finding in this isolated copy of the target, including its uncommitted changes. Report the command, observed and expected outputs; do not fix the target.', [], model,
+      { ...input.brief, id: `${input.brief.id}.adversary-${i + 1}`, reportRequirements: { kind: 'repro-review' } }));
+    const verifiers = adversaries.map((a, i) => node(`repro-${i + 1}`, 'repro-verifier',
+      'Independently rerun each reported command in this adversary worktree. Check whether the reproduction changes the reviewed code and whether its output breaks the stated intent. Drop findings that do not reproduce. Report actual commands and output; do not apply fixes.', [a.key], models[(i + 1) % models.length],
+      { ...input.brief, id: `${input.brief.id}.repro-${i + 1}`, reportRequirements: { kind: 'repro-review' } }));
+    nodes = [...adversaries, ...verifiers, node('synthesize', 'synthesizer', 'Compare the independently rerun reports, merge duplicate root causes, and report findings and dropped findings. Do not apply any changes. The coordinator must inspect actual command evidence before calling findings verified.', verifiers.map(n => n.key), judgeModel, { ...input.brief, id: `${input.brief.id}.interrogate-synthesis`, reportRequirements: { kind: 'repro-review' } })];
+    notes.push('Adversaries and separate repro sessions use isolated worktrees. Reports are model statements; the coordinator must inspect command evidence before accepting a finding. No changes are integrated.');
+  } else if (input.kind === 'review') {
+    const reviewers = models.map((model, i) => node(`review-${i + 1}`, 'reviewer',
+      'Review the fixed artifact. Emit findings with evidence locations, severity, reproducible findings, and model identity; do not edit.', [], model,
+      { ...input.brief, id: `${input.brief.id}.review-${i + 1}`, reportRequirements: { kind: 'review' } }));
+    nodes = [...reviewers, node('synthesize', 'synthesizer', 'Deduplicate findings by evidence, preserve minority reproducible findings. Produce severity and unresolved list.', reviewers.map(n => n.key), judgeModel)];
+  } else if (input.kind === 'autopilot-stack' || input.kind === 'autopilot-full' || input.kind === 'swarm' && input.swarmMode === 'partition') {
+    if (!input.slices?.length) throw new Error('SLICES_REQUIRED');
+    const serial = input.kind === 'autopilot-stack';
+    const workers = input.slices.map((slice, i) => {
+      validateBrief(slice.brief);
+      const result = node(slice.key, 'worker', slice.task, serial && i ? [input.slices![i - 1]!.key] : [], models[i % models.length], slice.brief);
+      if (serial && i) result.isolation = 'shared';
+      return result;
+    });
+    nodes = [...workers, node('integrate', 'integrator', 'Integrate every completed slice. Report completed/total coverage and unresolved slices.', workers.map(w => w.key), models[0],
+      { ...input.brief, id: `${input.brief.id}.coverage`, reportRequirements: { kind: 'coverage', slices: workers.map(w => w.key) } }),
+      node('verify', 'verifier', 'Audit integrated artifact and deterministic evidence. Default delivery is dry-run.', ['integrate'], judgeModel)];
+  } else if (input.kind === 'swarm' && input.swarmMode === 'race' && input.selectionPolicy === 'first-pass') {
+    const count = input.candidateCount ?? Math.max(2, models.length);
+    if (!Number.isInteger(count) || count < 2 || count > 16) throw new Error('INDEPENDENT_CANDIDATES_REQUIRED');
+    nodes = Array.from({ length: count }, (_, i) => node(`candidate-${i + 1}`, 'worker', input.brief.goal, [], models[i % models.length], { ...input.brief, id: `${input.brief.id}.candidate-${i + 1}` }));
+    notes.push('First-pass race: the first independently accepted candidate wins; remaining sessions receive cancellation and must settle before completion. No candidate is integrated automatically.');
+  } else {
+    if (input.kind === 'swarm' && input.swarmMode !== 'race') throw new Error('SWARM_MODE_REQUIRED');
+    if (!input.rubric?.length || input.rubric.some(r => !r.criterion || !(r.weight > 0))) throw new Error('RUBRIC_REQUIRED');
+    const count = input.candidateCount ?? (input.kind === 'swarm' ? Math.max(2, models.length) : models.length);
+    if (!Number.isInteger(count) || count < 2 || count > 16) throw new Error('INDEPENDENT_CANDIDATES_REQUIRED');
+    if (!judgeModel && input.kind === 'swarm') throw new Error('INDEPENDENT_JUDGE_REQUIRED');
+    policy ??= 'different-model';
+    if (judgeModel && policy === 'different-model' && models.includes(judgeModel)) throw new Error('JUDGE_NOT_INDEPENDENT');
+    if (judgeModel && policy === 'different-family' && (!input.modelFamilies?.[judgeModel] || models.some(m => !input.modelFamilies?.[m] || input.modelFamilies[m] === input.modelFamilies[judgeModel!]))) throw new Error('MODEL_FAMILY_INDEPENDENCE_UNPROVEN');
+    const goal = input.kind === 'architect' ? `${input.brief.goal}\nProduce a structurally distinct architectural sketch with types, signatures and module boundaries. Use not-implemented bodies and pseudocode; do not implement the final behavior in this phase.` : input.brief.goal;
+    const candidates = Array.from({ length: count }, (_, i) => node(`candidate-${i + 1}`, 'worker', goal, [], models[i % models.length],
+      { ...input.brief, id: `${input.brief.id}.candidate-${i + 1}` }));
+    if (!judgeModel && input.kind !== 'swarm') {
+      nodes = candidates;
+      candidateOnly = true;
+      notes.push('Cross-judge skipped. The coordinator must inspect every candidate, select and integrate the base, and verify the result; this candidate-only plan does not complete the skill.');
+    } else if (input.kind !== 'swarm' && input.judgeMode !== 'per-candidate') {
+      const keys = candidates.map(c => c.key);
+      const judge = node('cross-judge', 'cross-judge', `Inspect every candidate using pstack_candidates. Compare each against the same rubric ${JSON.stringify(input.rubric)} using direct file evidence, select one base, and identify useful parts to integrate.`, keys, judgeModel,
+        { ...input.brief, id: `${input.brief.id}.cross-evaluation`, reportRequirements: { kind: 'cross-evaluation', candidates: keys, criteria: input.rubric.map(r => r.criterion) } });
+      const integrate = node('integrate', 'integrator', 'Read each candidate and independently compare it criterion by criterion. Compare that judgment with the cross-judge, select a base, graft useful parts deliberately, and record the selection, grafts, rejections and dropouts.', [...keys, judge.key], models[0]);
+      const implement = input.kind === 'architect' ? node('implement', 'worker', 'Implement the requested behavior against the selected architectural sketch. Surface deviations from the sketch and run the relevant checks.', ['integrate'], models[0], { ...input.brief, id: `${input.brief.id}.implementation` }) : undefined;
+      if (implement) implement.isolation = 'shared';
+      nodes = [...candidates, judge, integrate, ...(implement ? [implement] : []),
+        node('verify', 'verifier', 'Audit final combined artifact. Candidate passes cannot prove integrated code.', [implement?.key ?? 'integrate'], judgeModel)];
+      if (implement) notes.push('Ground the existing system with how/why before dispatch; the implementation phase follows the selected sketch.');
+      notes.push('One read-only cross-judge can inspect the verified candidate worktrees through confined tools.');
+    } else {
+      const judges = candidates.map(c => node(`judge-${c.key}`, 'reviewer', `Evaluate only this candidate using ${JSON.stringify(input.rubric)}. Emit criterion, score, evidence, weaknesses, selectedParts.`, [c.key], judgeModel,
+        { ...input.brief, id: `${input.brief.id}.${c.key}.evaluation`, reportRequirements: { kind: 'evaluation', criteria: input.rubric!.map(r => r.criterion) } }));
+      if (input.kind === 'swarm' && input.selectionPolicy === 'rank-all') {
+        nodes = [...candidates, ...judges, node('rank', 'synthesizer', 'Rank every candidate against the rubric and explain each rank. Do not integrate or change any candidate.', judges.map(n => n.key), judgeModel,
+          { ...input.brief, id: `${input.brief.id}.ranking`, reportRequirements: { kind: 'ranking', candidates: candidates.map(c => c.key) } })];
+        notes.push('Rank-all returns an ordered comparison without automatically integrating a winner.');
+      } else {
+        nodes = [...candidates, ...judges, node('select', 'synthesizer', 'Select evidence-backed candidate/parts and explain rubric scores.', judges.map(n => n.key), judgeModel,
+          { ...input.brief, id: `${input.brief.id}.selection`, reportRequirements: { kind: 'selection', candidates: candidates.map(c => c.key) } }),
+          node('integrate', 'integrator', 'Integrate only selected parts and rerun deterministic checks.', ['select'], models[0]),
+          node('verify', 'verifier', 'Audit final combined artifact. Candidate passes cannot prove integrated code.', ['integrate'], judgeModel)];
+        notes.push('This template uses per-candidate judge sessions.');
+      }
+    }
+  }
+  validateGraph(nodes);
+  planArtifacts(nodes);
+  if (input.kind === 'autopilot-stack') notes.push('This DAG prepares local work, not a delivered PR stack. Use pstack-runner stack-plan/stack-open with independently verified linear worktree branches.');
+  return { deliveryContract: candidateOnly ? 'candidate-only' : input.kind === 'autopilot-stack' ? 'remote-stack-required' : 'local-dag', ...(input.kind === 'swarm' && input.swarmMode === 'race' && input.selectionPolicy === 'first-pass' ? { completionPolicy: 'first-pass' as const } : {}), nodes, estimatedAgents: nodes.length, budget: input.budget, notes };
+}

package/src/tools/agents.ts

@@ -0,0 +1,62 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentHost } from "../agent/host.ts";
+import { getProfile } from "../agent/profiles.ts";
+import { assertSessionOwner } from "../runtime/ownership.ts";
+import { loadModels } from "../runtime/config.ts";
+import { array, enums, object, string } from "./schema.ts";
+
+const PARAMETERS = object({
+  action: enums(["run", "start", "status", "list", "send", "stop"], "Operation."),
+  evidencePackets: {type:"array",items:{type:"object",additionalProperties:true}},
+  brief: {type:"object",additionalProperties:true},
+  budget: {type:"object",additionalProperties:true},
+  thinkingLevel: enums(["off","minimal","low","medium","high","xhigh","max"]),
+  id: string("Agent id for status/send/stop."),
+  profile: string("Agent profile, e.g. worker, reviewer, verifier, architect."),
+  playbook: string("Optional task or playbook name for configured role-model overrides, e.g. feature or bug-fix."),
+  modelRole: string("Optional named model role within the playbook, e.g. reflect tooling or judgment."),
+  task: string("Assigned task for run/start; message for send when message is omitted."),
+  message: string("Message for send."),
+  model: string("Optional provider/model selector or inherit-parent."),
+  isolation: enums(["shared", "readonly", "worktree"], "Optional isolation override."),
+  cwd: string("Optional working directory. Defaults to current Pi cwd."),
+  ids: array(string(), "Reserved for future batch operations."),
+}) as any;
+
+function reply(value: unknown) { return { content: [{ type: "text" as const, text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }], details: value }; }
+
+export function registerAgentTool(pi: ExtensionAPI, agents: AgentHost): void {
+  pi.registerTool({
+    name: "pstack_agents",
+    label: "Pstack Agents",
+    description: "Run and control Pi-native child AgentSessions. Pass playbook and optional modelRole to apply task-specific model overrides configured by /setup-pstack; an explicit model takes precedence. Background writable starts default to a worktree. Prefer pstack_workflow for parallel writers, integration, and dependency graphs.",
+    promptSnippet: "Launch or inspect Pi-native pstack child agents",
+    parameters: PARAMETERS,
+    executionMode: "sequential",
+    async execute(_id, params: any, _signal, _update, ctx) {
+      const sessionId = ctx.sessionManager.getSessionId();
+      const owned = (id: string) => { const record = agents.get(id); assertSessionOwner(record, sessionId); return record!; };
+      switch (params.action) {
+        case "run": {
+          if (!params.profile || !params.task) throw new Error("run requires profile and task");
+          const routes = params.playbook ? loadModels().workflows?.[params.playbook] : undefined;
+          const model = params.model ?? (params.modelRole ? routes?.[params.modelRole] : undefined) ?? routes?.[params.profile];
+          return reply(await agents.run({ profile: params.profile, task: params.task, cwd: params.cwd || ctx.cwd, isolation: params.isolation, model, evidencePackets:params.evidencePackets,brief:params.brief,budget:params.budget,thinkingLevel:params.thinkingLevel }, ctx));
+        }
+        case "start": {
+          if (!params.profile || !params.task) throw new Error("start requires profile and task");
+          const profile = getProfile(params.profile);
+          const isolation = params.isolation ?? (profile.writable ? "worktree" : profile.defaultIsolation);
+          const routes = params.playbook ? loadModels().workflows?.[params.playbook] : undefined;
+          const model = params.model ?? (params.modelRole ? routes?.[params.modelRole] : undefined) ?? routes?.[params.profile];
+          return reply(agents.start({ profile: params.profile, task: params.task, cwd: params.cwd || ctx.cwd, isolation, model, evidencePackets:params.evidencePackets,brief:params.brief,budget:params.budget,thinkingLevel:params.thinkingLevel }, ctx));
+        }
+        case "status": { if (!params.id) throw new Error("status requires id"); return reply(owned(params.id)); }
+        case "list": return reply(agents.list().filter((a) => a.parentSessionId === sessionId));
+        case "send": { if (!params.id || !(params.message || params.task)) throw new Error("send requires id and message"); owned(params.id); await agents.send(params.id, params.message || params.task); return reply({ ok: true, id: params.id }); }
+        case "stop": { if (!params.id) throw new Error("stop requires id"); owned(params.id); return reply(await agents.stop(params.id)); }
+        default: throw new Error(`Unsupported action: ${params.action}`);
+      }
+    },
+  } as any);
+}

package/src/tools/graph.ts

@@ -0,0 +1,37 @@
+import { upstreamVersion } from "../runtime/upstream.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WorkflowEngine } from "../workflow/engine.ts";
+import { array, enums, number, object, string } from "./schema.ts";
+
+const NODE = object({ evidencePackets:{type:"array",items:{type:"object",additionalProperties:true}}, key: string(), profile: string(), task: string(), model: string(), isolation: enums(["shared","readonly","worktree"]) }, ["key","task"]);
+const EDGE = object({ from: string(), to: string() }, ["from","to"]);
+const PARAMETERS = object({
+  action: enums(["run","start"]), name: string(), nodes: array(NODE), edges: array(EDGE), maxConcurrency: number(undefined,{minimum:1,maximum:16}),
+}, ["action","nodes","edges"]) as any;
+function reply(value: unknown) { return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value }; }
+
+export function registerGraphTool(pi: ExtensionAPI, workflows: WorkflowEngine): void {
+  pi.registerTool({
+    name: "pstack_graph",
+    label: "Pstack Graph",
+    description: "Low-level durable DAG runner. Edges are dependency arrows from prerequisite to dependent node.",
+    parameters: PARAMETERS,
+    executionMode: "sequential",
+    async execute(_id, params: any, _signal, _update, ctx) {
+      const deps = new Map<string,string[]>();
+      for (const node of params.nodes) deps.set(node.key, []);
+      for (const edge of params.edges) {
+        if (!deps.has(edge.to) || !deps.has(edge.from)) throw new Error(`Unknown edge ${edge.from} -> ${edge.to}`);
+        deps.get(edge.to)!.push(edge.from);
+      }
+      const record = workflows.create({
+        name: params.name,
+        type: "graph",
+        nodes: params.nodes.map((node: any) => ({ ...node, dependsOn: deps.get(node.key) })),
+        maxConcurrency: params.maxConcurrency,
+        parentSessionId: ctx.sessionManager.getSessionId(), cwd: ctx.cwd, pstackVersion: upstreamVersion(),
+      });
+      return reply(params.action === "run" ? await workflows.run(record.id, ctx) : workflows.start(record.id, ctx));
+    },
+  } as any);
+}

package/src/tools/protocol.ts

@@ -0,0 +1,53 @@
+import { assertGitHubRepository } from "../delivery/git.ts";
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { WorkflowEngine } from '../workflow/engine.ts';
+import { assertSessionOwner } from '../runtime/ownership.ts';
+import { object, string, enums, array, number } from './schema.ts';
+import { verify } from '../verification/runner.ts';
+import { fingerprint } from '../artifacts/fingerprint.ts';
+import { ownerOf } from '../artifacts/fingerprint.ts';
+import { protocol, hash } from '../runtime/protocol.ts';
+import { contextSnapshot } from '../context/snapshot.ts';
+import { GitHubCLI } from '../delivery/provider.ts';
+import { refresh, eligibility, watchFrontier } from '../delivery/frontier.ts';
+import { ProgramCoordinator } from '../program/coordinator.ts';
+const reply=(value:unknown)=>({content:[{type:'text' as const,text:JSON.stringify(value,null,2)}],details:value});
+export function registerProtocolTools(pi:ExtensionAPI,engine:WorkflowEngine):void {
+  const owned=(id:string,ctx:any)=>{const w=engine.get(id);assertSessionOwner(w,ctx.sessionManager.getSessionId());return w!;};
+  pi.registerTool({name:'pstack_verify',label:'Pstack Verification',description:'Inspect current repository fingerprint or run the persisted deterministic gates for a workflow call. Command permissions come from operator verification-policy.json, never from agent text.',parameters:object({action:enums(['fingerprint','run','run-pr','ledger','contract','revise']),id:string(),key:string(),brief:{type:'object',additionalProperties:true},reason:string(),repo:string(),number:number()},['action']),executionMode:'sequential',async execute(_id,p:any,_signal,_update,ctx){
+    if(p.action==='fingerprint')return reply(fingerprint(ctx.cwd));
+    const w=owned(p.id,ctx);const c=w.calls[p.key];if(!c)throw new Error('Unknown call');
+    if(p.action==='contract')return reply(c.brief ?? {contractLevel:'legacy',verification:'unknown'});
+    if(p.action==='revise')return reply(engine.reviseBrief(w.id,c.key,p.brief,'coordinator',p.reason));
+    if(p.action==='ledger') {const l=c.verification?.ledgerId?protocol().ledgers[c.verification.ledgerId]:undefined;return reply({ledger:l ?? null,current:engine.accepted(c),verification:c.verification ?? 'unknown'});}
+    if(!c.brief || c.state!=='completed' || !c.cwd)throw new Error('Completed call with brief and artifact cwd required');
+    const agent=c.agentId ? (await import('../runtime/store.ts')).readJson<any>((await import('../runtime/home.ts')).agentPath(c.agentId),undefined):undefined;
+    if(!agent)throw new Error('Agent artifact record missing');
+    if(p.action==='run-pr') {
+      assertGitHubRepository(c.cwd,p.repo);
+      const actual=await new GitHubCLI().read(p.repo,p.number);const current=fingerprint(c.cwd,'committed');
+      if(actual.headSha!==current.commitSha || actual.state!=='OPEN')throw new Error('PR_HEAD_MISMATCH');
+      return reply(await verify(c.cwd,c.brief,{before:agent.baseline,owner:ownerOf(c.brief,{workflowId:w.id,callKey:c.key}),report:agent.report,pr:{repoId:current.repoId,number:p.number,headSha:actual.headSha},signal:_signal}));
+    }
+    await engine.verifyCall(w.id,c.key,agent);return reply(engine.get(w.id)?.calls[c.key]);
+  }} as any);
+  pi.registerTool({name:'pstack_delivery',label:'Pstack Delivery Plan',description:'Read live GitHub PR stack state and return deterministic shipping blockers. The operator must name the trusted rootBase; it is never taken from the PRs under review. This tool never merges; authorized merge is a human CLI operation.',parameters:object({id:string(),repo:string(),numbers:array(number()),rootBase:string(),requireReview:{type:'boolean'},requireBehavior:{type:'boolean'}},['id','repo','numbers','rootBase']),executionMode:'sequential',async execute(_id,p:any,_signal,_update,ctx){
+    assertGitHubRepository(ctx.cwd,p.repo);
+    const f=await refresh({...p,repoId:fingerprint(ctx.cwd).repoId,owner:ctx.sessionManager.getSessionId()},new GitHubCLI());return reply({frontier:f,decisions:eligibility(f),watch:watchFrontier(f),dryRun:true});
+  }} as any);
+  pi.registerTool({name:'pstack_context',label:'Pstack Context Snapshot',description:'Rebuild authoritative handoff and current evidence status from durable records.',parameters:object({}),async execute(_id,_p,_signal,_update,ctx){return reply(contextSnapshot(engine,ctx.sessionManager.getSessionId()));}} as any);
+  const coordinator=new ProgramCoordinator(engine);
+  pi.registerTool({name:'pstack_program',label:'Pstack Program',description:'Create, run, drain, pause and close strict unit programs with a pilot and rolling concurrency. Close checks every unit and its current evidence.',parameters:object({action:enums(['create','run','status','drain','pause','resume','orders','close']),id:string(),units:array({type:'object',additionalProperties:true}),maxConcurrency:number(),standingOrders:array(string()),reason:string()},['action']),executionMode:'sequential',async execute(_id,p:any,_signal,_update,ctx){
+    const owner=ctx.sessionManager.getSessionId();
+    if(p.action==='create')return reply(coordinator.create(owner,(p.units ?? []).map((u:any)=>({...u,spec:{...u.spec,cwd:ctx.cwd,parentSessionId:owner}})),p.maxConcurrency));
+    if(p.action==='run')return reply(await coordinator.run(p.id,ctx));
+    if(p.action==='status')return reply(coordinator.get(p.id,owner));
+    if(p.action==='resume'){coordinator.resume(p.id,owner);return reply(await coordinator.run(p.id,ctx));}
+    if(p.action==='orders')return reply(coordinator.updateOrders(p.id,owner,p.standingOrders,p.reason));
+    if(p.action==='drain')return reply(coordinator.drain(p.id,owner));
+    if(p.action==='pause')return reply(coordinator.pause(p.id,owner));
+    return reply(coordinator.close(p.id,owner));
+  }} as any);
+  for(const [name,action] of [['pstack-contract','contract'],['pstack-ledger','ledger']] as const)pi.registerCommand(name,{description:`Show ${action} for WORKFLOW KEY`,handler:async(args,ctx)=>{const [id,key]=args.trim().split(/\s+/);const w=owned(id,ctx);const c=w.calls[key];if(!c)throw new Error('Unknown call');ctx.ui.notify(JSON.stringify(action==='contract'?c.brief:{...c.verification,current:engine.accepted(c)},null,2),'info');}});
+  pi.registerCommand('pstack-handoff',{description:'Reconstruct durable context index',handler:async(_args,ctx)=>{ctx.ui.notify(JSON.stringify(contextSnapshot(engine,ctx.sessionManager.getSessionId()),null,2),'info');}});
+}

package/src/tools/schema.ts

@@ -0,0 +1,9 @@
+// Pi accepts ordinary JSON Schema objects in addition to TypeBox-tagged schemas.
+// Keeping schemas here avoids a runtime dependency on typebox.
+export type JsonSchema = Record<string, unknown>;
+export const string = (description?: string, extra: Record<string, unknown> = {}): JsonSchema => ({ type: "string", ...(description ? { description } : {}), ...extra });
+export const boolean = (description?: string): JsonSchema => ({ type: "boolean", ...(description ? { description } : {}) });
+export const number = (description?: string, extra: Record<string, unknown> = {}): JsonSchema => ({ type: "number", ...(description ? { description } : {}), ...extra });
+export const array = (items: JsonSchema, description?: string): JsonSchema => ({ type: "array", items, ...(description ? { description } : {}) });
+export const object = (properties: Record<string, JsonSchema>, required: string[] = [], extra: Record<string, unknown> = {}): JsonSchema => ({ type: "object", properties, required, additionalProperties: false, ...extra });
+export const enums = (values: string[], description?: string): JsonSchema => ({ type: "string", enum: values, ...(description ? { description } : {}) });

package/src/tools/workflow.ts

@@ -0,0 +1,103 @@
+import { upstreamVersion } from "../runtime/upstream.ts";
+import { buildTemplate } from "../templates/build.ts";
+import { validateBrief } from "../contracts/brief.ts";
+import { validateGraph, dependencyEdges } from "../workflow/graph.ts";
+import { planArtifacts } from "../workflow/artifacts.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WorkflowEngine } from "../workflow/engine.ts";
+import { chainNodes } from "../workflow/graph.ts";
+import { loadModels } from "../runtime/config.ts";
+import { assertSessionOwner } from "../runtime/ownership.ts";
+import { array, enums, number, object, string } from "./schema.ts";
+
+const NODE = object({
+  evidencePackets: {type:"array",items:{type:"object",additionalProperties:true}},
+  brief: { type: "object", additionalProperties: true },
+  thinkingLevel: enums(["off","minimal","low","medium","high","xhigh","max"]),
+  budget: {type:"object",additionalProperties:true},
+  key: string("Unique call key."),
+  profile: string("Agent profile. Defaults to worker."),
+  task: string("Task for this node."),
+  dependsOn: array(string(), "Keys that must complete first."),
+  model: string("Optional model selector."),
+  modelRole: string("Optional named model role within the playbook."),
+  isolation: enums(["shared", "readonly", "worktree"]),
+}, ["key", "task"]);
+const PARAMETERS = object({
+  action: enums(["plan", "run", "start", "status", "list", "pause", "resume", "cancel", "retry"], "Operation."),
+  template: {type:"object",additionalProperties:true},
+  contractLevel: enums(["minimal","strict"]),
+  budget: {type:"object",additionalProperties:true},
+  dryRun: {type:"boolean"},
+  id: string("Workflow id."),
+  key: string("Call key for retry."),
+  name: string("Human-readable workflow name."),
+  playbook: string("Optional task or playbook name for configured role-model overrides, such as feature or bug-fix."),
+  skill: string("Optional originating pstack skill."),
+  mode: enums(["graph", "parallel", "chain", "swarm", "arena", "architect", "interrogate", "orchestrate", "review"], "Workflow mode."),
+  nodes: array(NODE, "Workflow nodes."),
+  maxConcurrency: number("Shared concurrency limit.", { minimum: 1, maximum: 16 }),
+}) as any;
+
+function reply(value: unknown) { return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value }; }
+function normalizedNodes(mode: string | undefined, nodes: any[]): any[] {
+  if (mode === "chain") return chainNodes(nodes.map(({ dependsOn: _d, ...node }) => node));
+  if (mode === "parallel") return nodes.map((node) => ({ ...node, dependsOn: [] }));
+  return nodes;
+}
+
+export function registerWorkflowTool(pi: ExtensionAPI, workflows: WorkflowEngine): void {
+  pi.registerTool({
+    name: "pstack_workflow",
+    label: "Pstack Workflow",
+    description: "Run durable Pi-native dependency graphs. Pass playbook and optional node modelRole for task-specific routing. Arena, architect and interrogate load configured or suggested panels. With no eligible cross-judge, arena/architect return candidates for the coordinator to compare, integrate and verify. Interrogate uses isolated adversaries and separate repro sessions; inspect actual evidence. Swarm races support first-pass and rank-all selection. Each template needs a strict brief; arena/architect also need a rubric. Plan first to inspect models, nodes and fallback notes.",
+    promptSnippet: "Run durable pstack multi-agent workflows",
+    parameters: PARAMETERS,
+    executionMode: "sequential",
+    async execute(_id, params: any, _signal, _update, ctx) {
+      const sessionId = ctx.sessionManager.getSessionId();
+      const owned = (id: string) => { const record = workflows.get(id); assertSessionOwner(record, sessionId); return record!; };
+      switch (params.action) {
+        case "plan":
+        case "run":
+        case "start": {
+          let plan: ReturnType<typeof buildTemplate> | undefined;
+          if (params.template) {
+            plan=buildTemplate(params.template,ctx);params.nodes=plan.nodes;
+            params.mode=params.template.kind.startsWith("autopilot")?"graph":params.template.kind === "interrogate"?"review":params.template.kind === "architect"?"arena":params.template.kind;
+            params.budget=params.budget ?? plan.budget;
+          }
+          else if (["arena","architect","interrogate","swarm","review"].includes(params.mode)) throw new Error("SPECIALIZED_MODE_REQUIRES_TEMPLATE");
+          if (!Array.isArray(params.nodes) || !params.nodes.length) throw new Error(`${params.action} requires nodes`);
+          const overrides = loadModels().workflows?.[params.playbook ?? params.mode ?? "graph"];
+          const nodes=normalizedNodes(params.mode,params.nodes).map(node => ({ ...node, model: node.model ?? (node.modelRole ? overrides?.[node.modelRole] : undefined) ?? overrides?.[node.profile ?? "worker"] }));
+          validateGraph(nodes);planArtifacts(nodes);
+          for(const n of nodes) {if(params.contractLevel==="strict" && !n.brief)throw new Error("BRIEF_INCOMPLETE");if(n.brief)validateBrief(n.brief);}
+          if(params.action==="plan" || params.dryRun) return reply({nodes,edges:dependencyEdges(nodes),plan,budget:params.budget ?? null,dryRun:true});
+          const record = workflows.create({
+            name: params.name,
+            deliveryContract: plan?.deliveryContract,
+            completionPolicy: plan?.completionPolicy,
+            modelNotes: plan?.notes,
+            type: params.mode || "graph",
+            playbook: params.playbook,
+            skill: params.skill,
+            nodes, contractLevel: params.contractLevel, budget:params.budget,
+            maxConcurrency: params.maxConcurrency,
+            parentSessionId: ctx.sessionManager.getSessionId(),
+            cwd: ctx.cwd,
+            pstackVersion: upstreamVersion(),
+          });
+          return reply(params.action === "run" ? await workflows.run(record.id, ctx) : workflows.start(record.id, ctx));
+        }
+        case "status": { if (!params.id) throw new Error("status requires id"); const w=owned(params.id);return reply({...w,currentAcceptance:Object.fromEntries(Object.values(w.calls).map((c:any)=>[c.key,c.brief?workflows.accepted(c):"unknown"]))}); }
+        case "list": return reply(workflows.list(ctx.sessionManager.getSessionId()));
+        case "pause": { if (!params.id) throw new Error("pause requires id"); owned(params.id); return reply(workflows.pause(params.id)); }
+        case "resume": { if (!params.id) throw new Error("resume requires id"); owned(params.id); return reply(workflows.resume(params.id, ctx)); }
+        case "cancel": { if (!params.id) throw new Error("cancel requires id"); owned(params.id); return reply(await workflows.cancel(params.id)); }
+        case "retry": { if (!params.id || !params.key) throw new Error("retry requires id and key"); owned(params.id); const next = workflows.retry(params.id, params.key); workflows.start(params.id, ctx); return reply(next); }
+        default: throw new Error(`Unsupported action: ${params.action}`);
+      }
+    },
+  } as any);
+}

package/src/tools/worktrees.ts

@@ -0,0 +1,39 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentHost } from "../agent/host.ts";
+import { enums, object, string } from "./schema.ts";
+import { assertSessionOwner } from "../runtime/ownership.ts";
+
+const PARAMETERS = object({
+  action: enums(["list", "cleanup"], "Operation."),
+  id: string("Agent id that owns the worktree."),
+}, ["action"]) as any;
+
+function reply(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }], details: value };
+}
+
+export function registerWorktreeTool(pi: ExtensionAPI, agents: AgentHost): void {
+  pi.registerTool({
+    name: "pstack_worktrees",
+    label: "Pstack Worktrees",
+    description: "List runtime-owned Git worktrees or safely clean one by agent id. Cleanup refuses dirty worktrees.",
+    promptSnippet: "Inspect or clean pstack-owned worktrees",
+    parameters: PARAMETERS,
+    executionMode: "sequential",
+    async execute(_id, params: any, _signal, _update, ctx) {
+      const sessionId = ctx.sessionManager.getSessionId();
+      if (params.action === "list") {
+        return reply(agents.list().filter((a) => a.worktree && a.parentSessionId === sessionId).map((a) => ({
+          agentId: a.id, workflowId: a.workflowId, callKey: a.callKey, state: a.state,
+          path: a.worktree, branch: a.branch, repoRoot: a.worktreeRepoRoot, baseRef: a.worktreeBaseRef,
+        })));
+      }
+      if (params.action === "cleanup") {
+        if (!params.id) throw new Error("cleanup requires id");
+        assertSessionOwner(agents.get(params.id), sessionId);
+        return reply(await agents.cleanupWorktree(params.id));
+      }
+      throw new Error(`Unsupported action: ${params.action}`);
+    },
+  } as any);
+}

package/src/verification/process.mjs

@@ -0,0 +1,9 @@
+// A small supervisor keeps command lifetime tied to the runner's pipe and timeout.
+import { spawn } from 'node:child_process';
+const [timeoutText, executable, ...args]=process.argv.slice(2);
+const child=spawn(executable,args,{shell:false,stdio:['ignore','inherit','inherit'],env:process.env});
+const terminate=()=>{try{if(process.platform!=='win32')process.kill(-process.pid,'SIGKILL');else child.kill('SIGKILL');}catch{};process.exit(124);};
+const timer=setTimeout(terminate,Number(timeoutText));
+process.stdin.resume();process.stdin.on('end',terminate);
+child.on('error',error=>{clearTimeout(timer);process.stderr.write(error.message);process.exit(127);});
+child.on('exit',(code,signal)=>{clearTimeout(timer);process.exit(code ?? (signal?125:0));});