deepline 0.3.55 → 0.3.57

package/dist/index.mjs

@@ -738,7 +738,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.55",
+  version: "0.3.57",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1
@@ -2744,9 +2744,9 @@ function nonEmptyString(value) {
 }
 function normalizeDatasetBornFrom(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const record = value;
-  const table = nonEmptyString(record.table);
-  const rowCountIn = finiteNonNegativeInteger2(record.rowCountIn);
+  const record2 = value;
+  const table = nonEmptyString(record2.table);
+  const rowCountIn = finiteNonNegativeInteger2(record2.rowCountIn);
   if (!table || rowCountIn === null) return null;
   return { table, rowCountIn };
 }
@@ -3806,21 +3806,21 @@ function normalizePlayRuntimeNamespace(value) {
 }
 function normalizePlayRuntimeSelection(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const record = value;
-  if (Object.keys(record).some(
+  const record2 = value;
+  if (Object.keys(record2).some(
     (key) => key !== "environment" && key !== "namespace" && key !== "backend"
-  ) || record.environment !== "preview") {
+  ) || record2.environment !== "preview") {
     return null;
   }
-  const namespace = normalizePlayRuntimeNamespace(record.namespace);
+  const namespace = normalizePlayRuntimeNamespace(record2.namespace);
   if (!namespace) return null;
-  if (record.backend === void 0) {
+  if (record2.backend === void 0) {
     return { environment: "preview", namespace };
   }
-  if (record.backend !== PLAY_RUNTIME_BACKENDS.daytona && record.backend !== PLAY_RUNTIME_BACKENDS.modal) {
+  if (record2.backend !== PLAY_RUNTIME_BACKENDS.daytona && record2.backend !== PLAY_RUNTIME_BACKENDS.modal) {
     return null;
   }
-  return { environment: "preview", namespace, backend: record.backend };
+  return { environment: "preview", namespace, backend: record2.backend };
 }
 function normalizePlayRuntimeEnvironment(value) {
   return typeof value === "string" && PLAY_RUNTIME_ENVIRONMENTS.includes(value) ? value : null;
@@ -4404,7 +4404,14 @@ var DeeplineClient = class {
       dependents: (key) => this.getMonitorDependents(key),
       update: (key, patch) => this.updateMonitor(key, patch),
       delete: (key, options2) => this.deleteMonitor(key, options2),
-      reactivate: (key, options2) => this.reactivateMonitor(key, options2)
+      reactivate: (key, options2) => this.reactivateMonitor(key, options2),
+      fleets: {
+        sync: (definitionOrId, options2) => this.syncMonitorFleet(definitionOrId, options2),
+        get: (fleetId, options2) => fleetId === void 0 ? this.listMonitorFleets() : this.getMonitorFleet(fleetId, options2),
+        list: () => this.listMonitorFleets(),
+        deactivate: (fleetId, options2) => this.deactivateMonitorFleet(fleetId, options2),
+        waitForConvergence: (fleetId, options2) => this.waitForMonitorFleetConvergence(fleetId, options2)
+      }
     };
   }
   /** The resolved base URL this client is targeting (e.g. `"http://localhost:3000"`). */
@@ -6712,6 +6719,104 @@ var DeeplineClient = class {
       { method: "POST", body: {} }
     );
   }
+  // ——————————————————————————————————————————————————————————
+  // Monitor Fleets
+  // ——————————————————————————————————————————————————————————
+  monitorFleetIdempotencyKey(operation) {
+    const uuid = globalThis.crypto?.randomUUID?.();
+    return `monitor-fleet-${operation}-${uuid ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`;
+  }
+  monitorFleetHeaders(operation, idempotencyKey) {
+    return {
+      "Idempotency-Key": idempotencyKey?.trim() || this.monitorFleetIdempotencyKey(operation)
+    };
+  }
+  monitorFleetPath(fleetId) {
+    return `/api/v2/monitors/fleets/${encodeURIComponent(fleetId)}`;
+  }
+  /**
+   * Create, update, or re-plan one fleet.
+   *
+   * The fleet id is always the resource path, so the same definition PUT twice
+   * is the same operation and the server can answer `replayed: true` instead of
+   * building a second set of monitors. Re-planning an existing fleet from its
+   * stored definition sends an EMPTY body: there is no second definition to
+   * send, and an empty body cannot be mistaken for "replace the definition with
+   * nothing".
+   */
+  async syncMonitorFleet(definitionOrId, options) {
+    const fleetId = typeof definitionOrId === "string" ? definitionOrId : definitionOrId.id;
+    const body = {
+      ...typeof definitionOrId === "string" ? {} : { definition: definitionOrId },
+      ...options?.dryRun ? { dry_run: true } : {},
+      ...options?.expectedGeneration !== void 0 ? { expected_generation: options.expectedGeneration } : {}
+    };
+    return this.http.request(
+      this.monitorFleetPath(fleetId),
+      {
+        method: "PUT",
+        body,
+        headers: this.monitorFleetHeaders("sync", options?.idempotencyKey),
+        maxRetries: 0,
+        exactUrlOnly: true
+      }
+    );
+  }
+  async listMonitorFleets() {
+    return this.http.request("/api/v2/monitors/fleets", {
+      method: "GET"
+    });
+  }
+  async getMonitorFleet(fleetId, options) {
+    const params = new URLSearchParams();
+    if (options?.drift) params.set("drift", "1");
+    if (options?.limit !== void 0)
+      params.set("limit", String(options.limit));
+    const query = params.toString();
+    return this.http.request(
+      `${this.monitorFleetPath(fleetId)}${query ? `?${query}` : ""}`,
+      { method: "GET" }
+    );
+  }
+  async deactivateMonitorFleet(fleetId, options) {
+    return this.http.request(
+      this.monitorFleetPath(fleetId),
+      {
+        method: "DELETE",
+        body: options?.dryRun ? { dry_run: true } : {},
+        headers: this.monitorFleetHeaders(
+          "deactivate",
+          options?.idempotencyKey
+        ),
+        maxRetries: 0,
+        exactUrlOnly: true
+      }
+    );
+  }
+  /**
+   * Poll one fleet until the server reports a terminal status.
+   *
+   * Convergence is the server's verdict, read from `status`. The timeout is not
+   * a failure and does not throw: a fleet still `converging` after ten minutes
+   * is healthy and slow, not broken, so the caller gets the last snapshot and
+   * decides what that means. Throwing here would have made "still working" look
+   * identical to "the request failed".
+   */
+  async waitForMonitorFleetConvergence(fleetId, options) {
+    const timeoutMs = Math.max(1, options?.timeoutMs ?? 10 * 6e4);
+    const pollIntervalMs = Math.max(1, options?.pollIntervalMs ?? 2e3);
+    const terminal = options?.until === "deactivated" ? /* @__PURE__ */ new Set(["deactivated", "degraded"]) : /* @__PURE__ */ new Set(["converged", "degraded", "deactivated"]);
+    const startedAt = Date.now();
+    let latest = await this.getMonitorFleet(fleetId);
+    while (true) {
+      options?.onProgress?.(latest);
+      const status = typeof latest.status === "string" ? latest.status : void 0;
+      if (status && terminal.has(status)) return latest;
+      if (Date.now() - startedAt >= timeoutMs) return latest;
+      await sleep2(pollIntervalMs);
+      latest = await this.getMonitorFleet(fleetId);
+    }
+  }
   /**
    * Check API connectivity and server health.
    *
@@ -7758,8 +7863,8 @@ function firstExperienceDate(value) {
   return null;
 }
 function normalizeJobChange(value) {
-  const record = isRecord8(value) ? value : {};
-  const nested = isRecord8(record.job_change) ? record.job_change : record;
+  const record2 = isRecord8(value) ? value : {};
+  const nested = isRecord8(record2.job_change) ? record2.job_change : record2;
   const output = isRecord8(nested.output) ? nested.output : nested;
   const person = isRecord8(output.person) ? output.person : {};
   const status = normalizeJobChangeStatus(
@@ -10306,6 +10411,341 @@ function defineMonitor(definition) {
   return definition;
 }
 
+// src/monitor-fleet-contract.ts
+var MONITOR_FLEET_MAX_MEMBERS = 1e3;
+var MONITOR_FLEET_FRONTIER_MAX_ROWS = 1e4;
+var MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 1;
+var SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS = [
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION
+];
+var MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG = [
+  {
+    edition: 1,
+    changed: "Initial Fleet JSON contract: bounded sticky table membership, one daily sync, and a seven-day removal grace.",
+    compatibilityOwner: "Monitors Runtime",
+    newWritesEnd: null,
+    readerRemoval: null
+  }
+];
+var MONITOR_FLEET_REMOVAL_GRACE_MS = 7 * 24 * 60 * 6e4;
+var MONITOR_FLEET_DOCUMENTATION = {
+  summary: "A Monitor Fleet keeps one bounded, sticky set of ordinary monitors aligned with Customer DB rows.",
+  authoredFields: {
+    id: "Stable lowercase fleet id used by sync, pause, resume, and deactivate.",
+    source: "Customer DB table, unique row key, and optional equality filters that select candidate rows.",
+    member: "Ordinary monitor tool, stable key template, and payload evaluated for each selected source row.",
+    selection: "Deterministic ranking and an active-member limit between 1 and 1,000."
+  },
+  fixedPolicy: {
+    cadence: "daily",
+    membership: "sticky",
+    removalGrace: "7d",
+    onRemoved: "deactivate",
+    ownership: "A Fleet may adopt a same-tool ordinary monitor with its deterministic member key. The first Fleet claim wins; another Fleet or a different tool receives a conflict.",
+    billing: "No Fleet fee, permit, or renewal. Dry-run reports ordinary monitor lifecycle charges due now."
+  },
+  stickyMembership: "Ranking fills vacancies but never replaces a current member merely because another row ranks higher.",
+  columnExpression: 'Use { "$fleet": "column", "name": "column_name" } in a member key or payload to read a value from each source row.'
+};
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function identifier(value) {
+  return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function exactKeys(input, keys, path, issues) {
+  if (!input) return;
+  for (const key of Object.keys(input)) {
+    if (keys.includes(key)) continue;
+    issues.push({
+      path: path ? `${path}.${key}` : key,
+      code: "unknown_fleet_field",
+      message: `${path || "Fleet"} does not accept '${key}'.`
+    });
+  }
+}
+function jsonValue(value, path, issues) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => jsonValue(item, `${path}.${index}`, issues));
+    return;
+  }
+  const input = record(value);
+  if (!input) {
+    issues.push({
+      path,
+      code: "invalid_fleet_json_value",
+      message: "Fleet payload values must be JSON values."
+    });
+    return;
+  }
+  for (const [key, item] of Object.entries(input)) {
+    jsonValue(item, `${path}.${key}`, issues);
+  }
+}
+function fleetColumn(name) {
+  if (!identifier(name)) throw new Error(`Invalid fleet column '${name}'.`);
+  return { $fleet: "column", name };
+}
+function fleetKey(...parts) {
+  if (parts.length === 0)
+    throw new Error("A fleet key needs at least one part.");
+  return { $fleet: "template", parts };
+}
+function defineMonitorFleet(definition) {
+  return definition;
+}
+function validateExpression(value, path, issues) {
+  const input = record(value);
+  if (!input || input.$fleet !== "column" || !identifier(input.name)) {
+    issues.push({
+      path,
+      code: "invalid_fleet_expression",
+      message: "Fleet expressions must be an exact tagged column reference."
+    });
+    return;
+  }
+  exactKeys(input, ["$fleet", "name"], path, issues);
+}
+function walkPayload(value, path, issues) {
+  if (Array.isArray(value)) {
+    value.forEach(
+      (item, index) => walkPayload(item, `${path}.${index}`, issues)
+    );
+    return;
+  }
+  const input = record(value);
+  if (!input) return;
+  if ("$fleet" in input) {
+    validateExpression(input, path, issues);
+    return;
+  }
+  for (const [key, item] of Object.entries(input)) {
+    walkPayload(item, `${path}.${key}`, issues);
+  }
+}
+function validateMonitorFleetDefinition(value) {
+  const issues = [];
+  const input = record(value);
+  if (!input) {
+    return {
+      valid: false,
+      issues: [
+        {
+          path: "",
+          code: "invalid_fleet",
+          message: "Fleet must be an object."
+        }
+      ]
+    };
+  }
+  exactKeys(input, ["id", "source", "member", "selection"], "", issues);
+  if (typeof input.id !== "string" || !/^[a-z][a-z0-9-]{0,199}$/.test(input.id)) {
+    issues.push({
+      path: "id",
+      code: "invalid_fleet_id",
+      message: "Fleet id must be lowercase kebab-case."
+    });
+  }
+  const source = record(input.source);
+  exactKeys(
+    source,
+    ["kind", "schema", "table", "key", "where"],
+    "source",
+    issues
+  );
+  if (!source || source.kind !== "customer_db_table") {
+    issues.push({
+      path: "source.kind",
+      code: "invalid_fleet_source",
+      message: "Beta fleets require customer_db_table."
+    });
+  }
+  if (!identifier(source?.schema) || !identifier(source?.table)) {
+    issues.push({
+      path: "source",
+      code: "invalid_fleet_table",
+      message: "Source schema and table must be SQL identifiers."
+    });
+  }
+  const sourceKey = record(source?.key);
+  exactKeys(sourceKey, ["column", "type"], "source.key", issues);
+  if (!sourceKey || !identifier(sourceKey.column) || !["text", "uuid", "int4", "int8"].includes(String(sourceKey.type))) {
+    issues.push({
+      path: "source.key",
+      code: "invalid_fleet_source_key",
+      message: "Source key must name a supported typed column."
+    });
+  }
+  if (source?.where !== void 0) {
+    const where = record(source.where);
+    if (!where) {
+      issues.push({
+        path: "source.where",
+        code: "invalid_fleet_where",
+        message: "source.where must be an object of equality values."
+      });
+    } else {
+      for (const [column, expected] of Object.entries(where)) {
+        if (!identifier(column)) {
+          issues.push({
+            path: `source.where.${column}`,
+            code: "invalid_fleet_where_column",
+            message: "source.where keys must be SQL identifiers."
+          });
+        }
+        if (expected !== null && typeof expected !== "string" && typeof expected !== "boolean" && !(typeof expected === "number" && Number.isFinite(expected))) {
+          issues.push({
+            path: `source.where.${column}`,
+            code: "invalid_fleet_where_value",
+            message: "source.where values must be finite JSON scalars or null."
+          });
+        }
+      }
+    }
+  }
+  const member = record(input.member);
+  exactKeys(member, ["tool", "key", "payload"], "member", issues);
+  const key = record(member?.key);
+  if (!member || typeof member.tool !== "string" || !member.tool.trim()) {
+    issues.push({
+      path: "member.tool",
+      code: "invalid_fleet_tool",
+      message: "Member tool is required."
+    });
+  }
+  if (!key || key.$fleet !== "template" || !Array.isArray(key.parts) || key.parts.length === 0) {
+    issues.push({
+      path: "member.key",
+      code: "invalid_fleet_key",
+      message: "Member key must be a tagged fleet template."
+    });
+  } else {
+    exactKeys(key, ["$fleet", "parts"], "member.key", issues);
+    for (const [index, part] of key.parts.entries()) {
+      if (typeof part !== "string")
+        validateExpression(part, `member.key.parts.${index}`, issues);
+    }
+    if (sourceKey && !key.parts.some(
+      (part) => record(part)?.$fleet === "column" && record(part)?.name === sourceKey.column
+    )) {
+      issues.push({
+        path: "member.key.parts",
+        code: "fleet_key_missing_source_key",
+        message: "Member key must include the source key column."
+      });
+    }
+  }
+  if (!member || !("payload" in member)) {
+    issues.push({
+      path: "member.payload",
+      code: "invalid_fleet_payload",
+      message: "Member payload is required."
+    });
+  } else {
+    jsonValue(member.payload, "member.payload", issues);
+  }
+  walkPayload(member?.payload, "member.payload", issues);
+  const selection = record(input.selection);
+  exactKeys(selection, ["limit", "orderBy", "membership"], "selection", issues);
+  if (!selection || !Number.isSafeInteger(selection.limit) || Number(selection.limit) < 1 || Number(selection.limit) > MONITOR_FLEET_MAX_MEMBERS) {
+    issues.push({
+      path: "selection.limit",
+      code: "MONITOR_FLEET_LIMIT_EXCEEDED",
+      message: "selection.limit must be between 1 and 1,000."
+    });
+  }
+  if (selection?.membership !== "sticky") {
+    issues.push({
+      path: "selection.membership",
+      code: "invalid_fleet_membership",
+      message: `Fleet membership is fixed to ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.membership}. ${MONITOR_FLEET_DOCUMENTATION.stickyMembership}`
+    });
+  }
+  const orderBy = selection?.orderBy;
+  if (!Array.isArray(orderBy) || orderBy.length === 0) {
+    issues.push({
+      path: "selection.orderBy",
+      code: "invalid_fleet_order",
+      message: "At least one deterministic order field is required."
+    });
+  } else {
+    const orderColumns = /* @__PURE__ */ new Set();
+    for (const [index, order] of orderBy.entries()) {
+      const item = record(order);
+      exactKeys(
+        item,
+        ["column", "direction"],
+        `selection.orderBy.${index}`,
+        issues
+      );
+      if (!item || !identifier(item.column) || !["asc", "desc"].includes(String(item.direction))) {
+        issues.push({
+          path: `selection.orderBy.${index}`,
+          code: "invalid_fleet_order",
+          message: "Order fields need a column and asc/desc direction."
+        });
+      } else if (orderColumns.has(item.column)) {
+        issues.push({
+          path: `selection.orderBy.${index}.column`,
+          code: "duplicate_fleet_order_column",
+          message: "Each selection order column may appear only once."
+        });
+      } else {
+        orderColumns.add(item.column);
+      }
+    }
+    if (sourceKey && record(orderBy.at(-1))?.column !== sourceKey.column) {
+      issues.push({
+        path: "selection.orderBy",
+        code: "fleet_order_missing_key",
+        message: "The final order field must be the source key."
+      });
+    }
+  }
+  for (const removedOption of ["spendLimits", "lifecycle", "reconciliation"]) {
+    if (removedOption in input) {
+      issues.push({
+        path: removedOption,
+        code: "unsupported_fleet_option",
+        message: `${removedOption} is fixed by Monitor Fleets and must be omitted. Fleets sync ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.cadence} and ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.onRemoved} members after ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.removalGrace} absent from the source.`
+      });
+    }
+  }
+  return issues.length === 0 ? { valid: true, definition: value, issues } : { valid: false, issues };
+}
+function admitMonitorFleetAuthoringContract(value, edition = MONITOR_FLEET_AUTHORING_CONTRACT_EDITION) {
+  if (!SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS.includes(
+    edition
+  )) {
+    return {
+      valid: false,
+      issues: [
+        {
+          path: "authoring_contract_edition",
+          code: "unsupported_fleet_authoring_contract_edition",
+          message: `Monitor Fleet authoring contract edition ${edition} is not supported.`
+        }
+      ]
+    };
+  }
+  const result = validateMonitorFleetDefinition(value);
+  return result.valid && result.definition ? {
+    valid: true,
+    contract: {
+      edition,
+      // JSON cloning prevents later caller mutation from changing the
+      // admitted snapshot.
+      definition: JSON.parse(
+        JSON.stringify(result.definition)
+      )
+    },
+    issues: []
+  } : { valid: false, issues: result.issues };
+}
+
 // ../plays/bootstrap-routes.ts
 var DEEPLINE_TOOL_CATEGORIES = [
   "company_search",
@@ -10593,6 +11033,11 @@ export {
   DeeplineContext,
   DeeplineError,
   JOB_CHANGE_STATUS_VALUES,
+  MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG,
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+  MONITOR_FLEET_DOCUMENTATION,
+  MONITOR_FLEET_FRONTIER_MAX_ROWS,
+  MONITOR_FLEET_MAX_MEMBERS,
   PHONE_STATUS_VALUES,
   PLAY_BOOTSTRAP_COMPANY_FIELDS,
   PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY,
@@ -10612,11 +11057,15 @@ export {
   SDK_VERSION,
   ToolExecutionError,
   ToolRateLimitError,
+  admitMonitorFleetAuthoringContract,
   defineInput,
   defineMonitor,
+  defineMonitorFleet,
   definePlay,
   defineWorkflow,
   extractSummaryFields,
+  fleetColumn,
+  fleetKey,
   formatPlayBootstrapFinderKinds,
   formatPlayBootstrapFinderKindsForSentence,
   formatPlayBootstrapTemplates,
@@ -10631,6 +11080,7 @@ export {
   runIf,
   steps,
   tryConvertToList,
+  validateMonitorFleetDefinition,
   writeCsvOutputFile,
   writeJsonOutputFile
 };

package/dist/install-integrity.json

@@ -10,6 +10,8 @@
     "dist/bundling-sources/sdk/src/helpers.ts",
     "dist/bundling-sources/sdk/src/http.ts",
     "dist/bundling-sources/sdk/src/index.ts",
+    "dist/bundling-sources/sdk/src/monitor-fleet-contract.ts",
+    "dist/bundling-sources/sdk/src/monitor-fleets.ts",
     "dist/bundling-sources/sdk/src/monitors.ts",
     "dist/bundling-sources/sdk/src/play.ts",
     "dist/bundling-sources/sdk/src/plays/bundle-play-file.ts",
@@ -23,6 +25,9 @@
     "dist/bundling-sources/sdk/src/version.ts",
     "dist/bundling-sources/shared_libs/integrations/bettercontact-execution-policy.ts",
     "dist/bundling-sources/shared_libs/integrations/theirstack-execution-policy.ts",
+    "dist/bundling-sources/shared_libs/monitors/monitor-fleet-limits.ts",
+    "dist/bundling-sources/shared_libs/monitors/org-monitor-limits.ts",
+    "dist/bundling-sources/shared_libs/monitors/validation.ts",
     "dist/bundling-sources/shared_libs/observability/node-tracing.ts",
     "dist/bundling-sources/shared_libs/observability/redaction.ts",
     "dist/bundling-sources/shared_libs/observability/scheduled-job-errors.ts",

package/package.json

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