agent-relay-server 0.121.5 → 0.122.1

package/runner/src/reply-obligation-cache.ts

@@ -0,0 +1,136 @@
+import type { ReplyObligation } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
+import { logger } from "./logger";
+
+// Phase 2 (#196) — the crux. The Claude Stop hook used to ask the server, synchronously
+// and in the hot path, "does this agent owe a reply?" before clearing the turn. A slow
+// server answer (the unindexed reply_to scan, #199) blew the hook's timeout and wedged the
+// agent in `busy` forever. The fix: the hook asks the Runner, the Runner answers instantly
+// from this local snapshot, and the snapshot is refreshed from the server only in the
+// background — never on the path that ends a turn.
+//
+// Design rules:
+// - `get()` is synchronous, never throws, never touches the network.
+// - `refresh()` is the only thing that talks to the server; it coalesces concurrent calls
+//   and, on failure, keeps the last-known snapshot (stale-but-serving beats blocking).
+// - A background interval keeps the snapshot warm; `markDirty()` requests an extra,
+//   debounced refresh when state likely just changed (a message arrived, a turn ended).
+
+// #418 — the human `user` sink is NOT delivered via an explicit relay reply: the agent's
+// turn is mirrored to the dashboard chat by the session-mirror lane (always, for managed
+// agents). So an explicit `/reply` to `user` double-delivers — the operator sees the mirrored
+// turn AND the explicit copy. Only agent↔agent / spawner obligations (#413) need an explicit
+// reply to clear and reach their recipient. This is the single home for that distinction —
+// both the Claude Stop-hook nag (control-server) and the non-claude re-injection (runner)
+// gate on it, so the rule must not drift between them.
+export function obligationRequiresExplicitReply(obligation: ReplyObligation): boolean {
+  if (obligation.source === "spawn-obligation") return false;
+  return obligation.from !== "user";
+}
+
+export function responseCaptureReplyRoute(
+  obligations: ReplyObligation[],
+  currentTurnStartedAt?: number,
+  opts: { suppressUser?: boolean } = {},
+): { replyToMessageId?: number; to: string } | null {
+  const eligible = [...obligations].reverse()
+    .filter((o) => currentTurnStartedAt === undefined || o.createdAt <= currentTurnStartedAt);
+  const explicit = eligible.find(obligationRequiresExplicitReply);
+  if (explicit) return { replyToMessageId: explicit.messageId, to: explicit.from };
+  const user = eligible.find((o) => o.from === "user");
+  if (!user) return { to: "user" };
+  return opts.suppressUser ? null : { replyToMessageId: user.messageId, to: "user" };
+}
+
+type ReplyObligationFetch = () => Promise<ReplyObligation[]>;
+
+interface ReplyObligationCacheOptions {
+  fetch: ReplyObligationFetch;
+  // Background freshness backstop. Default 10s — well under any turn cadence, cheap.
+  intervalMs?: number;
+  // Debounce window for markDirty()-triggered refreshes so a burst of events
+  // (e.g. a fan-out of messages) collapses into one server round-trip.
+  dirtyDebounceMs?: number;
+}
+
+const DEFAULT_INTERVAL_MS = 10_000;
+const DEFAULT_DIRTY_DEBOUNCE_MS = 400;
+
+export class ReplyObligationCache {
+  private readonly fetch: ReplyObligationFetch;
+  private readonly intervalMs: number;
+  private readonly dirtyDebounceMs: number;
+
+  private snapshot: ReplyObligation[] = [];
+  private lastRefreshedAt = 0;
+  private inFlight: Promise<void> | null = null;
+  private intervalTimer?: ReturnType<typeof setInterval>;
+  private dirtyTimer?: ReturnType<typeof setTimeout>;
+  private stopped = false;
+
+  constructor(options: ReplyObligationCacheOptions) {
+    this.fetch = options.fetch;
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.dirtyDebounceMs = options.dirtyDebounceMs ?? DEFAULT_DIRTY_DEBOUNCE_MS;
+  }
+
+  // Synchronous, hot-path-safe read. Returns a copy so callers can't mutate the snapshot.
+  get(): ReplyObligation[] {
+    return this.snapshot.slice();
+  }
+
+  getLastRefreshedAt(): number {
+    return this.lastRefreshedAt;
+  }
+
+  // Begin the background freshness loop and prime the first snapshot immediately.
+  start(): void {
+    if (this.intervalTimer || this.stopped) return;
+    void this.refresh();
+    this.intervalTimer = setInterval(() => { void this.refresh(); }, this.intervalMs);
+    // Don't keep the process alive solely for cache refreshes.
+    this.intervalTimer.unref?.();
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.intervalTimer) clearInterval(this.intervalTimer);
+    this.intervalTimer = undefined;
+    if (this.dirtyTimer) clearTimeout(this.dirtyTimer);
+    this.dirtyTimer = undefined;
+  }
+
+  // Request a refresh because state likely changed (message arrived / turn ended).
+  // Debounced so a burst collapses into a single server round-trip.
+  markDirty(): void {
+    if (this.stopped || this.dirtyTimer) return;
+    this.dirtyTimer = setTimeout(() => {
+      this.dirtyTimer = undefined;
+      void this.refresh();
+    }, this.dirtyDebounceMs);
+    this.dirtyTimer.unref?.();
+  }
+
+  // Fetch from the server and replace the snapshot. Coalesces concurrent callers onto a
+  // single in-flight request. Never rejects — a failed fetch leaves the prior snapshot in
+  // place (the hook keeps getting an answer even while the server is down).
+  refresh(): Promise<void> {
+    if (this.stopped) return Promise.resolve();
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.doRefresh().finally(() => { this.inFlight = null; });
+    return this.inFlight;
+  }
+
+  private async doRefresh(): Promise<void> {
+    try {
+      const obligations = await this.fetch();
+      if (this.stopped) return;
+      this.snapshot = Array.isArray(obligations) ? obligations : [];
+      this.lastRefreshedAt = Date.now();
+    } catch (error) {
+      // Server-down is a non-event: keep serving the last snapshot. Debug, not error —
+      // this is expected during outages and must not spam the log.
+      logger.debug("obligation-cache", `refresh failed, serving cached snapshot (${this.snapshot.length}): ${errMessage(error)}`);
+    }
+  }
+}

