deepline 0.3.274 → 0.3.276

package/dist/cli/index.mjs

@@ -1985,18 +1985,18 @@ function playInputExampleArgs(schema) {
   if (!schema) return " --input '@<input.json>'";
   if (schema.$ref || schema.allOf) return " --input '@<input.json>'";
   const csv = schema.csvInput;
-  const csvField = typeof csv?.inputField === "string" ? csv.inputField : null;
+  const csvField2 = typeof csv?.inputField === "string" ? csv.inputField : null;
   const required = Array.isArray(schema.required) ? schema.required : [];
-  const csvOnlyRequired = required.every((key) => key === csvField);
+  const csvOnlyRequired = required.every((key) => key === csvField2);
   const alternatives = schema.oneOf ?? schema.anyOf;
   const hasCsvAlternative = Array.isArray(alternatives) && alternatives.some((branch) => {
     if (!branch || typeof branch !== "object") return false;
     const keys = branch.required;
-    return Array.isArray(keys) && keys.includes(csvField) && keys.every((key) => key === csvField);
+    return Array.isArray(keys) && keys.includes(csvField2) && keys.every((key) => key === csvField2);
   });
-  if (csvField && csvOnlyRequired && (!alternatives || hasCsvAlternative)) {
-    if (csvField === "csv") return " --csv '<contacts.csv>'";
-    const value = JSON.stringify({ [csvField]: "<contacts.csv>" });
+  if (csvField2 && csvOnlyRequired && (!alternatives || hasCsvAlternative)) {
+    if (csvField2 === "csv") return " --csv '<contacts.csv>'";
+    const value = JSON.stringify({ [csvField2]: "<contacts.csv>" });
     return ` --input '${value.replace(/'/g, "'\\''")}'`;
   }
   if (Array.isArray(schema.required) && !required.length && !csv && !alternatives) {
@@ -3507,7 +3507,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.274",
+  version: "0.3.276",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
@@ -6210,6 +6210,28 @@ async function* watchRunEvents(options) {
   }
 }
 
+// src/runs/log-cursor.ts
+var RUN_LOGS_CURSOR_PREFIX = "before:";
+function encodeRunLogsCursor(beforeSequence) {
+  return `${RUN_LOGS_CURSOR_PREFIX}${beforeSequence}`;
+}
+function isRunLogsCursor(value) {
+  return value.startsWith(RUN_LOGS_CURSOR_PREFIX);
+}
+function parseRunLogsCursor(value) {
+  const raw = isRunLogsCursor(value) ? value.slice(RUN_LOGS_CURSOR_PREFIX.length) : "";
+  const parsed = /^[1-9]\d*$/.test(raw) ? Number(raw) : NaN;
+  if (!Number.isSafeInteger(parsed)) {
+    throw Object.assign(
+      new Error(
+        `Invalid run log cursor ${JSON.stringify(value)}. Pass the nextCursor value from a previous deepline runs logs result.`
+      ),
+      { exitCode: 2 }
+    );
+  }
+  return parsed;
+}
+
 // src/types.ts
 function isStopAllPlayRunsDryRunResult(result) {
   return "dryRun" in result && result.dryRun === true;
@@ -7160,6 +7182,7 @@ var DeeplineClient = class _DeeplineClient {
       status: (runId) => this.getRunLifecycleStatus(runId),
       list: (options2) => this.listRuns(options2),
       listPage: (options2) => this.listRunsPage(options2),
+      history: (options2) => this.getRunsHistory(options2),
       watch: (runId, options2) => this.watchRunToTerminal(runId, options2),
       tail: (runId, options2) => this.tailRun(runId, options2),
       logs: (runId, options2) => this.getRunLogs(runId, options2),
@@ -8237,11 +8260,21 @@ var DeeplineClient = class _DeeplineClient {
     if (options?.full === true) {
       params.set("full", "true");
     }
+    if (options?.configuration === true) {
+      params.set("include", "configuration");
+    }
     const query = params.size > 0 ? `?${params.toString()}` : "";
     const response = await this.http.get(
       `/api/v2/runs/${encodeURIComponent(runId)}${query}`,
       { headers: { "x-deepline-run-status": "1" } }
     );
+    if (options?.configuration === true && !Object.hasOwn(response, "contract")) {
+      throw new DeeplineError(
+        "This server does not support recorded configuration reads.",
+        void 0,
+        "RUN_CONFIGURATION_UNAVAILABLE"
+      );
+    }
     const status = normalizePlayStatus(response);
     if (options?.failedLogs !== true || status.status !== "failed") {
       return status;
@@ -8329,6 +8362,33 @@ var DeeplineClient = class _DeeplineClient {
   async listRuns(options) {
     return (await this.listRunsPage(options)).runs;
   }
+  /** The same tenant-scoped run history searched by the dashboard and CLI. */
+  async getRunsHistory(options = {}) {
+    const params = new URLSearchParams();
+    const search = options.search?.trim();
+    if (search && search.length > 200) {
+      throw new Error("Run search must be at most 200 characters.");
+    }
+    if (options.type && options.type !== "all" && !search) {
+      throw new Error("runs.history options.type requires options.search.");
+    }
+    if (search) params.set("search", search);
+    if (search && options.type) params.set("type", options.type);
+    if (options.cursor) params.set("cursor", options.cursor);
+    if (options.orgId) params.set("orgId", options.orgId);
+    if (options.limit !== void 0) {
+      if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+        throw new Error(
+          "runs.history options.limit must be a positive integer."
+        );
+      }
+      params.set("limit", String(options.limit));
+    }
+    return this.http.get(
+      `/api/v2/dashboard/runs-history?${params.toString()}`,
+      { signal: options.signal }
+    );
+  }
   /** Read one run page without discarding server pagination metadata. */
   async listRunsPage(options) {
     const playName = options.play?.trim();
@@ -8435,6 +8495,13 @@ var DeeplineClient = class _DeeplineClient {
         "INVALID_RUN_LOG_VIEW"
       );
     }
+    if (options?.cursor !== void 0 && options.failed === true) {
+      throw new DeeplineError(
+        "runs.logs cannot combine failed with cursor.",
+        void 0,
+        "INVALID_RUN_LOG_VIEW"
+      );
+    }
     if (options?.failed === true) {
       const requestedLimit = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0 ? Math.trunc(options.limit) : RUNS_FAILED_LOG_LIMIT;
       const failedLimit = Math.min(RUNS_FAILED_LOG_LIMIT, requestedLimit);
@@ -8460,6 +8527,7 @@ var DeeplineClient = class _DeeplineClient {
         ...page.logsTruncated ? { logsTruncated: true } : {}
       };
     }
+    const beforeSequence = options?.cursor !== void 0 ? parseRunLogsCursor(options.cursor) : null;
     const limit = options?.all ? Number.MAX_SAFE_INTEGER : typeof options?.limit === "number" && Number.isFinite(options.limit) && options.limit > 0 ? Math.trunc(options.limit) : 200;
     const fetchPage = (afterSeq2, pageLimit) => this.http.get(
       `/api/v2/runs/${encodeURIComponent(runId)}/logs?afterSeq=${afterSeq2}&limit=${pageLimit}`,
@@ -8467,24 +8535,33 @@ var DeeplineClient = class _DeeplineClient {
     );
     const probe = await fetchPage(0, 1);
     const lastStoredSeq = probe.lastStoredSeq;
-    let afterSeq = options?.all ? 0 : Math.max(0, lastStoredSeq - limit);
+    const oldestStoredSeq = probe.entries[0]?.seq ?? null;
+    const upperSeq = beforeSequence === null ? Number.POSITIVE_INFINITY : Math.min(beforeSequence - 1, lastStoredSeq);
+    const windowEndSeq = Math.min(upperSeq, lastStoredSeq);
+    let afterSeq = options?.all ? 0 : Math.max(0, windowEndSeq - limit);
     const entries = [];
-    while (entries.length < limit) {
+    while (entries.length < limit && afterSeq < upperSeq) {
       const page = await fetchPage(
         afterSeq,
-        Math.min(RUN_LOGS_PAGE_LIMIT, limit - entries.length)
+        Math.min(
+          RUN_LOGS_PAGE_LIMIT,
+          limit - entries.length,
+          upperSeq - afterSeq
+        )
       );
-      if (page.entries.length === 0) {
+      const inWindow = page.entries.filter((entry) => entry.seq <= upperSeq);
+      if (inWindow.length === 0) {
         break;
       }
-      entries.push(...page.entries);
-      afterSeq = page.entries[page.entries.length - 1].seq;
-      if (!page.hasMore) {
+      entries.push(...inWindow);
+      afterSeq = inWindow[inWindow.length - 1].seq;
+      if (!page.hasMore || inWindow.length < page.entries.length) {
         break;
       }
     }
     const firstSequence = entries.length > 0 ? entries[0].seq : null;
     const lastSequence = entries.length > 0 ? entries[entries.length - 1].seq : null;
+    const olderLinesExist = firstSequence !== null && oldestStoredSeq !== null && firstSequence > oldestStoredSeq;
     return {
       runId: probe.runId,
       totalCount: probe.totalLogCount,
@@ -8492,7 +8569,8 @@ var DeeplineClient = class _DeeplineClient {
       firstSequence,
       lastSequence,
       truncated: entries.length < probe.totalLogCount,
-      hasMore: lastSequence !== null && lastSequence < lastStoredSeq,
+      hasMore: olderLinesExist,
+      nextCursor: olderLinesExist ? encodeRunLogsCursor(firstSequence) : null,
       entries: entries.map((entry) => entry.line),
       view: options?.all ? "all" : "tail",
       ...probe.logsTruncated ? { logsTruncated: true } : {}
@@ -10469,6 +10547,7 @@ var ROOTS = {
   check: "kind target checked scope name exportName valid stage issues inputSchema outputSchema recognized triggers runtimeLimit limits featureFlags sourceHash artifactHash graphHash toolGetterHints exports actions diagnostics reference origin ownerType activeScheduledPlays command_context",
   run: "schemaVersion kind run datasets actions apiVersion dashboardUrl progress rowOutcomes steps errors error warnings result resultState execution command_context diagnostics",
   get: "schemaVersion kind run runStatus steps failures errorDetails rowOutcomes warnings failedLogs datasets result resultState actions diagnostics command_context",
+  config: "runId contract command_context",
   export: "runId datasets csv_path json_path format source rowCount columns notice metadata_path actions command_context"
 };
 function parseJsonFields(args, surface) {
@@ -15690,205 +15769,73 @@ function registerPlayTriggerConfigCommands(plays) {
 import { createHash as createHash4, randomUUID as randomUUID4 } from "crypto";
 
 // src/cli/run-logs-help.ts
-var EVENT_DETAILS = {
-  "run.created": {
-    emittedBy: "Run admission",
-    payloadFields: ["status", "playName", "runtimeBackend"]
-  },
-  "run.started": {
-    emittedBy: "Execution coordinator",
-    payloadFields: ["playName", "runtimeBackend"]
-  },
-  "run.waiting": {
-    emittedBy: "Durable wait handling",
-    payloadFields: ["waitKind", "waitUntil"]
-  },
-  "run.resumed": { emittedBy: "Durable wait handling", payloadFields: [] },
-  "run.completed": {
-    emittedBy: "Run finalization",
-    payloadFields: ["result", "resultSummary", "terminalWorkCounterSegment"]
-  },
-  "run.failed": {
-    emittedBy: "Run finalization",
-    payloadFields: [
-      "error",
-      "result",
-      "resultSummary",
-      "terminalWorkCounterSegment"
-    ]
-  },
-  "run.cancelled": {
-    emittedBy: "Run cancellation",
-    payloadFields: ["error", "result"]
-  },
-  "step.started": {
-    emittedBy: "Managed step execution",
-    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
-  },
-  "step.progress": {
-    emittedBy: "Managed step execution",
-    payloadFields: ["stepId", "label", "kind", "status", "progress"]
-  },
-  "step.completed": {
-    emittedBy: "Managed step execution",
-    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
-  },
-  "step.failed": {
-    emittedBy: "Managed step execution",
-    payloadFields: [
-      "stepId",
-      "label",
-      "kind",
-      "error",
-      "artifactTableNamespace"
-    ]
-  },
-  "step.skipped": {
-    emittedBy: "Managed step execution",
-    payloadFields: ["stepId", "label", "kind", "artifactTableNamespace"]
-  },
-  "log.appended": {
-    emittedBy: "ctx.log and runtime/coordinator messages",
-    payloadFields: [
-      "lines",
-      "lineContexts",
-      "producerAttempt",
-      "channelOffset",
-      "logsTruncated"
-    ]
-  },
-  "dataset.lifecycle": {
-    emittedBy: "Managed dataset storage",
-    payloadFields: [
-      "datasetId",
-      "path",
-      "tableNamespace",
-      "phase",
-      "persistedRows",
-      "succeededRows",
-      "failedRows",
-      "complete",
-      "bornFrom"
-    ]
+var KIND_DESCRIPTIONS = {
+  "run.created": "Run accepted.",
+  "run.started": "Execution started.",
+  "run.waiting": "Run waiting.",
+  "run.resumed": "Execution resumed.",
+  "run.completed": "Run succeeded.",
+  "run.failed": "Run failed.",
+  "run.cancelled": "Run cancelled.",
+  "step.started": "Step started.",
+  "step.progress": "Progress update.",
+  "step.completed": "Step succeeded.",
+  "step.failed": "Step failed.",
+  "step.skipped": "Step skipped.",
+  "log.appended": "Text log line.",
+  "dataset.lifecycle": "Dataset registered, available or failed.",
+  "activity.observed": "Provider or workflow activity.",
+  "work.counters": "Call, request and rate-limit totals.",
+  "receipt.completed": "Saved work result: succeeded.",
+  "receipt.failed": "Saved work result: failed.",
+  "receipt.skipped": "Saved work result: skipped.",
+  "runtime.event": "Other event."
+};
+var RUN_LOGS_KIND_HELP = RUN_EVENT_SEARCH_KIND_VALUES.map((kind) => ({
+  kind,
+  description: KIND_DESCRIPTIONS[kind]
+}));
+var READ_EXAMPLES = [
+  "deepline runs logs '<run-id>'",
+  "deepline runs logs '<run-id>' --out run.log"
+];
+var FILTER_EXAMPLES = [
+  {
+    label: "Failed work with saved details",
+    command: `deepline runs logs --kind receipt.failed --where '$.status == "failed"' --payloads --json`
   },
-  "activity.observed": {
-    emittedBy: "Managed provider/dataset/runner activity",
-    payloadFields: ["observation"]
+  {
+    label: "One failed step",
+    command: `deepline runs logs --kind step.failed --where '$.stepId == "company-lookup"' --payloads --json`
   },
-  "work.counters": {
-    emittedBy: "Runtime work accounting",
-    payloadFields: [
-      "attempt",
-      "invocationSeq",
-      "segmentId",
-      "logicalCalls",
-      "providerRequests",
-      "provider429s",
-      "final"
-    ]
-  }
-};
-var RUN_LOGS_KIND_HELP = [
-  ...Object.entries(RUN_EVENT_KIND_CATALOG).map(([kind, descriptor]) => ({
-    kind,
-    description: descriptor.description,
-    ...EVENT_DETAILS[kind]
-  })),
-  ...Object.entries(RUN_RECEIPT_SEARCH_KIND_CATALOG).map(
-    ([kind, descriptor]) => ({
-      kind,
-      description: descriptor.description,
-      emittedBy: "Durable work receipt settlement",
-      payloadFields: ["status", "output", "error", "errorPayload"]
-    })
-  ),
   {
-    kind: RUN_EVENT_SEARCH_FALLBACK_KIND,
-    description: "Fallback for an observation without a recognized event type.",
-    emittedBy: "Event indexing",
-    payloadFields: []
-  }
-];
-var SECTIONS = [
+    label: "Provider and operation",
+    command: `deepline runs logs --kind activity.observed --where '$.provider == "apollo" && $.operation == "company_lookup"' --json`
+  },
   {
-    title: "Choose the read",
-    paragraphs: [
-      "These commands read existing evidence; they do not start a run or execute a provider. Replace <run-id>, <play-name> and other angle-bracket values with identifiers returned by the CLI.",
-      "Text logs: runs logs <run-id> returns the last 200 retained lines by default. --out writes the full retained stream to a local file. --log-level filters text severity; debug includes all retained levels. --failed reads only a terminal-failed run\u2019s last 20 retained lines and reports retention limitations.",
-      "Event search: omit the run ID, or add any of --since, --until, --play, --kind, --where, --payloads, --cursor, --runtime-namespace or --runtime-backend. A supplied run ID then narrows the search. --limit and --json alone do not switch a run\u2019s text logs to event search. Text-only flags --out, --failed and --log-level cannot be combined with event search.",
-      "Current status and returned output selectors: runs get <run-id> --json. Live observation: runs watch <run-id>. Dataset rows: runs export <run-id> --dataset <returned-selector> --out rows.csv. A referenced tool response: runs receipt <run-id> --key <returned-receipt-key> --json. Read each command\u2019s --help for its options."
-    ],
-    commands: [
-      "deepline runs logs <run-id> --json",
-      "deepline runs logs <run-id> --out run.log --json",
-      "deepline runs logs --kind run.failed --json",
-      "deepline runs logs --kind step.failed --payloads --json",
-      "deepline runs logs --kind receipt.failed --payloads --json"
-    ]
+    label: "Failed dataset",
+    command: `deepline runs logs --kind dataset.lifecycle --where '$.datasetId == "companies" && $.phase == "failed"' --payloads --json`
   },
   {
-    title: "Search window and pagination",
-    paragraphs: [
-      "Search defaults to the last hour, newest first. Use explicit ISO UTC --since and --until values for reproducible queries; the maximum lookback is seven days. Default page size is 100 events; --limit accepts 1\u2013200. With --payloads, default and maximum are 10 events, with 16 MiB total payload data.",
-      "JSON returns events[], returnedCount, since, until, nextCursor and next.logs. Run the returned next.logs command to continue with the same filters and UTC window; nextCursor is opaque. A bounded page or an empty result does not establish whole-run coverage or application health."
-    ],
-    commands: [
-      "deepline runs logs <run-id> --kind log.appended --json",
-      "deepline runs logs --play <play-name> --since <UTC-start> --until <UTC-end> --json"
-    ]
+    label: "String log context",
+    command: `deepline runs logs --kind log.appended --where '$.context.companyId == "acme_123"' --json`
   },
   {
-    title: "Fields you can filter with --where",
-    paragraphs: [
-      "Identity strings: orgId, runId, playName, runtimeScope. These come from authenticated execution state; filters only narrow your authorized organization/runtime. Preview reads require the existing runtime credential and an authorized --runtime-namespace; --runtime-backend selects daytona or modal.",
-      "Event string: kind. Optional strings: source, stepId, stepKind, status, datasetId, phase, provider, operation. Optional positive integer: producerAttempt. These fields exist only when recorded; inspect a returned event before filtering on an optional field.",
-      'stepId/stepKind describe recorded step work; datasetId/phase describe dataset lifecycle (registered, available, failed). provider/operation appear on typed provider activity.observed events, not every receipt or provider call. status is the recorded status or activity state when present: run.completed and step.completed do not imply status == "completed". Select lifecycle outcomes with --kind.',
-      "context.<key> matches an authored flat scalar log field: string, number or boolean. Context cannot override event identity. Missing fields do not match. --where supports only $.field == literal predicates joined with &&, at most eight predicates and 512 bytes. No OR, ranges, wildcards, nested payload paths or text search. Time uses --since/--until; level and message are not --where fields.",
-      'Wrap the entire predicate in single shell quotes so $ and && reach the CLI unchanged. Inside it, strings use double quotes; numbers and booleans are unquoted. Types must match: 2 differs from "2", false differs from "false". Examples use illustrative recorded values; use your own step IDs, dataset IDs, provider/operation names and authored context. The context examples assume ctx.log recorded companyId: "acme_123", attempt: 2 and cached: false.'
-    ],
-    commands: [
-      "# Failed retained work with its stored error/result",
-      `deepline runs logs --kind receipt.failed --where '$.status == "failed"' --payloads --json`,
-      "# Failure details for one named step",
-      `deepline runs logs --kind step.failed --where '$.stepId == "company-lookup"' --payloads --json`,
-      "# Typed provider observations matching both fields",
-      `deepline runs logs --kind activity.observed --where '$.provider == "apollo" && $.operation == "company_lookup"' --json`,
-      "# Failed lifecycle transitions for one dataset",
-      `deepline runs logs --kind dataset.lifecycle --where '$.datasetId == "companies" && $.phase == "failed"' --payloads --json`,
-      "# Authored string context on log lines",
-      `deepline runs logs --kind log.appended --where '$.context.companyId == "acme_123"' --json`,
-      "# Authored number and boolean context, both required to match",
-      "deepline runs logs --kind log.appended --where '$.context.attempt == 2 && $.context.cached == false' --json",
-      "# Known producer identity within one run",
-      `deepline runs logs <run-id> --where '$.source == "worker" && $.producerAttempt == 1' --json`
-    ]
+    label: "Number and boolean log context",
+    command: "deepline runs logs --kind log.appended --where '$.context.attempt == 2 && $.context.cached == false' --json"
   },
   {
-    title: "What you get back",
-    paragraphs: [
-      "Search events include eventId, occurredAt, ingestedAt, kind, runId, playName, level and message. The CLI puts indexed fields directly on each events[] entry; SDK/API responses keep them under searchDoc. Log search message is a preview (up to 2,048 characters); use text logs or --out for full retained lines.",
-      "--payloads adds eventPayload for stored canonical events: lifecycle, step details/errors, activity observations, dataset transitions and work counters. Receipt matches instead hydrate payload with status, output, error and errorPayload. An event without a receipt does not promise a tool response; retained payloads may be unavailable. Neither --where nor event search indexes request/response bodies.",
-      "Search does not expose a receipt key or storage reference. To retrieve a specific retained tool response with runs receipt, use the receipt key returned in the run\u2019s exported evidence or tool execution metadata. For full row data, follow runs get output/export actions; dataset.lifecycle contains metadata, not all dataset rows.",
-      "The catalog lists known searchable kinds, including receipt outcomes and the runtime.event fallback. Use the exact dotted name with --kind. Future stored kinds can also be queried; this list is not a CLI validation allowlist. Events are observations, not a count of billed provider calls.",
-      "Catalog payload fields are possible producer fields, not required fields or --where paths. Canonical eventPayload uses type for the dotted event kind; its kind field, when present on a step, becomes indexed stepKind. Indexed log entries describe individual lines rather than reproducing the original lines batch.",
-      "Canonical event envelopes carry runId, type, occurredAt (producer milliseconds), source, optional seq and optional producer-owned payload. Search occurredAt/ingestedAt are UTC timestamp strings. source identifies the recorded producer; producerAttempt is present only when known.",
-      "activity.observed stores observation with activityId, stepId, target, state and observedAt. Targets describe provider, dataset, lease, runner, step or capacity work. State kinds are active, queued, waiting, retrying, scheduled, completed or failed; retry/wait detail stays in the payload. work.counters contains aggregate logicalCalls, providerRequests and provider429s, not per-call responses."
-    ],
-    commands: []
+    label: "One run and step",
+    command: `deepline runs logs '<run-id>' --where '$.stepId == "company-lookup"' --json`
   }
 ];
-var RETENTION = [
-  "Event/log/receipt search shares the PlanetScale index. New runs marked runEventStore=planet_scale retain accepted event/log history in PlanetScale; Convex keeps current run/control state and eligible saved-Play rollup facts. Older unmarked runs retain their existing readers. No backfill is implied.",
-  "Search retention is seven days; receipt payload retention is independent. Logs reflect accepted, retained lines: runtime sampling and truncation can omit original console output. Read returned retention/sampling warnings; an export contains the full retained stream, not suppressed lines."
-];
-function wrapParagraph(text, indent2 = 2) {
+function wrapParagraph(text) {
   const lines = [];
-  const padding = " ".repeat(indent2);
-  let line = padding;
+  let line = "  ";
   for (const word of text.split(" ")) {
     if (line.length + word.length > 80 && line.trim()) {
       lines.push(line.trimEnd());
-      line = padding;
+      line = "  ";
     }
     line += `${word} `;
   }
@@ -15896,34 +15843,36 @@ function wrapParagraph(text, indent2 = 2) {
   return lines.join("\n");
 }
 function renderRunLogsHelp() {
-  const section = ({
-    title,
-    paragraphs,
-    commands
-  }) => [
-    `${title}:`,
-    ...paragraphs.flatMap((paragraph) => [wrapParagraph(paragraph), ""]),
-    ...commands.length ? ["  Common commands:", ...commands.map((command) => `    ${command}`)] : [],
-    ""
-  ];
   return [
     "",
-    ...section(SECTIONS[0]),
-    "Known --kind values (complete catalog):",
-    ...RUN_LOGS_KIND_HELP.flatMap(
-      ({ kind, description, emittedBy, payloadFields }) => [
-        `  ${kind}`,
-        wrapParagraph(description, 4),
-        wrapParagraph(
-          `Recorded by: ${emittedBy}. Payload fields: ${kind === RUN_EVENT_SEARCH_FALLBACK_KIND ? "producer-specific fields; inspect the returned payload" : payloadFields.join(", ") || "event envelope only"}.`,
-          4
-        )
-      ]
+    "Examples:",
+    `  ${READ_EXAMPLES[0]}`,
+    "  deepline runs logs --kind run.failed --json",
+    ...[FILTER_EXAMPLES[1], FILTER_EXAMPLES[2], FILTER_EXAMPLES[5]].map(
+      ({ command }) => `  ${command}`
+    ),
+    "",
+    "Event kinds:",
+    ...RUN_LOGS_KIND_HELP.map(
+      ({ kind, description }) => `  ${kind.padEnd(20)} ${description}`
     ),
     "",
-    ...SECTIONS.slice(1).flatMap(section),
-    "Storage and retention:",
-    ...RETENTION.flatMap((paragraph) => [wrapParagraph(paragraph), ""])
+    "Filters:",
+    ...[
+      "Use $.field == value; combine matches with &&.",
+      "Quote the whole filter with single shell quotes. Strings use double quotes; numbers and booleans are unquoted.",
+      "Missing fields do not match. Maximum eight matches and 512 bytes per filter."
+    ].map((note) => wrapParagraph(note)),
+    "",
+    "Search:",
+    ...[
+      "A run ID alone reads text logs. Omit it or add a search flag to search events; a supplied run ID narrows the search.",
+      "Defaults to the last hour; maximum lookback is seven days. Follow next.logs for events; use nextCursor with --cursor for older text logs.",
+      "--payloads returns available details or saved results: up to 10 events and 16 MiB.",
+      "--out, --failed and --log-level apply to text logs and cannot be combined with event search."
+    ].map((note) => wrapParagraph(note)),
+    "",
+    "More examples: https://deepline.com/docs/sdk-v2/run-events"
   ].join("\n");
 }
 
@@ -18599,24 +18548,31 @@ includes nextCommand when another page is available.
 
 // src/cli/commands/plays/run-history.ts
 async function handleRunsHistory(options) {
-  const query = new URLSearchParams();
-  if (options.cursor) query.set("cursor", options.cursor);
-  if (options.org) query.set("orgId", options.org);
+  let limit;
+  if (options.type && !["all", "plays", "monitors"].includes(options.type)) {
+    throw new Error("--type must be all, plays or monitors.");
+  }
   if (options.limit !== void 0) {
-    const limit = Number(options.limit);
+    limit = Number(options.limit);
     if (!/^\d+$/.test(options.limit) || !Number.isSafeInteger(limit) || limit < 1) {
       throw new Error("--limit must be a positive integer.");
     }
-    query.set("limit", String(limit));
   }
-  const search = query.toString();
-  const page = await new HttpClient(resolveConfig()).get(
-    `/api/v2/dashboard/runs-history${search ? `?${search}` : ""}`
-  );
+  const page = await new DeeplineClient().runs.history({
+    cursor: options.cursor,
+    orgId: options.org,
+    search: options.search,
+    type: options.type,
+    limit
+  });
   const lines = page.runs.map(
     (run) => `${run.workflowName} \xB7 ${run.status} \xB7 ${run.runId}`
   );
-  if (lines.length === 0) lines.push("No runs found on this page.");
+  if (lines.length === 0) {
+    lines.push(
+      options.search && page.hasMore ? "No matches in this page; continue searching with the next cursor." : "No runs found on this page."
+    );
+  }
   if (page.hasMore) lines.push(`Next cursor: ${page.nextCursor}`);
   printCommandEnvelope(
     { ...page, render: { sections: [{ title: "Run history", lines }] } },
@@ -18628,6 +18584,12 @@ function registerRunHistoryCommand(runs) {
     "--cursor <cursor>",
     "Opaque nextCursor returned by the previous page"
   ).option("--limit <count>", "Maximum runs on this page").option(
+    "--search <text>",
+    "Search Play/workflow names, run IDs and statuses"
+  ).option(
+    "--type <type>",
+    "Search all, plays or monitors (requires --search)"
+  ).option(
     "--org <id>",
     "Workspace ID (must match the authenticated workspace)"
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").addHelpText(
@@ -24357,6 +24319,63 @@ var SDK_TYPES_ENTRY_FILE = HAS_SOURCE_BUNDLING_SOURCES ? SDK_ENTRY_FILE : resolv
 import { writeFileSync as writeFileSync9 } from "fs";
 import { resolve as resolve10 } from "path";
 
+// ../plays/table-csv.ts
+var TABLE_EXPORT_ERROR_COLUMN = "_error";
+var UNRECORDED_FAILURE_REASON = "Row failed without a recorded reason.";
+function tableCellText(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean")
+    return String(value);
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "symbol" || typeof value === "function") return "";
+  try {
+    return JSON.stringify(
+      value,
+      (_key, nested) => typeof nested === "bigint" ? nested.toString() : nested
+    ) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+function csvField(value) {
+  const text = tableCellText(value);
+  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+function csvRecord(values) {
+  return `${values.map(csvField).join(",")}
+`;
+}
+function isFailedRow(row) {
+  return row.status === "failed";
+}
+function tableExportHasFailedRows(rows) {
+  for (const row of rows) if (isFailedRow(row)) return true;
+  return false;
+}
+function tableExportErrorCell(row) {
+  if (!isFailedRow(row)) return "";
+  const reason = typeof row.error === "string" ? row.error.trim() : "";
+  return reason || UNRECORDED_FAILURE_REASON;
+}
+function tableExportColumns(columns, withError) {
+  if (!withError) return [...columns];
+  return [
+    ...columns.filter((column) => column !== TABLE_EXPORT_ERROR_COLUMN),
+    TABLE_EXPORT_ERROR_COLUMN
+  ];
+}
+function tableExportCells(row, columns, withError) {
+  return tableExportColumns(columns, withError).map(
+    (column) => column === TABLE_EXPORT_ERROR_COLUMN && withError ? tableExportErrorCell(row) : Object.hasOwn(row.data, column) ? row.data[column] : void 0
+  );
+}
+function tableCsvText(header, records) {
+  let text = csvRecord(header);
+  for (const record5 of records) text += csvRecord(record5);
+  return text;
+}
+
 // src/cli/run-dataset-order.ts
 function underscoreKeysLast(keys) {
   return [...keys].sort(
@@ -24405,9 +24424,13 @@ var RunDatasetCsv = class _RunDatasetCsv {
   }
   write(outPath) {
     const absolutePath = resolve10(outPath);
+    const { rows, columns } = this.#projection;
     writeFileSync9(
       absolutePath,
-      csvStringFromRows(this.#projection.rows, this.#projection.columns),
+      tableCsvText(
+        columns,
+        rows.map((data) => tableExportCells({ data }, columns, false))
+      ),
       "utf-8"
     );
     return absolutePath;
@@ -32003,7 +32026,20 @@ async function fetchBackingDatasetRows(input2) {
     }
     offset += page.rows.length;
   }
-  const rows = sheetRows.map(exportableSheetRow).filter((row) => Boolean(row));
+  const withError = tableExportHasFailedRows(
+    sheetRows.filter(
+      (row) => Boolean(row) && typeof row === "object" && !Array.isArray(row)
+    )
+  );
+  const rows = sheetRows.map((row) => {
+    const data = exportableSheetRow(row);
+    return data && withError ? {
+      ...data,
+      [TABLE_EXPORT_ERROR_COLUMN]: tableExportErrorCell(
+        row
+      )
+    } : data;
+  }).filter((row) => Boolean(row));
   const hasCompleteSettledPrefix = acceptsSettledRowsAsCompleteExport(input2.status) && settledTotal !== null && // A zero-row run-scoped read is not a settled export when the returned
   // Dataset Handle advertised rows. That shape is the replay/reuse case:
   // the rows belong to another writer (or the projection has not caught up)
@@ -33985,9 +34021,12 @@ function renderRunOverviewText(overview, extras = {}) {
 ${renderCommandEnvelopeText({ render: { sections, actions: actions2 } })}`;
 }
 async function handleRunGet(args) {
-  const selection = parseJsonFields(args, "get");
+  const selection = parseJsonFields(
+    args,
+    args.includes("--config") ? "config" : "get"
+  );
   args = selection.args;
-  const usage2 = "Usage: deepline runs get <run-id> [--json] [--full] [--input] [--log-failed]";
+  const usage2 = "Usage: deepline runs get <run-id> [--json] [--full] [--input] [--config] [--log-failed]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage2);
@@ -33996,6 +34035,25 @@ async function handleRunGet(args) {
     return 1;
   }
   const client2 = new DeeplineClient();
+  if (args.includes("--config")) {
+    if (args.some((arg) => ["--input", "--full", "--log-failed"].includes(arg))) {
+      console.error(
+        "--config cannot be combined with --input, --full or --log-failed."
+      );
+      return 1;
+    }
+    const status2 = await client2.runs.get(runId, { configuration: true });
+    if (!Object.hasOwn(status2, "contract")) {
+      throw new Error(
+        "This server does not support recorded configuration reads."
+      );
+    }
+    printCommandEnvelope(
+      { runId, contract: status2.contract ?? null },
+      { json: true, fields: selection.fields }
+    );
+    return 0;
+  }
   if (args.includes("--input")) {
     const input2 = await client2.getRunInput(runId);
     printCommandEnvelope(input2, { json: true });
@@ -34501,15 +34559,17 @@ async function handleRunLogs(args) {
     "--play",
     "--kind",
     "--where",
-    "--cursor",
     "--payloads",
     "--runtime-namespace",
     "--runtime-backend"
   ]);
-  if (!args[0] || args[0].startsWith("--") || args.some((arg) => searchFlags.has(arg))) {
+  const cursorIndex = args.indexOf("--cursor");
+  const cursorValue = cursorIndex >= 0 ? args[cursorIndex + 1] : void 0;
+  const continuesEventSearch = cursorIndex >= 0 && !(cursorValue && isRunLogsCursor(cursorValue));
+  if (!args[0] || args[0].startsWith("--") || continuesEventSearch || args.some((arg) => searchFlags.has(arg))) {
     return handleRunEventSearch(args);
   }
-  const usage2 = "Usage: deepline runs logs <run-id> [--limit 200] [--failed] [--out run.log] [--log-level debug|info|warn|error] [--json]";
+  const usage2 = "Usage: deepline runs logs <run-id> [--limit 200] [--cursor before:<seq>] [--failed] [--out run.log] [--log-level debug|info|warn|error] [--json]";
   let runId;
   try {
     runId = parseRunIdPositional(args, usage2);
@@ -34519,6 +34579,7 @@ async function handleRunLogs(args) {
   }
   let limit = 200;
   let outPath = null;
+  let cursor;
   let logLevel = "debug";
   let hasExplicitLogLevel = false;
   let usesDebugAlias = false;
@@ -34557,6 +34618,10 @@ async function handleRunLogs(args) {
       outPath = resolve13(args[++index]);
       continue;
     }
+    if (arg === "--cursor" && args[index + 1]) {
+      cursor = args[++index];
+      continue;
+    }
     if (arg.startsWith("--")) {
       console.error(`${arg} is not supported by deepline runs logs.`);
       return 1;
@@ -34575,6 +34640,12 @@ async function handleRunLogs(args) {
     );
     return 1;
   }
+  if (cursor !== void 0 && (failed || outPath)) {
+    console.error(
+      "--cursor pages the bounded log tail; it cannot be combined with --failed or --out."
+    );
+    return 1;
+  }
   const client2 = new DeeplineClient();
   if (outPath) {
     const result2 = await client2.runs.logs(runId, { all: true });
@@ -34608,19 +34679,25 @@ async function handleRunLogs(args) {
     return 0;
   }
   const result = await client2.runs.logs(runId, {
-    ...failed ? { limit, failed: true } : { all: logLevel !== "debug", limit }
-  });
-  const matchingEntries = result.entries.filter(
-    (line) => logLevelReaches(classifyLogLine(line).level, logLevel)
-  );
-  const entries = failed ? matchingEntries : matchingEntries.slice(-limit);
-  const matchingEntriesTruncated = !failed && matchingEntries.length > limit;
+    ...failed ? { limit, failed: true } : { all: logLevel !== "debug", limit },
+    ...cursor !== void 0 ? { cursor } : {}
+  });
+  const page = failed ? {
+    entries: result.entries,
+    firstSequence: result.firstSequence,
+    lastSequence: result.lastSequence,
+    truncated: result.truncated,
+    hasMore: result.hasMore,
+    nextCursor: void 0
+  } : selectRunLogTailPage(result, logLevel, limit);
+  const entries = page.entries;
+  const nextPage = page.nextCursor ? `deepline runs logs ${result.runId} --limit ${limit}${logLevel === "debug" ? "" : ` --log-level ${logLevel}`} --cursor ${page.nextCursor} --json` : null;
   const filteredResult = {
     ...result,
     entries,
     returnedCount: entries.length,
-    truncated: result.truncated || matchingEntriesTruncated,
-    hasMore: result.hasMore || matchingEntriesTruncated,
+    truncated: page.truncated,
+    hasMore: page.hasMore,
     view: failed ? result.view : "tail",
     next: {
       ...result.next ?? {},
@@ -34633,10 +34710,11 @@ async function handleRunLogs(args) {
       runId: result.runId,
       totalCount: result.totalCount,
       returnedCount: entries.length,
-      firstSequence: result.firstSequence,
-      lastSequence: result.lastSequence,
+      firstSequence: page.firstSequence,
+      lastSequence: page.lastSequence,
       truncated: filteredResult.truncated,
       hasMore: filteredResult.hasMore,
+      ...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {},
       logLevel,
       ...result.logsTruncated ? { logsTruncated: true } : {},
       entries,
@@ -34645,6 +34723,7 @@ async function handleRunLogs(args) {
       ...result.warning ? { warning: result.warning } : {},
       next: {
         ...result.next ?? {},
+        ...nextPage ? { page: nextPage } : {},
         export: `deepline runs logs ${result.runId} --out run.log --log-level ${logLevel} --json`
       },
       render: { sections: [{ title: "run logs", lines: entries }] }
@@ -34656,6 +34735,37 @@ async function handleRunLogs(args) {
   );
   return 0;
 }
+function selectRunLogTailPage(result, logLevel, limit) {
+  if (logLevel === "debug") {
+    return {
+      entries: [...result.entries],
+      firstSequence: result.firstSequence,
+      lastSequence: result.lastSequence,
+      truncated: result.truncated,
+      hasMore: result.hasMore,
+      nextCursor: result.nextCursor ?? null
+    };
+  }
+  const first = result.firstSequence;
+  if (result.entries.length > 0 && (first === null || result.lastSequence === null || result.lastSequence - first + 1 !== result.entries.length)) {
+    throw new Error(
+      `Run log window is not contiguous (sequences ${first}..${result.lastSequence} for ${result.entries.length} lines); cannot page by severity.`
+    );
+  }
+  const matching = result.entries.map((line, index) => ({ line, seq: first + index })).filter(
+    (entry) => logLevelReaches(classifyLogLine(entry.line).level, logLevel)
+  );
+  const selected = matching.slice(-limit);
+  const olderMatchesExist = matching.length > selected.length;
+  return {
+    entries: selected.map((entry) => entry.line),
+    firstSequence: selected[0]?.seq ?? null,
+    lastSequence: selected.at(-1)?.seq ?? null,
+    truncated: result.truncated || olderMatchesExist,
+    hasMore: olderMatchesExist,
+    nextCursor: olderMatchesExist ? encodeRunLogsCursor(selected[0].seq) : null
+  };
+}
 async function handleRunEventSearch(args) {
   const usage2 = "Usage: deepline runs logs [run-id] [--since ISO] [--until ISO] [--play name] [--kind kind] [--where jsonpath] [--payloads] [--cursor token] [--limit 100] [--json]";
   const values = {};
@@ -34821,6 +34931,14 @@ function buildRunLogsText(result) {
   }
   return `${lines.join("\n")}${lines.length > 0 ? "\n" : ""}`;
 }
+function resolveRunStopState(result) {
+  if (result.state) return result.state;
+  if (result.cancelling === true) return "cancelling";
+  if (result.stopped === false || result.staleSchedulerState === true) {
+    return "failed";
+  }
+  return "stopped";
+}
 async function handleRunStop(args) {
   const usage2 = 'Usage: deepline runs stop <run-id> [--reason "text"] [--json]';
   let runId;
@@ -34839,15 +34957,25 @@ async function handleRunStop(args) {
   }
   const client2 = new DeeplineClient();
   const result = await client2.runs.stop(runId, { reason });
-  if (result.cancelling === true && result.hitlCancellationPending !== true) {
+  const state = resolveRunStopState(result);
+  const hitlCleanupIncomplete = state === "cancelling" && result.hitlCancellationPending === true;
+  if (state === "cancelling" && !hitlCleanupIncomplete) {
+    const {
+      error: _legacyError,
+      staleSchedulerState: _legacyStale,
+      ...cancelling
+    } = result;
     const lines2 = [
-      `Cancellation queued for ${result.runId || runId}; sandbox cleanup is pending`,
+      `Cancelling run ${result.runId || runId}; sandbox cleanup and the final run update are pending.`,
       ...result.hitlCancelledCount > 0 ? [`cancelled HITL waits: ${result.hitlCancelledCount}`] : [],
       `inspect: deepline runs get ${runId} --full --json`
     ];
     printCommandEnvelope(
       {
-        ...result,
+        ...cancelling,
+        state,
+        stopped: false,
+        cancelling: true,
         render: {
           sections: [
             {
@@ -34861,9 +34989,8 @@ async function handleRunStop(args) {
     );
     return 0;
   }
-  const stopNotConfirmed = result.stopped === false || result.staleSchedulerState === true;
-  if (stopNotConfirmed) {
-    const detail = typeof result.error === "string" && result.error.trim() ? result.error.trim() : result.staleSchedulerState === true ? "scheduler state for the run is stale" : "the server did not confirm the stop";
+  if (state === "failed" || hitlCleanupIncomplete) {
+    const detail = typeof result.error === "string" && result.error.trim() ? result.error.trim() : hitlCleanupIncomplete ? "cancellation is queued, but HITL cleanup is still pending" : result.staleSchedulerState === true ? "scheduler state for the run is stale" : "the server did not confirm the stop";
     const lines2 = [
       `Failed to stop run ${runId}: ${detail}.`,
       ...result.hitlCancelledCount > 0 ? [`cancelled HITL waits: ${result.hitlCancelledCount}`] : [],
@@ -36884,15 +37011,15 @@ Examples:
       ...options.json ? ["--json"] : []
     ]);
   });
-  const runs = program.command("runs").description("Inspect, tail, stop, and export play runs.").addHelpText(
+  const runs = program.command("runs").description("Inspect, watch, stop, and export play runs.").addHelpText(
     "after",
     `
 Concepts:
   A run is one execution instance of a play. It has status, progress, logs,
   returned result, dataset previews, recovery metadata, and optional dataset export.
   plays run starts NEW work and follows it by default; --no-wait returns immediately.
-  runs tail attaches to EXISTING work and follows progress without starting a run.
-  Use tail after a disconnect or --no-wait; do not launch again to reconnect.
+  runs watch attaches to EXISTING work and follows progress without starting a run.
+  Use watch after a disconnect or --no-wait; do not launch again to reconnect.
   get reads the current overview once. logs fetches persisted log history.
   stop requests cancellation. rerun starts new work and may spend credits.
 
@@ -36906,14 +37033,15 @@ Retrieve results:
   not JSON rows. For a JSON row file, use --format json --out results.json.
 
 Follow existing work:
-  deepline runs tail <run-id>
-  tail --json waits for one terminal JSON document; --jsonl streams live events.
-  There is no runs watch command; tail is the live-follow command.
+  deepline runs watch <run-id>
+  watch --json waits for one terminal JSON document; --jsonl streams live events.
+  runs tail is an alias of runs watch.
 
 More options:
   deepline runs get -h
   deepline runs children -h
   deepline runs tail -h
+  deepline runs watch -h
   deepline runs export -h
   deepline plays -h
 
@@ -36960,6 +37088,7 @@ Notes:
   Run activity and status evidence retain provider cooldown and call progress.
   Use --input only when you intentionally need the original payload; it can
   contain customer data and is never included in ordinary status output.
+  --config reads only the recorded graph and source; it never uses current Play code.
   --json run.status,datasets.name,actions selects fields without flattening.
   Selection changes stdout only, not the server query. Optional missing paths
   are omitted; array positions are preserved. --json diagnostics needs --full.
@@ -36971,6 +37100,7 @@ Examples:
   deepline runs get play/my-play/run/20260501t000000-000 --log-failed --json
   deepline runs get play/my-play/run/20260501t000000-000 --full --json
   deepline runs get play/my-play/run/20260501t000000-000 --input
+  deepline runs get play/my-play/run/20260501t000000-000 --config --json
 `
   ).option(
     "--json [fields]",
@@ -36981,6 +37111,9 @@ Examples:
   ).option(
     "--input",
     "Explicitly print the original retained input JSON (may contain customer data)"
+  ).option(
+    "--config",
+    "Explicitly print the recorded configuration, without full results"
   ).option(
     "--log-failed",
     "Attach a bounded terminal-failure log window for failed runs"
@@ -36990,6 +37123,7 @@ Examples:
       ...jsonFieldArgs(options.json),
       ...options.full ? ["--full"] : [],
       ...options.input ? ["--input"] : [],
+      ...options.config ? ["--config"] : [],
       ...options.logFailed ? ["--log-failed"] : []
     ]);
   });
@@ -37130,15 +37264,7 @@ Examples:
       ...options.logLevel ? ["--log-level", options.logLevel] : []
     ]);
   });
-  runs.command("logs [runId]").description(
-    "Fetch one run\u2019s logs or search recent runtime events across runs."
-  ).addHelpText("after", renderRunLogsHelp()).option(
-    "--limit <count>",
-    "Text tail: default 200; search: default 100, max 200 (10 with --payloads)"
-  ).option("--out <path>", "Write the full retained log stream to a file").option("--failed", "Show the bounded terminal-failure log window").option(
-    "--log-level <level>",
-    "Minimum severity: debug (default), info, warn, or error"
-  ).addOption(
+  runs.command("logs [runId]").description("Read a run\u2019s logs or search recent events.").addHelpText("after", renderRunLogsHelp()).option("--limit <count>", "Maximum results: logs 200; events 100, max 200").option("--out <path>", "Save the full available text log").option("--failed", "Last 20 lines of a failed run").option("--log-level <level>", "debug (default), info, warn or error").addOption(
     new Option3(
       "--logs",
       "Compatibility alias for --log-level debug"
@@ -37148,19 +37274,20 @@ Examples:
       "--debug",
       "Compatibility alias for --log-level debug"
     ).hideHelp()
-  ).option("--json", "Emit JSON output. Also automatic when stdout is piped").option("--since <timestamp>", "Search events since this UTC timestamp").option("--until <timestamp>", "Search events before this UTC timestamp").option("--play <name>", "Filter events by Play name").option(
-    "--kind <kind>",
-    "Search one exact event kind; complete catalog below"
-  ).option(
-    "--where <jsonpath>",
-    "Search indexed fields with == and &&; field types and availability below"
-  ).option(
-    "--payloads",
-    "Search with canonical eventPayload or receipt payload; max 10 events, 16 MiB"
-  ).option("--cursor <token>", "Continue a bounded event search").option(
-    "--runtime-namespace <name>",
-    "Search an explicitly authorized Preview namespace"
-  ).option("--runtime-backend <backend>", "Preview backend: daytona or modal").action(async (runId, options) => {
+  ).option("--json", "JSON output; automatic when piped").option("--since <timestamp>", "Search from this UTC time").option("--until <timestamp>", "Search before this UTC time").option("--play <name>", "Filter by Play").option("--kind <kind>", "Filter by event kind").option("--where <filter>", "Match event fields; examples below").option("--payloads", "Include available details or saved results").option(
+    "--cursor <token>",
+    "Continue to older logs or the next events page"
+  ).addOption(
+    new Option3(
+      "--runtime-namespace <name>",
+      "Search an explicitly authorized Preview namespace"
+    ).hideHelp()
+  ).addOption(
+    new Option3(
+      "--runtime-backend <backend>",
+      "Preview backend: daytona or modal"
+    ).hideHelp()
+  ).action(async (runId, options) => {
     process.exitCode = await handleRunLogs([
       ...runId ? [runId] : [],
       ...options.limit ? ["--limit", options.limit] : [],