import { CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION } from '../../shared_libs/plays/artifact-contract-version'; /** * Single source of truth for SDK release metadata. * * Ordinary SDK PRs do NOT bump `version` here. Patch version selection * happens at publish time: on push to main, `.github/workflows/sdk-release.yml` * (via `scripts/sdk-release-autobump.ts`) compares the built package against * the latest published npm tarball and, when the content changed, stamps the * next unpublished patch into `version` in the CI workspace only and * publishes it in the same run. That patch stamp is not * committed back to main; production endpoints read npm metadata when they * need the newest patch-level SDK/CLI version. * * Edit THIS file by hand only for deliberate release decisions: * - minor/major version bumps (set `version`), * - API-major cutovers (set `contracts.api.currentMajor`; leave `version` to the * publish-time patch selector), * - support-window moves (`minimumSupported` / `deprecatedBelow`). * The automation never touches API compatibility policy, `minimumSupported`, or * `deprecatedBelow`. * * Everything else derives from these values: * * - `sdk/src/version.ts` re-exports `SDK_VERSION` and `SDK_API_CONTRACT`. * - `src/lib/sdk/release-policy.ts` re-exports `SDK_RELEASE_POLICY`. * - `sdk/package.json` `version` is stamped from `SDK_RELEASE.version` by * `scripts/sync-sdk-package-version.ts`, which runs as part of * `bun run sdk:build`. * - `contracts/sdk-api.manifest.json` is regenerated at build time from * `src/lib/sdk/api-routes.ts` and the apiContract here; the matching * `contracts/sdk-api.manifest.hash` is an ignored local/CI audit artifact. * * Any drift between release source and derived release locations is a * `check:sdk-release-readiness` failure with a one-shot fix command; SDK/API * compatibility policy is enforced by `bun run sdk:api-contract:check`. */ export type SdkReleaseChannel = 'latest' | 'next' | 'beta'; /** * The named public protocols. These are intentionally independent: * * - `api` is the HTTP SDK/CLI protocol. It is additive within a major. * - `playArtifact` is the immutable client-bundled Play payload ABI. * - `release` controls promotion/publishing; it is not a client protocol. * * Do not use an SDK package version or a date string as an artifact ABI. */ export type DeeplineContractPolicy = { api: { name: 'sdk-http-api'; currentMajor: number; supportedMajors: readonly number[]; /** Transitional value for installed SDKs that only send the old header. */ legacyWireIds: readonly string[]; }; playArtifact: { name: 'play-artifact-runtime'; currentVersion: number; supportedVersions: readonly number[]; }; release: { name: 'production-sdk-release'; /** npm may publish only from the active, healthy Production SHA. */ publishFrom: 'latest-successful-production-deployment'; /** A newer merge cancels an in-flight decision; reconciliation picks the last healthy SHA. */ coalesce: 'latest-healthy'; }; }; export type SdkSupportPolicy = { /** * Anything strictly below this returns `status: "unsupported"` from * `/api/v2/sdk/compat` and the CLI must hard-fail with the update command. * Only advance after the support window closes. */ minimumSupported: string; /** * Anything strictly below this returns `status: "deprecated"` (still works, * warns). Advance when a release becomes the new floor. */ deprecatedBelow: string; /** * Command-scoped support floors for SDK CLI workflows whose local behavior * can break while the network API contract remains compatible. */ commandMinimumSupported?: ReadonlyArray<{ command: string; displayCommand?: string; minimumSupported: string; reason: string; }>; /** * The version that first shipped a command. * * Deliberately not a support floor. `commandMinimumSupported` says an older * client is BROKEN for a command and forces an update; this says only that * an older client never had the command at all. That difference matters in * both directions: introducing a command must not auto-update anyone, and a * support floor may not exceed the version being released, while an * introduction version is a fact about an already-published release. * * It exists because agent skills are served by the backend and re-synced on * nearly every CLI invocation, while the CLI stays pinned. A release that * adds a command and documents it in the same commit therefore hands every * installed client instructions it cannot follow, and `unknown command` is * all the author sees. Recording the version lets the CLI say which release * added it. `check:skill-cli-commands` requires an entry here before a skill * may document a command. */ commandIntroducedIn?: ReadonlyArray<{ command: string; introducedIn: string; reason: string; }>; /** Previously published wire contracts that remain supported. */ compatibleApiContracts?: readonly string[]; /** * Published package versions that must keep working for direct SDK tool * callers. CI installs each package from npm and exercises `tools.get` and * `tools.execute` without involving the CLI or Play runtime. */ directToolsCompatibilityVersions?: readonly string[]; /** * Diagnostic freshness threshold reported by `/api/v2/sdk/compat`. * Stale-but-supported CLIs warn, but self-update is reserved for unsupported * versions and rollback-directed updates. */ autoUpdatePatchLag?: number; }; export type SdkRelease = { /** * Version published to npm. Usually stamped by the release workflow at * publish time (auto-bump); edit by hand only for minor/major releases. */ version: string; /** * One concise, agent-readable explanation shown while this release is an * available update. Keep it actionable; the compatibility route includes it * in its existing update message so older installed CLIs can print it too. */ updateSummary?: string; /** Named compatibility policies. This is the only authored contract policy. */ contracts: DeeplineContractPolicy; /** Public support policy reported by `/api/v2/sdk/compat`. */ supportPolicy: SdkSupportPolicy; }; export const SDK_RELEASE = { // 0.1.94 is claimed by PR #1527 — this watch-render fix ships as 0.1.95. // 0.1.98 ships the duplicate-browser-tab fix (default-browser detection). // 0.1.99 ships prebuilt job-change source-column preservation and validation fixes. // 0.1.101 ships retryable play artifact publish failures and CI retry hardening. // 0.1.102 ships the job-change ledger fixes: recovered-dataset export on // failed runs, persisted/succeeded/failed row counts, strict local CSV // preflight (existence, data rows, quotes, duplicate headers), HTML error // scrubbing, and word-boundary watch truncation. // 0.1.103 ships the refined SDK CLI command surface. // 0.1.104 shipped the retired Postgres scheduler suspension/billing parity and runtime worker hardening. // 0.1.105 ships the billing catalog surface: billing plans, subscribe, // subscription status/cancel, invoices, and the client.billing namespace. // 0.1.106 ships play cell provenance metadata and v2 preview retry hardening. // 0.1.107 ships the v2 quickstart command, the deepline-plays-quickstart // skill on the sdk sync surface, and the people-search-to-email prebuilt. // 0.1.108 ships explicit dataset column/tool recompute policy and removes // the SDK enrich generator's one-second stale policy. // 0.1.110 ships authored V2 prebuilts and required top-level play descriptions. // 0.1.111 ships dataset-native tool list getters and result row datasets. // 0.1.154 removes the short-lived generated enrich StepOptions recompute // fields shipped in 0.1.153. // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting. // 0.1.230 propagates enrich extractor failures as failed rows rather than // silently materializing them as unmatched results. // 0.1.220 deprecates SDK CLI versions below 0.1.219 and updates them // automatically without blocking their current command. // 0.1.241 hard-cuts published and launched plays to immutable cjs_node20 // artifacts. Older clients can submit esm_workers artifacts that the Absurd // runtime intentionally no longer compiles at publish or launch time. // 0.1.242 removes the retired Workers/ESM compiler, generated bundles, and // deploy-time artifact migration. Play authoring now has one CJS contract. // 0.1.252 hard-cuts the customer Monitor catalog to the two launched // Deepline-native radars. Older clients must update before discovering, // checking, or deploying an unlaunched monitor integration. // 0.1.253 makes play-page browser opening opt-in and retires --no-open. // 0.1.254 removes the internal operations tree from the published SDK CLI. // Operators use the checkout-local deepline-admin binary instead. // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly // exposed storage-dependent synchronous access. This deliberate minor // release keeps lazy paging semantics independent of row residency. // 0.3.0 introduces raw-v2: complete scrubbed provider responses are // available at toolResponse.rawV2 while toolResponse.raw and all declared // getters keep their established compatibility behavior. version: '0.3.21', updateSummary: 'New raw-v2 tool responses preserve complete scrubbed provider envelopes at toolResponse.rawV2, including JSON:API included resources, links, cursors, and totals. Existing toolResponse.raw and declared getters keep working unchanged.', contracts: { api: { name: 'sdk-http-api', // API v2 is append-only. A breaking public request/response change needs // v3 and an explicit v2 support-window decision, never a patch release. currentMajor: 2, supportedMajors: [2], // Accepted only to bridge SDKs released before X-Deepline-API-Major. legacyWireIds: [ '2026-07-admin-cli-local-cutover', '2026-07-native-monitor-launch-hard-cutover', ], }, playArtifact: { name: 'play-artifact-runtime', currentVersion: CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION, supportedVersions: [1, CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION], }, release: { name: 'production-sdk-release', publishFrom: 'latest-successful-production-deployment', coalesce: 'latest-healthy', }, }, supportPolicy: { minimumSupported: '0.1.53', deprecatedBelow: '0.1.219', commandIntroducedIn: [ { command: 'notifications', introducedIn: '0.2.40', reason: 'deepline notifications was added in SDK CLI 0.2.40. Older versions have no way to configure a Play failure alert, so a cron Play that dies reports to nobody.', }, ], commandMinimumSupported: [ { command: 'enrich', // Compatibility window through 2026-08-22 (owner: Chirag): versions // 0.1.238-0.1.252 differ only in local browser-opening behavior and // already contain the enrich data-correctness fixes below. minimumSupported: '0.1.238', reason: 'Older SDK CLI enrich generated stale play source; SDK CLI enrich 0.1.153 generated removed StepOptions fields in play source; SDK CLI enrich before 0.1.175 could silently succeed on the empty-waterfall bug when a requested waterfall returned no values for selected rows; SDK CLI enrich before 0.1.230 could convert extractor failures into successful unmatched results; SDK CLI enrich before 0.1.238 could drop a nested provider email match during generic pick("email") extraction and materialize it as NO_MATCH.', }, { command: 'plays', minimumSupported: '0.1.241', reason: 'Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract. Update before checking, publishing, or running plays.', }, { command: 'plays run', minimumSupported: '0.1.253', reason: 'Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract; versions before 0.1.253 open the play page by default and accept the removed --no-open flag.', }, { command: 'run', displayCommand: 'plays run', minimumSupported: '0.1.253', reason: 'Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract; versions before 0.1.253 open the play page by default and accept the removed --no-open flag.', }, { command: 'plays check', minimumSupported: '0.1.241', reason: 'Older SDK CLI versions predate dataset-native Play authoring and validate against the retired esm_workers artifact contract.', }, { command: 'check', displayCommand: 'plays check', minimumSupported: '0.1.241', reason: 'Older SDK CLI versions predate dataset-native Play authoring and validate against the retired esm_workers artifact contract.', }, { command: 'plays publish', minimumSupported: '0.1.241', reason: 'Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.', }, { command: 'publish', displayCommand: 'plays publish', minimumSupported: '0.1.241', reason: 'Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.', }, { command: 'plays set-live', minimumSupported: '0.1.241', reason: 'Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.', }, { command: 'set-live', displayCommand: 'plays set-live', minimumSupported: '0.1.241', reason: 'Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.', }, { command: 'runs', minimumSupported: '0.1.111', reason: 'Run result rows now render as dataset handles with explicit export commands.', }, { command: 'runs get', minimumSupported: '0.1.111', reason: 'Run result rows now render as dataset handles with explicit export commands.', }, { command: 'get', displayCommand: 'runs get', minimumSupported: '0.1.111', reason: 'Run result rows now render as dataset handles with explicit export commands.', }, { command: 'runs export', minimumSupported: '0.1.111', reason: 'Run result row datasets now use the dataset-handle export contract.', }, { command: 'export', displayCommand: 'runs export', minimumSupported: '0.1.111', reason: 'Run result row datasets now use the dataset-handle export contract.', }, ], directToolsCompatibilityVersions: ['0.1.171'], autoUpdatePatchLag: 2, }, } as const satisfies SdkRelease;