@hheei/pi-subagents 0.6.0 → 0.8.0

package/LICENSES/Apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,10 @@
+This package includes a compact CSS shell adapted from AgentDock.
+
+AgentDock mcpapps/app.html
+https://github.com/uvwt/agentdock-protocol/blob/a0ffc5114507a498013dc8a5bbd572114e23bf5d/mcpapps/app.html
+Copyright AgentDock contributors
+Licensed under the Apache License, Version 2.0
+The license text is LICENSES/Apache-2.0.txt.
+
+The adapted lines live in src/mcp/app.html and are marked there.
+The rest of @hheei/pi-subagents is MIT licensed; see LICENSE.

package/README.md

@@ -15,20 +15,20 @@ children and `/subagents stop [id]` to stop one without conflicting with other e
 
 | Tool | Purpose |
 | --- | --- |
-| `agent_spawn({ task, agent, cwd?, title? })` | Spawn an independent background subagent task. Runs in a new Herdr tab (or cmux surface) targeting the parent's workspace when a host is available, and headless in the background otherwise. **Prefer reusing existing subagents** via `agent_send` for related/follow-up work to maintain context and maximize prompt cache and memory efficiency. Tool description lists available agent names and roles, excluding disabled or hidden definitions. Deferred by default; discover via `tool_search({ query: "agent" })`. Do not poll for completion; results return automatically. |
-| `agent_send({ id, message, mode? })` | Send input to a specific child. `mode: "steer"` (the default) enters the current turn once its tool calls are in, before the next model request; `mode: "follow_up"` waits until the child has no tool calls or steering left, then continues as a new turn. **Primary tool for assigning follow-up or functionally related tasks** to existing subagents: idle, blocked, done, or errored children resume their existing session automatically with historical context intact. A child whose runtime has ended is resumed the same way; spawn a new child only for new work. Stop first only when send says the previous process is still running. Deferred by default; discover via `tool_search({ query: "agent" })`. |
-| `agent_get({ id, keys? })` | Inspect one subagent by id. `keys` is a comma-separated selection of `status` (default), `progress` (default), and `diagnostic`; unknown keys fail. The view never returns the child's task parameters or terminal result, which arrive automatically as reports. From the second successful inspection of the same child in this parent runtime, the result adds a short reminder that results return automatically and must not be polled. Deferred by default; discover via `tool_search({ query: "agent" })`. |
-| `agent_stop({ id })` | Stop one subagent's runtime by id. The child keeps its session, so a later `agent_send` can resume it. Deferred by default; discover via `tool_search({ query: "agent" })`. |
+| `agents_delegate({ task, agent?, id?, cwd?, wait? })` | Delegate work to a new agent (`agent`) or continue an existing one (`id`, which wins over `agent`). A new child runs in a new Herdr tab (or cmux surface) targeting the parent's workspace when a host is available, and headless in the background otherwise. **Prefer reusing existing agents** via `id` for related/follow-up work to keep context and maximize prompt-cache and memory efficiency. The tool description lists available agent names and roles, excluding disabled or hidden definitions. Deferred by default; discover via `tool_search({ query: "agent" })`. `wait:true` (default) returns the settled delegation, `wait:false` returns it as soon as it is accepted; either way the result arrives automatically, so do not poll. |
+| `agents_get({ id, revision?, includeOutput? })` | Read one delegation of an agent: the newest by default, `revision` for one specific delegation, and the result body only with `includeOutput: true` (bounded by the shared output limit). The view carries the delegation `status` and the runtime `progress.runtimeState` separately, so a new delegation never overwrites a historical result. From the second successful inspection of the same agent in this parent runtime, the result adds a short reminder that results return automatically and must not be polled. Deferred by default; discover via `tool_search({ query: "agent" })`. |
+| `agents_stop({ id })` | Stop one agent's runtime by id. Open delegations end as failed; finished results and the session are kept, so a later `agents_delegate` with this id resumes it. Deferred by default; discover via `tool_search({ query: "agent" })`. |
+| `agents_dashboard({})` | Summarise this session's agents: runtime counts plus each agent's latest delegation status and activity, never result bodies. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 
 ### Unified Task Management
 
