deepline 0.1.65 → 0.1.67

package/dist/repo/apps/play-runner-workers/src/dedup-do.ts

@@ -17,6 +17,41 @@
  */
 
 import { sanitizeLiveLogLines } from './runtime/live-progress';
+import type { PreloadedRuntimeDbSession } from '../../../shared_libs/play-runtime/db-session';
+
+type DurableObjectStorage = {
+  get<T>(key: string): Promise<T | undefined>;
+  get<T>(keys: string[]): Promise<Map<string, T>>;
+  put<T>(key: string, value: T): Promise<void>;
+  put<T>(entries: Record<string, T>): Promise<void>;
+  delete(key: string | string[]): Promise<unknown>;
+  deleteAll(): Promise<void>;
+  list<T>(options?: { prefix?: string }): Promise<Map<string, T>>;
+  setAlarm(scheduledTime: number): Promise<void>;
+};
+
+type DurableObjectState = {
+  storage: DurableObjectStorage;
+  blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+};
+
+type DurableObject = {
+  fetch(request: Request): Promise<Response>;
+  alarm?(): Promise<void>;
+};
+
+type DurableObjectId = {
+  toString(): string;
+};
+
+type DurableObjectStub = {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+};
+
+type DurableObjectNamespace = {
+  idFromName(name: string): DurableObjectId;
+  get(id: DurableObjectId): DurableObjectStub;
+};
 
 type DedupEntry =
   | { status: 'in_flight'; claimedBy: string; claimedAt: number }
@@ -83,6 +118,13 @@ type WorkflowRunRetryState = {
   expiresAt: number;
 };
 
+type WorkflowDbSessionsState = {
+  runId: string;
+  sessions: PreloadedRuntimeDbSession[];
+  storedAt: number;
+  expiresAt: number;
+};
+
 type CoordinatorTraceEntry = {
   ts: number;
   source: 'coordinator' | 'dynamic_worker';
@@ -166,6 +208,7 @@ const DEDUP_KEY_PREFIX = 'd:';
 const WORKFLOW_POOL_KEY_PREFIX = 'p:';
 const WORKFLOW_POOL_RUN_KEY_PREFIX = 'm:';
 const WORKFLOW_RUN_RETRY_KEY_PREFIX = 'r:';
+const WORKFLOW_DB_SESSIONS_KEY = 'db-sessions';
 const COORDINATOR_TRACE_KEY_PREFIX = 't:';
 const COORDINATOR_RUN_EVENT_KEY_PREFIX = 'e:';
 const COORDINATOR_TERMINAL_KEY = 'terminal';
@@ -177,11 +220,27 @@ const WORKFLOW_POOL_DEFAULT_TTL_MS = 8 * 60 * 1000;
 const WORKFLOW_POOL_RUN_MAPPING_TTL_MS = 60 * 60 * 1000;
 const WORKFLOW_POOL_READY_MAX_AGE_MS = 7 * 60_000;
 const WORKFLOW_RUN_RETRY_STATE_MAX_BYTES = 110_000;
+const WORKFLOW_DB_SESSIONS_TTL_MS = 10 * 60_000;
 
 function jsonByteLength(value: unknown): number {
   return new TextEncoder().encode(JSON.stringify(value)).byteLength;
 }
 
+function assertEncryptedDbSessionsForStorage(
+  sessions: PreloadedRuntimeDbSession[],
+): void {
+  for (const session of sessions) {
+    if (session.session.postgresUrl) {
+      throw new Error('preloaded db session storage rejects raw Postgres URLs');
+    }
+    if (!session.session.encryptedPostgresUrl) {
+      throw new Error(
+        'preloaded db session storage requires encrypted Postgres URLs',
+      );
+    }
+  }
+}
+
 interface DedupEnv {
   PLAY_DEDUP: DurableObjectNamespace;
 }
@@ -252,6 +311,10 @@ export class PlayDedup implements DurableObject {
           return await this.handleRunRetryStatePut(req);
         case '/run-retry-claim':
           return await this.handleRunRetryClaim(req);
+        case '/db-sessions-put':
+          return await this.handleDbSessionsPut(req);
+        case '/db-sessions-get':
+          return await this.handleDbSessionsGet(req);
         case '/pool-clear':
           return await this.handlePoolClear(req);
         case '/trace-add':
@@ -1086,6 +1149,77 @@ export class PlayDedup implements DurableObject {
     });
   }
 
