@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/src/agent/usage.ts

@@ -1,12 +1,8 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { Usage } from "@earendil-works/pi-ai";
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { journalStamp } from "../shared/native-journal.ts";
-import { isDeepStrictEqual } from "node:util";
 import { nativeProjection } from "../shared/journal-projections.ts";
 import { scanJournal } from "../shared/journal-frames.ts";
-import type { Projection } from "../shared/json-projection.ts";
 import { isRecord } from "../shared/unknown.ts";
 import { Assert } from "./typebox.ts";
 import {
@@ -18,132 +14,6 @@ import {
 } from "./contracts.ts";
 import { read, runDirectory, write } from "./storage.ts";
 
-export function sumUsage(values: readonly Contribution[]): Usage {
-  const total: Usage = {
-    input: 0,
-    output: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    totalTokens: 0,
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-  };
-  for (const { usage } of values) {
-    for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const) {
-      total[key] += usage[key];
-    }
-    for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
-      total.cost[key] += usage.cost[key];
-    }
-    for (const key of ["reasoning", "cacheWrite1h"] as const) {
-      if (usage[key] !== undefined) {
-        total[key] = (total[key] ?? 0) + usage[key];
-      }
-    }
-  }
-  return total;
-}
-function intents(details: unknown): Contribution[] | undefined {
-  if (!isRecord(details) || details.agentUsage === undefined) {
-    return;
-  }
-  const values: unknown = details.agentUsage;
-  Assert(contributionsSchema, values);
-  return values;
-}
-function publishedContributions(entry: unknown): Contribution[] {
-  if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message)) {
-    return [];
-  }
-  const message = entry.message;
-  if (
-    message.role !== "toolResult" ||
-    (message.toolName !== "delegate" && message.toolName !== "agent_runs")
-  ) {
-    return [];
-  }
-  const values = intents(message.details);
-  if (values === undefined || !isDeepStrictEqual(sumUsage(values), message.usage)) {
-    return [];
-  }
-  return values;
-}
-const receiptProjection: Projection = (keys) => {
-  if (keys.length === 0 || keys[0] === "type") {
-    return true;
-  }
-  if (keys[0] !== "message") {
-    return false;
-  }
-  if (keys.length === 1 || ["role", "toolName", "usage"].includes(String(keys[1]))) {
-    return true;
-  }
-  return keys[1] === "details" && (keys.length === 2 || keys[2] === "agentUsage");
-};
-function priorUsage(ctx: ExtensionContext): Map<string, Contribution> {
-  const values = new Map<string, Contribution>();
-  const file = ctx.sessionManager.getSessionFile();
-  if (file !== undefined) {
-    scanJournal(
-      file,
-      receiptProjection,
-      ({ value: entry }) => {
-        for (const value of publishedContributions(entry)) {
-          values.set(value.id, value);
-        }
-      },
-      { policy: "live", requireNewline: true },
-    );
-  }
-  for (const entry of ctx.sessionManager.getEntries()) {
-    for (const value of publishedContributions(entry)) {
-      values.set(value.id, value);
-    }
-  }
-  return values;
-}
-function uncharged(
-  values: readonly Contribution[],
-  prior: Map<string, Contribution>,
-): Contribution[] {
-  const pending: Contribution[] = [];
-  for (const value of values) {
-    const earlier = prior.get(value.id);
-    if (earlier && !isDeepStrictEqual(earlier, value)) {
-      throw new Error(`Conflicting native usage contribution ${value.id}`);
-    }
-    if (!earlier) {
-      pending.push(value);
-      prior.set(value.id, value);
-    }
-  }
-  return pending;
-}
-export function registerUsage(pi: ExtensionAPI): void {
-  pi.on("message_end", (event, ctx) => {
-    const message = event.message;
-    if (
-      message.role !== "toolResult" ||
-      (message.toolName !== "delegate" && message.toolName !== "agent_runs")
-    ) {
-      return;
-    }
-    const values = intents(message.details);
-    if (values === undefined || !isRecord(message.details)) {
-      return;
-    }
-    const pending = uncharged(values, priorUsage(ctx));
-    const { usage: _usage, ...rest } = message;
-    // Finalized native tool messages are serialized even for concurrent tools.
-    // Preparing or discarding a result cannot reserve a charge.
-    return {
-      message: {
-        ...rest,
-        details: { ...message.details, agentUsage: pending },
-        ...(pending.length > 0 ? { usage: sumUsage(pending) } : {}),
-      },
-    };
-  });
-}
 function billing(entry: Record<string, unknown>) {
   if (entry.checkpoint === true) {
     return;

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.");