deepline 0.3.88 → 0.3.90

package/dist/bundling-sources/shared_libs/monitors/http-error-response.ts

@@ -0,0 +1,270 @@
+import { NextResponse } from 'next/server';
+
+import { MAX_PRIORITY_MONITORS_PER_ORG } from '@deepline/monitors/provider-monitor-priority-execution';
+
+export const MONITOR_ERROR_FALLBACK_NEXT_ACTION =
+  "Do not retry blindly. Read the deepline-monitors skill's 'Recover from errors by code' section, inspect the returned message and relevant state, then diagnose this failure.";
+
+type MonitorErrorPayload = Record<string, unknown>;
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function errorCode(payload: MonitorErrorPayload): string {
+  const nested = asRecord(payload.error);
+  const value = nested?.code ?? payload.code;
+  return typeof value === 'string' ? value : '';
+}
+
+function nestedError(
+  payload: MonitorErrorPayload,
+): Record<string, unknown> | null {
+  return asRecord(payload.error);
+}
+
+function upstreamRetryAfterSeconds(
+  error: Record<string, unknown>,
+): number | null {
+  const declared = error.retryAfterSeconds;
+  if (
+    typeof declared === 'number' &&
+    Number.isFinite(declared) &&
+    declared >= 0
+  ) {
+    return Math.ceil(declared);
+  }
+
+  const headers = asRecord(error.headers);
+  const retryAfter = headers?.['retry-after'];
+  if (typeof retryAfter !== 'string' || !retryAfter.trim()) return null;
+  const numeric = Number(retryAfter);
+  if (Number.isFinite(numeric) && numeric >= 0) return Math.ceil(numeric);
+
+  const retryAt = Date.parse(retryAfter);
+  if (!Number.isFinite(retryAt)) return null;
+  return Math.max(0, Math.ceil((retryAt - Date.now()) / 1_000));
+}
+
+/**
+ * Classify only the monitor-lifecycle upstream failures that are safe to
+ * explain generically. This deliberately duck-types the integration error:
+ * monitor route tests and provider adapters can cross module boundaries, but
+ * the stable discriminant is part of the shared integration error contract.
+ *
+ * Do not relay the upstream message or body. They can contain provider account
+ * identifiers, request details, or provider-only diagnostics. The status and
+ * normalized Retry-After are enough for a customer to make a safe next move.
+ */
+export function monitorUpstreamFailureResponse(
+  error: unknown,
+): NextResponse | null {
+  const upstream = asRecord(error);
+  if (
+    upstream?.isIntegrationUpstreamHttpError !== true ||
+    typeof upstream.status !== 'number'
+  ) {
+    return null;
+  }
+
+  const retryAfterSeconds = upstreamRetryAfterSeconds(upstream);
+  const retryHeaders =
+    retryAfterSeconds === null
+      ? undefined
+      : { 'retry-after': String(retryAfterSeconds) };
+
+  if (upstream.status === 429) {
+    return monitorErrorResponse(
+      {
+        error: {
+          code: 'monitor_upstream_rate_limited',
+          message:
+            'The monitor provider is rate limiting lifecycle requests. Deepline could not confirm completion of this lifecycle change.',
+          upstream_status: upstream.status,
+          ...(retryAfterSeconds === null
+            ? {}
+            : { retry_after_seconds: retryAfterSeconds }),
+        },
+      },
+      { status: 429, headers: retryHeaders },
+    );
+  }
+
+  if (upstream.status >= 500 && upstream.status <= 599) {
+    return monitorErrorResponse(
+      {
+        error: {
+          code: 'monitor_upstream_unavailable',
+          message:
+            'The monitor provider is temporarily unavailable. Deepline could not confirm completion of this lifecycle change.',
+          upstream_status: upstream.status,
+          ...(retryAfterSeconds === null
+            ? {}
+            : { retry_after_seconds: retryAfterSeconds }),
+        },
+      },
+      { status: 503, headers: retryHeaders },
+    );
+  }
+
+  return null;
+}
+
+/**
+ * Server-owned recovery guidance for every agent-facing monitor error.
+ * Known codes get an exact next step. Unknown failures deliberately point at
+ * the monitor skill and prohibit blind retries instead of inventing a fix.
+ */
+export function monitorErrorNextAction(payload: MonitorErrorPayload): string {
+  const code = errorCode(payload);
+  const retryAfterMs = payload.retry_after_ms;
+  const retryAfterSeconds =
+    nestedError(payload)?.retry_after_seconds ?? payload.retry_after_seconds;
+
+  if (code === 'monitor_access_required') {
+    return 'Stop monitor work and contact the Deepline team to request access; then rerun `deepline monitors status --json`.';
+  }
+  if (code === 'monitor_tool_not_found' || code === 'unknown_monitor_tool') {
+    return 'Run `deepline monitors available --json`, choose a returned tool id, then retry with that exact id.';
+  }
+  if (code === 'deployed_monitor_not_found' || code === 'monitor_not_found') {
+    return 'Run `deepline monitors list --status all --json`, choose a returned public monitor key, then retry with that key.';
+  }
+  if (code === 'ingestion_plane_not_ready') {
+    return typeof retryAfterMs === 'number'
+      ? `Wait ${retryAfterMs} ms, then retry the same read or check once.`
+      : 'Wait for Customer DB provisioning, then retry the same read or check once.';
+  }
+  if (code === 'monitor_control_plane_unavailable') {
+    return 'Wait briefly, then rerun the same monitor read. No monitor state was changed.';
+  }
+  if (code === 'provider_monitor_identity_backfill_in_progress') {
+    return typeof retryAfterSeconds === 'number'
+      ? `Wait ${retryAfterSeconds} seconds, then retry the same monitor lifecycle request once. No upstream monitor was created.`
+      : 'Wait briefly, then retry the same monitor lifecycle request once. No upstream monitor was created.';
+  }
+  if (code === 'provider_monitor_capacity_backfill_in_progress') {
+    return typeof retryAfterSeconds === 'number'
+      ? `Wait ${retryAfterSeconds} seconds, then retry the same monitor create once. No upstream monitor was created.`
+      : 'Wait briefly, then retry the same monitor create once. No upstream monitor was created.';
+  }
+  if (code === 'ORG_MONITOR_LIMIT_EXCEEDED') {
+    return 'Run `deepline monitors list --status all --json`; stop watching an account you no longer need, or contact Deepline for a higher account limit.';
+  }
+  if (code === 'MONITOR_ENTITY_LIMIT_EXCEEDED') {
+    return 'This account already carries the maximum number of monitors. Delete one of its monitors, or watch the signal on a different account.';
+  }
+  if (code === 'MONITOR_CAPACITY_CLEANUP_REQUIRED') {
+    return 'Inspect the monitor and complete upstream cleanup before recreating this public key. Do not retry create blindly.';
+  }
+  if (code === 'MONITOR_MANAGED_BY_FLEET') {
+    return 'Change the owning Monitor Fleet or deactivate it before mutating this member directly.';
+  }
+  if (code === 'provider_monitor_operation_in_progress') {
+    return 'Rerun the same deploy or update that started this change. Do not send a different change until it finishes.';
+  }
+  if (code === 'provider_monitor_delete_in_progress') {
+    return 'Rerun the same delete now. Do not deploy, update, or reactivate this monitor until that delete finishes.';
+  }
+  if (
+    code === 'invalid_limit' ||
+    code === 'invalid_monitor_status' ||
+    code === 'unknown_monitor_tool_filter' ||
+    code === 'unknown_deployed_monitor_filter'
+  ) {
+    return 'Correct the request using the returned expected, received, or suggestion fields, then retry once.';
+  }
+  if (code === 'monitor_deploy_validation_failed') {
+    return 'Fix every returned issue using its path and suggestion. Rerun `deepline monitors check` for definitions or the relevant dry-run for delete/reactivate; do not mutate until validation passes.';
+  }
+  if (code === 'monitor_tool_unavailable') {
+    return 'Run `deepline monitors available --json`; choose a tool returned for this workspace, or stop and request access to the unavailable capability.';
+  }
+  if (code === 'monitor_entitlement_limit_exceeded') {
+    return 'Run `deepline monitors list --status all --json`; reuse or disable an existing monitor, or ask the user to change entitlement before retrying.';
+  }
+  if (code === 'priority_monitor_limit_exceeded') {
+    return `This workspace already has ${MAX_PRIORITY_MONITORS_PER_ORG} priority radars. Delete or update an existing priority radar only after confirming it is no longer needed, then retry the urgent preview.`;
+  }
+  if (code === 'monitor_already_exists') {
+    const existing = asRecord(nestedError(payload)?.existing_monitor)?.key;
+    return typeof existing === 'string'
+      ? `Run \`deepline monitors get ${existing} --json\` to inspect the monitor that owns this identity. Reuse it or contact Deepline support before replacing it; do not delete and redeploy blindly.`
+      : 'Inspect the returned existing_monitor.key with `deepline monitors get <key> --json`. Reuse that monitor or contact Deepline support before replacing it; do not delete and redeploy blindly.';
+  }
+  if (code === 'upstream_monitor_conflict_unresolved') {
+    const existing = asRecord(nestedError(payload)?.existing_monitor)?.key;
+    return typeof existing === 'string'
+      ? `Run \`deepline monitors get ${existing} --json\` to inspect the matching managed monitor, then report this upstream 409 to Deepline support. Do not retry blindly.`
+      : 'Report this upstream 409 to Deepline support with the returned tool and identity. Do not retry blindly.';
+  }
+  if (code === 'monitor_upstream_rate_limited') {
+    return typeof retryAfterSeconds === 'number'
+      ? `Wait ${retryAfterSeconds} seconds, then run \`deepline monitors get <key> --json\` to inspect the stored state. Do not retry or create another monitor unless that state confirms the prior lifecycle action was not applied; if it is missing or unclear, contact Deepline support with the returned upstream_status.`
+      : 'Wait briefly, then run `deepline monitors get <key> --json` to inspect the stored state. Do not retry or create another monitor unless that state confirms the prior lifecycle action was not applied; if it is missing or unclear, contact Deepline support with the returned upstream_status.';
+  }
+  if (code === 'monitor_upstream_unavailable') {
+    return typeof retryAfterSeconds === 'number'
+      ? `Wait ${retryAfterSeconds} seconds, then run \`deepline monitors get <key> --json\` to inspect the stored state. Do not retry or create another monitor unless that state confirms the prior lifecycle action was not applied; if it is missing or unclear, contact Deepline support with the returned upstream_status.`
+      : 'Wait briefly, then run `deepline monitors get <key> --json` to inspect the stored state. Do not retry or create another monitor unless that state confirms the prior lifecycle action was not applied; if it is missing or unclear, contact Deepline support with the returned upstream_status.';
+  }
+  if (
+    code === 'monitor_entitlement_required' ||
+    code === 'monitor_billing_policy_blocked'
+  ) {
+    return 'Stop and report the required monitor entitlement or unresolved pricing policy; do not retry until the Deepline team resolves it.';
+  }
+  if (code === 'monitor_billing_denied') {
+    return 'Report the returned required credits, balance, and shortfall, then stop; retry only after the user adds credits or changes the plan.';
+  }
+  if (code === 'BILLING_UNAVAILABLE') {
+    return 'Wait briefly and retry the same read or check once; do not repeat a mutation until its monitor state is verified.';
+  }
+  if (
+    code === 'monitor_billing_settlement_failed' ||
+    code.includes('cleanup_required') ||
+    code.includes('cleanup_failed')
+  ) {
+    return 'Run `deepline monitors get <key> --json`, report the disabled or repair-required state, and do not repeat the mutation blindly.';
+  }
+  if (code === 'no_active_org') {
+    return 'Select an active organization, verify it with `deepline auth status --json`, then retry.';
+  }
+
+  return MONITOR_ERROR_FALLBACK_NEXT_ACTION;
+}
+
+export function monitorErrorResponse(
+  payload: MonitorErrorPayload,
+  init: { status: number; headers?: HeadersInit },
+): NextResponse {
+  return NextResponse.json(
+    {
+      ...payload,
+      next_action:
+        typeof payload.next_action === 'string'
+          ? payload.next_action
+          : monitorErrorNextAction(payload),
+    },
+    init,
+  );
+}
+
+/** Add monitor-specific recovery guidance to auth errors created upstream. */
+export async function withMonitorErrorNextAction(
+  response: NextResponse,
+): Promise<NextResponse> {
+  if (response.status < 400) return response;
+  const payload = (await response
+    .clone()
+    .json()
+    .catch(() => null)) as unknown;
+  const record = asRecord(payload);
+  if (!record) return response;
+
+  const headers = new Headers(response.headers);
+  headers.delete('content-length');
+  return monitorErrorResponse(record, { status: response.status, headers });
+}

