@fitchmultz/pi-subagents 0.52.19 → 0.52.21

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

@@ -0,0 +1,37 @@
+interface Request {
+  readonly reject: (error: Readonly<Error>) => void;
+}
+
+/** Map membership owns settlement; taking a request also releases its deadline. */
+export class PendingRequests<T extends Request> {
+  private readonly pending = new Map<
+    string,
+    { readonly value: T; readonly timer: NodeJS.Timeout }
+  >();
+
+  get(id: string): T | undefined {
+    return this.pending.get(id)?.value;
+  }
+
+  set(id: string, value: T, timeoutMs: number, timeoutError: () => Error): void {
+    const timer = setTimeout(() => this.take(id)?.reject(timeoutError()), timeoutMs);
+    timer.unref();
+    this.pending.set(id, { value, timer });
+  }
+
+  take(id: string): T | undefined {
+    const pending = this.pending.get(id);
+    if (pending === undefined) {
+      return;
+    }
+    this.pending.delete(id);
+    clearTimeout(pending.timer);
+    return pending.value;
+  }
+
+  fail(error: Readonly<Error>): void {
+    for (const id of this.pending.keys()) {
+      this.take(id)?.reject(error);
+    }
+  }
+}

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

@@ -0,0 +1,56 @@
+import type { Message, SessionInfo } from "../types.ts";
+
+const REPLACE_DELIVERY_DELAY_MS = 1500;
+
+interface StagedDelivery {
+  readonly fromId: string;
+  readonly toId: string;
+  readonly from: SessionInfo;
+  readonly message: Message;
+  readonly timer: NodeJS.Timeout;
+}
+
+/** Only broker-staged messages remain replaceable; forwarding ends this owner's authority. */
+export class ReplaceDeliveries {
+  private readonly pending = new Map<string, StagedDelivery>();
+  private readonly deliver: (toId: string, from: SessionInfo, message: Message) => string | null;
+
+  constructor(deliver: (toId: string, from: SessionInfo, message: Message) => string | null) {
+    this.deliver = deliver;
+  }
+
+  stage(fromId: string, toId: string, from: SessionInfo, message: Message): void {
+    const key = `${fromId}\0${toId}\0${message.threadId ?? ""}`;
+    this.take(key);
+    const timer = setTimeout(() => this.flush(key), REPLACE_DELIVERY_DELAY_MS);
+    timer.unref();
+    this.pending.set(key, { fromId, toId, from, message, timer });
+  }
+
+  private take(key: string): StagedDelivery | undefined {
+    const pending = this.pending.get(key);
+    if (pending !== undefined) {
+      this.pending.delete(key);
+      clearTimeout(pending.timer);
+    }
+    return pending;
+  }
+
+  private flush(key: string): void {
+    const pending = this.take(key);
+    if (pending !== undefined) {
+      this.deliver(pending.toId, pending.from, pending.message);
+    }
+  }
+
+  disconnected(sessionId: string): void {
+    for (const [key, pending] of this.pending) {
+      if (
+        pending.toId === sessionId ||
+        (pending.fromId === sessionId && pending.message.expectsReply === true)
+      ) {
+        this.take(key);
+      }
+    }
+  }
+}

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

@@ -58,6 +58,14 @@ interface SessionParts {
   readonly subscriptions: TopicSubscription[] | undefined;
 }
 
