@hheei/pi-subagents 0.1.2 → 0.2.2

package/dist/registry.js

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { readJsonSettingsRoot, updateJsonSettingsRoot } from "@hheei/pi-ext-core";
-import { isExecutionMode, isLaunchValueSource, isPersistenceState, isRecord, isSessionId, isSubagentIntent, isSubagentState, isThinkingLevel, REGISTRY_VERSION, } from "./domain.js";
+import { isRecord, readJsonSettingsRoot, updateJsonSettingsRoot } from "@hheei/pi-ext-core";
+import { isLaunchValueSource, isPersistenceState, isPresentation, isSessionId, isSubagentIntent, isSubagentState, isThinkingLevel, normalizeSubagentState, REGISTRY_VERSION, } from "./domain.js";
 export class SubagentRegistryError extends Error {
     code;
     constructor(code, message) {
@@ -31,15 +31,15 @@ const RECORD_FIELDS = {
     initialTask: true,
     intent: true,
     state: true,
-    mode: true,
+    presentation: true,
     persistence: true,
     launchConfig: true,
     runtime: true,
     latestSummary: true,
+    activeTool: true,
     usage: true,
     interrupted: true,
     unacknowledgedInput: true,
-    claim: true,
 };
 const LAUNCH_CONFIG_FIELDS = {
     subagentId: true,
@@ -58,6 +58,10 @@ const LAUNCH_CONFIG_FIELDS = {
     prompt: true,
     bridgeExtensionPath: true,
     interactive: true,
+    title: true,
+    task: true,
+    referencedSessionPath: true,
+    codemodeOnly: true,
 };
 const AGENT_FIELDS = {
     name: true,
@@ -71,16 +75,7 @@ const INVOCATION_FIELDS = { command: true, args: true };
 const MODEL_FIELDS = { provider: true, id: true, source: true };
 const THINKING_FIELDS = { level: true, source: true };
 const SELECTION_FIELDS = { discovery: true, paths: true };
-const RUNTIME_FIELDS = { runtimeIdentity: true, endpoint: true, pid: true };
-const CLAIM_FIELDS = {
-    claimId: true,
-    kind: true,
-    holderPid: true,
-    runtimeIdentity: true,
-    endpoint: true,
-    controllerTokenHash: true,
-    runnerPid: true,
-};
+const RUNTIME_FIELDS = { runtimeIdentity: true, endpoint: true };
 const USAGE_FIELDS = {
     inputTokens: true,
     outputTokens: true,
@@ -188,26 +183,15 @@ function parseThinking(value, path) {
         throw invalid(path, "launchConfig.thinking.source is invalid");
     return Object.freeze({ level, source });
 }
-function parseExtensions(value, path) {
-    const raw = expectObject(value, "launchConfig.extensions", path);
-    expectKeys(raw, SELECTION_FIELDS, "launchConfig.extensions", path);
-    if (typeof raw.discovery !== "boolean") {
-        throw invalid(path, "launchConfig.extensions.discovery must be boolean");
-    }
-    return Object.freeze({
-        discovery: raw.discovery,
-        paths: Object.freeze(expectStringArray(raw.paths, "launchConfig.extensions.paths", path)),
-    });
-}
-function parseSkills(value, path) {
-    const raw = expectObject(value, "launchConfig.skills", path);
-    expectKeys(raw, SELECTION_FIELDS, "launchConfig.skills", path);
+function parseSelection(value, path, field) {
+    const raw = expectObject(value, `launchConfig.${field}`, path);
+    expectKeys(raw, SELECTION_FIELDS, `launchConfig.${field}`, path);
     if (typeof raw.discovery !== "boolean") {
-        throw invalid(path, "launchConfig.skills.discovery must be boolean");
+        throw invalid(path, `launchConfig.${field}.discovery must be boolean`);
     }
     return Object.freeze({
         discovery: raw.discovery,
-        paths: Object.freeze(expectStringArray(raw.paths, "launchConfig.skills.paths", path)),
+        paths: Object.freeze(expectStringArray(raw.paths, `launchConfig.${field}.paths`, path)),
     });
 }
 function parseUsage(value, path) {
@@ -235,42 +219,7 @@ function parseRuntime(value, path) {
     expectKeys(raw, RUNTIME_FIELDS, "runtime", path);
     const runtimeIdentity = expectString(raw.runtimeIdentity, "runtime.runtimeIdentity", path);
     const endpoint = expectString(raw.endpoint, "runtime.endpoint", path);
-    const pid = raw.pid;
-    if (pid === undefined)
-        return Object.freeze({ runtimeIdentity, endpoint });
-    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
-        throw invalid(path, "runtime.pid must be a positive integer");
-    }
-    return Object.freeze({ runtimeIdentity, endpoint, pid });
-}
-function parseClaim(value, path) {
-    const raw = expectObject(value, "claim", path);
-    expectKeys(raw, CLAIM_FIELDS, "claim", path);
-    if (raw.kind !== "reconnect" && raw.kind !== "replacement") {
-        throw invalid(path, "claim.kind must be reconnect or replacement");
-    }
-    const holderPid = raw.holderPid;
-    if (typeof holderPid !== "number" || !Number.isInteger(holderPid) || holderPid <= 0) {
-        throw invalid(path, "claim.holderPid must be a positive integer");
-    }
-    const tokenHash = expectString(raw.controllerTokenHash, "claim.controllerTokenHash", path);
-    if (!/^[0-9a-f]{64}$/u.test(tokenHash)) {
-        throw invalid(path, "claim.controllerTokenHash must be a SHA-256 hex digest");
-    }
-    const runnerPid = raw.runnerPid;
-    if (runnerPid !== undefined &&
-        (typeof runnerPid !== "number" || !Number.isInteger(runnerPid) || runnerPid <= 0)) {
-        throw invalid(path, "claim.runnerPid must be a positive integer");
-    }
-    return Object.freeze({
-        claimId: expectString(raw.claimId, "claim.claimId", path),
-        kind: raw.kind,
-        holderPid,
-        runtimeIdentity: expectString(raw.runtimeIdentity, "claim.runtimeIdentity", path),
-        endpoint: expectString(raw.endpoint, "claim.endpoint", path),
-        controllerTokenHash: tokenHash,
-        ...(runnerPid === undefined ? {} : { runnerPid }),
-    });
+    return Object.freeze({ runtimeIdentity, endpoint });
 }
 function parseLaunchConfig(value, path) {
     const raw = expectObject(value, "launchConfig", path);
@@ -279,7 +228,8 @@ function parseLaunchConfig(value, path) {
     if (!isSessionId(sessionId))
         throw invalid(path, "launchConfig.sessionId is not a valid session id");
     const sessionPath = expectOptionalString(raw.sessionPath, "launchConfig.sessionPath", path);
-    const extensions = parseExtensions(raw.extensions, path);
+    const referencedSessionPath = expectOptionalString(raw.referencedSessionPath, "launchConfig.referencedSessionPath", path);
+    const extensions = parseSelection(raw.extensions, path, "extensions");
     const bridgeExtensionPath = expectString(raw.bridgeExtensionPath, "launchConfig.bridgeExtensionPath", path);
     if (!extensions.paths.includes(bridgeExtensionPath)) {
         throw invalid(path, "launchConfig.bridgeExtensionPath is missing from the extension selection");
@@ -287,6 +237,7 @@ function parseLaunchConfig(value, path) {
     const subagentId = expectString(raw.subagentId, "launchConfig.subagentId", path);
     if (!isSessionId(subagentId))
         throw invalid(path, "launchConfig.subagentId is not a valid child id");
+    const title = expectOptionalString(raw.title, "launchConfig.title", path);
     return Object.freeze({
         subagentId,
         invocation: parseInvocation(raw.invocation, path),
@@ -294,21 +245,33 @@ function parseLaunchConfig(value, path) {
         sessionId,
         sessionDir: expectString(raw.sessionDir, "launchConfig.sessionDir", path),
         ...(sessionPath === undefined ? {} : { sessionPath }),
+        ...(referencedSessionPath === undefined ? {} : { referencedSessionPath }),
         agent: parseAgent(raw.agent, path),
         model: parseModel(raw.model, path),
         thinking: parseThinking(raw.thinking, path),
         tools: Object.freeze(expectStringArray(raw.tools, "launchConfig.tools", path)),
         excludeTools: Object.freeze(expectStringArray(raw.excludeTools, "launchConfig.excludeTools", path)),
         extensions,
-        skills: parseSkills(raw.skills, path),
+        skills: parseSelection(raw.skills, path, "skills"),
         prompt: expectString(raw.prompt, "launchConfig.prompt", path),
         bridgeExtensionPath,
         interactive: expectOptionalBoolean(raw.interactive, "launchConfig.interactive", path, false),
+        ...(expectOptionalBoolean(raw.codemodeOnly, "launchConfig.codemodeOnly", path, false)
+            ? { codemodeOnly: true }
+            : {}),
+        ...(title === undefined ? {} : { title }),
     });
 }
 /** Strictly revalidates one record read from disk; partial or unknown shapes never become state. */
 export function parseSubagentRecord(value, key, parentSessionId, path) {
     const raw = expectObject(value, `record ${key}`, path);
+    if (raw.presentation === undefined && raw.mode !== undefined) {
+        // A record from the attach era names its presentation `mode`, and that field means something
+        // else now (who holds the child's process), so it is never guessed at: the user deletes the
+        // record and this version starts the child fresh. Checked before the field list, because the
+        // old field is otherwise just "unsupported".
+        throw invalid(path, `record ${key} was written by an older version (mode ${JSON.stringify(raw.mode)}); delete this record to use presentation "panel" | "background"`);
+    }
     expectKeys(raw, RECORD_FIELDS, `record ${key}`, path);
     const subagentId = expectString(raw.subagentId, "subagentId", path);
     if (subagentId !== key)
@@ -322,12 +285,13 @@ export function parseSubagentRecord(value, key, parentSessionId, path) {
     if (!Number.isInteger(revision) || revision < 1) {
         throw invalid(path, `record ${key} revision must be a positive integer`);
     }
-    const state = raw.state;
-    if (!isSubagentState(state))
+    const rawState = raw.state;
+    if (!isSubagentState(rawState))
         throw invalid(path, `record ${key} state is invalid`);
-    const mode = raw.mode;
-    if (!isExecutionMode(mode))
-        throw invalid(path, `record ${key} mode is invalid`);
+    const state = normalizeSubagentState(rawState) ?? rawState;
+    const presentation = raw.presentation;
+    if (!isPresentation(presentation))
+        throw invalid(path, `record ${key} presentation is invalid`);
     const intent = raw.intent;
     if (!isSubagentIntent(intent))
         throw invalid(path, `record ${key} intent is invalid`);
@@ -357,9 +321,9 @@ export function parseSubagentRecord(value, key, parentSessionId, path) {
         throw invalid(path, `record ${key} claims a never-flushed session with a session path`);
     }
     const runtime = raw.runtime === undefined ? undefined : parseRuntime(raw.runtime, path);
-    const claim = raw.claim === undefined ? undefined : parseClaim(raw.claim, path);
     const usage = raw.usage === undefined ? undefined : parseUsage(raw.usage, path);
     const latestSummary = expectOptionalString(raw.latestSummary, "latestSummary", path);
+    const activeTool = expectOptionalString(raw.activeTool, "activeTool", path);
     const interrupted = expectOptionalString(raw.interrupted, "interrupted", path);
     const unacknowledgedInput = expectOptionalString(raw.unacknowledgedInput, "unacknowledgedInput", path);
     return Object.freeze({
@@ -374,12 +338,12 @@ export function parseSubagentRecord(value, key, parentSessionId, path) {
         initialTask: expectString(raw.initialTask, "initialTask", path),
         intent,
         state,
-        mode,
+        presentation,
         persistence,
         launchConfig,
         ...(runtime === undefined ? {} : { runtime }),
-        ...(claim === undefined ? {} : { claim }),
         ...(latestSummary === undefined ? {} : { latestSummary }),
+        ...(activeTool === undefined ? {} : { activeTool }),
         ...(usage === undefined ? {} : { usage }),
         ...(interrupted === undefined ? {} : { interrupted }),
         ...(unacknowledgedInput === undefined ? {} : { unacknowledgedInput }),
@@ -461,7 +425,7 @@ export function createSubagentRegistry(options) {
                 if (current === undefined) {
                     throw new SubagentRegistryError("unknown_child", `Unknown child ${id} in ${path}`);
                 }
-                if (current.revision !== expectedRevision) {
+                if (expectedRevision !== undefined && current.revision !== expectedRevision) {
                     throw new SubagentRegistryError("stale_revision", `Child ${id} is at revision ${current.revision}, not ${expectedRevision}`);
                 }
                 if (expectedRuntimeIdentity !== undefined &&
@@ -484,92 +448,6 @@ export function createSubagentRegistry(options) {
                 throw corrupt(path, `update of ${id} did not persist a record`);
             return stored;
         },
-        async claim(id, expectedRevision, candidate, expectedRuntimeIdentity, expectedClaimId, signal) {
-            return store.update(id, expectedRevision, (current) => {
-                if (current.intent === "stopped") {
-                    throw new SubagentRegistryError("stopped_child", `Child ${id} is stopped`);
-                }
-                if ((expectedClaimId === undefined && current.claim !== undefined) ||
-                    (expectedClaimId !== undefined && current.claim?.claimId !== expectedClaimId)) {
-                    throw new SubagentRegistryError("claim_conflict", `Child ${id} has another claim`);
-                }
-                if (candidate.kind === "reconnect") {
-                    if (current.runtime?.runtimeIdentity !== candidate.runtimeIdentity ||
-                        current.runtime.endpoint !== candidate.endpoint) {
-                        throw new SubagentRegistryError("runtime_mismatch", `Child ${id} runtime changed before reconnect claim`);
-                    }
-                }
-                else if (expectedRuntimeIdentity === undefined
-                    ? current.runtime !== undefined
-                    : current.runtime?.runtimeIdentity !== expectedRuntimeIdentity) {
-                    throw new SubagentRegistryError("runtime_mismatch", `Child ${id} runtime changed before replacement claim`);
-                }
-                return { ...current, claim: candidate };
-            }, undefined, signal);
-        },
-        async markClaimRunner(id, claimId, runnerPid, signal) {
-            const current = await store.get(id, signal);
-            if (current === undefined)
-                throw new SubagentRegistryError("unknown_child", `Unknown child ${id} in ${path}`);
-            return store.update(id, current.revision, (value) => {
-                if (value.claim?.claimId !== claimId || value.claim.kind !== "replacement") {
-                    throw new SubagentRegistryError("claim_mismatch", `Child ${id} claim changed`);
-                }
-                return { ...value, claim: { ...value.claim, runnerPid } };
-            }, undefined, signal);
-        },
-        async activateClaim(id, claimId, runnerPid, signal) {
-            const current = await store.get(id, signal);
-            if (current === undefined)
-                throw new SubagentRegistryError("unknown_child", `Unknown child ${id} in ${path}`);
-            return store.update(id, current.revision, (value) => {
-                const claim = value.claim;
-                if (claim?.claimId !== claimId ||
-                    claim.kind !== "replacement" ||
-                    (claim.runnerPid !== undefined && claim.runnerPid !== runnerPid) ||
-                    value.intent === "stopped") {
-                    throw new SubagentRegistryError("claim_mismatch", `Child ${id} replacement claim is no longer valid`);
-                }
-                const { claim: _claim, ...withoutClaim } = value;
-                return {
-                    ...withoutClaim,
-                    runtime: {
-                        runtimeIdentity: claim.runtimeIdentity,
-                        endpoint: claim.endpoint,
-                        pid: runnerPid,
-                    },
-                };
-            }, undefined, signal);
-        },
-        async consumeReconnectClaim(id, claimId, controllerTokenHash, signal) {
-            const current = await store.get(id, signal);
-            if (current === undefined)
-                throw new SubagentRegistryError("unknown_child", `Unknown child ${id} in ${path}`);
-            return store.update(id, current.revision, (value) => {
-                const claim = value.claim;
-                if (claim?.claimId !== claimId ||
-                    claim.kind !== "reconnect" ||
-                    claim.controllerTokenHash !== controllerTokenHash ||
-                    value.runtime?.runtimeIdentity !== claim.runtimeIdentity ||
-                    value.intent === "stopped") {
-                    throw new SubagentRegistryError("claim_mismatch", `Child ${id} reconnect claim is no longer valid`);
-                }
-                const { claim: _claim, ...withoutClaim } = value;
-                return withoutClaim;
-            }, current.runtime?.runtimeIdentity, signal);
-        },
-        async releaseClaim(id, claimId, signal) {
-            const current = await store.get(id, signal);
-            if (current === undefined)
-                throw new SubagentRegistryError("unknown_child", `Unknown child ${id} in ${path}`);
-            return store.update(id, current.revision, (value) => {
-                if (value.claim?.claimId !== claimId) {
-                    throw new SubagentRegistryError("claim_mismatch", `Child ${id} claim changed`);
-                }
-                const { claim: _claim, ...withoutClaim } = value;
-                return withoutClaim;
-            }, undefined, signal);
-        },
     };
     return store;
 }

package/dist/rpc-events.d.ts

@@ -1,8 +1,6 @@
 /**
- * Runner-local and child-lifecycle events are produced by the runner itself.
- * Only these Pi RPC event types are forwarded to a controller; everything
- * else (streaming token noise, undocumented internals) is dropped.
+ * The Pi events a child forwards to its parent. Everything else — streaming token noise,
+ * undocumented internals — is dropped, so the parent's projection only sees turn-level facts.
  */
-export declare const FORWARDED_PI_EVENT_TYPES: readonly ["agent_start", "agent_end", "turn_start", "turn_end", "tool_execution_start", "tool_execution_update", "tool_execution_end", "auto_retry", "message_update", "agent_settled"];
+export declare const FORWARDED_PI_EVENT_TYPES: readonly ["agent_start", "agent_end", "turn_start", "turn_end", "tool_execution_start", "tool_execution_update", "tool_execution_end", "auto_retry", "auto_retry_start", "auto_retry_end", "message_update", "agent_settled"];
 export declare function shouldForwardPiEvent(event: unknown): boolean;
-export declare function isIdlePiState(value: unknown): boolean;

package/dist/rpc-events.js

@@ -1,8 +1,7 @@
-import { isRecord } from "./domain.js";
+import { isRecord } from "@hheei/pi-ext-core";
 /**
- * Runner-local and child-lifecycle events are produced by the runner itself.
- * Only these Pi RPC event types are forwarded to a controller; everything
- * else (streaming token noise, undocumented internals) is dropped.
+ * The Pi events a child forwards to its parent. Everything else — streaming token noise,
+ * undocumented internals — is dropped, so the parent's projection only sees turn-level facts.
  */
 export const FORWARDED_PI_EVENT_TYPES = [
     "agent_start",
@@ -13,6 +12,8 @@ export const FORWARDED_PI_EVENT_TYPES = [
     "tool_execution_update",
     "tool_execution_end",
     "auto_retry",
+    "auto_retry_start",
+    "auto_retry_end",
     "message_update",
     "agent_settled",
 ];
@@ -22,8 +23,3 @@ export function shouldForwardPiEvent(event) {
     return (typeof event.type === "string" &&
         FORWARDED_PI_EVENT_TYPES.includes(event.type));
 }
-export function isIdlePiState(value) {
-    if (!isRecord(value))
-        return false;
-    return (value.isStreaming === false && value.isCompacting === false && value.pendingMessageCount === 0);
-}

package/dist/runtime.d.ts

@@ -1,22 +1,77 @@
+import { type ChildRuntime } from "./child-process.js";
 import type { SubagentRecord } from "./domain.js";
-import type { RunnerLike } from "./manager.js";
+import type { HostAdapter, HostAttachment } from "./host-adapter.js";
 import type { SubagentRegistry } from "./registry.js";
+/** Per-runtime bridge tokens, kept out of the registry because they are credentials. */
 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;
+export interface RuntimeTokenStoreOptions {
+    /** The parent session these tokens belong to. */
+    readonly parentSessionId: string;
+    /** Override for tests. Defaults to this parent's file in the shared runtime directory. */
+    readonly file?: string;
+    readonly diagnose?: (message: string) => void;
+}
+/**
+ * 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 declare function parentBridgeEndpoint(parentSessionId: string): string;
+/**
+ * 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 declare function parentTokenFile(parentSessionId: string): string;
+/**
+ * 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 declare function createRuntimeTokenStore(options: RuntimeTokenStoreOptions): RuntimeTokenStore;
+export interface LaunchChildOptions {
+    readonly registry: Pick<SubagentRegistry, "update">;
     readonly record: SubagentRecord;
     readonly tokens: RuntimeTokenStore;
+    /** Waits for this child's bridge connection; false when it did not connect in time. */
+    readonly waitForBridge: (childId: string, signal?: AbortSignal) => Promise<boolean>;
     readonly signal?: AbortSignal;
+    readonly diagnose?: (message: string) => void;
+}
+/**
+ * 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 declare function launchChild(options: LaunchChildOptions): Promise<LaunchOutcome<ChildRuntime>>;
+export interface OpenChildPanelOptions extends LaunchChildOptions {
+    readonly host: HostAdapter;
+}
+/**
+ * What a launch left behind. A launch that failed can still have started something — a child that
+ * never dialed in, or a process that ignores SIGTERM — and then the caller must keep the handle:
+ * dropping it would let the next send start a second runtime for a session the first one may still
+ * own. `failure` is what the caller reports.
+ */
+export interface LaunchOutcome<T> {
+    readonly handle?: T;
+    readonly failure?: string;
+    /**
+     * Set when something may still own the child's session and this process cannot observe it, so
+     * the caller refuses to start a second runtime until an explicit stop.
+     */
+    readonly unconfirmed?: boolean;
 }
-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;
+/**
+ * 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 declare function openChildPanel(options: OpenChildPanelOptions): Promise<LaunchOutcome<HostAttachment>>;
+/** Creates the runtime directory if needed; the socket itself is 0600 in a 0700 directory. */
+export declare function prepareRuntimeDirectory(diagnose?: (message: string) => void): Promise<string>;