@lovable.dev/workflows-sdk 0.0.0-dev.52 → 0.0.0-dev.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -65,6 +65,7 @@ Every durable operation needs a static, user-facing description:
65
65
  | --- | --- |
66
66
  | `ctx.step` | Third argument: `meta.description` |
67
67
  | `ctx.llm` | Second argument: `meta.description` |
68
+ | `ctx.connector` | Third argument: `meta.description` |
68
69
  | `ctx.sleep`, `ctx.sleepUntil` | Second argument: `meta.description` |
69
70
  | `ctx.waitForEvent` | Second argument: `meta.description` |
70
71
  | `ctx.now`, `ctx.uuid` | First argument: `meta.description` |
@@ -75,7 +76,11 @@ and returns assistant text. Pass a provider-prefixed `model` and either `prompt`
75
76
  or nonempty text-only user/assistant `messages`. Optional `system` supplies system
76
77
  instructions; `maxTokens` defaults to 4096. Use a unique `options.id` and a literal
77
78
  `options.meta.description`, with item-based template IDs for repeated calls.
78
- Compatible OpenAI and Gemini Chat Completions text models are supported.
79
+ Compatible OpenAI and Gemini Chat Completions models and Claude Messages models
80
+ are supported for text generation. Claude uses the separate `system` field and
81
+ returns joined text blocks; thinking blocks are excluded. Its token budget includes
82
+ thinking. Token-limit or context-window truncation fails the step with a truncation
83
+ error. Refusals, tool requests, paused turns, and responses without text also fail.
79
84
  Streaming, tools, images, and structured output are outside this API.
80
85
 
81
86
  The Gateway SDK reads the app's server-side `LOVABLE_API_KEY`; the generated
@@ -94,15 +99,16 @@ bun -e 'import { listModels } from "@lovable.dev/ai-gateway"; console.log(JSON.s
94
99
 
95
100
  Require `workspace_models: "included"`; missing markers, public catalogs, and
96
101
  invalid credentials do not establish project access. Choose an exact eligible
97
- OpenAI or Gemini model ID whose `supported_surfaces` includes `chat-completions`
98
- and `modalities.output` includes `text`. Use the project's resolved default when
99
- compatible, then run `bunx ai-gateway generate --model <model-id>` and inspect its
100
- Chat Completions contract for text support. Discovery happens while authoring,
101
- not on every workflow run.
102
+ model ID whose `modalities.output` includes `text`. Its `supported_surfaces` must
103
+ include `chat-completions` for `openai/...` and `google/gemini-...`, or `messages`
104
+ for `anthropic/claude-...`. Use the project's resolved default when compatible,
105
+ then run `bunx ai-gateway generate --model <model-id>` and inspect the matching
106
+ surface's text contract. Discovery happens while authoring, not on every workflow run.
102
107
 
103
108
  Run LLM workflows through the generated `/steps` route. The standalone
104
109
  `createTanStackWorkflowHandler` uses TanStack's runtime and does not support LLM steps.
105
110
  Real app-side calls require SDK `0.0.0-dev.49` or newer.
111
+ Claude support requires SDK `0.0.0-dev.54` or newer.
106
112
 
107
113
  Both `ctx.approve` and `ctx.waitForEvent` require `timeoutMs`: a duration in
