@hheei/pi-subagents 0.2.4 → 0.4.0

package/dist/process-lock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Node has no flock(2). A dedicated SQLite file held in BEGIN EXCLUSIVE uses the kernel POSIX
+ * lock, which is released when this process dies, including SIGKILL. A missed poll is not death.
+ * The parent must not keep the lock: a probe rolls back immediately.
+ */
+export interface ProcessLock {
+    release(): void;
+}
+export declare function processLockPath(stateFile: string, parentSessionId: string, subagentId: string): string | undefined;
+export declare function holdProcessLock(lockPath: string): ProcessLock;
+export declare function processLockHeld(lockPath: string): boolean;

package/dist/process-lock.js

@@ -0,0 +1,55 @@
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { isSessionId } from "./domain.js";
+export function processLockPath(stateFile, parentSessionId, subagentId) {
+    if (!isSessionId(parentSessionId) || !isSessionId(subagentId))
+        return undefined;
+    return join(dirname(stateFile), "locks", parentSessionId, `${subagentId}.lock`);
+}
+export function holdProcessLock(lockPath) {
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    const db = new DatabaseSync(lockPath);
+    chmodSync(lockPath, 0o600);
+    db.exec("PRAGMA busy_timeout = 2000");
+    db.exec("BEGIN EXCLUSIVE");
+    let released = false;
+    return {
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Closing the connection still drops the kernel lock.
+            }
+            db.close();
+        },
+    };
+}
+export function processLockHeld(lockPath) {
+    if (!existsSync(lockPath))
+        return false;
+    const db = new DatabaseSync(lockPath);
+    try {
+        db.exec("PRAGMA busy_timeout = 0");
+        try {
+            db.exec("BEGIN IMMEDIATE");
+        }
+        catch (error) {
+            if (isDatabaseLocked(error))
+                return true;
+            throw error;
+        }
+        db.exec("ROLLBACK");
+        return false;
+    }
+    finally {
+        db.close();
+    }
+}
+function isDatabaseLocked(error) {
+    return typeof error === "object" && error !== null && "errcode" in error && error.errcode === 5;
+}

package/dist/protocol.d.ts

@@ -7,7 +7,7 @@ export declare const DEFAULT_MAX_BUFFERED_EVENTS = 256;
  * input and state operations; the child returns reports and its Task result as requests, so a
  * report the parent refuses (a second Task result) is refused to the child that sent it.
  */
-export declare const BRIDGE_OPERATIONS: readonly ["prompt", "steer", "follow_up", "abort", "get_state", "get_entries", "shutdown", "contact_parent", "task_result"];
+export declare const BRIDGE_OPERATIONS: readonly ["prompt", "steer", "follow_up", "abort", "get_state", "get_entries", "session_facts", "shutdown", "contact_parent", "task_result"];
 export type BridgeOperation = (typeof BRIDGE_OPERATIONS)[number];
 /** Child-branch event: the child left the bound session, quit, or was interrupted. */
 export declare const CHILD_LIFECYCLE_EVENT: "child_lifecycle";
