deepline 0.3.88 → 0.3.90

package/dist/bundling-sources/shared_libs/plays/share/types.ts

@@ -0,0 +1,197 @@
+/**
+ * Package-owned types for Shareable Play Pages.
+ *
+ * These types are imported by Convex functions (`packages/convex/playSharePages.ts`),
+ * Next.js API routes, and the public landing page. They are the single,
+ * bounded contract for everything that crosses the public boundary.
+ *
+ * See docs/shareable-play-pages-plan.md.
+ */
+// This Module is bundled by Convex through its workspace dependency graph.
+import type { PlayStaticSubstep } from '../static-pipeline';
+
+/** SEO indexing posture for a share page or a specific version URL. */
+export type PlayShareSeoIndexing = 'index' | 'noindex';
+
+/**
+ * Generated landing-page copy, tied to one immutable Play Revision.
+ *
+ * Every field is plain human/agent-readable text. Nothing here may contain
+ * provider spend, secrets, raw runtime internals, or unpublished source.
+ */
+export type PlayShareGeneratedCopy = {
+  /** Concrete, job-focused landing title. */
+  title: string;
+  /** One paragraph, plain English. */
+  shortDescription: string;
+  /** The job the Play performs (jobs-to-be-done). */
+  jtbd: string;
+  /** 3-5 bullets describing when to reach for this Play. */
+  whenToUse: string[];
+  /** Concrete required inputs. */
+  inputs: string[];
+  /** Concrete produced outputs. */
+  outputs: string[];
+  /** Paste-ready Claude Code/Cursor/Codex instruction. */
+  agentPrompt: string;
+  /** Explicit, readable summary for LLM ingestion. */
+  llmSummary: string;
+  /** Search-result title. */
+  seoTitle: string;
+  /** Search-result description. */
+  seoDescription: string;
+};
+
+/** Owner overrides merge over generated copy at read time. */
+export type PlayShareCopyOverrides = Partial<PlayShareGeneratedCopy>;
+
+/**
+ * A single node in the bounded pipeline preview. Never includes source code,
+ * params, secrets, or provider spend — only a shape and a human label.
+ */
+export type PlaySharePreviewStep = {
+  /** Human-readable action, e.g. "search people by domain". */
+  label: string;
+  /** Provider name backing this step, when known. */
+  provider: string | null;
+};
+
+export type PlaySharePreviewNode = {
+  type:
+    | 'csv'
+    | 'dataset'
+    | 'tool'
+    | 'waterfall'
+    | 'step_suite'
+    | 'control_flow'
+    | 'play_call'
+    | 'play_launch'
+    | 'run_javascript'
+    | 'code';
+  /** Human-readable label, e.g. "Apollo" or "Dataset rows". */
+  label: string;
+  /** Optional provider name when this node calls a provider. */
+  provider?: string | null;
+  /** Optional secondary line, e.g. an input field or step kind. */
+  detail?: string | null;
+  /** Ordered sub-steps for waterfall / step-suite nodes (bounded). */
+  steps?: PlaySharePreviewStep[];
+};
+
+/** Bounded static-pipeline summary safe for public display. */
+export type PlayShareStaticPipelineSummary = {
+  stepCount: number;
+  providerCount: number;
+  hasMap: boolean;
+  previewNodes: PlaySharePreviewNode[];
+};
+
+/** Bounded, safe representation of the revision's input/output shape. */
+export type PlayShareSchemaShape = {
+  fields: string[];
+} | null;
+
+/**
+ * The ONLY object consumed by the public page and the public share API.
+ * Everything here is safe to expose to anyone with the unlisted link.
+ */
+export type PublishedPlayPagePackage = {
+  page: {
+    /** Internal stable record id. Never a public URL — pages are namespaced. */
+    shareSlug: string;
+    /** Org URL handle; the public page lives at `/p/:orgSlug/:playName`. */
+    orgSlug: string;
+    visibility: 'unlisted';
+    seoIndexing: PlayShareSeoIndexing;
+    /** Canonical path, e.g. `/p/:orgSlug/:playName/v/:publishedVersion`. */
+    canonicalPath: string;
+    /** Whether the requested URL is the currently-published version. */
+    isPublishedVersion: boolean;
+    /** When this version's public page was last published/updated. */
+    publishedAt: number;
+  };
+  definition: {
+    name: string;
+    ownerDisplayName: string | null;
+  };
+  revision: {
+    id: string;
+    version: number;
+    graphHash: string | null;
+    staticPipelineSummary: PlayShareStaticPipelineSummary;
+    /** Sanitized top-level substeps for the real v2 step-graph render. */
+    substeps: PlayStaticSubstep[];
+    inputSchema: PlayShareSchemaShape;
+    outputSchema: PlayShareSchemaShape;
+  };
+  copy: PlayShareGeneratedCopy;
+  publicMetrics: PublishedPlayPageMetrics;
+};
+
+/**
+ * Which cost denominator is comparable across runs of different input sizes,
+ * derived from the play's map shape. See `classifyCostBasis`.
+ */
+export type PlayCostBasis = 'run' | 'row' | 'none';
+
+/** Public, credit-only metrics. Provider spend is never present. */
+export type PublishedPlayPageMetrics = {
+  averageDeeplineCostCredits: number | null;
+  averageCostPerInputRowCredits: number | null;
+  averageCostPerOutputLeadCredits: number | null;
+  averageLatencyMs: number | null;
+  sampleRunCount: number;
+  /**
+   * The only cost denominator that is comparable across runs of different input
+   * sizes, derived from the play's map shape: `'run'` (flat play), `'row'`
+   * (single dataset over input rows), or `'none'` (multiple/nested datasets — no honest
+   * denominator, so cost is suppressed). Drives which credit metric the page
+   * renders, if any.
+   */
+  costBasis: PlayCostBasis;
+};
+
+/**
+ * Authenticated owner view of a share page (returned by GET/POST/PATCH
+ * `/api/v2/plays/:name/share`). Includes management metadata not exposed
+ * to the public read model.
+ */
+export type PlaySharePageOwnerView = {
+  shareSlug: string;
+  /** Org URL handle; the public page lives at `/p/:orgSlug/:playName`. */
+  orgSlug: string;
+  publishedRevisionId: string;
+  publishedVersion: number;
+  visibility: 'unlisted';
+  seoIndexing: PlayShareSeoIndexing;
+  showAverageDeeplineCost: boolean;
+  showAverageLatency: boolean;
+  publicPath: string;
+  canonicalPath: string;
+  createdAt: number;
+  updatedAt: number;
+};
+
+/**
+ * One row in the byte-bounded owner-facing version picker. The status response
+ * includes recent revisions plus any older working, live, public, or explicitly
+ * selected dashboard revision.
+ */
+export type PlaySharePageRevisionOption = {
+  revisionId: string;
+  version: number;
+  hasMap: boolean;
+  createdAt: number;
+  isLive: boolean;
+  isWorking: boolean;
+  isPublished: boolean;
+  hasCard: boolean;
+};
+
+/** Full payload for GET `/api/v2/plays/:name/share`. */
+export type PlaySharePageStatusResponse = {
+  playName: string;
+  share: PlaySharePageOwnerView | null;
+  publishedCopy: PlayShareGeneratedCopy | null;
+  revisions: PlaySharePageRevisionOption[];
+};

