@hexclave/next 1.0.70 → 1.0.71

package/dist/{quetzal-translations-DVNj-zsr.d.ts.map → quetzal-translations-BT1HrUsA.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"quetzal-translations-DVNj-zsr.d.ts","names":[],"sources":["../src/generated/quetzal-translations.ts"],"mappings":";cAUa,WAAA,EAAW,GAAA;AAAA,cAqTX,cAAA,EAAc,GAAA,mIAAA,GAAA,66qBAAA,GAAA,usnBAAA,GAAA,iyrBAAA,GAAA,g+qBAAA,GAAA,8srBAAA,GAAA,2trBAAA,GAAA,41pBAAA,GAAA,m3eAAA,GAAA,oreAAA,GAAA,swpBAAA,GAAA,+0qBAAA,GAAA,8wbAAA,GAAA"}
+{"version":3,"file":"quetzal-translations-BT1HrUsA.d.ts","names":[],"sources":["../src/generated/quetzal-translations.ts"],"mappings":";cAUa,WAAA,EAAW,GAAA;AAAA,cAqTX,cAAA,EAAc,GAAA,mIAAA,GAAA,66qBAAA,GAAA,usnBAAA,GAAA,iyrBAAA,GAAA,g+qBAAA,GAAA,8srBAAA,GAAA,2trBAAA,GAAA,41pBAAA,GAAA,m3eAAA,GAAA,oreAAA,GAAA,swpBAAA,GAAA,+0qBAAA,GAAA,8wbAAA,GAAA"}

package/dist/{translation-provider-DPFkLbrw.d.ts → translation-provider-C1wy92m_.d.ts}

