@fitchmultz/pi-subagents 0.50.0 → 0.51.0

package/src/agent/view.ts

@@ -2,16 +2,16 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readOutputPage } from "../shared/output-page.ts";
-import { actor, alive } from "./process.ts";
+import { actor, alive, observeAlive } from "./process.ts";
 import {
   admissionSchema,
   commandSchema,
   exitSchema,
   successorSchema,
   type Launch,
-  type RunsInput,
   type Result,
 } from "./contracts.ts";
+import type { RunsInput } from "./tool-schemas.ts";
 import { conversation, read, runDirectory } from "./storage.ts";
 import { published } from "./notifications.ts";
 import { readCanonicalResult, readResult } from "./usage.ts";
@@ -56,16 +56,37 @@ interface RunView extends Omit<RunSummary, "result"> {
   result?: Result;
   output: ReturnType<typeof outputView>;
 }
-export function toolResult(value: unknown, text = JSON.stringify(value, null, 2)): ToolReply {
+type Receipt =
+  | { readonly receipt: "launch"; readonly note: string }
+  | { readonly receipt: "continuation" | "existing-successor" }
+  | { readonly receipt: "guidance"; readonly command: string; readonly note: string }
+  | { readonly stopRequest?: string; readonly stopAcknowledged: false; readonly note: string };
+
+function toolResult(value: unknown, text: string): ToolReply {
   return { content: [{ type: "text" as const, text }], details: value };
 }
-function processView(base: string, launch: Launch) {
+function receiptResult(result: Result | undefined) {
+  return result === undefined
+    ? undefined
+    : {
+        id: result.id,
+        owner: result.owner,
+        status: result.status,
+        endedAt: result.endedAt,
+        terminalEntryId: result.terminalEntryId,
+        error: result.error,
+        accountingError: result.accountingError,
+        accountingPending: result.accountingPending,
+      };
+}
+/** `observed` holds batched liveness by actor token; any other actor gets a fresh check. */
+function processView(base: string, launch: Launch, observed?: ReadonlyMap<string, boolean>) {
   const identity = actor(base, launch);
   const exit = identity
     ? read(path.join(conversation(base, launch), `exit-${identity.token}.json`), exitSchema)
     : undefined;
   return {
-    live: identity !== undefined && alive(identity),
+    live: identity !== undefined && (observed?.get(identity.token) ?? alive(identity)),
     exit: exit ?? null,
     exitKnown: exit !== undefined,
   };
@@ -120,10 +141,14 @@ function metadata(
   base: string,
   launch: Launch,
   result: Result | undefined,
-  options: { ctx?: ExtensionContext; guidance: Guidance[] },
+  options: {
+    ctx?: ExtensionContext;
+    guidance: Guidance[];
+    observed?: ReadonlyMap<string, boolean>;
+  },
 ): Omit<RunView, "output"> {
   const directory = runDirectory(base, launch.id);
-  const process = processView(base, launch);
+  const process = processView(base, launch, options.observed);
   const outputFile = path.join(directory, "output.txt");
   const admission = read(
     path.join(conversation(base, launch), "admissions", `${launch.id}.json`),
@@ -156,16 +181,22 @@ function metadata(
     guidance: options.guidance,
   };
 }
-export function summaries(
+async function summaries(
   base: string,
   launches: readonly Launch[],
   ctx?: ExtensionContext,
-): RunSummary[] {
+): Promise<RunSummary[]> {
   const guidance = guidanceView(base, launches);
+  const identities = [
+    ...new Map(launches.map((launch) => [launch.rootId, actor(base, launch)])).values(),
+  ].filter((identity) => identity !== undefined);
+  const verdicts = await observeAlive(identities);
+  const observed = new Map(identities.map((identity, index) => [identity.token, verdicts[index]]));
   return launches.map((launch) => {
     const view = metadata(base, launch, readCanonicalResult(base, launch), {
       ctx,
       guidance: guidance.get(launch.id) ?? [],
+      observed,
     });
     return {
       ...view,
@@ -180,7 +211,7 @@ export function summaries(
     };
   });
 }
-export function projection(
+function projection(
   base: string,
   launch: Launch,
   ctx?: ExtensionContext,
@@ -195,6 +226,32 @@ export function projection(
     output: outputView(view.outputFile, input),
   };
 }
+export function renderReceipt(
+  base: string,
+  launch: Launch,
+  ctx: ExtensionContext | undefined,
+  receipt: Receipt,
+): ToolReply {
+  const details = { ...projection(base, launch, ctx), ...receipt };
+  const model = { ...details, result: receiptResult(details.result) };
+  return toolResult(details, JSON.stringify(model, null, 2));
+}
+export async function renderInventory(
+  base: string,
+  launches: readonly Launch[],
+  ctx: ExtensionContext | undefined,
+  input: Pick<RunsInput, "offset">,
+): Promise<ToolReply> {
+  const offset = input.offset ?? 0;
+  const runs = await summaries(base, launches.slice(offset, offset + 50), ctx);
+  const details = {
+    runs,
+    offset,
+    nextOffset: offset + runs.length < launches.length ? offset + runs.length : undefined,
+    total: launches.length,
+  };
+  return toolResult(details, JSON.stringify(details, null, 2));
+}
 function receiptText(details: RunView): string {
   return details.nativeReceipt !== null
     ? `Native completion receipt: published (${details.nativeReceipt}); publication does not prove model consumption.`
@@ -225,20 +282,13 @@ function resultText(details: RunView): string {
     `Native journal: ${details.sessionFile}`,
   ].join("\n");
 }
-export function render(
+export function renderInspection(
   base: string,
   launch: Launch,
   ctx?: ExtensionContext,
-  input: Pick<RunsInput, "offset" | "length"> & { receivedResult?: boolean } = {},
+  input: Pick<RunsInput, "offset" | "length"> = {},
 ): ToolReply {
-  const view = projection(base, launch, ctx, input);
-  const details = {
-    ...view,
-    receivedResult: input.receivedResult === true,
-    ...(input.receivedResult === true && view.result?.contributions !== undefined
-      ? { agentUsage: view.result.contributions }
-      : {}),
-  };
+  const details = projection(base, launch, ctx, input);
   return {
     ...toolResult(details, resultText(details)),
     isError: details.result?.status === "failed",

package/src/agent/wake.ts

@@ -0,0 +1,107 @@
+import * as fs from "node:fs";
+import { journalStamp } from "../shared/native-journal.ts";
+import { missing } from "./storage.ts";
+
+/** Identity and change stamp of a path; "" when absent. */
+export function pathStamp(file: string): string {
+  try {
+    const stat = fs.statSync(file, { bigint: true, throwIfNoEntry: false });
+    return stat === undefined ? "" : journalStamp(stat);
+  } catch {
+    return "unreadable";
+  }
+}
+
+/**
+ * `armed`: hints start now, so reconcile anything published earlier.
+ * `changed`: the directory's own entries changed since the previous check, which also
+ * covers hints the OS dropped.
+ */
+export type WatchState = "unwatched" | "armed" | "changed" | "watching";
+
+/** Native change hints for one directory identity; owners still reconcile canonical files. */
+export class DirectoryWatch {
+  private watcher?: fs.FSWatcher;
+  private armed = "";
+  private checked = "";
+  private failed = false;
+  private readonly directory: string;
+  private readonly relevant: (file: string | null) => boolean;
+  private readonly wake: () => void;
+  constructor(directory: string, relevant: (file: string | null) => boolean, wake: () => void) {
+    this.directory = directory;
+    this.relevant = relevant;
+    this.wake = wake;
+  }
+  ensure(): WatchState {
+    const stat = fs.statSync(this.directory, { bigint: true, throwIfNoEntry: false });
+    const identity = stat?.isDirectory() === true ? `${stat.dev}:${stat.ino}` : "";
+    const checked = this.checked;
+    this.checked = stat === undefined ? "" : `${identity}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    if (this.watcher !== undefined && identity === this.armed) {
+      return checked === this.checked ? "watching" : "changed";
+    }
+    // A replaced directory leaves an inode watch silent on Linux.
+    this.close();
+    return identity === "" || this.failed ? "unwatched" : this.arm(identity);
+  }
+  private arm(identity: string): WatchState {
+    try {
+      const watcher = fs.watch(this.directory, { persistent: false }, (_event, file) => {
+        if (watcher === this.watcher && this.relevant(file)) {
+          this.wake();
+        }
+      });
+      watcher.on("error", () => {
+        if (watcher === this.watcher) {
+          this.failed = true;
+          this.close();
+          this.wake();
+        }
+      });
+      this.watcher = watcher;
+      this.armed = identity;
+      return "armed";
+    } catch (error) {
+      // Unsupported platforms and watch limits keep their owner's polling fallback.
+      this.failed = !missing(error);
+      return "unwatched";
+    }
+  }
+  close(): void {
+    this.watcher?.close();
+    this.watcher = undefined;
+    this.armed = "";
+  }
+}
+
+/** A coalesced wake for one owner loop; raised until that loop takes it. */
+export class Wake {
+  private raised = true;
+  private resolve?: () => void;
+  readonly raise = (): void => {
+    this.raised = true;
+    this.resolve?.();
+  };
+  take(): boolean {
+    const raised = this.raised;
+    this.raised = false;
+    return raised;
+  }
+  /** Returns at once for a wake raised since the last take. */
+  async sleep(ms: number): Promise<void> {
+    if (this.raised) {
+      return;
+    }
+    const { promise, resolve } = Promise.withResolvers<"woken" | "elapsed">();
+    const timer = setTimeout(() => {
+      resolve("elapsed");
+    }, ms);
+    this.resolve = () => {
+      resolve("woken");
+    };
+    await promise;
+    clearTimeout(timer);
+    this.resolve = undefined;
+  }
+}

package/src/intercom-client.ts

@@ -0,0 +1,108 @@
+import {
+  IntercomClient as BrokerClient,
+  type IntercomClientOptions as BrokerOptions,
+} from "./pi-intercom/broker/client.ts";
+import {
+  isDeliveryGuard,
+  type DeliveryGuard,
+  type LastMessageQuery,
+  type LastMessageResult,
+  type ReceiptQuery,
+  type ReceiptResult,
+  type SendOptions,
+  type SendResult,
+  type SessionInfo,
+} from "./pi-intercom/types.ts";
+import { isRecord } from "./shared/unknown.ts";
+
+export type {
+  ContextTarget,
+  DeliveryGuard,
+  LastMessageQuery,
+  LastMessageResult,
+  MessageDelivery,
+  NativeReceipt,
+  PublicationReplyHint,
+  ReceiptQuery,
+  ReceiptResult,
+  SendResult,
+  SessionInfo,
+} from "./pi-intercom/types.ts";
+
+export type GuardedSendOptions = Omit<
+  SendOptions,
+  "messageId" | "guard" | "expectsReply" | "replyTo" | "human" | "topic" | "passive" | "delivery"
+> & {
+  readonly messageId: string;
+  readonly guard: DeliveryGuard;
+  readonly expectsReply: false;
+  readonly delivery: "queue" | "steer" | "passive";
+};
+
+export interface IntercomClientOptions extends BrokerOptions {
+  readonly spawn: false;
+  readonly session: Omit<
+    SessionInfo,
+    "id" | "guardedDelivery" | "applicationGuard" | "topics" | "subscriptions"
+  >;
+  readonly requestedId?: string;
+  readonly onError?: (error: Readonly<Error>) => void;
+}
+
+export interface IntercomClient {
+  readonly sessionId: string | null;
+  readonly isConnected: () => boolean;
+  readonly listSessions: () => Promise<readonly SessionInfo[]>;
+  readonly send: (to: string, options: GuardedSendOptions) => Promise<SendResult>;
+  readonly last: (to: string, query?: LastMessageQuery) => Promise<LastMessageResult>;
+  readonly receipt: (to: string, query: ReceiptQuery) => Promise<ReceiptResult>;
+  readonly disconnect: () => Promise<void>;
+}
+
+function requireNoSpawn(value: unknown): void {
+  if (value !== false) {
+    throw new Error("The supported Intercom client requires spawn:false.");
+  }
+}
+
+function guardedSend(to: string, input: unknown): boolean {
+  return (
+    isRecord(input) &&
+    isDeliveryGuard(input.guard) &&
+    to === input.guard.peerId &&
+    typeof input.messageId === "string" &&
+    input.expectsReply === false &&
+    input.delivery !== undefined
+  );
+}
+
+/** Connect to an existing native broker. No Pi runtime, broker spawn or automatic retry. */
+export async function connectIntercom(options: IntercomClientOptions): Promise<IntercomClient> {
+  requireNoSpawn(options.spawn);
+  const client = new BrokerClient(options);
+  client.on("error", (error: Readonly<Error>) => options.onError?.(error));
+  try {
+    await client.connect(options.session, options.requestedId);
+  } catch (error) {
+    await client.disconnect();
+    throw error;
+  }
+  return Object.freeze({
+    get sessionId() {
+      return client.sessionId;
+    },
+    isConnected: () => client.isConnected(),
+    listSessions: () => client.listSessions(),
+    async send(to: string, input: GuardedSendOptions) {
+      if (!guardedSend(to, input)) {
+        throw new Error(
+          "An exact guarded nonblocking send with an original message ID is required.",
+        );
+      }
+      return await client.send(to, input);
+    },
+    last: (to: string, query?: LastMessageQuery) => client.last(to, query),
+    receipt: (to: string, query: ReceiptQuery) => client.receipt(to, query),
+    disconnect: () => client.disconnect(),
+  });
+}

package/src/pi-intercom/bridge-session.ts

@@ -6,7 +6,7 @@ import type { Message, SendResult, SessionInfo } from "./types.ts";
 import type { Identity } from "./bridge-config.ts";
 import { Fault, cancelled, log, wait } from "./bridge-protocol.ts";
 import { Mailbox } from "./bridge-mailbox.ts";
-import type { UnknownRecord } from "../shared/unknown.ts";
+import { hasErrorCode, type UnknownRecord } from "../shared/unknown.ts";
 import type { Operation } from "./bridge-routes.ts";
 import type { RequestContext } from "./bridge-http.ts";
 import { resolveBridgeTarget, bridgeSessionList } from "./bridge-target.ts";
@@ -272,7 +272,7 @@ export class Session {
       peers = await wait(this.client.listSessions(), signal);
     } catch (error) {
       cancelled(signal);
-      if (error instanceof Error && error.message === "List sessions timeout") {
+      if (hasErrorCode(error, "list_timeout")) {
         throw new Fault(504, "list_timeout", "Broker session list deadline exceeded.");
       }
       throw new Fault(503, "broker_unavailable", "Broker session list failed.");

package/src/pi-intercom/broker/broker.ts

@@ -7,11 +7,11 @@ import { getBrokerRuntimeDir, prepareBrokerSocketPath } from "./paths.ts";
 import { brokerPidRecord } from "./pid.ts";
 import { assertBrokerCanStart } from "./spawn.ts";
 import { LastMessageRelay } from "./last.ts";
-import { assertMainParent, canSeeSession, findSessions } from "./targets.ts";
-import { acceptBrokerConnection } from "./server-connection.ts";
+import { canSeeSession, findSessions } from "./targets.ts";
+import { acceptBrokerConnection, registeredSessionInfo } from "./server-connection.ts";
+import { guardedDeliveryError } from "./guard.ts";
 import {
   compactTopicMessage,
-  isSessionRegistration,
   normalizeMessage,
   normalizeSessionInfo,
   type SessionInfo,
@@ -41,6 +41,7 @@ interface ConnectedSession {
   topics: TopicSnapshot;
   readonly topicFrames: boolean;
   readonly lastMessages: boolean;
+  readonly receiptReads: boolean;
 }
 
 interface PendingReplaceDelivery {
@@ -153,17 +154,8 @@ class IntercomBroker {
   }
 
   private register(socket: net.Socket, msg: UnknownRecord, setId: (id: string) => void): void {
-    if (!isSessionRegistration(msg.session)) {
-      throw new Error("Invalid register message");
-    }
-    assertMainParent(msg.session, this.sessions);
-    const requestedId =
-      typeof msg.requestedId === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(msg.requestedId)
-        ? msg.requestedId
-        : undefined;
-    const id =
-      requestedId !== undefined && !this.sessions.has(requestedId) ? requestedId : randomUUID();
-    const info: SessionInfo = { ...msg.session, id, lastSeen: msg.session.lastSeen ?? Date.now() };
+    const info = registeredSessionInfo(msg, this.sessions);
+    const id = info.id;
     snapshotFrames(randomUUID(), [info], true);
     const topicFrames = msg.topicFrames === true;
     this.sessions.set(id, {
@@ -172,6 +164,7 @@ class IntercomBroker {
       topics: new TopicSnapshot(info),
       topicFrames,
       lastMessages: msg.lastMessages === true,
+      receiptReads: msg.receiptReads === 1,
     });
     setId(id);
     if (this.shutdownTimer) {
@@ -182,6 +175,8 @@ class IntercomBroker {
       type: "registered",
       sessionId: id,
       lastMessages: true,
+      receiptReads: 1,
+      ...(msg.guardedDelivery === 1 ? { guardedDelivery: 1 } : {}),
       ...(topicFrames ? { topicsSupported: true, topicFrames: true } : {}),
     });
   }
@@ -296,6 +291,15 @@ class IntercomBroker {
     const targets = findSessions(this.sessions, msg.to, currentId);
     const target = targets[0];
     if (targets.length === 1) {
+      const guardError = guardedDeliveryError(this.sessions, msg.to, message);
+      if (guardError !== null) {
+        writeMessage(socket, {
+          type: "delivery_failed",
+          messageId: message.id,
+          reason: guardError,
+        });
+        return;
+      }
       const fromSession = this.sessions.get(currentId);
       if (!fromSession) {
         writeMessage(socket, {
@@ -343,11 +347,15 @@ class IntercomBroker {
       "lastIntercomActivity",
       "subscriptions",
       "topics",
+      "applicationGuard",
     ]) {
       if (msg[key] !== undefined) {
         update[key] = msg[key];
       }
     }
+    if (msg.applicationGuard === null) {
+      delete update.applicationGuard;
+    }
     const nextInfo = normalizeSessionInfo(update);
     if (!nextInfo) {
       throw new Error("Invalid presence update");
@@ -366,15 +374,7 @@ class IntercomBroker {
     message: Message,
   ): SendResult {
     const target = this.sessions.get(toId);
-    if (!target) {
-      return {
-        id: message.id,
-        accepted: false,
-        delivered: false,
-        reason: "Recipient disconnected before delivery",
-      };
-    }
-    if (shouldReplaceDelivery(message, target.info)) {
+    if (target && shouldReplaceDelivery(message, target.info)) {
       return this.queueReplaceDelivery(fromId, toId, from, message);
     }
     const reason = this.deliverMessage(toId, from, message);
@@ -465,6 +465,10 @@ class IntercomBroker {
   }
 
   private deliverMessage(toId: string, from: SessionInfo, message: Message): string | null {
+    const guardError = guardedDeliveryError(this.sessions, toId, message);
+    if (guardError !== null) {
+      return guardError;
+    }
     const target = this.sessions.get(toId);
     if (
       !target ||

package/src/pi-intercom/broker/client-last.ts

@@ -1,15 +1,25 @@
 import type net from "node:net";
 import { randomUUID } from "node:crypto";
 import { errorMessage, type UnknownRecord } from "../../shared/unknown.ts";
-import type { LastMessageResult } from "../types.ts";
-import { isLastMessageQuery, isLastMessageResult } from "./last.ts";
+import {
+  isNativeReadQuery,
+  isNativeReadResult,
+  isLastMessageResult,
+  isReceiptResult,
+  type NativeReadResult,
+} from "./last.ts";
+import type { LastMessageQuery, LastMessageResult, ReceiptQuery, ReceiptResult } from "../types.ts";
 import { writeMessage } from "./framing.ts";
 
 export class LastMessageRequests {
+  private readonly timeoutMs: number;
+  constructor(timeoutMs: number) {
+    this.timeoutMs = timeoutMs;
+  }
   private readonly pending = new Map<
     string,
     {
-      readonly resolve: (result: LastMessageResult) => void;
+      readonly resolve: (result: NativeReadResult) => void;
       readonly reject: (error: Readonly<Error>) => void;
       readonly timer: NodeJS.Timeout;
     }
@@ -24,7 +34,7 @@ export class LastMessageRequests {
   }
 
   receive(message: UnknownRecord): void {
-    if (typeof message.requestId !== "string" || !isLastMessageResult(message.result)) {
+    if (typeof message.requestId !== "string" || !isNativeReadResult(message.result)) {
       throw new Error("Invalid last-message response");
     }
     const pending = this.pending.get(message.requestId);
@@ -36,13 +46,16 @@ export class LastMessageRequests {
     pending.resolve(message.result);
   }
 
-  request(
-    socket: net.Socket,
-    to: string,
-    query: unknown,
-    timeoutMs: number,
-  ): Promise<LastMessageResult> {
-    if (!isLastMessageQuery(query)) {
+  async last(socket: net.Socket, to: string, query: LastMessageQuery): Promise<LastMessageResult> {
+    const result = await this.request(socket, to, query);
+    return isLastMessageResult(result) ? result : { error: "Invalid last-message response" };
+  }
+  async receipt(socket: net.Socket, to: string, query: ReceiptQuery): Promise<ReceiptResult> {
+    const result = await this.request(socket, to, query);
+    return isReceiptResult(result) ? result : { error: "Invalid receipt response" };
+  }
+  private request(socket: net.Socket, to: string, query: unknown): Promise<NativeReadResult> {
+    if (!isNativeReadQuery(query)) {
       return Promise.reject(new Error("Invalid last-message query"));
     }
     return new Promise((resolve, reject) => {
@@ -50,7 +63,7 @@ export class LastMessageRequests {
       const timer = setTimeout(() => {
         this.pending.delete(requestId);
         reject(new Error("Last-message read timeout"));
-      }, timeoutMs);
+      }, this.timeoutMs);
       timer.unref();
       this.pending.set(requestId, { resolve, reject, timer });
       try {