deepline 0.3.275 → 0.3.277

package/dist/cli/index.js

@@ -3512,7 +3512,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.275",
+  version: "0.3.277",
   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
@@ -15743,205 +15743,73 @@ function registerPlayTriggerConfigCommands(plays) {
 var import_node_crypto7 = require("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. When older lines exist, hasMore is true and nextCursor continues the next older page with --cursor. --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, --runtime-namespace or --runtime-backend. A supplied run ID then narrows the search. --cursor continues event search unless it is a returned before:<sequence> text-log cursor. --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> --cursor before:1201 --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} `;
   }
@@ -15949,34 +15817,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");
 }
 
@@ -37321,15 +37191,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 import_commander3.Option(
       "--logs",
       "Compatibility alias for --log-level debug"
@@ -37339,22 +37201,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(
+  ).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 paging: older run-log lines (nextCursor) or 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) => {
+    "Continue to older logs or the next events page"
+  ).addOption(
+    new import_commander3.Option(
+      "--runtime-namespace <name>",
+      "Search an explicitly authorized Preview namespace"
+    ).hideHelp()
+  ).addOption(
+    new import_commander3.Option(
+      "--runtime-backend <backend>",
+      "Preview backend: daytona or modal"
+    ).hideHelp()
+  ).action(async (runId, options) => {
     process.exitCode = await handleRunLogs([
       ...runId ? [runId] : [],
       ...options.limit ? ["--limit", options.limit] : [],