108
114
  milliseconds, written as a finite numeric literal of at least 60000 (one minute) (for example,
@@ -129,6 +135,63 @@ Keep durable control flow in the workflow handler. Do not pass, alias,
129
135
  destructure, or return `ctx`, and do not detach methods such as `ctx.step`.
130
136
  Pass extracted data such as `ctx.input.customerId` to helpers instead.
131
137
 
138
+ ### Connector callbacks
139
+
140
+ SDK `0.0.0-dev.52` is the first version that executes
141
+ `ctx.connector(stepId, callback, options)` through the generated `/steps` route.
142
+ Use it for gateway-backed App connectors: a connection linked to the app,
143
+ shared across workflow runs. App User Connectors, which act for individual app
144
+ users, are outside this authoring flow.
145
+
146
+ ```ts
147
+ const messages = await ctx.connector("read-messages", ({ signal }) => readMessages(signal), {
148
+ connectorId: "slack", connectionId: "std_REPLACE_WITH_LINKED_CONNECTION_ID",
149
+ meta: { description: "Read recent channel messages" },
150
+ });
151
+ ```
152
+
153
+ Keep `connectorId` and `connectionId` as nonempty string literals in the inline
154
+ options object. They identify the declared step in the manifest and run history;
155
+ credentials enforce access. They cannot vary by workflow input or loop item.
156
+ Use a new workflow version when changing the connection; replay rejects saved
157
+ results or failures whose connector identity differs.
158
+
159
+ The callback receives the normal step context, including `signal`. It owns
160
+ server-side credential access, URL, method, headers, encoding, `fetch`, and
161
+ provider errors. Check both HTTP success and the provider's success fields
162
+ before returning. Forward `signal` to I/O. Return compact JSON-serializable
163
+ data, including plain strings; there is no response envelope. A callback that
164
+ returns `undefined` records and returns `null`. Return parsed data or text,
165
+ never a `Response` or credentials.
166
+
167
+ Select and link an App connection with Lovable's existing connector tools.
168
+ `standard_connectors--get_connection_secrets` takes the connection's `std_...`
169
+ ID and returns exact secret names and generated-app routing, never secret
170
+ values. Follow that routing and run its read-only App credential check before
171
+ using the workflow. Secret names depend on the connection; do not derive them
172
+ from `connectorId`. Keep gateway credentials separate from
173
+ `LOVABLE_WORKFLOWS_KEY`, which authenticates the workflow endpoint.
174
+
175
+ Connector retries inherit `defaultStepRetry`. An inline `retry` replaces that
176
+ default and requires `maxAttempts`; use literal `backoff: "fixed"` or
177
+ `"exponential"` and optional `baseMs`. The engine records custom-policy flags
178
+ but does not invoke `shouldRetry` or backoff callbacks; custom backoff uses
179
+ exponential delays. `timeout` is a positive number of
180
+ milliseconds per attempt. Let the workflow engine retry: disable additional
181
+ client retries and avoid retry loops inside the callback. An external write
182
+ can repeat if its result is lost before persistence; use a provider idempotency
183
+ key derived from stable run input when the provider supports one.
184
+
185
+ Discovery, unselected branches, and completed-step replay never invoke the
186
+ callback. Saved final failures throw into the handler's `try/catch`. The
187
+ standalone `createTanStackWorkflowHandler` does not support connector callbacks.
188
+ See the [Slack digest example](examples/src/lib/workflows/slack-digest/index.ts)
189
+ for a connector read followed by an LLM summary and a saved code-step result.
190
+ The example uses hosted-app gateway authentication. Replace its marked
191
+ connection ID and secret name with the tool output, adapt routing/authentication
192
+ to that output, and select a model through the discovery procedure above before
193
+ running it.
194
+
132
195
  ### Repeated steps
133
196
 
134
197
  A step inside a loop or callback needs `meta.group` with a stable ID and
@@ -142,7 +205,9 @@ ctx.step(`process-${item.id}`, () => processItem(item), {
142
205
 
143
206
  For dynamic sequential work, await one step directly as the only statement in
144
207
  a `for...of` loop. For dynamic parallel work, use a mapped `Promise.all()`.
145
- Both forms support `ctx.step` and `ctx.llm`; see [order summaries](examples/src/lib/workflows/order-summaries/index.ts).
208
+ Both forms support `ctx.step`, `ctx.llm`, and `ctx.connector`; see [order summaries](examples/src/lib/workflows/order-summaries/index.ts).
209
+ Repeated connector steps keep the same literal connector and connection IDs
210
+ while each item gets a unique step ID.
146
211
  Use a different group ID for each repeated callsite, and derive item IDs from
147
212
  workflow input or saved step results so replay reaches the same operations.
148
213
  Fixed `Promise.all([stepA, stepB])` branches and ordinary sequential steps do
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-C1rydF9J.js";
2
2
  //#region src/manifests/branch-metadata.ts
3
3
  const optionsArgument = {
4
4
  step: 2,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-C1rydF9J.js";
2
2
  //#region src/manifests/context-escapes.ts
3
3
  const durableMethods = /* @__PURE__ */ new Set([
4
4
  "step",
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-C1rydF9J.js";
2
2
  //#region src/manifests/duplicate-ids.ts
3
3
  /** Where an explicit `{ id }` would sit for each operation. */
4
4
  const optionsArgument = {
@@ -6626,7 +6626,7 @@ function listValueFromJson(listValue, json) {
6626
6626
  }
6627
6627
  //#endregion
6628
6628
  //#region package.json
6629
- var version = "0.0.0-dev.52";
6629
+ var version = "0.0.0-dev.54";
6630
6630
  //#endregion
6631
6631
  //#region src/proto/lovable/appworkflows/v1/workflow_manifest_pb.ts
6632
6632
  /**
@@ -6839,15 +6839,15 @@ function serializeSchema(schema, direction, label) {
6839
6839
  }
6840
6840
  }
6841
6841
  async function generateManifests(definition, options = {}) {
6842
- const { extractWorkflowGraph } = await import("./graph-RIBcr2Xd.js");
6843
- const { findBranchMetadataIssues } = await import("./branch-metadata-DIu0sMPS.js");
6844
- const { findWorkflowContextEscapes } = await import("./context-escapes-CMZlpkct.js");
6845
- const { findDuplicateOperationIds } = await import("./duplicate-ids-DiBCVnwz.js");
6842
+ const { extractWorkflowGraph } = await import("./graph-C1rydF9J.js");
6843
+ const { findBranchMetadataIssues } = await import("./branch-metadata-C7zbyVoJ.js");
6844
+ const { findWorkflowContextEscapes } = await import("./context-escapes-CKZic0A-.js");
6845
+ const { findDuplicateOperationIds } = await import("./duplicate-ids-BwttKNnU.js");
6846
6846
  const { DURABLE_ID_REQUIRED } = await import("./durable-ids-Cx341nJQ.js").then((n) => n.n);
6847
- const { findNestedDurableOperations } = await import("./nested-operations-xQdnHHR7.js");
6848
- const { findOperationDescriptionIssues } = await import("./operation-descriptions-BGSwAA0h.js");
6849
- const { findStepMetadataIssues } = await import("./step-metadata-CzUMB8XT.js");
6850
- const { findWaitDeadlineIssues } = await import("./wait-deadlines-Dg0U2ZK5.js");
6847
+ const { findNestedDurableOperations } = await import("./nested-operations-DRadcW5J.js");
6848
+ const { findOperationDescriptionIssues } = await import("./operation-descriptions-YSRFtN5C.js");
6849
+ const { findStepMetadataIssues } = await import("./step-metadata-BMUvomJ7.js");
6850
+ const { findWaitDeadlineIssues } = await import("./wait-deadlines-DetLq7Zp.js");
6851
6851
  const { WAIT_DEADLINE_REQUIRED } = await import("./wait-deadlines-DpK-Fgnd.js");
6852
6852
  const collection = registerWorkflows(definition);
6853
6853
  const manifests = [];
@@ -1,4 +1,4 @@
1
- import { C as WorkflowManifestWaitForEventNodeV1Schema, S as WorkflowManifestUuidNodeV1Schema, _ as WorkflowManifestSleepNodeV1Schema, a as WorkflowManifestConnectorNodeV1Schema, b as WorkflowManifestStepNodeV1Schema, c as WorkflowManifestGraphV1Schema, d as WorkflowManifestNowNodeV1Schema, f as WorkflowManifestOrderEdgeV1Schema, g as WorkflowManifestRepeatedStepV1Schema, h as WorkflowManifestRepeatedLlmV1Schema, i as WorkflowManifestBranchNodeV1Schema, l as WorkflowManifestLlmNodeV1Schema, m as WorkflowManifestRepeatedConnectorV1Schema, n as WorkflowManifestApproveNodeV1Schema, o as WorkflowManifestGraphEdgeV1Schema, p as WorkflowManifestParallelNodeV1Schema, r as WorkflowManifestBranchEdgeV1Schema, s as WorkflowManifestGraphNodeV1Schema, u as WorkflowManifestLoopNodeV1Schema, v as WorkflowManifestSleepUntilNodeV1Schema, w as create, x as WorkflowManifestUnknownNodeV1Schema, y as WorkflowManifestStepExecutionPolicyV1Schema } from "./generate-C9MJlJBn.js";
1
+ import { C as WorkflowManifestWaitForEventNodeV1Schema, S as WorkflowManifestUuidNodeV1Schema, _ as WorkflowManifestSleepNodeV1Schema, a as WorkflowManifestConnectorNodeV1Schema, b as WorkflowManifestStepNodeV1Schema, c as WorkflowManifestGraphV1Schema, d as WorkflowManifestNowNodeV1Schema, f as WorkflowManifestOrderEdgeV1Schema, g as WorkflowManifestRepeatedStepV1Schema, h as WorkflowManifestRepeatedLlmV1Schema, i as WorkflowManifestBranchNodeV1Schema, l as WorkflowManifestLlmNodeV1Schema, m as WorkflowManifestRepeatedConnectorV1Schema, n as WorkflowManifestApproveNodeV1Schema, o as WorkflowManifestGraphEdgeV1Schema, p as WorkflowManifestParallelNodeV1Schema, r as WorkflowManifestBranchEdgeV1Schema, s as WorkflowManifestGraphNodeV1Schema, u as WorkflowManifestLoopNodeV1Schema, v as WorkflowManifestSleepUntilNodeV1Schema, w as create, x as WorkflowManifestUnknownNodeV1Schema, y as WorkflowManifestStepExecutionPolicyV1Schema } from "./generate--cMBfJhd.js";
2
2
  import { n as assertLlmOptions, t as assertLlmModel } from "./llm-validation-DdDO6csU.js";
3
3
  //#region src/manifests/handler-source.ts
4
4
  const nativeFunctionSource = /\{\s*\[native code\]\s*\}\s*$/;
package/dist/index.js CHANGED
@@ -1,8 +1,8 @@
1
1
  import { t as DURABLE_ID_REQUIRED } from "./durable-ids-Cx341nJQ.js";
2
- import { A as daily, D as registerWorkflows, E as createWorkflow, M as weekly, O as workflowVersions, T as createMiddleware, j as hourly, k as defineSchedule, t as generateManifests } from "./generate-C9MJlJBn.js";
2
+ import { A as daily, D as registerWorkflows, E as createWorkflow, M as weekly, O as workflowVersions, T as createMiddleware, j as hourly, k as defineSchedule, t as generateManifests } from "./generate--cMBfJhd.js";
3
3
  import { n as assertLlmOptions, r as assertLlmRequest } from "./llm-validation-DdDO6csU.js";
4
4
  import { WorkflowRequestParseError, inMemoryRunStore, parseWorkflowRequest, runWorkflow } from "@tanstack/workflow-core";
5
- import { generateChatCompletion } from "@lovable.dev/ai-gateway";
5
+ import { generateChatCompletion, generateMessage } from "@lovable.dev/ai-gateway";
6
6
  //#region src/stacks/tanstack/sse.ts
7
7
  const HEADERS = {
8
8
  "content-type": "text/event-stream; charset=utf-8",
@@ -203,6 +203,7 @@ function assertConnectorOptions(options) {
203
203
  //#endregion
204
204
  //#region src/runtime/llm.ts
205
205
  const completeChat = generateChatCompletion;
206
+ const completeMessage = generateMessage;
206
207
  function chatRequest(request) {
207
208
  const messages = request.prompt !== void 0 ? [{
208
209
  role: "user",
@@ -224,10 +225,34 @@ function chatRequest(request) {
224
225
  max_tokens: maxTokens,
225
226
  modalities: ["text"]
226
227
  };
227
- throw new Error("ctx.llm requires an OpenAI or Gemini model with Chat Completions text support");
228
+ throw new Error("ctx.llm requires an OpenAI or Gemini Chat Completions model, or a Claude Messages model");
229
+ }
230
+ function claudeText(response) {
231
+ if (response === null || typeof response !== "object" || !("content" in response) || !Array.isArray(response.content) || "stop_reason" in response && (response.stop_reason === "refusal" || response.stop_reason === "tool_use" || response.stop_reason === "pause_turn")) throw new Error("AI Gateway returned no assistant text");
232
+ if ("stop_reason" in response && (response.stop_reason === "max_tokens" || response.stop_reason === "model_context_window_exceeded")) throw new Error(`AI Gateway returned truncated Claude text (${response.stop_reason})`);
233
+ const text = response.content.map((block) => {
234
+ if (block === null || typeof block !== "object" || !("type" in block)) throw new Error("AI Gateway returned no assistant text");
235
+ if (block.type !== "text") return "";
236
+ if (!("text" in block) || typeof block.text !== "string") throw new Error("AI Gateway returned no assistant text");
237
+ return block.text;
238
+ }).join("");
239
+ if (text.trim() === "") throw new Error("AI Gateway returned no assistant text");
240
+ return text;
228
241
  }
229
242
  async function generateLlmText(request, options) {
230
243
  assertLlmRequest(request);
244
+ if (request.model.startsWith("anthropic/claude-")) return claudeText(await completeMessage({
245
+ model: request.model,
246
+ messages: request.prompt !== void 0 ? [{
247
+ role: "user",
248
+ content: request.prompt
249
+ }] : request.messages,
250
+ ...request.system === void 0 ? {} : { system: request.system },
251
+ max_tokens: request.maxTokens ?? 4096
252
+ }, {
253
+ ...options,
254
+ maxRetries: 0
255
+ }));
231
256
  const message = (await completeChat(chatRequest(request), {
232
257
  ...options,
233
258
  maxRetries: 0
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-C1rydF9J.js";
2
2
  //#region src/manifests/nested-operations.ts
3
3
  const durableMethods = [
4
4
  "step",
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-C1rydF9J.js";
2
2
  //#region src/manifests/operation-descriptions.ts
3
3
  const optionsArgument = {
4
4
  approve: 0,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-C1rydF9J.js";
2
2
  //#region src/manifests/step-metadata.ts
3
3
  async function findStepMetadataIssues(handler) {
4
4
  const api = await loadTypeScript();
package/dist/vite.js CHANGED
@@ -1,4 +1,4 @@
1
- import { t as generateManifests } from "./generate-C9MJlJBn.js";
1
+ import { t as generateManifests } from "./generate--cMBfJhd.js";
2
2
  import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
3
3
  import { createServer } from "vite";
4
4
  import { lstat, mkdir, mkdtemp, readdir, rename, rm, writeFile } from "node:fs/promises";
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-C1rydF9J.js";
2
2
  //#region src/manifests/wait-deadlines.ts
3
3
  const optionsArgument = {
4
4
  approve: 0,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lovable.dev/workflows-sdk",
3
- "version": "0.0.0-dev.52",
3
+ "version": "0.0.0-dev.54",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "tag": "dev",
@@ -31,7 +31,7 @@
31
31
  "dependencies": {
32
32
  "@standard-schema/spec": "^1.1.0",
33
33
  "@tanstack/workflow-core": "0.0.4",
34
- "@lovable.dev/ai-gateway": "0.1.9"
34
+ "@lovable.dev/ai-gateway": "0.1.11"
35
35
  },
36
36
  "devDependencies": {
37
37
  "@bufbuild/protobuf": "^2.10.1",