@@ -1,4 +1,4 @@
-import { n as quetzalLocales } from "./quetzal-translations-DVNj-zsr.js";
+import { n as quetzalLocales } from "./quetzal-translations-BT1HrUsA.js";
 
 //#region src/providers/translation-provider.d.ts
 declare function TranslationProvider({
@@ -12,4 +12,4 @@ declare function TranslationProvider({
 }): import("react/jsx-runtime").JSX.Element;
 //#endregion
 export { TranslationProvider as t };
-//# sourceMappingURL=translation-provider-DPFkLbrw.d.ts.map
+//# sourceMappingURL=translation-provider-C1wy92m_.d.ts.map

package/dist/{translation-provider-DPFkLbrw.d.ts.map → translation-provider-C1wy92m_.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"translation-provider-DPFkLbrw.d.ts","names":[],"sources":["../src/providers/translation-provider.tsx"],"mappings":";;;iBAQgB,mBAAA;EAAsB,IAAA;EAAM,oBAAA;EAAsB;AAAA;EAChE,IAAA,EAAM,UAAA,QAAkB,cAAA,CAAe,GAAA;EACvC,oBAAA,GAAuB,MAAA;EACvB,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA,gCACjB,GAAA,CAAA,OAAA"}
+{"version":3,"file":"translation-provider-C1wy92m_.d.ts","names":[],"sources":["../src/providers/translation-provider.tsx"],"mappings":";;;iBAQgB,mBAAA;EAAsB,IAAA;EAAM,oBAAA;EAAsB;AAAA;EAChE,IAAA,EAAM,UAAA,QAAkB,cAAA,CAAe,GAAA;EACvC,oBAAA,GAAuB,MAAA;EACvB,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA,gCACjB,GAAA,CAAA,OAAA"}

package/dist/workflows-DEb7pIuQ.d.ts

@@ -0,0 +1,125 @@
+import { WorkflowDivergenceDiagnosticJson, WorkflowRunDetailsJson, WorkflowRunJson, WorkflowSummaryJson, WorkflowSyncResultJson, WorkflowVersionJson } from "@hexclave/shared/dist/interface/workflows";
+
+//#region src/lib/hexclave-app/workflows.d.ts
+type AdminWorkflowTrigger = {
+  type: "event";
+  eventType: string;
+} | {
+  type: "schedule";
+  cron: string;
+  timezone: string;
+};
+type AdminWorkflow = {
+  id: string;
+  displayName: string;
+  latestVersion: number;
+  triggers: AdminWorkflowTrigger[];
+  stats: {
+    activeRuns: number;
+    sleepingRuns: number;
+    failed7d: number;
+    runVolume14d: number[];
+  };
+  createdAtMillis: number;
+  lastDeployedAtMillis: number;
+};
+type AdminWorkflowRunState = "queued" | "running" | "sleeping" | "completed" | "failed" | "canceled";
+type AdminWorkflowDivergenceDiagnostic = {
+  reason: WorkflowDivergenceDiagnosticJson["reason"];
+  suspendedStepKey: string | null;
+  foundStepKey: string | null;
+  consumedStepKeys: string[];
+  unconsumedStepKeys: string[];
+  details: string;
+};
+type AdminWorkflowRun = {
+  id: string;
+  workflowId: string;
+  runKey: string | null;
+  state: AdminWorkflowRunState;
+  version: number;
+  triggerType: string;
+  triggerSummary: string;
+  currentStepId: string | null;
+  stepsRecorded: number;
+  errorSummary: string | null;
+  failureKind: "user" | "platform" | null;
+  lastUpgradeDivergence: AdminWorkflowDivergenceDiagnostic | null;
+  createdAtMillis: number;
+  completedAtMillis: number | null;
+  nextWakeAtMillis: number | null;
+};
+type AdminWorkflowStep = {
+  stepKey: string;
+  stepId: string;
+  kind: "run" | "sleep";
+  result: unknown;
+  resultSizeBytes: number;
+  attempts: number;
+  executedAtVersion: number;
+  elapsedMs: number | null;
+  createdAtMillis: number;
+};
+type AdminWorkflowStepAttempt = {
+  stepKey: string;
+  stepId: string; /** 0 for the original execution; incremented by each manual retry of the run. */
+  retryEpoch: number;
+  attempt: number;
+  outcome: "succeeded" | "failed";
+  error: {
+    name: string;
+    message: string;
+    stack?: string;
+  } | null;
+  failureKind: "user" | "platform" | null;
+  logs: string | null;
+  startedAtMillis: number;
+  finishedAtMillis: number;
+};
+type AdminWorkflowRunDetails = AdminWorkflowRun & {
+  triggerPayload: unknown;
+  steps: AdminWorkflowStep[];
+  stepAttempts: AdminWorkflowStepAttempt[];
+};
+type AdminWorkflowVersion = {
+  workflowId: string;
+  version: number;
+  sourceHash: string;
+  source: string;
+  runtimeEnvVersion: string;
+  isLatest: boolean;
+  inFlightRuns: number;
+  createdAtMillis: number;
+};
+type AdminWorkflowSyncResult = {
+  workflowId: string;
+  version: number;
+  created: boolean;
+  inFlightRunsOnOlderVersions: number;
+};
+type AdminWorkflowUpgradeResult = {
+  upgradedCount: number;
+  skipped: {
+    runId: string;
+    runKey: string | null;
+    fromVersion: number;
+    diagnostic: AdminWorkflowDivergenceDiagnostic;
+  }[];
+};
+type AdminWorkflowRunsFilter = {
+  state?: AdminWorkflowRunState;
+  version?: number;
+  runKey?: string;
+  cursor?: string;
+  limit?: number; /** Include each run's memoized steps and attempt history. */
+  includeState?: boolean;
+};
+declare function adminWorkflowFromCrud(crud: WorkflowSummaryJson): AdminWorkflow;
+declare function adminWorkflowRunFromCrud(crud: WorkflowRunJson): AdminWorkflowRun;
+declare function isWorkflowRunDetailsJson(crud: WorkflowRunJson): crud is WorkflowRunDetailsJson;
+declare function adminWorkflowRunDetailsFromCrud(crud: WorkflowRunDetailsJson): AdminWorkflowRunDetails;
+declare function adminWorkflowVersionFromCrud(crud: WorkflowVersionJson): AdminWorkflowVersion;
+declare function adminWorkflowSyncResultFromCrud(crud: WorkflowSyncResultJson): AdminWorkflowSyncResult;
+//#endregion
+export { adminWorkflowVersionFromCrud as _, AdminWorkflowRunState as a, AdminWorkflowStepAttempt as c, AdminWorkflowUpgradeResult as d, AdminWorkflowVersion as f, adminWorkflowSyncResultFromCrud as g, adminWorkflowRunFromCrud as h, AdminWorkflowRunDetails as i, AdminWorkflowSyncResult as l, adminWorkflowRunDetailsFromCrud as m, AdminWorkflowDivergenceDiagnostic as n, AdminWorkflowRunsFilter as o, adminWorkflowFromCrud as p, AdminWorkflowRun as r, AdminWorkflowStep as s, AdminWorkflow as t, AdminWorkflowTrigger as u, isWorkflowRunDetailsJson as v };
+//# sourceMappingURL=workflows-DEb7pIuQ.d.ts.map

package/dist/workflows-DEb7pIuQ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows-DEb7pIuQ.d.ts","names":[],"sources":["../src/lib/hexclave-app/workflows.ts"],"mappings":";;;KAiBY,oBAAA;EACN,IAAA;EAAe,SAAA;AAAA;EACf,IAAA;EAAkB,IAAA;EAAc,QAAA;AAAA;AAAA,KAE1B,aAAA;EACV,EAAA;EACA,WAAA;EACA,aAAA;EACA,QAAA,EAAU,oBAAoB;EAC9B,KAAA;IACE,UAAA;IACA,YAAA;IACA,QAAA;IACA,YAAA;EAAA;EAEF,eAAA;EACA,oBAAA;AAAA;AAAA,KAGU,qBAAA;AAAA,KAEA,iCAAA;EACV,MAAA,EAAQ,gCAAgC;EACxC,gBAAA;EACA,YAAA;EACA,gBAAA;EACA,kBAAA;EACA,OAAA;AAAA;AAAA,KAGU,gBAAA;EACV,EAAA;EACA,UAAA;EACA,MAAA;EACA,KAAA,EAAO,qBAAA;EACP,OAAA;EACA,WAAA;EACA,cAAA;EACA,aAAA;EACA,aAAA;EACA,YAAA;EACA,WAAA;EACA,qBAAA,EAAuB,iCAAiC;EACxD,eAAA;EACA,iBAAA;EACA,gBAAA;AAAA;AAAA,KAGU,iBAAA;EACV,OAAA;EACA,MAAA;EACA,IAAA;EACA,MAAA;EACA,eAAA;EACA,QAAA;EACA,iBAAA;EACA,SAAA;EACA,eAAA;AAAA;AAAA,KAGU,wBAAA;EACV,OAAA;EACA,MAAA,UAvBA;EAyBA,UAAA;EACA,OAAA;EACA,OAAA;EACA,KAAA;IAAS,IAAA;IAAc,OAAA;IAAiB,KAAA;EAAA;EACxC,WAAA;EACA,IAAA;EACA,eAAA;EACA,gBAAA;AAAA;AAAA,KAGU,uBAAA,GAA0B,gBAAA;EACpC,cAAA;EACA,KAAA,EAAO,iBAAA;EACP,YAAA,EAAc,wBAAA;AAAA;AAAA,KAGJ,oBAAA;EACV,UAAA;EACA,OAAA;EACA,UAAA;EACA,MAAA;EACA,iBAAA;EACA,QAAA;EACA,YAAA;EACA,eAAA;AAAA;AAAA,KAGU,uBAAA;EACV,UAAA;EACA,OAAA;EACA,OAAA;EACA,2BAAA;AAAA;AAAA,KAGU,0BAAA;EACV,aAAA;EACA,OAAA;IACE,KAAA;IACA,MAAA;IACA,WAAA;IACA,UAAA,EAAY,iCAAiC;EAAA;AAAA;AAAA,KAIrC,uBAAA;EACV,KAAA,GAAQ,qBAAqB;EAC7B,OAAA;EACA,MAAA;EACA,MAAA;EACA,KAAA,WApCsC;EAsCtC,YAAA;AAAA;AAAA,iBAGc,qBAAA,CAAsB,IAAA,EAAM,mBAAA,GAAsB,aAAa;AAAA,iBA+B/D,wBAAA,CAAyB,IAAA,EAAM,eAAA,GAAkB,gBAAgB;AAAA,iBAoBjE,wBAAA,CAAyB,IAAA,EAAM,eAAA,GAAkB,IAAA,IAAQ,sBAAsB;AAAA,iBAQ/E,+BAAA,CAAgC,IAAA,EAAM,sBAAA,GAAyB,uBAAuB;AAAA,iBA8BtF,4BAAA,CAA6B,IAAA,EAAM,mBAAA,GAAsB,oBAAoB;AAAA,iBAa7E,+BAAA,CAAgC,IAAA,EAAM,sBAAA,GAAyB,uBAAuB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template (FOR package.json FILES, PLEASE EDIT package-template.json)",
   "name": "@hexclave/next",
-  "version": "1.0.70",
+  "version": "1.0.71",
   "repository": "https://github.com/hexclave/hexclave",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -74,9 +74,9 @@
     "tailwindcss-animate": "^1.0.7",
     "rrweb": "^1.1.3",
     "yup": "^1.7.1",
-    "@hexclave/sc": "1.0.70",
-    "@hexclave/shared": "1.0.70",
-    "@hexclave/ui": "1.0.70"
+    "@hexclave/sc": "1.0.71",
+    "@hexclave/shared": "1.0.71",
+    "@hexclave/ui": "1.0.71"
   },
   "peerDependencies": {
     "@types/react": ">=18.0.0",

package/src/lib/hexclave-app/apps/implementations/admin-app-impl.ts

@@ -26,6 +26,7 @@ import { AdminProjectPermission, AdminProjectPermissionDefinition, AdminProjectP
 import type { PlanUsage } from "../../plan-usage";
 import { AdminOwnedProject, AdminProject, AdminProjectUpdateOptions, PushConfigOptions, adminProjectUpdateOptionsToCrud } from "../../projects";
 import type { AdminSessionReplay, AdminSessionReplayChunk, ListSessionReplayChunksOptions, ListSessionReplayChunksResult, ListSessionReplaysOptions, ListSessionReplaysResult, SessionReplayAllEventsResult } from "../../session-replays";
+import { AdminWorkflow, AdminWorkflowRun, AdminWorkflowRunDetails, AdminWorkflowRunsFilter, AdminWorkflowSyncResult, AdminWorkflowUpgradeResult, AdminWorkflowVersion, adminWorkflowFromCrud, adminWorkflowRunDetailsFromCrud, adminWorkflowRunFromCrud, adminWorkflowSyncResultFromCrud, adminWorkflowVersionFromCrud, isWorkflowRunDetailsJson } from "../../workflows";
 import { ManagedEmailProviderListItem, ManagedEmailProviderSetupResult, ManagedEmailProviderStatus, EmailOutboxUpdateOptions, StackAdminApp, StackAdminAppConstructorOptions } from "../interfaces/admin-app";
 import { clientVersion, createCache, getDefaultExtraRequestHeaders, getDefaultProjectId, getDefaultPublishableClientKey, getDefaultSecretServerKey, getDefaultSuperSecretAdminKey, resolveApiUrls, resolveConstructorOptions } from "./common";
 import { _HexclaveServerAppImplIncomplete } from "./server-app-impl";
@@ -99,6 +100,9 @@ export class _HexclaveAdminAppImplIncomplete<HasTokenStore extends boolean, Proj
   private readonly _adminEmailDraftsCache = createCache(async () => {
     return await this._interface.listInternalEmailDrafts();
   });
+  private readonly _adminWorkflowsCache = createCache(async () => {
+    return await this._interface.listWorkflows();
+  });
   private readonly _adminTeamPermissionDefinitionsCache = createCache(async () => {
     return await this._interface.listTeamPermissionDefinitions();
   });
@@ -517,6 +521,10 @@ export class _HexclaveAdminAppImplIncomplete<HasTokenStore extends boolean, Proj
       }));
     }, [crud]);
   }
