deepline 0.2.67 → 0.2.69

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

@@ -1767,6 +1767,10 @@ export class DeeplineClient {
     const cloneEditStarter = this.playCloneEditStarter(play);
     return {
       name: play.name,
+      // playKey and triggerStatus were projected away here, so `plays describe`
+      // was strictly less informative than `plays list` for the same play — no
+      // stable key, and no way to see that a cron was armed.
+      ...(play.playKey ? { playKey: play.playKey } : {}),
       ...(play.reference ? { reference: play.reference } : {}),
       ...(play.displayName ? { displayName: play.displayName } : {}),
       ...(description ? { description } : {}),
@@ -1794,6 +1798,11 @@ export class DeeplineClient {
       examples: [runCommand],
       ...(cloneEditStarter ? { cloneEditStarter } : {}),
       currentPublishedVersion: play.currentPublishedVersion ?? null,
+      // Read the live version off the live revision. It was previously only
+      // ever written by the publish/live routes, so every list and describe
+      // payload reported liveVersion: null even for an actively serving play.
+      liveVersion: play.liveRevision?.version ?? null,
+      ...(play.triggerStatus ? { triggerStatus: play.triggerStatus } : {}),
       isDraftDirty: play.isDraftDirty,
     };
   }

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

@@ -23,6 +23,15 @@ export type SdkCompatibilityResponse = {
   message: string;
   update_command: string;
   command?: string | null;
+  /**
+   * Present only when the queried command postdates this CLI. Advisory: the
+   * client is not unsupported, it simply predates the command.
+   */
+  command_introduced_in?: {
+    command: string;
+    introduced_in: string;
+    reason: string;
+  };
   auto_update?: {
     should_auto_update: boolean;
     required: boolean;

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

@@ -91,6 +91,29 @@ export type SdkSupportPolicy = {
     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[];
   /**
@@ -160,7 +183,7 @@ export const SDK_RELEASE = {
   // 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.
-  version: '0.2.67',
+  version: '0.2.69',
   contracts: {
     api: {
       name: 'sdk-http-api',
@@ -188,6 +211,14 @@ export const SDK_RELEASE = {
   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',

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

@@ -1130,6 +1130,8 @@ export interface ProductNotification {
 
 export interface PlayDescription {
   name: string;
+  /** Stable registry key. Same value `plays list` reports for this play. */
+  playKey?: string;
   reference?: string;
   displayName?: string;
   description?: string | null;
@@ -1151,6 +1153,17 @@ export interface PlayDescription {
     checkCommand: string;
   };
   currentPublishedVersion?: number | null;
+  /**
+   * Version currently serving runs by name, from the live revision. Null when
+   * the play has never been published.
+   */
+  liveVersion?: number | null;
+  /** Whether this play's cron and webhook triggers are armed. */
+  triggerStatus?: {
+    cron: string | null;
+    webhook: string | null;
+    blockedReason: string | null;
+  };
   isDraftDirty?: boolean;
   latestRunId?: string | null;
 }

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -383,19 +383,44 @@ export type PlaySqlQuery = {
 };
 
 declare const PLAY_SECRET_HANDLE_BRAND: unique symbol;
+/**
+ * An opaque reference to a workspace secret, returned by `ctx.secrets.get`. The handle never carries the value into play code: it stringifies to `[secret:NAME]` and throws on `JSON.stringify`, so a secret cannot reach a play variable, a log line, a dataset cell, or a replay artifact even by accident. Only the runtime resolves it, at the moment it attaches the request header.
+ *
+ * @sdkReference runtime 176 SecretHandle
+ */
 export type PlaySecretHandle = {
   readonly [PLAY_SECRET_HANDLE_BRAND]: never;
+  /** Name of the workspace secret, uppercased. Never its value. */
   readonly name: string;
+  /** Renders `[secret:NAME]`, so an interpolated handle leaks nothing. */
   toString(): string;
+  /** Always throws. A secret handle is deliberately not serializable. */
   toJSON(): never;
 };
+/**
+ * One resolved authentication scheme, built by `ctx.secrets.bearer` or `ctx.secrets.header` and attached to a request through `init.auth`.
+ *
+ * @sdkReference runtime 177 SecretAuth
+ */
 export type PlaySecretAuth = {
+  /** `bearer` sends `Authorization: Bearer <value>`; `header` sends a named header. */
   readonly kind: 'bearer' | 'header';
+  /** The handle whose value the runtime attaches. */
   readonly secret: PlaySecretHandle;
+  /** Header name, set only when `kind` is `header`. */
   readonly header?: string;
 };
+/**
+ * The `init` accepted by `ctx.fetch`. Same shape as `RequestInit` plus `auth`.
+ *
+ * @sdkReference runtime 174 SecretAwareRequestInit
+ */
 export type PlaySecretAwareRequestInit = Omit<RequestInit, 'headers'> & {
+  /** Ordinary request headers, recorded in the durable receipt. Never interpolate a secret value here — use `auth`. */
   headers?: HeadersInit;
+  /**
+   * The single authenticated header for this request. One value, not a list: exactly one `ctx.secrets` auth attaches per `ctx.fetch`. An API wanting two credentialed headers at once — Supabase with both `apikey` and `Authorization` — cannot express both. Put the must-stay-secret credential in `auth`; pass a genuinely non-secret second value in `headers`. If both are secret, the request needs a server-side proxy holding one of them.
+   */
   auth?: PlaySecretAuth;
 };
 export type PlayLooseObject = { [key: string]: PlayLooseObject };
@@ -789,13 +814,27 @@ export type PlayAuthoringFetchOptions = {
   staleAfterSeconds?: DurableCallStaleAfterSeconds;
 };
 
+/**
+ * The value `ctx.fetch(...)` resolves to: a plain durable record, not a WHATWG `Response`. The body is read once at request time so the call can be checkpointed and replayed, so `bodyText` and `json` are already-materialized properties. There is no `.json()`, `.text()`, or `.body` to await — `await res.json()` is a type error, not a typing problem.
+ *
+ * @sdkReference runtime 175 PlayFetchResponse
+ */
 export type PlayAuthoringFetchResponse = {
+  /** True when the response status is in the 2xx range. */
   ok: boolean;
+  /** HTTP status code as returned by the upstream server. */
   status: number;
+  /** HTTP status text as returned by the upstream server. */
   statusText: string;
+  /** Final response URL after any redirects. */
   url: string;
+  /** Response headers, lowercased, with any known secret values redacted. */
   headers: Record<string, string>;
+  /** Full response body as text, with any known secret values redacted. */
   bodyText: string;
+  /**
+   * The parsed body, eagerly decoded at request time. Read it as a property — `const body = res.json`, never `await res.json()`. Null when the body is empty AND when it is not valid JSON: a malformed payload is reported as null rather than thrown, so check `res.ok` and fall back to `res.bodyText` before treating null as an empty result.
+   */
   json: unknown | null;
 };
 
@@ -831,8 +870,24 @@ export const PLAY_AUTHORING_DOCUMENTATION = {
       'ctx.run.id is stable while Deepline retries or resumes one durable run. A separately submitted run receives a new id.',
     use: 'Use it when deriving an external idempotency key for a sequence of batches.',
   },
+  staticCallKeys: {
+    constraint:
+      'Durable call keys — the ctx.fetch key, the ctx.dataset key, the ctx.step id — must be static string literals. The key names a durable receipt, so check, publish, and replay have to agree on it before the body runs. A key computed at runtime cannot be resolved at check time and is rejected.',
+    consequence:
+      'This is an architectural constraint, not a style rule. A play cannot loop over a computed key, so it cannot page a large table with a helper like page(pageNumber). Unrolling one literal key per page is not a design at any real page count.',
+    workaround:
+      'Push the aggregation server-side and call it once: a SQL function, a view, or a provider endpoint that returns the whole result. Keep unrolled literal keys only for a handful of genuinely distinct calls. To fan out over rows, use ctx.dataset with a static key — the per-row receipt identity comes from the row, not from the key.',
+  },
 } as const;
 
+/**
+ * Shown when a ctx.fetch key is present but not statically resolvable. Named
+ * separately so the field registry, the check hint, and the generated
+ * reference cannot drift from one another.
+ */
+export const PLAY_AUTHORING_STATIC_FETCH_KEY_HINT =
+  `${PLAY_AUTHORING_DOCUMENTATION.staticCallKeys.workaround} Do not compute the key.` as const;
+
 /** The complete customer-authored `ctx` Interface shared by every Adapter. */
 export interface PlayAuthoringRuntimeContext {
   /**
@@ -932,8 +987,23 @@ export interface PlayAuthoringRuntimeContext {
   ): Promise<PlayAuthoringFetchResponse>;
 
   secrets: {
+    /**
+     * Reference a workspace secret by name without reading its value. This is the only supported way to authenticate an outbound request from a Play: `process.env.X` is rejected at check time because an env read puts the raw value in a play variable, where it can reach a log line or a replay artifact. A handle cannot — pass it to `bearer` or `header` and the runtime resolves it only while attaching the header. Names are uppercased; manage stored values with `deepline secrets set` / `deepline secrets list`.
+     *
+     * @sdkReference runtime 171 ctx.secrets.get(name)
+     */
     get(name: string): PlaySecretHandle;
+    /**
+     * Send the secret as `Authorization: Bearer <value>`.
+     *
+     * @sdkReference runtime 172 ctx.secrets.bearer(secret)
+     */
     bearer(secret: PlaySecretHandle): PlaySecretAuth;
+    /**
+     * Send the secret as a named header, for APIs that do not use bearer tokens — `x-api-key`, `apikey`, `private-token`, and similar.
+     *
+     * @sdkReference runtime 173 ctx.secrets.header(header, secret)
+     */
     header(header: string, secret: PlaySecretHandle): PlaySecretAuth;
   };
 
@@ -1830,6 +1900,7 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     issueCode: 'play_authoring_durable_policy_invalid',
     description: 'Stable durable identity for one external HTTP request.',
     errorMessage: 'ctx.fetch key must be a non-empty static string.',
+    unresolvedHint: PLAY_AUTHORING_STATIC_FETCH_KEY_HINT,
   },
   'ctx.fetch.staleAfterSeconds': {
     schema: Type.Union([Type.Null(), Type.Integer({ minimum: 0 })]),
@@ -2220,6 +2291,13 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     issueCode: PlayAuthoringContractIssueCode;
     description: string;
     errorMessage: string;
+    /**
+     * Hint shown when the value is present but could not be resolved
+     * statically. Defaults to generic "use a literal" advice, which is useless
+     * when the author has a real reason to compute the value. Set this on any
+     * field where the reason is common enough to name the way out.
+     */
+    unresolvedHint?: string;
   }
 >;
 
@@ -2331,6 +2409,25 @@ function cloudReferenceType(path: PlayAuthoringFieldPath): string {
   return PLAY_AUTHORING_FIELD_REGISTRY[path].referenceType;
 }
 
+const DEFAULT_UNRESOLVED_HINT =
+  'Use a literal value so check, publish, and runtime agree.';
+
+/**
+ * Hint for a field that is present but not statically resolvable.
+ *
+ * The registry is `as const satisfies`, so an entry without `unresolvedHint`
+ * has no such property in its literal type. Read it through here rather than
+ * widening the registry and losing the per-field schema narrowing.
+ */
+export function playAuthoringUnresolvedHint(
+  path: PlayAuthoringFieldPath,
+): string {
+  const definition = PLAY_AUTHORING_FIELD_REGISTRY[path] as {
+    unresolvedHint?: string;
+  };
+  return definition.unresolvedHint ?? DEFAULT_UNRESOLVED_HINT;
+}
+
 /** Ambient declarations generated into the cloud Play compiler from this model. */
 export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   `export type DurableCallStaleAfterSeconds = ${cloudReferenceType('ctx.tools.execute.staleAfterSeconds')};`,