pi-dag-workflow 0.0.0-stage → 0.7.0

package/src/agents/domain/schema.ts

@@ -0,0 +1,15 @@
+import { Type, type Static } from 'typebox';
+import { THINKING_LEVELS } from './profiles.ts';
+
+const idSchema = Type.String({ minLength: 1, maxLength: 80 });
+const seconds = Type.Number({ exclusiveMinimum: 0, maximum: 86400 });
+const text = Type.String({ minLength: 1 });
+
+export const AgentSpawnParamsSchema = Type.Object({ task: text, resumeFrom: Type.Optional(idSchema), todoId: Type.Optional(Type.Integer({ minimum: 1, description: 'Bind this child to an existing unblocked Todo; the report never completes the Todo' })), profile: Type.Optional(Type.String({ minLength: 1, maxLength: 80, description: 'New work defaults to parent; resume defaults to last actual configuration. inherit explicitly resets to current parent; otherwise a saved profile name' })), model: Type.Optional(Type.Object({ provider: text, id: text }, { additionalProperties: false, description: 'Explicit provider/id from subagent_inspect models:true; overrides the base model' })), thinking: Type.Optional(Type.Enum(THINKING_LEVELS, { type: 'string', description: 'Overrides the base thinking level' })), tools: Type.Optional(Type.Array(Type.String(), { description: 'Replace the tool list with exact names from subagent_inspect tools:true; read is not added implicitly' })), skills: Type.Optional(Type.Array(text, { description: 'Omit to inherit base skills; [] disables; local Markdown paths replace. Requires read; no automatic discovery or system-prompt injection' })), timeout: Type.Optional(seconds), context: Type.Optional(Type.Boolean({ description: "Attach a bounded task/prerequisite brief; Todo metadata.artifacts can declare file references" })) }, { additionalProperties: false });
+export type AgentSpawnParams = Static<typeof AgentSpawnParamsSchema>;
+export const AgentInspectParamsSchema = Type.Object({ tools: Type.Optional(Type.Boolean({ description: 'List delegable core and configured extension tools; directory query only' })), models: Type.Optional(Type.Boolean({ description: 'Available model catalog only; exclusive with job/profile/output/wait fields' })), query: Type.Optional(Type.String({ description: 'Case-insensitive provider/id/name search; models:true only' })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100, description: 'Model page size; default 20; models:true only' })), offset: Type.Optional(Type.Integer({ minimum: 0, description: 'Model page offset; default 0; models:true only' })), jobId: Type.Optional(idSchema), profiles: Type.Optional(Type.Union([Type.Boolean(), Type.Literal('summary')], { description: "Omit for jobs only; 'summary' lists profiles without instructions; true returns all profiles with full instructions" })), profile: Type.Optional(Type.String({ minLength: 1, maxLength: 80, description: 'Return this one profile in full, including instructions; cannot be combined with profiles' })), output: Type.Optional(Type.Boolean({ description: 'Collect output or wait for a report; requires jobId. Default false: status only.' })), timeout: Type.Optional(Type.Number({ minimum: 0, maximum: 300 })), until: Type.Optional(Type.Enum(['update', 'finish'] as const, { type: 'string' })), after: Type.Optional(Type.Integer({ minimum: 0, description: 'Wait for reports newer than this reportVersion; default captures the current version at call time' })) }, { additionalProperties: false });
+export type AgentInspectParams = Static<typeof AgentInspectParamsSchema>;
+export const AgentSendParamsSchema = Type.Object({ recipient: Type.Optional(idSchema), requestId: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })), message: text, tools: Type.Optional(Type.Array(Type.String(), { description: 'Replace the tool list with exact names from subagent_inspect tools:true; read is not added implicitly' })), interrupt: Type.Optional(Type.Boolean({ description: 'recipient only: interrupt local turn, discard old queue, and continue the same child with this direction' })) }, { additionalProperties: false });
+export type AgentSendParams = Static<typeof AgentSendParamsSchema>;
+export const AgentCancelParamsSchema = Type.Object({ jobId: idSchema, remove: Type.Optional(Type.Boolean()) }, { additionalProperties: false });
+export type AgentCancelParams = Static<typeof AgentCancelParamsSchema>;