package/dist/bundling-sources/shared_libs/monitors/inbound-publish-key.ts

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto';
+import {
+  parseProviderCallbackPayload,
+  providerCallbackWireEventId,
+} from '@deepline/monitors/provider-callback-verification';
+
+// The Neon-free publish idempotency key the thin receiver forwards to the queue
+// producer's send(..., { idempotencyKey }). Pure function of what is on the wire:
+// (provider, orgId, token) scope + the stable provider event id derived from
+// headers+payload. A provider re-POST of the SAME event yields the SAME key
+// (deduped at publish); two DISTINCT events yield DIFFERENT keys; a token/org
+// swap can never collide. When the provider gives no id, providerCallbackWireEventId
+// falls back to a deterministic sha256 of the payload, so the key stays stable
+// and content-addressed (never random).
+//
+// Lives in its own module (not /monitors/inbound-queue) so the thin receiver
+// can import the REAL helper even when tests fake the queue producer seam.
+export function signalRadarInboundPublishIdempotencyKey(input: {
+  provider: string;
+  orgId: string;
+  token: string;
+  headers: Headers;
+  rawBody: string;
+}): string {
+  const payload = parseProviderCallbackPayload({
+    contentType: input.headers.get('content-type'),
+    rawBody: input.rawBody,
+  });
+
+  const eventId = providerCallbackWireEventId({
+    provider: input.provider,
+    headers: input.headers,
+    payload,
+  });
+
+  return `sr_inbound_${createHash('sha256')
+    .update(JSON.stringify([input.provider, input.orgId, input.token, eventId]))
+    .digest('hex')}`;
+}