+  useWorkflows(): AdminWorkflow[] {
+    const crud = useAsyncCache(this._adminWorkflowsCache, [], "adminApp.useWorkflows()");
+    return useMemo(() => crud.map(adminWorkflowFromCrud), [crud]);
+  }
   async listEmailThemes(): Promise<{ id: string, displayName: string }[]> {
     const crud = Result.orThrow(await this._adminEmailThemesCache.getOrWait([], "write-only"));
     return crud.map((theme) => ({
@@ -535,6 +543,121 @@ export class _HexclaveAdminAppImplIncomplete<HasTokenStore extends boolean, Proj
     }));
   }
 
+  // ─── Workflows (internal-project gated; see the Workflows v1 spec) ───────
+
+  async listWorkflows(): Promise<AdminWorkflow[]> {
+    const crud = Result.orThrow(await this._adminWorkflowsCache.getOrWait([], "write-only"));
+    return crud.map(adminWorkflowFromCrud);
+  }
+
+  async createWorkflow(options: { id: string, displayName?: string, source: string }): Promise<AdminWorkflowSyncResult> {
+    const result = await this._interface.createWorkflow({
+      id: options.id,
+      display_name: options.displayName,
+      source: options.source,
+    });
+    await this._adminWorkflowsCache.refresh([]);
+    return adminWorkflowSyncResultFromCrud(result);
+  }
+
+  async updateWorkflowSource(workflowId: string, source: string): Promise<AdminWorkflowSyncResult> {
+    const result = await this._interface.updateWorkflowSource(workflowId, source);
+    await this._adminWorkflowsCache.refresh([]);
+    return adminWorkflowSyncResultFromCrud(result);
+  }
+
+  async deleteWorkflow(workflowId: string): Promise<void> {
+    await this._interface.deleteWorkflow(workflowId);
+    await this._adminWorkflowsCache.refresh([]);
+  }
+
+  async listWorkflowVersions(workflowId: string): Promise<AdminWorkflowVersion[]> {
+    return (await this._interface.listWorkflowVersions(workflowId)).map(adminWorkflowVersionFromCrud);
+  }
+
+  async listWorkflowRuns(workflowId: string, filter: AdminWorkflowRunsFilter & { includeState: true }): Promise<{ runs: AdminWorkflowRunDetails[], nextCursor: string | null }>;
+  async listWorkflowRuns(workflowId: string, filter?: AdminWorkflowRunsFilter): Promise<{ runs: AdminWorkflowRun[], nextCursor: string | null }>;
+  async listWorkflowRuns(workflowId: string, filter: AdminWorkflowRunsFilter = {}): Promise<{ runs: AdminWorkflowRun[], nextCursor: string | null }> {
+    if (filter.includeState === true) {
+      const result = await this._interface.listWorkflowRuns(workflowId, {
+        state: filter.state,
+        version: filter.version,
+        run_key: filter.runKey,
+        cursor: filter.cursor,
+        limit: filter.limit,
+        include_state: true,
+      });
+      return {
+        runs: result.runs.map((run) => adminWorkflowRunDetailsFromCrud(
+          isWorkflowRunDetailsJson(run)
+            ? run
+            : throwErr("Workflow runs response omitted state after include_state=true"),
+        )),
+        nextCursor: result.next_cursor,
+      };
+    }
+    const result = await this._interface.listWorkflowRuns(workflowId, {
+      state: filter.state,
+      version: filter.version,
+      run_key: filter.runKey,
+      cursor: filter.cursor,
+      limit: filter.limit,
+    });
+    return {
+      runs: result.runs.map(adminWorkflowRunFromCrud),
+      nextCursor: result.next_cursor,
+    };
+  }
+
+  async getWorkflowRun(runId: string): Promise<AdminWorkflowRunDetails> {
+    return adminWorkflowRunDetailsFromCrud(await this._interface.getWorkflowRun(runId));
+  }
+
+  async cancelWorkflowRuns(workflowId: string, filter: { runKey?: string, runId?: string, state?: "queued" | "running" | "sleeping", version?: number } = {}): Promise<{ canceledCount: number }> {
+    const result = await this._interface.cancelWorkflowRuns(workflowId, {
+      run_key: filter.runKey,
+      run_id: filter.runId,
+      state: filter.state,
+      version: filter.version,
+    });
+    await this._adminWorkflowsCache.refresh([]);
+    return { canceledCount: result.canceled_count };
+  }
+
+  async upgradeWorkflowRuns(workflowId: string, options: { toVersion: number, runKey?: string, fromVersion?: number }): Promise<AdminWorkflowUpgradeResult> {
+    const result = await this._interface.upgradeWorkflowRuns(workflowId, {
+      to_version: options.toVersion,
+      run_key: options.runKey,
+      from_version: options.fromVersion,
+    });
+    return {
+      upgradedCount: result.upgraded_count,
+      skipped: result.skipped.map((skip) => ({
+        runId: skip.run_id,
+        runKey: skip.run_key,
+        fromVersion: skip.from_version,
+        diagnostic: {
+          reason: skip.diagnostic.reason,
+          suspendedStepKey: skip.diagnostic.suspended_step_key,
+          foundStepKey: skip.diagnostic.found_step_key,
+          consumedStepKeys: skip.diagnostic.consumed_step_keys,
+          unconsumedStepKeys: skip.diagnostic.unconsumed_step_keys,
+          details: skip.diagnostic.details,
+        },
+      })),
+    };
+  }
+
+  async retryWorkflowRun(runId: string): Promise<void> {
+    await this._interface.retryWorkflowRun(runId);
+    await this._adminWorkflowsCache.refresh([]);
+  }
+
+  async sendWorkflowEvent(name: string, data?: unknown): Promise<{ eventId: string }> {
+    const result = await this._interface.sendWorkflowEvent(name, data ?? null);
+    return { eventId: result.event_id };
+  }
+
   async listEmailDrafts(): Promise<{ id: string, displayName: string, themeId: string | undefined | false, tsxSource: string, sentAt: Date | null }[]> {
     const crud = Result.orThrow(await this._adminEmailDraftsCache.getOrWait([], "write-only"));
     return crud.map((draft) => ({

package/src/lib/hexclave-app/apps/interfaces/admin-app.ts

@@ -14,6 +14,7 @@ import { InternalApiKey, InternalApiKeyCreateOptions, InternalApiKeyFirstView }
 import { AdminProjectPermission, AdminProjectPermissionDefinition, AdminProjectPermissionDefinitionCreateOptions, AdminProjectPermissionDefinitionUpdateOptions, AdminTeamPermission, AdminTeamPermissionDefinition, AdminTeamPermissionDefinitionCreateOptions, AdminTeamPermissionDefinitionUpdateOptions } from "../../permissions";
 import type { PlanUsage } from "../../plan-usage";
 import { AdminProject } from "../../projects";
+import type { AdminWorkflow, AdminWorkflowRun, AdminWorkflowRunDetails, AdminWorkflowRunsFilter, AdminWorkflowSyncResult, AdminWorkflowUpgradeResult, AdminWorkflowVersion } from "../../workflows";
 import { _HexclaveAdminAppImpl } from "../implementations";
 import { StackServerApp, StackServerAppConstructorOptions } from "./server-app";
 
@@ -60,6 +61,7 @@ export type ManagedEmailProviderListItem = {
 
 import type { AdminSessionReplay, ListSessionReplayChunksOptions, ListSessionReplayChunksResult, ListSessionReplaysOptions, ListSessionReplaysResult, SessionReplayAllEventsResult } from "../../session-replays";
 export type { AdminSessionReplay, AdminSessionReplayChunk, ListSessionReplaysOptions, ListSessionReplaysResult, ListSessionReplayChunksOptions, ListSessionReplayChunksResult, SessionReplayAllEventsResult } from "../../session-replays";
+export type { AdminWorkflow, AdminWorkflowDivergenceDiagnostic, AdminWorkflowRun, AdminWorkflowRunDetails, AdminWorkflowRunsFilter, AdminWorkflowRunState, AdminWorkflowStep, AdminWorkflowStepAttempt, AdminWorkflowSyncResult, AdminWorkflowTrigger, AdminWorkflowUpgradeResult, AdminWorkflowVersion } from "../../workflows";
 
 
 /** @deprecated Use `HexclaveAdminAppConstructorOptions` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */
@@ -84,6 +86,7 @@ export type StackAdminApp<HasTokenStore extends boolean = boolean, ProjectId ext
   & AsyncStoreProperty<"emailPreviewWithEditableMarkers", [{ themeId?: string | null | false, themeTsxSource?: string, templateId?: string, templateTsxSource?: string, editableSource?: 'template' | 'theme' | 'both' }], { html: string, editableRegions?: Record<string, unknown> }, false> // THIS_LINE_PLATFORM react-like
   & AsyncStoreProperty<"emailTemplates", [], { id: string, displayName: string, themeId?: string, tsxSource: string }[], true>
   & AsyncStoreProperty<"emailDrafts", [], { id: string, displayName: string, themeId: string | undefined | false, tsxSource: string, sentAt: Date | null }[], true>
+  & AsyncStoreProperty<"workflows", [], AdminWorkflow[], true>
   & AsyncStoreProperty<"stripeAccountInfo", [], { account_id: string, charges_enabled: boolean, details_submitted: boolean, payouts_enabled: boolean } | null, false>
   & AsyncStoreProperty<
     "transactions",
@@ -141,6 +144,22 @@ export type StackAdminApp<HasTokenStore extends boolean = boolean, ProjectId ext
     createEmailTemplate(displayName: string): Promise<{ id: string }>,
     deleteEmailTemplate(id: string): Promise<void>,
 
+    // Workflows (internal-project gated; see the Workflows v1 spec). The
+    // management verbs live on the admin app only in v1.
+    createWorkflow(options: { id: string, displayName?: string, source: string }): Promise<AdminWorkflowSyncResult>,
+    updateWorkflowSource(workflowId: string, source: string): Promise<AdminWorkflowSyncResult>,
+    deleteWorkflow(workflowId: string): Promise<void>,
+    listWorkflowVersions(workflowId: string): Promise<AdminWorkflowVersion[]>,
+    listWorkflowRuns: {
+      (workflowId: string, filter: AdminWorkflowRunsFilter & { includeState: true }): Promise<{ runs: AdminWorkflowRunDetails[], nextCursor: string | null }>,
+      (workflowId: string, filter?: AdminWorkflowRunsFilter): Promise<{ runs: AdminWorkflowRun[], nextCursor: string | null }>,
+    },
+    getWorkflowRun(runId: string): Promise<AdminWorkflowRunDetails>,
+    cancelWorkflowRuns(workflowId: string, filter?: { runKey?: string, runId?: string, state?: "queued" | "running" | "sleeping", version?: number }): Promise<{ canceledCount: number }>,
+    upgradeWorkflowRuns(workflowId: string, options: { toVersion: number, runKey?: string, fromVersion?: number }): Promise<AdminWorkflowUpgradeResult>,
+    retryWorkflowRun(runId: string): Promise<void>,
+    sendWorkflowEvent(name: string, data?: unknown): Promise<{ eventId: string }>,
+
     setupPayments(): Promise<{ url: string }>,
     createStripeWidgetAccountSession(): Promise<{ client_secret: string }>,
     getPaymentMethodConfigs(): Promise<{ configId: string, methods: Array<{ id: string, name: string, enabled: boolean, available: boolean, overridable: boolean }> } | null>,

package/src/lib/hexclave-app/index.ts

@@ -45,6 +45,21 @@ export type {
   EmailOutboxUpdateOptions
 } from "./apps/interfaces/admin-app";
 
+export type {
+  AdminWorkflow,
+  AdminWorkflowDivergenceDiagnostic,
+  AdminWorkflowRun,
+  AdminWorkflowRunDetails,
+  AdminWorkflowRunsFilter,
+  AdminWorkflowRunState,
+  AdminWorkflowStep,
+  AdminWorkflowStepAttempt,
+  AdminWorkflowSyncResult,
+  AdminWorkflowTrigger,
+  AdminWorkflowUpgradeResult,
+  AdminWorkflowVersion
+} from "./workflows";
+
 export type {
   ProjectConfig
 } from "./project-configs";

package/src/lib/hexclave-app/workflows.test.ts

@@ -0,0 +1,28 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import type { WorkflowVersionJson } from "@hexclave/shared/dist/interface/workflows";
+import { describe, expect, it } from "vitest";
+import { adminWorkflowVersionFromCrud } from "./workflows";
+
+describe("adminWorkflowVersionFromCrud", () => {
+  it("preserves the deployment source hash", () => {
+    const version: WorkflowVersionJson = {
+      workflow_id: "daily-report",
+      version: 3,
+      source: "export default 1",
+      source_hash: "0123456789abcdef",
+      runtime_env_version: "v1",
+      is_latest: true,
+      in_flight_runs: 2,
+      created_at_millis: 1234,
+    };
+
+    expect(adminWorkflowVersionFromCrud(version)).toMatchObject({
+      workflowId: "daily-report",
+      version: 3,
+      sourceHash: "0123456789abcdef",
+    });
+  });
+});

package/src/lib/hexclave-app/workflows.ts

@@ -0,0 +1,245 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import type {
+  WorkflowDivergenceDiagnosticJson,
+  WorkflowRunDetailsJson,
+  WorkflowRunJson,
+  WorkflowSummaryJson,
+  WorkflowSyncResultJson,
+  WorkflowVersionJson,
+} from "@hexclave/shared/dist/interface/workflows";
+
+// SDK-side (camelCase) types + converters for the workflows admin surface.
+// The wire types live in @hexclave/shared/dist/interface/workflows; these
+// mirror them 1:1 so the dashboard never touches snake_case.
+
+export type AdminWorkflowTrigger =
+  | { type: "event", eventType: string }
+  | { type: "schedule", cron: string, timezone: string };
+
+export type AdminWorkflow = {
+  id: string,
+  displayName: string,
+  latestVersion: number,
+  triggers: AdminWorkflowTrigger[],
+  stats: {
+    activeRuns: number,
+    sleepingRuns: number,
+    failed7d: number,
+    runVolume14d: number[],
+  },
+  createdAtMillis: number,
+  lastDeployedAtMillis: number,
+};
+
+export type AdminWorkflowRunState = "queued" | "running" | "sleeping" | "completed" | "failed" | "canceled";
+
+export type AdminWorkflowDivergenceDiagnostic = {
+  reason: WorkflowDivergenceDiagnosticJson["reason"],
+  suspendedStepKey: string | null,
+  foundStepKey: string | null,
+  consumedStepKeys: string[],
+  unconsumedStepKeys: string[],
+  details: string,
+};
+
+export type AdminWorkflowRun = {
+  id: string,
+  workflowId: string,
+  runKey: string | null,
+  state: AdminWorkflowRunState,
+  version: number,
+  triggerType: string,
+  triggerSummary: string,
+  currentStepId: string | null,
+  stepsRecorded: number,
+  errorSummary: string | null,
+  failureKind: "user" | "platform" | null,
+  lastUpgradeDivergence: AdminWorkflowDivergenceDiagnostic | null,
+  createdAtMillis: number,
+  completedAtMillis: number | null,
+  nextWakeAtMillis: number | null,
+};
+
+export type AdminWorkflowStep = {
+  stepKey: string,
+  stepId: string,
+  kind: "run" | "sleep",
+  result: unknown,
+  resultSizeBytes: number,
+  attempts: number,
+  executedAtVersion: number,
+  elapsedMs: number | null,
+  createdAtMillis: number,
+};
+
+export type AdminWorkflowStepAttempt = {
+  stepKey: string,
+  stepId: string,
+  /** 0 for the original execution; incremented by each manual retry of the run. */
+  retryEpoch: number,
+  attempt: number,
+  outcome: "succeeded" | "failed",
+  error: { name: string, message: string, stack?: string } | null,
+  failureKind: "user" | "platform" | null,
+  logs: string | null,
+  startedAtMillis: number,
+  finishedAtMillis: number,
+};
+
+export type AdminWorkflowRunDetails = AdminWorkflowRun & {
+  triggerPayload: unknown,
+  steps: AdminWorkflowStep[],
+  stepAttempts: AdminWorkflowStepAttempt[],
+};
+
+export type AdminWorkflowVersion = {
+  workflowId: string,
+  version: number,
+  sourceHash: string,
+  source: string,
+  runtimeEnvVersion: string,
+  isLatest: boolean,
+  inFlightRuns: number,
+  createdAtMillis: number,
+};
+
+export type AdminWorkflowSyncResult = {
+  workflowId: string,
+  version: number,
+  created: boolean,
+  inFlightRunsOnOlderVersions: number,
+};
+
+export type AdminWorkflowUpgradeResult = {
+  upgradedCount: number,
+  skipped: {
+    runId: string,
+    runKey: string | null,
+    fromVersion: number,
+    diagnostic: AdminWorkflowDivergenceDiagnostic,
+  }[],
+};
+
+export type AdminWorkflowRunsFilter = {
+  state?: AdminWorkflowRunState,
+  version?: number,
+  runKey?: string,
+  cursor?: string,
+  limit?: number,
+  /** Include each run's memoized steps and attempt history. */
+  includeState?: boolean,
+};
+
+export function adminWorkflowFromCrud(crud: WorkflowSummaryJson): AdminWorkflow {
+  return {
+    id: crud.id,
+    displayName: crud.display_name,
+    latestVersion: crud.latest_version,
+    triggers: crud.triggers.map((trigger) => trigger.type === "event"
+      ? { type: "event", eventType: trigger.event_type }
+      : { type: "schedule", cron: trigger.cron, timezone: trigger.timezone }),
+    stats: {
+      activeRuns: crud.stats.active_runs,
+      sleepingRuns: crud.stats.sleeping_runs,
+      failed7d: crud.stats.failed_7d,
+      runVolume14d: crud.stats.run_volume_14d,
+    },
+    createdAtMillis: crud.created_at_millis,
+    lastDeployedAtMillis: crud.last_deployed_at_millis,
+  };
+}
+
+function adminDivergenceFromCrud(crud: WorkflowDivergenceDiagnosticJson | null): AdminWorkflowDivergenceDiagnostic | null {
+  if (crud == null) return null;
+  return {
+    reason: crud.reason,
+    suspendedStepKey: crud.suspended_step_key,
+    foundStepKey: crud.found_step_key,
+    consumedStepKeys: crud.consumed_step_keys,
+    unconsumedStepKeys: crud.unconsumed_step_keys,
+    details: crud.details,
+  };
+}
+
+export function adminWorkflowRunFromCrud(crud: WorkflowRunJson): AdminWorkflowRun {
+  return {
+    id: crud.id,
+    workflowId: crud.workflow_id,
+    runKey: crud.run_key,
+    state: crud.state,
+    version: crud.version,
+    triggerType: crud.trigger_type,
+    triggerSummary: crud.trigger_summary,
+    currentStepId: crud.current_step_id,
+    stepsRecorded: crud.steps_recorded,
+    errorSummary: crud.error_summary,
+    failureKind: crud.failure_kind,
+    lastUpgradeDivergence: adminDivergenceFromCrud(crud.last_upgrade_divergence),
+    createdAtMillis: crud.created_at_millis,
+    completedAtMillis: crud.completed_at_millis,
+    nextWakeAtMillis: crud.next_wake_at_millis,
+  };
+}
+
+export function isWorkflowRunDetailsJson(crud: WorkflowRunJson): crud is WorkflowRunDetailsJson {
+  return "trigger_payload" in crud
+    && "steps" in crud
+    && Array.isArray(crud.steps)
+    && "step_attempts" in crud
+    && Array.isArray(crud.step_attempts);
+}
+
+export function adminWorkflowRunDetailsFromCrud(crud: WorkflowRunDetailsJson): AdminWorkflowRunDetails {
+  return {
+    ...adminWorkflowRunFromCrud(crud),
+    triggerPayload: crud.trigger_payload,
+    steps: crud.steps.map((step) => ({
+      stepKey: step.step_key,
+      stepId: step.step_id,
+      kind: step.kind,
+      result: step.result,
+      resultSizeBytes: step.result_size_bytes,
+      attempts: step.attempts,
+      executedAtVersion: step.executed_at_version,
+      elapsedMs: step.elapsed_ms,
+      createdAtMillis: step.created_at_millis,
+    })),
+    stepAttempts: crud.step_attempts.map((attempt) => ({
+      stepKey: attempt.step_key,
+      stepId: attempt.step_id,
+      retryEpoch: attempt.retry_epoch,
+      attempt: attempt.attempt,
+      outcome: attempt.outcome,
+      error: attempt.error,
+      failureKind: attempt.failure_kind,
+      logs: attempt.logs,
+      startedAtMillis: attempt.started_at_millis,
+      finishedAtMillis: attempt.finished_at_millis,
+    })),
+  };
+}
+
+export function adminWorkflowVersionFromCrud(crud: WorkflowVersionJson): AdminWorkflowVersion {
+  return {
+    workflowId: crud.workflow_id,
+    version: crud.version,
+    sourceHash: crud.source_hash,
+    source: crud.source,
+    runtimeEnvVersion: crud.runtime_env_version,
+    isLatest: crud.is_latest,
+    inFlightRuns: crud.in_flight_runs,
+    createdAtMillis: crud.created_at_millis,
+  };
+}
+
+export function adminWorkflowSyncResultFromCrud(crud: WorkflowSyncResultJson): AdminWorkflowSyncResult {
+  return {
+    workflowId: crud.workflow_id,
+    version: crud.version,
+    created: crud.created,
+    inFlightRunsOnOlderVersions: crud.in_flight_runs_on_older_versions,
+  };
+}