@henryqw/pi-subagent 18.0.1 → 22.0.1

package/dist/launch-runtime.js

@@ -0,0 +1,195 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdtemp, open, realpath, rmdir, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, normalize, relative, sep } from "node:path";
+import { resolveConfiguredRoleLaunch } from "./index.js";
+import { EXECUTION_BUDGET_ENV } from "./ephemeral.js";
+import { registerModelTask } from "@henryqw/pi-task-models";
+const PROMPT_FLAG = "--append-system-prompt";
+const DIRECTORY_MODE = 0o700;
+const PROMPT_MODE = 0o600;
+export const ISOLATED_MODEL_TASK = {
+    id: "pi-subagent/isolatedRoleLaunch",
+    label: "Isolated Role launch",
+    purpose: "Resolve one task-scoped isolated Role launch.",
+    defaultProfile: "balanced",
+};
+function abortIfNeeded(signal) {
+    signal?.throwIfAborted();
+}
+function isMissing(error) {
+    return Boolean(error && typeof error === "object" && error.code === "ENOENT");
+}
+function isWithin(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === "" || (fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot));
+}
+async function removeTransientLaunch(directory, promptPath, promptRequired) {
+    const failures = [];
+    try {
+        await unlink(promptPath);
+    }
+    catch (error) {
+        if (promptRequired || !isMissing(error)) {
+            failures.push(new Error(`Could not remove transient Role prompt ${promptPath}.`, { cause: error }));
+        }
+    }
+    try {
+        await rmdir(directory);
+    }
+    catch (error) {
+        failures.push(new Error(`Could not remove transient Role launch directory ${directory}.`, { cause: error }));
+    }
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1)
+        throw new AggregateError(failures, "Transient Role launch cleanup was incomplete.");
+}
+export async function materializeTransientLaunch(prepared, signal) {
+    abortIfNeeded(signal);
+    const promptBytes = Buffer.from(prepared.prompt, "utf8");
+    const created = await mkdtemp(join(tmpdir(), "pi-subagent-role-"));
+    let directory = normalize(created);
+    let promptPath = join(directory, "system-prompt");
+    let promptCreated = false;
+    let file;
+    try {
+        directory = normalize(await realpath(created));
+        promptPath = join(directory, "system-prompt");
+        await chmod(directory, DIRECTORY_MODE);
+        const directoryInfo = await lstat(directory);
+        if (directoryInfo.isSymbolicLink() || !directoryInfo.isDirectory()
+            || (directoryInfo.mode & 0o7777) !== DIRECTORY_MODE
+            || !isWithin(normalize(await realpath(tmpdir())), directory)) {
+            throw new Error("Transient Role launch directory is not unique canonical mode 0700 OS-temp storage.");
+        }
+        file = await open(promptPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, PROMPT_MODE);
+        promptCreated = true;
+        await file.chmod(PROMPT_MODE);
+        abortIfNeeded(signal);
+        await file.writeFile(promptBytes, { signal });
+        await file.sync();
+        await file.close();
+        file = undefined;
+        const promptInfo = await lstat(promptPath);
+        if (promptInfo.isSymbolicLink() || !promptInfo.isFile()
+            || (promptInfo.mode & 0o7777) !== PROMPT_MODE
+            || normalize(await realpath(promptPath)) !== promptPath) {
+            throw new Error("Transient Role prompt is not a canonical mode 0600 regular file.");
+        }
+        const args = [...prepared.launch.args];
+        args.splice(prepared.promptArgIndex, 0, PROMPT_FLAG, promptPath);
+        const launch = Object.freeze({
+            ...prepared.launch,
+            args: Object.freeze(args),
+        });
+        let cleanup;
+        return Object.freeze({
+            launch,
+            cleanup: async () => await (cleanup ??= removeTransientLaunch(directory, promptPath, true)),
+        });
+    }
+    catch (error) {
+        const failures = [error];
+        if (file) {
+            try {
+                await file.close();
+            }
+            catch (closeError) {
+                failures.push(closeError);
+            }
+        }
+        try {
+            await removeTransientLaunch(directory, promptPath, promptCreated);
+        }
+        catch (cleanupError) {
+            failures.push(cleanupError);
+        }
+        if (failures.length > 1) {
+            throw new AggregateError(failures, `Transient Role prompt materialization for ${prepared.launch.role} failed and cleanup was incomplete.`);
+        }
+        throw error;
+    }
+}
+export class RoleLaunchRuntime {
+    options;
+    constructor(options) {
+        this.options = options;
+        registerModelTask(options.pi, ISOLATED_MODEL_TASK);
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    randomToken() {
+        return this.options.randomToken?.() ?? randomBytes(12).toString("hex");
+    }
+    async prepareLaunch(role, modelClass, context) {
+        abortIfNeeded(context.signal);
+        const input = { role, modelClass, task: ISOLATED_MODEL_TASK };
+        const prepared = await resolveConfiguredRoleLaunch(this.options.pi, this.options.context(), input);
+        if (prepared.missingSkills.length) {
+            throw new Error(`Role ${role} requires missing Skills: ${prepared.missingSkills.join(", ")}.`);
+        }
+        const executionBudget = this.options.executionBudget?.();
+        return Object.freeze({
+            launch: Object.freeze({
+                role: prepared.role,
+                modelClass,
+                model: `${prepared.model.provider}/${prepared.model.id}`,
+                thinkingLevel: prepared.thinkingLevel,
+                args: Object.freeze([...prepared.args]),
+                env: Object.freeze({
+                    ...prepared.env,
+                    ...(executionBudget === undefined ? {} : {
+                        [EXECUTION_BUDGET_ENV]: JSON.stringify({ ...executionBudget, startedAt: this.now() }),
+                    }),
+                }),
+                tools: Object.freeze([...prepared.tools]),
+            }),
+            prompt: prepared.systemPrompt,
+            promptArgIndex: prepared.promptArgIndex,
+        });
+    }
+    async preflight(input, context) {
+        abortIfNeeded(context.signal);
+        const resolvedRoot = await this.options.resolveRoot(input.cwd, context);
+        if (typeof resolvedRoot !== "string" || !isAbsolute(resolvedRoot) || resolvedRoot.includes("\0")) {
+            throw new Error("Pi Subagent root resolver must return an absolute canonical path.");
+        }
+        const root = normalize(await realpath(resolvedRoot));
+        if (root !== resolvedRoot)
+            throw new Error("Pi Subagent root resolver returned a non-canonical path.");
+        const rootInfo = await lstat(root);
+        if (!rootInfo.isDirectory())
+            throw new Error("Pi Subagent root must be an existing local directory.");
+        abortIfNeeded(context.signal);
+        if (input.request.tasks.some((task) => task.kind === "changeset")) {
+            await this.options.preflightHost?.({ request: input.request, cwd: input.cwd, root }, context);
+        }
+        const main = await this.options.inspectMain({ root }, context);
+        const required = new Map();
+        const addRequired = (role, modelClass) => {
+            const modelClasses = required.get(role) ?? new Set();
+            modelClasses.add(modelClass);
+            required.set(role, modelClasses);
+        };
+        for (const task of input.request.tasks) {
+            addRequired(task.role, task.modelClass);
+            if (task.kind === "changeset" && task.judgment)
+                addRequired(task.judgment.role, task.judgment.modelClass);
+        }
+        if (input.request.finalJudgment) {
+            addRequired(input.request.finalJudgment.role, input.request.finalJudgment.modelClass);
+        }
+        for (const [role, modelClasses] of required) {
+            for (const modelClass of modelClasses)
+                await this.prepareLaunch(role, modelClass, context);
+        }
+        return { root, main };
+    }
+    async acquireLaunch(role, modelClass, context) {
+        const prepared = await this.prepareLaunch(role, modelClass, context);
+        return await materializeTransientLaunch(prepared, context.signal);
+    }
+}

package/dist/process.d.ts

@@ -0,0 +1,9 @@
+type ProcessOptions = {
+    cwd: string;
+    signal: AbortSignal;
+    timeoutMs?: number;
+    stdin?: string;
+};
+/** Infrastructure errors reject; only ordinary command exits return a result. */
+export declare const runProcess: (command: string, args: string[], options: ProcessOptions) => Promise<import("@henryqw/pi-process").ExecResult>;
+export {};

package/dist/process.js

@@ -0,0 +1,11 @@
+import { spawnBounded } from "@henryqw/pi-process";
+const OUTPUT_LIMIT_BYTES = 1024 * 1024;
+/** Infrastructure errors reject; only ordinary command exits return a result. */
+export const runProcess = async (command, args, options) => await spawnBounded(command, args, {
+    cwd: options.cwd,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs ?? null,
+    ...(options.stdin === undefined ? {} : { stdin: options.stdin }),
+    stdoutLimitBytes: OUTPUT_LIMIT_BYTES,
+    stderrLimitBytes: OUTPUT_LIMIT_BYTES,
+});

package/dist/runner.d.ts

@@ -0,0 +1,356 @@
+import type { EphemeralSubagentExecutor } from "./ephemeral.ts";
+import { IntegrationGit } from "./integration-git.ts";
+import { type AllocationKind, type CheckCommand, type ChangesetTaskRequest, type CleanupKind, type ExecuteRequest, type ExecutionPolicySnapshot, type HostAllocationIntent, type HostAllocationPlan, type ModelClass, type ReviewEvidence, type ResumeRequest, type RunState, type TaskAttempt, type TaskRequest, type TaskState, type WorktreeAllocationIntent, type WorktreeAllocationPlan, type WorkspaceIdentity } from "./schema.ts";
+import { FileRunStore } from "./store.ts";
+export declare const CLEANUP_SAFETY_BUDGET_MS = 30000;
+export declare const TERMINATION_SAFETY_BUDGET_MS = 15000;
+export declare const STATUS_INSPECTION_BUDGET_MS = 5000;
+export interface OperationContext {
+    readonly signal: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly deadline?: number;
+}
+export interface CommandResult extends CheckCommand {
+    code: number;
+    killed?: boolean;
+    stdout: string;
+    stderr: string;
+}
+type AllocationFailureResult<Kind extends AllocationKind> = {
+    kind: Kind;
+    outcome: "absent";
+    failure: string;
+} | {
+    kind: Kind;
+    outcome: "unknown";
+    failure: string;
+    possibleResources?: string[];
+};
+export type WorktreeAllocationResult = {
+    kind: "worktree";
+    outcome: "owned";
+} | AllocationFailureResult<"worktree">;
+export type WorkspaceAllocationResult = {
+    kind: "workspace";
+    outcome: "owned";
+    workspaceId: string;
+    rootTabId: string;
+    rootPaneId: string;
+} | AllocationFailureResult<"workspace">;
+export type WorkerTabAllocationResult = {
+    kind: "worker_tab";
+    outcome: "owned";
+    tabId: string;
+    paneId: string;
+} | AllocationFailureResult<"worker_tab">;
+export type AgentAllocationResult = {
+    kind: "agent";
+    outcome: "owned";
+} | AllocationFailureResult<"agent">;
+export type HostAllocationResult = WorkspaceAllocationResult | WorkerTabAllocationResult | AgentAllocationResult;
+export type AllocationResult = WorktreeAllocationResult | HostAllocationResult;
+export type AllocationReconciliation<Kind extends AllocationKind = AllocationKind> = {
+    kind: Kind;
+    outcome: "absent";
+} | {
+    kind: Kind;
+    outcome: "possible";
+    failure: string;
+    possibleResources?: string[];
+};
+export type WorkerResult = {
+    outcome: "candidate";
+    candidate: WorkspaceIdentity;
+    diagnostic?: string;
+} | {
+    outcome: "blocked" | "not_prompted";
+    diagnostic: string;
+} | {
+    outcome: "unknown" | "interrupted";
+    diagnostic: string;
+};
+export interface CheckRunResult {
+    results: CommandResult[];
+    identityAfter: WorkspaceIdentity;
+}
+export interface ReviewResult {
+    verdict: string;
+    identityAfter: WorkspaceIdentity;
+}
+/** A just-in-time launch whose argv contains only an ephemeral Role prompt path. */
+export interface VerifiedLaunch {
+    readonly role: string;
+    readonly modelClass: ModelClass;
+    readonly model: string;
+    readonly thinkingLevel: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly tools: readonly string[];
+}
+export interface TransientLaunchHandle<Launch extends VerifiedLaunch = VerifiedLaunch> {
+    readonly launch: Launch;
+    cleanup(): Promise<void>;
+}
+/** Run one launch action and surface cleanup failure, including after action failure or abort. */
+export declare function withTransientLaunch<Launch extends VerifiedLaunch, Result>(handle: TransientLaunchHandle<Launch>, operation: (launch: Launch) => Promise<Result>): Promise<Result>;
+/**
+ * Productive hooks may inspect or change implementation state. Every call receives
+ * the same request abort signal. Individual I/O operations keep their own caps.
+ */
+export interface CoordinatorRuntime {
+    now(): number;
+    randomToken(): string;
+    preflight(input: {
+        request: ExecuteRequest;
+        cwd: string;
+    }, context: OperationContext): Promise<{
+        root: string;
+        main: WorkspaceIdentity;
+    }>;
+    acquireLaunch(role: string, modelClass: ModelClass, context: OperationContext): Promise<TransientLaunchHandle<VerifiedLaunch>>;
+}
+export type HostAllocationKind = Exclude<AllocationKind, "worktree">;
+export type HostCleanupKind = Extract<CleanupKind, "worker_tab" | "workspace">;
+export interface HostRuntime {
+    planHostAllocation(input: {
+        readonly requestId: ExecuteRequest["id"];
+        readonly goal: ExecuteRequest["goal"];
+        kind: HostAllocationKind;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<HostAllocationPlan>;
+    allocateHost(input: {
+        requestId: ExecuteRequest["id"];
+        intent: HostAllocationIntent;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        /** Invoked only after pane, lease, and startability checks at the final agent-start boundary. */
+        acquireLaunch?: () => Promise<TransientLaunchHandle<VerifiedLaunch>>;
+    }, context: OperationContext): Promise<HostAllocationResult>;
+    reconcileHostAllocation(input: {
+        requestId: ExecuteRequest["id"];
+        intent: HostAllocationIntent;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<AllocationReconciliation<HostAllocationKind>>;
+    runWorker(input: {
+        readonly goal: ExecuteRequest["goal"];
+        readonly contexts: readonly TextTaskContext[];
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        workerId: string;
+        kind: "initial" | "correction" | "followup";
+        preCandidate: WorkspaceIdentity;
+        failure?: string;
+        instruction?: string;
+    }, context: OperationContext): Promise<WorkerResult>;
+    terminateWorker(input: {
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        workerId: string;
+        candidate: WorkspaceIdentity;
+    }, context: OperationContext): Promise<{
+        outcome: "terminated";
+    } | {
+        outcome: "unknown";
+        failure: string;
+    }>;
+    reconcileWorkerTermination(input: {
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        workerId: string;
+        candidate: WorkspaceIdentity;
+    }, context: OperationContext): Promise<{
+        outcome: "terminated" | "active";
+    } | {
+        outcome: "unknown";
+        failure: string;
+    }>;
+    cleanupHost(input: {
+        requestId: ExecuteRequest["id"];
+        kind: HostCleanupKind;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<{
+        outcome: "completed" | "absent";
+    } | {
+        outcome: "blocked";
+        failure: string;
+    }>;
+}
+export interface TaskCandidateInspector {
+    inspectTaskCandidate(input: {
+        root: string;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
+}
+export interface InFlightTaskCandidateInspection {
+    candidate: WorkspaceIdentity;
+    clean: boolean;
+    valid: boolean;
+}
+export interface InFlightTaskCandidateInspector {
+    inspectInFlightTaskCandidate(input: {
+        root: string;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<InFlightTaskCandidateInspection>;
+}
+export interface GitRuntime {
+    inspectMain(input: {
+        root: string;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
+    allocateWorktree(input: {
+        root: string;
+        baseRoot?: string;
+        intent: WorktreeAllocationIntent;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        onPrepared(worktree: WorktreeAllocationPlan): Promise<void>;
+    }, context: OperationContext): Promise<WorktreeAllocationResult>;
+    reconcileWorktreeAllocation(input: {
+        root: string;
+        intent: WorktreeAllocationIntent;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<AllocationReconciliation<"worktree">>;
+    runChecks(input: {
+        root: string;
+        scope: "task" | "final";
+        taskId?: string;
+        attempt?: TaskAttempt;
+        checks: CheckCommand[];
+        candidate: WorkspaceIdentity;
+    }, context: OperationContext): Promise<CheckRunResult>;
+    review(input: {
+        root: string;
+        scope: "task" | "final";
+        phase: ReviewEvidence["phase"];
+        taskId?: string;
+        attempt?: TaskAttempt;
+        criterion: string;
+        base: WorkspaceIdentity;
+        tip: WorkspaceIdentity;
+        acquireLaunch(): Promise<TransientLaunchHandle<VerifiedLaunch>>;
+    }, context: OperationContext): Promise<ReviewResult>;
+    inspectRetainedTask(input: {
+        root: string;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
+}
+export type MainStatus = {
+    status: "current" | "drifted";
+    expected: WorkspaceIdentity;
+    actual: WorkspaceIdentity;
+} | {
+    status: "unavailable";
+    expected: WorkspaceIdentity;
+    failure: string;
+};
+export interface RunResponse {
+    text: string;
+    state: RunState;
+    main?: MainStatus;
+    continuation?: ResumeRequest;
+}
+export type TextTaskContext = {
+    taskId: string;
+    text: string;
+};
+/** Build one bounded changeset assignment. Call this before acquiring its Role launch. */
+export declare function buildChangesetTaskPrompt(input: {
+    readonly goal: ExecuteRequest["goal"];
+    readonly contexts: readonly TextTaskContext[];
+    task: ChangesetTaskRequest;
+    kind: "initial" | "correction" | "followup";
+    worktreeCwd: string;
+    failure?: string;
+    instruction?: string;
+}): string;
+/** Resolve completed text outputs in the consumer's declared context order. */
+export declare function resolveTextTaskContexts(state: {
+    readonly tasks: readonly TaskState[];
+}, task: Pick<TaskRequest, "id" | "contextFrom">): TextTaskContext[];
+/** Format complete context blocks or fail; prompt data is never truncated. */
+export declare function formatTextTaskContexts(contexts: readonly TextTaskContext[], maxBytes: number): string;
+/** Build a bounded text-task assignment with upstream output marked as task data. */
+export declare function buildTextTaskPrompt(goal: ExecuteRequest["goal"], task: Pick<TaskRequest, "id" | "requirements" | "deliverable">, contexts: readonly TextTaskContext[]): string;
+export declare function readyPendingTasks(state: RunState): TaskState[];
+export declare class IsolatedRunner {
+    private readonly coordinatorRuntime;
+    private readonly hostRuntime;
+    private readonly gitRuntime;
+    private readonly store;
+    private readonly integrationGit;
+    private readonly textExecutor;
+    private readonly currentPolicy;
+    private readonly productiveLifecycles;
+    private readonly followupControls;
+    constructor(coordinatorRuntime: CoordinatorRuntime, hostRuntime: HostRuntime, gitRuntime: GitRuntime & TaskCandidateInspector, store: FileRunStore | undefined, textExecutor: EphemeralSubagentExecutor, policy?: ExecutionPolicySnapshot, currentPolicy?: () => ExecutionPolicySnapshot, integrationGit?: IntegrationGit);
+    listRequests(root: string): Promise<{
+        requests: Array<{
+            id: string;
+            name: string;
+            status: string;
+            tasks: Array<{
+                id: string;
+                name: string;
+                status: string;
+                kind: string;
+            }>;
+        }>;
+        invalidIds: string[];
+    }>;
+    canFollowup(root: string, requestId: string, taskId: string): boolean;
+    drainFollowups(root: string, requestId: string, taskId: string): string[];
+    queueFollowup(root: string, requestId: string, taskId: string, instruction: string): string;
+    private withProductiveRun;
+    private withLifecycleLock;
+    private saveProductive;
+    private callProductive;
+    private rethrowStopped;
+    execute(value: unknown, cwd: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    resume(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    /** Main selects an exact retained candidate; only the owned integration checkout is writable. */
+    stage(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    private stageReceipts;
+    /** Only Main can validate/promote the exact selected, clean combined tip. */
+    integrate(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    private releaseRejected;
+    private releaseSuperseded;
+    private cleanupPromoted;
+    private requireExactIntegration;
+    abort(id: string, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    status(id: string, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    private run;
+    private dispatchTask;
+    private dispatchTextTask;
+    private correctionAllowed;
+    private driveWorkerSafely;
+    private driveWorker;
+    private terminationCandidate;
+    private terminateWithSafety;
+    private runCheckBatch;
+    private runReview;
+    private retainCandidate;
+    private verifyRetainedTask;
+    private retry;
+    private finalize;
+    private runFinal;
+    private markFinalFailed;
+    private markSuperseded;
+    private recoverInterrupted;
+    private ensureFollowupControl;
+    private controlKey;
+    private activeControl;
+    private activeControls;
+    private hasActiveControl;
+    private hasAnyActiveControl;
+    private closeFollowupControl;
+    private closeRequestControls;
+    private attention;
+    private response;
+}
+export {};