package/runner/src/response-capture-report.ts

@@ -0,0 +1,63 @@
+import type { MessageSessionMeta, SendMessageInput } from "agent-relay-sdk";
+
+interface ReportOutbox {
+  enqueue(record: { kind: string; idempotencyKey?: string; payload: SendMessageInput }): void;
+}
+
+type SessionPublisher = (input: {
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+  replyTo?: number;
+}) => void | Promise<void>;
+
+function finalSession(session: MessageSessionMeta): MessageSessionMeta {
+  return { ...session, final: true };
+}
+
+export async function publishCapturedResponse(input: {
+  publishSessionEvent: SessionPublisher;
+  outbox: ReportOutbox;
+  provider: string;
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+  replyTo?: number;
+}): Promise<void> {
+  await input.publishSessionEvent({
+    from: input.from,
+    to: input.to,
+    body: input.body,
+    ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+    session: finalSession(input.session),
+  });
+  enqueueCapturedResponseReport(input);
+}
+
+export function enqueueCapturedResponseReport(input: {
+  outbox: ReportOutbox;
+  provider: string;
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+  replyTo?: number;
+}): void {
+  if (!input.replyTo || input.to === "user") return;
+  const turnId = input.session.turnId ?? "";
+  input.outbox.enqueue({
+    kind: "session-message",
+    idempotencyKey: `response-report:${input.from}:${input.replyTo}:${turnId}`,
+    payload: {
+      from: input.from,
+      to: input.to,
+      replyTo: input.replyTo,
+      kind: "chat",
+      body: input.body,
+      replyExpected: false,
+      payload: { responseCapture: { provider: input.provider, ...finalSession(input.session) } },
+    },
+  });
+}