@hheei/pi-subagents 0.1.2 → 0.2.3

package/dist/runtime.js

@@ -1,253 +1,227 @@
-import { spawn } from "node:child_process";
-import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+/**
+ * Runtime plumbing for a child Pi process that this parent owns.
+ *
+ * There is no supervisor: a background child is a child process of this Pi, and a child that runs in
+ * a host panel is owned by that host. Either way the parent's bridge socket is what the child dials,
+ * so "is this child alive?" is answered by a bridge connection, and the runtime metadata in the
+ * registry only records which runtime and endpoint a child was last launched with.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync } from "node:fs";
+import { chmod, mkdir, rename, 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 { errorMessage } from "@hheei/pi-ext-core";
+import { spawnChildRuntime } from "./child-process.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();
+/**
+ * The one socket a parent session listens on. A child dials this path, so a parent that restarts
+ * re-listens in the same place and a surviving child reconnects instead of being rebuilt.
+ */
+export function parentBridgeEndpoint(parentSessionId) {
+    return join(runtimeDirectory(), `parent-${parentSessionId}.sock`);
+}
+/**
+ * Every parent session keeps its own token file. One shared file is rewritten wholesale by whichever
+ * parent saved last, so two parent sessions in the same runtime directory would erase each other's
+ * credentials and a child that survived a restart could no longer authorize itself.
+ */
+export function parentTokenFile(parentSessionId) {
+    return join(runtimeDirectory(), `tokens-${parentSessionId}.json`);
+}
+/**
+ * Tokens outlive the parent process: a child that survived (a panel child, or one whose parent was
+ * killed) reconnects with the token it was launched with, and a restarted parent must be able to
+ * authorize it without holding the old process's memory. The store is a 0600 file in the 0700
+ * runtime directory; the registry never sees a token.
+ */
+export function createRuntimeTokenStore(options) {
+    const file = options.file ?? parentTokenFile(options.parentSessionId);
+    const diagnose = options.diagnose ?? (() => { });
+    const tokens = new Map(readStoredTokens(file, diagnose));
+    let writing = Promise.resolve();
+    const persist = () => {
+        const payload = `${JSON.stringify(Object.fromEntries(tokens))}\n`;
+        writing = writing
+            .then(async () => {
+            mkdirSync(runtimeDirectory(), { recursive: true, mode: 0o700 });
+            // Writing in place truncates the file first, and a parent killed inside that window would
+            // leave every surviving child locked out of the bridge. The swap is atomic instead.
+            const temporary = `${file}.${process.pid}.tmp`;
+            await writeFile(temporary, payload, { mode: 0o600 });
+            await rename(temporary, file);
+        })
+            .catch((error) => {
+            diagnose(`could not persist bridge tokens: ${errorMessage(error)}`);
+        });
+    };
     return {
         remember(runtimeIdentity, token) {
             tokens.set(runtimeIdentity, token);
+            persist();
         },
         get(runtimeIdentity) {
             return tokens.get(runtimeIdentity);
         },
         forget(runtimeIdentity) {
-            tokens.delete(runtimeIdentity);
-        },
-        clear() {
-            tokens.clear();
+            if (tokens.delete(runtimeIdentity))
+                persist();
         },
     };
 }