-`agent_spawn` returns JSON `{ id, path }` on success. `path` is the absolute child session file path
-assigned by Pi; its first write may still be pending. `agent_get` exposes the same `progress.path`.
-`agent_send` and `agent_stop` return one confirmation
-sentence. Failures return only their reason. Operation results omit session IDs, presentation, and
-state snapshots; use `agent_get` for runtime inspection.
+`agents_delegate` returns `{ id, revision, status, task, hasOutput }`: `revision` identifies that
+delegation of the agent, and a settled delegation carries its result when `wait` is true.
+`agents_stop` returns the same projection for the agent it stopped. Failures return only their
+reason. There is no public `title` or `mode`: the child session title is derived from the agent name
+and id, and continuing an agent always steers.
 
-SubagentManager and its SQLite ledger own child conversation state, runtime leases, recovery, and reports. No pi-ext-tools task service is required. Only delivery batching is shared through ext-core BackgroundDelivery. Child reports arrive automatically; do not poll status to detect completion. Bash uses separate `bg_bash_*` tools. Deferred subagent tools are loaded via `tool_search`; `before_agent_start` writes the `subagents` bullet into the structured prompt's `optional_tools` section. Both get tools return the same `status`, `progress`, and optional `diagnostic` envelope. Diagnostics describe blockers, failed turns, or uncertain runtime state.
+SubagentManager and its SQLite ledger own child conversation state, runtime leases, recovery, and reports. No pi-ext-tools task service is required. Only delivery batching is shared through ext-core BackgroundDelivery. Child reports arrive automatically; do not poll status to detect completion. Bash uses separate `bg_bash_*` tools. Deferred agent tools are loaded via `tool_search`; `before_agent_start` writes the `subagents` bullet into the structured prompt's `optional_tools` section. Diagnostics describe blockers, failed turns, or uncertain runtime state.
 
 ## Child execution and reporting
 
@@ -37,6 +37,8 @@ Subagents communicate with the parent through the `commands` table in `state.sql
 - **Completion by Direct Output**: Subagents do **not** need to call any reporting tool upon successful completion. The subagent simply outputs its final answer as normal assistant text.
 - **Settlement Batching**: When a subagent settles, the harness captures the trailing assistant text and delivers it to the parent conversation as a `subagent-report`. Reports flush within 500ms when no other child is working, and are batched for up to 10 seconds while another child is still running.
 - **Blockers & Decisions**: The child registers `contact_parent({ message, reason? })` strictly for reporting when it is blocked or urgently requires a parent decision midway (`reason` defaults to `'blocked'`). Blocked reports wake the parent immediately.
+- **Direct `/compact` Command**: Sending `"/compact"` (or `"/compact [instructions]"`) via `agents_delegate` intercepts the command on the child side without passing it as prompt text to the LLM. The child executes native context compaction and reports completion status back to the parent via `contact_parent`. Duplicate `/compact` requests while a compaction is already in flight are safely acknowledged and ignored.
+- **Context Trim Hint**: When a subagent completes a task with context usage exceeding 100,000 tokens, its report includes a hint advising the parent to trim memory via `agents_delegate({ id, task: "/compact" })` if the child session will be retained for future work.
 - **Automatic Retry**: Pi's own auto-retry is observed, not invented: reports are suppressed while a retry is in flight, and a retry that succeeds clears the previous error instead of reporting it.
 - **Panel Failure Auto-Close**: When a subagent running in a panel encounters a fatal error or reports a blocker, the manager starts a 15-second countdown after notifying the parent, automatically closing the panel tab to avoid workspace clutter unless new instructions are dispatched.
 ## Compact status and reports
@@ -45,12 +47,12 @@ Running children use the native Pi status line: `🤖 󰪠#21 #22 #23`. With pi-
 
 Confirmed done, error, and blocked reports appear once as `subagent-info` transcript entries. Collapsed entries show the outcome, child ID, and agent name; expand to read the complete report. They survive resume and do not enter model context. The original automatic `subagent-report` still reaches the model, with its duplicate transcript display hidden. Transient errors remain subject to settlement and retry checks before reporting.
 
