@hheei/pi-subagents 0.1.2

package/dist/runtime.d.ts

@@ -0,0 +1,22 @@
+import type { SubagentRecord } from "./domain.js";
+import type { RunnerLike } from "./manager.js";
+import type { SubagentRegistry } from "./registry.js";
+export interface RuntimeTokenStore {
+    remember(runtimeIdentity: string, token: string): void;
+    get(runtimeIdentity: string): string | undefined;
+    forget(runtimeIdentity: string): void;
+    clear(): void;
+}
+export interface LaunchDetachedRunnerOptions {
+    readonly registry: SubagentRegistry;
+    readonly record: SubagentRecord;
+    readonly tokens: RuntimeTokenStore;
+    readonly signal?: AbortSignal;
+}
+export declare function createRuntimeTokenStore(): RuntimeTokenStore;
+/** Starts the package runner as a detached process and returns its authenticated controller. */
+export declare function launchDetachedRunner(options: LaunchDetachedRunnerOptions): Promise<RunnerLike>;
+/** Reconnects to a surviving writer, launching a replacement only after its PID is confirmed dead. */
+export declare function recoverDetachedRunner(options: LaunchDetachedRunnerOptions): Promise<RunnerLike>;
+export declare function isRecordedRunnerConfirmedDead(record: SubagentRecord): Promise<boolean>;
+export declare function isPidConfirmedDead(pid: number): boolean;

package/dist/runtime.js

