@humwick/runner 0.0.0-stage → 0.130.1

package/src/reply-obligation-cache.ts

@@ -0,0 +1,211 @@
+import type { Message, ReplyObligation } from "@humwick/sdk";
+import { isHumanAgentId, ACK_REACTION_EMOJIS, errMessage, isMechanicalMessageKind } from "@humwick/sdk";
+import { latestReplyableMessage, type ProviderSessionEvent } from "./adapter";
+import { logger } from "./logger";
+import { receivesTurnResponseAutomatically } from "./response-routing";
+
+// 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).
+
+export function obligationRequiresExplicitReply(obligation: ReplyObligation): boolean {
+  if (obligation.source === "spawn-obligation") return false;
+  return !receivesTurnResponseAutomatically(obligation.from);
+}
+
+// #2831 — automatic nags (Stop-hook block, idle re-injection) skip an obligation the server marked
+// deferred: its owner is waiting on its own relay_run. The obligation itself stays open.
+export function obligationNagEligible(obligation: ReplyObligation): boolean {
+  return obligationRequiresExplicitReply(obligation) && obligation.nagDeferral === undefined;
+}
+
+// #2335 (P1 privacy) — does this obligation's originator sit behind a CHANNEL-EGRESS bridge
+// (`telegram:<account>`, …)? A bridge forwards what it receives to a real human's DM, so the runner's
+// auto-captured turn narration must never be ADDRESSED at one; the obligation itself still stands and
+// still requires an EXPLICIT reply (obligationRequiresExplicitReply is deliberately untouched).
+//
+// The runner has no channel registry — the relay owns that, and owns the routing guard
+// (isDisallowedChannelContent, src/db/channel-egress-allowlist.ts). So this reads the channel facts
+// the server already stamps onto every obligation, and reads them NARROWLY, because a false positive
+// here is not free: it redirects the worker's turn-final capture to the dashboard mirror and drops
+// `replyTo`, which for a peer obligation means the coordinator silently loses its auto report-up.
+//
+//   `kind === "channel.event"` — the server's OWN classification of the inbound. `inferMessageKind`
+//     types anything from a channel agent this way, so the leaking egress-failure notice matches.
+//   `channel === from` — the obligation's channel names the originator ITSELF, i.e. the sender is the
+//     bridge. A bare non-empty `channel` is NOT enough: `channel` is a free-form caller-set string on
+//     ANY message (`/message <peer> --channel X`, an integration event, a reply that inherited
+//     `parent.channel`), so keying on its mere presence caught ordinary peer traffic.
+export function obligationOriginatesFromChannel(obligation: Pick<ReplyObligation, "from" | "kind" | "channel">): boolean {
+  return obligation.kind === "channel.event" || obligation.channel === obligation.from;
+}
+
+export function responseCaptureReplyRoute(
+  obligations: ReplyObligation[],
+  currentTurnStartedAt?: number,
+  opts: { suppressUser?: boolean } = {},
+): { replyToMessageId?: number; to: string; channelTarget?: boolean } | 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,
+      ...(obligationOriginatesFromChannel(explicit) ? { channelTarget: true } : {}),
+    };
+  }
+  const user = eligible.find((o) => receivesTurnResponseAutomatically(o.from));
+  if (!user) return { to: "user" };
+  return opts.suppressUser ? null : { replyToMessageId: user.messageId, to: user.from };
+}
+
+type ReplyObligationFetch = () => Promise<ReplyObligation[]>;
+
+/** The route a turn opened by this delivered batch answers (#2840): its latest replyable message that could
+ * carry an obligation — never the agent's own run/timer wake (sent to itself) nor a system/control notice. */
+export function deliveredBatchReplyRoute(messages: Message[], selfId?: string): NonNullable<ProviderSessionEvent["replyRoute"]> | null {
+  const replyable = latestReplyableMessage(messages.filter((m) => m.from !== m.to && m.from !== selfId && !isMechanicalMessageKind(m.kind)));
+  return replyable ? { to: replyable.from, replyToMessageId: replyable.id, channelTarget: obligationOriginatesFromChannel(replyable), replyExpected: replyable.replyExpected === true } : null;
+}
+
+/** #2840 — the server's "answered" rule (annotateAnsweredMessages): the agent replied to it or later in
+ * its thread with a live (non-suppressed) message, or acknowledged it with an ack reaction. */
+export function threadAnswers(thread: Message[], askedId: number, agentId: string): boolean {
+  const asked = thread.find((m) => m.id === askedId);
+  if (asked?.reactions?.some((r) => r.actorId === agentId && ACK_REACTION_EMOJIS.includes(r.emoji) && r.createdAt >= asked.createdAt)) return true;
+  return thread.some((m) => m.from === agentId && m.kind !== "session" && (isHumanAgentId(m.to) || m.payload?.reportSuppression === undefined)
+    && (m.replyTo === askedId || (asked?.threadId !== undefined && m.threadId === asked.threadId && m.id > askedId)));
+}
+
+/** The server's obligation-settle rule: only a live reply with reply_to settles a reply-expected message. */
+function repliesTo(thread: Message[], askedId: number, agentId: string): boolean {
+  return thread.some((m) => m.from === agentId && m.kind !== "session" && m.replyTo === askedId && (isHumanAgentId(m.to) || m.payload?.reportSuppression === undefined));
+}
+
+// Peer chat has no obligation row and can be acknowledged without a reply, so the thread decides: relay_reply
+// (or 👍) followed by a native final stays single. A route backed by an obligation row (a reply-expected
+// message, or `fromObligationRow`) follows the server's settle rule and is already proven open when unreadable.
+export async function submittedResponseReplyRoute(
+  route: ProviderSessionEvent["replyRoute"], getThread: (id: number) => Promise<Message[]>, agentId: string, fromObligationRow = false,
+): Promise<ProviderSessionEvent["replyRoute"]> {
+  if (!route) return route;
+  const obligation = fromObligationRow || route.replyExpected === true;
+  try {
+    const thread = await getThread(route.replyToMessageId);
+    return (obligation ? repliesTo : threadAnswers)(thread, route.replyToMessageId, agentId) ? null : route;
+  } catch { return obligation ? route : null; } // Never guess that an unreachable peer debt is open.
+}
+
+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;
+const NAG_REFRESH_TIMEOUT_MS = 1_000;
+
+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?.();
+  }
+
+  // #2831 — a nag (Stop-hook block, idle re-injection) decided on a stale snapshot can miss a relay_run
+  // started this turn, or one that just settled. Re-read once, bounded well under the Stop hook's 2s
+  // curl budget, but only when an explicit-reply obligation is in play; otherwise serve the snapshot.
+  async freshForNag(timeoutMs = NAG_REFRESH_TIMEOUT_MS): Promise<ReplyObligation[]> {
+    if (!this.snapshot.some(obligationRequiresExplicitReply)) return this.get();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    await Promise.race([this.refresh(), new Promise<void>((resolve) => { timer = setTimeout(resolve, timeoutMs); })]);
+    clearTimeout(timer);
+    return this.get();
+  }
+
+  // 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/src/response-capture-report.ts