+type SnapshotPhase =
+  | {
+      readonly kind: "open";
+      readonly sessions: Map<string, SessionParts>;
+      readonly receipts: Receipt[];
+    }
+  | { readonly kind: "finished" | "failed" };
+
 function appendRows<T>(
   previous: T[] | undefined,
   rows: readonly T[] | undefined,
@@ -75,16 +83,28 @@ function appendRows<T>(
 
 /** Multipart frames build a private cache; only a complete validated snapshot escapes. */
 export class SnapshotReader {
-  private readonly sessions = new Map<string, SessionParts>();
-  private readonly receipts: Receipt[] = [];
+  private phase: SnapshotPhase = { kind: "open", sessions: new Map(), receipts: [] };
+
+  private open(): Extract<SnapshotPhase, { readonly kind: "open" }> {
+    if (this.phase.kind !== "open") {
+      throw new Error(`Session snapshot is ${this.phase.kind}`);
+    }
+    return this.phase;
+  }
 
-  private addSession(row: unknown): void {
+  fail(): void {
+    if (this.phase.kind === "open") {
+      this.phase = { kind: "failed" };
+    }
+  }
+
+  private addSession(state: Extract<SnapshotPhase, { readonly kind: "open" }>, row: unknown): void {
     if (!isRecord(row) || typeof row.id !== "string") {
       throw new Error("Invalid session snapshot row");
     }
     const topics = optionalArray(row.topics);
     const subscriptions = optionalArray(row.subscriptions);
-    const previous = this.sessions.get(row.id);
+    const previous = state.sessions.get(row.id);
     const info = normalizeSessionInfo({
       ...previous?.info,
       ...row,
@@ -95,7 +115,7 @@ export class SnapshotReader {
       throw new Error("Invalid session snapshot");
     }
     const { topics: newTopics, subscriptions: newSubscriptions, ...identity } = info;
-    this.sessions.set(info.id, {
+    state.sessions.set(info.id, {
       info: identity,
       topics: appendRows(previous?.topics, newTopics, "topics" in row),
       subscriptions: appendRows(previous?.subscriptions, newSubscriptions, "subscriptions" in row),
@@ -103,27 +123,35 @@ export class SnapshotReader {
   }
 
   append(sessions: readonly unknown[], receipts: unknown): void {
-    for (const row of sessions) {
-      this.addSession(row);
-    }
-    if (receipts === undefined) {
-      return;
-    }
-    if (!isUnknownArray(receipts)) {
-      throw new Error("Invalid topic delivery receipts");
+    const state = this.open();
+    try {
+      for (const row of sessions) {
+        this.addSession(state, row);
+      }
+      if (receipts === undefined) {
+        return;
+      }
+      if (!isUnknownArray(receipts)) {
+        throw new Error("Invalid topic delivery receipts");
+      }
+      state.receipts.push(...receipts.map(receipt));
+    } catch (error) {
+      this.fail();
+      throw error;
     }
-    this.receipts.push(...receipts.map(receipt));
   }
 
   finish(): SessionSnapshot {
+    const state = this.open();
     const sessions: SessionInfo[] = [];
-    for (const { info, topics, subscriptions } of this.sessions.values()) {
+    for (const { info, topics, subscriptions } of state.sessions.values()) {
       sessions.push({
         ...info,
         ...(topics !== undefined ? { topics } : {}),
         ...(subscriptions !== undefined ? { subscriptions } : {}),
       });
     }
-    return { sessions, receipts: this.receipts };
+    this.phase = { kind: "finished" };
+    return { sessions, receipts: state.receipts };
   }
 }

package/src/pi-intercom/connection.ts

@@ -43,8 +43,10 @@ export class IntercomConnection {
   private parked: IntercomClient | null = null;
   private reconnectTimer: NodeJS.Timeout | null = null;
   private startupTimer: NodeJS.Timeout | null = null;
-  private connecting: Promise<IntercomTransport> | null = null;
-  private connectingGeneration: number | null = null;
+  private connecting: {
+    readonly task: Promise<IntercomTransport>;
+    readonly generation: number;
+  } | null = null;
   private attempt = 0;
   private readonly lifecycle: Lifecycle;
   private readonly config: IntercomConfig;
@@ -352,8 +354,8 @@ export class IntercomConnection {
     if (!ctx || generation !== this.lifecycle.generation) {
       throw new Error("Intercom shutting down");
     }
-    if (this.connecting && this.connectingGeneration === generation) {
-      return this.connecting;
+    if (this.connecting?.generation === generation) {
+      return this.connecting.task;
     }
     if (this.client?.isConnected() === true) {
       return this.client;
@@ -365,8 +367,7 @@ export class IntercomConnection {
     this.clearReconnect();
     // Publish ownership before registration, which can synchronously invoke subscribers.
     const attempt = Promise.resolve().then(() => this.connect(ctx, generation, sessionId));
-    this.connecting = attempt;
-    this.connectingGeneration = generation;
+    this.connecting = { task: attempt, generation };
     return await this.finishAttempt(attempt, ctx, generation);
   }
   private async finishAttempt(
@@ -381,9 +382,8 @@ export class IntercomConnection {
       retry = this.lifecycle.live(ctx, generation) !== null;
       throw error;
     } finally {
-      if (this.connecting === attempt) {
+      if (this.connecting?.task === attempt) {
         this.connecting = null;
-        this.connectingGeneration = null;
       }
       if (retry) {
         this.scheduleReconnect();
@@ -394,7 +394,7 @@ export class IntercomConnection {
     this.clearTimers();
     this.cancelWakes();
     // The bounded launcher attempt is joined before socket shutdown.
-    await Promise.allSettled([this.connecting]);
+    await Promise.allSettled([this.connecting?.task]);
     if (this.client) {
       await this.client.disconnect();
       this.client = null;

package/src/pi-intercom/inbound-journal.ts

@@ -191,13 +191,16 @@ export class InboundJournal {
           pending.from.id === entry.from.id &&
           pending.message.threadId === entry.message.threadId
         ) {
-          this.consume(pending.message.id);
-          this.replies.markReplied(pending.message.id);
+          this.supersede(pending.message.id);
         }
       }
     }
     this.pending.set(entry.message.id, entry);
   }
+  private supersede(id: string): void {
+    this.consume(id);
+    this.replies.markReplied(id);
+  }
   setStage(entry: PendingInboundMessage, stage: PendingInboundMessage["stage"]): void {
     if (entry.stage === stage) {
       return;

package/src/shared/journal-frames.ts

@@ -16,13 +16,15 @@ export interface JournalOptions {
   readonly stringChunk?: StringChunk | undefined;
 }
 
+type RecordState =
+  | { readonly kind: "blank" | "reading" }
+  | { readonly kind: "invalid"; readonly error: unknown };
+
 /** Byte-framed JSONL. Publication framing is independent of malformed-record tolerance. */
 export class JournalFrames {
   private projection: JsonProjection;
   private decoder = new TextDecoder("utf8", { fatal: true });
-  private error: unknown;
-  private failed = false;
-  private nonblank = false;
+  private state: RecordState = { kind: "blank" };
   private start: number;
   offset: number;
   private readonly policy: JournalPolicy;
@@ -48,20 +50,20 @@ export class JournalFrames {
     return new JsonProjection(this.select, this.options.stringChunk);
   }
   private part(bytes: Buffer): void {
-    if (!this.nonblank && bytes.some((byte) => ![9, 10, 13, 32].includes(byte))) {
-      this.nonblank = true;
+    if (this.state.kind === "invalid") {
+      return;
     }
-    if (!this.failed) {
-      try {
-        this.projection.write(this.decoder.decode(bytes, { stream: true }));
-      } catch (error) {
-        this.failed = true;
-        this.error = error;
-      }
+    if (this.state.kind === "blank" && bytes.some((byte) => ![9, 10, 13, 32].includes(byte))) {
+      this.state = { kind: "reading" };
+    }
+    try {
+      this.projection.write(this.decoder.decode(bytes, { stream: true }));
+    } catch (error) {
+      this.state = { kind: "invalid", error };
     }
   }
   private finishRecord(end: number): JournalRecord | undefined {
-    if (!this.nonblank || this.failed) {
+    if (this.state.kind !== "reading") {
       return undefined;
     }
     try {
@@ -72,17 +74,16 @@ export class JournalFrames {
       }
       return { value, start: this.start, end };
     } catch (error) {
-      this.failed = true;
-      this.error = error;
+      this.state = { kind: "invalid", error };
       return undefined;
     }
   }
   private commit(end: number): void {
     const start = this.start;
     const record = this.finishRecord(end);
-    const failed = this.failed;
-    const error = this.error;
-    if (failed && this.policy !== "inspect") {
+    const state = this.state;
+    if (state.kind === "invalid" && this.policy !== "inspect") {
+      const { error } = state;
       throw new SyntaxError(`Invalid JSONL record at byte ${start}: ${errorDescription(error)}`, {
         cause: error,
       });
@@ -90,10 +91,8 @@ export class JournalFrames {
     this.start = end;
     this.projection = this.newProjection();
     this.decoder = new TextDecoder("utf8", { fatal: true });
-    this.error = undefined;
-    this.failed = false;
-    this.nonblank = false;
-    if (!failed && record) {
+    this.state = { kind: "blank" };
+    if (record) {
       this.record(record);
     }
   }
@@ -110,7 +109,7 @@ export class JournalFrames {
   }
   finish(): number {
     if (this.requireNewline) {
-      if (this.policy === "strict" && this.nonblank) {
+      if (this.policy === "strict" && this.state.kind !== "blank") {
         throw new SyntaxError(`Unpublished JSONL record at byte ${this.start}: newline required`);
       }
     } else if (this.offset > this.start) {