-Use `/subagents` for complete status and management. `agent_send` can resume a done, blocked, errored, or stopped child with its session context intact; retrying does not guarantee the underlying failure is resolved.
+Use `/subagents` for complete status and management. `agents_delegate` with an existing `id` can resume a done, blocked, errored, or stopped child with its session context intact; retrying does not guarantee the underlying failure is resolved.
 
 ## Host Integration and Isolation
 
 - **Herdr Workspace Affinity**: When spawning in Herdr, tabs are explicitly created in the parent process's current workspace (`--workspace <WORKSPACE_ID>`), preventing child tabs from jumping to whichever workspace happens to have user focus.
-- **Hindsight Memory Isolation**: `PI_HINDSIGHT_DISABLE=1` is set in the child environment and memory auto-registration/recall/writeback are disabled. The child bridge blocks all `mcp__hindsight__*` calls (including nested codemode calls and future server tools), even if that server is configured in a file. Memory recall prompt blocks are stripped. This boundary applies to the reserved `hindsight` server name, not arbitrary external servers registered under other names.
+- **Memory Isolation**: Both `PI_HINDSIGHT_DISABLE=1` and `PI_OBSERVATIONAL_MEMORY_DISABLE=1` are injected into child processes. Hindsight memory auto-registration, recall, and writeback are disabled, and the child bridge blocks all `mcp__hindsight__*` calls. Background Observational Memory workers (observation, reflection, compaction triggers) are suppressed in passive mode.
 
 ## Agent definitions
 

package/dist/child-control.d.ts

@@ -1,11 +1,3 @@
-/**
- * Child-side control plane.
- *
- * The parent drives a child, and the child reports back, over one bridge connection. Every parent
- * request is executed with this process's own Pi primitives, so a child presented in a host panel
- * and a child running headless are controlled identically and no second transport (an RPC writer,
- * a pause handshake) has to be kept in sync with the child's real state.
- */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ChildIdentity } from "./domain.js";
 import { type ChildInputSource } from "./protocol.js";

package/dist/child-control.js

@@ -1,3 +1,12 @@
+/**
+ * Child-side control plane.
+ *
+ * The parent drives a child, and the child reports back, over one bridge connection. Every parent
+ * request is executed with this process's own Pi primitives, so a child presented in a host panel
+ * and a child running headless are controlled identically and no second transport (an RPC writer,
+ * a pause handshake) has to be kept in sync with the child's real state.
+ */
+import { randomUUID } from "node:crypto";
 import { errorMessage, isRecord } from "@hheei/pi-ext-core";
 import { attachChildMailbox } from "./mailbox.js";
 import { BridgeError, CHILD_INPUT_EVENT } from "./protocol.js";
@@ -198,6 +207,26 @@ export function registerChildControl(pi, options) {
         }
         return ctx;
     };