@@ -41,7 +41,7 @@ export declare const RequestFrameSchema: Type.TObject<{
     version: Type.TLiteral<1>;
     type: Type.TLiteral<"request">;
     id: Type.TString;
-    operation: Type.TUnion<Type.TLiteral<"contact_parent" | "steer" | "follow_up" | "prompt" | "abort" | "get_state" | "get_entries" | "shutdown" | "task_result">[]>;
+    operation: Type.TUnion<Type.TLiteral<"contact_parent" | "steer" | "follow_up" | "prompt" | "abort" | "get_state" | "get_entries" | "session_facts" | "shutdown" | "task_result">[]>;
     payload: Type.TOptional<Type.TUnknown>;
 }>;
 export declare const BridgeErrorSchema: Type.TObject<{

package/dist/protocol.js

@@ -16,6 +16,7 @@ export const BRIDGE_OPERATIONS = [
     "abort",
     "get_state",
     "get_entries",
+    "session_facts",
     "shutdown",
     "contact_parent",
     "task_result",

package/dist/registry.d.ts

@@ -30,7 +30,7 @@ export interface CreateSubagentRegistryOptions {
     readonly filePath?: string;
     readonly now?: () => Date;
 }
-export declare function defaultRegistryPath(parentSessionId: string): string;
 /** Strictly revalidates one record read from disk; partial or unknown shapes never become state. */
 export declare function parseSubagentRecord(value: unknown, key: string, parentSessionId: string, path: string): SubagentRecord;
+export declare function defaultRegistryPath(_parentSessionId: string): string;
 export declare function createSubagentRegistry(options: CreateSubagentRegistryOptions): SubagentRegistry;

package/dist/registry.js

@@ -1,7 +1,8 @@
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { isRecord, readJsonSettingsRoot, updateJsonSettingsRoot } from "@hheei/pi-ext-core";
-import { isLaunchValueSource, isPersistenceState, isPresentation, isSessionId, isSubagentIntent, isSubagentState, isThinkingLevel, normalizeSubagentState, REGISTRY_VERSION, } from "./domain.js";
+import { isRecord } from "@hheei/pi-ext-core";
+import { isLaunchValueSource, isPersistenceState, isPresentation, isSessionId, isSubagentIntent, isSubagentState, isThinkingLevel, normalizeSubagentState, } from "./domain.js";
+import { insertChild, listChildRecords, openStateDb, readChild, replaceChild, withWrite, } from "./state-db.js";
 export class SubagentRegistryError extends Error {
     code;
     constructor(code, message) {
@@ -10,15 +11,6 @@ export class SubagentRegistryError extends Error {
         this.code = code;
     }
 }
-export function defaultRegistryPath(parentSessionId) {
-    return join(getAgentDir(), "pi-subagents", "registry", `${parentSessionId}.json`);
-}
-const ROOT_FIELDS = {
-    version: true,
-    parentSessionId: true,
-    updatedAt: true,
-    records: true,
-};
 const RECORD_FIELDS = {
     subagentId: true,
     parentSessionId: true,
@@ -57,11 +49,10 @@ const LAUNCH_CONFIG_FIELDS = {
     skills: true,
     prompt: true,
     bridgeExtensionPath: true,
-    interactive: true,
     title: true,
     task: true,
-    referencedSessionPath: true,
     codemodeOnly: true,
+    mcp: true,
 };
 const AGENT_FIELDS = {
     name: true,
@@ -75,7 +66,12 @@ 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 };
+const RUNTIME_FIELDS = {
+    runtimeIdentity: true,
+    endpoint: true,
+    attachment: true,
+};
+const ATTACHMENT_FIELDS = { kind: true, host: true, id: true, pid: true };
 const USAGE_FIELDS = {
     inputTokens: true,
     outputTokens: true,
@@ -219,7 +215,58 @@ 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);
-    return Object.freeze({ runtimeIdentity, endpoint });
+    const attachment = raw.attachment === undefined ? undefined : parseAttachment(raw.attachment, path);
+    return Object.freeze({
+        runtimeIdentity,
+        endpoint,
+        ...(attachment === undefined ? {} : { attachment }),
+    });
+}
+function parseAttachment(value, path) {
+    const raw = expectObject(value, "runtime.attachment", path);
+    expectKeys(raw, ATTACHMENT_FIELDS, "runtime.attachment", path);
+    if (raw.kind === "panel") {
+        if (raw.pid !== undefined)
+            throw invalid(path, "runtime.attachment panel must not carry a pid");
+        const host = raw.host;
+        if (!isPanelHost(host))
+            throw invalid(path, "runtime.attachment.host is invalid");
+        const id = expectString(raw.id, "runtime.attachment.id", path);
+        if (id === "")
+            throw invalid(path, "runtime.attachment.id must not be empty");
+        return Object.freeze({ kind: "panel", host, id });
+    }
+    if (raw.kind === "process") {
+        if (raw.host !== undefined || raw.id !== undefined) {
+            throw invalid(path, "runtime.attachment process must not carry a panel id");
+        }
+        const pid = raw.pid;
+        if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+            throw invalid(path, "runtime.attachment.pid must be a positive integer");
+        }
+        return Object.freeze({ kind: "process", pid });
+    }
+    throw invalid(path, "runtime.attachment.kind is invalid");
+}
+function isPanelHost(value) {
+    return value === "herdr" || value === "cmux";
+}
+function parseMcpSelection(value, path) {
+    if (value === undefined)
+        return Object.freeze({ enabled: true });
+    const raw = expectObject(value, "launchConfig.mcp", path);
+    const enabled = expectOptionalBoolean(raw.enabled, "launchConfig.mcp.enabled", path, true);
+    const servers = raw.servers === undefined
+        ? undefined
+        : Object.freeze(expectStringArray(raw.servers, "launchConfig.mcp.servers", path));
+    const excluded = raw.excluded === undefined
+        ? undefined
+        : Object.freeze(expectStringArray(raw.excluded, "launchConfig.mcp.excluded", path));
+    return Object.freeze({
+        enabled,
+        ...(servers === undefined ? {} : { servers }),
+        ...(excluded === undefined ? {} : { excluded }),
+    });
 }
 function parseLaunchConfig(value, path) {
     const raw = expectObject(value, "launchConfig", path);
@@ -228,7 +275,6 @@ 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 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)) {
@@ -245,7 +291,6 @@ 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),
@@ -253,9 +298,9 @@ function parseLaunchConfig(value, path) {
         excludeTools: Object.freeze(expectStringArray(raw.excludeTools, "launchConfig.excludeTools", path)),
         extensions,
         skills: parseSelection(raw.skills, path, "skills"),
+        mcp: parseMcpSelection(raw.mcp, path),
         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 }
             : {}),