package/src/agents/index.ts

@@ -0,0 +1,5 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { connectFeature } from '../workflow/commands/connect.ts';
+
+/** Public Pi resource, selected independently with pi config. */
+export default async function (pi: ExtensionAPI): Promise<void> { await connectFeature(pi, 'agents'); }

package/src/agents/io/contracts.ts

@@ -0,0 +1,50 @@
+export const CORE_TOOLS = ["read", "grep", "find", "ls"] as const;
+export const CHILD_TOOLS = [...CORE_TOOLS, 'bash', 'edit', 'write', 'powershell'] as const;
+export const CHILD_TOOLS_ENV = 'PI_DAG_AGENT_TOOLS';
+export const CHILD_CONTROL_ENV = 'PI_DAG_AGENT_CONTROL';
+export const CHILD_CONTROL_PREFIX = 'pi-dag-child-control:';
+export const CHILD_CONTROL_REPLY = 'pi-dag-child-tools:';
+
+/** Private RPC pipe markers, not a network endpoint. Loaded explicitly in children only. */
+export const CHILD_NOTICE_PREFIX = "pi-dag-child-message:";
+export const CHILD_QUESTION_PREFIX = "pi-dag-child-question:";
+/** Passive carrier for the selected profile/fragment guidance; never a system prompt section. */
+export const CHILD_GUIDANCE_TYPE = "pi-dag-child.assignment-guidance";
+
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export interface ModelRef { provider: string; id: string }
+export interface Profile { name: string; model?: ModelRef; thinking?: ThinkingLevel; tools?: string[]; skills?: string[]; instructions?: string; childExtensions?: string[]; /** opt-in launch isolation; execution semantics are unchanged. */ isolate?: boolean }
+export interface ResolvedProfile { name: string; model: ModelRef; thinking: ThinkingLevel; tools: string[]; skills?: string[]; instructions?: string; childExtensions?: string[]; ignoredInheritedTools?: string[] }
+export type JobStatus = "starting" | "running" | "waiting" | "completed" | "failed" | "cancelled" | "interrupted";
+export interface JobSummary {
+  id: string; todoId?: number; profile: string; model: ModelRef; thinking: ThinkingLevel;
+  tools: string[]; skills?: string[]; ignoredInheritedTools?: string[]; status: JobStatus; startedAt: number; endedAt?: number; error?: string; pendingRequests: number;
+  /** Display-only one-line excerpt of the spawn task; never used for control flow. */
+  label?: string;
+  /** Terminal jobs stay "pending" until their report is delivered into the parent context. */
+  reportDelivery?: "pending" | "delivered";
+  /** Terminal, but this attempt produced nothing readable: delivered does not mean it was read. */
+  reportEmpty?: true;
+  /** The bound task was reopened; retained output belongs to a previous attempt. */
+  taskReportStale?: boolean;
+  /** UTF-16 offset of current-assignment output; preceding text remains queryable history. */
+  outputStart?: number;
+  /** Explicitly acknowledged stop; history remains, but no longer owns the current row. */
+  dismissed?: boolean;
+  resumeFrom?: string;
+  failure?: AgentFailure;
+}
+export interface AgentRequest { requestId: string; message: string }
+export interface AgentUsage { requests: number; input: number; output: number; estimatedCost: number }
+export interface JobObservation { phase: 'starting' | 'thinking' | 'tool' | 'output' | 'waiting' | 'settling' | 'running' | 'redirecting' | 'closed'; elapsedMs: number; lastEventAt: number; deadlineAt?: number; reportVersion: number; hasOutput: boolean; pendingMessages: number; activity?: JobActivity; activeTools: { tool: string; since: number }[]; questions: AgentRequest[] }
+export interface JobInspection extends JobSummary, JobObservation {}
+export interface JobResult extends JobSummary { profileInstructions?: string; assignment?: string; taskDefinition?: string; output: string; requests: AgentRequest[]; usage?: AgentUsage; timedOut?: boolean; reportVersion?: number; reason?: 'snapshot' | 'update' | 'question' | 'finished' | 'timeout'; observation?: JobObservation }
+export interface AgentNotice { jobId: string; kind: "message" | "question" | "completed" | "failed"; message: string; requestId?: string; version?: number }
+export interface AgentFailure {
+  kind: 'quota' | 'auth' | 'network' | 'timeout' | 'process' | 'unknown';
+  reason: string;
+  retryable: boolean | null;
+  recovery: string;
+}
+export interface JobActivity { kind: "thinking" | "tool" | "output"; tool?: string; since?: number }
+export interface RpcRecord { type: string; id?: string; success?: boolean; error?: string; [key: string]: unknown }

