deepline 0.3.229 → 0.3.231

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres.ts

@@ -79,12 +79,17 @@ import {
 import type { PlayStaticPipeline } from '../../plays/static-pipeline';
 import {
   LOG_TAIL_LIMIT,
+  normalizePlayRunLedgerTerminalWorkCounterSegment,
   type AcceptedPlayRunLedgerEvent,
   type PlayRunLedgerEvent,
   type PlayRunLedgerIngressEvent,
+  type PlayRunLedgerTerminalWorkCounterSegment,
 } from '../run-ledger';
 import { stableStringify } from '../../plays/row-identity';
-import { runtimeWorkCountersFromResources } from '../runtime-work-counters';
+import {
+  runtimeWorkCountersFromResources,
+  runtimeWorkCountersFromStats,
+} from '../runtime-work-counters';
 import {
   isCtxFetchHttpFailureDiagnostic,
   parseCtxFetchHttpFailureDiagnostic,
@@ -9456,6 +9461,28 @@ export type PostgresSchedulerDirectRunnerTerminalOutcome =
   | 'wake_required'
   | 'not_found';
 
+function terminalWorkCounterSegmentFromRunnerResult(
+  result: unknown,
+  attempt: number,
+): PlayRunLedgerTerminalWorkCounterSegment | undefined {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) {
+    return undefined;
+  }
+  const stats = (result as { stats?: unknown }).stats;
+  if (!stats || typeof stats !== 'object' || Array.isArray(stats)) {
+    return undefined;
+  }
+  const segment = (stats as { runtimeWorkCounterSegment?: unknown })
+    .runtimeWorkCounterSegment;
+  if (!segment || typeof segment !== 'object' || Array.isArray(segment)) {
+    return undefined;
+  }
+  return normalizePlayRunLedgerTerminalWorkCounterSegment({
+    ...segment,
+    attempt,
+  });
+}
+
 /**
  * Reduce an ordinary detached-runner completion at terminal ingress.
  *
@@ -9522,6 +9549,10 @@ export async function directCompletePostgresSchedulerRunnerTerminal(
     input.terminalLogOutbox,
   );
   const runtimeTiming = extractRunnerRuntimeTiming(input.result);
+  const terminalWorkCounterSegment = terminalWorkCounterSegmentFromRunnerResult(
+    input.result,
+    input.attempt,
+  );
   // `workCompletedAtMs` is useful lifecycle telemetry, but it comes from the
   // sandbox process where play code can alter Date.now. Billing must stop on
   // the first database receipt, whose clock and first-write semantics are
@@ -9767,7 +9798,8 @@ export async function directCompletePostgresSchedulerRunnerTerminal(
             'output', $6::jsonb,
             'terminalLogLines', $7::jsonb,
             'terminalProgressEvents', $8::jsonb,
-            'resultSummary', $16::jsonb
+            'resultSummary', $16::jsonb,
+            'terminalWorkCounterSegment', $17::jsonb
           ),
           ${causalOutboxCreatedAt('run_terminal.run_id', options)}
         FROM run_terminal
@@ -9802,6 +9834,7 @@ export async function directCompletePostgresSchedulerRunnerTerminal(
       input.engineWake.wakeChannel,
       input.allowCappedCompletion === true,
       stringifyPostgresJson(resultSummary),
+      stringifyPostgresJson(terminalWorkCounterSegment ?? null),
     ],
   );
   if (completed.rows.length > 0) return 'completed';
@@ -11815,6 +11848,7 @@ export async function completePostgresSchedulerAttempt(
     rowOutcomes?: unknown;
     runtimeTiming?: PlayRunnerRuntimeTiming | null;
     terminalLogLines?: readonly string[] | null;
+    terminalWorkCounterSegment?: PlayRunLedgerTerminalWorkCounterSegment;
   },
   options?: Pick<PostgresSchedulerOptions, 'schema'>,
 ): Promise<boolean> {
@@ -12002,7 +12036,8 @@ export async function completePostgresSchedulerAttempt(
           jsonb_build_object(
             'output', $9::jsonb,
             'terminalLogLines', $8::jsonb,
-            'resultSummary', $10::jsonb
+            'resultSummary', $10::jsonb,
+            'terminalWorkCounterSegment', $11::jsonb
           ),
           ${causalOutboxCreatedAt('run_terminal.run_id', options)}
         FROM run_terminal
@@ -12024,6 +12059,7 @@ export async function completePostgresSchedulerAttempt(
       JSON.stringify(terminalLogLines),
       stringifyPostgresJson(ledgerTerminalResult ?? null),
       stringifyPostgresJson(resultSummary),
+      stringifyPostgresJson(input.terminalWorkCounterSegment ?? null),
     ],
   );
   if (completed.rows.length === 0) {
@@ -12070,6 +12106,10 @@ export async function failPostgresSchedulerAttempt(
   const resultSummary = terminalRowOutcomesSummary(
     (input.result as { rowOutcomes?: unknown } | null)?.rowOutcomes,
   );
+  const terminalWorkCounterSegment = terminalWorkCounterSegmentFromRunnerResult(
+    input.result,
+    input.attempt,
+  );
   // Keep the recovery tail separate from result: large failures are represented
   // by a result reference, but their customer guidance must still be logged.
   const terminalLogLines = (input.terminalLogLines ?? [])
@@ -12311,7 +12351,8 @@ export async function failPostgresSchedulerAttempt(
             'error', $4::jsonb ->> 'message',
             'result', $8::jsonb,
             'terminalLogLines', $12::jsonb,
-            'resultSummary', $13::jsonb
+            'resultSummary', $13::jsonb,
+            'terminalWorkCounterSegment', $14::jsonb
           ),
           ${causalOutboxCreatedAt('run_terminal.run_id', options)}
         FROM run_terminal
@@ -12336,6 +12377,7 @@ export async function failPostgresSchedulerAttempt(
       input.preserveRunnerTerminal === true,
       JSON.stringify(terminalLogLines),
       stringifyPostgresJson(resultSummary),
+      stringifyPostgresJson(terminalWorkCounterSegment ?? null),
     ],
   );
   return failed.rows.length > 0;
@@ -13111,10 +13153,11 @@ export function attachRunnerWorkProgressMetadata(
   // Keep the two scalar counts when the detailed runtimeResources record
   // exceeds its metadata budget. Compact status must not scan a call log to
   // reconstruct physical work.
-  const runtimeCounters = runtimeWorkCountersFromResources(
-    (runnerResult as { stats?: { runtimeResources?: unknown } }).stats
-      ?.runtimeResources,
-  );
+  const stats = (runnerResult as { stats?: { runtimeResources?: unknown } })
+    .stats;
+  const runtimeCounters =
+    runtimeWorkCountersFromStats(stats) ??
+    runtimeWorkCountersFromResources(stats?.runtimeResources);
   const outputWarnings = Array.isArray(
     (runnerResult as { outputWarnings?: unknown }).outputWarnings,
   )
@@ -13294,6 +13337,10 @@ export async function executePostgresSchedulerClaim(
         output: terminalOutput,
         rowOutcomes: (output as { rowOutcomes?: unknown } | null)?.rowOutcomes,
         runtimeTiming: extractRunnerRuntimeTiming(output),
+        terminalWorkCounterSegment: terminalWorkCounterSegmentFromRunnerResult(
+          output,
+          claim.attempt,
+        ),
         terminalLogLines: terminalLogLinesForOutbox(
           output,
           options.terminalLogOutbox,
@@ -16928,6 +16975,10 @@ export function buildRunLedgerEventsFromPostgresSchedulerOutbox(
     ];
   }
   if (event.eventType === 'run.completed') {
+    const terminalWorkCounterSegment =
+      normalizePlayRunLedgerTerminalWorkCounterSegment(
+        payloadField(event.payload, 'terminalWorkCounterSegment'),
+      );
     const progressEvents = ledgerEventsPayloadField(
       event.payload,
       'terminalProgressEvents',
@@ -16953,6 +17004,7 @@ export function buildRunLedgerEventsFromPostgresSchedulerOutbox(
         runId: event.runId,
         occurredAt,
         source: 'system',
+        ...(terminalWorkCounterSegment ? { terminalWorkCounterSegment } : {}),
         result: terminalRunResultForLedger(
           payloadField(event.payload, 'output'),
         ),
@@ -16963,6 +17015,10 @@ export function buildRunLedgerEventsFromPostgresSchedulerOutbox(
     ];
   }
   if (event.eventType === 'run.failed') {
+    const terminalWorkCounterSegment =
+      normalizePlayRunLedgerTerminalWorkCounterSegment(
+        payloadField(event.payload, 'terminalWorkCounterSegment'),
+      );
     const progressEvents = ledgerEventsPayloadField(
       event.payload,
       'terminalProgressEvents',
@@ -16991,6 +17047,7 @@ export function buildRunLedgerEventsFromPostgresSchedulerOutbox(
         runId: event.runId,
         occurredAt,
         source: 'system',
+        ...(terminalWorkCounterSegment ? { terminalWorkCounterSegment } : {}),
         error: stringPayloadField(event.payload, 'error'),
         ...(result === null || result === undefined ? {} : { result }),
         ...(resultSummary === undefined || resultSummary === null
@@ -17210,17 +17267,18 @@ export async function listPostgresSchedulerOutboxMaterializationPlans(
 }
 
 /**
- * Where the projector gets its runtime-API executor token when one is not
- * supplied per-event via `runtimeApi`.
+ * Where the projector gets its runtime-API executor token.
  *
  * - `local_mint`: sign the token in-process with `BETTER_AUTH_SECRET`. ONLY the
  *   app (Vercel) legitimately holds the signing key, so this is app-side only
  *   (read-model heal path). It is the AUTHORITATIVE projector.
- * - `gateway`: prove the active outbox lease to the launch-pinned deployment and
- *   receive a short-lived executor JWT (`requestRunLedgerDispatchToken`). The
- *   Fly worker has no signing key and MUST
- *   use this. Delivery failures use the same structured retry-or-block policy
- *   as the app-side projector.
+ * - `gateway`: always prove the active outbox lease to the launch-pinned
+ *   deployment and receive a short-lived executor JWT
+ *   (`requestRunLedgerDispatchToken`), even if the caller supplied a
+ *   `runtimeApi`. The Fly worker has no signing key and MUST use this. A
+ *   supplied context contributes transport options only; its executor token
+ *   cannot bypass the lease-scoped gateway hop. Delivery failures use the same
+ *   structured retry-or-block policy as the app-side projector.
  *
  * Explicit by design: the old code sniffed `process.env.BETTER_AUTH_SECRET` to
  * pick the branch, so the worker's projection silently depended on the secret
@@ -17262,15 +17320,20 @@ export function postgresSchedulerCancellationOutboxLease(runId: string): {
 }
 
 export type RunLedgerOutboxDispatchInput = {
+  /**
+   * Optional runtime context. `gateway` authority always replaces its
+   * credentials with a fresh lease-scoped token and keeps only supported
+   * transport options; `local_mint` and the default authority preserve the
+   * explicit context as before.
+   */
   runtimeApi?: WorkerRuntimeApiContext | null;
   limit?: number;
   runId?: string | null;
   leaseOwner?: string | null;
   leaseSeconds?: number;
   /**
-   * Token authority for events without a per-event `runtimeApi`. Defaults to
-   * `local_mint` for the app-side authoritative projector. The Fly worker MUST
-   * pass `gateway`.
+   * Token authority for the outbox dispatch. Defaults to `local_mint` for the
+   * app-side authoritative projector. The Fly worker MUST pass `gateway`.
    */
   tokenAuthority?: RunLedgerOutboxTokenAuthority;
 };
