Update function diagnostics surfaces

Author: MajorTal

README.md

@@ -412,7 +412,7 @@ The full MCP surface — every tool is a thin shim over an SDK call.
 |------|-------------|
 | `deploy_function` | Deploy a Node 22 serverless function. Cron-schedulable. |
 | `invoke_function` | Invoke a deployed function over the direct API-key-protected test path. |
-| `get_function_logs` | Recent logs (CloudWatch). |
+| `get_function_logs` | Recent logs (CloudWatch), filterable by `since` and routed `request_id`. |
 | `update_function` | Update schedule / timeout / memory without redeploying code. |
 | `list_functions` / `delete_function` | List / remove functions. |
 | `set_secret` / `list_secrets` / `delete_secret` | Manage `process.env` secrets injected into all functions. Values are write-only; list returns keys and timestamps only. |

README.zh-CN.md

@@ -24,7 +24,7 @@ npx run402-mcp
 | `deploy_site` | 部署静态 HTML/CSS/JS 站点 |
 | `deploy_function` | 部署 Node 22 Serverless 函数 |
 | `invoke_function` | 调用已部署的函数 |
-| `get_function_logs` | 获取函数日志 |
+| `get_function_logs` | 获取函数日志，可按 `since` 和 routed `request_id` 过滤 |
 | `set_secret` | 设置函数环境变量 |
 
 ## 定价

SKILL.md

@@ -44,6 +44,7 @@ Important fields:
 - `safe_to_retry` — repeating the same request should not duplicate or corrupt a mutation
 - `mutation_state` — gateway-known mutation progress: `none`, `not_started`, `committed`, `rolled_back`, `partial`, or `unknown`
 - `trace_id` — include this when reporting a Run402 issue
+- `request_id` — routed/function failure handle; use `get_function_logs` with `request_id` for function diagnostics. This is distinct from gateway `trace_id`.
 - `details` — structured route-specific context
 - `next_actions` — advisory suggestions such as `authenticate`, `submit_payment`, `renew_tier`, `check_usage`, `retry`, `resume_deploy`, `edit_request`, or `edit_migration`; render or follow them only after validating the action is safe
 
@@ -299,7 +300,7 @@ No `route_scopes` means no CI route-declaration authority. With route scopes, CI
 
 - **`deploy_function`** — deploy a Node 22 serverless function. Cron-schedulable via `schedule`. Pass `deps` as npm specs (bare names → latest at deploy time, pinned `lodash@4.17.21` or ranges `date-fns@^3.0.0` honored verbatim, max 30 entries / 200 chars each, native binaries rejected). Response surfaces `runtime_version`, `deps_resolved`, `warnings`.
 - **`invoke_function`** — invoke for testing over the direct `/functions/v1/:name` API-key-protected path.
-- **`get_function_logs`** — recent logs (CloudWatch). Use `since` for incremental polling.
+- **`get_function_logs`** — recent logs (CloudWatch). Use `since` for incremental polling and `request_id` (`req_...`) to follow a routed browser failure from `X-Run402-Request-Id` / JSON `request_id`.
 - **`update_function`** — change schedule / timeout / memory without redeploying code.
 - **`list_functions`** / **`delete_function`** — list / remove.
 - **`set_secret`** / **`list_secrets`** / **`delete_secret`** — `process.env` secrets injected into every function. Values are write-only; `list_secrets` returns keys and timestamps only. Deploy specs use `secrets.require[]` as a dependency gate, not as a value carrier or per-function allowlist.

cli-argv.test.mjs

@@ -170,6 +170,97 @@ describe("--flag=value", () => {
     assert.ok(call, `expected logs request, got ${JSON.stringify(calls)}`);
     assert.match(call.url, /tail=10/);
   });