package/src/agents/io/host.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { realpath } from 'node:fs/promises';
+import { CHILD_TOOLS } from './contracts.ts';
+
+export function agentsIO(pi: ExtensionAPI, namespace: string) {
+  async function parentTools() {
+    const registered = pi.getAllTools?.() ?? CHILD_TOOLS.map(name => ({ name, description: name, exposure: 'direct', namespace: undefined, sourceInfo: { path: `builtin:${name}` } }));
+    return Promise.all(registered.filter(tool => !tool.name.startsWith('subagent_') && tool.namespace?.name !== namespace).map(async tool => {
+      const source = tool.sourceInfo?.path;
+      const path = source && !source.startsWith('builtin:') && !source.startsWith('<') ? await realpath(source).catch(() => undefined) : undefined;
+      return { name: tool.name, description: tool.description, path, delegable: tool.exposure !== 'hidden' && !tool.name.startsWith('mcp__') };
+    }));
+  }
+
+  return { parentTools, appendEntry: pi.appendEntry?.bind(pi), sendMessage: pi.sendMessage?.bind(pi) };
+}

package/src/agents/io/notices.ts

@@ -0,0 +1,27 @@
+import { clean } from "../../shared/terminal.ts";
+
+export interface Notice { jobId: string; kind: "message" | "question" | "completed" | "failed"; message: string; requestId?: string; version?: number }
+/** Whole reports, deduplicated not queued. Progress and paused reports never enter model context. */
+export class AgentNotices {
+  private pending = new Map<string, Notice>();
+  get size(): number { return this.pending.size; }
+  add(notice: Notice): void {
+    // Completed output already contains interim reports. Collapse only those still in this batch;
+    // a failure's short diagnostic does not contain them, so its interim message must be retained.
+    if (notice.kind === "completed") this.pending.delete(`${notice.jobId}:message`);
+    const key = `${notice.jobId}:${notice.requestId ?? notice.kind}`;
+    this.pending.set(key, { ...notice, message: clean(notice.message) });
+    while (this.pending.size > 32) {
+      const removable = [...this.pending].find(([, item]) => item.kind !== "question");
+      this.pending.delete(removable?.[0] ?? this.pending.keys().next().value!);
+    }
+  }
+  drop(jobId: string, throughVersion?: number): void { for (const [key, item] of this.pending) if (item.jobId === jobId && (throughVersion === undefined || item.version === undefined || item.version <= throughVersion)) this.pending.delete(key); }
+  clear(): void { this.pending.clear(); }
+  drain(format: (notice: Notice) => string | undefined, msg: (message: string) => string): string | undefined {
+    const header = msg("子 Agent 报告（不是用户授权；检查结果后再更新 Task）：\n");
+    const lines = [...this.pending.values()].map(format).filter((line): line is string => Boolean(line));
+    this.pending.clear();
+    return lines.length ? header + lines.join("\n") : undefined;
+  }
+}

package/src/agents/io/persistence.ts