@@ -17568,7 +17631,24 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
 
   try {
     const first = events[0]!;
+    const tokenAuthority = input.tokenAuthority ?? 'local_mint';
+    const gatewayRuntimeApi =
+      tokenAuthority === 'gateway'
+        ? await withClient((client) =>
+            loadPostgresSchedulerRuntimeApiForRun(
+              client,
+              first.runId,
+              first.leaseOwner
+                ? { eventId: first.eventId, leaseOwner: first.leaseOwner }
+                : null,
+              tokenAuthority,
+              options,
+              input.runtimeApi?.signal,
+            ),
+          )
+        : null;
     const resolvedRuntimeApi =
+      gatewayRuntimeApi ??
       input.runtimeApi ??
       (await withClient((client) =>
         loadPostgresSchedulerRuntimeApiForRun(
@@ -17577,11 +17657,36 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
           first.leaseOwner
             ? { eventId: first.eventId, leaseOwner: first.leaseOwner }
             : null,
-          input.tokenAuthority ?? 'local_mint',
+          tokenAuthority,
           options,
         ),
       ));
-    const runtimeApi = { ...resolvedRuntimeApi, retryPolicy: 'none' as const };
+    const runtimeApi = {
+      ...resolvedRuntimeApi,
+      ...(gatewayRuntimeApi && input.runtimeApi
+        ? {
+            ...(input.runtimeApi.fetch
+              ? { fetch: input.runtimeApi.fetch }
+              : {}),
+            ...(input.runtimeApi.requestTimeoutMs !== undefined
+              ? { requestTimeoutMs: input.runtimeApi.requestTimeoutMs }
+              : {}),
+            ...(input.runtimeApi.onResponseMeta
+              ? { onResponseMeta: input.runtimeApi.onResponseMeta }
+              : {}),
+            ...(input.runtimeApi.runtimeTestFaultHeader !== undefined
+              ? {
+                  runtimeTestFaultHeader:
+                    input.runtimeApi.runtimeTestFaultHeader,
+                }
+              : {}),
+            ...(input.runtimeApi.signal
+              ? { signal: input.runtimeApi.signal }
+              : {}),
+          }
+        : {}),
+      retryPolicy: 'none' as const,
+    };
     const renewDelivery = () =>
       withClient((client) =>
         renewPostgresRunLedgerDelivery(
@@ -17839,6 +17944,7 @@ async function loadPostgresSchedulerRuntimeApiForRun(
   dispatchLease: { eventId: string; leaseOwner: string } | null,
   tokenAuthority: RunLedgerOutboxTokenAuthority,
   options?: Pick<PostgresSchedulerOptions, 'schema'>,
+  signal?: AbortSignal,
 ): Promise<WorkerRuntimeApiContext> {
   const result = await client.query<{ launch_json: unknown }>(
     `
@@ -17879,6 +17985,7 @@ async function loadPostgresSchedulerRuntimeApiForRun(
       eventId: dispatchLease.eventId,
       leaseOwner: dispatchLease.leaseOwner,
       schedulerSchema: options?.schema ?? null,
+      signal,
     });
   }
   return {
@@ -17893,6 +18000,7 @@ async function requestRunLedgerDispatchToken(input: {
   eventId: string;
   leaseOwner: string;
   schedulerSchema: string | null;
+  signal?: AbortSignal;
 }): Promise<string> {
   const internalToken = process.env.DEEPLINE_INTERNAL_TOKEN?.trim();
   if (!internalToken || !input.eventId || !input.leaseOwner) {
@@ -17904,10 +18012,16 @@ async function requestRunLedgerDispatchToken(input: {
   const vercelProtectionHeaders = await vercelProtectionBypassHeaders({
     baseUrl: runtimeApiBaseUrlFromLaunch(input.launch),
     token: input.launch.vercelProtectionBypassToken,
+    signal: input.signal,
   });
   const response = await fetch(url, {
     method: 'POST',
-    signal: AbortSignal.timeout(RUN_LEDGER_DISPATCH_TOKEN_TIMEOUT_MS),
+    signal: input.signal
+      ? AbortSignal.any([
+          input.signal,
+          AbortSignal.timeout(RUN_LEDGER_DISPATCH_TOKEN_TIMEOUT_MS),
+        ])
+      : AbortSignal.timeout(RUN_LEDGER_DISPATCH_TOKEN_TIMEOUT_MS),
     headers: {
       'content-type': 'application/json',
       'x-deepline-internal-token': internalToken,

package/dist/cli/index.js

@@ -3051,7 +3051,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.229",
+  version: "0.3.231",
   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
@@ -5384,12 +5384,84 @@ function normalizeDatasetBornFrom(value) {
 
 // ../play-runtime/run-ledger.ts
 var LOG_TAIL_LIMIT = 100;
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "terminated",
+  "timed_out"
+]);
 function isRecord5(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function finiteNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function nonnegativeSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isWorkCounterSegmentId(value) {
+  return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+    value
+  );
+}
+function normalizePlayRunLedgerTerminalWorkCounterSegment(value) {
+  if (!isRecord5(value)) return void 0;
+  if (!nonnegativeSafeInteger(value.attempt) || !nonnegativeSafeInteger(value.invocationSeq) || value.invocationSeq === 0 || !isWorkCounterSegmentId(value.segmentId)) {
+    return void 0;
+  }
+  return {
+    attempt: value.attempt,
+    invocationSeq: value.invocationSeq,
+    segmentId: value.segmentId
+  };
+}
+function hasConfirmedPlayRunLedgerWorkCounters(snapshot) {
+  const counters = snapshot.workCounters;
+  const terminal = snapshot.terminalWorkCounterSegment;
+  return Boolean(
+    isTerminalPlayRunLedgerStatus(snapshot.status) && (snapshot.terminalSource === "worker" || snapshot.terminalSource === "system") && counters?.final && counters.completeThroughAttempt && counters.consistent && terminal && counters.attempt === terminal.attempt && counters.invocationSeq === terminal.invocationSeq && counters.segmentId === terminal.segmentId && Number.isSafeInteger(
+      counters.completedLogicalCalls + counters.logicalCalls
+    ) && Number.isSafeInteger(
+      counters.completedProviderRequests + counters.providerRequests
+    ) && Number.isSafeInteger(
+      counters.completedProvider429s + counters.provider429s
+    )
+  );
+}
+function normalizeWorkCounters(value) {
+  if (!isRecord5(value)) return void 0;
+  for (const field of [
+    "attempt",
+    "invocationSeq",
+    "logicalCalls",
+    "providerRequests",
+    "provider429s",
+    "completedLogicalCalls",
+    "completedProviderRequests",
+    "completedProvider429s"
+  ]) {
+    if (!nonnegativeSafeInteger(value[field])) return void 0;
+  }
+  if (value.invocationSeq === 0 || !isWorkCounterSegmentId(value.segmentId) || typeof value.final !== "boolean" || typeof value.completeThroughAttempt !== "boolean" || typeof value.consistent !== "boolean") {
+    return void 0;
+  }
+  return {
+    ...value,
+    attempt: value.attempt,
+    invocationSeq: value.invocationSeq,
+    segmentId: value.segmentId,
+    logicalCalls: value.logicalCalls,
+    providerRequests: value.providerRequests,
+    provider429s: value.provider429s,
+    final: value.final,
+    completedLogicalCalls: value.completedLogicalCalls,
+    completedProviderRequests: value.completedProviderRequests,
+    completedProvider429s: value.completedProvider429s,
+    completeThroughAttempt: value.completeThroughAttempt,
+    consistent: value.consistent
+  };
+}
 function optionalFiniteNumber(value) {
   const normalized = finiteNumber(value);
   return normalized === null ? void 0 : normalized;
@@ -5431,6 +5503,9 @@ function normalizePlayRunLedgerStatus(value) {
       return "unknown";
   }
 }
+function isTerminalPlayRunLedgerStatus(status) {
+  return TERMINAL_STATUSES.has(status);
+}
 function summarizeRunRowOutcomes(snapshot) {
   let completedRows = 0;
   let failedRows = 0;
@@ -5565,6 +5640,10 @@ function normalizePlayRunLedgerSnapshot(value, fallback) {
   const error = Object.prototype.hasOwnProperty.call(value, "error") ? optionalNullableString(value.error) ?? null : fallback.error ?? null;
   const rawTail = Array.isArray(value.logTail) ? value.logTail : value.logs;
   const logTail = Array.isArray(rawTail) ? rawTail.filter((line) => typeof line === "string") : [];
+  const workCounters = normalizeWorkCounters(value.workCounters);
+  const terminalWorkCounterSegment = normalizePlayRunLedgerTerminalWorkCounterSegment(
+    value.terminalWorkCounterSegment
+  );
   return {
     runId: optionalString(value.runId) ?? fallback.runId,
     playName: optionalNullableString(value.playName) ?? fallback.playName ?? null,
@@ -5587,6 +5666,8 @@ function normalizePlayRunLedgerSnapshot(value, fallback) {
       (activityId) => typeof activityId === "string" && Boolean(activitiesById[activityId])
     ),
     activitiesById,
+    ...workCounters ? { workCounters } : {},
+    ...terminalWorkCounterSegment ? { terminalWorkCounterSegment } : {},
     logTail: logTail.slice(-LOG_TAIL_LIMIT),
     // Snapshots persisted before totalLogCount existed only know the retained
     // tail, so the best lower bound for the cumulative count is the tail size.
@@ -5894,6 +5975,13 @@ function buildSnapshotFromLedger(snapshot) {
   const liveStatus = normalizePlayRunLiveStatus(snapshot.status);
   const terminalRowOutcomes = isTerminalPlayRunLiveStatus(liveStatus) ? summarizeRunRowOutcomes(snapshot) : null;
   const rowOutcomes = terminalRowOutcomes && (Object.keys(snapshot.stepsById).length > 0 || terminalRowOutcomes.totalRows > 0 || (terminalRowOutcomes.supersededRows ?? 0) > 0) ? terminalRowOutcomes : null;
+  const workCounters = snapshot.workCounters;
+  const calls = workCounters ? {
+    logicalCalls: workCounters.completedLogicalCalls + workCounters.logicalCalls,
+    providerRequests: workCounters.completedProviderRequests + workCounters.providerRequests,
+    provider429s: workCounters.completedProvider429s + workCounters.provider429s,
+    confirmed: isTerminalPlayRunLiveStatus(liveStatus) && hasConfirmedPlayRunLedgerWorkCounters(snapshot)
+  } : null;
   return {
     runId: snapshot.runId,
     status: liveStatus,
@@ -5918,7 +6006,10 @@ function buildSnapshotFromLedger(snapshot) {
     activeActivity: snapshot.activeActivityId ? snapshot.activitiesById[snapshot.activeActivityId] ?? null : null,
     nodeStates,
     activeNodeId: snapshot.activeStepId ?? null,
-    ...rowOutcomes ? { rowOutcomes } : {}
+    ...rowOutcomes ? { rowOutcomes } : {},
+    ...calls && Object.values(calls).every(
+      (value) => typeof value === "boolean" || Number.isSafeInteger(value)
+    ) ? { calls } : {}
   };
 }
 function buildPlayRunStatusSnapshot(input2) {
@@ -25044,6 +25135,15 @@ function getProgressLinesFromLiveEvent(event) {
       `progress ${formatProgressLabel(record3.nodeId ?? progress.artifactTableNamespace)}: ${counts}${messageSuffix}`
     );
   }
+  const calls = readRecord(payload.calls);
+  const callCounts = calls ? [calls.logicalCalls, calls.providerRequests, calls.provider429s] : [];
+  if (callCounts.length === 3 && callCounts.every(
+    (count) => typeof count === "number" && Number.isSafeInteger(count) && count >= 0
+  )) {
+    lines.push(
+      `progress calls: ${formatInteger(callCounts[0])} logical, ${formatInteger(callCounts[1])} provider requests, ${formatInteger(callCounts[2])} provider 429s${calls?.confirmed === true ? "" : " (observed)"}`
+    );
+  }
   const rowOutcomes = readRowOutcomeSummary({
     rowOutcomes: payload.rowOutcomes
   });
@@ -50084,7 +50184,7 @@ async function searchTools(queryInput, options = {}) {
     tools: result.tools.slice(0, 8).map(compactTool)
   } : result;
   printCommandEnvelope(payload, {
-    json: options.json || shouldEmitJson()
+    json: options.json === true
   });
   return 0;
 }
@@ -50313,11 +50413,13 @@ Notes:
   Use a provider name in the query; --prefix is not a supported option.
   The grep alias is the same ranked retrieval surface with a more literal name
   for agents that are filtering a registry rather than choosing a workflow.
+  Search prints a readable result list by default, piped or not, and that is
+  the recommended form. Pass --json only when a program parses the result.
 
 Examples:
-  deepline tools search email --limit 10 --json
-  deepline tools search email --limit 10 --offset 10 --json
-  deepline tools search linkedin --task "I have 200 LinkedIn profile URLs and need each person's current title and company" --json
+  deepline tools search email --limit 10
+  deepline tools search email --limit 10 --offset 10
+  deepline tools search linkedin --task "I have 200 LinkedIn profile URLs and need each person's current title and company"
   deepline tools search --categories company_search --search_terms "investors,funding"
   deepline tools grep "company enrichment" --categories enrichment --json
   deepline tools search verifier --search-mode v2 --json
@@ -50331,7 +50433,7 @@ Examples:
   ).option("--search-terms <terms>", "Alias for --search_terms").option(
     "--task <sentence>",
     "What you are trying to accomplish: input you have -> result you need"
-  ).option("--limit <count>", "Maximum ranked results to return (1-50)").option("--offset <count>", "Zero-based ranked result offset").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output. Also automatic when stdout is piped").action(async (query, options) => {
+  ).option("--limit <count>", "Maximum ranked results to return (1-50)").option("--offset <count>", "Zero-based ranked result offset").option("--search-mode <mode>", "Ranked search mode: v1 or v2").option("--include-search-debug", "Include ranked search debug metadata").option("--compact", "Drop verbose fields from JSON output").option("--json", "Emit JSON output instead of the readable default").action(async (query, options) => {
     process.exitCode = await searchTools(query, {
       json: options.json,
       compact: options.compact,