@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/src/agent/view.ts

@@ -0,0 +1,296 @@
+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, observeAlive } from "./process.ts";
+import {
+  admissionSchema,
+  commandSchema,
+  exitSchema,
+  successorSchema,
+  type Launch,
+  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";
+import { Type } from "./typebox.ts";
+
+const commandMetadataSchema = Type.Pick(commandSchema, ["id", "runId", "action", "createdAt"]);
+interface Guidance {
+  id: string;
+  runId: string;
+  action: "steer";
+  state: "pending" | "accepted" | "stale";
+  at: number;
+}
+
+interface ToolReply {
+  content: { type: "text"; text: string }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface RunSummary {
+  id: string;
+  owner: string;
+  rootId: string;
+  predecessor?: string;
+  name?: string;
+  cwd: string;
+  model: string;
+  thinking: string;
+  context: string;
+  admission: string;
+  status: string;
+  completed: boolean;
+  result?: Pick<Result, "status" | "endedAt" | "error">;
+  nativeReceipt: string | null;
+  process: ReturnType<typeof processView>;
+  sessionId: string;
+  sessionFile: string;
+  outputFile: string;
+  guidance: Guidance[];
+}
+interface RunView extends Omit<RunSummary, "result"> {
+  result?: Result;
+  output: ReturnType<typeof outputView>;
+}
+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 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 && (observed?.get(identity.token) ?? alive(identity)),
+    exit: exit ?? null,
+    exitKnown: exit !== undefined,
+  };
+}
+function outputView(file: string, input: Pick<RunsInput, "offset" | "length">) {
+  return fs.existsSync(file)
+    ? readOutputPage(file, { offset: input.offset ?? 0, length: input.length ?? 32768 })
+    : undefined;
+}
+function guidanceView(base: string, launches: readonly Launch[]): Map<string, Guidance[]> {
+  const runs = new Map<string, Guidance[]>(launches.map((launch) => [launch.id, []]));
+  for (const rootId of new Set(launches.map((launch) => launch.rootId))) {
+    const runIds = new Set(
+      launches.filter((launch) => launch.rootId === rootId).map((launch) => launch.id),
+    );
+    const directory = runDirectory(base, rootId);
+    const dir = path.join(directory, "commands");
+    if (!fs.existsSync(dir)) {
+      continue;
+    }
+    fs.readdirSync(dir)
+      .filter((file) => file.endsWith(".json"))
+      .forEach((file) => {
+        const command = read(
+          path.join(dir, file),
+          commandMetadataSchema,
+          (keys) =>
+            keys.length === 0 ||
+            (keys.length === 1 && Object.hasOwn(commandMetadataSchema.properties, String(keys[0]))),
+        );
+        const guidance = command && runIds.has(command.runId) ? runs.get(command.runId) : undefined;
+        if (command?.action !== "steer" || !guidance) {
+          return;
+        }
+        const admission = read(
+          path.join(directory, "admissions", `${command.id}.json`),
+          admissionSchema,
+        );
+        guidance.push({
+          id: command.id,
+          runId: command.runId,
+          action: command.action,
+          state: admission ? (admission.state ?? "accepted") : "pending",
+          at: admission?.at ?? command.createdAt,
+        });
+        guidance.sort((a, b) => b.at - a.at).splice(20);
+      });
+  }
+  return runs;
+}
+function metadata(
+  base: string,
+  launch: Launch,
+  result: Result | undefined,
+  options: {
+    ctx?: ExtensionContext;
+    guidance: Guidance[];
+    observed?: ReadonlyMap<string, boolean>;
+  },
+): Omit<RunView, "output"> {
+  const directory = runDirectory(base, launch.id);
+  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`),
+    admissionSchema,
+  );
+  const status =
+    result?.status ??
+    (process.live && read(path.join(directory, "successor.json"), successorSchema) === undefined
+      ? "running"
+      : "interrupted");
+  return {
+    id: launch.id,
+    owner: launch.owner,
+    rootId: launch.rootId,
+    predecessor: launch.predecessor,
+    name: launch.name,
+    cwd: launch.cwd,
+    model: `${launch.provider}/${launch.model}`,
+    thinking: launch.thinking,
+    context: launch.context,
+    admission: admission ? "admitted" : "pending",
+    status,
+    completed: result !== undefined,
+    result,
+    nativeReceipt: options.ctx ? (published(options.ctx, launch) ?? null) : null,
+    process,
+    sessionId: launch.sessionId,
+    sessionFile: launch.sessionFile,
+    outputFile,
+    guidance: options.guidance,
+  };
+}
+async function summaries(
+  base: string,
+  launches: readonly Launch[],
+  ctx?: ExtensionContext,
+): 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,
+      name: view.name?.slice(0, 256),
+      result: view.result
+        ? {
+            status: view.result.status,
+            endedAt: view.result.endedAt,
+            error: view.result.error?.slice(0, 2048),
+          }
+        : undefined,
+    };
+  });
+}
+function projection(
+  base: string,
+  launch: Launch,
+  ctx?: ExtensionContext,
+  input: Pick<RunsInput, "offset" | "length"> = {},
+): RunView {
+  const view = metadata(base, launch, readResult(base, launch), {
+    ctx,
+    guidance: guidanceView(base, [launch]).get(launch.id) ?? [],
+  });
+  return {
+    ...view,
+    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.`
+    : "Native completion receipt: not observed published; queue admission is not publication or model consumption.";
+}
+function exitText(details: RunView): string {
+  return details.process.exit
+    ? `Process exit observed: code ${details.process.exit.code ?? "unknown"}, signal ${details.process.exit.signal ?? "none"}.`
+    : "Process exit: unknown; run completion does not imply process exit.";
+}
+function resultText(details: RunView): string {
+  const page = details.output;
+  const suffix =
+    page?.nextOffset !== undefined
+      ? `\n[Output continues: agent_runs inspect id=${details.id} offset=${page.nextOffset}; ${page.size} bytes total.]`
+      : "";
+  const guidance = details.guidance
+    .map((command) => `  ${command.id}: ${command.state}`)
+    .join("\n");
+  return [
+    `Agent run ${details.id}: ${details.status}; admission ${details.admission}; process ${details.process.live ? "live" : "not observed live"}.`,
+    receiptText(details),
+    exitText(details),
+    `Guidance (latest 20):\n${guidance.length > 0 ? guidance : "  none"}`,
+    "Guidance states: pending = not yet admitted; accepted = native queue admission, not journal publication or model consumption; stale = rejected, no new work was started (retry the entire prompt as a continuation).",
+    details.result?.error ?? "",
+    `${page?.text ?? ""}${suffix}`,
+    `Native journal: ${details.sessionFile}`,
+  ].join("\n");
+}
+export function renderInspection(
+  base: string,
+  launch: Launch,
+  ctx?: ExtensionContext,
+  input: Pick<RunsInput, "offset" | "length"> = {},
+): ToolReply {
+  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/index.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import agents from "./agent/index.ts";
+import observe from "./agent/observe.ts";
+import intercom from "./pi-intercom/index.ts";
+
+export default function extension(pi: ExtensionAPI): void {
+  agents(pi);
+  observe(pi);
+  intercom(pi);
+}

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-config.ts

@@ -1,10 +1,8 @@
-import { realpathSync, statSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import { createSecureContext } from "node:tls";
 import { parseEnv } from "node:util";
 import { isUnknownArray } from "../shared/unknown.ts";
-import { BODY_LIMIT, object, label, fingerprint } from "./bridge-protocol.ts";
-import { launchPolicy, type LaunchPolicy } from "./bridge-launch-policy.ts";
+import { BODY_LIMIT, object, label, fingerprint, log } from "./bridge-protocol.ts";
 import { stateDirectory } from "./bridge-storage.ts";
 import { readBridgeFile } from "./bridge-files.ts";
 
@@ -41,7 +39,6 @@ export interface Identity {
   readonly fingerprint256: string;
   readonly name: string;
   readonly cwd: string;
-  readonly launch?: LaunchPolicy;
   readonly wake?: WakePolicy;
 }
 export interface Config {
@@ -60,30 +57,35 @@ function identities(value: unknown): Map<string, Identity> {
   }
   const clients = new Map<string, Identity>();
   const names = new Set<string>();
+  let retiredLaunch = false;
   for (const raw of value) {
-    const entry = object(raw, ["fingerprint256", "name", "cwd", "launch", "wake"]);
+    const entry = object(raw, ["fingerprint256", "name", "cwd", "wake", "launch"]);
+    retiredLaunch ||= Object.hasOwn(entry, "launch");
     const fingerprint256 = fingerprint(entry.fingerprint256);
     const name = label(entry.name, "name", 128).trim();
     const cwd = label(entry.cwd, "cwd", 4096);
     if (!isAbsolute(cwd)) {
       throw new Error("Client cwd must be absolute.");
     }
-    const launch = launchPolicy(entry.launch);
-    if (launch && !statSync(cwd).isDirectory()) {
-      throw new Error("Launch cwd must be an existing directory.");
-    }
+
     if (clients.has(fingerprint256) || names.has(name.toLowerCase())) {
       throw new Error("Client fingerprints and names must be unique.");
     }
     clients.set(fingerprint256, {
       fingerprint256,
       name,
-      cwd: launch ? realpathSync(cwd) : cwd,
-      launch,
+      cwd,
       wake: wakePolicy(entry.wake),
     });
     names.add(name.toLowerCase());
   }
+  if (retiredLaunch) {
+    log("deprecated_config_field", {
+      field: "clients[].launch",
+      action: "ignored",
+      note: "Remote launch is retired. Remove this field when convenient; no launch permission is granted.",
+    });
+  }
   return clients;
 }
 
@@ -94,19 +96,6 @@ function configInput(path: string): Record<string, unknown> {
   return object(raw, ["port", "ca", "cert", "key", "clients", "stateDir"]);
 }
 
-/** Recipient admission reads private policy and the public CA, never the server key. */
-export function loadControlPolicy(path: string): {
-  readonly clients: ReadonlyMap<string, Identity>;
-  readonly ca: Buffer;
-} {
-  const input = configInput(path);
-  const ca = label(input.ca, "ca path", 4096);
-  if (!isAbsolute(ca)) {
-    throw new Error("CA path must be absolute.");
-  }
-  return { clients: identities(input.clients), ca: readBridgeFile(ca, false, 1024 * 1024) };
-}
-
 export function loadConfig(path: string): Config {
   const input = configInput(path);
   const port = input.port === undefined ? 9443 : input.port;

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

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { BODY_LIMIT, Fault, BroadcastFault } from "./bridge-protocol.ts";
+import { BODY_LIMIT, Fault } from "./bridge-protocol.ts";
 import { errorMessage, type UnknownRecord } from "../shared/unknown.ts";
 
 export interface RequestContext {
@@ -105,7 +105,6 @@ export function reply(
 export function replyFault(res: ServerResponse, requestId: string, fault: Fault): void {
   reply(res, requestId, fault.status, {
     ok: false,
-    ...(fault instanceof BroadcastFault ? fault.outcome : {}),
     error: { code: fault.code, message: fault.message, ...fault.details },
   });
 }

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

@@ -1,8 +1,7 @@
 import type { DatabaseSync } from "node:sqlite";
 import { privateDatabase } from "./bridge-storage.ts";
 import { isRecord, type UnknownRecord } from "../shared/unknown.ts";
-import { normalizeMessage, normalizeSessionInfo } from "./types.ts";
-import type { Envelope } from "./bridge-ask.ts";
+import { normalizeMessage, normalizeSessionInfo, type Message, type SessionInfo } from "./types.ts";
 import {
   Fault,
   INBOX_BYTES,
@@ -10,6 +9,11 @@ import {
   fingerprint as certificateFingerprint,
 } from "./bridge-protocol.ts";
 
+export interface Envelope {
+  readonly from: SessionInfo;
+  readonly message: Message;
+}
+
 interface Entry extends Envelope {
   readonly sequence: number;
   readonly bytes: number;
@@ -192,19 +196,15 @@ export class Mailbox {
   }
   ack(ids: readonly string[]): UnknownRecord {
     const acked: string[] = [];
-    const retained: string[] = [];
     for (const id of ids) {
       const entry = this.get(id);
-      if (entry?.message.expectsReply === true) {
-        // Durable consumer intake owns the primary wake; keep only the reply obligation here.
+      if (entry) {
         this.notificationAccepted(id);
-        retained.push(id);
-      } else if (entry) {
         this.remove(id);
         acked.push(id);
       }
     }
-    return { acked, retained };
+    return { acked };
   }
   page(after: number, limit: number): InboxPage {
     return this.readPage(after, limit, false);