deepline 0.3.224 → 0.3.226

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

@@ -3401,6 +3401,9 @@ export class DeeplineClient {
     if (options.searchTerms?.trim()) {
       params.set('search_terms', options.searchTerms.trim());
     }
+    if (options.task?.trim()) {
+      params.set('task', options.task.trim());
+    }
     return this.http.get<ToolSearchResult>(
       `/api/v2/tools/search?${params.toString()}`,
     );

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.224',
+  version: '0.3.226',
   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/types.ts

@@ -476,6 +476,8 @@ export interface ToolSearchOptions {
   categories?: string;
   /** Optional explicit search terms used by agent/CLI callers. */
   searchTerms?: string;
+  /** One sentence: the input you have and the result you need (not the query restated). */
+  task?: string;
   /** Search algorithm/version. Defaults to the current ranked mode. */
   searchMode?: 'v1' | 'v2';
   /** Include backend debug metadata in the search response. */

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

@@ -51,9 +51,11 @@ import {
 import { PLAY_RUNTIME_API_COMPAT_PATH } from './/runtime-api-paths';
 import {
   buildRunLedgerEventsIdempotencyKey,
+  isRunLedgerProjectionMismatchDiagnostic,
   isRunLedgerProjectionLeaseLostReason,
   type RunLedgerProjectionChunk,
   type RunLedgerProjectionLeaseLostReason,
+  type RunLedgerProjectionMismatchDiagnostic,
 } from './run-ledger-projection-contract';
 import { partitionRunEventsForAppRuntime } from './run-ledger-event-transport';
 import {
@@ -851,6 +853,21 @@ function appRuntimeFailureReason(
   }
 }
 
+function appRuntimeProjectionMismatch(
+  responseCode: string | null,
+  body: string,
+): RunLedgerProjectionMismatchDiagnostic | null {
+  if (responseCode !== 'RUN_LEDGER_DELIVERY_LEASE_LOST') return null;
+  try {
+    const parsed = JSON.parse(body) as { projectionMismatch?: unknown };
+    return isRunLedgerProjectionMismatchDiagnostic(parsed.projectionMismatch)
+      ? parsed.projectionMismatch
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 export function isTransientAppRuntimeFailureBody(body: string): boolean {
   return /WorkerOverloaded|"\s*code\s*"\s*:\s*"\s*InternalServerError\s*"|Your request couldn't be completed\. Try again later\.|timeout exceeded when trying to connect|timed out|fetch failed|ECONNRESET|ECONNREFUSED|UND_ERR_CONNECT_TIMEOUT|tuple concurrently updated|RUNTIME_SCHEDULER_(?:SATURATED|UNAVAILABLE|SCHEMA_NOT_READY)|Runtime scheduler DB pool is saturated|Runtime scheduler DB circuit breaker is open|Runtime scheduler schema .* is not ready|OptimisticConcurrencyControlFailure|changed while this mutation was being run|Documents read from or written to the .* table changed while this mutation/i.test(
     body,
@@ -1264,6 +1281,7 @@ export class AppRuntimeApiResponseError extends Error {
   readonly status: number;
   readonly code: string | null;
   readonly failureReason: RunLedgerProjectionLeaseLostReason | null;
+  readonly projectionMismatch: RunLedgerProjectionMismatchDiagnostic | null;
   readonly requestId: string | null;
   readonly retryable: boolean;
   /** Server-requested delay, retained for durable callers after local retries end. */
@@ -1275,6 +1293,7 @@ export class AppRuntimeApiResponseError extends Error {
     status: number;
     code?: string | null;
     failureReason?: RunLedgerProjectionLeaseLostReason | null;
+    projectionMismatch?: RunLedgerProjectionMismatchDiagnostic | null;
     requestId?: string | null;
     retryable: boolean;
     retryAfterMs?: number | null;
@@ -1292,6 +1311,7 @@ export class AppRuntimeApiResponseError extends Error {
     this.status = input.status;
     this.code = input.code?.trim() || null;
     this.failureReason = input.failureReason ?? null;
+    this.projectionMismatch = input.projectionMismatch ?? null;
     this.requestId = input.requestId?.trim() || null;
     this.retryable = input.retryable;
     this.retryAfterMs =
@@ -1757,6 +1777,7 @@ async function postAppRuntimeApi<TResponse>(
       status: response.status,
       code,
       failureReason: appRuntimeFailureReason(code, responseText),
+      projectionMismatch: appRuntimeProjectionMismatch(code, responseText),
       requestId,
       // The structured response is authoritative even for a 5xx. Retrying an
       // explicitly deterministic database failure here turns one rejected SQL

package/dist/bundling-sources/shared_libs/play-runtime/run-ledger-projection-contract.ts

@@ -45,6 +45,124 @@ export const RUN_LEDGER_PROJECTION_LEASE_LOST_REASONS = [
   'projected_events_mismatch',
 ] as const;
 
+export const RUN_LEDGER_PROJECTION_MISMATCH_KINDS = [
+  'expected_chunk_unavailable',
+  'event_count_mismatch',
+  'event_content_mismatch',
+] as const;
+
+export const RUN_LEDGER_PROJECTION_MISMATCH_FIELDS = [
+  'type',
+  'runId',
+  'occurredAt',
+  'source',
+  'opaque',
+  'payload',
+  'seq',
+  'status',
+  'playName',
+  'runtimeBackend',
+  'triggerSource',
+  'inputSummary',
+  'definitionScope',
+  'result',
+  'resultSummary',
+  'error',
+  'errorSummary',
+  'retryAfterMs',
+  'waitKind',
+  'waitUntil',
+  'nodeId',
+  'progress',
+  'stepId',
+  'toolId',
+  'provider',
+  'operation',
+  'lines',
+  'channelOffset',
+  'producerAttempt',
+  'other',
+] as const;
+
+export type RunLedgerProjectionMismatchKind =
+  (typeof RUN_LEDGER_PROJECTION_MISMATCH_KINDS)[number];
+
+export type RunLedgerProjectionMismatchField =
+  (typeof RUN_LEDGER_PROJECTION_MISMATCH_FIELDS)[number];
+
+/** Payload-free comparison facts safe to persist in the operator diagnostics. */
+export type RunLedgerProjectionMismatchDiagnostic = {
+  kind: RunLedgerProjectionMismatchKind;
+  expectedEventCount: number | null;
+  projectedEventCount: number;
+  chunkIndex: number | null;
+  chunkCount: number | null;
+  firstMismatchIndex: number | null;
+  eventTypeMatches: boolean | null;
+  mismatchedFields: RunLedgerProjectionMismatchField[];
+};
+
+export function isRunLedgerProjectionMismatchDiagnostic(
+  value: unknown,
+): value is RunLedgerProjectionMismatchDiagnostic {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const candidate = value as Record<string, unknown>;
+  const diagnosticKeys = [
+    'kind',
+    'expectedEventCount',
+    'projectedEventCount',
+    'chunkIndex',
+    'chunkCount',
+    'firstMismatchIndex',
+    'eventTypeMatches',
+    'mismatchedFields',
+  ];
+  const keys = Object.keys(candidate);
+  if (
+    keys.length !== diagnosticKeys.length ||
+    keys.some((key) => !diagnosticKeys.includes(key))
+  ) {
+    return false;
+  }
+  return (
+    typeof candidate.kind === 'string' &&
+    RUN_LEDGER_PROJECTION_MISMATCH_KINDS.includes(
+      candidate.kind as RunLedgerProjectionMismatchKind,
+    ) &&
+    (candidate.expectedEventCount === null ||
+      (Number.isSafeInteger(candidate.expectedEventCount) &&
+        Number(candidate.expectedEventCount) >= 0)) &&
+    Number.isSafeInteger(candidate.projectedEventCount) &&
+    Number(candidate.projectedEventCount) >= 0 &&
+    (candidate.chunkIndex === null ||
+      (Number.isSafeInteger(candidate.chunkIndex) &&
+        Number(candidate.chunkIndex) >= 0)) &&
+    (candidate.chunkCount === null ||
+      (Number.isSafeInteger(candidate.chunkCount) &&
+        Number(candidate.chunkCount) > 1)) &&
+    ((candidate.chunkIndex === null && candidate.chunkCount === null) ||
+      (Number.isSafeInteger(candidate.chunkIndex) &&
+        Number.isSafeInteger(candidate.chunkCount) &&
+        Number(candidate.chunkIndex) < Number(candidate.chunkCount))) &&
+    (candidate.firstMismatchIndex === null ||
+      (Number.isSafeInteger(candidate.firstMismatchIndex) &&
+        Number(candidate.firstMismatchIndex) >= 0)) &&
+    (candidate.eventTypeMatches === null ||
+      typeof candidate.eventTypeMatches === 'boolean') &&
+    Array.isArray(candidate.mismatchedFields) &&
+    candidate.mismatchedFields.length <= 8 &&
+    candidate.mismatchedFields.every(
+      (field) =>
+        typeof field === 'string' &&
+        RUN_LEDGER_PROJECTION_MISMATCH_FIELDS.includes(
+          field as RunLedgerProjectionMismatchField,
+        ),
+    ) &&
+    new Set(candidate.mismatchedFields).size ===
+      candidate.mismatchedFields.length
+  );
+}
+
 export type RunLedgerProjectionLeaseLostReason =
   (typeof RUN_LEDGER_PROJECTION_LEASE_LOST_REASONS)[number];
 
@@ -61,13 +179,16 @@ export function isRunLedgerProjectionLeaseLostReason(
 
 export class RunLedgerProjectionLeaseLostError extends Error {
   readonly reason: RunLedgerProjectionLeaseLostReason;
+  readonly projectionMismatch: RunLedgerProjectionMismatchDiagnostic | null;
 
   constructor(
     reason: RunLedgerProjectionLeaseLostReason = 'delivery_lease_not_current',
+    projectionMismatch: RunLedgerProjectionMismatchDiagnostic | null = null,
   ) {
     super('Run Ledger projection requires the current outbox delivery lease.');
     this.name = 'RunLedgerProjectionLeaseLostError';
     this.reason = reason;
+    this.projectionMismatch = projectionMismatch;
   }
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/run-ledger-projection-diagnostics.ts

@@ -0,0 +1,151 @@
+import { stableStringify } from '../plays/row-identity';
+import type {
+  AcceptedPlayRunLedgerEvent,
+  PlayRunLedgerIngressEvent,
+} from './run-ledger';
+import { isPlayRunLedgerOpaqueEvent } from './run-ledger';
+import {
+  RUN_LEDGER_PROJECTION_MISMATCH_FIELDS,
+  type RunLedgerProjectionChunk,
+  type RunLedgerProjectionMismatchDiagnostic,
+  type RunLedgerProjectionMismatchField,
+} from './run-ledger-projection-contract';
+
+type ComparableRunLedgerEvent =
+  | AcceptedPlayRunLedgerEvent
+  | PlayRunLedgerIngressEvent;
+
+/**
+ * A newer app may receive a projection from a worker that predates optional
+ * wait metadata. Normalize only those absent fields before the exact compare.
+ */
+function normalizeLegacyRunWaitingProjectionFields(
+  projectedEvents: readonly AcceptedPlayRunLedgerEvent[],
+  expectedEvents: readonly ComparableRunLedgerEvent[],
+): AcceptedPlayRunLedgerEvent[] {
+  return projectedEvents.map((event, index) => {
+    const expected = expectedEvents[index];
+    if (
+      isPlayRunLedgerOpaqueEvent(event) ||
+      event.type !== 'run.waiting' ||
+      expected?.type !== 'run.waiting' ||
+      ('opaque' in expected && expected.opaque === true)
+    ) {
+      return event;
+    }
+    const expectedEvent = expected as Record<string, unknown>;
+    const expectedWaitKind = expectedEvent.waitKind;
+    const expectedWaitUntil = expectedEvent.waitUntil;
+    return {
+      ...event,
+      ...(event.waitKind === undefined &&
+      (typeof expectedWaitKind === 'string' || expectedWaitKind === null)
+        ? { waitKind: expectedWaitKind }
+        : {}),
+      ...(event.waitUntil === undefined &&
+      (typeof expectedWaitUntil === 'number' || expectedWaitUntil === null)
+        ? { waitUntil: expectedWaitUntil }
+        : {}),
+    };
+  });
+}
+
+function eventType(event: ComparableRunLedgerEvent | undefined): string | null {
+  if (!event) return null;
+  return typeof event.type === 'string'
+    ? event.type
+    : typeof event.key === 'string'
+      ? event.key
+      : null;
+}
+
+function safeMismatchedFields(
+  projected: ComparableRunLedgerEvent,
+  expected: ComparableRunLedgerEvent,
+): RunLedgerProjectionMismatchField[] {
+  const projectedRecord = projected as Record<string, unknown>;
+  const expectedRecord = expected as Record<string, unknown>;
+  const allowedFields = new Set<string>(RUN_LEDGER_PROJECTION_MISMATCH_FIELDS);
+  const fields = new Set<RunLedgerProjectionMismatchField>();
+  const keys = new Set([
+    ...Object.keys(projectedRecord),
+    ...Object.keys(expectedRecord),
+  ]);
+  for (const key of [...keys].sort()) {
+    if (
+      stableStringify(projectedRecord[key]) ===
+      stableStringify(expectedRecord[key])
+    ) {
+      continue;
+    }
+    fields.add(
+      allowedFields.has(key)
+        ? (key as RunLedgerProjectionMismatchField)
+        : 'other',
+    );
+    if (fields.size === 8) break;
+  }
+  return [...fields];
+}
+
+/**
+ * Compare one received chunk with its canonical outbox slice and return only
+ * bounded structural facts. Event values, IDs, and opaque payload keys never
+ * leave this module.
+ */
+export function runLedgerProjectionMismatch(input: {
+  projectedEvents: readonly AcceptedPlayRunLedgerEvent[];
+  expectedEvents: readonly ComparableRunLedgerEvent[] | null;
+  chunk?: RunLedgerProjectionChunk;
+}): RunLedgerProjectionMismatchDiagnostic | null {
+  const chunkIndex = input.chunk?.index ?? null;
+  const chunkCount = input.chunk?.count ?? null;
+  const projectedEventCount = input.projectedEvents.length;
+  if (input.expectedEvents === null) {
+    return {
+      kind: 'expected_chunk_unavailable',
+      expectedEventCount: null,
+      projectedEventCount,
+      chunkIndex,
+      chunkCount,
+      firstMismatchIndex: null,
+      eventTypeMatches: null,
+      mismatchedFields: [],
+    };
+  }
+
+  const normalizedProjectedEvents = normalizeLegacyRunWaitingProjectionFields(
+    input.projectedEvents,
+    input.expectedEvents,
+  );
+  const expectedEventCount = input.expectedEvents.length;
+  const sharedEventCount = Math.min(projectedEventCount, expectedEventCount);
+  for (let index = 0; index < sharedEventCount; index += 1) {
+    const projected = normalizedProjectedEvents[index]!;
+    const expected = input.expectedEvents[index]!;
+    if (stableStringify(projected) === stableStringify(expected)) continue;
+    return {
+      kind: 'event_content_mismatch',
+      expectedEventCount,
+      projectedEventCount,
+      chunkIndex,
+      chunkCount,
+      firstMismatchIndex: index,
+      eventTypeMatches: eventType(projected) === eventType(expected),
+      mismatchedFields: safeMismatchedFields(projected, expected),
+    };
+  }
+  if (projectedEventCount !== expectedEventCount) {
+    return {
+      kind: 'event_count_mismatch',
+      expectedEventCount,
+      projectedEventCount,
+      chunkIndex,
+      chunkCount,
+      firstMismatchIndex: sharedEventCount,
+      eventTypeMatches: null,
+      mismatchedFields: [],
+    };
+  }
+  return null;
+}

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

@@ -78,7 +78,6 @@ import {
 } from '../work-receipts';
 import type { PlayStaticPipeline } from '../../plays/static-pipeline';
 import {
-  isPlayRunLedgerOpaqueEvent,
   LOG_TAIL_LIMIT,
   type AcceptedPlayRunLedgerEvent,
   type PlayRunLedgerEvent,
@@ -98,9 +97,11 @@ import {
   RunLedgerProjectionLeaseLostError,
   type RunLedgerProjectionChunk,
   type RunLedgerProjectionLeaseLostReason,
+  type RunLedgerProjectionMismatchDiagnostic,
   buildRunLedgerStartIdempotencyKey,
   buildRunLedgerTerminalIdempotencyKey,
 } from '../run-ledger-projection-contract';
+import { runLedgerProjectionMismatch } from '../run-ledger-projection-diagnostics';
 import { selectRunEventsForAppRuntimeProjectionChunk } from '../run-ledger-event-transport';
 import {
   assertTerminalRunResultWithinLimit,
@@ -15938,64 +15939,6 @@ async function appendRunLedgerOutboxFact(
 
 export { RunLedgerProjectionLeaseLostError } from '../run-ledger-projection-contract';
 
-/**
- * A newer app can receive a projection from a worker that predates optional
- * wait metadata. Treat only those absent fields as their canonical values;
- * lease identity, event ordering, and every field the worker did send remain
- * exact.
- */
-function normalizeLegacyRunWaitingProjectionFields(
-  projectedEvents: readonly AcceptedPlayRunLedgerEvent[],
-  expectedEvents: readonly (
-    | AcceptedPlayRunLedgerEvent
-    | PlayRunLedgerIngressEvent
-  )[],
-): AcceptedPlayRunLedgerEvent[] {
-  return projectedEvents.map((event, index) => {
-    const expected = expectedEvents[index];
-    if (
-      isPlayRunLedgerOpaqueEvent(event) ||
-      event.type !== 'run.waiting' ||
-      expected?.type !== 'run.waiting' ||
-      ('opaque' in expected && expected.opaque === true)
-    ) {
-      return event;
-    }
-    const expectedEvent = expected as Record<string, unknown>;
-    const expectedWaitKind = expectedEvent.waitKind;
-    const expectedWaitUntil = expectedEvent.waitUntil;
-    return {
-      ...event,
-      ...(event.waitKind === undefined &&
-      (typeof expectedWaitKind === 'string' || expectedWaitKind === null)
-        ? { waitKind: expectedWaitKind }
-        : {}),
-      ...(event.waitUntil === undefined &&
-      (typeof expectedWaitUntil === 'number' || expectedWaitUntil === null)
-        ? { waitUntil: expectedWaitUntil }
-        : {}),
-    };
-  });
-}
-
-function runLedgerProjectionMatchesCanonicalPrefix(
-  projectedEvents: readonly AcceptedPlayRunLedgerEvent[],
-  expectedEvents: readonly (
-    | AcceptedPlayRunLedgerEvent
-    | PlayRunLedgerIngressEvent
-  )[],
-): boolean {
-  if (projectedEvents.length !== expectedEvents.length) return false;
-  return (
-    stableStringify(
-      normalizeLegacyRunWaitingProjectionFields(
-        projectedEvents,
-        expectedEvents,
-      ),
-    ) === stableStringify(expectedEvents)
-  );
-}
-
 /** Extend only our still-live lease before another bounded transport piece. */
 export async function renewPostgresRunLedgerDelivery(
   client: PostgresSchedulerQueryClient,
@@ -16183,16 +16126,17 @@ export async function assertPostgresRunLedgerDelivery(
           ? input.sanitizeExpectedProjectionEvents(prefixEvents)
           : prefixEvents;
       }
-      if (
-        expectedProjectionEvents !== undefined &&
-        runLedgerProjectionMatchesCanonicalPrefix(
-          input.projectedEvents,
-          expectedProjectionEvents,
-        )
-      ) {
-        return;
-      }
-      throw new RunLedgerProjectionLeaseLostError('projected_events_mismatch');
+      const projectionMismatch: RunLedgerProjectionMismatchDiagnostic | null =
+        runLedgerProjectionMismatch({
+          projectedEvents: input.projectedEvents,
+          expectedEvents: expectedProjectionEvents ?? null,
+          ...(input.projectionChunk ? { chunk: input.projectionChunk } : {}),
+        });
+      if (projectionMismatch === null) return;
+      throw new RunLedgerProjectionLeaseLostError(
+        'projected_events_mismatch',
+        projectionMismatch,
+      );
     }
 
     if (
@@ -16728,6 +16672,7 @@ function runLedgerDeliveryFailure(input: { error: unknown }): {
   status: number | null;
   retryable: boolean;
   failureReason: RunLedgerProjectionLeaseLostReason | null;
+  projectionMismatch: RunLedgerProjectionMismatchDiagnostic | null;
   retryAfterMs: number | null;
 } {
   if (input.error instanceof AppRuntimeApiResponseError) {
@@ -16748,6 +16693,7 @@ function runLedgerDeliveryFailure(input: { error: unknown }): {
       status: input.error.status,
       retryable,
       failureReason: input.error.failureReason,
+      projectionMismatch: input.error.projectionMismatch,
       retryAfterMs:
         input.error.retryAfterMs === null
           ? null
@@ -16764,6 +16710,7 @@ function runLedgerDeliveryFailure(input: { error: unknown }): {
       status: null,
       retryable: true,
       failureReason: null,
+      projectionMismatch: null,
       retryAfterMs: null,
     };
   }
@@ -16775,6 +16722,7 @@ function runLedgerDeliveryFailure(input: { error: unknown }): {
     status: null,
     retryable: true,
     failureReason: null,
+    projectionMismatch: null,
     retryAfterMs: null,
   };
 }
@@ -16874,6 +16822,9 @@ export async function settlePostgresSchedulerOutboxFailure(
         ...(failure.failureReason
           ? { failureReason: failure.failureReason }
           : {}),
+        ...(failure.projectionMismatch
+          ? { projectionMismatch: failure.projectionMismatch }
+          : {}),
         retryAfterMs: failure.retryAfterMs,
         recordedAt: new Date().toISOString(),
       }),

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.224",
+  version: "0.3.226",
   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
@@ -7603,6 +7603,9 @@ var DeeplineClient = class _DeeplineClient {
     if (options.searchTerms?.trim()) {
       params.set("search_terms", options.searchTerms.trim());
     }
+    if (options.task?.trim()) {
+      params.set("task", options.task.trim());
+    }
     return this.http.get(
       `/api/v2/tools/search?${params.toString()}`
     );
@@ -50068,6 +50071,7 @@ async function searchTools(queryInput, options = {}) {
     query,
     categories: options.categories,
     searchTerms: options.searchTerms,
+    task: options.task,
     limit: options.limit,
     offset: options.offset,
     searchMode: options.searchMode,
@@ -50303,6 +50307,9 @@ Notes:
   supplied. Providing neither is a usage error. Both filters accept
   comma-separated values. Use --limit and --offset to page through ranked
   results (limit 1-50, offset is zero-based); JSON includes next_offset.
+  Pass --task with one sentence on what you are trying to accomplish right
+  now: the input you have and the result you need, not a restatement of the
+  query. It materially improves ranking, especially for short queries.
   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.
@@ -50310,6 +50317,7 @@ Notes:
 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 --categories company_search --search_terms "investors,funding"
   deepline tools grep "company enrichment" --categories enrichment --json
   deepline tools search verifier --search-mode v2 --json
@@ -50320,7 +50328,10 @@ Examples:
   ).option(
     "--search_terms <terms>",
     "Comma-separated structured search terms; may be used without a query"
-  ).option("--search-terms <terms>", "Alias for --search_terms").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("--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) => {
     process.exitCode = await searchTools(query, {
       json: options.json,
       compact: options.compact,
@@ -50328,6 +50339,7 @@ Examples:
       offset: options.offset !== void 0 ? Number.parseInt(options.offset, 10) : void 0,
       categories: options.categories,
       searchTerms: options.searchTerms ?? options.search_terms,
+      task: options.task,
       searchMode: options.searchMode === "v1" || options.searchMode === "v2" ? options.searchMode : void 0,
       includeSearchDebug: Boolean(options.includeSearchDebug)
     });

package/dist/cli/index.mjs

@@ -3046,7 +3046,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.224",
+  version: "0.3.226",
   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
@@ -7598,6 +7598,9 @@ var DeeplineClient = class _DeeplineClient {
     if (options.searchTerms?.trim()) {
       params.set("search_terms", options.searchTerms.trim());
     }
+    if (options.task?.trim()) {
+      params.set("task", options.task.trim());
+    }
     return this.http.get(
       `/api/v2/tools/search?${params.toString()}`
     );
@@ -50216,6 +50219,7 @@ async function searchTools(queryInput, options = {}) {
     query,
     categories: options.categories,
     searchTerms: options.searchTerms,
+    task: options.task,
     limit: options.limit,
     offset: options.offset,
     searchMode: options.searchMode,
@@ -50451,6 +50455,9 @@ Notes:
   supplied. Providing neither is a usage error. Both filters accept
   comma-separated values. Use --limit and --offset to page through ranked
   results (limit 1-50, offset is zero-based); JSON includes next_offset.
+  Pass --task with one sentence on what you are trying to accomplish right
+  now: the input you have and the result you need, not a restatement of the
+  query. It materially improves ranking, especially for short queries.
   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.
@@ -50458,6 +50465,7 @@ Notes:
 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 --categories company_search --search_terms "investors,funding"
   deepline tools grep "company enrichment" --categories enrichment --json
   deepline tools search verifier --search-mode v2 --json
@@ -50468,7 +50476,10 @@ Examples:
   ).option(
     "--search_terms <terms>",
     "Comma-separated structured search terms; may be used without a query"
-  ).option("--search-terms <terms>", "Alias for --search_terms").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("--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) => {
     process.exitCode = await searchTools(query, {
       json: options.json,
       compact: options.compact,
@@ -50476,6 +50487,7 @@ Examples:
       offset: options.offset !== void 0 ? Number.parseInt(options.offset, 10) : void 0,
       categories: options.categories,
       searchTerms: options.searchTerms ?? options.search_terms,
+      task: options.task,
       searchMode: options.searchMode === "v1" || options.searchMode === "v2" ? options.searchMode : void 0,
       includeSearchDebug: Boolean(options.includeSearchDebug)
     });

package/dist/index.d.mts

@@ -1492,6 +1492,8 @@ interface ToolSearchOptions {
     categories?: string;
     /** Optional explicit search terms used by agent/CLI callers. */
     searchTerms?: string;
+    /** One sentence: the input you have and the result you need (not the query restated). */
+    task?: string;
     /** Search algorithm/version. Defaults to the current ranked mode. */
     searchMode?: 'v1' | 'v2';
     /** Include backend debug metadata in the search response. */

package/dist/index.d.ts

@@ -1492,6 +1492,8 @@ interface ToolSearchOptions {
     categories?: string;
     /** Optional explicit search terms used by agent/CLI callers. */
     searchTerms?: string;
+    /** One sentence: the input you have and the result you need (not the query restated). */
+    task?: string;
     /** Search algorithm/version. Defaults to the current ranked mode. */
     searchMode?: 'v1' | 'v2';
     /** Include backend debug metadata in the search response. */

package/dist/index.js

@@ -864,7 +864,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.224",
+  version: "0.3.226",
   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
@@ -5275,6 +5275,9 @@ var DeeplineClient = class _DeeplineClient {
     if (options.searchTerms?.trim()) {
       params.set("search_terms", options.searchTerms.trim());
     }
+    if (options.task?.trim()) {
+      params.set("task", options.task.trim());
+    }
     return this.http.get(
       `/api/v2/tools/search?${params.toString()}`
     );

package/dist/index.mjs

@@ -768,7 +768,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.224",
+  version: "0.3.226",
   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
@@ -5179,6 +5179,9 @@ var DeeplineClient = class _DeeplineClient {
     if (options.searchTerms?.trim()) {
       params.set("search_terms", options.searchTerms.trim());
     }
+    if (options.task?.trim()) {
+      params.set("task", options.task.trim());
+    }
     return this.http.get(
       `/api/v2/tools/search?${params.toString()}`
     );

package/dist/install-integrity.json

@@ -295,6 +295,7 @@
     "dist/bundling-sources/shared_libs/play-runtime/run-identity.ts",
     "dist/bundling-sources/shared_libs/play-runtime/run-ledger-event-transport.ts",
     "dist/bundling-sources/shared_libs/play-runtime/run-ledger-projection-contract.ts",
+    "dist/bundling-sources/shared_libs/play-runtime/run-ledger-projection-diagnostics.ts",
     "dist/bundling-sources/shared_libs/play-runtime/run-ledger.ts",
     "dist/bundling-sources/shared_libs/play-runtime/run-lifecycle-policy.ts",
     "dist/bundling-sources/shared_libs/play-runtime/run-log-buffer.ts",

package/dist/release.d.mts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.224";
+    readonly version: "0.3.226";
     readonly 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.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.d.ts

@@ -149,7 +149,7 @@ type SdkRelease = {
     supportPolicy: SdkSupportPolicy;
 };
 declare const SDK_RELEASE: {
-    readonly version: "0.3.224";
+    readonly version: "0.3.226";
     readonly 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.";
     readonly packageCapabilities: {
         readonly updatePreferences: 1;

package/dist/release.js

@@ -74,7 +74,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.224",
+  version: "0.3.226",
   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

package/dist/release.mjs

@@ -48,7 +48,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.224",
+  version: "0.3.226",
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.224",
+  "version": "0.3.226",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",