package/dist/bundling-sources/shared_libs/monitors/inbound-queue.ts

@@ -0,0 +1,82 @@
+import { signalRadarInboundPublishIdempotencyKey } from '@deepline/monitors/inbound-publish-key';
+import {
+  classifyInboundFailure,
+  recordSignalRadarDeadLetter as recordSignalRadarDeadLetterCore,
+  type InboundFailureClass,
+  type InboundPgClient,
+} from '@deepline/monitors/signal-radars/inbound-dead-letter';
+import {
+  send as sendSignalRadarInbound,
+  SIGNAL_RADAR_INBOUND_TOPIC as SIGNAL_RADAR_INBOUND_TOPIC_VALUE,
+  type SignalRadarInboundSendOptions,
+} from '@deepline/monitors/signal-radars/inbound-queue';
+import type { SignalRadarInboundMessage } from '@deepline/monitors/signal-radars/inbound-message';
+
+// Public inbound-queue surface used by the thin provider-callback receiver.
+// Re-exports the topic + producer and adds the Neon-free publish key helper and
+// the retry classifier the receiver/worker share.
+export const SIGNAL_RADAR_INBOUND_TOPIC = SIGNAL_RADAR_INBOUND_TOPIC_VALUE;
+
+function headersToObject(headers: Headers): Record<string, string> {
+  const result: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    result[key.toLowerCase()] = value;
+  });
+  return result;
+}
+
+// Re-export the Neon-free publish key helper so the pure-helper test resolves it
+// here. The receiver imports it directly from /monitors/inbound-publish-key
+// so it gets the real helper even when this module's producer seam is faked.
+export { signalRadarInboundPublishIdempotencyKey };
+
+// Producer wrapper the receiver calls: `send(message, { idempotencyKey })`.
+export async function sendSignalRadarInboundMessage(
+  message: SignalRadarInboundMessage,
+  options?: SignalRadarInboundSendOptions,
+) {
+  return sendSignalRadarInbound(message, options);
+}
+
+// Transient (retry) vs permanent (dead-letter) classifier, shared with the
+// worker's retry callback. See classifyInboundFailure for the semantics.
+export function classifySignalRadarInboundError(
+  error: unknown,
+): InboundFailureClass {
+  return classifyInboundFailure(error);
+}
+
+// Positional-client dead-letter writer used by the worker's retry path. Adapts
+// the ergonomic call shape to the shared idempotent writer.
+export async function recordSignalRadarDeadLetter(
+  client: InboundPgClient,
+  input: {
+    provider: string;
+    orgId?: string | null;
+    radarKey?: string | null;
+    eventIdempotencyKey?: string | null;
+    payload: Record<string, unknown>;
+    headers?: Record<string, string>;
+    attempts: number;
+    lastError?: string | null;
+  },
+): Promise<void> {
+  await recordSignalRadarDeadLetterCore({
+    client,
+    message: {
+      provider: input.provider,
+      orgId: input.orgId ?? '',
+      token: '',
+      radarKey: input.radarKey ?? null,
+      eventIdempotencyKey: input.eventIdempotencyKey ?? null,
+      headers: input.headers ?? {},
+      receivedAt: new Date().toISOString(),
+      rawBody: JSON.stringify(input.payload ?? {}),
+    },
+    error: new Error(input.lastError ?? 'monitor inbound poison message'),
+    attempts: input.attempts,
+  });
+}
+
+export type { SignalRadarInboundMessage } from '@deepline/monitors/signal-radars/inbound-message';
+export { headersToObject };

