deepline 0.3.272 → 0.3.274

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>;
@@ -2858,7 +2890,7 @@ export class DeeplineClient {
     play: Pick<PlayListItem, 'name' | 'reference' | 'inputSchema'>,
   ): string {
     const target = play.reference || play.name;
-    return `deepline plays run ${target}${playInputExampleArgs(play.inputSchema)} --watch`;
+    return `deepline plays run ${target}${playInputExampleArgs(play.inputSchema)}`;
   }
 
   private starterPlayPath(
@@ -3657,7 +3689,7 @@ export class DeeplineClient {
    * Convenience wrapper around {@link registerPlayArtifact} plus
    * {@link startPlayRun}. This is the canonical file-backed path used by wrappers.
    * The returned id can be passed to {@link getPlayStatus} to retrieve the same
-   * durable `{ result }` object that the CLI prints after `--watch` completes.
+   * durable `{ result }` object that the CLI prints after `plays run` completes.
    *
    * @param code - Source string fallback; the bundled artifact should be passed in `options.artifact`
    * @param csvPath - Path to input CSV file, or `null`
@@ -3839,7 +3871,7 @@ export class DeeplineClient {
    * Get the current status of a play execution.
    *
    * Internal/advanced primitive. Public callers should usually prefer
-   * {@link runPlay}, {@link PlayJob.get}, or `deepline plays run --watch`.
+   * {@link runPlay}, {@link PlayJob.get}, or `deepline plays run`.
    *
    * @param workflowId - Play-run id from {@link startPlayRun}
    * @returns Current status with progress logs and partial results
@@ -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/index.ts

@@ -50,7 +50,7 @@ export type {
  * });
  * ```
  *
- * Then run with the CLI: `deepline plays run --file my-play.play.ts --watch`
+ * Then run with the CLI: `deepline plays run --file my-play.play.ts`
  * Installed npm CLIs can also run saved or prebuilt plays by name.
  *
  * ## Architecture

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

@@ -39,7 +39,7 @@
  * ```
  *
  * Then run via the CLI:
- * `deepline plays run --file my-play.play.ts --watch`.
+ * `deepline plays run --file my-play.play.ts`.
  * Installed npm CLIs can also run saved or prebuilt plays by name.
  *
  * ### Programmatic usage
@@ -486,7 +486,7 @@ export type DeeplinePlayRuntimeContext = PlayAuthoringRuntimeContext;
  * Provides methods to check status, stream logs, wait for completion,
  * or cancel the execution.
  *
- * This handle is the SDK-context equivalent of `deepline plays run --watch` and
+ * This handle is the SDK-context equivalent of `deepline plays run` and
  * `POST /api/v2/plays/run`: every surface returns a run id first, then exposes
  * the completed user output through `PlayJob.get()` or the status endpoint's
  * `result` field. Runtime logs are available from `status().progress.logs` and

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.272',
+  version: '0.3.274',
   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/plays/authoring-contract.ts

@@ -1607,13 +1607,14 @@ export interface PlayAuthoringRuntimeContext {
   ): Promise<AsyncPlayRunRef>;
 
   /**
-   * Write a customer-safe line to the durable Run Log Stream. Omitting level
-   * preserves the historical info-level behavior.
+   * Write a customer-safe retained log line, searchable as `log.appended` in the unified event journal. Default severity is info; runtime sampling and retention limits apply. Use `runs.logs` for retained text and `runs.searchEvents` for indexed context; see `deepline runs logs --help` for the complete read contract.
    */
   log(
     message: string,
     options?: {
+      /** Defaults to info. Warn/error lines are not subject to info/debug sampling. */
       level?: 'debug' | 'info' | 'warn' | 'error';
+      /** At most eight flat scalar fields and 2,048 UTF-8 bytes total. Keys match [A-Za-z_][A-Za-z0-9_]{0,63}; __proto__, constructor and prototype are forbidden. String values are at most 256 UTF-8 bytes. Search with `$.context.<key> == literal`; context cannot override run/event identity. */
       context?: Readonly<Record<string, string | number | boolean>>;
     },
   ): void;