package/dist/bundling-sources/shared_libs/plays/slack-hitl-timeout-error.ts

@@ -0,0 +1,37 @@
+import { ToolExecutionError } from './tool-execution-error';
+
+/** Stable code for an unanswered `slack_message_with_hitl` approval. */
+export const SLACK_HITL_TIMEOUT_ERROR_CODE = 'SLACK_HITL_TIMEOUT' as const;
+
+/**
+ * A Slack human-in-the-loop approval reached its deadline without a decision.
+ *
+ * Deepline first confirms that it replaced the Slack card with “Interaction
+ * timed out.” and removed its controls. The error is non-retryable and
+ * runner-fatal: an authored `try/catch` may observe it, but cannot settle the
+ * Play successfully or start another durable operation. Retry the Play only
+ * after changing its input or timeout policy.
+ *
+ */
+export class SlackHitlTimeoutError extends ToolExecutionError {
+  constructor(message?: string) {
+    const detail =
+      message?.trim() ||
+      'Slack approval timed out before a human decision was received.';
+    super(`${SLACK_HITL_TIMEOUT_ERROR_CODE}: ${detail}`, {
+      toolId: 'slack_message_with_hitl',
+      provider: 'slack',
+      operation: 'slack_message_with_hitl',
+      code: SLACK_HITL_TIMEOUT_ERROR_CODE,
+      origin: 'deepline',
+      category: 'conflict',
+      retryable: false,
+      statusCode: 408,
+      requestId: null,
+      retryAfterMs: null,
+      networkKind: null,
+      networkScope: null,
+    });
+    this.name = 'SlackHitlTimeoutError';
+  }
+}

