@wrongstack/core 0.291.2 → 0.292.1

package/dist/coordination/index.js

@@ -328,6 +328,112 @@ function expectDefined(value, label) {
   return value;
 }
 
+// src/utils/message-invariants.ts
+function repairToolUseAdjacency(messages) {
+  const removedToolUses = [];
+  const removedToolResults = [];
+  let removedMessages = 0;
+  let changed = false;
+  const out = [];
+  for (let i = 0; i < messages.length; i++) {
+    const original = expectDefined(messages[i]);
+    let msg = original;
+    if (hasToolUse(msg)) {
+      const nextIds = toolResultIds(messages[i + 1]);
+      const filtered = mapContent(msg, (blocks) => {
+        const next = [];
+        for (const block of blocks) {
+          if (block.type === "tool_use" && !nextIds.has(block.id)) {
+            removedToolUses.push(block.id);
+            changed = true;
+            continue;
+          }
+          next.push(block);
+        }
+        return next;
+      });
+      msg = filtered ?? msg;
+    }
+    if (hasToolResult(msg)) {
+      const allowed = toolUseIds(out[out.length - 1]);
+      const filtered = mapContent(msg, (blocks) => {
+        const next = [];
+        for (const block of blocks) {
+          if (block.type === "tool_result" && !allowed.has(block.tool_use_id)) {
+            removedToolResults.push(block.tool_use_id);
+            changed = true;
+            continue;
+          }
+          next.push(block);
+        }
+        return next;
+      });
+      msg = filtered ?? msg;
+    }
+    if (isEmptyMessage(msg)) {
+      removedMessages++;
+      changed = true;
+      continue;
+    }
+    out.push(msg);
+  }
+  return {
+    messages: changed ? out : messages,
+    report: { changed, removedToolUses, removedToolResults, removedMessages }
+  };
+}
+function hasToolUse(msg) {
+  return contentBlocks(msg).some((b) => b.type === "tool_use");
+}
+function hasToolResult(msg) {
+  return contentBlocks(msg).some((b) => b.type === "tool_result");
+}
+function toolUseIds(msg) {
+  const ids = /* @__PURE__ */ new Set();
+  if (msg?.role !== "assistant") return ids;
+  for (const block of contentBlocks(msg)) {
+    if (block.type === "tool_use") ids.add(block.id);
+  }
+  return ids;
+}
+function toolResultIds(msg) {
+  const ids = /* @__PURE__ */ new Set();
+  if (msg?.role !== "user") return ids;
+  for (const block of contentBlocks(msg)) {
+    if (block.type === "tool_result") ids.add(block.tool_use_id);
+  }
+  return ids;
+}
+function contentBlocks(msg) {
+  return msg && Array.isArray(msg.content) ? msg.content : [];
+}
+function mapContent(msg, fn) {
+  if (!Array.isArray(msg.content)) return msg;
+  const next = fn(msg.content);
+  if (next.length === msg.content.length && next.every((b, idx) => b === msg.content[idx])) {
+    return msg;
+  }
+  return { ...msg, content: next };
+}
+function hasMeaningfulContent(content) {
+  if (typeof content === "string") return content.trim().length > 0;
+  for (const block of content) {
+    if (block.type === "text") {
+      if (block.text.trim().length > 0) return true;
+      continue;
+    }
+    if (block.type === "thinking") {
+      if (block.thinking.trim().length > 0 || block.signature) return true;
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+function isEmptyMessage(msg) {
+  return !hasMeaningfulContent(msg.content);
+}
+
 // src/utils/glob-expand.ts
 import * as fsp from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
@@ -455,112 +561,6 @@ async function expandGlob(pattern) {
   return [...results];
 }
 
-// src/utils/message-invariants.ts
-function repairToolUseAdjacency(messages) {
-  const removedToolUses = [];
-  const removedToolResults = [];
-  let removedMessages = 0;
-  let changed = false;
-  const out = [];
-  for (let i = 0; i < messages.length; i++) {
-    const original = expectDefined(messages[i]);
-    let msg = original;
-    if (hasToolUse(msg)) {
-      const nextIds = toolResultIds(messages[i + 1]);
-      const filtered = mapContent(msg, (blocks) => {
-        const next = [];
-        for (const block of blocks) {
-          if (block.type === "tool_use" && !nextIds.has(block.id)) {
-            removedToolUses.push(block.id);
-            changed = true;
-            continue;
-          }
-          next.push(block);
-        }
-        return next;
-      });
-      msg = filtered ?? msg;
-    }
-    if (hasToolResult(msg)) {
-      const allowed = toolUseIds(out[out.length - 1]);
-      const filtered = mapContent(msg, (blocks) => {
-        const next = [];
-        for (const block of blocks) {
-          if (block.type === "tool_result" && !allowed.has(block.tool_use_id)) {
-            removedToolResults.push(block.tool_use_id);
-            changed = true;
-            continue;
-          }
-          next.push(block);
-        }
-        return next;
-      });
-      msg = filtered ?? msg;
-    }
-    if (isEmptyMessage(msg)) {
-      removedMessages++;
-      changed = true;
-      continue;
-    }
-    out.push(msg);
-  }
-  return {
-    messages: changed ? out : messages,
-    report: { changed, removedToolUses, removedToolResults, removedMessages }
-  };
-}
-function hasToolUse(msg) {
-  return contentBlocks(msg).some((b) => b.type === "tool_use");
-}
-function hasToolResult(msg) {
-  return contentBlocks(msg).some((b) => b.type === "tool_result");
-}
-function toolUseIds(msg) {
-  const ids = /* @__PURE__ */ new Set();
-  if (msg?.role !== "assistant") return ids;
-  for (const block of contentBlocks(msg)) {
-    if (block.type === "tool_use") ids.add(block.id);
-  }
-  return ids;
-}
-function toolResultIds(msg) {
-  const ids = /* @__PURE__ */ new Set();
-  if (msg?.role !== "user") return ids;
-  for (const block of contentBlocks(msg)) {
-    if (block.type === "tool_result") ids.add(block.tool_use_id);
-  }
-  return ids;
-}
-function contentBlocks(msg) {
-  return msg && Array.isArray(msg.content) ? msg.content : [];
-}
-function mapContent(msg, fn) {
-  if (!Array.isArray(msg.content)) return msg;
-  const next = fn(msg.content);
-  if (next.length === msg.content.length && next.every((b, idx) => b === msg.content[idx])) {
-    return msg;
-  }
-  return { ...msg, content: next };
-}
-function hasMeaningfulContent(content) {
-  if (typeof content === "string") return content.trim().length > 0;
-  for (const block of content) {
-    if (block.type === "text") {
-      if (block.text.trim().length > 0) return true;
-      continue;
-    }
-    if (block.type === "thinking") {
-      if (block.thinking.trim().length > 0 || block.signature) return true;
-      continue;
-    }
-    return true;
-  }
-  return false;
-}
-function isEmptyMessage(msg) {
-  return !hasMeaningfulContent(msg.content);
-}
-
 // src/utils/safe-json.ts
 function safeParse(input, maxBytes = 5e6) {
   if (Buffer.byteLength(input, "utf8") > maxBytes) {
@@ -5235,8 +5235,8 @@ function createDelegateTool(opts) {
   };
   return {
     name: "delegate",
-    description: "Hand a piece of work to a subagent and wait for its result. Has own context, LLM call, auto-extending budget. Can continue remaining work with a fresh subagent on partial completion (maxHandoffs, default 1). Workers cannot recursively spawn. Use roster roles when possible; otherwise pass `name` + `task`.",
-    usageHint: "Set `task` to a complete instruction. Pick `role` from roster or pass `name` for free-form. Override `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed.",
+    description: "Hand a piece of work to a subagent and block until it returns. This call is synchronous: the leader's iteration pauses for the full duration of the subagent's run. (Multiple `delegate` calls fired in the same assistant turn still parallelize through the provider's parallel-tool-call surface, but each one eats wall-clock time \u2014 so for fan-out you actually control, reach for the async path below.) Use `delegate` when your next step genuinely needs the subagent's verdict \u2014 a review, a fact-check, a sign-off. Has own context, own LLM call, auto-extending budget, and a partial-completion handoff path (maxHandoffs, default 1). Workers cannot recursively spawn.\n\n**Do NOT use `delegate` for fan-out you control.** Multiple sequential `delegate` calls each block the leader, wasting wall-clock time. For independent investigations you want to run in parallel \u2014 security scan + bug hunt + perf review on the same PR \u2014 use the async tool family: `spawn_subagent` to create each worker (returns a `subagentId` immediately), `assign_task` to queue work on it (returns a `taskId` immediately), then the `await_tasks` tool with `{mode: 'any'}` to fold the first useful result into the next decision while the rest keep churning. Reach for `delegate` only when the result gates your next move.",
+    usageHint: "Set `task` to a complete instruction. Pick `role` from roster or pass `name` for free-form. Raise `maxHandoffs` (default 1, cap 8) for multi-day or multi-refactor tasks; pass larger `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed. For parallel work, use `spawn_subagent` + `assign_task` + `await_tasks` instead.",
     permission: "auto",
     mutating: false,
     managesOwnTimeout: true,
@@ -6511,8 +6511,8 @@ function makeSpawnTool(director, roster) {
   };
   return {
     name: "spawn_subagent",
-    description: "Create a new subagent under this director. Returns the subagent id.",
-    usageHint: "Pass `role` (matches the roster), `description` (smart dispatch to best agent), or `name` + `provider`/`model`. Returns `{ subagentId }`.",
+    description: "Create a new subagent under this director (own LLM context, own budget). NON-BLOCKING: returns a `subagentId` immediately without triggering any model call. Pair with `assign_task` to send work and `await_tasks` to retrieve the result later \u2014 this is the async-delegation pattern that lets the leader keep working while the subagent runs in its own context.",
+    usageHint: "Pass `role` (matches the roster), `description` (smart dispatch to best agent), or `name` + `provider`/`model`. Returns `{ subagentId }`. Use this instead of `delegate` when you want to fan out to multiple subagents or keep the leader unblocked while work runs in parallel.",
     permission: "auto",
     mutating: false,
     capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
@@ -6994,7 +6994,7 @@ function makeAssignTool(director) {
   };
   return {
     name: "assign_task",
-    description: "Hand a task to a previously spawned subagent. Returns the task id.",
+    description: "Queue a task on a previously spawned subagent. NON-BLOCKING: returns a `taskId` IMMEDIATELY \u2014 the subagent processes the task on its next iteration with its own LLM budget. The `taskId` is the durable handle for retrieving the result later via `await_tasks`, `roll_up`, or `ask_result`. Many `assign_task` calls can be in flight in parallel against the same or different subagents. This is the primary tool for fan-out work; do NOT use `delegate` to spawn multiple investigations sequentially.",
     permission: "auto",
     mutating: false,
     capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
@@ -7521,7 +7521,7 @@ function resultErrorText(result) {
 function makeAwaitTasksTool(director) {
   return {
     name: "await_tasks",
-    description: 'Wait for assigned tasks. mode:"all" (default) blocks until EVERY named task completes and returns all results. mode:"any" returns as soon as AT LEAST ONE completes \u2014 use it for independent tasks so you can handle each finisher immediately (reassign work, spawn helpers) instead of idling on the slowest; call again with the returned `pending` ids to pick up the next finisher.',
+    description: 'Block until one or more `taskId`s complete, then return their results. The subagents keep running in the background \u2014 only the leader\'s iteration pauses, which is the point: this is the correct tool to retrieve a result you started earlier with `assign_task`. mode:"all" (default) blocks until EVERY named task completes. mode:"any" returns as soon as AT LEAST ONE completes \u2014 use it for independent tasks so you can handle each finisher immediately (reassign work, spawn helpers) instead of idling on the slowest; call again with the returned `pending` ids to pick up the next finisher. The pattern "fan out via assign_task, then await_tasks({mode:\'any\'})" is the async replacement for serial `delegate` calls.',
     permission: "auto",
     mutating: false,
     capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
@@ -8192,9 +8192,10 @@ function hashStr(s) {
 }
 
 // src/types/provider.ts
-var CONTEXT_OVERFLOW_RE = /context.length|context.window|max.*tokens?.*exceeded|prompt is too long|too long|exceeds the context|\btokens\b.*exceed|context_length_exceeded/i;
+var CONTEXT_OVERFLOW_RE = /context.length|context.window|maximum context|max.*tokens?.*exceeded|prompt is too long|too long|exceeds the context|\btokens\b.*exceed|too many tokens|reduce the length|resulted in \d+ tokens|input.{0,12}too (?:large|long)|context_length_exceeded/i;
 var CONTENT_FILTER_RE = /content.(filter|policy|moderation)|safety (system|filter)/i;
-var QUOTA_EXHAUSTED_RE = /(?:insufficient|exhausted|depleted|exceeded|no|not enough)[-_\s]*(?:quota|credit|balance)|(?:quota|credit|balance)[-_\s]*(?:exhausted|depleted|exceeded|insufficient)|billing[_\s-]*(?:hard[_\s-]*)?limit|payment required|spending limit|plan limit/i;
+var QUOTA_EXHAUSTED_RE = /(?:insufficient|exhausted|depleted|exceeded|no|not enough)[-_\s]*(?:quota|credit|balance)|(?:quota|credit|balance)[-_\s]*(?:exhausted|depleted|exceeded|insufficient)|billing[_\s-]*(?:hard[_\s-]*)?limit|payment required|spending limit|plan limit|usage[-_\s]*limit[-_\s]*(?:reached|exceeded)/i;
+var RATE_LIMIT_EXCEEDED_RE = /rate[-_\s]*limit[-_\s]*exceeded/i;
 function classifyProviderError(status, body, message) {
   const type = body?.type;
   const text = [message, body?.message, type, body?.raw].filter(Boolean).join("\n");
@@ -8202,6 +8203,9 @@ function classifyProviderError(status, body, message) {
   if (status === 408) return "timeout";
   if (status === 599) return "stream_hang";
   if (status === 402 || QUOTA_EXHAUSTED_RE.test(text)) return "quota_exhausted";
+  if (status === 429 && body?.message && RATE_LIMIT_EXCEEDED_RE.test(body.message)) {
+    return "quota_exhausted";
+  }
   if (type === "rate_limit_error" || status === 429) return "rate_limit";
   if (type === "overloaded_error" || status === 529) return "overloaded";
   if (status >= 500) return "server";
@@ -17354,6 +17358,8 @@ import { timingSafeEqual } from "node:crypto";
 var MAILBOX_HTTP_MAX_BODY_BYTES = 256 * 1024;
 var MAILBOX_HTTP_RATE_LIMIT_PER_MINUTE = 120;
 var MAILBOX_HTTP_RATE_LIMIT_WINDOW_MS = 6e4;
+var MAILBOX_HTTP_DEFAULT_MAX_AGE_MS = 60 * 60 * 1e3;
+var MAILBOX_HTTP_MAX_AGE_CEILING_MS = 7 * 24 * 60 * 60 * 1e3;
 function authorizeMailboxBearerToken(request, expectedToken) {
   const header = request.headers.authorization;
   if (typeof header !== "string") return { allowed: false };
@@ -17397,6 +17403,7 @@ var MailboxHttpRateLimiter = class {
 };
 function createMailboxHttpRouter(options) {
   const maxBodyBytes = options.maxBodyBytes ?? MAILBOX_HTTP_MAX_BODY_BYTES;
+  const defaultMaxAgeMs = options.defaultMaxAgeMs ?? void 0;
   const closeSseStreams = /* @__PURE__ */ new Set();
   return {
     async handle(request, response, routePath) {
@@ -17411,15 +17418,17 @@ function createMailboxHttpRouter(options) {
         if (!access2.allowed) {
           const forwardedFor = request.headers["x-forwarded-for"];
           const clientIp = (Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor)?.split(",")[0]?.trim() ?? request.socket?.remoteAddress ?? "unknown";
-          console.warn(JSON.stringify({
-            level: "warn",
-            event: "mailbox.http_auth_failure",
-            message: `Mailbox HTTP auth rejected for ${request.method ?? "?"} ${request.url ?? "?"} from ${clientIp}`,
-            method: request.method,
-            url: request.url,
-            clientIp,
-            timestamp: (/* @__PURE__ */ new Date()).toISOString()
-          }));
+          console.warn(
+            JSON.stringify({
+              level: "warn",
+              event: "mailbox.http_auth_failure",
+              message: `Mailbox HTTP auth rejected for ${request.method ?? "?"} ${request.url ?? "?"} from ${clientIp}`,
+              method: request.method,
+              url: request.url,
+              clientIp,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            })
+          );
           writeJson(
             response,
             access2.status ?? 401,
@@ -17446,7 +17455,9 @@ function createMailboxHttpRouter(options) {
           method,
           url,
           maxBodyBytes,
-          closeSseStreams
+          defaultMaxAgeMs,
+          closeSseStreams,
+          routePath
         );
       } catch (error) {
         const code = error instanceof MailboxHttpValidationError ? "VALIDATION_ERROR" : "INTERNAL_ERROR";
@@ -17465,85 +17476,134 @@ function createMailboxHttpRouter(options) {
     }
   };
 }
-async function dispatchMailboxRoute(mailbox, eventEmitter, request, response, method, url, maxBodyBytes, closeSseStreams) {
-  if (method === "POST" && url === "/mailbox/send") {
+async function dispatchMailboxRoute(mailbox, eventEmitter, request, response, method, url, maxBodyBytes, defaultMaxAgeMs, closeSseStreams, routePath) {
+  if (routePath !== void 0 && routePath.indexOf("?") === 0) {
+    throw validationError(`routePath must not start with '?' (got ${JSON.stringify(routePath)})`);
+  }
+  const queryIndex = url.indexOf("?");
+  const path20 = queryIndex === -1 ? url : url.slice(0, queryIndex);
+  if (method === "POST" && path20 === "/mailbox/send") {
     const input = validateSend(await readJsonBody(request, maxBodyBytes));
     writeJson(response, 201, await mailbox.send(input));
     return;
   }
-  if (method === "POST" && url === "/mailbox/query") {
+  if (method === "POST" && path20 === "/mailbox/query") {
+    const queryContext = parseSinceMs(url, defaultMaxAgeMs);
+    if ("error" in queryContext) {
+      writeJson(response, 400, { error: queryContext.error });
+      return;
+    }
     const messages = await mailbox.query(validateQuery(await readJsonBody(request, maxBodyBytes)));
-    writeJson(response, 200, { data: messages, count: messages.length });
+    const filtered = filterMailboxMessagesByTimestamp(messages, queryContext.minTimestampIso);
+    writeJson(response, 200, { data: filtered, count: filtered.length });
     return;
   }
-  if (method === "POST" && url === "/mailbox/check") {
+  if (method === "POST" && path20 === "/mailbox/check") {
+    const queryContext = parseSinceMs(url, defaultMaxAgeMs);
+    if ("error" in queryContext) {
+      writeJson(response, 400, { error: queryContext.error });
+      return;
+    }
     const result = await checkMailbox(
       mailbox,
-      validateCheck(await readJsonBody(request, maxBodyBytes))
+      validateCheck(await readJsonBody(request, maxBodyBytes)),
+      queryContext.minTimestampIso
     );
     writeJson(response, 200, result);
     return;
   }
-  if (method === "POST" && url === "/mailbox/ack") {
+  if (method === "POST" && path20 === "/mailbox/ack") {
     const updated = await mailbox.ack(validateAck(await readJsonBody(request, maxBodyBytes)));
     writeJson(response, 200, { updated });
     return;
   }
-  if (method === "POST" && url === "/mailbox/ack-many") {
+  if (method === "POST" && path20 === "/mailbox/ack-many") {
     const updated = await mailbox.ackMany(
       validateAckMany(await readJsonBody(request, maxBodyBytes))
     );
     writeJson(response, 200, { updated, count: updated.length });
     return;
   }
-  if (method === "POST" && url === "/mailbox/unread-count") {
+  if (method === "POST" && path20 === "/mailbox/unread-count") {
     const body = await readJsonBody(request, maxBodyBytes);
-    writeJson(response, 200, { count: await mailbox.unreadCount(requireString(body, "forAgentId")) });
+    writeJson(response, 200, {
+      count: await mailbox.unreadCount(requireString(body, "forAgentId"))
+    });
     return;
   }
-  if (method === "POST" && url === "/mailbox/agents/register") {
-    await mailbox.registerAgent(validateAgentRegistration(await readJsonBody(request, maxBodyBytes)));
+  if (method === "POST" && path20 === "/mailbox/agents/register") {
+    await mailbox.registerAgent(
+      validateAgentRegistration(await readJsonBody(request, maxBodyBytes))
+    );
     writeJson(response, 200, { ok: true });
     return;
   }
-  if (method === "POST" && url === "/mailbox/agents/heartbeat") {
+  if (method === "POST" && path20 === "/mailbox/agents/heartbeat") {
     await mailbox.heartbeat(validateAgentHeartbeat(await readJsonBody(request, maxBodyBytes)));
     writeJson(response, 200, { ok: true });
     return;
   }
-  if (method === "POST" && url === "/mailbox/register-client") {
-    await mailbox.registerClient(validateClientRegistration(await readJsonBody(request, maxBodyBytes)));
+  if (method === "POST" && path20 === "/mailbox/register-client") {
+    await mailbox.registerClient(
+      validateClientRegistration(await readJsonBody(request, maxBodyBytes))
+    );
     writeJson(response, 200, { ok: true });
     return;
   }
-  if (method === "POST" && url === "/mailbox/heartbeat") {
-    await mailbox.clientHeartbeat(validateClientHeartbeat(await readJsonBody(request, maxBodyBytes)));
+  if (method === "POST" && path20 === "/mailbox/heartbeat") {
+    await mailbox.clientHeartbeat(
+      validateClientHeartbeat(await readJsonBody(request, maxBodyBytes))
+    );
     writeJson(response, 200, { ok: true });
     return;
   }
-  if (method === "POST" && url === "/mailbox/purge-clients") {
+  if (method === "POST" && path20 === "/mailbox/purge-clients") {
     writeJson(response, 200, { ok: true, purged: await mailbox.purgeClients() });
     return;
   }
-  if (method === "GET" && url === "/mailbox/agents") {
+  if (method === "GET" && path20 === "/mailbox/agents") {
     const agents = await mailbox.getAgentStatuses();
     writeJson(response, 200, { data: agents, count: agents.length });
     return;
   }
-  if (method === "GET" && url === "/mailbox/agents/online") {
+  if (method === "GET" && path20 === "/mailbox/agents/online") {
     const agents = await mailbox.getOnlineAgents();
     writeJson(response, 200, { data: agents, count: agents.length });
     return;
   }
-  if (method === "GET" && url === "/mailbox/events" && eventEmitter) {
-    handleSse(request, response, eventEmitter, closeSseStreams);
+  if (method === "GET" && path20 === "/mailbox/events" && eventEmitter) {
+    const queryContext = parseSinceMs(url, defaultMaxAgeMs);
+    if ("error" in queryContext) {
+      writeJson(response, 400, { error: queryContext.error });
+      return;
+    }
+    handleSse(request, response, eventEmitter, queryContext.minTimestampIso, closeSseStreams);
     return;
   }
   writeJson(response, 404, {
     error: { code: "NOT_FOUND", message: `no route for ${method} ${url}` }
   });
 }
-function handleSse(request, response, eventEmitter, closeSseStreams) {
+function extractEventTimestamp(event) {
+  if (event === null || typeof event !== "object") return void 0;
+  const top = event.timestamp;
+  if (typeof top === "string") return top;
+  const nestedKeys = ["messageSent", "ackUpdated"];
+  for (const key of nestedKeys) {
+    const nested = event[key];
+    if (nested !== null && typeof nested === "object") {
+      const inner = nested.timestamp;
+      if (typeof inner === "string") return inner;
+    }
+  }
+  return void 0;
+}
+function isEventOlderThan(event, minTimestampIso) {
+  const eventTimestamp = extractEventTimestamp(event);
+  if (eventTimestamp === void 0) return false;
+  return eventTimestamp < minTimestampIso;
+}
+function handleSse(request, response, eventEmitter, minTimestampIso, closeSseStreams) {
   response.writeHead(200, {
     "Content-Type": "text/event-stream",
     "Cache-Control": "no-store",
@@ -17553,6 +17613,9 @@ function handleSse(request, response, eventEmitter, closeSseStreams) {
   response.write(": connected\n\n");
   const unsubscribe = eventEmitter.subscribe((event) => {
     try {
+      if (minTimestampIso !== void 0 && isEventOlderThan(event, minTimestampIso)) {
+        return;
+      }
       response.write(`data: ${JSON.stringify(event)}
 
 `);
@@ -17662,6 +17725,52 @@ function optionalNumber(object, key) {
   }
   return value;
 }
+function parseSinceMs(url, defaultMaxAgeMs) {
+  const queryStart = url.indexOf("?");
+  if (queryStart === -1) return resolveDefault(defaultMaxAgeMs, Date.now());
+  const params = new URLSearchParams(url.slice(queryStart + 1));
+  if (!params.has("sinceMs")) return resolveDefault(defaultMaxAgeMs, Date.now());
+  const raw = params.get("sinceMs");
+  if (raw === null || raw === void 0 || raw === "") {
+    return {
+      error: {
+        code: "VALIDATION_ERROR",
+        message: 'query parameter "sinceMs" is required (integer in milliseconds) when present'
+      }
+    };
+  }
+  if (!/^\d+$/.test(raw)) {
+    return {
+      error: {
+        code: "VALIDATION_ERROR",
+        message: 'query parameter "sinceMs" must be a non-negative integer (milliseconds)'
+      }
+    };
+  }
+  const requestedMs = Number(raw);
+  if (!Number.isFinite(requestedMs) || requestedMs > Number.MAX_SAFE_INTEGER) {
+    return {
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `query parameter "sinceMs" is out of range (max ${Number.MAX_SAFE_INTEGER})`
+      }
+    };
+  }
+  const now = Date.now();
+  if (requestedMs === 0) return { minTimestampIso: void 0 };
+  const effectiveMs = Math.min(requestedMs, MAILBOX_HTTP_MAX_AGE_CEILING_MS);
+  return { minTimestampIso: new Date(now - effectiveMs).toISOString() };
+}
+function resolveDefault(defaultMaxAgeMs, now) {
+  if (defaultMaxAgeMs === void 0 || !Number.isFinite(defaultMaxAgeMs) || defaultMaxAgeMs < 0 || defaultMaxAgeMs === 0) {
+    return { minTimestampIso: void 0 };
+  }
+  return { minTimestampIso: new Date(now - defaultMaxAgeMs).toISOString() };
+}
+function filterMailboxMessagesByTimestamp(messages, minTimestampIso) {
+  if (minTimestampIso === void 0) return messages.slice();
+  return messages.filter((message) => message.timestamp >= minTimestampIso);
+}
 function optionalBoolean(object, key) {
   if (typeof object !== "object" || object === null) return void 0;
   const value = object[key];
@@ -17782,7 +17891,7 @@ function validateQuery(body) {
   if (incompleteOnly !== void 0) result.incompleteOnly = incompleteOnly;
   return result;
 }
-async function checkMailbox(mailbox, input) {
+async function checkMailbox(mailbox, input, minTimestampIso) {
   const limit = input.limit ?? 20;
   const markRead = input.markRead ?? true;
   const completed = input.completed ?? false;
@@ -17790,8 +17899,9 @@ async function checkMailbox(mailbox, input) {
   const batches = await Promise.all(
     targets.map((to) => mailbox.query({ to, unreadBy: input.agentId, limit }))
   );
+  const withinWindow = filterMailboxMessagesByTimestamp(batches.flat(), minTimestampIso);
   const seen = /* @__PURE__ */ new Set();
-  const messages = batches.flat().filter((message) => {
+  const messages = withinWindow.filter((message) => {
     if (seen.has(message.id) || message.from === input.agentId) return false;
     seen.add(message.id);
     return true;
@@ -19354,19 +19464,24 @@ var ProviderModelStatusTracker = class {
     let newState = s.state;
     let reason = "";
     const quotaExhausted = kind === "quota_exhausted" || isQuotaExhausted(kind, status, message);
+    const endpointUnreachable = isEndpointUnreachable(kind, status, message);
     if (quotaExhausted) {
       newState = "blocked";
       reason = "quota_exhausted";
       s.stateExpiresAt = now + this.cfg.quotaBlockDurationMs;
+    } else if (endpointUnreachable) {
+      newState = "blocked";
+      reason = "endpoint_unreachable";
+      s.stateExpiresAt = now + this.cfg.quotaBlockDurationMs;
     }
-    if (!quotaExhausted && s.state === "healthy") {
+    if (!quotaExhausted && !endpointUnreachable && s.state === "healthy") {
       if (s.consecutiveFailures >= this.cfg.degradedAfterFailures) {
         newState = "degraded";
         reason = `consecutive_failures_${s.consecutiveFailures}`;
         s.stateExpiresAt = now + this.cfg.degradedDurationMs;
       }
     }
-    if (!quotaExhausted && (s.state === "degraded" || s.state === "healthy")) {
+    if (!quotaExhausted && !endpointUnreachable && (s.state === "degraded" || s.state === "healthy")) {
       if (s.rateLimitHits >= this.cfg.blockAfterRateLimitHits) {
         newState = "blocked";
         reason = `rate_limit_threshold_${this.cfg.blockAfterRateLimitHits}`;
@@ -19696,13 +19811,20 @@ function unpairKey(key) {
   if (idx === -1) return [key, ""];
   return [key.slice(0, idx), key.slice(idx + 1)];
 }
-var QUOTA_EXHAUSTED_RE2 = /(?:insufficient|exhausted|depleted|exceeded|no|not enough)[-_\s]*(?:quota|credit|balance)|(?:quota|credit|balance)[-_\s]*(?:exhausted|depleted|exceeded|insufficient)|billing[_\s-]*(?:hard[_\s-]*)?limit|payment required|spending limit|plan limit/i;
+var QUOTA_EXHAUSTED_RE2 = /(?:insufficient|exhausted|depleted|exceeded|no|not enough)[-_\s]*(?:quota|credit|balance)|(?:quota|credit|balance)[-_\s]*(?:exhausted|depleted|exceeded|insufficient)|billing[_\s-]*(?:hard[_\s-]*)?limit|payment required|spending limit|plan limit|usage[-_\s]*limit[-_\s]*(?:reached|exceeded)|rate[-_\s]*limit[-_\s]*exceeded/i;
 function isQuotaExhausted(kind, status, message) {
   if (status === 402) return true;
   if (kind !== "rate_limit" && kind !== "quota_exhausted" && kind !== "invalid_request" && kind !== "auth")
     return false;
   return QUOTA_EXHAUSTED_RE2.test(message);
 }
+var ENDPOINT_UNREACHABLE_RE = /(?:upstream|origin|backend|endpoint)[-_\s]*(?:unreachable|refused|connect(?:ion)?[-_\s]*(?:refused|error|fail)|unavailable|down|timeout)|no[-_\s]*(?:healthy|valid)[-_\s]*upstream|cannot[-_\s]*connect|connection[-_\s]*(?:refused|reset|closed|timed?[-_\s]out)/i;
+function isEndpointUnreachable(kind, status, message) {
+  if (status !== 502 && status !== 503 && status !== 0) return false;
+  if (kind !== "server" && kind !== "network" && kind !== "overloaded" && kind !== "timeout")
+    return false;
+  return ENDPOINT_UNREACHABLE_RE.test(message);
+}
 function safeCount(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : 0;
 }
@@ -22911,6 +23033,8 @@ export {
   MAILBOX_HEALTH_DEFAULT_FROM,
   MAILBOX_HEALTH_DEFAULT_INTERVAL_MS,
   MAILBOX_HEALTH_DEFAULT_TIMEOUT_MS,
+  MAILBOX_HTTP_DEFAULT_MAX_AGE_MS,
+  MAILBOX_HTTP_MAX_AGE_CEILING_MS,
   MAILBOX_HTTP_MAX_BODY_BYTES,
   MAILBOX_HTTP_RATE_LIMIT_PER_MINUTE,
   MAILBOX_HTTP_RATE_LIMIT_WINDOW_MS,