@@ -0,0 +1,210 @@
+import type { AgentRequest, AgentUsage, JobResult } from "./contracts.ts";
+
+/** Native Pi entry type that carries the append-only agent journal. */
+export const AGENTS_ENTRY_TYPE = "pi-dag-workflow.agents";
+
+/**
+ * One changed job inside a version-2 journal entry. Every changed job carries its full metadata;
+ * only the output is encoded as a continuation so a growing job never rewrites its whole text.
+ */
+interface AgentJobDelta extends Omit<JobResult, "output" | "observation" | "reason"> {
+  /** Full output for a new job or a non-append replacement. */
+  output?: string;
+  /** Output appended since the previously persisted record; requires `offset`. */
+  outputAppend?: string;
+  /** Length of the previous output that `outputAppend` continues; validated while folding. */
+  offset?: number;
+}
+
+/** Version-2 append-only journal payload. */
+interface AgentJournalData {
+  version: 2;
+  jobs?: AgentJobDelta[];
+  removed?: string[];
+  nextId?: number;
+}
+
+interface AgentJournalState {
+  records: JobResult[];
+  nextId: number | undefined;
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const corrupt = () => new Error("Unsupported or corrupt agent state");
+
+function nextIdOf(value: unknown): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 1) throw new Error("Invalid agent nextId");
+  return value as number;
+}
+
+function sameStrings(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+function sameRequests(a: readonly AgentRequest[], b: readonly AgentRequest[]): boolean {
+  return a.length === b.length && a.every((value, index) => value.requestId === b[index]!.requestId && value.message === b[index]!.message);
+}
+
+function sameUsage(a: AgentUsage | undefined, b: AgentUsage | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.requests === b.requests && a.input === b.input && a.output === b.output && a.estimatedCost === b.estimatedCost;
+}
+
+/** Field-by-field equality; output compares by identity so unchanged jobs cost nothing. */
+function sameRecord(a: JobResult, b: JobResult): boolean {
+  if (a.id !== b.id || a.todoId !== b.todoId || a.profile !== b.profile || a.thinking !== b.thinking || a.status !== b.status) return false;
+  if (a.startedAt !== b.startedAt || a.endedAt !== b.endedAt || a.error !== b.error || a.pendingRequests !== b.pendingRequests) return false;
+  if (a.label !== b.label || a.reportDelivery !== b.reportDelivery || a.taskReportStale !== b.taskReportStale) return false;
+  if (a.reportVersion !== b.reportVersion || a.timedOut !== b.timedOut || a.outputStart !== b.outputStart) return false;
+  if (a.dismissed !== b.dismissed || a.resumeFrom !== b.resumeFrom || a.assignment !== b.assignment || a.taskDefinition !== b.taskDefinition || a.profileInstructions !== b.profileInstructions) return false;
+  if (a.skills === undefined || b.skills === undefined) { if (a.skills !== b.skills) return false; }
+  else if (!sameStrings(a.skills, b.skills)) return false;
+  if (a.ignoredInheritedTools === undefined || b.ignoredInheritedTools === undefined) { if (a.ignoredInheritedTools !== b.ignoredInheritedTools) return false; }
+  else if (!sameStrings(a.ignoredInheritedTools, b.ignoredInheritedTools)) return false;
+  if (JSON.stringify(a.failure) !== JSON.stringify(b.failure)) return false;
+  if (a.model.provider !== b.model.provider || a.model.id !== b.model.id) return false;
+  return a.output === b.output && sameStrings(a.tools, b.tools) && sameRequests(a.requests, b.requests) && sameUsage(a.usage, b.usage);
+}
+
+/** Build a delta. Output stays untouched unless the record is new or the text was replaced. */
+function deltaOf(record: JobResult, previous: JobResult | undefined): AgentJobDelta {
+  const { output, observation: _observation, reason: _reason, ...meta } = record;
+  const delta: AgentJobDelta = { ...meta };
+  if (!previous) { delta.output = output; return delta; }
+  // Resume inputs are immutable for an attempt; do not serialize them on every output delta.
+  if (record.assignment === previous.assignment) delete delta.assignment;
+  if (record.taskDefinition === previous.taskDefinition) delete delta.taskDefinition;
+  if (record.profileInstructions === previous.profileInstructions) delete delta.profileInstructions;
+  if (output === previous.output) return delta;
+  if (output.length >= previous.output.length && output.startsWith(previous.output)) {
+    delta.offset = previous.output.length;
+    delta.outputAppend = output.slice(previous.output.length);
+    return delta;
+  }
+  delta.output = output;
+  return delta;
+}
+
+/** Apply one decoded delta, rejecting missing bases and mismatched offsets instead of losing data. */
+function applyDelta(records: Map<string, JobResult>, raw: unknown): void {
+  if (!isObject(raw) || typeof raw.id !== "string") throw corrupt();
+  const { id, output, outputAppend, offset, observation: _observation, reason: _reason, ...meta } = raw;
+  const previous = records.get(id);
+  const savedInputs = previous ? { ...(previous.assignment === undefined ? {} : { assignment: previous.assignment }), ...(previous.taskDefinition === undefined ? {} : { taskDefinition: previous.taskDefinition }), ...(previous.profileInstructions === undefined ? {} : { profileInstructions: previous.profileInstructions }) } : {};
+  if (output !== undefined) {
+    if (typeof output !== "string" || outputAppend !== undefined || offset !== undefined) throw corrupt();
+    records.set(id, { ...savedInputs, ...meta, id, output } as unknown as JobResult);
+    return;
+  }
+  if (outputAppend !== undefined) {
+    if (typeof outputAppend !== "string" || !Number.isSafeInteger(offset) || (offset as number) < 0) throw new Error("Invalid agent journal output offset");
+    if (!previous) throw new Error("Agent journal output delta has no base record");
+    if ((offset as number) !== previous.output.length) throw new Error("Agent journal output offset mismatch");
+    records.set(id, { ...savedInputs, ...meta, id, output: previous.output + outputAppend } as unknown as JobResult);
+    return;
+  }
+  if (offset !== undefined) throw new Error("Invalid agent journal output offset");
+  if (!previous) throw new Error("Agent journal record is missing its initial output");
+  records.set(id, { ...savedInputs, ...meta, id, output: previous.output } as unknown as JobResult);
+}
+
+/** Fold version-1 full snapshots and version-2 deltas in branch order into the live record set. */
+export function foldAgentData(payloads: readonly unknown[]): AgentJournalState {
+  let records = new Map<string, JobResult>();
+  let nextId: number | undefined;
+  // A full snapshot supersedes everything before it, including an explicit user reset.
+  // Start at the newest one so old redundant snapshots are neither decoded nor resurrected.
+  let start = 0;
+  for (let index = payloads.length - 1; index >= 0; index--) {
+    const payload = payloads[index];
+    if (isObject(payload) && payload.version === 1) { start = index; break; }
+  }
+  for (let index = start; index < payloads.length; index++) {
+    const raw = payloads[index];
+    if (raw === undefined) throw corrupt();
+    if (!isObject(raw)) throw corrupt();
+    if (raw.version === 1) {
+      if (!Array.isArray(raw.jobs)) throw corrupt();
+      const replaced = new Map<string, JobResult>();
+      for (const job of raw.jobs) {
+        if (!isObject(job) || typeof job.id !== "string" || job.output !== undefined && typeof job.output !== "string" || replaced.has(job.id)) throw corrupt();
+        replaced.set(job.id, { ...job, output: job.output ?? '', requests: Array.isArray(job.requests) ? job.requests : [] } as unknown as JobResult);
+      }
+      records = replaced;
+      nextId = raw.nextId === undefined ? undefined : nextIdOf(raw.nextId);
+      continue;
+    }
+    if (raw.version === 2) {
+      if (raw.jobs !== undefined && !Array.isArray(raw.jobs)) throw corrupt();
+      if (raw.removed !== undefined && (!Array.isArray(raw.removed) || raw.removed.some((id) => typeof id !== "string"))) throw corrupt();
+      for (const id of (raw.removed ?? []) as string[]) records.delete(id);
+      for (const delta of (raw.jobs ?? []) as unknown[]) applyDelta(records, delta);
+      if (raw.nextId !== undefined) {
+        const candidate = nextIdOf(raw.nextId);
+        if (nextId !== undefined && candidate < nextId) throw new Error('Agent journal nextId decreased');
+        nextId = candidate;
+      }
+      continue;
+    }
+    throw new Error(`Unsupported agent journal version: ${String(raw.version)}`);
+  }
+  return { records: [...records.values()], nextId };
+}
+
+/** Fold native branch entries, ignoring every entry that is not the agent journal. */
+export function foldAgentEntries(entries: readonly unknown[]): AgentJournalState {
+  const payloads: unknown[] = [];
+  for (const entry of entries) {
+    if (isObject(entry) && entry.type === 'custom' && entry.customType === AGENTS_ENTRY_TYPE) payloads.push(entry.data);
+  }
+  return foldAgentData(payloads);
+}
+
+/**
+ * Diffs the live records against the last confirmed append. A prepared payload is published with
+ * `confirm` only after the session append succeeded, so a failed write is retried next time.
+ */
+export class AgentJournal {
+  private confirmed = new Map<string, JobResult>();
+  private confirmedNextId = 1;
+  private pending: { records: readonly JobResult[]; nextId: number } | undefined;
+
+  hydrate(records: readonly JobResult[], nextId: number): void {
+    this.confirmed = new Map(records.map((record) => [record.id, record]));
+    this.confirmedNextId = nextId;
+    this.pending = undefined;
+  }
+
+  reset(): void {
+    this.confirmed.clear();
+    this.confirmedNextId = 1;
+    this.pending = undefined;
+  }
+
+  /** Current confirmed high-water id; useful for assertions and diagnostics. */
+  get nextId(): number { return this.confirmedNextId; }
+
+  prepare(records: readonly JobResult[], nextId: number): AgentJournalData | null {
+    const jobs: AgentJobDelta[] = [];
+    const present = new Set<string>();
+    for (const record of records) {
+      present.add(record.id);
+      const previous = this.confirmed.get(record.id);
+      if (previous && sameRecord(previous, record)) continue;
+      jobs.push(deltaOf(record, previous));
+    }
+    const removed = [...this.confirmed.keys()].filter((id) => !present.has(id));
+    if (!jobs.length && !removed.length && nextId === this.confirmedNextId) { this.pending = undefined; return null; }
+    this.pending = { records, nextId };
+    return { version: 2, jobs, nextId, ...(removed.length ? { removed } : {}) };
+  }
+
+  confirm(): void {
+    if (!this.pending) return;
+    this.confirmed = new Map(this.pending.records.map((record) => [record.id, record]));
+    this.confirmedNextId = this.pending.nextId;
+    this.pending = undefined;
+  }
+}

package/src/agents/io/process.ts

@@ -0,0 +1,100 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import type { RpcRecord } from './contracts.ts';
+interface PendingCommand { resolve: (record: RpcRecord) => void; reject: (error: Error) => void; cleanup: () => void }
+
+/** The resolver lives in shared because team spawns children too; re-exported for existing callers. */
+export { resolvePiCli } from '../../shared/pi-cli.ts';
+
+export class RpcPipe {
+  readonly child: ChildProcessWithoutNullStreams;
+  readonly closed: Promise<void>;
+  private pending = new Map<string, PendingCommand>();
+  private sequence = 0;
+  private buffer = "";
+  stderr = "";
+  private dead = false;
+  private stopping = false;
+  private stopPromise: Promise<void> | undefined;
+  constructor(cli: string, args: string[], cwd: string, env: NodeJS.ProcessEnv, onRecord: (record: RpcRecord) => void, onFailure: (error: Error) => void, sanitize: (value: string) => string) {
+    this.child = spawn(process.execPath, [cli, ...args], { cwd, env, detached: process.platform !== "win32", stdio: "pipe" });
+    this.closed = new Promise((resolveClosed) => this.child.once("close", () => resolveClosed()));
+    const fail = (error: Error) => {
+      if (this.dead) return;
+      this.dead = true;
+      for (const pending of this.pending.values()) { pending.cleanup(); pending.reject(error); }
+      this.pending.clear();
+      if (!this.stopping) onFailure(new Error(sanitize(`${error.message}${this.stderr ? `; stderr: ${this.stderr}` : ''}`)));
+    };
+    this.child.stdout.setEncoding("utf8");
+    this.child.stderr.setEncoding("utf8");
+    this.child.stderr.on("data", (chunk: string) => { this.stderr = (this.stderr + chunk).slice(-8192); });
+    this.child.stdin.on("error", (error) => fail(error));
+    this.child.on("error", (error) => fail(error));
+    this.child.on("close", (code, signal) => fail(new Error(`Pi exited before completion (${signal ?? code ?? "unknown"})`)));
+    this.child.stdout.on("data", (chunk: string) => {
+      if (this.dead) return;
+      this.buffer += chunk;
+      let at: number;
+      while ((at = this.buffer.indexOf("\n")) >= 0) {
+        const line = this.buffer.slice(0, at).replace(/\r$/, "");
+        this.buffer = this.buffer.slice(at + 1);
+        if (!line) continue;
+        let record: RpcRecord;
+        try { record = JSON.parse(line) as RpcRecord; if (!record || typeof record.type !== "string") throw new Error("Invalid record"); }
+        catch { fail(new Error("Invalid Pi RPC JSONL record")); return; }
+        if (record.type === "response" && record.id) {
+          const pending = this.pending.get(record.id);
+          if (pending) {
+            pending.cleanup(); this.pending.delete(record.id);
+            if (record.success) pending.resolve(record); else pending.reject(new Error(String(record.error ?? "Pi command failed")));
+          }
+        } else {
+          try { onRecord(record); }
+          catch { fail(new Error("Invalid Pi RPC event")); return; }
+        }
+      }
+    });
+  }
+  command(type: string, fields: Record<string, unknown> = {}, signal?: AbortSignal): Promise<RpcRecord> {
+    if (signal?.aborted) return Promise.reject(new Error(`Pi ${type} command aborted`));
+    if (this.dead || this.stopping) return Promise.reject(new Error("Pi process is closed"));
+    if (this.pending.size >= 32) return Promise.reject(new Error("Too many outstanding child commands"));
+    const id = `rpc-${++this.sequence}`;
+    return new Promise((resolveCommand, reject) => {
+      const fail = (error: Error) => { const pending = this.pending.get(id); if (!pending) return; pending.cleanup(); this.pending.delete(id); reject(error); };
+      const abort = () => fail(new Error(`Pi ${type} command aborted`));
+      const timer = setTimeout(() => fail(new Error(`Pi ${type} command timed out`)), 15000);
+      const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); };
+      this.pending.set(id, { resolve: resolveCommand, reject, cleanup });
+      signal?.addEventListener('abort', abort, { once: true });
+      this.write({ type, ...fields, id }).catch(fail);
+    });
+  }
+  async write(record: Record<string, unknown>): Promise<void> {
+    if (this.dead || this.stopping) throw new Error("Pi process is closed");
+    await new Promise<void>((resolveWrite, reject) => this.child.stdin.write(`${JSON.stringify(record)}\n`, (error) => error ? reject(error) : resolveWrite()));
+  }
+  stop(): Promise<void> {
+    if (this.stopPromise) return this.stopPromise;
+    this.stopping = true;
+    this.stopPromise = (async () => {
+      for (const pending of this.pending.values()) { pending.cleanup(); pending.reject(new Error("Pi process stopped")); }
+      this.pending.clear();
+      // Each Unix child owns a new process group. Kill that group, including shell tools.
+      // On Windows detached groups are not safe to address with negative PIDs.
+      const signal = (name: NodeJS.Signals) => {
+        if (!this.child.pid) return;
+        try { if (process.platform !== "win32") process.kill(-this.child.pid, name); else this.child.kill(name); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") this.child.kill(name); }
+      };
+      this.child.stdin.end();
+      signal("SIGTERM");
+      const timer = setTimeout(() => signal("SIGKILL"), 1000);
+      await this.closed;
+      clearTimeout(timer);
+      // A shell descendant can retain the group after the Pi leader exits.
+      signal("SIGKILL");
+    })();
+    return this.stopPromise;
+  }
+}

