deepline 0.3.271 → 0.3.273

package/README.md

@@ -38,6 +38,15 @@ with project-local skills automatically.
 
 ## Use it with an agent
 
+For an existing run, start with `deepline runs logs --help`. It includes every
+known event kind, what records it, available fields, filters, payload reads,
+pagination and retention. `runs logs` reads text or structured events;
+`runs get`, `runs watch`, `runs export` and `runs receipt` cover status, live
+observation, dataset rows and retained tool results. These inspection commands
+read existing evidence without starting provider work. TypeScript callers use
+`client.runs.logs`, `client.runs.searchEvents` and `client.runs.getReceipts`;
+their source JSDoc and the generated SDK/API references describe the same reads.
+
 Paste this into Claude Code, Codex, or another coding agent:
 
 ```text

package/dist/bundling-sources/sdk/src/client.ts

@@ -740,25 +740,33 @@ export type RunsWatchOptions = {
 /** @deprecated Use `RunsWatchOptions`. */
 export type RunsTailOptions = RunsWatchOptions;
 
-/** Log fetch options for `client.runs.logs(...)`. */
+/** Read retained text with `client.runs.logs(...)`; use `runs.searchEvents` for structured filters and payloads. */
 export type RunsLogsOptions = {
-  /** Return the LAST `limit` stored log lines (default 200). */
+  /** Return the last `limit` retained lines in sequence order; default 200. Ignored when `all` is true. */
   limit?: number;
-  /** Fetch every stored log line, paginating to the full totalCount. */
+  /** Page through every retained line. Cannot combine with `failed`; sampling or retention loss cannot be recovered. */
   all?: boolean;
-  /** Select the bounded failure view; truncated runs degrade explicitly. */
+  /** Read a terminal-failed run's last 20 retained lines, or fewer with `limit`. Retention loss returns an explicit association and warning. */
   failed?: boolean;
 };
 
-/** Persisted log response for one play run. */
+/** Retained text for one run. Counts and retention flags describe the stored stream, not every original console call. */
 export type RunsLogsResult = {
+  /** Public run identity. */
   runId: string;
+  /** Count tracked by the log stream; may exceed available bodies after retention truncation. */
   totalCount: number;
+  /** Number of line bodies returned in `entries`. */
   returnedCount: number;
+  /** First returned stored sequence, or null for an empty view. */
   firstSequence: number | null;
+  /** Last returned stored sequence, or null for an empty view. */
   lastSequence: number | null;
+  /** Tail/all: returned count is below total count. Failed: the stream lost bodies to retention. Check `logsTruncated` to distinguish retention loss from a selected tail. */
   truncated: boolean;
+  /** More retained lines exist after `lastSequence`; always false for the designed failure window. */
   hasMore: boolean;
+  /** Formatted text lines in stored sequence order; structured context is available through event search. */
   entries: string[];
   /** Selected public log view. */
   view?: 'tail' | 'failed' | 'all';
@@ -775,53 +783,77 @@ export type RunsLogsResult = {
   logsTruncated?: boolean;
 };
 
-/** Bounded org-scoped search over durable Play runtime observations. */
+/** Read existing events in the authenticated organization/runtime scope, newest first by occurrence time and event ID. See the complete catalog and field contract in `deepline runs logs --help`. */
 export type RunsEventSearchOptions = {
   /** Inclusive UTC timestamp; defaults to one hour before the request. */
   since?: string;
-  /** Exclusive UTC timestamp; defaults to the request time. */
+  /** Exclusive UTC timestamp; defaults to the request time. A window spans at most seven days; event retention is seven days. */
   until?: string;
   /** Optional run filter. Omit to search across the active organization. */
   runId?: string;
+  /** Exact Play name; HTTP query parameter `playName`, CLI `--play`. */
   playName?: string;
+  /** Exact dotted event kind, such as `step.failed`. The catalog is discoverable with `runs logs --help`; future stored kinds are accepted too. */
   kind?: string;
-  /** Flat equality predicate in the supported PostgreSQL JSONPath subset. */
+  /** Equality joined with `&&`, at most eight predicates and 512 bytes. Fields: orgId, runId, playName, runtimeScope, producerAttempt, kind, status, source, stepId, stepKind, datasetId, phase, provider, operation and scalar `context.<key>`. Missing fields do not match; status is not inferred from kind. No body, message, level, nested payload, range or OR search. HTTP `jsonpath`, CLI `--where`. */
   jsonpath?: string;
-  /** Include canonical event details and receipt-backed outputs, capped to ten events and 16 MiB total. */
+  /** Add stored canonical `eventPayload` and, for receipt matches, retained `payload`. At most ten events and 16 MiB; unavailable receipts return null. HTTP `payloads=true`, CLI `--payloads`. Does not execute tools. */
   includePayloads?: boolean;
+  /** Page size: default 100, maximum 200; with payloads, default and maximum ten. */
   limit?: number;
+  /** Opaque `nextCursor` from the preceding page. Reuse that page's returned since/until and the same filters and runtime scope. */
   cursor?: string;
   /** Explicit Preview selection requires the existing runtime credential. */
   runtime?: PlayRuntimeSelection;
 };
 
+/** One indexed observation; optional indexed fields and payloads depend on what its producer recorded. */
 export type RunsEventSearchEntry = {
+  /** Stable event identity; also breaks ties in newest-first pagination. */
   eventId: string;
+  /** Producer occurrence time as a UTC timestamp string. */
   occurredAt: string;
+  /** Index ingestion time as a UTC timestamp string; may be later than occurrence. */
   ingestedAt: string;
+  /** Public run identity associated with this observation. */
   runId: string;
+  /** Recorded Play name. */
   playName: string;
+  /** Exact indexed kind; canonical payloads use `type` for this dotted name. */
   kind: string;
+  /** Recorded log severity, or null; not a JSONPath filter field. */
   level: string | null;
+  /** Log message preview of at most 2,048 characters, or null. Use text logs/export for the full retained line. */
   message: string | null;
+  /** Indexed identity and recorded scalar fields. SDK/API keep this nested; CLI search flattens it onto each event. Provider/operation describe typed activity observations, not every provider call. */
   searchDoc: Record<string, unknown>;
-  /** Accepted Play event from PScale when this run uses the unified journal. */
+  /** Stored canonical event details, only when payloads are requested and available. Lifecycle/activity/dataset payloads are observations, not complete tool responses or dataset rows. */
   eventPayload?: Record<string, unknown>;
-  /** Optional full result, included only when explicitly requested. */
+  /** Retained work result for a receipt match when payloads are requested; null if unavailable. Other events need not carry this field. */
   payload?: RunsEventPayload | null;
 };
 
+/** One bounded search page. Continue using `nextCursor` and these exact time bounds; CLI-only counts and follow-up commands are not SDK/API fields. */
 export type RunsEventSearchResult = {
+  /** Matching observations in descending occurredAt/eventId order. */
   events: RunsEventSearchEntry[];
+  /** Opaque continuation token, or null when no further page exists. */
   nextCursor: string | null;
+  /** Resolved inclusive UTC bound, including a defaulted bound. */
   since: string;
+  /** Resolved exclusive UTC bound, including a defaulted bound. */
   until: string;
 };
 
+/** Retained work outcome hydrated for a receipt event; not a new execution, billing receipt or guarantee of a raw HTTP response. */
 export type RunsEventPayload = {
+  /** Recorded terminal work outcome. */
   status: 'completed' | 'failed' | 'skipped';
+  /** Stored result data, or null when no output was retained. */
   output: unknown | null;
+  /** Stored failure message, or null when absent. */
   error: string | null;
+  /** Stored structured failure details, or null when absent. */
   errorPayload: unknown | null;
 };
 
@@ -902,7 +934,7 @@ export type PlaySecretCheck = {
  * @sdkReference client 020 client.runs
  */
 export type RunsNamespace = {
-  /** Read retained tool results associated with a run, in supplied key order. Never executes tools. */
+  /** Read retained tool results in supplied key order. Use keys returned in exported evidence or execution metadata; search does not expose receipt keys. Never executes tools. */
   getReceipts: (
     runId: string,
     options: { keys: string[] },
@@ -937,9 +969,9 @@ export type RunsNamespace = {
   watch: (runId: string, options?: RunsWatchOptions) => Promise<PlayStatus>;
   /** @deprecated Use `watch`; retained as a source-compatible alias. */
   tail: (runId: string, options?: RunsTailOptions) => Promise<PlayStatus>;
-  /** Fetch persisted log lines for a run. */
+  /** Read a run's retained text tail, full stream (`all`) or terminal failure window (`failed`). For structured filters and payloads, see [run logs and events](run-events.md). */
   logs: (runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>;
-  /** Search recent durable runtime events across runs in the active organization. */
+  /** Search existing events across the active organization; default last hour, up to 200 events per page (ten with payloads). See [run logs and events](run-events.md) for the catalog, query fields and response types. */
   searchEvents: (
     options?: RunsEventSearchOptions,
   ) => Promise<RunsEventSearchResult>;
@@ -4342,7 +4374,7 @@ export class DeeplineClient {
     return { ...response, runs: response.runs ?? [] };
   }
 
-  /** Read batches rather than silently truncating a long key list. */
+  /** Read retained tool results without executing tools, preserving supplied key order and batching 100 keys per request. Obtain keys from exported evidence or execution metadata; each key must be nonempty, at most 2,048 characters and contain no CR, LF or NUL. Missing/expired results have an explicit per-key error. */
   async getRunReceipts(
     runId: string,
     options: { keys: string[] },
@@ -4426,7 +4458,7 @@ export class DeeplineClient {
   }
 
   /**
-   * Fetch persisted logs for a run using the public runs resource model.
+   * Read a run's retained text tail (default 200), full retained stream (`all`), or terminal failure window (`failed`, at most 20). These are existing reads; sampling and retention loss cannot be recovered. See [run logs and events](run-events.md) for structured search and payload retrieval.
    *
    * This is the SDK equivalent of:
    *
@@ -4525,7 +4557,7 @@ export class DeeplineClient {
     };
   }
 
-  /** Search bounded, structured runtime history without requiring a run id. */
+  /** Read structured history across the active organization without requiring a run ID. Defaults to the last hour, newest first; use the returned cursor and exact time bounds to continue. See [run logs and events](run-events.md) for all kinds, indexed fields, payloads and SDK/API response types. */
   async searchRunEvents(
     options: RunsEventSearchOptions = {},
   ): Promise<RunsEventSearchResult> {

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const 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.271',
+  version: '0.3.273',
   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: {

package/dist/bundling-sources/sdk/src/runs/receipts.ts

@@ -1,23 +1,39 @@
-/** A retained result, not a new tool execution or a billing receipt. */
+/** Read-only retained tool evidence associated with a run. Each requested key returns either its stored result or an explicit error; this never executes tools or returns a billing receipt. */
 export type RunToolReceiptResult = {
+  /** Exact key supplied to the read, obtained from exported evidence or execution metadata. */
   receiptKey: string;
+  /** Recorded work status when available; an error does not imply a fresh provider failure. */
   status?: string;
 } & (
   | {
+      /** Retained result envelope; provider fields reflect stored evidence, not a guaranteed raw HTTP response. */
       result: {
+        /** Status recorded in the tool result. */
         status: string;
+        /** Provider job identity when recorded. */
         job_id?: string;
+        /** Stored tool response. */
         toolResponse: Record<string, unknown>;
+        /** Stored target values when the tool supplied them. */
         targetValues?: Record<string, unknown>;
+        /** Stored list dataset metadata when supplied. */
         listDatasets?: Record<string, unknown>;
+        /** Stored list row evidence when supplied. */
         listRows?: Record<string, unknown>;
       };
       error?: never;
     }
-  | { result?: never; error: { code: string; message: string } }
+  | {
+      result?: never;
+      /** Explicit lookup/access/retention failure for this key. */
+      error: { code: string; message: string };
+    }
 );
 
+/** Results in the exact requested key order, including errors for unavailable keys. */
 export type RunToolReceiptsResponse = {
+  /** Public run identity used to scope the read. */
   runId: string;
+  /** One result or error per requested key. */
   receipts: RunToolReceiptResult[];
 };

package/dist/bundling-sources/shared_libs/play-runtime/activity-observation.ts

@@ -1,3 +1,4 @@
+import { RUN_EVENT_KIND } from './run-event-catalog';
 /**
  * Canonical, producer-facing description of what a play is doing.
  *
@@ -117,7 +118,7 @@ export type PlayActivityObservation = {
 };
 
 export type PlayActivityEvent = {
-  type: 'activity.observed';
+  type: typeof RUN_EVENT_KIND.activityObserved;
   observation: PlayActivityObservation;
 };
 
@@ -357,7 +358,7 @@ export function createPlayActivityReporter(input: {
   return {
     observe(observation) {
       input.emit({
-        type: 'activity.observed',
+        type: RUN_EVENT_KIND.activityObserved,
         observation: {
           ...observation,
           observedAt: observation.observedAt ?? input.now?.() ?? Date.now(),

package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts

@@ -1,3 +1,7 @@
+import {
+  RUN_EVENT_KIND,
+  RUN_EVENT_TERMINAL_KIND_VALUES,
+} from './run-event-catalog';
 import { prepareRetainedPlayPipelinesForTransport } from '../plays/execution-pipeline';
 import { createWriteStream } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
@@ -2257,7 +2261,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
   });
   if (update.workCounters) {
     events.push({
-      type: 'work.counters',
+      type: RUN_EVENT_KIND.workCounters,
       runId: update.playId,
       source: 'worker',
       occurredAt: update.lastCheckpointAt ?? Date.now(),
@@ -2283,7 +2287,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
           event.bornFrom.rowCountIn > current.bornFrom.rowCountIn));
     if (!changesSnapshot) continue;
     events.push({
-      type: 'dataset.lifecycle',
+      type: RUN_EVENT_KIND.datasetLifecycle,
       runId: update.playId,
       source: 'worker',
       occurredAt: event.at,
@@ -2315,7 +2319,7 @@ async function updateRunStatusViaAppRuntimeUnlocked(
     });
     if (lane === 'drop' || lane === 'liveness') continue;
     events.push({
-      type: 'activity.observed',
+      type: RUN_EVENT_KIND.activityObserved,
       runId: update.playId,
       source: 'worker',
       occurredAt: observation.observedAt,
@@ -2461,9 +2465,7 @@ function runLedgerReceiptBatchIndex(
   for (let index = batches.length - 1; index >= 0; index -= 1) {
     if (
       batches[index]!.some((event) =>
-        ['run.completed', 'run.failed', 'run.cancelled'].includes(
-          event.key ?? event.type ?? '',
-        ),
+        RUN_EVENT_TERMINAL_KIND_VALUES.includes(event.key ?? event.type ?? ''),
       )
     )
       return index;
@@ -2500,9 +2502,9 @@ export async function appendRunEventsViaAppRuntime(
       batches[index]!.some((event) => {
         const key = event.key ?? event.type;
         return (
-          key === 'run.completed' ||
-          key === 'run.failed' ||
-          key === 'run.cancelled'
+          key === RUN_EVENT_KIND.runCompleted ||
+          key === RUN_EVENT_KIND.runFailed ||
+          key === RUN_EVENT_KIND.runCancelled
         );
       })
     ) {

package/dist/bundling-sources/shared_libs/play-runtime/context.ts

@@ -1,3 +1,4 @@
+import { RUN_EVENT_KIND } from './run-event-catalog';
 /**
  * PlayContextImpl — the cloud execution engine.
  *
@@ -14728,7 +14729,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const observedAt = Date.now();
     const label = providerCapacityLabel(provider);
     this.emitExecutionEvent({
-      type: 'activity.observed',
+      type: RUN_EVENT_KIND.activityObserved,
       observation: {
         activityId: `capacity:provider:${label}`,
         target: { kind: 'capacity', pool: 'provider', label },
@@ -20524,7 +20525,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 );
                 retryActivityEmitted = true;
                 this.emitExecutionEvent({
-                  type: 'activity.observed',
+                  type: RUN_EVENT_KIND.activityObserved,
                   observation: {
                     schemaVersion: 1,
                     activityId,
@@ -20561,7 +20562,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   deeplineRequestId = `ctx-tool-${stableDigest(`${executionRequestNonce}:provider-rate-limit-retry:${invocationAttempt}`).slice(0, 32)}`;
                 }
                 this.emitExecutionEvent({
-                  type: 'activity.observed',
+                  type: RUN_EVENT_KIND.activityObserved,
                   observation: {
                     schemaVersion: 1,
                     activityId,
@@ -20654,7 +20655,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       toolInputSnapshotMemory.current?.release();
       if (retryActivityEmitted) {
         this.emitExecutionEvent({
-          type: 'activity.observed',
+          type: RUN_EVENT_KIND.activityObserved,
           observation: {
             schemaVersion: 1,
             activityId,

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -1,3 +1,4 @@
+import { RUN_EVENT_KIND } from './run-event-catalog';
 // Core types for PlayContext.
 import type {
   PlayCellReadRef,
@@ -572,7 +573,7 @@ export type PlayExecutionEvent =
       at: number;
     }
   | {
-      type: 'dataset.lifecycle';
+      type: typeof RUN_EVENT_KIND.datasetLifecycle;
       datasetId: string;
       path: string;
       tableNamespace: string;