deepline 0.3.307 → 0.3.308

package/dist/cli/{play-2YXLQD24.mjs → play-2JTIEOZM.mjs}

@@ -1,13 +1,13 @@
 import {
   handleDeploymentGet,
   handleDeploymentsList
-} from "./chunk-ILOCS73R.mjs";
+} from "./chunk-XFYVL7EM.mjs";
 import {
   parseCsvDataInput
 } from "./chunk-EDWJY6T4.mjs";
 import {
   registerDeprecatedSearchCommand
-} from "./chunk-BDFVIOLY.mjs";
+} from "./chunk-XSDL3NHZ.mjs";
 import {
   PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY,
   PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER,
@@ -20,15 +20,17 @@ import {
   CSV_HEADER_MATCHING_NOTE,
   DeeplineClient,
   RUN_EVENT_SEARCH_KIND_VALUES,
+  RunEventQueryInputError,
   classifyLogLine,
   encodeRunLogsCursor,
   isRunLogsCursor,
   isTransientPlayRunReadError,
   logLevelReaches,
   logProvenanceReaches,
+  normalizeRunEventOperationRequest,
   parseLogLevel,
   playInputExampleArgs
-} from "./chunk-TLTKAJ6S.mjs";
+} from "./chunk-HGI6RGHB.mjs";
 import {
   CSV_DATA_INPUT_KEY,
   buildNamedPlayRunRequest,
@@ -58,13 +60,14 @@ import {
   printCommandEnvelope,
   printCompactJson,
   printJson,
+  printJsonError,
   renderCommandEnvelopeText
-} from "./chunk-D55NIPGU.mjs";
+} from "./chunk-ABMGEW3C.mjs";
 import {
   fetchWithDeploymentProtection
-} from "./chunk-MPVXXDWH.mjs";
+} from "./chunk-T3P4NRZU.mjs";
 import "./chunk-DLIRSHV6.mjs";
