pi-durable-subagents 0.0.0-stage → 1.0.2

package/dist/agent/capabilities.js

@@ -0,0 +1,32 @@
+// Upgrade safety (robustness.md layer 3, AC5): probe every pi surface we use before registering anything.
+// A missing tier-0 surface disables Durable Subagents with one exact message; a missing UI surface disables only
+// the UI. Never a silent failure, never a crash of pi.
+export const SURFACES = [
+    ...["on", "registerTool", "appendEntry", "sendMessage", "setModel", "setThinkingLevel"].map(name => ({ tier: 0, where: "ExtensionAPI", name })),
+    { tier: 0, where: "@earendil-works/pi-coding-agent", name: "defineTool" },
+    { tier: 0, where: "@earendil-works/pi-ai", name: "Type" },
+    ...["AssistantMessageComponent", "UserMessageComponent", "ToolExecutionComponent", "getMarkdownTheme", "getSelectListTheme"]
+        .map(name => ({ tier: 2, where: "@earendil-works/pi-coding-agent", name })),
+    { tier: 2, where: "ExtensionAPI", name: "registerMessageRenderer" },
+    { tier: 2, where: "@earendil-works/pi-tui", name: "wrapTextWithAnsi" },
+    ...["Input", "SelectList", "fuzzyFilter", "matchesKey", "truncateToWidth", "visibleWidth"].map(name => ({ tier: 2, where: "@earendil-works/pi-tui", name })),
+];
+/** AC5, P21: Check the surfaces present in pi's modules and extension API; produce exact degradation messages. */
+export function checkCapabilities(modules, api, version) {
+    const has = (s) => s.where === "ExtensionAPI" ? typeof api[s.name] === "function" : modules[s.where]?.[s.name] !== undefined;
+    const missing = SURFACES.filter(s => !has(s));
+    const name = (list) => list.map(s => `${s.where}.${s.name}`).join(", ");
+    const pi = version ? `pi ${version}` : "this pi version";
+    // The evaluator's CPU limit needs worker.cpuUsage and process.threadCpuUsage (Node 22.19); without them a runaway
+    // script would never be stopped, so an older Node disables execution rather than run unguarded.
+    const node = typeof process.threadCpuUsage === "function";
+    const execution = node && !missing.some(s => s.tier === 0), ui = execution && !missing.some(s => s.tier === 2);
+    const messages = [];
+    if (!node)
+        messages.push(`Durable Subagents disabled: it needs Node.js 22.19 or later (this is ${process.version}).`);
+    else if (!execution)
+        messages.push(`Durable Subagents disabled: ${pi} no longer provides ${name(missing.filter(s => s.tier === 0))}. Running workflows are untouched; run \`pi-durable-subagents smoke\` for details.`);
+    else if (!ui)
+        messages.push(`Durable Subagents: native watch view disabled (${pi} no longer exports ${name(missing.filter(s => s.tier === 2))}); use \`pi-durable-subagents tail\`.`);
+    return { ...(version ? { version } : {}), missing, execution, ui, messages };
+}

package/dist/agent/child/history.js

