@vforsh/argus 0.1.23 → 0.2.0

package/dist/argus.js

@@ -2130,7 +2130,7 @@ var {
 // package.json
 var package_default = {
   name: "@vforsh/argus",
-  version: "0.1.23",
+  version: "0.2.0",
   repository: {
     type: "git",
     url: "git+https://github.com/vforsh/argus.git",
@@ -2156,9 +2156,9 @@ var package_default = {
     access: "public"
   },
   dependencies: {
-    "@vforsh/argus-core": "^0.1.11",
-    "@vforsh/argus-plugin-api": "^0.1.4",
-    "@vforsh/argus-watcher": "^0.1.16",
+    "@vforsh/argus-core": "^0.2.0",
+    "@vforsh/argus-plugin-api": "^0.2.0",
+    "@vforsh/argus-watcher": "^0.2.0",
     commander: "14.0.2",
     esbuild: "0.25.12",
     prettier: "3.7.4"
@@ -2448,7 +2448,7 @@ var optionalPoint = (value, key) => {
 // ../argus-core/dist/protocol/http/auth.js
 var AUTH_STATE_METADATA_SCHEMA_VERSION = 1;
 // ../argus-core/dist/protocol/version.js
-var ARGUS_PROTOCOL_VERSION = 1;
+var ARGUS_PROTOCOL_VERSION = 2;
 // ../argus-core/dist/registry/registry.js
 import fs2 from "node:fs/promises";
 import path3 from "node:path";
@@ -6093,12 +6093,279 @@ var buildStatus = (ctx) => {
   };
 };
 
+// ../argus-watcher/dist/buffer/LogBuffer.js
+import { randomUUID } from "node:crypto";
+
+class LogEpochError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "LogEpochError";
+    this.code = code;
+  }
+}
+var EPOCH_PREFIX = "argus-log-epoch-v1.";
+
+class LogBuffer {
+  maxSize;
+  streamId = randomUUID();
+  events = [];
+  nextId = 1;
+  waiters = [];
+  epochWaiters = [];
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  add(event) {
+    const entry = {
+      ...event,
+      id: this.nextId++
+    };
+    this.events.push(entry);
+    this.trim();
+    this.flushWaiters();
+    this.flushEpochWaiters();
+    return entry;
+  }
+  listAfter(after, filters, limit) {
+    return this.listAfterPosition(after, filters, limit);
+  }
+  getCursor() {
+    return this.beginLogEpoch();
+  }
+  beginLogEpoch() {
+    return encodeEpoch({ v: 1, s: this.streamId, p: this.currentPosition() });
+  }
+  getEpoch() {
+    return this.beginLogEpoch();
+  }
+  getEpochAt(position) {
+    return encodeEpoch({ v: 1, s: this.streamId, p: position });
+  }
+  listAfterEpoch(epoch, filters, limit) {
+    const position = this.resolveEpoch(epoch);
+    const events = this.listAfterPosition(position, filters, limit);
+    return {
+      events,
+      nextCursor: events.length > 0 ? this.getEpochAt(events[events.length - 1]?.id ?? position) : epoch
+    };
+  }
+  waitForAfter(after, filters, limit, timeoutMs) {
+    const immediate = this.listAfter(after, filters, limit);
+    if (immediate.length > 0) {
+      return Promise.resolve(immediate);
+    }
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.waiters = this.waiters.filter((waiter) => waiter.timer !== timer);
+        resolve([]);
+      }, timeoutMs);
+      this.waiters.push({ after, filters, limit, resolve, timer });
+    });
+  }
+  async waitForAfterEpoch(epoch, filters, limit, timeoutMs) {
+    const position = this.resolveEpoch(epoch);
+    const immediate = this.listAfterPosition(position, filters, limit);
+    if (immediate.length > 0) {
+      return { events: immediate, nextCursor: this.getEpochAt(immediate[immediate.length - 1]?.id ?? position) };
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.epochWaiters = this.epochWaiters.filter((waiter) => waiter.timer !== timer);
+        resolve({ events: [], nextCursor: epoch });
+      }, timeoutMs);
+      this.epochWaiters.push({ position, filters, limit, resolve, reject, timer });
+    });
+  }
+  getStats() {
+    if (this.events.length === 0) {
+      return { size: this.maxSize, count: 0, minId: null, maxId: null };
+    }
+    return {
+      size: this.maxSize,
+      count: this.events.length,
+      minId: this.events[0]?.id ?? null,
+      maxId: this.events[this.events.length - 1]?.id ?? null
+    };
+  }
+  trim() {
+    if (this.maxSize <= 0) {
+      this.events = [];
+      return;
+    }
+    if (this.events.length <= this.maxSize) {
+      return;
+    }
+    this.events = this.events.slice(this.events.length - this.maxSize);
+  }
+  flushWaiters() {
+    if (this.waiters.length === 0) {
+      return;
+    }
+    const remaining = [];
+    for (const waiter of this.waiters) {
+      const events = this.listAfter(waiter.after, waiter.filters, waiter.limit);
+      if (events.length > 0) {
+        clearTimeout(waiter.timer);
+        waiter.resolve(events);
+        continue;
+      }
+      remaining.push(waiter);
+    }
+    this.waiters = remaining;
+  }
+  flushEpochWaiters() {
+    if (this.epochWaiters.length === 0) {
+      return;
+    }
+    const remaining = [];
+    for (const waiter of this.epochWaiters) {
+      try {
+        this.validatePosition(waiter.position);
+      } catch (error) {
+        clearTimeout(waiter.timer);
+        waiter.reject(error);
+        continue;
+      }
+      const events = this.listAfterPosition(waiter.position, waiter.filters, waiter.limit);
+      if (events.length > 0) {
+        clearTimeout(waiter.timer);
+        waiter.resolve({
+          events,
+          nextCursor: this.getEpochAt(events[events.length - 1]?.id ?? waiter.position)
+        });
+        continue;
+      }
+      remaining.push(waiter);
+    }
+    this.epochWaiters = remaining;
+  }
+  listAfterPosition(position, filters, limit) {
+    return this.events.filter((event) => event.id > position && matchesFilters(event, filters)).slice(0, limit);
+  }
+  resolveEpoch(epoch) {
+    const payload = decodeEpoch(epoch);
+    if (!payload) {
+      throw new LogEpochError("invalid", "Invalid log epoch. Capture a new epoch from the watcher.");
+    }
+    if (payload.s !== this.streamId) {
+      throw new LogEpochError("mismatch", "Log epoch belongs to a different watcher session. Capture a new epoch.");
+    }
+    if (payload.p > this.currentPosition()) {
+      throw new LogEpochError("future", "Log epoch points past the current log stream.");
+    }
+    this.validatePosition(payload.p);
+    return payload.p;
+  }
+  validatePosition(position) {
+    if (this.events.length > 0 && position < (this.events[0]?.id ?? position + 1) - 1) {
+      throw new LogEpochError("evicted", "Log epoch is stale because the ring buffer evicted entries. Capture a new epoch.");
+    }
+    if (this.maxSize === 0 && this.currentPosition() > position) {
+      throw new LogEpochError("evicted", "Log epoch is stale because the ring buffer evicted entries. Capture a new epoch.");
+    }
+  }
+  currentPosition() {
+    return this.nextId - 1;
+  }
+}
+var encodeEpoch = (payload) => `${EPOCH_PREFIX}${Buffer.from(JSON.stringify(payload)).toString("base64url")}`;
+var decodeEpoch = (epoch) => {
+  if (typeof epoch !== "string" || !epoch.startsWith(EPOCH_PREFIX)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(Buffer.from(epoch.slice(EPOCH_PREFIX.length), "base64url").toString("utf8"));
+    if (parsed.v !== 1 || typeof parsed.s !== "string" || !parsed.s || typeof parsed.p !== "number" || !Number.isSafeInteger(parsed.p) || parsed.p < 0) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+var matchesFilters = (event, filters) => {
+  if (filters.sinceTs && event.ts < filters.sinceTs) {
+    return false;
+  }
+  if (filters.levels && filters.levels.length > 0 && !filters.levels.includes(event.level)) {
+    return false;
+  }
+  if (filters.source && !event.source.toLowerCase().includes(filters.source.toLowerCase())) {
+    return false;
+  }
+  if (filters.match && filters.match.length > 0) {
+    for (const pattern of filters.match) {
+      if (pattern.test(event.text)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  return true;
+};
+
+// ../argus-watcher/dist/http/routes/logEpochQuery.js
+var parseLogPosition = (url) => {
+  const after = normalizeQueryValue2(url.searchParams.get("after") ?? null);
+  const sinceEpoch = normalizeQueryValue2(url.searchParams.get("sinceEpoch"));
+  if (after && sinceEpoch) {
+    return { error: "Use either after or sinceEpoch, not both." };
+  }
+  if (sinceEpoch) {
+    return { kind: "epoch", epoch: sinceEpoch };
+  }
+  if (after) {
+    return { kind: "epoch", epoch: after };
+  }
+  return { kind: "all" };
+};
+var respondLogEpochError = (res, error) => {
+  const status = error.code === "invalid" || error.code === "future" ? 400 : 409;
+  respondJson(res, {
+    ok: false,
+    error: {
+      message: error.message,
+      code: `log_epoch_${error.code}`
+    }
+  }, status);
+};
+var listLogsFromPosition = (buffer, position, filters, limit) => {
+  if (position.kind === "epoch") {
+    return buffer.listAfterEpoch(position.epoch, filters, limit);
+  }
+  return createQueryResult(buffer, position, buffer.listAfter(0, filters, limit));
+};
+var waitForLogsFromPosition = async (buffer, position, filters, limit, timeoutMs) => {
+  if (position.kind === "epoch") {
+    return buffer.waitForAfterEpoch(position.epoch, filters, limit, timeoutMs);
+  }
+  const events = await buffer.waitForAfter(0, filters, limit, timeoutMs);
+  return createQueryResult(buffer, position, events);
+};
+var createQueryResult = (buffer, position, events) => ({
+  events,
+  nextCursor: resolveNextCursor(buffer, position, events)
+});
+var resolveNextCursor = (buffer, position, events) => {
+  if (events.length > 0) {
+    return buffer.getEpochAt(events[events.length - 1]?.id ?? 0);
+  }
+  if (position.kind === "epoch") {
+    return position.epoch;
+  }
+  return buffer.getEpoch();
+};
+
 // ../argus-watcher/dist/http/routes/getLogs.js
 var route2 = defineJsonRoute({
   method: "GET",
   path: "/logs",
   handle: ({ res, url, ctx }) => {
-    const after = clampNumber(url.searchParams.get("after"), 0);
+    const position = parseLogPosition(url);
+    if ("error" in position) {
+      return respondLogEpochError(res, new LogEpochError("invalid", position.error));
+    }
     const limit = clampNumber(url.searchParams.get("limit"), 500, 1, 5000);
     const levels = parseLevels(url.searchParams.get("levels"));
     const match = url.searchParams.getAll("match");
@@ -6116,10 +6383,25 @@ var route2 = defineJsonRoute({
     if (compiledMatch.error) {
       return respondInvalidMatch(res, compiledMatch.error);
     }
-    emitRequest(ctx, res, "logs", { after, limit, levels, match: matchPatterns.patterns, matchCase, source, sinceTs });
-    const events = ctx.buffer.listAfter(after, { levels, match: compiledMatch.match, source, sinceTs }, limit);
-    const nextAfter = events.length > 0 ? events[events.length - 1]?.id ?? after : after;
-    return { ok: true, events, nextAfter };
+    emitRequest(ctx, res, "logs", {
+      after: position.kind === "epoch" && url.searchParams.has("after") ? position.epoch : undefined,
+      sinceEpoch: position.kind === "epoch" ? position.epoch : undefined,
+      limit,
+      levels,
+      match: matchPatterns.patterns,
+      matchCase,
+      source,
+      sinceTs
+    });
+    try {
+      const result = listLogsFromPosition(ctx.buffer, position, { levels, match: compiledMatch.match, source, sinceTs }, limit);
+      return { ok: true, ...result };
+    } catch (error) {
+      if (error instanceof LogEpochError) {
+        return respondLogEpochError(res, error);
+      }
+      throw error;
+    }
   }
 });
 
@@ -6130,12 +6412,22 @@ var route3 = defineJsonRoute({
   handle: ({ ctx }) => ({ ok: true, cursor: ctx.buffer.getCursor() })
 });
 
-// ../argus-watcher/dist/http/routes/getTail.js
+// ../argus-watcher/dist/http/routes/getLogEpoch.js
 var route4 = defineJsonRoute({
+  method: "GET",
+  path: "/logs/epoch",
+  handle: ({ ctx }) => ({ ok: true, epoch: ctx.buffer.beginLogEpoch() })
+});
+
+// ../argus-watcher/dist/http/routes/getTail.js
+var route5 = defineJsonRoute({
   method: "GET",
   path: "/tail",
   handle: async ({ res, url, ctx }) => {
-    const after = clampNumber(url.searchParams.get("after"), 0);
+    const position = parseLogPosition(url);
+    if ("error" in position) {
+      return respondLogEpochError(res, new LogEpochError("invalid", position.error));
+    }
     const limit = clampNumber(url.searchParams.get("limit"), 500, 1, 5000);
     const timeoutMs = clampNumber(url.searchParams.get("timeoutMs"), 25000, 1000, 120000);
     const levels = parseLevels(url.searchParams.get("levels"));
@@ -6153,10 +6445,25 @@ var route4 = defineJsonRoute({
     if (compiledMatch.error) {
       return respondInvalidMatch(res, compiledMatch.error);
     }
-    emitRequest(ctx, res, "tail", { after, limit, levels, match: matchPatterns.patterns, matchCase, source, timeoutMs });
-    const events = await ctx.buffer.waitForAfter(after, { levels, match: compiledMatch.match, source }, limit, timeoutMs);
-    const nextAfter = events.length > 0 ? events[events.length - 1]?.id ?? after : after;
-    return { ok: true, events, nextAfter, timedOut: events.length === 0 };
+    emitRequest(ctx, res, "tail", {
+      after: position.kind === "epoch" ? position.epoch : undefined,
+      sinceEpoch: position.kind === "epoch" ? position.epoch : undefined,
+      limit,
+      levels,
+      match: matchPatterns.patterns,
+      matchCase,
+      source,
+      timeoutMs
+    });
+    try {
+      const result = await waitForLogsFromPosition(ctx.buffer, position, { levels, match: compiledMatch.match, source }, limit, timeoutMs);
+      return { ok: true, ...result, timedOut: result.events.length === 0 };
+    } catch (error) {
+      if (error instanceof LogEpochError) {
+        return respondLogEpochError(res, error);
+      }
+      throw error;
+    }
   }
 });
 
@@ -6471,7 +6778,7 @@ var hasTruthyFlag = (searchParams, key) => {
 var optionalClampNumber = (value, min) => value == null ? undefined : clampNumber(value, undefined, min);
 
 // ../argus-watcher/dist/http/routes/getNet.js
-var route5 = defineJsonRoute({
+var route6 = defineJsonRoute({
   method: "GET",
   path: "/net",
   handle: ({ res, url, ctx }) => {
@@ -6490,7 +6797,7 @@ var route5 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getNetRequests.js
-var route6 = defineJsonRoute({
+var route7 = defineJsonRoute({
   method: "GET",
   path: "/net/requests",
   handle: ({ res, url, ctx }) => {
@@ -6544,7 +6851,7 @@ var parsePositiveInt2 = (value) => {
 };
 
 // ../argus-watcher/dist/http/routes/getNetRequest.js
-var route7 = defineJsonRoute({
+var route8 = defineJsonRoute({
   method: "GET",
   path: "/net/request",
   handle: ({ res, url, ctx }) => {
@@ -6628,7 +6935,7 @@ var createNetBodyError = (message, code) => {
 var capitalizePart = (part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`;
 
 // ../argus-watcher/dist/http/routes/getNetRequestBody.js
-var route8 = defineJsonRoute({
+var route9 = defineJsonRoute({
   method: "GET",
   path: "/net/request/body",
   handle: async ({ res, url, ctx }) => {
@@ -6698,7 +7005,7 @@ var resolveBodySessionId = (ctx, frameId, storedSessionId) => {
 };
 
 // ../argus-watcher/dist/http/routes/getNetTail.js
-var route9 = defineJsonRoute({
+var route10 = defineJsonRoute({
   method: "GET",
   path: "/net/tail",
   handle: async ({ res, url, ctx }) => {
@@ -6734,7 +7041,7 @@ var pollNetBuffer = async (buffer, after, filters, limit, timeoutMs) => {
 var delay2 = (timeoutMs) => new Promise((resolve) => setTimeout(resolve, timeoutMs));
 
 // ../argus-watcher/dist/http/routes/getNetWebSockets.js
-var route10 = defineJsonRoute({
+var route11 = defineJsonRoute({
   method: "GET",
   path: "/net/ws",
   handle: ({ res, url, ctx }) => {
@@ -6753,7 +7060,7 @@ var route10 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getNetWebSocketConnection.js
-var route11 = defineJsonRoute({
+var route12 = defineJsonRoute({
   method: "GET",
   path: "/net/ws/connection",
   handle: ({ res, url, ctx }) => {
@@ -6775,7 +7082,7 @@ var route11 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getNetSse.js
-var route12 = defineJsonRoute({
+var route13 = defineJsonRoute({
   method: "GET",
   path: "/net/sse",
   handle: ({ res, url, ctx }) => {
@@ -6794,7 +7101,7 @@ var route12 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postNetClear.js
-var route13 = defineJsonRoute({
+var route14 = defineJsonRoute({
   method: "POST",
   path: "/net/clear",
   handle: ({ res, ctx }) => {
@@ -7279,7 +7586,7 @@ var normalizeStorageEntries = (entries) => entries.filter((entry) => typeof entr
 }));
 
 // ../argus-watcher/dist/http/routes/getAuthCookies.js
-var route14 = defineJsonRoute({
+var route15 = defineJsonRoute({
   method: "GET",
   path: "/auth/cookies",
   handle: ({ res, url, ctx }) => {
@@ -7294,7 +7601,7 @@ var route14 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getAuthState.js
-var route15 = defineJsonRoute({
+var route16 = defineJsonRoute({
   method: "GET",
   path: "/auth/state",
   handle: ({ res, url, ctx }) => {
@@ -7484,7 +7791,7 @@ var applyAuthStateToSession = async (input) => hydrateAuthState({
 });
 
 // ../argus-watcher/dist/http/routes/postAuthStateLoad.js
-var route16 = defineJsonRoute({
+var route17 = defineJsonRoute({
   method: "POST",
   path: "/auth/state/load",
   parseBody: true,
@@ -7603,12 +7910,12 @@ var expandRemoteObjectViaGetProperties = async (record2, cdp) => {
 };
 
 // ../argus-watcher/dist/cdp/scenarioBridge.js
-import { randomUUID } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
 var SCENARIO_ACTION_TIMEOUT_MS = 30000;
 var DEFAULT_LOG_LIMIT = 500;
 var MAX_LOG_LIMIT = 5000;
 var installScenarioBridge = async (session, expression, args, services, timeoutMs) => {
-  const token = randomUUID();
+  const token = randomUUID2();
   const suffix = token.replaceAll("-", "");
   const bindingName = `__argusScenarioSend_${suffix}`;
   const responseName = `__argusScenarioReceive_${suffix}`;
@@ -7728,17 +8035,11 @@ var parseCheckpointName = (value) => {
 var readScenarioLogs = (buffer, value) => {
   const payload = requireRecord(value, "logs.read payload");
   const cursor = payload.cursor;
-  if (typeof cursor !== "number" || !Number.isInteger(cursor) || cursor < 0) {
-    throw new Error("log cursor must be a non-negative integer");
+  if (typeof cursor !== "string" || !cursor.trim()) {
+    throw new Error("log cursor must be a non-empty opaque cursor");
   }
   const { filters, limit } = parseLogOptions(payload.options);
-  const endCursor = buffer.getCursor();
-  const events = buffer.listAfter(cursor, filters, limit);
-  let nextCursor = endCursor;
-  if (events.length === limit) {
-    nextCursor = events[events.length - 1]?.id ?? cursor;
-  }
-  return { events, nextCursor };
+  return buffer.listAfterEpoch(cursor, filters, limit);
 };
 var parseLogOptions = (value) => {
   if (value == null)
@@ -8021,7 +8322,7 @@ var shouldMaterializeByValue = (record2) => {
 };
 
 // ../argus-watcher/dist/http/routes/postEval.js
-var route17 = defineJsonRoute({
+var route18 = defineJsonRoute({
   method: "POST",
   path: "/eval",
   parseBody: true,
@@ -8060,7 +8361,7 @@ var normalizeEvalArgs = (args) => {
 };
 
 // ../argus-watcher/dist/http/routes/postTraceStart.js
-var route18 = defineJsonRoute({
+var route19 = defineJsonRoute({
   method: "POST",
   path: "/trace/start",
   parseBody: true,
@@ -8069,7 +8370,7 @@ var route18 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postTraceStop.js
-var route19 = defineJsonRoute({
+var route20 = defineJsonRoute({
   method: "POST",
   path: "/trace/stop",
   parseBody: true,
@@ -8165,7 +8466,7 @@ var validateClip = (clip) => {
 };
 
 // ../argus-watcher/dist/http/routes/postScreenshot.js
-var route20 = defineJsonRoute({
+var route21 = defineJsonRoute({
   method: "POST",
   path: "/screenshot",
   parseBody: true,
@@ -8677,7 +8978,7 @@ var countNodes = (nodes) => {
 };
 
 // ../argus-watcher/dist/http/routes/postSnapshot.js
-var route21 = defineJsonRoute({
+var route22 = defineJsonRoute({
   method: "POST",
   path: "/snapshot",
   parseBody: true,
@@ -8854,7 +9155,7 @@ var locateRoutes = [
 ];
 
 // ../argus-watcher/dist/http/routes/postCodeList.js
-var route22 = defineJsonRoute({
+var route23 = defineJsonRoute({
   method: "POST",
   path: "/code/list",
   parseBody: true,
@@ -8869,7 +9170,7 @@ var route22 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postCodeRead.js
-var route23 = defineJsonRoute({
+var route24 = defineJsonRoute({
   method: "POST",
   path: "/code/read",
   parseBody: true,
@@ -8894,7 +9195,7 @@ var route23 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postCodeGrep.js
-var route24 = defineJsonRoute({
+var route25 = defineJsonRoute({
   method: "POST",
   path: "/code/grep",
   parseBody: true,
@@ -8915,7 +9216,7 @@ var route24 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postCodeEdit.js
-var route25 = defineJsonRoute({
+var route26 = defineJsonRoute({
   method: "POST",
   path: "/code/edit",
   parseBody: true,
@@ -9272,7 +9573,7 @@ var fillResolvedNodes = async (session, handles, value) => {
   return handles.length;
 };
 // ../argus-watcher/dist/http/routes/postDomTree.js
-var route26 = defineJsonRoute({
+var route27 = defineJsonRoute({
   method: "POST",
   path: "/dom/tree",
   parseBody: true,
@@ -9295,7 +9596,7 @@ var route26 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDomInfo.js
-var route27 = defineJsonRoute({
+var route28 = defineJsonRoute({
   method: "POST",
   path: "/dom/info",
   parseBody: true,
@@ -9580,7 +9881,7 @@ var defineDomTargetRoute = (input) => defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDomHover.js
-var route28 = defineDomTargetRoute({
+var route29 = defineDomTargetRoute({
   path: "/dom/hover",
   endpoint: "dom/hover",
   action: "hover",
@@ -9591,7 +9892,7 @@ var route28 = defineDomTargetRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDomClick.js
-var route29 = defineJsonRoute({
+var route30 = defineJsonRoute({
   method: "POST",
   path: "/dom/click",
   bodySchema: domClickRequestSchema,
@@ -9639,7 +9940,7 @@ var route29 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDomDrag.js
-var route30 = defineJsonRoute({
+var route31 = defineJsonRoute({
   method: "POST",
   path: "/dom/drag",
   bodySchema: domDragRequestSchema,
@@ -9856,7 +10157,7 @@ var dispatchKeydown = async (session, options) => {
 };
 
 // ../argus-watcher/dist/http/routes/postDomKeydown.js
-var route31 = defineJsonRoute({
+var route32 = defineJsonRoute({
   method: "POST",
   path: "/dom/keydown",
   parseBody: true,
@@ -9906,7 +10207,7 @@ var route31 = defineJsonRoute({
 
 // ../argus-watcher/dist/http/routes/postDomAdd.js
 var validPositions = ["beforebegin", "afterbegin", "beforeend", "afterend"];
-var route32 = defineJsonRoute({
+var route33 = defineJsonRoute({
   method: "POST",
   path: "/dom/add",
   parseBody: true,
@@ -9995,7 +10296,7 @@ var selectDomAddNodeIds = (allNodeIds, options) => {
 };
 
 // ../argus-watcher/dist/http/routes/postDomRemove.js
-var route33 = defineJsonRoute({
+var route34 = defineJsonRoute({
   method: "POST",
   path: "/dom/remove",
   parseBody: true,
@@ -10017,7 +10318,7 @@ var route33 = defineJsonRoute({
 
 // ../argus-watcher/dist/http/routes/postDomModify.js
 var validTypes = ["attr", "class", "style", "text", "html"];
-var route34 = defineJsonRoute({
+var route35 = defineJsonRoute({
   method: "POST",
   path: "/dom/modify",
   parseBody: true,
@@ -10048,7 +10349,7 @@ var route34 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDomSetFile.js
-var route35 = defineJsonRoute({
+var route36 = defineJsonRoute({
   method: "POST",
   path: "/dom/set-file",
   parseBody: true,
@@ -10086,7 +10387,7 @@ var route35 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDomFocus.js
-var route36 = defineDomTargetRoute({
+var route37 = defineDomTargetRoute({
   path: "/dom/focus",
   endpoint: "dom/focus",
   action: "focus",
@@ -10097,7 +10398,7 @@ var route36 = defineDomTargetRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDomFill.js
-var route37 = defineDomTargetRoute({
+var route38 = defineDomTargetRoute({
   path: "/dom/fill",
   endpoint: "dom/fill",
   action: "fill",
@@ -10118,7 +10419,7 @@ var route37 = defineDomTargetRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDomScroll.js
-var route38 = defineJsonRoute({
+var route39 = defineJsonRoute({
   method: "POST",
   path: "/dom/scroll",
   parseBody: true,
@@ -10177,7 +10478,7 @@ var getViewportSize = async (session) => {
 };
 
 // ../argus-watcher/dist/http/routes/postDomScrollTo.js
-var route39 = defineJsonRoute({
+var route40 = defineJsonRoute({
   method: "POST",
   path: "/dom/scroll-to",
   parseBody: true,
@@ -10224,7 +10525,7 @@ var route39 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getEmulation.js
-var route40 = defineJsonRoute({
+var route41 = defineJsonRoute({
   method: "GET",
   path: "/emulation",
   endpoint: "emulation",
@@ -10233,7 +10534,7 @@ var route40 = defineJsonRoute({
 
 // ../argus-watcher/dist/http/routes/postEmulation.js
 var validActions = ["set", "clear"];
-var route41 = defineJsonRoute({
+var route42 = defineJsonRoute({
   method: "POST",
   path: "/emulation",
   parseBody: true,
@@ -10292,7 +10593,7 @@ function validateEmulationRequest(payload) {
 }
 
 // ../argus-watcher/dist/http/routes/getThrottle.js
-var route42 = defineJsonRoute({
+var route43 = defineJsonRoute({
   method: "GET",
   path: "/throttle",
   endpoint: "throttle",
@@ -10301,7 +10602,7 @@ var route42 = defineJsonRoute({
 
 // ../argus-watcher/dist/http/routes/postThrottle.js
 var validActions2 = ["set", "clear"];
-var route43 = defineJsonRoute({
+var route44 = defineJsonRoute({
   method: "POST",
   path: "/throttle",
   parseBody: true,
@@ -10329,7 +10630,7 @@ var route43 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getDialog.js
-var route44 = defineJsonRoute({
+var route45 = defineJsonRoute({
   method: "GET",
   path: "/dialog",
   endpoint: "dialog/status",
@@ -10337,7 +10638,7 @@ var route44 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDialog.js
-var route45 = defineJsonRoute({
+var route46 = defineJsonRoute({
   method: "POST",
   path: "/dialog",
   parseBody: true,
@@ -10376,7 +10677,7 @@ var route45 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postVisibility.js
-var route46 = defineJsonRoute({
+var route47 = defineJsonRoute({
   method: "POST",
   path: "/visibility",
   parseBody: true,
@@ -10493,7 +10794,7 @@ function validateStoragePayload(payload) {
 }
 
 // ../argus-watcher/dist/http/routes/postReload.js
-var route47 = defineJsonRoute({
+var route48 = defineJsonRoute({
   method: "POST",
   path: "/reload",
   parseBody: true,
@@ -10507,7 +10808,7 @@ var route47 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postShutdown.js
-var route48 = defineJsonRoute({
+var route49 = defineJsonRoute({
   method: "POST",
   path: "/shutdown",
   endpoint: "shutdown",
@@ -10522,7 +10823,7 @@ var route48 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getExtensionTabs.js
-var route49 = defineJsonRoute({
+var route50 = defineJsonRoute({
   method: "GET",
   path: "/tabs",
   extensionOnly: true,
@@ -10543,7 +10844,7 @@ var route49 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getExtensionDiagnostics.js
-var route50 = defineJsonRoute({
+var route51 = defineJsonRoute({
   method: "GET",
   path: "/extension/diagnostics",
   extensionOnly: true,
@@ -10557,7 +10858,7 @@ var route50 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/getTargets.js
-var route51 = defineJsonRoute({
+var route52 = defineJsonRoute({
   method: "GET",
   path: "/targets",
   extensionOnly: true,
@@ -10572,7 +10873,7 @@ var route51 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postAttach.js
-var route52 = defineJsonRoute({
+var route53 = defineJsonRoute({
   method: "POST",
   path: "/attach",
   parseBody: true,
@@ -10595,7 +10896,7 @@ var route52 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/http/routes/postDetach.js
-var route53 = defineJsonRoute({
+var route54 = defineJsonRoute({
   method: "POST",
   path: "/detach",
   parseBody: true,
@@ -10621,8 +10922,8 @@ var route53 = defineJsonRoute({
 var watcherRoutes = [
   route,
   route3,
-  route2,
   route4,
+  route2,
   route5,
   route6,
   route7,
@@ -10632,22 +10933,22 @@ var watcherRoutes = [
   route11,
   route12,
   route13,
-  ...netMockRoutes,
   route14,
+  ...netMockRoutes,
+  route15,
   cookieGetRoute,
   cookieSetRoute,
   cookieDeleteRoute,
   cookieClearRoute,
-  route15,
   route16,
   route17,
   route18,
   route19,
-  ...recordRoutes,
   route20,
+  ...recordRoutes,
   route21,
-  ...locateRoutes,
   route22,
+  ...locateRoutes,
   route23,
   route24,
   route25,
@@ -10672,18 +10973,19 @@ var watcherRoutes = [
   route44,
   route45,
   route46,
-  ...storageRoutes,
   route47,
+  ...storageRoutes,
   route48,
   route49,
   route50,
   route51,
   route52,
-  route53
+  route53,
+  route54
 ];
 
 // ../argus-watcher/dist/http/router.js
-var routes = new Map(watcherRoutes.map((route54) => [`${route54.method} ${route54.path}`, route54]));
+var routes = new Map(watcherRoutes.map((route55) => [`${route55.method} ${route55.path}`, route55]));
 var dispatch = (req, res, url, ctx) => {
   const entry = routes.get(`${req.method} ${url.pathname}`);
   if (!entry || entry.extensionOnly && !ctx.sourceHandle) {
@@ -11347,100 +11649,6 @@ var formatWatcherError = (error) => {
 import os3 from "node:os";
 import path7 from "node:path";
 
-// ../argus-watcher/dist/buffer/LogBuffer.js
-class LogBuffer {
-  maxSize;
-  events = [];
-  nextId = 1;
-  waiters = [];
-  constructor(maxSize) {
-    this.maxSize = maxSize;
-  }
-  add(event) {
-    const entry = {
-      ...event,
-      id: this.nextId++
-    };
-    this.events.push(entry);
-    this.trim();
-    this.flushWaiters();
-    return entry;
-  }
-  listAfter(after, filters, limit) {
-    const filtered = this.events.filter((event) => event.id > after && matchesFilters(event, filters));
-    return filtered.slice(0, limit);
-  }
-  getCursor() {
-    return this.nextId - 1;
-  }
-  waitForAfter(after, filters, limit, timeoutMs) {
-    const immediate = this.listAfter(after, filters, limit);
-    if (immediate.length > 0) {
-      return Promise.resolve(immediate);
-    }
-    return new Promise((resolve) => {
-      const timer = setTimeout(() => {
-        this.waiters = this.waiters.filter((waiter) => waiter.timer !== timer);
-        resolve([]);
-      }, timeoutMs);
-      this.waiters.push({ after, filters, limit, resolve, timer });
-    });
-  }
-  getStats() {
-    if (this.events.length === 0) {
-      return { size: this.maxSize, count: 0, minId: null, maxId: null };
-    }
-    return {
-      size: this.maxSize,
-      count: this.events.length,
-      minId: this.events[0]?.id ?? null,
-      maxId: this.events[this.events.length - 1]?.id ?? null
-    };
-  }
-  trim() {
-    if (this.events.length <= this.maxSize) {
-      return;
-    }
-    this.events = this.events.slice(this.events.length - this.maxSize);
-  }
-  flushWaiters() {
-    if (this.waiters.length === 0) {
-      return;
-    }
-    const remaining = [];
-    for (const waiter of this.waiters) {
-      const events = this.listAfter(waiter.after, waiter.filters, waiter.limit);
-      if (events.length > 0) {
-        clearTimeout(waiter.timer);
-        waiter.resolve(events);
-        continue;
-      }
-      remaining.push(waiter);
-    }
-    this.waiters = remaining;
-  }
-}
-var matchesFilters = (event, filters) => {
-  if (filters.sinceTs && event.ts < filters.sinceTs) {
-    return false;
-  }
-  if (filters.levels && filters.levels.length > 0 && !filters.levels.includes(event.level)) {
-    return false;
-  }
-  if (filters.source && !event.source.toLowerCase().includes(filters.source.toLowerCase())) {
-    return false;
-  }
-  if (filters.match && filters.match.length > 0) {
-    for (const pattern of filters.match) {
-      if (pattern.test(event.text)) {
-        return true;
-      }
-    }
-    return false;
-  }
-  return true;
-};
-
 // ../argus-watcher/dist/buffer/NetBuffer.js
 class NetBuffer {
   maxSize;
@@ -20030,9 +20238,11 @@ var previewLogEvent = (event) => ({
 
 // dist/watchers/queryParams.js
 var appendAfterLimitParams = (params, options) => {
-  const after = parseNumber(options.after);
-  if (after != null) {
-    params.set("after", String(after));
+  if (options.after?.trim()) {
+    params.set("after", options.after.trim());
+  }
+  if (options.sinceEpoch?.trim()) {
+    params.set("sinceEpoch", options.sinceEpoch.trim());
   }
   const limit = parseNumber(options.limit);
   if (limit != null) {
@@ -20171,7 +20381,11 @@ var appendRepeatedParams = (params, key, values) => {
 // dist/commands/logs.js
 var runLogCursor = defineWatcherCommand({
   build: () => ({ path: "/logs/cursor", timeoutMs: 5000 }),
-  formatHuman: (response, { output }) => output.writeHuman(String(response.cursor))
+  formatHuman: (response, { output }) => output.writeHuman(response.cursor)
+});
+var runLogEpoch = defineWatcherCommand({
+  build: () => ({ path: "/logs/epoch", timeoutMs: 5000 }),
+  formatHuman: (response, { output }) => output.writeHuman(response.epoch)
 });
 var runLogs = defineWatcherCommand({
   isJson: (options) => options.jsonFull === true,
@@ -20214,7 +20428,14 @@ var runTail = async (id, options) => {
   if (!resolved)
     return;
   const { watcher } = resolved;
-  let after = parseNumber(options.after) ?? 0;
+  const afterEpoch = options.after?.trim() || undefined;
+  const sinceEpoch = options.sinceEpoch?.trim() || undefined;
+  if (afterEpoch && sinceEpoch) {
+    output.writeWarn("Use either --after or --since-epoch, not both.");
+    process.exitCode = 2;
+    return;
+  }
+  let position = afterEpoch ?? sinceEpoch;
   const timeoutMs = parseNumber(options.timeout) ?? 25000;
   const limit = parseNumber(options.limit);
   let running = true;
@@ -20225,7 +20446,9 @@ var runTail = async (id, options) => {
   process.on("SIGTERM", stop);
   while (running) {
     const params = new URLSearchParams;
-    params.set("after", String(after));
+    if (position) {
+      params.set(sinceEpoch ? "sinceEpoch" : "after", position);
+    }
     params.set("timeoutMs", String(timeoutMs));
     if (limit != null) {
       params.set("limit", String(limit));
@@ -20245,25 +20468,23 @@ var runTail = async (id, options) => {
       process.exitCode = 1;
       return;
     }
-    if (response.events.length > 0) {
-      for (const event of response.events) {
-        if (options.jsonFull) {
-          output.writeJsonLine({ watcher: watcher.id, event });
-          continue;
-        }
-        if (options.json) {
-          const previewEvent = previewLogEvent(event);
-          output.writeJsonLine({ watcher: watcher.id, event: previewEvent });
-          continue;
-        }
-        output.writeHuman(formatLogEvent(event, {
-          includeTimestamps: watcher.includeTimestamps
-        }));
-      }
+    for (const event of response.events) {
+      writeTailEvent(event, watcher, options, output);
     }
-    after = response.nextAfter;
+    position = response.nextCursor;
   }
 };
+var writeTailEvent = (event, watcher, options, output) => {
+  if (options.jsonFull) {
+    output.writeJsonLine({ watcher: watcher.id, event });
+    return;
+  }
+  if (options.json) {
+    output.writeJsonLine({ watcher: watcher.id, event: previewLogEvent(event) });
+    return;
+  }
+  output.writeHuman(formatLogEvent(event, { includeTimestamps: watcher.includeTimestamps }));
+};
 
 // dist/cli/register/logsCommands.js
 var sharedFilterOptions = [
@@ -20290,7 +20511,8 @@ var logsCommands = [
     options: [
       ...sharedFilterOptions,
       { flags: "--since <duration>", description: "Filter by time window (e.g. 10m, 2h, 30s)" },
-      { flags: "--after <id>", description: "Only return events after this id" },
+      { flags: "--after <cursor>", description: "Only return events after this opaque cursor" },
+      { flags: "--since-epoch <epoch>", description: "Only return events after this opaque epoch" },
       { flags: "--limit <count>", description: "Maximum number of events" },
       { flags: "--json", description: "Output bounded JSON preview for automation" },
       { flags: "--json-full", description: "Output full JSON (can be very large)" }
@@ -20302,6 +20524,16 @@ var logsCommands = [
       await runLogs(id, options);
     },
     subcommands: [
+      {
+        name: "epoch",
+        description: "Return an opaque watcher-session log epoch without downloading events",
+        arguments: [{ flags: "[id]", description: "Watcher id to query" }],
+        options: [{ flags: "--json", description: "Output one JSON document for automation" }],
+        examples: ["argus logs epoch app", "argus logs epoch app --json"],
+        action: async (id, options, command) => {
+          await runLogEpoch(id, command.optsWithGlobals?.() ?? options);
+        }
+      },
       {
         name: "cursor",
         description: "Return the current log cursor without downloading events",
@@ -20318,7 +20550,8 @@ var logsCommands = [
         arguments: [{ flags: "[id]", description: "Watcher id to follow" }],
         options: [
           ...sharedFilterOptions,
-          { flags: "--after <id>", description: "Start after this event id" },
+          { flags: "--after <cursor>", description: "Start after this opaque cursor" },
+          { flags: "--since-epoch <epoch>", description: "Start after this opaque epoch" },
           { flags: "--limit <count>", description: "Maximum number of events per poll" },
           { flags: "--timeout <ms>", description: "Long-poll timeout in milliseconds" },
           { flags: "--json", description: "Output bounded newline-delimited JSON events" },