-import "./chunk-QACDLYNO.mjs";
+import "./chunk-YSZSERRZ.mjs";
 import {
   PLAY_DEFAULT_EXPORT,
   extractDefinedPlayName,
@@ -2711,6 +2714,8 @@ function renderRunLogsHelp() {
     "",
     "Examples:",
     `  ${READ_EXAMPLES[0]}`,
+    "  deepline runs logs '<run-id>' --step company-lookup --level warn --since 1h",
+    "  deepline runs logs '<run-id>' --query timeout --count --json",
     `  deepline runs logs --where '$.eventId == "receipt:5a32ee1a-46cf-4853-b72b-5f1d782ffab4"' --payloads --json`,
     "  deepline runs logs --kind run.failed --json",
     ...[
@@ -2731,20 +2736,408 @@ function renderRunLogsHelp() {
       "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)),
+    "  With --step/--level/--query, filters also support ranges, ||, in and exists.",
+    "  --count is exact; --group-by pages groups; --sum totals numeric fields.",
+    "  Use --fields for available fields. Use runs events for lifecycle events.",
     "",
     "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.",
-      "To read one exact saved result, filter by its returned eventId and add --payloads.",
-      "--out, --failed and --log-level apply to text logs and cannot be combined with event search."
+      "Defaults to the last hour; maximum lookback is seven days.",
+      "Follow next.page for log queries, next.logs for compatibility event search.",
+      "Text logs use nextCursor with --cursor. --payloads: 10 events and 16 MiB.",
+      "Find an exact saved result by returned eventId and add --payloads.",
+      "--out, --failed and --log-level cannot be combined with event search."
     ].map((note) => wrapParagraph(note)),
     "",
     "More examples: https://deepline.com/docs/sdk-v2/run-events"
   ].join("\n");
 }
 
+// src/cli/run-event-query.ts
+import { Option } from "commander";
+var STRUCTURED_LOG_FLAGS = /* @__PURE__ */ new Set([
+  "--step",
+  "--level",
+  "--query",
+  "--count",
+  "--group-by",
+  "--sum",
+  "--fields"
+]);
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--since",
+  "--until",
+  "--play",
+  "--kind",
+  "--where",
+  "--step",
+  "--level",
+  "--query",
+  "--limit",
+  "--cursor",
+  "--group-by",
+  "--sum",
+  "--runtime-namespace",
+  "--runtime-backend"
+]);
+var SWITCH_FLAGS = /* @__PURE__ */ new Set(["--json", "--count", "--payloads", "--fields"]);
+function requestsStructuredLogs(args) {
+  return args.some((arg) => STRUCTURED_LOG_FLAGS.has(arg.split("=", 1)[0]));
+}
+function configureRunQueryCommandErrors(command, resource) {
+  command.exitOverride((error) => {
+    let program = command;
+    while (program.parent) program = program.parent;
+    const args = program.args;
+    if (error.exitCode !== 0 && (resource === "events" || requestsStructuredLogs(args))) {
+      error.exitCode = 2;
+      if (argsWantJson(args) || command.optsWithGlobals().json === true) {
+        printJsonError(
+          Object.assign(new RunEventQueryInputError(error.message), {
+            exitCode: 2,
+            retryable: false
+          })
+        );
+      }
+    }
+    throw error;
+  });
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function terminalText(value) {
+  return value.replace(
+    /[\u0000-\u001f\u007f-\u009f]/g,
+    (control) => `\\x${control.codePointAt(0).toString(16).padStart(2, "0")}`
+  );
+}
+function renderEvent(event, resource) {
+  const context = event.context === void 0 ? "" : ` ${JSON.stringify(event.context)}`;
+  const identity = resource === "logs" ? `${event.level ?? "unknown"}${event.stepId ? ` [${event.stepId}]` : ""}` : `${event.kind} ${event.runId}${event.stepId ? ` [${event.stepId}]` : ""}`;
+  const message = event.message ?? "";
+  const details = [
+    event.eventPayload === void 0 ? "" : `event: ${JSON.stringify(event.eventPayload)}`,
+    event.payload === void 0 ? "" : `payload: ${JSON.stringify(event.payload)}`
+  ].filter(Boolean);
+  return [
+    terminalText(`${event.occurredAt} ${identity} ${message}${context}`),
+    ...details.map(terminalText)
+  ].join("\n");
+}
+function parseQuery(args, resource) {
+  const values = {};
+  const switches = /* @__PURE__ */ new Set();
+  const sums = [];
+  let runId;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const equals = arg.indexOf("=");
+    const flag = equals > 0 ? arg.slice(0, equals) : arg;
+    if (VALUE_FLAGS.has(flag)) {
+      const value = equals > 0 ? arg.slice(equals + 1) : args[++index];
+      if (!value || equals < 0 && value.startsWith("--") && flag !== "--query" && flag !== "--where") {
+        throw new RunEventQueryInputError(
+          `${flag} requires a value. Use ${flag} <value>.`
+        );
+      }
+      if (flag === "--sum") sums.push(value);
+      else {
+        if (values[flag] !== void 0) {
+          throw new RunEventQueryInputError(
+            `${flag} may only be supplied once.`
+          );
+        }
+        values[flag] = value;
+      }
+      continue;
+    }
+    if (SWITCH_FLAGS.has(flag) && equals < 0) {
+      switches.add(flag);
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      const correction = flag === "--log-level" ? "Use --level for structured severity filtering." : flag === "--out" || flag === "--failed" || flag === "--all" ? "Use this flag with a plain runs logs <run-id> text read." : "Use --step, --level, --query, --where, --count, --group-by or --fields; see runs logs --help.";
+      throw new RunEventQueryInputError(
+        `Unsupported query flag ${flag}. ${correction}`
+      );
+    }
+    if (runId !== void 0) {
+      throw new RunEventQueryInputError(
+        `Unexpected argument ${JSON.stringify(arg)}. Supply one run ID.`
+      );
+    }
+    runId = arg;
+  }
+  if (switches.has("--fields")) {
+    if (runId !== void 0) {
+      throw new RunEventQueryInputError(
+        "--fields does not use a run ID. Omit the positional run ID."
+      );
+    }
+    const incompatible = [
+      ...switches.has("--count") ? ["--count"] : [],
+      ...switches.has("--payloads") ? ["--payloads"] : [],
+      ...sums.length ? ["--sum"] : [],
+      ...Object.keys(values).filter(
+        (flag) => flag !== "--runtime-namespace" && flag !== "--runtime-backend"
+      )
+    ];
+    if (incompatible.length) {
+      throw new RunEventQueryInputError(
+        `--fields cannot be combined with ${incompatible.join(", ")}. Use --fields alone to discover the query contract.`
+      );
+    }
+  }
+  if (switches.has("--count") && values["--group-by"] !== void 0) {
+    throw new RunEventQueryInputError(
+      "--count cannot be combined with --group-by. Use --group-by for counts per group."
+    );
+  }
+  if (sums.length && switches.has("--count")) {
+    throw new RunEventQueryInputError(
+      "--sum cannot be combined with --count. Use --sum for the exact count and numeric total."
+    );
+  }
+  const operation = switches.has("--fields") ? "fields" : switches.has("--count") ? "count" : values["--group-by"] !== void 0 || sums.length > 0 ? "summarize" : "list";
+  if (operation === "count") {
+    for (const flag of ["--limit", "--cursor", "--payloads"]) {
+      if (values[flag] !== void 0 || switches.has(flag)) {
+        throw new RunEventQueryInputError(
+          `--count cannot be combined with ${flag}. Remove ${flag} to count all matching retained records.`
+        );
+      }
+    }
+  }
+  const body = {
+    operation,
+    resource,
+    ...runId === void 0 ? {} : { runId }
+  };
+  for (const [flag, key] of [
+    ["--since", "since"],
+    ["--until", "until"],
+    ["--play", "playName"],
+    ["--kind", "kind"],
+    ["--where", "where"],
+    ["--step", "stepId"],
+    ["--level", "minLevel"],
+    ["--query", "text"],
+    ["--cursor", "cursor"]
+  ]) {
+    if (values[flag] !== void 0) body[key] = values[flag];
+  }
+  if (values["--limit"] !== void 0) body.limit = Number(values["--limit"]);
+  if (switches.has("--payloads")) body.includePayloads = true;
+  if (operation === "summarize") {
+    body.groupBy = values["--group-by"] === void 0 ? [] : values["--group-by"].split(",").map((field) => field.trim());
+    if (sums.length) {
+      body.measures = [
+        { op: "count" },
+        ...sums.map((field) => ({ op: "sum", field }))
+      ];
+    }
+  }
+  const request = normalizeRunEventOperationRequest(body);
+  const namespace = values["--runtime-namespace"] ?? (process.env.DEEPLINE_RUNTIME_ENVIRONMENT === "preview" ? process.env.DEEPLINE_RUNTIME_NAMESPACE : void 0);
+  const backend = values["--runtime-backend"];
+  if (backend && backend !== "daytona" && backend !== "modal") {
+    throw new RunEventQueryInputError(
+      "--runtime-backend must be daytona or modal."
+    );
+  }
+  if (backend && !namespace) {
+    throw new RunEventQueryInputError(
+      "--runtime-backend requires --runtime-namespace."
+    );
+  }
+  return {
+    request,
+    values,
+    sums,
+    ...namespace ? {
+      runtime: {
+        environment: "preview",
+        namespace,
+        ...backend ? { backend } : {}
+      }
+    } : {}
+  };
+}
+function continuation(parsed, query, cursor) {
+  const { request, values, sums, runtime } = parsed;
+  return [
+    `deepline runs ${request.resource}`,
+    ...request.runId ? [shellQuote(request.runId)] : [],
+    "--since",
+    shellQuote(String(query.since)),
+    "--until",
+    shellQuote(String(query.until)),
+    ...["--play", "--kind", "--where", "--step", "--level", "--query"].flatMap(
+      (flag) => values[flag] === void 0 ? [] : [flag, shellQuote(values[flag])]
+    ),
+    ...request.operation === "summarize" && values["--group-by"] !== void 0 ? ["--group-by", shellQuote(values["--group-by"])] : [],
+    ...sums.flatMap((field) => ["--sum", shellQuote(field)]),
+    ...request.operation === "list" && request.includePayloads ? ["--payloads"] : [],
+    ...runtime ? ["--runtime-namespace", shellQuote(runtime.namespace)] : [],
+    ...runtime?.backend ? ["--runtime-backend", shellQuote(runtime.backend)] : [],
+    "--limit",
+    String("limit" in request ? request.limit : ""),
+    "--cursor",
+    shellQuote(cursor),
+    "--json"
+  ].join(" ");
+}
+async function handleRunEventQuery(args, resource = "logs") {
+  try {
+    return await executeRunEventQuery(args, resource);
+  } catch (error) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    const record3 = failure;
+    const status = record3.statusCode;
+    const exitCode = error instanceof RunEventQueryInputError || status === 400 || status === 422 || record3.code === "INVALID_RUNTIME_SELECTION" ? 2 : status === 401 || status === 403 || record3.code === "CONFIG_ERROR" || record3.code === "RUNTIME_ENVIRONMENT_TOKEN_REQUIRED" ? 3 : status === 404 ? 4 : 5;
+    const diagnostic = Object.assign(failure, {
+      exitCode,
+      retryable: exitCode === 5
+    });
+    if (argsWantJson(args)) printJsonError(diagnostic);
+    else console.error(`Error: ${diagnostic.message}`);
+    return exitCode;
+  }
+}
+async function executeRunEventQuery(args, resource) {
+  const parsed = parseQuery(args, resource);
+  const { request, runtime } = parsed;
+  const {
+    operation: _operation,
+    resource: _resource,
+    runId,
+    ...criteria
+  } = request;
+  const options = { ...criteria, ...runtime ? { runtime } : {} };
+  const client = new DeeplineClient();
+  let result;
+  if (request.operation === "fields") {
+    result = await client.runs[resource].fields(runtime ? { runtime } : {});
+  } else if (request.operation === "count") {
+    result = resource === "logs" ? await client.runs.logs.count(runId, options) : await client.runs.events.count({
+      ...options,
+      ...runId ? { runId } : {}
+    });
+  } else if (request.operation === "summarize") {
+    const summary = {
+      ...options,
+      groupBy: request.groupBy,
+      measures: request.measures,
+      limit: request.limit,
+      cursor: request.cursor
+    };
+    result = resource === "logs" ? await client.runs.logs.summarize(runId, summary) : await client.runs.events.summarize({
+      ...summary,
+      ...runId ? { runId } : {}
+    });
+  } else {
+    result = resource === "logs" ? await client.runs.logs.query(runId, options) : await client.runs.events.list({
+      ...options,
+      ...runId ? { runId } : {}
+    });
+  }
+  let lines;
+  let nextPage;
+  if ("fields" in result) {
+    lines = [
+      ...result.fields.map(
+        (field) => `${field.field} (${field.type}${field.nullable ? ", optional" : ""}): ${field.operators.join(", ")}${field.summable ? "; sum" : ""}`
+      ),
+      `${result.context.field} (${result.context.type}): ${result.context.operators.join(", ")}; sum numeric values`,
+      "Missing fields are distinct from null. Only recorded values match."
+    ];
+  } else {
+    if ("matchedCount" in result) {
+      lines = [`${result.matchedCount} matching retained ${resource} (exact).`];
+    } else if ("groups" in result) {
+      lines = result.groups.map(
+        (group) => [
+          ...Object.entries(group.keys).map(
+            ([field, value]) => `${field}=${typeof value === "object" && value !== null && "missing" in value ? "<missing>" : JSON.stringify(value)}`
+          ),
+          ...Object.entries(group.measures).map(
+            ([name, value]) => `${name}=${value}`
+          )
+        ].join(" ")
+      );
+      if (lines.length === 0) lines.push("0 matching retained groups.");
+    } else {
+      const entries = "logs" in result ? result.logs : result.events;
+      lines = entries.map((event) => renderEvent(event, resource));
+      if (lines.length === 0) lines.push(`0 matching retained ${resource}.`);
+    }
+    lines.push(
+      `Retained history since ${result.retention.retainedSince} (${result.retention.retentionDays} days).`
+    );
+    if ("page" in result && result.page.nextCursor) {
+      nextPage = continuation(parsed, result.query, result.page.nextCursor);
+      lines.push(`Next page: ${nextPage}`);
+    }
+  }
+  printCommandEnvelope(
+    {
+      ...result,
+      ...nextPage ? { next: { page: nextPage } } : {},
+      render: { sections: [{ title: `run ${resource}`, lines }] }
+    },
+    { json: argsWantJson(args), text: `${lines.join("\n")}
+` }
+  );
+  return 0;
+}
+function registerRunEventsCommand(runs) {
+  const command = runs.command("events [runId]").description("Query, count or summarize retained run events.").option("--since <time>", "Inclusive UTC time or lookback such as 1h").option("--until <time>", "Exclusive UTC time").option("--play <name>", "Exact Play name").option("--kind <kind>", "Exact event kind").option("--where <filter>", "Typed comparisons with &&, || and parentheses").option("--step <id>", "Exact authored step ID").option("--level <level>", "Minimum severity: debug, info, warn or error").option("--query <text>", "Literal text in the full retained log message").option("--count", "Exact retained count; no limit, cursor or payloads").option("--group-by <fields>", "Count groups by comma-separated fields").option(
+    "--sum <field>",
+    "Count and sum numeric values; repeatable, optionally grouped",
+    (field, previous) => [...previous, field],
+    []
+  ).option("--fields", "Discover filter fields, types and operators").option("--limit <count>", "Rows or groups per page (maximum 200)").option("--cursor <token>", "Continue the exact preceding query").option("--payloads", "Include saved details: at most 10 events and 16 MiB").option("--json", "JSON output; automatic when piped").addOption(
+    new Option(
+      "--runtime-namespace <name>",
+      "Authorized Preview namespace"
+    ).hideHelp()
+  ).addOption(
+    new Option(
+      "--runtime-backend <backend>",
+      "Preview backend: daytona or modal"
+    ).hideHelp()
+  ).addHelpText(
+    "after",
+    "\nExamples:\n  deepline runs events --kind step.failed --since 1h --json\n  deepline runs events --group-by kind --since 1h --json\n  deepline runs events --fields --json\n"
+  ).action(async (runId, options) => {
+    const args = runId ? [runId] : [];
+    for (const [key, flag] of [
+      ["since", "--since"],
+      ["until", "--until"],
+      ["play", "--play"],
+      ["kind", "--kind"],
+      ["where", "--where"],
+      ["step", "--step"],
+      ["level", "--level"],
+      ["query", "--query"],
+      ["groupBy", "--group-by"],
+      ["limit", "--limit"],
+      ["cursor", "--cursor"],
+      ["runtimeNamespace", "--runtime-namespace"],
+      ["runtimeBackend", "--runtime-backend"]
+    ]) {
+      if (options[key] !== void 0) args.push(flag, options[key]);
+    }
+    for (const field of options.sum ?? []) args.push("--sum", field);
+    for (const flag of ["count", "fields", "payloads", "json"]) {
+      if (options[flag]) args.push(`--${flag}`);
+    }
+    process.exitCode = await handleRunEventQuery(args, "events");
+  });
+  configureRunQueryCommandErrors(command, "events");
+}
+
 // ../play-runtime/run-execution-state.ts
 function assertNeverState(value, what) {
   throw new Error(`Unhandled ${what}: ${JSON.stringify(value)}`);
@@ -3570,7 +3963,7 @@ import {
   relative as relative3,
   resolve as resolve5
 } from "path";
-import { Option } from "commander";
+import { Option as Option2 } from "commander";
 
 // src/cli/commands/plays/bootstrap.ts
 import {
@@ -5317,7 +5710,7 @@ Existing credential redactions and referenced-list previews remain as stored.
 }
 
 // src/cli/commands/run-children.ts
-function shellQuote(value) {
+function shellQuote2(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function registerRunChildrenCommand(runs) {
@@ -5352,11 +5745,11 @@ includes nextCommand when another page is available.
       });
       const nextCommand = page.hasMore && page.nextCursor ? [
         "deepline runs children",
-        shellQuote(parentRunId),
+        shellQuote2(parentRunId),
         "--launch-key",
-        shellQuote(options.launchKey),
+        shellQuote2(options.launchKey),
         "--cursor",
-        shellQuote(page.nextCursor),
+        shellQuote2(page.nextCursor),
         "--limit",
         String(limit),
         "--json"
@@ -8944,7 +9337,7 @@ function rankPlayReferenceSuggestions(input) {
 function searchQueryForMissingPlayReference(target) {
   return parseReferencedPlayTarget2(target).unqualifiedPlayName.replace(/[-_./]+/g, " ").replace(/\s+/g, " ").trim();
 }
-function shellQuote2(value) {
+function shellQuote3(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function buildPlayReferenceNotFoundMessage(input) {
@@ -8977,7 +9370,7 @@ function buildPlayReferenceNotFoundMessage(input) {
     lines.push(
       "",
       "Search visible plays:",
-      `  deepline search --type plays ${shellQuote2(searchQuery)} --json`
+      `  deepline search --type plays ${shellQuote3(searchQuery)} --json`
     );
   }
   return lines.join("\n");
@@ -13940,7 +14333,7 @@ async function handlePlayCheck(args) {
         runtimeLimit: play.runtimeLimit ?? null,
         activeScheduledPlays: play.activeScheduledPlays ?? null,
         actions: {
-          getFullCheckCmd: `deepline plays check ${shellQuote2(options.target)} --full --json`,
+          getFullCheckCmd: `deepline plays check ${shellQuote3(options.target)} --full --json`,
           ...play.runCommand ? { runCmd: play.runCommand } : {}
         },
         ...options.full ? { diagnostics: { staticPipeline: play.staticPipeline ?? null } } : {}
@@ -13994,8 +14387,8 @@ async function handlePlayCheck(args) {
     outcomes,
     target: options.target,
     full: options.full,
-    detailsCommand: `deepline plays check ${shellQuote2(options.target)} --full --json`,
-    publishCommand: primary?.result.artifactHash ? `deepline plays publish ${shellQuote2(options.target)} --expected-artifact ${primary.result.artifactHash}` : void 0
+    detailsCommand: `deepline plays check ${shellQuote3(options.target)} --full --json`,
+    publishCommand: primary?.result.artifactHash ? `deepline plays publish ${shellQuote3(options.target)} --expected-artifact ${primary.result.artifactHash}` : void 0
   });
   printCommandEnvelope(output, {
     json: options.jsonOutput,
@@ -15083,7 +15476,7 @@ Active runs: ${next.running}`
     return lines2.join("\n");
   });
   const nextOffset = (page.offset ?? offset ?? 0) + runs.length;
-  const nextPage = page.hasMore && playName ? `deepline runs list --play ${shellQuote2(playName)}${statusFilter ? ` --status ${shellQuote2(statusFilter)}` : ""} --limit ${page.limit ?? limit ?? 20} --offset ${nextOffset} --json` : null;
+  const nextPage = page.hasMore && playName ? `deepline runs list --play ${shellQuote3(playName)}${statusFilter ? ` --status ${shellQuote3(statusFilter)}` : ""} --limit ${page.limit ?? limit ?? 20} --offset ${nextOffset} --json` : null;
   if (page.hasMore) {
     lines.push("List truncated \u2014 more runs match this filter.");
     lines.push(
@@ -15242,6 +15635,7 @@ async function handleRunTail(args) {
   return status.status === "failed" ? 1 : 0;
 }
 async function handleRunLogs(args) {
+  if (requestsStructuredLogs(args)) return handleRunEventQuery(args, "logs");
   const searchFlags = /* @__PURE__ */ new Set([
     "--since",
     "--until",
@@ -15575,19 +15969,19 @@ ${renderedDetails}` : ""}`;
   });
   const nextCommand = result.nextCursor ? [
     "deepline runs logs",
-    ...runId ? [shellQuote2(runId)] : [],
+    ...runId ? [shellQuote3(runId)] : [],
     "--since",
-    shellQuote2(result.since),
+    shellQuote3(result.since),
     "--until",
-    shellQuote2(result.until),
-    ...values["--play"] ? ["--play", shellQuote2(values["--play"])] : [],
-    ...values["--kind"] ? ["--kind", shellQuote2(values["--kind"])] : [],
-    ...values["--where"] ? ["--where", shellQuote2(values["--where"])] : [],
+    shellQuote3(result.until),
+    ...values["--play"] ? ["--play", shellQuote3(values["--play"])] : [],
+    ...values["--kind"] ? ["--kind", shellQuote3(values["--kind"])] : [],
+    ...values["--where"] ? ["--where", shellQuote3(values["--where"])] : [],
     ...includePayloads ? ["--payloads"] : [],
-    ...namespace ? ["--runtime-namespace", shellQuote2(namespace)] : [],
-    ...backend ? ["--runtime-backend", shellQuote2(backend)] : [],
+    ...namespace ? ["--runtime-namespace", shellQuote3(namespace)] : [],
+    ...backend ? ["--runtime-backend", shellQuote3(backend)] : [],
     "--cursor",
-    shellQuote2(result.nextCursor),
+    shellQuote3(result.nextCursor),
     "--limit",
     String(limit),
     "--json"
@@ -16230,7 +16624,7 @@ async function handlePlayList(args) {
     );
     return 1;
   }
-  const nextPage = page.hasMore && page.cursor ? `deepline plays list${categories ? ` --categories ${shellQuote2(categories)}` : ""}${tags.map((tag) => ` --tag ${shellQuote2(tag)}`).join("")}${limit ? ` --limit ${limit}` : ""}${showCost ? " --show-cost" : ""} --cursor ${shellQuote2(page.cursor)} --json` : null;
+  const nextPage = page.hasMore && page.cursor ? `deepline plays list${categories ? ` --categories ${shellQuote3(categories)}` : ""}${tags.map((tag) => ` --tag ${shellQuote3(tag)}`).join("")}${limit ? ` --limit ${limit}` : ""}${showCost ? " --show-cost" : ""} --cursor ${shellQuote3(page.cursor)} --json` : null;
   if (page.hasMore && !nextPage) {
     throw new Error(
       "Play list reported more results without a continuation cursor"
@@ -16578,7 +16972,7 @@ async function handlePlaySave(args) {
       message: "Refusing to save: the local file no longer produces the artifact checked earlier.",
       expectedArtifactHash: options.expectedArtifactHash,
       currentArtifactHash: artifactHash,
-      next: `deepline plays check ${shellQuote2(options.target)}`
+      next: `deepline plays check ${shellQuote3(options.target)}`
     };
     if (options.jsonOutput) {
       printCompactJson(result);
@@ -16643,7 +17037,7 @@ async function handlePlaySave(args) {
       graphHash: graph.root.artifact.graphHash,
       artifactStorageKey: saved.artifactStorageKey,
       next: {
-        publish: `deepline plays publish ${shellQuote2(options.target)} --expected-artifact ${artifactHash}`,
+        publish: `deepline plays publish ${shellQuote3(options.target)} --expected-artifact ${artifactHash}`,
         get: `deepline plays get ${playName} --source --out ./${playName}/ --working`
       }
     };
@@ -16703,7 +17097,7 @@ async function handlePlayPublish(args) {
         message: "Refusing to publish: the local file no longer produces the artifact checked earlier.",
         expectedArtifactHash: options.expectedArtifactHash,
         currentArtifactHash: artifactHash,
-        next: `deepline plays check ${shellQuote2(playName)}`
+        next: `deepline plays check ${shellQuote3(playName)}`
       };
       if (options.jsonOutput) {
         printCompactJson(result3);
@@ -17173,12 +17567,12 @@ Examples:
     "--fixture-behavior <json>",
     "Internal/testing: fixture response behavior JSON object or @file path"
   ).addOption(
-    new Option(
+    new Option2(
       "--watch",
       "Compatibility alias; run waits by default"
     ).hideHelp()
   ).addOption(
-    new Option(
+    new Option2(
       "--wait",
       "Compatibility alias; run waits by default"
     ).hideHelp()
@@ -17186,12 +17580,12 @@ Examples:
     "--run-id-file <path>",
     "Atomically write the accepted run id to a new JSON file"
   ).addOption(
-    new Option(
+    new Option2(
       "--logs",
       "Compatibility alias for --log-level debug"
     ).hideHelp()
   ).addOption(
-    new Option(
+    new Option2(
       "--debug [value]",
       "Compatibility alias for --log-level debug when bare; --debug <value> remains legacy Play input.debug"
     ).hideHelp()
@@ -17694,6 +18088,7 @@ Examples:
   registerRunReceiptCommand(runs);
   registerRunChildrenCommand(runs);
   registerRunHistoryCommand(runs);
+  registerRunEventsCommand(runs);
   runs.command("status <runId>").description(
     "Legacy scalar-only read. Use runs get for canonical status, progress, logs, and results."
   ).option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (runId, options) => {
@@ -17745,7 +18140,7 @@ Examples:
     "--config",
     "Explicitly print the recorded configuration, without full results"
   ).addOption(
-    new Option("--log-failed", "Attach terminal-failure logs").hideHelp()
+    new Option2("--log-failed", "Attach terminal-failure logs").hideHelp()
   ).action(async (runId, options) => {
     process.exitCode = await handleRunGet([
       runId,
@@ -17870,12 +18265,12 @@ Examples:
     "--compact",
     "Show deduplicated human step transitions and progress"
   ).addOption(
-    new Option(
+    new Option2(
       "--logs",
       "Compatibility alias for --log-level debug"
     ).hideHelp()
   ).addOption(
-    new Option(
+    new Option2(
       "--debug",
       "Compatibility alias for --log-level debug"
     ).hideHelp()
@@ -17893,13 +18288,27 @@ Examples:
       ...options.logLevel ? ["--log-level", options.logLevel] : []
     ]);
   });
-  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 Option(
+  const runLogsCommand = 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").option("--step <id>", "Query structured logs from this authored step").option(
+    "--level <level>",
+    "Query structured logs at this severity or above"
+  ).option(
+    "--query <text>",
+    "Find literal text in the full retained log message"
+  ).option(
+    "--count",
+    "Exact matching retained log count; no limit or payloads"
+  ).option("--group-by <fields>", "Count log groups by comma-separated fields").option(
+    "--sum <field>",
+    "Count and sum numeric values; repeatable, optionally grouped",
+    (field, previous) => [...previous, field],
+    []
+  ).option("--fields", "Discover query fields, types and operators").addOption(
+    new Option2(
       "--logs",
       "Compatibility alias for --log-level debug"
     ).hideHelp()
   ).addOption(
-    new Option(
+    new Option2(
       "--debug",
       "Compatibility alias for --log-level debug"
     ).hideHelp()
@@ -17907,36 +18316,44 @@ Examples:
     "--cursor <token>",
     "Continue to older logs or the next events page"
   ).addOption(
-    new Option(
+    new Option2(
       "--runtime-namespace <name>",
       "Search an explicitly authorized Preview namespace"
     ).hideHelp()
   ).addOption(
-    new Option(
+    new Option2(
       "--runtime-backend <backend>",
       "Preview backend: daytona or modal"
     ).hideHelp()
   ).action(async (runId, options) => {
     process.exitCode = await handleRunLogs([
       ...runId ? [runId] : [],
-      ...options.limit ? ["--limit", options.limit] : [],
-      ...options.out ? ["--out", options.out] : [],
+      ...options.limit !== void 0 ? ["--limit", options.limit] : [],
+      ...options.out !== void 0 ? ["--out", options.out] : [],
       ...options.failed ? ["--failed"] : [],
       ...options.logLevel ? ["--log-level", options.logLevel] : [],
+      ...options.step !== void 0 ? ["--step", options.step] : [],
+      ...options.level !== void 0 ? ["--level", options.level] : [],
+      ...options.query !== void 0 ? ["--query", options.query] : [],
+      ...options.count ? ["--count"] : [],
+      ...options.groupBy !== void 0 ? ["--group-by", options.groupBy] : [],
+      ...(options.sum ?? []).flatMap((field) => ["--sum", field]),
+      ...options.fields ? ["--fields"] : [],
       ...options.logs ? ["--logs"] : [],
       ...options.debug ? ["--debug"] : [],
-      ...options.since ? ["--since", options.since] : [],
-      ...options.until ? ["--until", options.until] : [],
-      ...options.play ? ["--play", options.play] : [],
-      ...options.kind ? ["--kind", options.kind] : [],
-      ...options.where ? ["--where", options.where] : [],
+      ...options.since !== void 0 ? ["--since", options.since] : [],
+      ...options.until !== void 0 ? ["--until", options.until] : [],
+      ...options.play !== void 0 ? ["--play", options.play] : [],
+      ...options.kind !== void 0 ? ["--kind", options.kind] : [],
+      ...options.where !== void 0 ? ["--where", options.where] : [],
       ...options.payloads ? ["--payloads"] : [],
-      ...options.cursor ? ["--cursor", options.cursor] : [],
+      ...options.cursor !== void 0 ? ["--cursor", options.cursor] : [],
       ...options.runtimeNamespace ? ["--runtime-namespace", options.runtimeNamespace] : [],
       ...options.runtimeBackend ? ["--runtime-backend", options.runtimeBackend] : [],
       ...options.json ? ["--json"] : []
     ]);
   });
+  configureRunQueryCommandErrors(runLogsCommand, "logs");
   runs.command("stop <runId>").description("Stop a play run.").addHelpText(
     "after",
     `