-/** 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;
-        }
+function readStoredTokens(file, diagnose) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT")
+            diagnose(`could not read bridge tokens: ${errorMessage(error)}`);
+        return [];
+    }
+    if (raw.trim() === "")
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        diagnose(`bridge token file is not valid JSON: ${errorMessage(error)}`);
+        return [];
     }
-    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);
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    return Object.entries(parsed).filter((entry) => typeof entry[1] === "string");
 }
-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");
+/**
+ * Mints the runtime identity and its bridge token, remembers the token so the child's very first
+ * hello can be authorized, and builds the one LaunchSpec for this presentation. The token travels
+ * in the spec's environment, because who starts the child differs: the parent starts a background
+ * child and the host starts a panel one.
+ */
+function planChildRuntime(record, tokens, presentation) {
+    const runtimeIdentity = randomUUID();
     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({
+    const endpoint = parentBridgeEndpoint(record.parentSessionId);
+    const spec = buildLaunchSpec({
         config: record.launchConfig,
         invocation: record.launchConfig.invocation,
-        mode: "rpc",
+        presentation,
         persistence: record.persistence,
         bridge: {
-            parentSessionId: identity.parentSessionId,
-            subagentId: identity.subagentId,
-            runtimeIdentity: identity.runtimeIdentity,
-            endpoint: identity.endpoint,
+            parentSessionId: record.parentSessionId,
+            subagentId: record.subagentId,
+            runtimeIdentity,
+            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);
+    return { runtimeIdentity, endpoint, spec: { ...spec, env: withBridgeToken(spec.env, token) } };
 }
-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;
+/** Evidence first: the record names the runtime that was asked for even if starting it fails. */
+async function recordRuntimeEvidence(registry, record, plan) {
+    await registry.update(record.subagentId, undefined, (current) => ({
+        ...current,
+        runtime: { runtimeIdentity: plan.runtimeIdentity, endpoint: plan.endpoint },
+    }));
 }
-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 }),
+/**
+ * Starts one headless child Pi and waits for it to connect. Nothing is driven over its stdio: the
+ * process gets the parent's socket path and its own runtime token in the environment, and the
+ * bridge is the only control channel. A child that never connects is terminated here rather than
+ * left running with no way to reach it.
+ */
+export async function launchChild(options) {
+    const record = options.record;
+    const plan = planChildRuntime(record, options.tokens, "background");
+    await recordRuntimeEvidence(options.registry, record, plan);
+    const runtime = spawnChildRuntime({
+        command: plan.spec.command,
+        args: plan.spec.argv,
+        cwd: plan.spec.cwd,
+        env: { ...process.env, ...plan.spec.env },
+        ...(options.diagnose === undefined ? {} : { diagnose: options.diagnose }),
     });
-    if (placement.persistence === record.persistence &&
-        placement.sessionPath === record.sessionPath) {
-        return record;
+    let connected;
+    try {
+        connected = await options.waitForBridge(record.subagentId, options.signal);
     }
-    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`);
+    catch (error) {
+        options.diagnose?.(`bridge wait failed: ${errorMessage(error)}`);
+        connected = false;
     }
-    if (claim.runnerPid !== undefined && !isPidConfirmedDead(claim.runnerPid)) {
-        throw new Error(`Child ${record.subagentId} has a live or unknown claimed runner`);
+    if (connected)
+        return { handle: runtime };
+    await runtime.terminate();
+    if (runtime.alive) {
+        // The process outlived termination, so it is not gone and the caller keeps the handle: it is
+        // the only thing that can try again.
+        return {
+            handle: runtime,
+            failure: `Child ${record.subagentId} never connected to the parent bridge and did not stop (it may still be running)`,
+        };
     }
-    return registry.releaseClaim(record.subagentId, claim.claimId, signal);
+    options.tokens.forget(plan.runtimeIdentity);
+    return { failure: `Child ${record.subagentId} never connected to the parent bridge` };
 }
-export async function isRecordedRunnerConfirmedDead(record) {
-    const runtime = record.runtime;
-    if (runtime?.pid === undefined)
-        return false;
-    if (process.platform !== "linux")
-        return isPidConfirmedDead(runtime.pid);
+/**
+ * Opens one child in a host panel and waits for it to connect. The host owns this process, so the
+ * parent holds no runtime handle for it; a panel that never yields a bridge is closed again instead
+ * of being left as a process nobody can control.
+ */
+export async function openChildPanel(options) {
+    const record = options.record;
+    const plan = planChildRuntime(record, options.tokens, "panel");
+    await recordRuntimeEvidence(options.registry, record, plan);
+    let attachment;
     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;
+        attachment = await options.host.open(plan.spec);
     }
     catch (error) {
-        return isErrno(error, "ENOENT");
+        // Opening is not atomic: the host may have created the panel and started the process before
+        // failing to report it. The token is kept so a child that does come up can still be adopted,
+        // and the caller is told the runtime is unconfirmed instead of that nothing was started.
+        return {
+            unconfirmed: true,
+            failure: `Child ${record.subagentId} could not be opened in a ${options.host.kind} panel (${errorMessage(error)}); a panel may have been created, so stop the child before sending again`,
+        };
     }
-}
-export function isPidConfirmedDead(pid) {
+    let connected;
     try {
-        process.kill(pid, 0);
-        return false;
+        connected = await options.waitForBridge(record.subagentId, options.signal);
     }
     catch (error) {
-        return isErrno(error, "ESRCH");
+        options.diagnose?.(`bridge wait failed: ${errorMessage(error)}`);
+        connected = false;
+    }
+    if (connected)
+        return { handle: attachment };
+    // The child never dialed in, so the panel is closed again — and only a host that confirms it is
+    // gone counts. While it may still run, the caller keeps the handle and the token: the handle is
+    // what stops a second runtime from being started for the same session, and the token is what lets
+    // a child that does come up be adopted instead of lingering as a process nobody owns.
+    const cleanup = await attachment.cleanup();
+    const observed = await attachment.observe();
+    if (!(observed.known && !observed.alive)) {
+        return {
+            handle: attachment,
+            failure: `Child ${record.subagentId} never connected to the parent bridge and its panel could not be closed (${cleanup.stderr || "its state could not be observed"}); close it manually`,
+        };
     }
+    options.tokens.forget(plan.runtimeIdentity);
+    return { failure: `Child ${record.subagentId} never connected to the parent bridge` };
 }
-function isErrno(value, code) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "code" in value &&
-        value.code === code);
+/** Creates the runtime directory if needed; the socket itself is 0600 in a 0700 directory. */
+export async function prepareRuntimeDirectory(diagnose) {
+    const directory = runtimeDirectory();
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700).catch((error) => {
+        diagnose?.(`could not restrict the runtime directory: ${errorMessage(error)}`);
+    });
+    return directory;
 }

package/dist/session-bootstrap.d.ts

@@ -1,5 +1,5 @@
-import type { ModelRegistryLike, ParentAgentDefaults } from "./agent-resolver.js";
-import type { EffectiveLaunchConfig, ExecutionMode, PersistenceState, PiInvocation, SpawnSubagentInput, SubagentRecord } from "./domain.js";
+import type { ModelRegistryLike, ParentAgentDefaults, SkillCatalogEntry } from "./agent-resolver.js";
+import type { EffectiveLaunchConfig, PersistenceState, PiInvocation, Presentation, SpawnSubagentInput, SubagentRecord } from "./domain.js";
 import type { SubagentRegistry } from "./registry.js";
 export interface SessionPlacement {
     readonly sessionId: string;
@@ -20,11 +20,18 @@ export interface SessionFileIdentity {
     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.
+ * The session directory Pi itself would use for this cwd. At the top level it holds the
+ * human's own sessions, which is why children never write there directly.
  */
 export declare function resolveDefaultSessionDir(cwd: string): string;
+/**
+ * The session directory a delegated child writes to.
+ *
+ * Pi discovers sessions with a non-recursive `readdir` of the session directory, so a
+ * subdirectory keeps delegated sessions out of the human's session list while the child still
+ * receives that directory as an explicit `--session-dir` recovery can find again.
+ */
+export declare function resolveSubagentSessionDir(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. */
@@ -35,18 +42,27 @@ export declare function findSessionFile(sessionDir: string, sessionId: string):
  * 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 declare function resetSubagentIdCounter(value?: number): void;
+export declare function createSubagentId(existingIds?: readonly string[]): 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;
+    /** Parent's loaded skills, the catalog this launch's skill names resolve against. */
+    readonly skillCatalog?: readonly SkillCatalogEntry[];
+    /** Diagnostics for the caller to surface; omitted means they are dropped. */
+    readonly onWarning?: (message: string) => void;
     readonly invocation?: PiInvocation;
     readonly bridgeExtensionPath?: string;
     readonly homeDirectory?: string;
     readonly subagentId?: string;
     readonly sessionId?: string;
+    readonly existingSubagentIds?: readonly string[];
+    readonly enforceEnabled?: boolean;
+    readonly sessionPath?: string;
+    readonly referencedSessionPath?: string;
 }
 /**
  * One resolution chain for a spawn: agent definition + explicit parent defaults
@@ -59,7 +75,7 @@ export interface PersistSubagentIntentOptions {
     readonly parentSessionId: string;
     readonly task: string;
     readonly launchConfig: EffectiveLaunchConfig;
-    readonly mode?: ExecutionMode;
+    readonly presentation?: Presentation;
     readonly now?: () => Date;
 }
 /**