+  private async handleDbSessionsPut(req: Request): Promise<Response> {
+    const body = (await req.json().catch(() => null)) as {
+      runId?: unknown;
+      sessions?: unknown;
+      ttlMs?: unknown;
+    } | null;
+    const runId = typeof body?.runId === 'string' ? body.runId : '';
+    const sessions = Array.isArray(body?.sessions)
+      ? (body.sessions as PreloadedRuntimeDbSession[])
+      : null;
+    if (!runId || !sessions) {
+      return new Response('runId and sessions are required', { status: 400 });
+    }
+    assertEncryptedDbSessionsForStorage(sessions);
+    const now = Date.now();
+    const ttlMs =
+      typeof body?.ttlMs === 'number' &&
+      Number.isFinite(body.ttlMs) &&
+      body.ttlMs > 0
+        ? Math.min(Math.max(Math.floor(body.ttlMs), 60_000), 30 * 60_000)
+        : WORKFLOW_DB_SESSIONS_TTL_MS;
+    const state: WorkflowDbSessionsState = {
+      runId,
+      sessions,
+      storedAt: now,
+      expiresAt: now + ttlMs,
+    };
+    await this.state.storage.put(WORKFLOW_DB_SESSIONS_KEY, state);
+    return new Response(
+      JSON.stringify({
+        ok: true,
+        sessionCount: sessions.length,
+        expiresAt: state.expiresAt,
+      }),
+      { headers: { 'content-type': 'application/json' } },
+    );
+  }
+
+  private async handleDbSessionsGet(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    const runId = url.searchParams.get('runId') ?? '';
+    if (!runId) {
+      return new Response('runId is required', { status: 400 });
+    }
+    const state = await this.state.storage.get<WorkflowDbSessionsState>(
+      WORKFLOW_DB_SESSIONS_KEY,
+    );
+    if (!state || state.runId !== runId) {
+      return new Response(JSON.stringify({ error: 'db sessions not found' }), {
+        status: 404,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+    if (state.expiresAt <= Date.now()) {
+      await this.state.storage.delete(WORKFLOW_DB_SESSIONS_KEY);
+      return new Response(JSON.stringify({ error: 'db sessions expired' }), {
+        status: 410,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+    assertEncryptedDbSessionsForStorage(state.sessions);
+    return new Response(
+      JSON.stringify({
+        sessions: state.sessions,
+        sessionCount: state.sessions.length,
+        expiresAt: state.expiresAt,
+      }),
+      { headers: { 'content-type': 'application/json' } },
+    );
+  }
+
   private async handlePoolClear(req: Request): Promise<Response> {
     const version = this.workflowPoolVersion(req);
     const [pool, mappings, retries] = await Promise.all([

package/dist/repo/apps/play-runner-workers/src/entry.ts

@@ -86,6 +86,7 @@ import type {
   PlayRunLedgerStepProgress,
   PlayRunLedgerStepStatus,
 } from '../../../shared_libs/play-runtime/run-ledger';
+import type { PlayHarnessRpc } from '../../play-harness-worker/src/rpc-types';
 import {
   createCsvDatasetHandle,
   createInlineDatasetHandle,
@@ -272,18 +273,11 @@ type WorkerEnv = {
     ): Promise<void>;
   };
   /**
-   * Service binding to the long-lived Play Harness Worker
+   * Required service binding to the long-lived Play Harness Worker
    * (apps/play-harness-worker). Wired by the coordinator's WorkerLoader
-   * factory — see apps/play-runner-workers/src/coordinator-entry.ts. The
-   * binding's typed RPC surface is `PlayHarnessRpc`, defined in
-   * apps/play-harness-worker/src/rpc-types.ts.
-   *
-   * Optional: if absent (older coordinator deploy that hasn't been
-   * upgraded, or a dev environment running without the harness Worker),
-   * SDK call sites that try to reach into the harness will throw a
-   * loud error. Loud failures > silent fallbacks.
+   * factory — see apps/play-runner-workers/src/coordinator-entry.ts.
    */
-  HARNESS?: import('../../play-harness-worker/src/rpc-types').PlayHarnessRpc;
+  HARNESS: PlayHarnessRpc;
   VERCEL_PROTECTION_BYPASS_TOKEN?: string;
 };
 
@@ -314,7 +308,18 @@ function captureCoordinatorBinding(env: WorkerEnv): void {
  * across plays.
  */
 function captureHarnessBinding(env: WorkerEnv): void {
-  setHarnessBinding(env.HARNESS ?? null);
+  setHarnessBinding(requireHarnessBinding(env));
+}
+
+function requireHarnessBinding(env: WorkerEnv): PlayHarnessRpc {
+  const harness = env.HARNESS;
+  if (!harness) {
+    throw new Error(
+      'Cloudflare play Workers require the HARNESS service binding. ' +
+        'Start apps/play-harness-worker before the coordinator or fix wrangler.toml services.',
+    );
+  }
+  return harness;
 }
 
 /**
@@ -325,17 +330,12 @@ function captureHarnessBinding(env: WorkerEnv): void {
  * to plumb a separate health route or instrument SDK call sites.
  *
  * Behavior on fail:
- *   - Binding missing entirely → log clearly that HARNESS is unwired so
- *     anyone investigating cold-path perf knows the harness isn't in the
- *     loop yet.
- *   - Binding present but ping throws → log the error. Don't re-throw —
- *     a probe failure must NEVER block the play; if a real call site
- *     later needs HARNESS and the binding is broken, that call site's
- *     own throw is the loud failure (see harness-stub → requireBinding).
+ *   - Binding or ping failure → fail the run. HARNESS is required in every
+ *     deployed environment; no fallback should hide a miswired harness.
  *
  * This is intentionally idempotent and cheap (a single ping RPC,
  * deduplicated per isolate via the module-level guard) so the probe
- * itself never adds measurable latency to a run.
+ * itself never adds meaningful latency to a run.
  */
 let harnessProbeFiredForIsolate = false;
 async function probeHarnessOnce(
@@ -343,33 +343,16 @@ async function probeHarnessOnce(
   runPrefix: string,
 ): Promise<void> {
   if (harnessProbeFiredForIsolate) return;
-  harnessProbeFiredForIsolate = true;
-  if (!env.HARNESS) {
-    console.log(
-      `${runPrefix} [harness-probe] env.HARNESS unwired — coordinator did not pass the binding. ` +
-        `Per-play SDK call sites that reach into the harness will throw clearly. ` +
-        `See apps/play-harness-worker/README.md.`,
-    );
-    return;
-  }
-  if (
-    typeof (env.HARNESS as { ping?: () => Promise<{ ok: true; ts: number }> })
-      .ping !== 'function'
-  ) {
-    console.log(
-      `${runPrefix} [harness-probe] env.HARNESS is present but does not expose ping(); ` +
-        `continuing and relying on the first real call to fail if the contract changed.`,
-    );
-    return;
-  }
+  const harness = requireHarnessBinding(env);
   try {
-    const result = await env.HARNESS.ping();
+    const result = await harness.ping();
+    harnessProbeFiredForIsolate = true;
     console.log(
       `${runPrefix} [harness-probe] env.HARNESS connected ts=${result.ts}`,
     );
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    console.log(
+    throw new Error(
       `${runPrefix} [harness-probe] env.HARNESS resolved but ping failed: ${message}`,
     );
   }
@@ -3028,6 +3011,7 @@ async function persistCompletedMapRows(input: {
   await harnessPersistCompletedSheetRows({
     baseUrl: input.req.baseUrl,
     executorToken: input.req.executorToken,
+    orgId: input.req.orgId,
     preloadedDbSessions: input.req.preloadedDbSessions ?? null,
     playName: input.req.playName,
     tableNamespace: input.tableNamespace,
@@ -3060,6 +3044,7 @@ async function prepareMapRows(input: {
   const result = await harnessStartSheetDataset({
     baseUrl: input.req.baseUrl,
     executorToken: input.req.executorToken,
+    orgId: input.req.orgId,
     preloadedDbSessions: input.req.preloadedDbSessions ?? null,
     playName: input.req.playName,
     tableNamespace: input.tableNamespace,
@@ -3233,22 +3218,22 @@ function createMinimalWorkerCtx(
   };
   const rootGovernance = req.playCallGovernance;
   const rootRunId = rootGovernance?.rootRunId ?? req.runId;
-  const receiptStore = env.HARNESS
-    ? createHarnessWorkerReceiptStore({ executorToken: req.executorToken })
-    : undefined;
+  const receiptStore = createHarnessWorkerReceiptStore({
+    executorToken: req.executorToken,
+    orgId: req.orgId,
+    preloadedDbSessions: req.preloadedDbSessions ?? null,
+    userEmail: req.userEmail,
+  });
   const executeWithRuntimeReceipt = async <T>(
     key: string,
     execute: () => Promise<T> | T,
     repairRunningReceiptForSameRun = false,
   ): Promise<T> => {
     const serialized = await runWorkerRuntimeReceiptBoundary<unknown>({
-      baseUrl: req.baseUrl,
-      executorToken: req.executorToken,
       orgId: req.orgId,
       playName: req.playName,
       runId: req.runId,
       key,
-      postRuntimeApi,
       receiptStore,
       execute: async () => serializeDurableStepValue(await execute()),
       repairRunningReceiptForSameRun,
@@ -3897,6 +3882,7 @@ function createMinimalWorkerCtx(
           const result = await harnessReadSheetDatasetRows({
             baseUrl: req.baseUrl,
             executorToken: req.executorToken,
+            orgId: req.orgId,
             playName: req.playName,
             tableNamespace: name,
             runId: req.runId,
@@ -5273,6 +5259,7 @@ async function persistResultDatasets(
       await harnessStartSheetDataset({
         baseUrl: req.baseUrl,
         executorToken: req.executorToken,
+        orgId: req.orgId,
         playName: req.playName,
         tableNamespace: dataset.tableNamespace,
         sheetContract: requireSheetContract(req, dataset.tableNamespace),
@@ -5295,6 +5282,7 @@ async function persistResultDatasets(
     await harnessStartSheetDataset({
       baseUrl: req.baseUrl,
       executorToken: req.executorToken,
+      orgId: req.orgId,
       preloadedDbSessions: req.preloadedDbSessions ?? null,
       playName: req.playName,
       tableNamespace: dataset.tableNamespace,
@@ -5502,14 +5490,14 @@ export class TenantWorkflow extends WorkflowEntrypoint<
     );
     captureCoordinatorBinding(this.env);
     captureRuntimeApiBinding(this.env);
-    // Hand the harness service binding (if wired) to the SDK-side stub.
+    // Hand the required harness service binding to the SDK-side stub.
     // Must run BEFORE any SDK call site that would reach into HARNESS,
     // i.e. before user play code is invoked. Idempotent within a run.
     captureHarnessBinding(this.env);
     // Fire the one-time wiring probe (deduplicated across runs in the
     // same isolate). Awaited so the result is in the log before user code
-    // begins, but never throws — broken HARNESS at probe time doesn't
-    // block the play; real call-site errors do.
+    // begins. A missing or unhealthy HARNESS fails the run before user code
+    // can accidentally take a slower fallback path.
     await probeHarnessOnce(this.env, runPrefix);
     const abortController = new AbortController();
     try {

package/dist/repo/apps/play-runner-workers/src/runtime/harness-receipt-store.ts

@@ -3,27 +3,40 @@ import {
   harnessCompleteRuntimeReceipt,
   harnessFailRuntimeReceipt,
 } from '../../../../sdk/src/plays/harness-stub';
+import type { PreloadedRuntimeDbSessionInput } from '../../../play-harness-worker/src/rpc-types';
 import type { WorkerRuntimeReceiptStore } from './receipts';
 
 export function createHarnessWorkerReceiptStore(input: {
   executorToken: string;
+  orgId: string;
+  preloadedDbSessions?: PreloadedRuntimeDbSessionInput[] | null;
+  userEmail?: string | null;
 }): WorkerRuntimeReceiptStore {
   return {
     claimReceipt(command) {
       return harnessClaimRuntimeReceipt({
         executorToken: input.executorToken,
+        orgId: input.orgId,
+        preloadedDbSessions: input.preloadedDbSessions ?? null,
+        userEmail: input.userEmail ?? null,
         ...command,
       });
     },
     completeReceipt(command) {
       return harnessCompleteRuntimeReceipt({
         executorToken: input.executorToken,
+        orgId: input.orgId,
+        preloadedDbSessions: input.preloadedDbSessions ?? null,
+        userEmail: input.userEmail ?? null,
         ...command,
       });
     },
     failReceipt(command) {
       return harnessFailRuntimeReceipt({
         executorToken: input.executorToken,
+        orgId: input.orgId,
+        preloadedDbSessions: input.preloadedDbSessions ?? null,
+        userEmail: input.userEmail ?? null,
         ...command,
       });
     },

package/dist/repo/apps/play-runner-workers/src/runtime/receipts.ts

@@ -1,68 +1,28 @@
-import type {
-  WorkReceipt,
-  WorkReceiptClaim,
-  WorkReceiptCommand,
-  WorkReceiptStatus,
-  WorkReceiptStore,
+import {
+  buildScopedWorkReceiptKey,
+  type WorkReceipt,
+  type WorkReceiptClaim,
+  type WorkReceiptCommand,
+  type WorkReceiptStatus,
+  type WorkReceiptStore,
 } from '../../../../shared_libs/play-runtime/work-receipts';
 
 export type RuntimeReceiptStatus = WorkReceiptStatus;
 
 export type WorkerRuntimeReceipt = WorkReceipt;
 
-export type WorkerRuntimeReceiptResponse = {
-  receipt?: WorkerRuntimeReceipt | null;
-};
-
-export type WorkerRuntimeReceiptAction =
-  | {
-      action: 'get_runtime_step_receipt';
-      playName: string;
-      runId: string;
-      key: string;
-    }
-  | {
-      action: 'claim_runtime_step_receipt';
-      playName: string;
-      runId: string;
-      key: string;
-    }
-  | {
-      action: 'complete_runtime_step_receipt';
-      playName: string;
-      runId: string;
-      key: string;
-      output: unknown;
-    }
-  | {
-      action: 'fail_runtime_step_receipt';
-      playName: string;
-      runId: string;
-      key: string;
-      error: string;
-    };
-
 export type WorkerRuntimeReceiptCommand = WorkReceiptCommand;
 
 export type WorkerRuntimeReceiptClaim = WorkReceiptClaim;
 
 export type WorkerRuntimeReceiptStore = WorkReceiptStore;
 
-type PostRuntimeApi = (
-  baseUrl: string,
-  executorToken: string,
-  body: WorkerRuntimeReceiptAction,
-) => Promise<WorkerRuntimeReceiptResponse>;
-
 type RuntimeReceiptContext = {
-  baseUrl?: string;
-  executorToken?: string;
   orgId?: string | null;
   playName: string;
   runId: string;
   key: string;
-  postRuntimeApi?: PostRuntimeApi;
-  receiptStore?: WorkerRuntimeReceiptStore;
+  receiptStore: WorkerRuntimeReceiptStore;
 };
 
 function scopedReceiptKey(input: {
@@ -70,7 +30,7 @@ function scopedReceiptKey(input: {
   playName: string;
   key: string;
 }): string {
-  return `ctx:${input.orgId?.trim() || 'org'}:${input.playName.trim() || 'play'}:${input.key}`;
+  return buildScopedWorkReceiptKey(input);
 }
 
 function receiptOutput<T>(receipt: WorkerRuntimeReceipt): T {
@@ -90,92 +50,6 @@ function runningReceiptError(
   );
 }
 
-function isReusableReceipt(receipt: WorkerRuntimeReceipt): boolean {
-  return receipt.status === 'completed' || receipt.status === 'skipped';
-}
-
-export function createRuntimeApiWorkerReceiptStore(input: {
-  baseUrl: string;
-  executorToken: string;
-  postRuntimeApi: PostRuntimeApi;
-}): WorkerRuntimeReceiptStore {
-  const postRuntimeReceiptAction = (body: WorkerRuntimeReceiptAction) =>
-    input.postRuntimeApi(input.baseUrl, input.executorToken, body);
-
-  return {
-    async claimReceipt(command) {
-      const claimed = await postRuntimeReceiptAction({
-        action: 'claim_runtime_step_receipt',
-        playName: command.playName,
-        runId: command.runId,
-        key: command.key,
-      });
-      if (claimed.receipt) {
-        return { disposition: 'claimed', receipt: claimed.receipt };
-      }
-
-      const latest = await postRuntimeReceiptAction({
-        action: 'get_runtime_step_receipt',
-        playName: command.playName,
-        runId: command.runId,
-        key: command.key,
-      });
-      if (latest.receipt && isReusableReceipt(latest.receipt)) {
-        return { disposition: 'reused', receipt: latest.receipt };
-      }
-      if (latest.receipt?.status === 'running') {
-        return { disposition: 'running', receipt: latest.receipt };
-      }
-      if (latest.receipt?.status === 'failed') {
-        return { disposition: 'failed', receipt: latest.receipt };
-      }
-      throw new Error(
-        `Runtime receipt ${command.key} claim did not return execution ownership.`,
-      );
-    },
-
-    async completeReceipt(command) {
-      const completed = await postRuntimeReceiptAction({
-        action: 'complete_runtime_step_receipt',
-        playName: command.playName,
-        runId: command.runId,
-        key: command.key,
-        output: command.output,
-      });
-      return completed.receipt ?? null;
-    },
-
-    async failReceipt(command) {
-      const failed = await postRuntimeReceiptAction({
-        action: 'fail_runtime_step_receipt',
-        playName: command.playName,
-        runId: command.runId,
-        key: command.key,
-        error: command.error,
-      });
-      return failed.receipt ?? null;
-    },
-  };
-}
-
-function resolveReceiptStore(
-  input: RuntimeReceiptContext,
-): WorkerRuntimeReceiptStore {
-  if (input.receiptStore) {
-    return input.receiptStore;
-  }
-  if (!input.baseUrl || !input.executorToken || !input.postRuntimeApi) {
-    throw new Error(
-      'Runtime receipts require either a receiptStore or Runtime API transport.',
-    );
-  }
-  return createRuntimeApiWorkerReceiptStore({
-    baseUrl: input.baseUrl,
-    executorToken: input.executorToken,
-    postRuntimeApi: input.postRuntimeApi,
-  });
-}
-
 async function executeAndPersistReceipt<T>(input: {
   key: string;
   playName: string;
@@ -223,7 +97,7 @@ export async function runWorkerRuntimeReceiptBoundary<T>(
   },
 ): Promise<T> {
   const key = scopedReceiptKey(input);
-  const receiptStore = resolveReceiptStore(input);
+  const receiptStore = input.receiptStore;
   const claimed = await receiptStore.claimReceipt({
     playName: input.playName,
     runId: input.runId,

package/dist/repo/sdk/src/client.ts

@@ -57,6 +57,9 @@ import type {
   PublishPlayVersionResult,
   StartPlayRunRequest,
   DeletePlayResult,
+  SharePageStatus,
+  PublishSharePageRequest,
+  UpdateSharePageRequest,
   ToolDefinition,
   ToolSearchOptions,
   ToolSearchResult,
@@ -1625,6 +1628,76 @@ export class DeeplineClient {
     return this.http.delete<DeletePlayResult>(`/api/v2/plays/${encodedName}`);
   }
 
+  // ——————————————————————————————————————————————————————————
+  // Plays — public share pages
+  // ——————————————————————————————————————————————————————————
+
+  /**
+   * Current share status for a play: the public page (if any), the published
+   * copy, and the revision picker. Read-only.
+   */
+  async getSharePage(name: string): Promise<SharePageStatus> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.get<SharePageStatus>(`/api/v2/plays/${encodedName}/share`);
+  }
+
+  /**
+   * Publish (or repoint) the play's public share page to a revision. Requires
+   * `acknowledgedUnlisted: true` — the page is publicly viewable. Org-admin only.
+   */
+  async publishSharePage(
+    name: string,
+    request: PublishSharePageRequest,
+  ): Promise<SharePageStatus> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post<SharePageStatus>(
+      `/api/v2/plays/${encodedName}/share`,
+      request,
+    );
+  }
+
+  /**
+   * Update share-page settings (SEO indexing, credit-cost / latency display)
+   * without moving the published pointer. Org-admin only.
+   */
+  async updateSharePage(
+    name: string,
+    request: UpdateSharePageRequest,
+  ): Promise<SharePageStatus> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.patch<SharePageStatus>(
+      `/api/v2/plays/${encodedName}/share`,
+      request,
+    );
+  }
+
+  /**
+   * Unshare: hard-delete the play's public page and its cards. Returns the
+   * fresh status (now `share: null`). Org-admin only. Idempotent — a no-op when
+   * the play was never published.
+   */
+  async unpublishSharePage(name: string): Promise<SharePageStatus> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.delete<SharePageStatus>(
+      `/api/v2/plays/${encodedName}/share`,
+    );
+  }
+
+  /**
+   * Regenerate the LLM landing-page copy for a revision (defaults to the
+   * published one). Org-admin only.
+   */
+  async regenerateSharePage(
+    name: string,
+    request: { revisionId?: string } = {},
+  ): Promise<SharePageStatus> {
+    const encodedName = encodeURIComponent(name);
+    return this.http.post<SharePageStatus>(
+      `/api/v2/plays/${encodedName}/share/regenerate`,
+      request,
+    );
+  }
+
   // ——————————————————————————————————————————————————————————
   // Plays — high-level orchestration
   // ——————————————————————————————————————————————————————————