+    const reportCompaction = (controlId, reason, message) => {
+        void client
+            .report("contact_parent", {
+            type: "pi_subagent_report",
+            parentSessionId: options.identity.parentSessionId,
+            childId: options.identity.subagentId,
+            runtimeIdentity: options.identity.runtimeIdentity,
+            reason,
+            message,
+            controlId,
+        })
+            .catch((err) => {
+            options.diagnose?.(`failed to report compaction ${reason}: ${errorMessage(err)}`);
+        });
+    };
+    /**
+     * The compaction this child is running for a delegation. A second /compact joins it instead of
+     * queueing another one, so both delegations settle with the same operation.
+     */
+    let compactOperation;
     const deliverPrompt = (payload, deliverAs) => {
         const message = promptMessage(payload);
         // A message needs a session to land in: while the process is between sessions the parent
@@ -206,6 +235,32 @@ export function registerChildControl(pi, options) {
         if (path === undefined) {
             throw new BridgeError("session_not_ready", "This child has no session file path");
         }
+        const trimmed = message.trim();
+        if (trimmed === "/compact" || trimmed.startsWith("/compact ")) {
+            // A compaction this child already runs for a delegation is the operation a new request
+            // joins, whatever the event state says yet.
+            if (compactOperation !== undefined) {
+                return { accepted: true, path, compacting: true, controlId: compactOperation };
+            }
+            if (isCompacting) {
+                throw new BridgeError("compaction_unbound", "A compaction started outside a delegation is already running");
+            }
+            const controlId = randomUUID();
+            compactOperation = controlId;
+            const customInstructions = trimmed.slice(8).trim() || undefined;
+            requireContext().compact({
+                ...(customInstructions ? { customInstructions } : {}),
+                onComplete: (result) => {
+                    compactOperation = undefined;
+                    reportCompaction(controlId, "success", `Context compacted (${result.tokensBefore} -> ${result.estimatedTokensAfter} tokens).`);
+                },
+                onError: (err) => {
+                    compactOperation = undefined;
+                    reportCompaction(controlId, "blocked", `Compaction failed: ${err.message}`);
+                },
+            });
+            return { accepted: true, path, compacting: true, controlId };
+        }
         if (isCompacting) {
             pendingCompactionDeliveries.push({ message, deliverAs });
             return { accepted: true, path, queuedForCompaction: true };
@@ -248,12 +303,20 @@ export function registerChildControl(pi, options) {
                 return deliverPrompt(request.payload, undefined);
             case "steer":
                 return deliverPrompt(request.payload, "steer");
-            case "follow_up":
-                return deliverPrompt(request.payload, "followUp");
             case "get_state":
                 return childState(requireContext(), isCompacting);
             case "get_entries": {
-                return { entries: currentEntries() };
+                const payload = isRecord(request.payload) ? request.payload : undefined;
+                const cursor = typeof payload?.cursor === "number" && payload.cursor >= 0
+                    ? Math.floor(payload.cursor)
+                    : 0;
+                const limit = typeof payload?.limit === "number" && payload.limit > 0
+                    ? Math.min(Math.floor(payload.limit), 100)
+                    : 20;
+                const all = currentEntries();
+                const entries = all.slice(cursor, cursor + limit);
+                const nextCursor = cursor + entries.length < all.length ? cursor + entries.length : undefined;
+                return { entries, ...(nextCursor === undefined ? {} : { nextCursor }) };
             }
             case "session_facts": {
                 const expected = isRecord(request.payload) ? request.payload.expectedInput : undefined;

package/dist/commands.js

@@ -46,7 +46,7 @@ export function registerParentCommands(pi, manager) {
         getArgumentCompletions: subcommandCompletions(SUBAGENT_SUBCOMMANDS),
         handler: async (args, ctx) => {
             if (ctx.mode !== "tui") {
-                ctx.ui.notify("Use agent_spawn / agent_send / agent_get / agent_stop in this mode");
+                ctx.ui.notify("Use agents_delegate / agents_get / agents_stop in this mode");
                 return;
             }
             const { verb, rest: target } = splitSubcommand(args);

package/dist/controller-ipc.d.ts

@@ -0,0 +1,38 @@
+import { type Server } from "node:net";
+import type { ControllerManager } from "./controller-role.js";
+/** Bumped whenever this call surface changes: a client never talks to a controller from another build. */
+export declare const CONTROLLER_PROTOCOL = 2;
+export type ControllerOp = "protocol" | "delegate" | "receipts" | "get" | "list" | "stop" | "transcript";
+export interface ControllerCall {
+    readonly op: ControllerOp;
+    readonly input: unknown;
+}
+export interface ControllerReply {
+    readonly ok: boolean;
+    readonly result?: unknown;
+    readonly error?: string;
+}
+export declare function serveControllerIpc(options: {
+    readonly socketPath: string;
+    readonly parentSessionId: string;
+    readonly manager: ControllerManager;
+    /** Ledger this controller records delegations in; defaults to this parent's state database. */
+    readonly statePath?: string;
+}): Promise<Server>;
+/** Stops listening and drops open calls. `server.close()` alone waits until every wait:true socket ends. */
+export declare function closeControllerIpc(server: Server): Promise<void>;
+/**
+ * What answered on this socket. `silent` is not a protocol: a slow or dead peer must not be treated
+ * as an older build.
+ */
+export type ControllerProbe = {
+    readonly state: "ready";
+    readonly protocol: number;
+} | {
+    readonly state: "foreign";
+} | {
+    readonly state: "silent";
+};
+/** The call surface of the controller listening here. Only an actual answer can be foreign. */
+export declare function controllerProtocol(socketPath: string): Promise<ControllerProbe>;
+export declare function callController(socketPath: string, call: ControllerCall, signal?: AbortSignal): Promise<ControllerReply>;