@@ -0,0 +1,49 @@
+import { CT } from "../../types.js";
+/** A1, P4, P8, P37: Recover receipts and question revisions for this call generation. A generation continues the
+ *  session of the previous one (P37), but request sequences are per recipient (P5): records addressed to an earlier
+ *  generation stay in history and are skipped here: segments opened by another call's execution marker are foreign. */
+export function recover(entries, call) {
+    const records = [], questions = new Map(), answered = new Set();
+    let foreign = false;
+    for (const entry of entries) {
+        if (entry.type === 'custom' && entry.customType === CT.exec) {
+            const owner = /^(.*)#\d+\.\d+$/.exec(String(entry.data?.exec ?? ''));
+            foreign = call !== undefined && !!owner && owner[1] !== call;
+        }
+        if (foreign)
+            continue;
+        if (entry.type === 'custom') {
+            const data = entry.data;
+            if (!data)
+                continue;
+            if (entry.customType === CT.admitted)
+                records.push({ ...data, type: 'admitted' });
+            if (entry.customType === CT.rejected)
+                records.push({ type: 'rejected', rid: data.rid, reason: data.reason });
+            if (entry.customType === CT.withdrawn) {
+                records.push({ type: 'withdrawn', rids: data.rids });
+                if (data.rid)
+                    records.push({ type: 'applied', rid: data.rid });
+            }
+            if (entry.customType === CT.model)
+                records.push({ type: 'applied', rid: data.rid });
+            if (entry.customType === CT.question)
+                questions.set(data.qid, data);
+        }
+        else if (entry.type === 'custom_message' && entry.customType === CT.msg) {
+            const details = entry.details;
+            records.push({ type: 'applied', rid: details.rid });
+            // P28: a hibernation resume delivers the answer as a continue message; its receipt answers qid@rev.
+            if (details.qid && details.rev)
+                answered.add(`${details.qid}@${details.rev}`);
+        }
+        else if (entry.type === 'message' && entry.message.role === 'toolResult' && entry.message.toolName === 'ask') {
+            const details = entry.message.details;
+            if (details?.rid)
+                records.push({ type: 'applied', rid: details.rid });
+            if (details?.qid && details.rev)
+                answered.add(`${details.qid}@${details.rev}`);
+        }
+    }
+    return { records, questions, answered };
+}

package/dist/agent/child/live.js