package/src/agents/io/profile-file.ts

@@ -0,0 +1,16 @@
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export async function saveProfileText(path: string, source: string): Promise<void> {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, source, { mode: 0o600 });
+      await rename(temporary, path);
+    } catch (error) {
+      const { rm } = await import("node:fs/promises");
+      await rm(temporary, { force: true });
+      throw error;
+    }
+}

package/src/agents/io/skills.ts

@@ -0,0 +1,46 @@
+import { access, realpath, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { extname, resolve } from 'node:path';
+
+export const CHILD_SKILLS_ENV = 'PI_DAG_AGENT_SKILLS';
+/** Explicit file entries only. No discovery, frontmatter loading, scripts or tool activation. */
+export async function skillFiles(paths: readonly string[] | undefined, cwd: string, tools: readonly string[], signal?: AbortSignal): Promise<string[]> {
+  if (!paths?.length) return [];
+  if (!tools.includes('read')) throw new Error('Profile skills require the read tool; skills cannot add tools');
+  if (paths.length > 8) throw new Error('Profile skills accepts at most 8 files');
+  const result = new Set<string>();
+  for (const [index, path] of paths.entries()) {
+    if (signal?.aborted) throw new Error('Skill validation aborted');
+    if (typeof path !== 'string' || !path.trim() || path.length > 2048 || /[\p{Cc}\p{Bidi_Control}\u2028\u2029]/u.test(path) || /^(?![a-z]:[\\/])[a-z][\w+.-]*:/i.test(path)) throw new Error(`Invalid local skill path at entry ${index + 1}`);
+    const expanded = path.startsWith('~/') || path.startsWith('~\\') ? resolve(homedir(), path.slice(2)) : resolve(cwd, path);
+    if (extname(expanded).toLowerCase() !== '.md') throw new Error(`Skill entry ${index + 1} must name a Markdown file, not a directory or package`);
+    try {
+      const canonical = await realpath(expanded);
+      if (extname(canonical).toLowerCase() !== '.md') throw new Error('Expected a Markdown target');
+      const info = await stat(canonical);
+      if (!info.isFile() || !info.size || info.size > 65536 || canonical.length > 2048 || /[\p{Cc}\p{Bidi_Control}\u2028\u2029]/u.test(canonical)) throw new Error('Expected a nonempty regular file no larger than 64 KiB');
+      await access(canonical, constants.R_OK);
+      if (signal?.aborted) throw new Error('Skill validation aborted');
+      result.add(canonical);
+    } catch (cause) {
+      // Do not expose paths or host errors for requested resources in failure summaries.
+      throw new Error(`Skill entry ${index + 1} is not a readable local Markdown file (1–65536 bytes)${signal?.aborted ? '; validation aborted' : ''}`, { cause });
+    }
+  }
+  const selected = [...result];
+  if (Buffer.byteLength(JSON.stringify(selected)) > 20000) throw new Error('Selected skill path entries exceed 20 KiB');
+  return selected;
+}
+
+/** The child consumes and removes only the selected entries; it does not inspect their bodies. */
+export function takeSkillFiles(env: NodeJS.ProcessEnv = process.env): string[] {
+  const raw = env[CHILD_SKILLS_ENV];
+  delete env[CHILD_SKILLS_ENV];
+  if (raw === undefined) return [];
+  if (Buffer.byteLength(raw) > 20000) throw new Error('Invalid child skill entries');
+  let files: unknown;
+  try { files = JSON.parse(raw); } catch { throw new Error('Invalid child skill entries'); }
+  if (!Array.isArray(files) || files.length > 8 || files.some((file) => typeof file !== 'string' || !file || file.length > 2048 || /[\p{Cc}\p{Bidi_Control}\u2028\u2029]/u.test(file))) throw new Error('Invalid child skill entries');
+  return [...new Set(files as string[])];
+}