package/dist/bundling-sources/shared_libs/plays/slug.ts

@@ -0,0 +1,115 @@
+/**
+ * Canonical slug helpers — the single home for URL-handle normalization and
+ * unguessable-suffix generation. Shared by Convex (relative `.//slug`)
+ * and the Next app (`.//slug`).
+ *
+ * Used by:
+ * - Organization slugs (the org's stable URL handle)
+ * - Share-page slugs (`/p/{shareSlug}`) and version paths
+ * - Play-name slug bases
+ *
+ * Intentionally NOT covered here (different concerns — kept separate so this
+ * stays a real seam, not DRY-for-its-own-sake):
+ * - URL → durable-scope slugs (parse host:port; playground backend / scripts)
+ * - DataForSEO codegen `kebabCase` (underscore-only transform)
+ */
+
+const SHARE_SLUG_NAME_MAX_LEN = 48;
+const SHARE_SLUG_SUFFIX_LEN = 8;
+const SUFFIX_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+
+/**
+ * Normalize an arbitrary string into a URL-safe kebab slug: lowercase, NFKD-fold
+ * accents, collapse every run of non-`[a-z0-9]` into a single dash, trim edge
+ * dashes, and optionally cap length (re-trimming a trailing dash after the cut).
+ *
+ * Returns `''` for empty/garbage input — callers supply their own domain
+ * fallback (`'team'`, `'play'`, `'ci-bootstrap'`, …), since the right default is
+ * domain-specific.
+ */
+export function normalizeSlug(
+  value: string,
+  options?: { maxLength?: number },
+): string {
+  let slug = value
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  const maxLength = options?.maxLength;
+  if (maxLength !== undefined && slug.length > maxLength) {
+    slug = slug.slice(0, maxLength).replace(/-+$/g, '');
+  }
+  return slug;
+}
+
+/**
+ * Deterministic unguessable suffix from injected bytes (pure + testable). Each
+ * byte maps into a 36-char lowercase-alphanumeric alphabet. `randomBytes` must
+ * be at least `length` long.
+ */
+export function buildSlugSuffix(
+  length: number,
+  randomBytes: Uint8Array,
+): string {
+  if (randomBytes.length < length) {
+    throw new Error(
+      `buildSlugSuffix requires at least ${length} random bytes.`,
+    );
+  }
+  let suffix = '';
+  for (let i = 0; i < length; i += 1) {
+    suffix += SUFFIX_ALPHABET[randomBytes[i] % SUFFIX_ALPHABET.length];
+  }
+  return suffix;
+}
+
+/** Crypto-backed unguessable suffix (Node / Convex / browser global `crypto`). */
+export function randomSlugSuffix(length: number): string {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return buildSlugSuffix(length, bytes);
+}
+
+/** Kebab-case the human play name into the readable share-slug stem. */
+export function playNameToSlugBase(name: string): string {
+  return normalizeSlug(name, { maxLength: SHARE_SLUG_NAME_MAX_LEN }) || 'play';
+}
+
+/**
+ * Build a full share slug from a name stem and a source of randomness. Pure +
+ * deterministic for tests; callers pass crypto-backed bytes.
+ */
+export function buildShareSlug(name: string, randomBytes: Uint8Array): string {
+  const suffix = buildSlugSuffix(SHARE_SLUG_SUFFIX_LEN, randomBytes);
+  return `${playNameToSlugBase(name)}-${suffix}`;
+}
+
+/** Generate a crypto-backed share slug. */
+export function generateShareSlug(name: string): string {
+  return `${playNameToSlugBase(name)}-${randomSlugSuffix(SHARE_SLUG_SUFFIX_LEN)}`;
+}
+
+/**
+ * Public path for a share page — namespaced by org slug + play name.
+ *
+ * This is the ONLY public URL shape. There is no top-level `/p/{slug}`: org
+ * slugs are globally unique (Better Auth) and play names are unique within an
+ * org (`by_orgId_name`), so `{org}/{play}` is globally unique on its own. The
+ * random `shareSlug` is kept only as an internal record id, never a URL.
+ */
+export function buildSharePublicPath(
+  orgSlug: string,
+  playName: string,
+): string {
+  return `/p/${encodeURIComponent(orgSlug)}/${encodeURIComponent(playName)}`;
+}
+
+/** Canonical, version-pinned path for a share page. */
+export function buildShareCanonicalPath(
+  orgSlug: string,
+  playName: string,
+  version: number,
+): string {
+  return `${buildSharePublicPath(orgSlug, playName)}/v/${version}`;
+}

