deepline 0.3.302 → 0.3.304

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.302',
+  version: '0.3.304',
   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/shared_libs/play-runtime/app-runtime-api.ts

@@ -2452,7 +2452,9 @@ export async function projectRunEventsViaAppRuntime(
   const batches = partitionRunEventsForAppRuntime(input.events);
   const receiptBatch = runLedgerReceiptBatchIndex(batches);
   for (const [index, events] of batches.entries()) {
+    const beforeBatchStartedAt = Date.now();
     await input.beforeBatch();
+    const beforeBatchMs = Math.max(0, Date.now() - beforeBatchStartedAt);
     // Retain the original receipt for the terminal (or final) piece so an acknowledged
     // legacy delivery stays acknowledged across the reader rollout.
     const idempotencyKey =
@@ -2476,7 +2478,16 @@ export async function projectRunEventsViaAppRuntime(
     };
     // The durable outbox owns recovery; this helper does not retry OCCs or
     // other delivery failures inside an already-leased invocation.
-    const deliveryContext = { ...context, retryPolicy: 'none' as const };
+    let responseMeta: RuntimeApiResponseMeta | null = null;
+    const deliveryContext = {
+      ...context,
+      retryPolicy: 'none' as const,
+      onResponseMeta(meta: RuntimeApiResponseMeta) {
+        context.onResponseMeta?.(meta);
+        if (meta.action === 'project_run_events') responseMeta = meta;
+      },
+    };
+    const requestStartedAt = Date.now();
     try {
       await postAppRuntimeApi(deliveryContext, {
         action: 'project_run_events',
@@ -2501,6 +2512,25 @@ export async function projectRunEventsViaAppRuntime(
         ...request,
       });
     }
+    const requestWallMs = Math.max(0, Date.now() - requestStartedAt);
+    if (beforeBatchMs >= 500 || requestWallMs >= 500) {
+      const observedResponse = responseMeta as RuntimeApiResponseMeta | null;
+      console.info('[run-ledger-outbox.project_transport_slow]', {
+        runId: input.playId,
+        eventCount: events.length,
+        batchIndex: index,
+        batchCount: batches.length,
+        beforeBatchMs,
+        requestWallMs,
+        roundTripMs: observedResponse?.roundTripMs ?? null,
+        requestId: observedResponse?.requestId ?? null,
+        requestBodyRawBytes: observedResponse?.requestBodyRawBytes ?? null,
+        requestBodyWireBytes: observedResponse?.requestBodyWireBytes ?? null,
+        requestBodySerializeMs:
+          observedResponse?.requestBodySerializeMs ?? null,
+        requestBodyPackMs: observedResponse?.requestBodyPackMs ?? null,
+      });
+    }
   }
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/execute-server-timing.ts

@@ -33,6 +33,36 @@ export const EXECUTE_SERVER_TIMING_STAGES = [
   'execute',
   'identity',
   'usage_schedule',
+  // Managed AI inference slices: `ai_prepare` includes request preparation and
+  // contains `ai_billing_authorize`; `ai_provider_work_start` is the durable
+  // pre-call transition; `ai_gateway_first_output` is the time to the first
+  // model-output part (excluding SDK control chunks); and
+  // `ai_gateway_stream_wall` is the end-to-end SDK stream
+  // collection wall. Stream wall includes awaited finish callbacks, so evidence
+  // persistence and settlement overlap it. First-output and stream wall both
+  // include Gateway/network/upstream time; neither claims provider-internal
+  // model time.
+  'ai_prepare',
+  'ai_billing_authorize',
+  'ai_provider_work_start',
+  'ai_gateway_first_output',
+  'ai_gateway_stream_wall',
+  'ai_generation_evidence_persist',
+  'ai_billing_settlement',
+  'ai_output_canonicalization',
+  'ai_result_persist',
+  // Provider HTTP slices are only nonzero for calls that take this path:
+  // admission; `provider_fetch_headers` until response headers arrive (or
+  // `provider_fetch_error_wait` for a rejected fetch); retry backoff; body
+  // read, JSON parse, result transform and output normalization are separate.
+  'provider_admission',
+  'provider_fetch_headers',
+  'provider_fetch_error_wait',
+  'provider_retry_wait',
+  'provider_body_read',
+  'provider_json_parse',
+  'provider_result_transform',
+  'provider_output_normalization',
   'total',
   // The execution gateway preserves these disjoint stages beside the app
   // handler's stages. They are deliberately part of this small, additive

package/dist/bundling-sources/shared_libs/play-runtime/resource-governor.ts

@@ -12,7 +12,10 @@ import type {
   ProviderConcurrencyGrant,
   ProviderPacingGrant,
 } from './governor/rate-state-backend';
-import type { ExecuteServerTiming } from './execute-server-timing';
+import type {
+  ExecuteServerTiming,
+  ExecuteServerTimingStage,
+} from './execute-server-timing';
 
 export type RuntimeResourceLease = WorkLease;
 export type RuntimeProviderPermit = ProviderPermit;
@@ -511,6 +514,29 @@ export type RuntimePhaseTiming = {
   ewmaMs: number | null;
 };
 
+const AI_INFERENCE_EXECUTE_STAGES = [
+  'ai_prepare',
+  'ai_billing_authorize',
+  'ai_provider_work_start',
+  'ai_gateway_first_output',
+  'ai_gateway_stream_wall',
+  'ai_generation_evidence_persist',
+  'ai_billing_settlement',
+  'ai_output_canonicalization',
+  'ai_result_persist',
+] as const satisfies readonly ExecuteServerTimingStage[];
+
+const PROVIDER_HTTP_EXECUTE_STAGES = [
+  'provider_admission',
+  'provider_fetch_headers',
+  'provider_fetch_error_wait',
+  'provider_retry_wait',
+  'provider_body_read',
+  'provider_json_parse',
+  'provider_result_transform',
+  'provider_output_normalization',
+] as const satisfies readonly ExecuteServerTimingStage[];
+
 /**
  * Selected execute-route stages for the same population as `fetchToHeaders`.
  * These are nested because they partition handler work inside that wall; they
@@ -523,6 +549,26 @@ export type RuntimeExecuteRouteTiming = {
   chargeOpenMs: number;
   fixtureLoadMs: number;
   executeMs: number;
+  /**
+   * Managed `ai_inference` stages, accumulated independently because each can
+   * observe a different request population. `count` is the number of requests
+   * with a non-zero `ai_prepare` marker. Stage counters include positive
+   * durations only: the header serializes milliseconds to three decimal
+   * places, so an absent stage cannot be distinguished from a duration
+   * rounded to zero. These slices overlap; in particular stream wall contains
+   * awaited evidence persistence and billing settlement.
+   */
+  aiInference?: RuntimeExecuteStageGroup<
+    (typeof AI_INFERENCE_EXECUTE_STAGES)[number]
+  >;
+  /**
+   * Deepline-owned HTTP provider stages. `count` is the number of requests
+   * with a non-zero provider-admission marker; each stage retains its own
+   * positive-duration denominator for rolling-build compatibility.
+   */
+  providerHttp?: RuntimeExecuteStageGroup<
+    (typeof PROVIDER_HTTP_EXECUTE_STAGES)[number]
+  >;
   /**
    * Where `chargeOpenMs` went, nested rather than summed: these are disjoint
    * slices of it, never independent phases. Present only when the deployed app
@@ -557,6 +603,18 @@ export type RuntimeExecuteRouteTiming = {
   };
 };
 
+/** Fixed-size run summary for one execute-route stage. */
+export type RuntimeExecuteStageTiming = {
+  count: number;
+  totalMs: number;
+  maxMs: number | null;
+};
+
+/** A fixed set of named execute stages with one run-level request count. */
+export type RuntimeExecuteStageGroup<Stage extends ExecuteServerTimingStage> = {
+  count: number;
+} & Record<Stage, RuntimeExecuteStageTiming>;
+
 /**
  * A compact, unitless sample aggregate. Provider permits use it for bucket
  * occupancy at admission, rather than mislabelling an in-flight count as ms.
@@ -854,6 +912,71 @@ function createPhaseTiming(): {
   };
 }
 
+function createExecuteStageAccumulator(): {
+  observe(value: number): void;
+  snapshot(): RuntimeExecuteStageTiming;
+} {
+  let count = 0;
+  let totalMs = 0;
+  let maxMs: number | null = null;
+  return {
+    observe(value) {
+      count += 1;
+      totalMs += value;
+      maxMs = maxMs === null ? value : Math.max(maxMs, value);
+    },
+    snapshot() {
+      return { count, totalMs, maxMs };
+    },
+  };
+}
+
+function createExecuteStageGroup<
+  const Stages extends readonly ExecuteServerTimingStage[],
+>(stages: Stages) {
+  type Stage = Stages[number];
+  // Keep the tuple's element type explicit through iteration. TypeScript can
+  // widen a generic readonly tuple to the full timing-stage union in loops,
+  // even though every value here came from this group's stage list.
+  const stageNames = stages as readonly Stage[];
+  const metrics = Object.fromEntries(
+    stageNames.map((stage) => [stage, createExecuteStageAccumulator()]),
+  ) as Record<Stage, ReturnType<typeof createExecuteStageAccumulator>>;
+  let count = 0;
+  return {
+    get count() {
+      return count;
+    },
+    observe(markerMs: number | null, timing: ExecuteServerTiming) {
+      // The execute header renders absent stages as zero, so zero cannot be
+      // attributed to an observed stage with confidence. The positive marker
+      // selects calls in this group; stage populations remain explicit.
+      if (markerMs === null || !Number.isFinite(markerMs) || markerMs <= 0) {
+        return;
+      }
+      count += 1;
+      for (const stage of stageNames) {
+        const durationMs = timing[stage];
+        if (
+          durationMs !== null &&
+          Number.isFinite(durationMs) &&
+          durationMs > 0
+        ) {
+          metrics[stage].observe(durationMs);
+        }
+      }
+    },
+    snapshot(): RuntimeExecuteStageGroup<Stage> {
+      return {
+        count,
+        ...Object.fromEntries(
+          stageNames.map((stage) => [stage, metrics[stage].snapshot()]),
+        ),
+      } as RuntimeExecuteStageGroup<Stage>;
+    },
+  };
+}
+
 function createSampleTiming(): {
   observe(value: number | null | undefined): void;
   snapshot(): RuntimeSampleTiming;
@@ -979,6 +1102,12 @@ export function createRuntimeResourceGovernor(input: {
     fixtureLoadMs: 0,
     executeMs: 0,
   };
+  const executeAiInference = createExecuteStageGroup(
+    AI_INFERENCE_EXECUTE_STAGES,
+  );
+  const executeProviderHttp = createExecuteStageGroup(
+    PROVIDER_HTTP_EXECUTE_STAGES,
+  );
   const executeChargeOpen = {
     count: 0,
     eligibilityMs: 0,
@@ -1288,6 +1417,14 @@ export function createRuntimeResourceGovernor(input: {
       executeRoute.chargeOpenMs += executeRouteTiming.charge_open;
       executeRoute.fixtureLoadMs += executeRouteTiming.fixture_load;
       executeRoute.executeMs += executeRouteTiming.execute;
+      executeAiInference.observe(
+        executeRouteTiming.ai_prepare,
+        executeRouteTiming,
+      );
+      executeProviderHttp.observe(
+        executeRouteTiming.provider_admission,
+        executeRouteTiming,
+      );
       // Same rule as the gateway block below: require the complete substage
       // set this app version emits, so an older build that reports only
       // `charge_open` does not silently contribute a partial split.
@@ -1734,6 +1871,12 @@ export function createRuntimeResourceGovernor(input: {
           ? {
               executeRoute: {
                 ...executeRoute,
+                ...(executeAiInference.count > 0
+                  ? { aiInference: executeAiInference.snapshot() }
+                  : {}),
+                ...(executeProviderHttp.count > 0
+                  ? { providerHttp: executeProviderHttp.snapshot() }
+                  : {}),
                 ...(executeChargeOpen.count > 0
                   ? { chargeOpen: { ...executeChargeOpen } }
                   : {}),

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

@@ -20733,6 +20733,7 @@ async function dispatchRunLedgerOutboxBatchWithScope(
       eventIds: events.map((event) => event.eventId),
       error: error instanceof Error ? error.message : String(error),
       code: failure.code,
+      responseStatus: failure.status,
       failureReason: failure.failureReason,
       ...(failure.projectionMismatch
         ? { projectionMismatch: failure.projectionMismatch }

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

@@ -1032,6 +1032,88 @@ export async function setRuntimeEventDeferredProjection(
   }
 }
 
+export type RuntimeEventProjectionModes = {
+  runtimeScope: string;
+  deferred: boolean | null;
+  independent: boolean | null;
+  unavailableReason:
+    | 'projection_mode_readers_missing'
+    | 'deferred_projection_reader_missing'
+    | 'independent_projection_reader_missing'
+    | null;
+};
+
+/** Read installed operator modes without scanning or changing the outbox. */
+export async function readRuntimeEventProjectionModes(
+  client: PostgresSchedulerQueryClient,
+  runtimeScope: string,
+): Promise<RuntimeEventProjectionModes> {
+  const scope = requiredScope(runtimeScope);
+  const schema = quoteIdent(scope);
+  const installed = await client.query<{
+    deferred_installed: boolean;
+    independent_installed: boolean;
+  }>(
+    `SELECT to_regprocedure($1) IS NOT NULL AS deferred_installed,
+            to_regprocedure($2) IS NOT NULL AS independent_installed`,
+    [
+      `${schema}.defer_runtime_event_projection()`,
+      `${schema}.independent_runtime_event_projection()`,
+    ],
+  );
+  const readers = installed.rows[0];
+  if (
+    !readers ||
+    typeof readers.deferred_installed !== 'boolean' ||
+    typeof readers.independent_installed !== 'boolean'
+  ) {
+    throw new Error('Runtime projection mode lookup returned no reader state.');
+  }
+  const unavailableReason = readers.deferred_installed
+    ? readers.independent_installed
+      ? null
+      : 'independent_projection_reader_missing'
+    : readers.independent_installed
+      ? 'deferred_projection_reader_missing'
+      : 'projection_mode_readers_missing';
+  if (!readers.deferred_installed && !readers.independent_installed) {
+    return {
+      runtimeScope: scope,
+      deferred: null,
+      independent: null,
+      unavailableReason,
+    };
+  }
+  // An absent function cannot appear in the SQL, even in an unselected CASE.
+  const deferredExpression = readers.deferred_installed
+    ? `${schema}.defer_runtime_event_projection()`
+    : 'NULL::boolean';
+  const independentExpression = readers.independent_installed
+    ? `${schema}.independent_runtime_event_projection()`
+    : 'NULL::boolean';
+  const result = await client.query<{
+    deferred: boolean | null;
+    independent: boolean | null;
+  }>(
+    `SELECT ${deferredExpression} AS deferred,
+            ${independentExpression} AS independent`,
+  );
+  const modes = result.rows[0];
+  if (
+    !modes ||
+    (readers.deferred_installed && typeof modes.deferred !== 'boolean') ||
+    (readers.independent_installed && typeof modes.independent !== 'boolean')
+  ) {
+    throw new Error('Runtime projection mode lookup returned invalid values.');
+  }
+  return {
+    runtimeScope: scope,
+    deferred: modes.deferred,
+    independent: modes.independent,
+    unavailableReason,
+  };
+}
+
 /** Operator state uses the same durable pending set as the outbox projector. */
 export async function inspectRuntimeEventProjection(
   client: PostgresSchedulerQueryClient,

package/dist/bundling-sources/shared_libs/plays/tool-response-contract.ts

@@ -23,6 +23,31 @@ export type ToolResponseContract =
 
 export type ToolResponseView = 'data' | 'rawV2';
 
+/** Authoring guidance shared by provider descriptions and the public CLI. */
+export const TOOL_RESPONSE_AUTHORING_GUIDANCE = {
+  prefer: [
+    'Use toolExecutionResult.extractedLists.<name>.get() only for declared extracted lists listed below.',
+    'Use toolExecutionResult.extractedValues.<name>.get() only for declared extracted values listed below. Values may be scalars or normalized objects such as EmailStatus; inspect each entry details.strategy and details.valueType.',
+    'Use toolExecutionResult.toolResponse.rawV2 for provider/tool-specific scalar fields, fields in outputSchema that are not declared extracted values, and debugging. Inspect the observed response envelope before selecting nested fields. For declared row/list outputs, use extractedLists.<name>.get().',
+    'toolResponse.rawV2 is the complete parsed and scrubbed provider response, including JSON:API included resources, cursors, links, and totals. It is not the original HTTP bytes or headers.',
+  ],
+  rawMeaning:
+    'Complete parsed and scrubbed provider response for provider/tool-specific scalar fields and debugging. Inspect its envelope before selecting nested fields. Declared row/list outputs should use extractedLists.<name>.get().',
+  invalidGetterHint:
+    'If TypeScript says an extractedValues/extractedLists property does not exist, that field is not a declared Deepline getter; inspect toolResponse.rawV2 for provider/tool-specific scalar fields, and use extractedLists.<name>.get() for declared row/list outputs.',
+  responseShape: {
+    canonicalResponse: 'toolResponse.rawV2',
+    nesting:
+      'rawV2 preserves the provider/tool adapter envelope. The payload may be at rawV2, rawV2.data, or rawV2.data.data; there is no universal unwrap depth. view: "data" does not flatten rawV2. Prefer declared getters; otherwise inspect the retained response from the same execution surface and assert the exact field path before bulk execution.',
+    outputSchema:
+      'outputSchema describes the declared normalized tool output, not an observed rawV2 envelope. Do not derive a rawV2 field path from it.',
+    extractorPaths:
+      'details.rawToolOutputPaths records compatibility extractor provenance, not copyable rawV2 paths. Use the getter expression; do not mechanically replace raw with rawV2.',
+    missingFields:
+      'An absent expected field is an extraction contract mismatch, not proof of a provider miss or invalid email. Keep legitimate no-result responses distinct from unexpected shapes.',
+  },
+} as const;
+
 export function isToolResponseContract(
   value: unknown,
 ): value is ToolResponseContract {

package/dist/cli/auth-UBWZC26A.js

@@ -0,0 +1,31 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+
+
+var _chunk7NQJDQPHjs = require('./chunk-7NQJDQPH.js');
+require('./chunk-BBXO7APG.js');
+require('./chunk-DOCDA2YP.js');
+require('./chunk-XNYIZMNQ.js');
+require('./chunk-ZQSQCHG3.js');
+require('./chunk-7P5AA3SN.js');
+require('./chunk-OG64RBAC.js');
+require('./chunk-COGTRVWW.js');
+
+
+
+
+
+
+
+
+
+
+
+exports.EXIT_WORKSPACE_MISMATCH = _chunk7NQJDQPHjs.EXIT_WORKSPACE_MISMATCH; exports.clearPendingClaim = _chunk7NQJDQPHjs.clearPendingClaim; exports.clearSatisfiedPendingClaim = _chunk7NQJDQPHjs.clearSatisfiedPendingClaim; exports.handleRegister = _chunk7NQJDQPHjs.handleRegister; exports.handleStatus = _chunk7NQJDQPHjs.handleStatus; exports.handleWait = _chunk7NQJDQPHjs.handleWait; exports.readPendingAuthClaim = _chunk7NQJDQPHjs.readPendingAuthClaim; exports.registerAuthCommands = _chunk7NQJDQPHjs.registerAuthCommands; exports.reportSetupCompleted = _chunk7NQJDQPHjs.reportSetupCompleted; exports.resolvePendingAuthClaimForResume = _chunk7NQJDQPHjs.resolvePendingAuthClaimForResume;

package/dist/cli/{auth-WHKDFARX.mjs → auth-YKJHKHIQ.mjs}

@@ -9,11 +9,11 @@ import {
   registerAuthCommands,
   reportSetupCompleted,
   resolvePendingAuthClaimForResume
-} from "./chunk-V4WVYW3G.mjs";
-import "./chunk-AIIVF62D.mjs";
-import "./chunk-GHYU5YWJ.mjs";
+} from "./chunk-IHT6XITB.mjs";
+import "./chunk-35SCWK4Y.mjs";
+import "./chunk-7QV545D7.mjs";
 import "./chunk-DLIRSHV6.mjs";
-import "./chunk-A4UUUINX.mjs";
+import "./chunk-7OXXCRGZ.mjs";
 import "./chunk-NXGCO4JB.mjs";
 import "./chunk-WZYKRD7T.mjs";
 import "./chunk-KRD6H754.mjs";