@ai-sdk/workflow-harness 0.0.0-07500555-20260730161446

package/CHANGELOG.md

@@ -0,0 +1,306 @@
+# @ai-sdk/workflow-harness
+
+## 0.0.0-07500555-20260730161446
+
+### Patch Changes
+
+- Updated dependencies [5f65e61]
+  - @ai-sdk/harness@0.0.0-07500555-20260730161446
+
+## 1.0.39
+
+### Patch Changes
+
+- Updated dependencies [86a84c9]
+  - @ai-sdk/harness@1.0.39
+
+## 1.0.38
+
+### Patch Changes
+
+- f5cdb2d: chore(harness): update primary SDK dependencies
+  - @ai-sdk/harness@1.0.38
+
+## 1.0.37
+
+### Patch Changes
+
+- Updated dependencies [b460541]
+- Updated dependencies [079591e]
+  - @ai-sdk/harness@1.0.37
+
+## 1.0.36
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.36
+
+## 1.0.35
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.35
+
+## 1.0.34
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.34
+
+## 1.0.33
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.33
+
+## 1.0.32
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.32
+
+## 1.0.31
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.31
+
+## 1.0.30
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.30
+
+## 1.0.29
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.29
+
+## 1.0.28
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.28
+
+## 1.0.27
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.27
+
+## 1.0.26
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.26
+
+## 1.0.25
+
+### Patch Changes
+
+- Updated dependencies [44e988a]
+  - @ai-sdk/harness@1.0.25
+
+## 1.0.24
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.24
+
+## 1.0.23
+
+### Patch Changes
+
+- Updated dependencies [39c8276]
+- Updated dependencies [91fe6d8]
+- Updated dependencies [0be5014]
+  - @ai-sdk/harness@1.0.23
+
+## 1.0.22
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.22
+
+## 1.0.21
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.21
+
+## 1.0.20
+
+### Patch Changes
+
+- Updated dependencies [b7aa06a]
+  - @ai-sdk/harness@1.0.20
+
+## 1.0.19
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.19
+
+## 1.0.18
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.18
+
+## 1.0.17
+
+### Patch Changes
+
+- Updated dependencies [5c5c0f5]
+  - @ai-sdk/harness@1.0.17
+
+## 1.0.16
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.16
+
+## 1.0.15
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.15
+
+## 1.0.14
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.14
+
+## 1.0.13
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.13
+
+## 1.0.12
+
+### Patch Changes
+
+- Updated dependencies [7859cea]
+- Updated dependencies [c857346]
+  - @ai-sdk/harness@1.0.12
+
+## 1.0.11
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.11
+
+## 1.0.10
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.10
+
+## 1.0.9
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.9
+
+## 1.0.8
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.8
+
+## 1.0.7
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.7
+
+## 1.0.6
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.6
+
+## 1.0.5
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.5
+
+## 1.0.4
+
+### Patch Changes
+
+- Updated dependencies [c493634]
+  - @ai-sdk/harness@1.0.4
+
+## 1.0.3
+
+### Patch Changes
+
+- Updated dependencies [51d10a0]
+  - @ai-sdk/harness@1.0.3
+
+## 1.0.2
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.2
+
+## 1.0.1
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.1
+
+## 1.0.0
+
+### Major Changes
+
+- 6e33eb6: feat(workflow-harness): introduce workflow utilities for durable harness agent execution
+
+### Patch Changes
+
+## 1.0.0-beta.5
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-beta.27
+
+## 1.0.0-beta.4
+
+### Patch Changes
+
+- Updated dependencies [a83a367]
+  - @ai-sdk/harness@1.0.0-beta.26
+
+## 1.0.0-beta.3
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-beta.25
+
+## 1.0.0-beta.2
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-beta.24
+
+## 1.0.0-beta.1
+
+### Patch Changes
+
+- Updated dependencies [57e0a59]
+  - @ai-sdk/harness@1.0.0-beta.23
+
+## 1.0.0-beta.0
+
+### Major Changes
+
+- 6e33eb6: feat(workflow-harness): introduce workflow utilities for durable harness agent execution
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-beta.22

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,92 @@
+# @ai-sdk/workflow-harness
+
+Run an AI SDK `HarnessAgent` (Claude Code, Codex, Pi) as a **durable workflow**
+using the [Workflow DevKit](https://www.npmjs.com/package/workflow).
+
+A long agent turn is sliced into short, time-boxed steps so it survives a Fluid
+Compute function recycle (~800s). Between slices the agent is frozen
+non-destructively — the sandbox keeps running and the next slice reattaches to
+the in-flight turn (`attach`) — and a serializable state object is persisted as
+the durable step return value.
+
+This package ships plain helpers + a serializable state machine; you own the
+thin `'use workflow'` / `'use step'` wrappers (the Workflow DevKit compiles
+those directives in your app).
+
+Keep the Workflow DevKit entrypoints separate from the agent definition. The
+workflow module should import only workflow-safe code plus step modules. The
+step module should dynamically import the agent inside the `'use step'` body so
+the agent, sandbox provider, and other Node-heavy dependencies stay out of the
+compiled workflow bundle.
+
+`agent.ts`:
+
+```ts
+import { HarnessAgent } from '@ai-sdk/harness/agent';
+import { claudeCode } from '@ai-sdk/harness-claude-code';
+import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
+
+export const agent = new HarnessAgent({
+  harness: claudeCode,
+  sandbox: createVercelSandbox({ runtime: 'node24', ports: [4000] }),
+});
+```
+
+`run-slice-step.ts`:
+
+```ts
+import {
+  runHarnessAgentSlice,
+  type HarnessWorkflowState,
+} from '@ai-sdk/workflow-harness';
+
+export async function runSlice(
+  state: HarnessWorkflowState,
+): Promise<HarnessWorkflowState> {
+  'use step';
+
+  const { agent } = await import('./agent');
+  return runHarnessAgentSlice({ agent, state });
+}
+```
+
+`workflow.ts`:
+
+```ts
+import {
+  createHarnessWorkflowState,
+  finalizeHarnessWorkflow,
+  type HarnessWorkflowInput,
+} from '@ai-sdk/workflow-harness';
+import { runSlice } from './run-slice-step';
+
+export async function codingWorkflow(input: {
+  prompt: HarnessWorkflowInput['prompt'];
+  sessionId: string;
+}) {
+  'use workflow';
+
+  let state = createHarnessWorkflowState(input);
+  while (state.status === 'running' || state.status === 'timed_out') {
+    state = await runSlice(state);
+  }
+  return finalizeHarnessWorkflow(state);
+}
+```
+
+`route.ts` (Next.js example):
+
+```ts
+import { start } from 'workflow/api';
+import { codingWorkflow } from './workflow';
+
+export async function POST(request: Request) {
+  const body = (await request.json()) as {
+    prompt: string;
+    sessionId: string;
+  };
+  const run = await start(codingWorkflow, [body]);
+
+  return new Response(run.readable);
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+import { HarnessV1Prompt, HarnessV1ResumeSessionState, HarnessV1ContinueTurnState } from '@ai-sdk/harness';
+import { HarnessAgentSession } from '@ai-sdk/harness/agent';
+
+type HarnessWorkflowModelMessage = {
+    readonly role: 'system';
+    readonly content: any;
+} | {
+    readonly role: 'user';
+    readonly content: any;
+} | {
+    readonly role: 'assistant';
+    readonly content: any;
+} | {
+    readonly role: 'tool';
+    readonly content: any;
+};
+/**
+ * Where a workflow-driven harness run is in its slice loop.
+ *
+ *  - `running`   — fresh state, no slice has run yet.
+ *  - `timed_out` — a slice hit its wall-clock budget; `continueFrom` carries
+ *                  the cursor to continue the same turn.
+ *  - `awaiting_tool_approval` — the turn emitted one or more tool approval
+ *                  requests and `continueFrom` carries the suspended turn.
+ *  - `finished`  — the agent turn completed on its own; `finalResult` is set.
+ *  - `failed`    — the turn errored; `error` is set.
+ */
+type HarnessWorkflowStatus = 'running' | 'timed_out' | 'awaiting_tool_approval' | 'finished' | 'failed';
+interface HarnessWorkflowUsageSummary {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+}
+interface HarnessWorkflowFinalResult {
+    readonly sessionId: string;
+    readonly finishReason: string;
+    readonly usage?: HarnessWorkflowUsageSummary;
+}
+interface HarnessWorkflowSerializedChunk {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+interface HarnessWorkflowStreamContext {
+    readonly activeTextParts?: Record<string, HarnessWorkflowSerializedChunk>;
+    readonly activeReasoningParts?: Record<string, HarnessWorkflowSerializedChunk>;
+    readonly pendingToolInputs?: Record<string, HarnessWorkflowSerializedChunk>;
+}
+/**
+ * Serializable state machine threaded between workflow slices. A `'use step'`
+ * returns the next value of this object, and the Workflow DevKit persists that
+ * return value — so this is the entire durable state of a harness run. Every
+ * field must be JSON-serializable.
+ *
+ * Two independent lifecycle states drive the engine:
+ *
+ *  - `resumeFrom` reattaches to a warm session before starting this run's new
+ *    user turn.
+ *  - `continueFrom` reattaches to an interrupted turn from this same run and
+ *    continues it without sending `prompt` again.
+ */
+interface HarnessWorkflowState {
+    /**
+     * Stable harness session id; doubles as the sandbox name across processes.
+     * Reuse the chat/conversation id so every user turn resumes the same warm
+     * session and the agent retains prior-turn context.
+     */
+    readonly sessionId: string;
+    /**
+     * The new user turn for this run — a plain string or a single
+     * `UserModelMessage` (the harness's own {@link HarnessV1Prompt}), so
+     * structured content survives instead of being flattened to text. Sent once,
+     * on the slice that starts the turn.
+     */
+    readonly prompt: HarnessV1Prompt;
+    /**
+     * Full AI SDK model messages for continuing a suspended approval turn. When
+     * present, the next slice sends these to `HarnessAgent.stream()` so approval
+     * responses can resume the interrupted turn.
+     */
+    readonly messages?: HarnessWorkflowModelMessage[];
+    readonly status: HarnessWorkflowStatus;
+    /**
+     * Resume coordinates for the next user turn. Absent only on the first turn of
+     * a brand-new conversation or when the sandbox was destroyed after finish.
+     */
+    readonly resumeFrom?: HarnessV1ResumeSessionState;
+    /**
+     * Continuation coordinates for this run's current suspended turn. When
+     * present, the next slice must call `continueTurn` rather than sending
+     * `prompt` again.
+     */
+    readonly continueFrom?: HarnessV1ContinueTurnState;
+    readonly streamContext?: HarnessWorkflowStreamContext;
+    readonly finalResult?: HarnessWorkflowFinalResult;
+    readonly error?: string;
+}
+/**
+ * Input for one user turn — the argument to {@link createHarnessWorkflowState}
+ * and the natural shape for a workflow function's input. `sessionId` is required
+ * (and must be caller-supplied, since the workflow runtime forbids
+ * non-deterministic id generation inside a step) — reuse the conversation id so
+ * the sandbox name is stable across turns. Pass `resumeFrom` (the handle
+ * persisted after the previous turn) to resume the warm conversation; omit it
+ * only for the first turn of a new conversation.
+ */
+interface HarnessWorkflowInput {
+    prompt?: HarnessV1Prompt;
+    messages?: HarnessWorkflowModelMessage[];
+    sessionId: string;
+    resumeFrom?: HarnessV1ResumeSessionState;
+    continueFrom?: HarnessV1ContinueTurnState;
+}
+/** Initial state for one user turn (see {@link HarnessWorkflowInput}). */
+declare function createHarnessWorkflowState(input: HarnessWorkflowInput): HarnessWorkflowState;
+/**
+ * Collapse a terminal state into its result. Throws if the run failed; returns
+ * the captured `finalResult` when finished, or a best-effort result otherwise.
+ */
+declare function finalizeHarnessWorkflow(state: HarnessWorkflowState): HarnessWorkflowFinalResult;
+
+/** The non-string arm of {@link HarnessV1Prompt} — a single `UserModelMessage`. */
+type HarnessV1UserMessage = Exclude<HarnessV1Prompt, string>;
+/** A UI-message-stream chunk. Kept structural so this package need not depend on `ai`. */
+interface HarnessWorkflowChunk {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * The subset of a harness `stream()` / `continueStream()` result the slice loop uses.
+ * `StreamTextResult` satisfies it structurally.
+ */
+interface HarnessWorkflowStreamResult {
+    toUIMessageStream(): ReadableStream<HarnessWorkflowChunk>;
+    readonly finishReason: PromiseLike<unknown>;
+    readonly totalUsage: PromiseLike<unknown>;
+}
+/**
+ * The subset of `HarnessAgent` the slice loop drives. Declared structurally so
+ * the engine is decoupled from the concrete agent generics and easy to mock.
+ */
+interface HarnessWorkflowAgent {
+    createSession(options?: {
+        sessionId?: string;
+        resumeFrom?: HarnessV1ResumeSessionState;
+        continueFrom?: HarnessV1ContinueTurnState;
+    }): Promise<HarnessAgentSession>;
+    stream(options: {
+        session: HarnessAgentSession;
+        /**
+         * The new user turn. A string or an array of user messages — the shape
+         * `HarnessAgent.stream` accepts (it collapses an array to its last user
+         * entry). The engine passes the run's single {@link HarnessV1Prompt}.
+         */
+        prompt: string | HarnessV1UserMessage[];
+        messages?: undefined;
+    } | {
+        session: HarnessAgentSession;
+        prompt?: undefined;
+        messages: HarnessWorkflowModelMessage[];
+    }): Promise<HarnessWorkflowStreamResult>;
+    continueStream(options: {
+        session: HarnessAgentSession;
+    }): Promise<HarnessWorkflowStreamResult>;
+}
+interface RunHarnessAgentSliceOptions {
+    readonly agent: HarnessWorkflowAgent;
+    readonly state: HarnessWorkflowState;
+    /** Wall-clock budget for this slice. Defaults to {@link DEFAULT_SLICE_TIMEOUT_SECONDS}. */
+    readonly sliceTimeoutSeconds?: number;
+    /**
+     * When the turn finishes, whether to destroy the sandbox. Defaults to `false`:
+     * the session is parked or stopped and a fresh resume state is returned in
+     * `resumeFrom`, so the next user turn reattaches to the same conversation
+     * (multi-turn chat). Set `true` for a one-shot run that should release the
+     * sandbox when the turn completes.
+     */
+    readonly destroyOnFinish?: boolean;
+    /**
+     * Where to write the turn's UI-message chunks. Defaults to the workflow's
+     * output stream (`getWritable()` from `workflow`). Inject a stream in tests
+     * to run the engine without a workflow runtime.
+     */
+    readonly writable?: WritableStream<HarnessWorkflowChunk>;
+}
+/**
+ * Run one durable slice of a harness agent turn.
+ *
+ * Intended to be the body of a consumer's `'use step'`: it resumes (or starts)
+ * the session, streams the turn's chunks to the workflow output, and races the
+ * turn against a wall-clock budget. If the budget fires first it freezes the
+ * turn with `session.suspendTurn()` (the sandbox keeps running) and returns a
+ * `timed_out` state carrying continuation state for the next slice; if the
+ * turn finishes first it returns a `finished` state with the result.
+ *
+ * The returned {@link HarnessWorkflowState} is serializable and is meant to be
+ * the step's return value — the Workflow DevKit persists it as the durable
+ * checkpoint between slices.
+ */
+declare function runHarnessAgentSlice(options: RunHarnessAgentSliceOptions): Promise<HarnessWorkflowState>;
+
+export { type HarnessWorkflowAgent, type HarnessWorkflowChunk, type HarnessWorkflowFinalResult, type HarnessWorkflowInput, type HarnessWorkflowModelMessage, type HarnessWorkflowState, type HarnessWorkflowStatus, type HarnessWorkflowStreamResult, type HarnessWorkflowUsageSummary, type RunHarnessAgentSliceOptions, createHarnessWorkflowState, finalizeHarnessWorkflow, runHarnessAgentSlice };