@@ -0,0 +1,111 @@
+import type { MessageSessionMeta, SendMessageInput } from "@humwick/sdk";
+
+import { receivesTurnResponseAutomatically } from "./response-routing";
+
+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>;
+
+/** The turn-final capture's addressing, after the #2335 channel guard has had its say. */
+interface CaptureRoute {
+  to: string;
+  replyTo?: number;
+}
+
+interface CapturedResponseInput {
+  outbox: ReportOutbox;
+  provider: string;
+  from: string;
+  to: string;
+  body: string;
+  session: MessageSessionMeta;
+  replyTo?: number;
+  /**
+   * #2335 — the reply route resolved to a CHANNEL-EGRESS bridge (see obligationOriginatesFromChannel,
+   * runner/src/reply-obligation-cache.ts). Set by the caller; absent means "not a channel".
+   */
+  channelTarget?: boolean;
+}
+
+// #1086: dual-stamp the Part A (#1082) turn-finality field alongside the legacy
+// `final` alias so old consumers keep working while new ones can key off the
+// typed `turnFinal` flag directly instead of every writer's own `final: true`.
+function finalSession(session: MessageSessionMeta): MessageSessionMeta {
+  return { ...session, turnFinal: true, final: true };
+}
+
+/**
+ * #2335 (P1 privacy) — the runner-side half of "auto-captured narration NEVER reaches a channel".
+ *
+ * What this function captures is the agent's raw terminal narration at turn end: its own running
+ * commentary, written for its operator's scrollback. Whenever a reply obligation was open, that text
+ * was ADDRESSED at the obligation's originator — and the only originator ever skipped was the literal
+ * string `"user"`. That sentinel is far too narrow: the moment the originator is a channel bridge
+ * (`telegram:<account>`, e.g. an obligation inherited from a bridge-sent egress-failure notice),
+ * `'telegram:default' !== 'user'` held, so the narration was addressed at the bridge and DM'd to that
+ * account's allowlisted human. The exposure is generic per account, not specific to one bot.
+ *
+ * This guard is the SOURCE fix — the cheapest and most surgical of the two layers, since auto-captured
+ * narration is never a freeform note and so refusing to emit it at a channel target has zero collateral.
+ * It is not the only layer: the relay owns the channel registry and re-decides at both the send-side
+ * stamp and the channel-recipient poll (isDisallowedChannelContent, src/db/channel-egress-allowlist.ts),
+ * which is what still holds when the sender is a stale runner, an automation, or a raw POST.
+ *
+ * The capture is not discarded — #1083 requires a turn-final capture to ALWAYS be mirrored. It is
+ * re-addressed to the `user` dashboard-mirror sink with the reply link dropped, exactly the shape an
+ * autonomous turn with no eligible obligation already produces. Dropping `replyTo` is the point, not a
+ * side effect: the channel obligation stays OPEN and still demands an explicit `relay_reply` /
+ * `relay_egress_to_channel`, so a channel gets a deliberate, addressed answer or none at all.
+ */
+function captureRoute(input: CapturedResponseInput): CaptureRoute {
+  if (input.channelTarget === true) return { to: "user" };
+  return { to: input.to, ...(input.replyTo ? { replyTo: input.replyTo } : {}) };
+}
+
+export async function publishCapturedResponse(input: CapturedResponseInput & {
+  publishSessionEvent: SessionPublisher;
+}): Promise<void> {
+  const route = captureRoute(input);
+  // #2844 — the enqueued chat report IS the parent delivery, so the mirror stays
+  // transcript-only (`user` sink): at most one parent-addressed row per turn-final. (Before,
+  // the mirror ALSO went to the parent, doubling opener-answered turns and splitting the
+  // #2831/#2840 suppression decision.) The mirror keeps replyTo + turn stamp for lineage.
+  const reported = input.replyTo !== undefined && !receivesTurnResponseAutomatically(input.to) && input.channelTarget !== true;
+  await input.publishSessionEvent({
+    from: input.from,
+    to: reported ? "user" : route.to,
+    body: input.body,
+    ...(route.replyTo ? { replyTo: route.replyTo } : {}),
+    session: finalSession(input.session),
+  });
+  enqueueCapturedResponseReport({ ...input, ...route, replyTo: route.replyTo });
+}
+
+export function enqueueCapturedResponseReport(input: CapturedResponseInput): void {
+  // #2335 — `to === "user"` is kept (the dashboard mirror already carries the turn; a report would
+  // double it) but is NO LONGER the only skip: a channel-egress target is dropped outright, whether
+  // it arrived here pre-rewritten by captureRoute or straight from a caller that never consulted it.
+  if (!input.replyTo || receivesTurnResponseAutomatically(input.to) || input.channelTarget === true) 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) } },
+    },
+  });
+}

package/src/response-routing.ts

@@ -0,0 +1,6 @@
+import { isHumanAgentId } from "@humwick/sdk/types/users";
+// The runner mirrors every completed turn to the dashboard's user sink, regardless of role.
+// Keep header/nag policy and capture-report routing on the same recipient rule (#3346).
+export function receivesTurnResponseAutomatically(recipient: string): boolean {
+  return isHumanAgentId(recipient);
+}