package/dist/bundling-sources/shared_libs/monitors/inventory-reconciliation.ts

@@ -0,0 +1,59 @@
+/** Shared inventory rules. Job progress and missing evidence are not monitor states. */
+export type InventoryRadar = {
+  id: string;
+  status: 'active' | 'inactive' | 'unknown';
+};
+export type InventoryDecision = {
+  verdict: 'converged' | 'desynced' | 'unknown';
+  reason: string;
+  radarId?: string;
+};
+
+/** Call only after BOTH inventories completed. Absence is otherwise unknown. */
+export function compareMonitorInventory(input: {
+  desired: 'active' | 'inactive';
+  resourceId: string | null;
+  exact: InventoryRadar[];
+  marker: InventoryRadar[];
+  candidateOwnerCount: number;
+}): InventoryDecision {
+  const { desired, resourceId, exact, marker, candidateOwnerCount } = input;
+  if (exact.length > 1 || candidateOwnerCount > (resourceId ? 1 : 0)) {
+    return { verdict: 'unknown', reason: 'ambiguous_tamradar_binding' };
+  }
+  if (!resourceId) {
+    if (marker.length > 1)
+      return { verdict: 'unknown', reason: 'ambiguous_tamradar_binding' };
+    if (marker.length === 1)
+      return {
+        verdict: 'desynced',
+        reason: 'adoptable_tamradar_radar',
+        radarId: marker[0]!.id,
+      };
+  }
+  const radar = exact[0];
+  if (!radar) {
+    if (!resourceId) {
+      // A complete account list proves that no stamped counterpart exists; it
+      // cannot prove which resource an unbound historical row used to own.
+      // Creation or adoption is a separate, explicit operator operation.
+      return { verdict: 'unknown', reason: 'missing_tamradar_binding' };
+    }
+    return desired === 'inactive'
+      ? { verdict: 'converged', reason: 'in_sync' }
+      : { verdict: 'desynced', reason: 'missing_tamradar_radar' };
+  }
+  if (radar.status === 'unknown')
+    return {
+      verdict: 'unknown',
+      reason: 'unknown_tamradar_state',
+      radarId: radar.id,
+    };
+  return radar.status === desired
+    ? { verdict: 'converged', reason: 'in_sync', radarId: radar.id }
+    : {
+        verdict: 'desynced',
+        reason: 'tamradar_state_differs',
+        radarId: radar.id,
+      };
+}