+
+  it("functions logs accepts equals-form request-id filters", async () => {
+    const { run } = await import("./cli/lib/functions.mjs");
+    captureStart();
+    await run("logs", ["prj_test123", "hello", "--request-id=req_abc123"]);
+    captureStop();
+
+    const call = calls.find((c) => /\/logs\?/.test(c.path));
+    assert.ok(call, `expected logs request, got ${JSON.stringify(calls)}`);
+    assert.equal(new URL(call.url).searchParams.get("request_id"), "req_abc123");
+  });
+});
+
+describe("function log filter validation", () => {
+  it("functions logs rejects invalid --since before network", async () => {
+    const { run } = await import("./cli/lib/functions.mjs");
+    const err = await expectExit1(() =>
+      run("logs", ["prj_test123", "hello", "--since", "not-a-date"]));
+
+    assert.equal(err.code, "BAD_USAGE");
+    assert.equal(err.details.flag, "--since");
+    assert.equal(calls.length, 0, "bad --since must not hit the network");
+  });
+
+  it("functions logs rejects invalid --request-id before network", async () => {
+    const { run } = await import("./cli/lib/functions.mjs");
+    const err = await expectExit1(() =>
+      run("logs", ["prj_test123", "hello", "--request-id", "trace_abc"]));
+
+    assert.equal(err.code, "BAD_USAGE");
+    assert.equal(err.details.flag, "--request-id");
+    assert.equal(calls.length, 0, "bad --request-id must not hit the network");
+  });
+
+  it("functions logs follow dedupes same-millisecond entries by event identity", async () => {
+    const { run } = await import("./cli/lib/functions.mjs");
+    const prevFetch = globalThis.fetch;
+    const prevSetTimeout = globalThis.setTimeout;
+    const timestamp = "2026-05-01T00:00:00.000Z";
+    let logFetches = 0;
+    let sleeps = 0;
+    globalThis.fetch = (input, init) => {
+      const info = requestInfo(input, init);
+      calls.push(info);
+      const pathNoQuery = info.path.split("?")[0];
+      if (/\/functions\/hello\/logs$/.test(pathNoQuery) && info.method === "GET") {
+        logFetches += 1;
+        const logs = logFetches === 1
+          ? [
+              { timestamp, message: "first", event_id: "evt-1", log_stream_name: "stream-a" },
+              { timestamp, message: "second", event_id: "evt-2", log_stream_name: "stream-a" },
+            ]
+          : [
+              { timestamp, message: "first", event_id: "evt-1", log_stream_name: "stream-a" },
+              { timestamp, message: "second", event_id: "evt-2", log_stream_name: "stream-a" },
+              { timestamp, message: "third", event_id: "evt-3", log_stream_name: "stream-a" },
+            ];
+        return Promise.resolve(json({ logs }));
+      }
+      return mockFetch(input, init);
+    };
+    globalThis.setTimeout = (fn, _ms, ...args) => {
+      sleeps += 1;
+      queueMicrotask(() => {
+        if (sleeps >= 2) process.emit("SIGINT");
+        fn(...args);
+      });
+      return 0;
+    };
+
+    try {
+      captureStart();
+      await run("logs", ["prj_test123", "hello", "--follow"]);
+      captureStop();
+    } finally {
+      captureStop();
+      globalThis.fetch = prevFetch;
+      globalThis.setTimeout = prevSetTimeout;
+    }
+
+    const output = stdout.join("\n");
+    assert.equal((output.match(/first/g) || []).length, 1);
+    assert.equal((output.match(/second/g) || []).length, 1);
+    assert.equal((output.match(/third/g) || []).length, 1);
+    const logCalls = calls.filter((c) => /\/logs\?/.test(c.path));
+    assert.ok(logCalls.length >= 2, `expected at least two log polls, got ${JSON.stringify(logCalls)}`);
+    assert.equal(
+      new URL(logCalls[1].url).searchParams.get("since"),
+      String(new Date(timestamp).getTime()),
+    );
+  });
 });
 
 describe("numeric flag validation", () => {

cli/README.md

@@ -114,7 +114,7 @@ run402 functions deploy <id> my-fn --file fn.ts \
   --timeout 30 --memory 256 \
   --schedule "*/15 * * * *" \
   --deps "stripe,zod@^3"
-run402 functions logs <id> my-fn --tail 100 --follow
+run402 functions logs <id> my-fn --tail 100 --request-id req_abc123 --follow
 run402 functions invoke <id> my-fn --body '{"hello":"world"}'
 ```
 

cli/lib/functions.mjs

@@ -4,6 +4,8 @@ import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag, validateRegularFile } from "./argparse.mjs";
 
+const FUNCTION_LOG_REQUEST_ID_RE = /^req_[A-Za-z0-9_-]{4,128}$/;
+
 const HELP = `run402 functions — Manage serverless functions
 
 Usage:
@@ -14,7 +16,7 @@ Subcommands:
                                        Deploy a function to a project
   invoke <id> <name> [--method <M>] [--body <json>]
                                        Invoke a deployed function
-  logs   <id> <name> [--tail <n>] [--since <ts>] [--follow]
+  logs   <id> <name> [--tail <n>] [--since <ts>] [--request-id <req_...>] [--follow]
                                        Get function logs
   update <id> <name> [--schedule <cron>] [--schedule-remove] [--timeout <s>] [--memory <mb>]
                                        Update function schedule or config without re-deploying
@@ -28,6 +30,7 @@ Examples:
   run402 functions invoke prj_abc123 stripe-webhook --body '{"event":"test"}'
   run402 functions logs prj_abc123 stripe-webhook --tail 100
   run402 functions logs prj_abc123 stripe-webhook --since 2026-03-29T14:00:00Z
+  run402 functions logs prj_abc123 stripe-webhook --request-id req_abc123
   run402 functions logs prj_abc123 stripe-webhook --follow
   run402 functions update prj_abc123 send-reminders --schedule '0 */4 * * *'
   run402 functions update prj_abc123 send-reminders --schedule-remove
@@ -112,11 +115,13 @@ Arguments:
 Options:
   --tail <n>          Number of most-recent entries (default 50)
   --since <ts>        ISO timestamp or epoch ms; only entries after this
+  --request-id <id>   Only entries correlated to this req_... request id
   --follow            Poll every 3s and stream new entries (Ctrl-C to stop)
 
 Examples:
   run402 functions logs prj_abc123 stripe-webhook --tail 100
   run402 functions logs prj_abc123 stripe-webhook --since 2026-03-29T14:00:00Z
+  run402 functions logs prj_abc123 stripe-webhook --request-id req_abc123
   run402 functions logs prj_abc123 stripe-webhook --follow
 `,
   update: `run402 functions update — Update function config without re-deploying
@@ -227,14 +232,16 @@ async function invoke(projectId, name, args) {
 }
 
 async function logs(projectId, name, args) {
-  assertRequiredProjectAndName(projectId, name, "run402 functions logs <project_id> <name> [--tail <n>]");
-  assertKnownFlags(args, ["--tail", "--since", "--follow", "--help", "-h"], ["--tail", "--since"]);
+  assertRequiredProjectAndName(projectId, name, "run402 functions logs <project_id> <name> [--tail <n>] [--request-id <req_...>]");
+  assertKnownFlags(args, ["--tail", "--since", "--request-id", "--follow", "--help", "-h"], ["--tail", "--since", "--request-id"]);
   let tail = 50;
   let since = undefined;
+  let requestId = undefined;
   let follow = false;
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--tail") tail = parseIntegerFlag("--tail", args[++i], { min: 1 });
     if (args[i] === "--since" && args[i + 1]) since = args[++i];
+    if (args[i] === "--request-id" && args[i + 1]) requestId = args[++i];
     if (args[i] === "--follow") follow = true;
   }
 
@@ -254,12 +261,20 @@ async function logs(projectId, name, args) {
     }
     sinceIso = new Date(ms).toISOString();
   }
+  if (requestId !== undefined && !FUNCTION_LOG_REQUEST_ID_RE.test(requestId)) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Invalid --request-id value: ${requestId}`,
+      details: { flag: "--request-id", value: requestId, expected: "req_<4-128 url-safe chars>" },
+    });
+  }
 
   const fetchLogs = async () => {
     try {
       const data = await getSdk().functions.logs(projectId, name, {
         tail,
         since: sinceIso,
+        requestId,
       });
       return data.logs || [];
     } catch (err) {
@@ -278,27 +293,60 @@ async function logs(projectId, name, args) {
   let running = true;
   process.on("SIGINT", () => { running = false; });
 
-  const initial = await fetchLogs();
-  for (const entry of initial) {
-    console.log(`[${entry.timestamp}] ${entry.message}`);
-  }
-  if (initial.length > 0) {
-    sinceIso = new Date(new Date(initial[initial.length - 1].timestamp).getTime() + 1).toISOString();
-  }
+  let highWaterMs = sinceIso === undefined ? Number.NEGATIVE_INFINITY : new Date(sinceIso).getTime();
+  let seenAtHighWater = new Set();
 
-  while (running) {
-    await new Promise(r => setTimeout(r, 3000));
-    if (!running) break;
-    const entries = await fetchLogs();
+  const printFreshEntries = (entries) => {
+    let nextHighWaterMs = highWaterMs;
+    const fresh = [];
     for (const entry of entries) {
+      const entryMs = logTimestampMs(entry);
+      const identity = logEntryIdentity(entry);
+      if (entryMs < highWaterMs) continue;
+      if (entryMs === highWaterMs && seenAtHighWater.has(identity)) continue;
+      fresh.push({ entry, entryMs, identity });
+      if (entryMs > nextHighWaterMs) nextHighWaterMs = entryMs;
+    }
+
+    for (const { entry } of fresh) {
       console.log(`[${entry.timestamp}] ${entry.message}`);
     }
-    if (entries.length > 0) {
-      sinceIso = new Date(new Date(entries[entries.length - 1].timestamp).getTime() + 1).toISOString();
+    if (fresh.length === 0 || !Number.isFinite(nextHighWaterMs)) return;
+
+    const nextSeenAtHighWater = new Set();
+    for (const entry of entries) {
+      if (logTimestampMs(entry) === nextHighWaterMs) {
+        nextSeenAtHighWater.add(logEntryIdentity(entry));
+      }
     }
+    for (const { entry, entryMs, identity } of fresh) {
+      if (entryMs === nextHighWaterMs) {
+        nextSeenAtHighWater.add(identity);
+      }
+    }
+    highWaterMs = nextHighWaterMs;
+    seenAtHighWater = nextSeenAtHighWater;
+    sinceIso = new Date(highWaterMs).toISOString();
+  };
+
+  printFreshEntries(await fetchLogs());
+
+  while (running) {
+    await new Promise(r => setTimeout(r, 3000));
+    if (!running) break;
+    printFreshEntries(await fetchLogs());
   }
 }
 
+function logTimestampMs(entry) {
+  const ms = new Date(entry.timestamp).getTime();
+  return Number.isNaN(ms) ? 0 : ms;
+}
+
+function logEntryIdentity(entry) {
+  return entry.event_id || `${entry.log_stream_name || ""}:${entry.timestamp || ""}:${entry.message || ""}`;
+}
+
 async function update(projectId, name, args) {
   assertRequiredProjectAndName(projectId, name, "run402 functions update <project_id> <name> [options]");
   assertKnownFlags(args, ["--schedule", "--schedule-remove", "--timeout", "--memory", "--help", "-h"], ["--schedule", "--timeout", "--memory"]);

cli/llms-cli.txt

@@ -47,6 +47,7 @@ Canonical fields:
 - `safe_to_retry`: repeating the same request should not duplicate or corrupt a mutation
 - `mutation_state`: one of `none`, `not_started`, `committed`, `rolled_back`, `partial`, `unknown`
 - `trace_id`: include this when reporting the issue
+- `request_id`: routed/function failure handle; use `run402 functions logs <id> <name> --request-id <req_...>` for function diagnostics. This is distinct from gateway `trace_id`.
 - `details`: structured route-specific context
 - `next_actions`: advisory suggestions such as `authenticate`, `submit_payment`, `renew_tier`, `check_usage`, `retry`, `resume_deploy`, `edit_request`, `edit_migration`, or `deploy_site_first`; do not execute route-like suggestions without validating method/path/auth/safety
 
@@ -671,10 +672,12 @@ const res = await fetch('https://api.run402.com/functions/v1/my-function', {
 
 - `run402 functions deploy <id> <name> --file <file> [--deps "<spec,...>"] [--timeout <s>] [--memory <mb>] [--schedule "<cron>"]`
 - `run402 functions invoke <id> <name> [--body '<json>'] [--method <GET|POST|...>]`
-- `run402 functions logs <id> <name> [--tail <n>] [--since <iso-timestamp>] [--follow]`
+- `run402 functions logs <id> <name> [--tail <n>] [--since <iso-timestamp>] [--request-id <req_...>] [--follow]`
 - `run402 functions update <id> <name> [--schedule "<cron>"] [--schedule-remove] [--timeout <s>] [--memory <mb>]`
 - `run402 functions <list|delete> <id> [<name>]`
 
+For routed browser 500s, copy `X-Run402-Request-Id` or the JSON `request_id` from the response and run `run402 functions logs <project> <function> --request-id req_...`. `--since` is validated locally and should be supplied for incidents older than the default recent lookup window.
+
 #### --deps semantics, runtime_version, deps_resolved
 
 `--deps` is a comma-separated list of npm specs that the gateway installs and bundles into the function zip alongside the user code:

llms-mcp.txt

@@ -48,6 +48,7 @@ Important fields:
 - `safe_to_retry` — repeating the same request will not duplicate or corrupt a mutation
 - `mutation_state` — `none` / `not_started` / `committed` / `rolled_back` / `partial` / `unknown`
 - `trace_id` — include this when reporting an issue
+- `request_id` — routed/function failure handle. Use `get_function_logs` with `request_id` for function diagnostics; it is distinct from gateway `trace_id`.
 - `details` — structured route-specific context
 - `next_actions` — `authenticate`, `submit_payment`, `renew_tier`, `check_usage`, `retry`, `resume_deploy`, `edit_request`, `edit_migration`
 
@@ -262,10 +263,12 @@ No `route_scopes` means no CI route-declaration authority. Route scopes are exac
 
 - **`deploy_function`** — deploy a Node 22 serverless function. Params: `project_id`, `name`, `code`, `config?` (`{ timeout?, memory? }`), `deps?` (npm specs: bare names → latest; pinned `lodash@4.17.21`; ranges `date-fns@^3.0.0`; max 30 entries / 200 chars; native binaries rejected; **don't list `@run402/functions`**), `schedule?` (5-field cron). Response surfaces `runtime_version`, `deps_resolved`, `warnings`.
 - **`invoke_function`** — invoke for testing over the direct `/functions/v1/:name` API-key-protected path. Params: `project_id`, `name`, `method?`, `body?`, `headers?`.
-- **`get_function_logs`** — recent logs (CloudWatch). Params: `project_id`, `name`, `tail?` (default 50, max 200), `since?` (ISO 8601, for incremental polling).
+- **`get_function_logs`** — recent logs (CloudWatch). Params: `project_id`, `name`, `tail?` (default 50, max 1000), `since?` (ISO 8601, locally validated), `request_id?` (`req_...`, for routed/function correlation). Returned lines include optional metadata such as `request_id`, `event_id`, log stream, and ingestion time.
 - **`update_function`** — change schedule / timeout / memory without redeploying code. Params: `project_id`, `name`, `schedule?` (`null` to remove), `timeout?`, `memory?`.
 - **`list_functions`** / **`delete_function`** — list / remove.
 
+For routed browser 500s, copy `X-Run402-Request-Id` or the JSON `request_id` from the response and call `get_function_logs` with that `request_id`. If the incident is older than the default recent lookup window, also pass `since`.
+
 Scheduled function tier limits: prototype 1 / 15 min, hobby 3 / 5 min, team 10 / 1 min. Deploying a scheduled function beyond the limit returns 403.
 
 ### Secrets

openclaw/SKILL.md

@@ -76,6 +76,7 @@ Fields to use:
 - `safe_to_retry`: repeating the same request should not duplicate or corrupt a mutation
 - `mutation_state`: one of `none`, `not_started`, `committed`, `rolled_back`, `partial`, `unknown`
 - `trace_id`: include when reporting an issue
+- `request_id`: routed/function failure handle; use `run402 functions logs <id> <name> --request-id <req_...>` for diagnostics. Distinct from gateway `trace_id`.
 - `details`: structured route-specific context
 - `next_actions`: advisory actions such as `authenticate`, `submit_payment`, `renew_tier`, `check_usage`, `retry`, `resume_deploy`, `edit_request`, `edit_migration`; never treat them as blindly executable
 
@@ -373,7 +374,7 @@ run402 functions deploy <id> my-fn --file fn.ts \
   --deps "stripe,zod@^3,date-fns@3.6.0"
 
 run402 functions invoke <id> my-fn --body '{"hello":"world"}'
-run402 functions logs   <id> my-fn --tail 100 --follow
+run402 functions logs   <id> my-fn --tail 100 --request-id req_abc123 --follow
 run402 functions update <id> my-fn --schedule "0 */6 * * *"
 run402 functions list   <id>
 run402 functions delete <id> my-fn