@@ -0,0 +1,253 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { connectWithRetry, RunnerConnection } from "./connector.js";
+import { buildLaunchSpec, withBridgeToken } from "./launch-spec.js";
+import { planSessionPlacement } from "./session-bootstrap.js";
+function runtimeDirectory() {
+    const user = typeof process.getuid === "function" ? process.getuid() : "user";
+    return join(tmpdir(), `pi-subagents-${user}`);
+}
+export function createRuntimeTokenStore() {
+    const tokens = new Map();
+    return {
+        remember(runtimeIdentity, token) {
+            tokens.set(runtimeIdentity, token);
+        },
+        get(runtimeIdentity) {
+            return tokens.get(runtimeIdentity);
+        },
+        forget(runtimeIdentity) {
+            tokens.delete(runtimeIdentity);
+        },
+        clear() {
+            tokens.clear();
+        },
+    };
+}
+/** Starts the package runner as a detached process and returns its authenticated controller. */
+export async function launchDetachedRunner(options) {
+    const record = await requireCurrentRecord(options.registry, options.record.subagentId, options.signal);
+    const prepared = await claimRuntime(options.registry, record, "replacement", undefined, undefined, options.signal);
+    return startClaimedRunner(options.registry, prepared.record, prepared.identity, prepared.token, prepared.claim.claimId, options.signal, options.tokens);
+}
+/** Reconnects to a surviving writer, launching a replacement only after its PID is confirmed dead. */
+export async function recoverDetachedRunner(options) {
+    let record = await requireCurrentRecord(options.registry, options.record.subagentId, options.signal);
+    if (record.intent === "stopped")
+        throw new Error(`Child ${record.subagentId} is stopped`);
+    record = await clearDeadHolderClaim(options.registry, record, options.signal);
+    if (record.runtime !== undefined) {
+        const prepared = await claimRuntime(options.registry, record, "reconnect", record.runtime.runtimeIdentity, record.claim?.claimId, options.signal);
+        const connection = new RunnerConnection({
+            endpoint: prepared.identity.endpoint,
+            identity: prepared.identity,
+            token: prepared.token,
+            role: "recovery",
+            claimId: prepared.claim.claimId,
+        });
+        try {
+            await connectWithRetry(connection, {
+                attempts: 20,
+                delayMs: 50,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            });
+            rememberClaimedToken(options.tokens, record, prepared.identity.runtimeIdentity, prepared.token);
+            return connection;
+        }
+        catch (error) {
+            connection.close();
+            const afterFailure = await requireCurrentRecord(options.registry, record.subagentId, options.signal);
+            if (afterFailure.claim?.claimId !== prepared.claim.claimId) {
+                throw new Error(`Recovery authorization for ${record.subagentId} was consumed before the connection completed`, { cause: error });
+            }
+            if (!(await isRecordedRunnerConfirmedDead(afterFailure))) {
+                await options.registry.releaseClaim(record.subagentId, prepared.claim.claimId, options.signal);
+                throw new Error(`Runner ${record.subagentId} could not be reconnected and is not confirmed dead; replacement refused`, { cause: error });
+            }
+            record = afterFailure;
+        }
+    }
+    const expectedRuntimeIdentity = record.runtime?.runtimeIdentity;
+    record = await refreshSessionPlacement(options.registry, record, options.signal);
+    const prepared = await claimRuntime(options.registry, record, "replacement", expectedRuntimeIdentity, record.claim?.claimId, options.signal);
+    return startClaimedRunner(options.registry, prepared.record, prepared.identity, prepared.token, prepared.claim.claimId, options.signal, options.tokens);
+}
+async function claimRuntime(registry, record, kind, expectedRuntimeIdentity, expectedClaimId, signal) {
+    const runtimeIdentity = kind === "reconnect" ? expectedRuntimeIdentity : randomUUID();
+    if (runtimeIdentity === undefined)
+        throw new Error("Reconnect requires a runtime identity");
+    const token = randomBytes(32).toString("hex");
+    const directory = runtimeDirectory();
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    const endpoint = kind === "reconnect" && record.runtime !== undefined
+        ? record.runtime.endpoint
+        : join(directory, `${record.subagentId}-${runtimeIdentity.slice(0, 12)}.sock`);
+    const claim = {
+        claimId: randomUUID(),
+        kind,
+        holderPid: process.pid,
+        runtimeIdentity,
+        endpoint,
+        controllerTokenHash: createHash("sha256").update(token).digest("hex"),
+    };
+    const claimed = await registry.claim(record.subagentId, record.revision, claim, expectedRuntimeIdentity, expectedClaimId, signal);
+    return {
+        record: claimed,
+        identity: {
+            parentSessionId: claimed.parentSessionId,
+            subagentId: claimed.subagentId,
+            runtimeIdentity,
+            endpoint,
+            token,
+        },
+        token,
+        claim,
+    };
+}
+async function startClaimedRunner(registry, record, identity, token, claimId, signal, tokens) {
+    const launch = buildLaunchSpec({
+        config: record.launchConfig,
+        invocation: record.launchConfig.invocation,
+        mode: "rpc",
+        persistence: record.persistence,
+        bridge: {
+            parentSessionId: identity.parentSessionId,
+            subagentId: identity.subagentId,
+            runtimeIdentity: identity.runtimeIdentity,
+            endpoint: identity.endpoint,
+        },
+    });
+    const directory = runtimeDirectory();
+    const jobPath = join(directory, `${record.subagentId}-${identity.runtimeIdentity}.json`);
+    const job = {
+        invocation: { command: launch.command, args: launch.argv },
+        cwd: launch.cwd,
+        sessionId: record.sessionId,
+        ...(record.sessionPath === undefined ? {} : { sessionPath: record.sessionPath }),
+        claimId,
+        env: launch.env,
+    };
+    let child;
+    const connection = new RunnerConnection({ endpoint: identity.endpoint, identity, token });
+    try {
+        await writeFile(jobPath, `${JSON.stringify(job)}\n`, { mode: 0o600, flag: "wx" });
+        const runnerEntry = fileURLToPath(new URL("./runner-entry.js", import.meta.url));
+        child = spawn(process.execPath, [runnerEntry, "--job", jobPath], {
+            cwd: launch.cwd,
+            detached: true,
+            env: { ...process.env, ...withBridgeToken(launch.env, token) },
+            stdio: "ignore",
+        });
+        if (child.pid === undefined)
+            throw new Error(`Runner process for ${record.subagentId} has no PID`);
+        await registry.markClaimRunner(record.subagentId, claimId, child.pid, signal);
+        child.unref();
+        await connectWithRetry(connection, {
+            attempts: 120,
+            delayMs: 50,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        await unlink(jobPath).catch(() => undefined);
+        rememberClaimedToken(tokens, record, identity.runtimeIdentity, token);
+        return connection;
+    }
+    catch (error) {
+        connection.close();
+        child?.kill("SIGTERM");
+        await unlink(jobPath).catch(() => undefined);
+        const current = await registry.get(record.subagentId).catch(() => undefined);
+        if (current?.claim?.claimId === claimId) {
+            await registry.releaseClaim(record.subagentId, claimId).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+function rememberClaimedToken(tokens, record, runtimeIdentity, token) {
+    const previous = record.runtime?.runtimeIdentity;
+    tokens.remember(runtimeIdentity, token);
+    if (previous !== undefined && previous !== runtimeIdentity)
+        tokens.forget(previous);
+}
+async function requireCurrentRecord(registry, id, signal) {
+    const record = await registry.get(id, signal);
+    if (record === undefined)
+        throw new Error(`Child ${id} disappeared from the registry`);
+    return record;
+}
+async function refreshSessionPlacement(registry, record, signal) {
+    const placement = await planSessionPlacement({
+        sessionId: record.sessionId,
+        cwd: record.cwd,
+        sessionDir: record.launchConfig.sessionDir,
+        persistence: record.persistence,
+        ...(record.sessionPath === undefined ? {} : { sessionPath: record.sessionPath }),
+    });
+    if (placement.persistence === record.persistence &&
+        placement.sessionPath === record.sessionPath) {
+        return record;
+    }
+    return registry.update(record.subagentId, record.revision, (current) => ({
+        ...current,
+        persistence: placement.persistence,
+        ...(placement.sessionPath === undefined
+            ? {}
+            : {
+                sessionPath: placement.sessionPath,
+                launchConfig: { ...current.launchConfig, sessionPath: placement.sessionPath },
+            }),
+    }), record.runtime?.runtimeIdentity, signal);
+}
+async function clearDeadHolderClaim(registry, record, signal) {
+    const claim = record.claim;
+    if (claim === undefined)
+        return record;
+    if (!isPidConfirmedDead(claim.holderPid)) {
+        throw new Error(`Child ${record.subagentId} is already claimed by a live or unknown owner`);
+    }
+    if (claim.runnerPid !== undefined && !isPidConfirmedDead(claim.runnerPid)) {
+        throw new Error(`Child ${record.subagentId} has a live or unknown claimed runner`);
+    }
+    return registry.releaseClaim(record.subagentId, claim.claimId, signal);
+}
+export async function isRecordedRunnerConfirmedDead(record) {
+    const runtime = record.runtime;
+    if (runtime?.pid === undefined)
+        return false;
+    if (process.platform !== "linux")
+        return isPidConfirmedDead(runtime.pid);
+    try {
+        const environment = await readFile(`/proc/${runtime.pid}/environ`, "utf8");
+        const identity = environment
+            .split("\0")
+            .filter(Boolean)
+            .map((entry) => {
+            const separator = entry.indexOf("=");
+            return [entry.slice(0, separator), entry.slice(separator + 1)];
+        })
+            .find(([key]) => key === "PI_SUBAGENTS_RUNTIME_ID")?.[1];
+        return identity !== runtime.runtimeIdentity;
+    }
+    catch (error) {
+        return isErrno(error, "ENOENT");
+    }
+}
+export function isPidConfirmedDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return isErrno(error, "ESRCH");
+    }
+}
+function isErrno(value, code) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "code" in value &&
+        value.code === code);
+}

package/dist/session-bootstrap.d.ts

@@ -0,0 +1,69 @@
+import type { ModelRegistryLike, ParentAgentDefaults } from "./agent-resolver.js";
+import type { EffectiveLaunchConfig, ExecutionMode, PersistenceState, PiInvocation, SpawnSubagentInput, SubagentRecord } from "./domain.js";
+import type { SubagentRegistry } from "./registry.js";
+export interface SessionPlacement {
+    readonly sessionId: string;
+    readonly sessionDir: string;
+    /** Present only when a durable session file already exists for this id. */
+    readonly sessionPath?: string;
+    readonly persistence: PersistenceState;
+}
+export interface PlanSessionPlacementOptions {
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly sessionDir?: string;
+    readonly sessionPath?: string;
+    readonly persistence?: PersistenceState;
+}
+export interface SessionFileIdentity {
+    readonly sessionId: string;
+    readonly cwd: string;
+}
+/**
+ * The Pi session directory a child would use by default for its cwd. It is asked
+ * of Pi itself instead of re-deriving the layout, and is always passed to the child
+ * as an explicit `--session-dir` so recovery can find the file again.
+ */
+export declare function resolveDefaultSessionDir(cwd: string): string;
+/** Verifies that a durable session file exists and still carries the expected identity. */
+export declare function inspectSessionFile(path: string, sessionId: string): Promise<SessionFileIdentity>;
+/** Finds an already-flushed session file for an id. Empty files are not sessions yet. */
+export declare function findSessionFile(sessionDir: string, sessionId: string): Promise<string | undefined>;
+/**
+ * Decides whether a child session is already durable. A never-flushed session keeps
+ * its recorded id and gets no path, so nothing can open an absent path and mint a
+ * random id; a flushed session must still prove its identity on disk.
+ */
+export declare function planSessionPlacement(options: PlanSessionPlacementOptions): Promise<SessionPlacement>;
+export declare function createSubagentId(): string;
+export interface ResolveSubagentLaunchOptions {
+    readonly input: SpawnSubagentInput;
+    /** Parent agent cwd, used when the tool call does not ask for another one. */
+    readonly cwd: string;
+    readonly parent: ParentAgentDefaults;
+    readonly modelRegistry: ModelRegistryLike;
+    readonly invocation?: PiInvocation;
+    readonly bridgeExtensionPath?: string;
+    readonly homeDirectory?: string;
+    readonly subagentId?: string;
+    readonly sessionId?: string;
+}
+/**
+ * One resolution chain for a spawn: agent definition + explicit parent defaults
+ * become a single immutable, non-secret launch configuration. Child and session ids
+ * are minted here, before any process exists.
+ */
+export declare function resolveSubagentLaunch(options: ResolveSubagentLaunchOptions): Promise<EffectiveLaunchConfig>;
+export interface PersistSubagentIntentOptions {
+    readonly registry: SubagentRegistry;
+    readonly parentSessionId: string;
+    readonly task: string;
+    readonly launchConfig: EffectiveLaunchConfig;
+    readonly mode?: ExecutionMode;
+    readonly now?: () => Date;
+}
+/**
+ * Writes the spawn intent before anything is launched. Registry failure propagates,
+ * so a child is never started from intent that could not be recovered.
+ */
+export declare function persistSubagentIntent(options: PersistSubagentIntentOptions): Promise<SubagentRecord>;

package/dist/session-bootstrap.js

@@ -0,0 +1,195 @@
+import { randomUUID } from "node:crypto";
+import { open, readdir, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { resolveAgent } from "./agent-resolver.js";
+import { isRecord, isSessionId } from "./domain.js";
+import { assembleChildPrompt, resolveBridgeExtensionPath, resolvePiInvocation, } from "./launch-spec.js";
+/** Bounded read for a session header; the first line holds the whole identity of the file. */
+const HEADER_READ_BYTES = 64 * 1024;
+/**
+ * The Pi session directory a child would use by default for its cwd. It is asked
+ * of Pi itself instead of re-deriving the layout, and is always passed to the child
+ * as an explicit `--session-dir` so recovery can find the file again.
+ */
+export function resolveDefaultSessionDir(cwd) {
+    return SessionManager.create(cwd).getSessionDir();
+}
+async function readSessionHeader(path) {
+    const handle = await open(path, "r");
+    try {
+        const buffer = Buffer.alloc(HEADER_READ_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, HEADER_READ_BYTES, 0);
+        const chunk = buffer.subarray(0, bytesRead).toString("utf8");
+        const end = chunk.indexOf("\n");
+        const line = (end === -1 ? chunk : chunk.slice(0, end)).trim();
+        if (line === "") {
+            throw new Error(`Session file ${path} has no header`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`Session file ${path} has an unreadable header`, { cause: error });
+        }
+        if (!isRecord(parsed) || parsed.type !== "session") {
+            throw new Error(`Session file ${path} is not a Pi session`);
+        }
+        if (typeof parsed.id !== "string" || !isSessionId(parsed.id)) {
+            throw new Error(`Session file ${path} has an invalid session id`);
+        }
+        return { sessionId: parsed.id, cwd: typeof parsed.cwd === "string" ? parsed.cwd : "" };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Verifies that a durable session file exists and still carries the expected identity. */
+export async function inspectSessionFile(path, sessionId) {
+    const header = await readSessionHeader(path);
+    if (header.sessionId !== sessionId) {
+        throw new Error(`Session file ${path} belongs to session ${header.sessionId}, not ${sessionId}`);
+    }
+    return header;
+}
+/** Finds an already-flushed session file for an id. Empty files are not sessions yet. */
+export async function findSessionFile(sessionDir, sessionId) {
+    let names;
+    try {
+        names = await readdir(sessionDir);
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const candidates = names
+        .filter((name) => name === `${sessionId}.jsonl` || name.endsWith(`_${sessionId}.jsonl`))
+        .sort((left, right) => left.localeCompare(right));
+    for (const name of candidates) {
+        const path = join(sessionDir, name);
+        const info = await stat(path);
+        if (info.size === 0)
+            continue;
+        await inspectSessionFile(path, sessionId);
+        return path;
+    }
+    return undefined;
+}
+/**
+ * Decides whether a child session is already durable. A never-flushed session keeps
+ * its recorded id and gets no path, so nothing can open an absent path and mint a
+ * random id; a flushed session must still prove its identity on disk.
+ */
+export async function planSessionPlacement(options) {
+    if (!isSessionId(options.sessionId)) {
+        throw new Error(`Invalid session id ${options.sessionId}`);
+    }
+    const sessionDir = options.sessionDir ?? resolveDefaultSessionDir(options.cwd);
+    const sessionPath = options.sessionPath;
+    if (sessionPath !== undefined &&
+        (await stat(sessionPath).then(() => true, () => false))) {
+        await inspectSessionFile(sessionPath, options.sessionId);
+        return { sessionId: options.sessionId, sessionDir, sessionPath, persistence: "flushed" };
+    }
+    if (sessionPath !== undefined && options.persistence === "flushed") {
+        throw new Error(`Recorded session file is missing: ${sessionPath}`);
+    }
+    const discovered = await findSessionFile(sessionDir, options.sessionId);
+    if (discovered !== undefined) {
+        return {
+            sessionId: options.sessionId,
+            sessionDir,
+            sessionPath: discovered,
+            persistence: "flushed",
+        };
+    }
+    return { sessionId: options.sessionId, sessionDir, persistence: "never_flushed" };
+}
+export function createSubagentId() {
+    return `sa_${randomUUID().replace(/-/gu, "").slice(0, 12)}`;
+}
+/**
+ * One resolution chain for a spawn: agent definition + explicit parent defaults
+ * become a single immutable, non-secret launch configuration. Child and session ids
+ * are minted here, before any process exists.
+ */
+export async function resolveSubagentLaunch(options) {
+    const task = options.input.task.trim();
+    if (task === "")
+        throw new Error("spawn_subagent requires a non-empty task");
+    const name = options.input.agent?.trim();
+    if (name === undefined || name === "") {
+        throw new Error("spawn_subagent requires an explicit agent name; V1 has no built-in default agent");
+    }
+    const cwd = resolve(options.input.cwd?.trim() || options.cwd);
+    const subagentId = options.subagentId ?? createSubagentId();
+    const sessionId = options.sessionId ?? randomUUID();
+    const bridgeExtensionPath = options.bridgeExtensionPath ?? resolveBridgeExtensionPath();
+    const policy = await resolveAgent({
+        name,
+        cwd,
+        modelRegistry: options.modelRegistry,
+        parent: options.parent,
+        bridgeExtensionPath,
+        ...(options.homeDirectory === undefined ? {} : { homeDirectory: options.homeDirectory }),
+    });
+    return Object.freeze({
+        subagentId,
+        invocation: options.invocation ?? resolvePiInvocation(),
+        cwd,
+        sessionId,
+        sessionDir: resolveDefaultSessionDir(cwd),
+        agent: policy.agent,
+        model: policy.model,
+        thinking: policy.thinking,
+        tools: policy.tools,
+        excludeTools: policy.excludeTools,
+        extensions: policy.extensions,
+        skills: policy.skills,
+        prompt: assembleChildPrompt(policy.agent.instructions),
+        bridgeExtensionPath,
+        interactive: policy.interactive,
+    });
+}
+/**
+ * Writes the spawn intent before anything is launched. Registry failure propagates,
+ * so a child is never started from intent that could not be recovered.
+ */
+export async function persistSubagentIntent(options) {
+    const task = options.task.trim();
+    if (task === "")
+        throw new Error("Cannot persist a spawn intent without a task");
+    if (options.registry.parentSessionId !== options.parentSessionId) {
+        throw new Error(`Registry belongs to parent session ${options.registry.parentSessionId}, not ${options.parentSessionId}`);
+    }
+    const { launchConfig } = options;
+    const placement = await planSessionPlacement({
+        sessionId: launchConfig.sessionId,
+        cwd: launchConfig.cwd,
+        sessionDir: launchConfig.sessionDir,
+        ...(launchConfig.sessionPath === undefined ? {} : { sessionPath: launchConfig.sessionPath }),
+    });
+    const timestamp = (options.now ?? (() => new Date()))().toISOString();
+    return options.registry.create({
+        subagentId: launchConfig.subagentId,
+        parentSessionId: options.parentSessionId,
+        revision: 1,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        sessionId: placement.sessionId,
+        ...(placement.sessionPath === undefined ? {} : { sessionPath: placement.sessionPath }),
+        cwd: launchConfig.cwd,
+        initialTask: task,
+        intent: "active",
+        state: "starting",
+        mode: options.mode ?? "rpc",
+        persistence: placement.persistence,
+        launchConfig: Object.freeze({
+            ...launchConfig,
+            ...(placement.sessionPath === undefined ? {} : { sessionPath: placement.sessionPath }),
+        }),
+        unacknowledgedInput: task,
+    });
+}

package/dist/state.d.ts

@@ -0,0 +1,15 @@
+import type { SubagentState, UsageSummary } from "./domain.js";
+export interface StateSnapshot {
+    readonly state: SubagentState;
+    readonly summary?: string;
+    readonly interrupted?: string;
+    readonly usage: UsageSummary;
+}
+export interface StateProjector {
+    applyEvent(event: unknown): StateSnapshot;
+    rebuild(entries: readonly unknown[]): StateSnapshot;
+    snapshot(): StateSnapshot;
+}
+export declare function summarizeCurrentBranch(entries: readonly unknown[]): string | undefined;
+export declare function aggregateUsage(entries: readonly unknown[]): UsageSummary;
+export declare function createStateProjector(initialState?: SubagentState): StateProjector;