@@ -0,0 +1,62 @@
+// UI §3 "be pi": the child's in-flight model response, for watching only. pi persists an assistant message when it
+// ends; until then the session file cannot say whether the model is thinking, writing or has not answered yet.
+// live.json (next to the session) holds that ephemeral state. It is not durable state: written without fsync,
+// replaced atomically (temp + rename), ignored when stale, and never read by the orchestrator.
+import { renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const LIVE_FILE = "live.json";
+const TAIL = 4000, EVERY_MS = 250;
+const tail = (text) => text.length > TAIL ? text.slice(-TAIL) : text;
+/** UI §3: Publish waiting/streaming/idle while a provider request is in flight (at most four writes a second). */
+export function registerLive(pi, enabled) {
+    let since = 0, last = 0, pending, path, state;
+    const flush = () => {
+        pending = undefined;
+        last = Date.now();
+        if (!path || !state)
+            return;
+        try {
+            const tmp = `${path}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify({ ...state, at: last }));
+            renameSync(tmp, path);
+        }
+        catch { /* Watching is best effort; the session file stays the truth. */ }
+    };
+    const publish = (ctx, next, now = false) => {
+        if (!enabled())
+            return;
+        const file = ctx.sessionManager.getSessionFile();
+        if (!file)
+            return;
+        path = join(dirname(file), LIVE_FILE);
+        const changed = state?.phase !== next.phase;
+        state = { ...next, at: Date.now() };
+        if (changed || now || Date.now() - last >= EVERY_MS) {
+            if (pending)
+                clearTimeout(pending);
+            flush();
+        }
+        else
+            pending ??= setTimeout(flush, EVERY_MS - (Date.now() - last));
+    };
+    // A turn is one model call: from its start (or the provider request) until the first streamed token, it is waiting.
+    const waiting = (_event, ctx) => { if (state?.phase !== "waiting")
+        since = Date.now(); publish(ctx, { phase: "waiting", since }); };
+    pi.on("turn_start", waiting);
+    pi.on("before_provider_request", waiting);
+    pi.on("message_update", (event, ctx) => {
+        const m = event.message;
+        if (m.role !== "assistant" || !Array.isArray(m.content))
+            return;
+        const thinking = m.content.filter(b => b.type === "thinking").map(b => b.thinking ?? "").join("\n");
+        const text = m.content.filter(b => b.type === "text").map(b => b.text ?? "").join("\n");
+        const tool = m.content.filter(b => b.type === "toolCall").at(-1)?.name;
+        publish(ctx, { phase: "streaming", since: since || Date.now(), ...(thinking ? { thinking: tail(thinking) } : {}), ...(text ? { text: tail(text) } : {}), ...(tool ? { tool } : {}) });
+    });
+    pi.on("message_end", (event, ctx) => {
+        if (event.message.role === "assistant") {
+            since = 0;
+            publish(ctx, { phase: "idle", since: Date.now() }, true);
+        }
+    });
+}

package/dist/agent/child/schema.js

@@ -0,0 +1,86 @@
+import { isDeepStrictEqual } from 'node:util';
+const keywords = new Set(['type', 'enum', 'items', 'properties', 'required', 'additionalProperties', 'description', 'title']);
+const types = new Set(['null', 'boolean', 'object', 'array', 'number', 'integer', 'string']);
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** P24, T4: List unsupported keywords and malformed shapes so a schema that would not constrain fails loudly. */
+export function schemaProblems(schema, path = '$') {
+    if (typeof schema === 'boolean')
+        return [];
+    if (!isObject(schema))
+        return [`${path}: must be an object or boolean`];
+    const problems = [];
+    for (const [key, value] of Object.entries(schema)) {
+        const at = `${path}.${key}`;
+        if (!keywords.has(key))
+            problems.push(`${path}: unsupported keyword "${key}"`);
+        else if (key === 'type') {
+            const names = Array.isArray(value) ? value : [value];
+            if (!names.length || !names.every(n => typeof n === 'string' && types.has(n)))
+                problems.push(`${at}: must be one of ${[...types].join(', ')} or a nonempty array of them`);
+        }
+        else if (key === 'enum') {
+            if (!Array.isArray(value))
+                problems.push(`${at}: must be an array`);
+        }
+        else if (key === 'items' || key === 'additionalProperties')
+            problems.push(...schemaProblems(value, at));
+        else if (key === 'properties') {
+            if (!isObject(value))
+                problems.push(`${at}: must be an object of schemas`);
+            else
+                for (const [name, item] of Object.entries(value))
+                    problems.push(...schemaProblems(item, `${at}.${name}`));
+        }
+        else if (key === 'required') {
+            if (!Array.isArray(value) || !value.every(n => typeof n === 'string'))
+                problems.push(`${at}: must be an array of strings`);
+        }
+        else if (typeof value !== 'string')
+            problems.push(`${at}: must be a string`);
+    }
+    return problems;
+}
+/** P24: Validate the supported JSON schema vocabulary without coercion or dependencies. */
+export function validate(schema, value, path = '$') {
+    if (schema === true)
+        return [];
+    if (schema === false)
+        return [`${path}: forbidden`];
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema))
+        throw new Error('Invalid report schema');
+    const s = schema, errors = [];
+    const matches = (type) => {
+        if (type === 'null')
+            return value === null;
+        if (type === 'array')
+            return Array.isArray(value);
+        if (type === 'object')
+            return value !== null && typeof value === 'object' && !Array.isArray(value);
+        if (type === 'integer')
+            return typeof value === 'number' && Number.isInteger(value);
+        if (type === 'number')
+            return typeof value === 'number' && Number.isFinite(value);
+        return typeof value === type;
+    };
+    if (s.type && !(Array.isArray(s.type) ? s.type : [s.type]).some(matches))
+        errors.push(`${path}: expected ${s.type}`);
+    if (s.enum && !s.enum.some((item) => isDeepStrictEqual(item, value)))
+        errors.push(`${path}: not in enum`);
+    if (Array.isArray(value) && s.items !== undefined)
+        value.forEach((item, i) => errors.push(...validate(s.items, item, `${path}[${i}]`)));
+    if (matches('object')) {
+        const obj = value, properties = s.properties ?? {};
+        for (const key of s.required ?? [])
+            if (!Object.hasOwn(obj, key))
+                errors.push(`${path}.${key}: required`);
+        for (const [key, item] of Object.entries(obj)) {
+            if (Object.hasOwn(properties, key))
+                errors.push(...validate(properties[key], item, `${path}.${key}`));
+            else if (s.additionalProperties === false)
+                errors.push(`${path}.${key}: additional property`);
+            else if (s.additionalProperties && typeof s.additionalProperties === 'object')
+                errors.push(...validate(s.additionalProperties, item, `${path}.${key}`));
+        }
+    }
+    return errors;
+}

package/dist/agent/child.js

@@ -0,0 +1,305 @@
+import { watch } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { Type } from '@earendil-works/pi-ai';
+import { CT, ENV, JT } from "../types.js";
+import { readJournalSnapshot } from "../kernel/journal.js";
+import { scanInbox } from "../kernel/mailbox.js";
+import { contentHash } from "../kernel/ids.js";
+import { planDecisions } from "../kernel/lifecycle.js";
+import { openness } from "../kernel/guards.js";
+import { recover } from "./child/history.js";
+import { validate } from "./child/schema.js";
+import { registerLive } from "./child/live.js";
+const MESSAGES = ['task', 'steer', 'follow-up', 'continue'];
+/** P31, P33, P37: Usage of this call only — assistant messages in segments opened by this call's executions,
+ *  deduplicated by entry id. Context inherited from an earlier generation or a forked origin is not charged. */
+export function usage(entries, call) {
+    let tokens = 0, costUsd = 0, own = call === undefined;
+    const seen = new Set();
+    for (const e of entries) {
+        if (e.type === 'custom' && e.customType === CT.exec)
+            own = call === undefined || String(e.data?.exec ?? '').startsWith(`${call}#`) || !/#\d+\.\d+$/.test(String(e.data?.exec ?? ''));
+        if (!own)
+            continue;
+        const u = e.type === 'message' && e.message?.role === 'assistant' ? e.message.usage : undefined;
+        if (!u || (e.id && seen.has(e.id)))
+            continue;
+        if (e.id)
+            seen.add(e.id);
+        tokens += u.totalTokens ?? (u.input ?? 0) + (u.output ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+        costUsd += u.cost?.total ?? 0;
+    }
+    return { tokens, costUsd };
+}
+/** P4, P8, P23, P24: Consume the child mailbox at serialized pi boundaries, retaining native session receipts. */
+export function registerChild(pi) {
+    let target = process.env[ENV.model];
+    const exec = process.env[ENV.exec], call = process.env[ENV.call], inbox = process.env[ENV.inbox], journal = process.env[ENV.journal];
+    let active = false, watcher, queue = Promise.resolve();
+    let state = recover([]), blocked;
+    const serial = (fn) => {
+        const result = queue.then(fn);
+        queue = result.catch(() => { });
+        return result;
+    };
+    const fail = (ctx, error) => {
+        console.error('Child mailbox failed:', error);
+        active = false;
+        watcher?.close();
+        blocked?.reject(error instanceof Error ? error : new Error(String(error)));
+        blocked = undefined;
+        ctx.shutdown();
+    };
+    /** C8: Make the model the executor holds a slot for (or a model request named) the active one before a turn starts.
+     *  pi captures a turn's model when the turn begins, so a correction in the `context` hook comes too late for that
+     *  turn: seen on CI as one "Unknown provider: unknown" reply (pi's placeholder model) after a resume. The registry
+     *  can briefly lack an extension provider at startup, so wait for it up to 5 s. */
+    async function ensureModel(ctx) {
+        const slash = target?.indexOf('/') ?? -1;
+        if (!target || slash <= 0 || `${ctx.model?.provider}/${ctx.model?.id}` === target)
+            return;
+        let model = ctx.modelRegistry.find(target.slice(0, slash), target.slice(slash + 1));
+        for (let waited = 0; !model && waited < 5000; waited += 50) {
+            await new Promise(resolve => setTimeout(resolve, 50));
+            model = ctx.modelRegistry.find(target.slice(0, slash), target.slice(slash + 1));
+        }
+        if (model)
+            await pi.setModel(model);
+        else
+            console.error(`durable-subagents: model ${target} is not registered in this pi (have: ${[...new Set(ctx.modelRegistry.getAll().map(m => m.provider))].join(', ')})`);
+    }
+    async function consume(ctx, mode) {
+        if (!active || (mode === 'idle' && !ctx.isIdle()))
+            return [];
+        if (mode === 'idle')
+            await ensureModel(ctx); // an idle delivery starts a turn
+        const candidates = await scanInbox(inbox), byRid = new Map(candidates.map(req => [req.rid, req]));
+        // Scan is asynchronous: recheck before using the idle delivery API.
+        if (!active || (mode === 'idle' && !ctx.isIdle()))
+            return [];
+        let delivered = false;
+        const plans = planDecisions(state.records, candidates, req => {
+            if (req.to !== call)
+                return { action: 'reject', reason: 'wrong-recipient' };
+            if ([...MESSAGES, 'answer'].includes(req.kind) && typeof req.body?.message !== 'string')
+                return { action: 'reject', reason: 'malformed' };
+            if (req.kind === 'answer') {
+                const qid = req.cond?.qid, rev = req.cond?.rev, question = qid ? state.questions.get(qid) : undefined;
+                if (state.answered.has(`${qid}@${rev}`))
+                    return { action: 'reject', reason: 'already-answered' };
+                if (!question || question.rev !== rev)
+                    return { action: 'reject', reason: 'stale-rev' };
+                if (mode !== 'ask' || delivered || !openness({ open: [...state.questions.values()], blocked }, { qid: qid, rev: rev }))
+                    return { action: 'defer' };
+                delivered = true;
+                return { action: 'apply' };
+            }
+            if (mode === 'ask' && (req.kind !== 'steer' || delivered))
+                return { action: 'defer' };
+            if (req.kind === 'model') {
+                const body = req.body;
+                return body && ctx.modelRegistry.find(body.provider, body.model) ? { action: 'apply' } : { action: 'reject', reason: 'unknown-model' };
+            }
+            if (MESSAGES.includes(req.kind)) {
+                if ((mode === 'idle' && delivered) || (req.kind === 'follow-up' && mode === 'boundary'))
+                    return { action: 'defer' };
+                delivered = true;
+                return { action: 'apply' };
+            }
+            return { action: 'reject', reason: 'unsupported' };
+        });
+        // Idle delivery starts pi immediately. Commit only through that message's receipt;
+        // later decisions must be reconsidered at the next boundary, in history order.
+        if (mode === 'idle') {
+            const firstMessage = plans.findIndex(d => d.type === 'applied' && MESSAGES.includes(byRid.get(d.rid).kind));
+            if (firstMessage >= 0)
+                plans.splice(firstMessage + 1);
+        }
+        const entries = [];
+        const record = (customType, data) => entries.push({ type: 'custom', customType, data });
+        let answer, waiter = blocked;
+        for (let i = 0; i < plans.length; i++) {
+            const decision = plans[i];
+            if (decision.type === 'admitted' || decision.type === 'rejected') {
+                const { type, ...data } = decision;
+                record(type === 'admitted' ? CT.admitted : CT.rejected, data);
+            }
+            else if (decision.type === 'withdrawn') {
+                // The kernel emits target rejections between tombstones and the withdrawal receipt.
+                const receipt = plans.slice(i + 1).find(d => d.type === 'applied' && byRid.get(d.rid)?.kind === 'withdraw');
+                record(CT.withdrawn, { rid: receipt.rid, rids: decision.rids });
+            }
+            else {
+                const req = byRid.get(decision.rid);
+                if (req.kind === 'withdraw')
+                    continue;
+                if (req.kind === 'model') {
+                    const body = req.body, model = ctx.modelRegistry.find(body.provider, body.model);
+                    if (!(await pi.setModel(model)))
+                        throw new Error(`Cannot activate model ${body.provider}/${body.model}`);
+                    if (body.thinking)
+                        pi.setThinkingLevel(body.thinking);
+                    target = `${body.provider}/${body.model}`;
+                    record(CT.model, { rid: req.rid, provider: body.provider, model: body.model, ...(body.thinking ? { thinking: body.thinking } : {}) });
+                }
+                else if (mode === 'ask' && waiter) {
+                    const text = req.body.message;
+                    answer = req.kind === 'answer'
+                        ? { content: [{ type: 'text', text }], details: { rid: req.rid, qid: waiter.qid, rev: waiter.rev } }
+                        : { content: [{ type: 'text', text: `${JSON.stringify({ interrupted_by: 'steer', open: waiter.qid })}\n${text}` }], details: { rid: req.rid, kind: 'steer' } };
+                    if (req.kind === 'answer')
+                        state.answered.add(`${waiter.qid}@${waiter.rev}`);
+                }
+                else {
+                    // P28: a continue bound to a question (hibernation resume) is that question's answer receipt.
+                    const bound = req.kind === 'continue' && req.cond?.qid && req.cond.rev ? { qid: req.cond.qid, rev: req.cond.rev } : undefined;
+                    if (bound)
+                        state.answered.add(`${bound.qid}@${bound.rev}`);
+                    entries.push({ type: 'custom_message', customType: CT.msg, content: req.body.message, display: true, details: { rid: req.rid, kind: req.kind, from: req.from, ...bound } });
+                }
+            }
+        }
+        state.records.push(...plans);
+        if (mode !== 'boundary' && mode !== 'settle') {
+            // A single idle message is last: once it starts pi, further work waits for a boundary.
+            const message = entries.find(e => e.type === 'custom_message');
+            for (const entry of entries)
+                if (entry.type === 'custom')
+                    pi.appendEntry(entry.customType, entry.data);
+            if (message?.type === 'custom_message')
+                pi.sendMessage(message, { triggerTurn: true });
+            if (answer && waiter) {
+                blocked = undefined;
+                waiter.resolve(answer);
+            }
+            return [];
+        }
+        return entries;
+    }
+    pi.on('session_start', async (_event, ctx) => {
+        await serial(async () => {
+            const entries = await readJournalSnapshot(journal);
+            if (entries.filter(e => e.type === JT.exec && e.call === call).at(-1)?.exec !== exec || entries.some(e => e.type === JT.fenced && e.exec === exec)) {
+                ctx.shutdown();
+                // P23: pi 1.0.2 rpc-mode.js:256-257/:632 honors shutdown only after another
+                // RPC command. This owned child is inert and has written nothing; exit now.
+                setImmediate(() => process.exit(0));
+                return;
+            }
+            state = recover(ctx.sessionManager.getEntries(), call);
+            active = true;
+            pi.appendEntry(CT.exec, { exec });
+            // C8: pi can resolve the session's model before an extension-registered provider exists ("Unknown provider").
+            // The executor names the model it holds a slot for; apply it before any provider request if pi did not.
+            // Observed with pi 1.0.2 on resumed sessions: the registry briefly lacks an extension provider at startup.
+            // Nothing is delivered (so no provider request starts) until the held model is resolvable, for up to 5 s.
+            await ensureModel(ctx);
+            watcher = watch(inbox, () => { void serial(async () => { await consume(ctx, blocked ? 'ask' : 'idle'); }).catch(error => fail(ctx, error)); });
+            watcher.on('error', error => fail(ctx, error));
+            await consume(ctx, 'idle');
+        });
+    });
+    const boundary = (mode) => async (_event, ctx) => {
+        try {
+            return await serial(async () => { const entries = await consume(ctx, mode); return { entries, continue: entries.some(e => e.type === 'custom_message' || (e.type === 'custom' && e.customType === CT.model)) }; });
+        }
+        catch (error) {
+            fail(ctx, error);
+        }
+    };
+    pi.on('turn_end', boundary('boundary'));
+    registerLive(pi, () => active); // UI §3: in-flight response for watching (ephemeral, not durable state)
+    pi.on('agent_before_settle', boundary('settle'));
+    // P31b, V8: refuse the next provider request once the per-call budget is reached (one in-flight overshoot at most).
+    const budget = process.env[ENV.budget] ? JSON.parse(process.env[ENV.budget]) : undefined;
+    // C8: last line of defence before each provider request — pi 1.0.2 occasionally starts a resumed turn with its
+    // placeholder model ("unknown"); re-apply the model the executor holds a slot for.
+    // A model request applied by this child (P12) replaces the target.
+    // turn_start runs before the request is prepared (pi reads the model then); `context` runs after it, too late for
+    // that request (seen on CI: model_change after the delivered message, then "Unknown provider: unknown"). Keep both.
+    const guard = async (_event, ctx) => {
+        const slash = target?.indexOf('/') ?? -1;
+        if (!target || slash <= 0 || `${ctx.model?.provider}/${ctx.model?.id}` === target)
+            return;
+        const model = ctx.modelRegistry.find(target.slice(0, slash), target.slice(slash + 1));
+        if (model)
+            await pi.setModel(model);
+        else
+            console.error(`durable-subagents: model ${target} is not registered before a provider request`);
+    };
+    pi.on('turn_start', guard);
+    pi.on('context', guard);
+    if (budget)
+        pi.on('context', async (_event, ctx) => {
+            if (!active)
+                return;
+            const used = usage(ctx.sessionManager.getEntries(), call);
+            if ((budget.tokens === undefined || used.tokens < budget.tokens) && (budget.costUsd === undefined || used.costUsd < budget.costUsd))
+                return;
+            await serial(async () => {
+                if (!active)
+                    return;
+                active = false;
+                watcher?.close();
+                pi.appendEntry(CT.budget, { exec, usage: used });
+                ctx.abort();
+            });
+        });
+    pi.on('session_shutdown', async () => {
+        active = false;
+        watcher?.close();
+        blocked?.reject(new Error('Session shut down'));
+        blocked = undefined;
+        await queue;
+    });
+    pi.registerTool({
+        name: 'ask', label: 'Ask supervisor', description: 'Ask a question and wait for an answer or steering message.',
+        parameters: Type.Object({ question: Type.String() }), executionMode: 'sequential', exposure: 'model-only',
+        async execute(_id, { question }, signal, _update, ctx) {
+            let resolve, reject;
+            const result = new Promise((yes, no) => { resolve = yes; reject = no; });
+            // Attach immediately so abort during the queued intake never produces an unhandled rejection.
+            void result.catch(() => { });
+            const abort = () => { void serial(async () => { if (blocked?.resolve === resolve)
+                blocked = undefined; reject(new Error('Ask aborted')); }); };
+            signal?.addEventListener('abort', abort, { once: true });
+            try {
+                await serial(async () => {
+                    if (!active || signal?.aborted)
+                        throw new Error('Ask aborted');
+                    if (blocked)
+                        throw new Error('Another question is already blocked');
+                    const qid = contentHash({ exec, question }), rev = (state.questions.get(qid)?.rev ?? 0) + 1;
+                    const q = { qid, rev, question };
+                    state.questions.set(qid, q);
+                    pi.appendEntry(CT.question, q);
+                    blocked = { ...q, resolve, reject };
+                    await consume(ctx, 'ask');
+                });
+                return await result;
+            }
+            finally {
+                signal?.removeEventListener('abort', abort);
+            }
+        },
+    });
+    if (process.env[ENV.schema])
+        pi.registerTool({
+            name: 'report', label: 'Report result', description: 'Submit a schema-validated final report and terminate the run.',
+            parameters: Type.Object({ outcome: Type.Union([Type.Literal('ok'), Type.Literal('failed')]), summary: Type.Optional(Type.String()), data: Type.Optional(Type.Unknown()) }),
+            executionMode: 'sequential', exposure: 'model-only',
+            async execute(_id, payload, _signal, _update, _ctx) {
+                return serial(async () => {
+                    if (!active)
+                        throw new Error('Execution is not current');
+                    const schema = JSON.parse(await readFile(process.env[ENV.schema], 'utf8')), errors = validate(schema, payload.data);
+                    if (errors.length)
+                        throw new Error(`Invalid report: ${errors.join('; ')}`);
+                    pi.appendEntry(CT.report, { exec, ...payload });
+                    active = false;
+                    watcher?.close();
+                    return { content: [{ type: 'text', text: payload.summary ?? JSON.stringify(payload.data) ?? payload.outcome }], details: { exec, ...payload }, terminate: true };
+                });
+            },
+        });
+}

package/dist/agent/extension.js

@@ -0,0 +1,56 @@
+// pi extension entry (P2): the same extension runs in every pi session.
+// Child mode when DSA_EXEC is set (spawned by the orchestrator), main mode otherwise.
+// The orchestrator always passes `-e <this file>` to children; if the package is also installed,
+// pi may load it twice in one load pass, so a process-global guard keeps registration single. The guard is
+// cleared on session_shutdown, which pi emits before /reload replaces the extension runtime.
+// Upgrade safety (AC5): pi surfaces are probed through namespace imports (never a link error) before the modules
+// that use them are loaded; DSA_PROBE=<file> only writes the capability report (used by `smoke`).
+import { writeFileSync, writeSync } from "node:fs";
+import * as coding from "@earendil-works/pi-coding-agent";
+import * as tui from "@earendil-works/pi-tui";
+import * as ai from "@earendil-works/pi-ai";
+import { ENV } from "../types.js";
+import { checkCapabilities } from "./capabilities.js";
+const LOADED = Symbol.for("pi-durable-subagents.loaded");
+/** P21: A child (DSA_EXEC set) without its execution surfaces cannot do its call; it reports the exact message on
+ *  stderr and exits 3, so the executor records the message per call and counts a loss (failed after K2) instead of
+ *  waiting on a child that will never act. Returns the stderr text, or undefined when the child may proceed. */
+export function childRefusal(report, env) {
+    if (!env[ENV.exec] || report.execution)
+        return undefined;
+    return report.messages.join("\n");
+}
+export default async function (pi) {
+    const modules = { "@earendil-works/pi-coding-agent": coding, "@earendil-works/pi-tui": tui, "@earendil-works/pi-ai": ai };
+    const report = checkCapabilities(modules, pi, typeof coding.VERSION === "string" ? String(coding.VERSION) : undefined);
+    if (process.env.DSA_PROBE) {
+        writeFileSync(process.env.DSA_PROBE, JSON.stringify(report));
+        return;
+    }
+    const refusal = childRefusal(report, process.env);
+    // Synchronous write: process.exit must not drop the message on an asynchronous pipe.
+    if (refusal !== undefined) {
+        writeSync(2, `${refusal}\n`);
+        process.exit(3);
+    }
+    const g = globalThis;
+    if (g[LOADED])
+        return;
+    g[LOADED] = true;
+    for (const message of report.messages)
+        console.error(message);
+    if (typeof pi.on === "function") {
+        pi.on("session_shutdown", () => { delete g[LOADED]; });
+        if (report.messages.length && !process.env[ENV.exec])
+            pi.on("session_start", (_event, ctx) => {
+                for (const message of report.messages)
+                    ctx.ui?.notify?.(message, report.execution ? "warning" : "error");
+            });
+    }
+    if (!report.execution)
+        return;
+    if (process.env[ENV.exec])
+        (await import("./child.js")).registerChild(pi);
+    else
+        (await import("./main.js")).registerMain(pi, report.ui ? (await import("../ui/index.js")).registerUi : undefined);
+}