@@ -349,36 +394,8 @@ export function parseSubagentRecord(value, key, parentSessionId, path) {
         ...(unacknowledgedInput === undefined ? {} : { unacknowledgedInput }),
     });
 }
-function parseRoot(raw, path, parentSessionId) {
-    if (Object.keys(raw).length === 0)
-        return new Map();
-    const version = raw.version;
-    if (version === undefined)
-        throw corrupt(path, "missing version");
-    if (version !== REGISTRY_VERSION) {
-        throw new SubagentRegistryError("unsupported_version", `Unsupported registry version ${String(version)} in ${path}; expected ${REGISTRY_VERSION}`);
-    }
-    if (raw.parentSessionId !== parentSessionId) {
-        throw new SubagentRegistryError("parent_mismatch", `Registry ${path} belongs to parent session ${String(raw.parentSessionId)}, not ${parentSessionId}`);
-    }
-    const records = raw.records;
-    if (!isRecord(records))
-        throw corrupt(path, "records must be an object");
-    const parsed = new Map();
-    for (const [id, value] of Object.entries(records)) {
-        parsed.set(id, parseSubagentRecord(value, id, parentSessionId, path));
-    }
-    return parsed;
-}
-function writeRoot(root, parentSessionId, records, now) {
-    for (const key of Object.keys(root)) {
-        if (ROOT_FIELDS[key] !== true)
-            delete root[key];
-    }
-    root.version = REGISTRY_VERSION;
-    root.parentSessionId = parentSessionId;
-    root.updatedAt = now.toISOString();
-    root.records = Object.fromEntries(records);
+export function defaultRegistryPath(_parentSessionId) {
+    return join(getAgentDir(), "pi-subagents", "state.sqlite");
 }
 export function createSubagentRegistry(options) {
     const { parentSessionId } = options;
@@ -387,41 +404,43 @@ export function createSubagentRegistry(options) {
     }
     const path = options.filePath ?? defaultRegistryPath(parentSessionId);
     const now = options.now ?? (() => new Date());
-    const readRecords = async (signal) => parseRoot(await readJsonSettingsRoot(path, signal), path, parentSessionId);
-    const store = {
+    const db = openStateDb(path);
+    const load = (id) => {
+        const row = readChild(db, parentSessionId, id);
+        if (row === undefined)
+            return undefined;
+        return parseSubagentRecord(JSON.parse(row.record), id, parentSessionId, path);
+    };
+    return {
         path,
         parentSessionId,
-        async get(id, signal) {
-            return (await readRecords(signal)).get(id);
+        async get(id) {
+            return load(id);
         },
-        async list(signal) {
-            const records = [...(await readRecords(signal)).values()];
+        async list() {
+            const records = listChildRecords(db, parentSessionId).map((record) => {
+                const parsed = JSON.parse(record);
+                if (!isRecord(parsed) || typeof parsed.subagentId !== "string") {
+                    throw corrupt(path, "child record is missing subagentId");
+                }
+                return parseSubagentRecord(parsed, parsed.subagentId, parentSessionId, path);
+            });
             records.sort((left, right) => left.createdAt === right.createdAt
                 ? left.subagentId.localeCompare(right.subagentId)
                 : left.createdAt.localeCompare(right.createdAt));
             return records;
         },
-        async create(record, signal) {
-            let stored;
-            await updateJsonSettingsRoot(path, (root) => {
-                const records = parseRoot(root, path, parentSessionId);
-                const candidate = parseSubagentRecord(record, record.subagentId, parentSessionId, path);
-                if (records.has(candidate.subagentId)) {
-                    throw new SubagentRegistryError("duplicate_child", `Child ${candidate.subagentId} already exists in ${path}`);
-                }
-                records.set(candidate.subagentId, candidate);
-                writeRoot(root, parentSessionId, records, now());
-                stored = candidate;
-            }, signal);
-            if (stored === undefined)
-                throw corrupt(path, "create did not persist a record");
-            return stored;
+        async create(record) {
+            const candidate = parseSubagentRecord(record, record.subagentId, parentSessionId, path);
+            const inserted = withWrite(db, () => insertChild(db, parentSessionId, candidate.subagentId, candidate.revision, JSON.stringify(candidate)));
+            if (!inserted) {
+                throw new SubagentRegistryError("duplicate_child", `Child ${candidate.subagentId} already exists in ${path}`);
+            }
+            return candidate;
         },
-        async update(id, expectedRevision, updater, expectedRuntimeIdentity, signal) {
-            let stored;
-            await updateJsonSettingsRoot(path, (root) => {
-                const records = parseRoot(root, path, parentSessionId);
-                const current = records.get(id);
+        async update(id, expectedRevision, updater, expectedRuntimeIdentity) {
+            return withWrite(db, () => {
+                const current = load(id);
                 if (current === undefined) {
                     throw new SubagentRegistryError("unknown_child", `Unknown child ${id} in ${path}`);
                 }
@@ -440,14 +459,12 @@ export function createSubagentRegistry(options) {
                     revision: current.revision + 1,
                     updatedAt: now().toISOString(),
                 }, id, parentSessionId, path);
-                records.set(id, next);
-                writeRoot(root, parentSessionId, records, now());
-                stored = next;
-            }, signal);
-            if (stored === undefined)
-                throw corrupt(path, `update of ${id} did not persist a record`);
-            return stored;
+                const replaced = replaceChild(db, parentSessionId, id, current.revision, next.revision, JSON.stringify(next));
+                if (!replaced) {
+                    throw new SubagentRegistryError("stale_revision", `Child ${id} changed while it was being updated`);
+                }
+                return next;
+            });
         },
     };
-    return store;
 }

package/dist/rpc-events.d.ts

@@ -2,5 +2,5 @@
  * 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", "auto_retry_start", "auto_retry_end", "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_end", "auto_retry", "auto_retry_start", "auto_retry_end", "message_update", "agent_settled", "compaction_start", "compaction_end"];
 export declare function shouldForwardPiEvent(event: unknown): boolean;

package/dist/rpc-events.js

@@ -9,13 +9,14 @@ export const FORWARDED_PI_EVENT_TYPES = [
     "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",
+    "compaction_start",
+    "compaction_end",
 ];
 export function shouldForwardPiEvent(event) {
     if (!isRecord(event))

package/dist/runtime.d.ts

@@ -19,22 +19,16 @@ export interface RuntimeTokenStoreOptions {
  * 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;
+export declare function parentBridgeEndpoint(_parentSessionId: string): string;
+/** Tokens live in the same sqlite file as the child ledger. Rows do not clobber each other. */
+export declare function parentTokenFile(_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.
+ * Tokens outlive the parent process. A restarted parent reads the same sqlite file and can still
+ * match the token a surviving child was launched with.
  */
 export declare function createRuntimeTokenStore(options: RuntimeTokenStoreOptions): RuntimeTokenStore;
 export interface LaunchChildOptions {
-    readonly registry: Pick<SubagentRegistry, "update">;
+    readonly registry: Pick<SubagentRegistry, "get" | "update">;
     readonly record: SubagentRecord;
     readonly tokens: RuntimeTokenStore;
     /** Waits for this child's bridge connection; false when it did not connect in time. */
@@ -53,19 +47,12 @@ 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.
+ * What a launch left behind. `failure` is what the caller reports. A handle is kept when the host
+ * still has a tab, so stop can close it. It does not by itself forbid another send.
  */
 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;
 }
 /**
  * Opens one child in a host panel and waits for it to connect. The host owns this process, so the