package/dist/bundling-sources/shared_libs/plays/static-pipeline.ts

@@ -212,7 +212,10 @@ export function ensureCompiledSheetContract(
     substeps: PlayStaticSubstep[],
   ): PlayStaticSubstep[] =>
     substeps.map((substep) => {
-      if (substep.type === 'play_call' && substep.pipeline) {
+      if (
+        (substep.type === 'play_call' || substep.type === 'play_launch') &&
+        substep.pipeline
+      ) {
         return {
           ...substep,
           pipeline: ensureCompiledSheetContract(substep.pipeline) ?? null,
@@ -409,7 +412,11 @@ function truncateStaticSubstepsForStorage(
       return truncateStaticSubstepShallowForStorage(base);
     }
 
-    if (base.type !== 'play_call' && 'pipeline' in substepWithoutSourceText) {
+    if (
+      base.type !== 'play_call' &&
+      base.type !== 'play_launch' &&
+      'pipeline' in substepWithoutSourceText
+    ) {
       const nestedPipeline = substepWithoutSourceText.pipeline;
       (base as { pipeline?: PlayStaticPipeline | null }).pipeline =
         nestedPipeline
@@ -435,7 +442,12 @@ function truncateStaticSubstepsForStorage(
         columns: base.columns
           ? base.columns.map((column) => ({
               ...column,
-              producers: column.producers.map((producer) => ({
+              // `producers` was added after some persisted runtime Sheet
+              // contracts already existed. It is descriptive provenance, not
+              // required to identify or persist a Sheet column, so normalize
+              // a legacy omission to its semantic empty value while retaining
+              // the original column contract.
+              producers: (column.producers ?? []).map((producer) => ({
                 ...omitUndefinedProperties({ ...producer }),
                 sourceRange: cloneStorageSafeSourceRange(producer.sourceRange),
                 steps: producer.steps
@@ -489,7 +501,7 @@ function truncateStaticSubstepsForStorage(
       });
     }
 
-    if (base.type !== 'play_call') {
+    if (base.type !== 'play_call' && base.type !== 'play_launch') {
       if (Array.isArray((base as { steps?: unknown }).steps)) {
         return omitUndefinedProperties({
           ...base,
@@ -502,9 +514,9 @@ function truncateStaticSubstepsForStorage(
       return base;
     }
 
-    // A normalized authoring graph intentionally leaves a named play-call's
-    // child pipeline absent. That is a reference edge, not a failed or
-    // truncated resolution, so preserve it without inventing an error.
+    // A normalized authoring graph may leave a named Play reference's child
+    // pipeline absent. That is a reference edge, not a failed or truncated
+    // resolution, so preserve it without inventing an error.
     if (
       !base.pipeline &&
       !Object.prototype.hasOwnProperty.call(substep, 'pipeline') &&
@@ -617,11 +629,7 @@ export function createStaticPipelineReferenceProjection(
     preserveEmbeddedPlayIds?: ReadonlySet<string>;
   },
 ): PlayStaticPipeline | null | undefined {
-  const stored = truncateStaticPipelineForStorage(pipeline, {
-    maxEmbeddedPlayCallPipelineDepth: Number.POSITIVE_INFINITY,
-    maxStoredSubstepDepth: Number.POSITIVE_INFINITY,
-  });
-  if (!stored) return stored;
+  if (!pipeline) return pipeline;
 
   const projectSteps = (
     steps: PlayStaticSubstep[] | undefined,
@@ -653,6 +661,10 @@ export function createStaticPipelineReferenceProjection(
         }
         return projected;
       }
+      if (projected.type === 'play_launch' && projected.pipeline) {
+        projected.pipeline = projectPipeline(projected.pipeline);
+        return projected;
+      }
       if (
         (projected.type === 'dataset' ||
           projected.type === 'step_suite' ||
@@ -678,7 +690,13 @@ export function createStaticPipelineReferenceProjection(
     substeps: projectSteps(candidate.substeps),
   });
 
-  return projectPipeline(stored);
+  // Prune named child snapshots before the storage-safe deep copy. Resolved
+  // calls can share large child graphs; copying those once per call site only
+  // to discard them can exhaust the launch process before run admission.
+  return truncateStaticPipelineForStorage(projectPipeline(pipeline), {
+    maxEmbeddedPlayCallPipelineDepth: Number.POSITIVE_INFINITY,
+    maxStoredSubstepDepth: Number.POSITIVE_INFINITY,
+  });
 }
 
 function asStaticRecord(value: unknown): Record<string, unknown> | null {
@@ -1315,6 +1333,19 @@ export type PlayStaticSubstep = PlayStaticSubstepMetadata &
         callDepth?: number;
         callPath?: string[];
       }
+    | {
+        type: 'play_launch';
+        playId: string;
+        field: string;
+        inLoop?: boolean;
+        pipeline?: PlayStaticPipeline | null;
+        cycleDetected?: boolean;
+        resolutionError?: string;
+        description?: string;
+        sourceRange?: PlayStaticSourceRange;
+        callDepth?: number;
+        callPath?: string[];
+      }
     | {
         type: 'control_flow';
         kind: 'conditional' | 'loop';
@@ -1601,7 +1632,7 @@ function columnProducerFromSubstep(
           ? 'stepProgram'
           : substep.type === 'control_flow'
             ? 'controlFlow'
-            : substep.type === 'play_call'
+            : substep.type === 'play_call' || substep.type === 'play_launch'
               ? 'playCall'
               : 'transform';
   return {
@@ -1609,7 +1640,9 @@ function columnProducerFromSubstep(
     kind,
     field,
     ...(substep.type === 'tool' ? { toolId: substep.toolId } : {}),
-    ...(substep.type === 'play_call' ? { playId: substep.playId } : {}),
+    ...(substep.type === 'play_call' || substep.type === 'play_launch'
+      ? { playId: substep.playId }
+      : {}),
     ...(substep.conditional ? { conditional: true } : {}),
     ...(substep.disabled ? { disabled: true } : {}),
     ...(substep.sourceRange ? { sourceRange: substep.sourceRange } : {}),
@@ -1624,6 +1657,8 @@ function producerId(substep: PlayStaticSubstep, field: string): string {
     return `${field}:waterfall:${substep.id ?? substep.tool ?? 'unknown'}`;
   }
   if (substep.type === 'play_call') return `${field}:play:${substep.playId}`;
+  if (substep.type === 'play_launch')
+    return `${field}:play-launch:${substep.playId}`;
   if (substep.type === 'step_suite') return `${field}:steps`;
   if (substep.type === 'control_flow')
     return `${field}:control:${substep.kind}:${sourceRangeKey(substep.sourceRange)}`;

package/dist/bundling-sources/shared_libs/plays/tool-category-descriptions.ts

@@ -1,10 +1,10 @@
 // One-line definitions for the tool categories surfaced by `deepline tools list`.
 //
 // Tool categories are free-form strings that each provider tool declares in the
-// generated catalog (see `src/lib/integrations/**`), not a single closed enum.
+// generated catalog (see `packages/integrations/**`), not a single closed enum.
 // The canonical set of well-known category slugs lives next to this file in
 // `DEEPLINE_TOOL_CATEGORIES` (bootstrap-routes.ts) and in the richer
-// `IntegrationCatalogTag` enum (src/lib/integrations/catalog-tags.ts). This map
+// `IntegrationCatalogTag` enum (packages/integrations/catalog-tags.ts). This map
 // MUST track the categories that actually appear on live tools. The CLI derives
 // the category enumeration from the live catalog, so a new category slug shows
 // up automatically; only its human-readable definition comes from here. When a

package/dist/bundling-sources/shared_libs/plays/tool-result-types.ts

@@ -5,7 +5,7 @@ import type { PlayDataset, SerializedPlayDataset } from './dataset';
 export type ToolResultExecutionMetadata = {
   idempotent: true;
   cached: boolean;
-  source: 'live' | 'checkpoint' | 'cache' | 'in_flight';
+  source: 'live' | 'checkpoint' | 'cache' | 'in_flight' | 'source_run';
   cacheKey?: string;
   receiptRole?: 'owner' | 'follower';
   receiptKey?: string;