@ai-sdk/workflow-harness 0.0.0 → 1.0.0-beta.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/harness-workflow-state.ts","../src/run-harness-agent-slice.ts"],"sourcesContent":["import type {\n  HarnessV1ContinueTurnState,\n  HarnessV1Prompt,\n  HarnessV1ResumeSessionState,\n} from '@ai-sdk/harness';\n\nexport type HarnessWorkflowModelMessage =\n  | { readonly role: 'system'; readonly content: any }\n  | { readonly role: 'user'; readonly content: any }\n  | { readonly role: 'assistant'; readonly content: any }\n  | { readonly role: 'tool'; readonly content: any };\n\n/**\n * Where a workflow-driven harness run is in its slice loop.\n *\n *  - `running`   — fresh state, no slice has run yet.\n *  - `timed_out` — a slice hit its wall-clock budget; `continueFrom` carries\n *                  the cursor to continue the same turn.\n *  - `awaiting_tool_approval` — the turn emitted one or more tool approval\n *                  requests and `continueFrom` carries the suspended turn.\n *  - `finished`  — the agent turn completed on its own; `finalResult` is set.\n *  - `failed`    — the turn errored; `error` is set.\n */\nexport type HarnessWorkflowStatus =\n  | 'running'\n  | 'timed_out'\n  | 'awaiting_tool_approval'\n  | 'finished'\n  | 'failed';\n\nexport interface HarnessWorkflowUsageSummary {\n  readonly inputTokens?: number;\n  readonly outputTokens?: number;\n}\n\nexport interface HarnessWorkflowFinalResult {\n  readonly sessionId: string;\n  readonly finishReason: string;\n  readonly usage?: HarnessWorkflowUsageSummary;\n}\n\nexport interface HarnessWorkflowSerializedChunk {\n  readonly type: string;\n  readonly [key: string]: unknown;\n}\n\nexport interface HarnessWorkflowStreamContext {\n  readonly activeTextParts?: Record<string, HarnessWorkflowSerializedChunk>;\n  readonly activeReasoningParts?: Record<\n    string,\n    HarnessWorkflowSerializedChunk\n  >;\n  readonly pendingToolInputs?: Record<string, HarnessWorkflowSerializedChunk>;\n}\n\n/**\n * Serializable state machine threaded between workflow slices. A `'use step'`\n * returns the next value of this object, and the Workflow DevKit persists that\n * return value — so this is the entire durable state of a harness run. Every\n * field must be JSON-serializable.\n *\n * Two independent lifecycle states drive the engine:\n *\n *  - `resumeFrom` reattaches to a warm session before starting this run's new\n *    user turn.\n *  - `continueFrom` reattaches to an interrupted turn from this same run and\n *    continues it without sending `prompt` again.\n */\nexport interface HarnessWorkflowState {\n  /**\n   * Stable harness session id; doubles as the sandbox name across processes.\n   * Reuse the chat/conversation id so every user turn resumes the same warm\n   * session and the agent retains prior-turn context.\n   */\n  readonly sessionId: string;\n  /**\n   * The new user turn for this run — a plain string or a single\n   * `UserModelMessage` (the harness's own {@link HarnessV1Prompt}), so\n   * structured content survives instead of being flattened to text. Sent once,\n   * on the slice that starts the turn.\n   */\n  readonly prompt: HarnessV1Prompt;\n  /**\n   * Full AI SDK model messages for continuing a suspended approval turn. When\n   * present, the next slice sends these to `HarnessAgent.stream()` so approval\n   * responses can resume the interrupted turn.\n   */\n  readonly messages?: HarnessWorkflowModelMessage[];\n  readonly status: HarnessWorkflowStatus;\n  /**\n   * Resume coordinates for the next user turn. Absent only on the first turn of\n   * a brand-new conversation or when the sandbox was destroyed after finish.\n   */\n  readonly resumeFrom?: HarnessV1ResumeSessionState;\n  /**\n   * Continuation coordinates for this run's current suspended turn. When\n   * present, the next slice must call `continueTurn` rather than sending\n   * `prompt` again.\n   */\n  readonly continueFrom?: HarnessV1ContinueTurnState;\n  readonly streamContext?: HarnessWorkflowStreamContext;\n  readonly finalResult?: HarnessWorkflowFinalResult;\n  readonly error?: string;\n}\n\n/**\n * Input for one user turn — the argument to {@link createHarnessWorkflowState}\n * and the natural shape for a workflow function's input. `sessionId` is required\n * (and must be caller-supplied, since the workflow runtime forbids\n * non-deterministic id generation inside a step) — reuse the conversation id so\n * the sandbox name is stable across turns. Pass `resumeFrom` (the handle\n * persisted after the previous turn) to resume the warm conversation; omit it\n * only for the first turn of a new conversation.\n */\nexport interface HarnessWorkflowInput {\n  prompt?: HarnessV1Prompt;\n  messages?: HarnessWorkflowModelMessage[];\n  sessionId: string;\n  resumeFrom?: HarnessV1ResumeSessionState;\n  continueFrom?: HarnessV1ContinueTurnState;\n}\n\n/** Initial state for one user turn (see {@link HarnessWorkflowInput}). */\nexport function createHarnessWorkflowState(\n  input: HarnessWorkflowInput,\n): HarnessWorkflowState {\n  return {\n    sessionId: input.sessionId,\n    prompt: input.prompt ?? '',\n    ...(input.messages != null ? { messages: input.messages } : {}),\n    status: 'running',\n    ...(input.resumeFrom != null ? { resumeFrom: input.resumeFrom } : {}),\n    ...(input.continueFrom != null ? { continueFrom: input.continueFrom } : {}),\n  };\n}\n\n/**\n * Collapse a terminal state into its result. Throws if the run failed; returns\n * the captured `finalResult` when finished, or a best-effort result otherwise.\n */\nexport function finalizeHarnessWorkflow(\n  state: HarnessWorkflowState,\n): HarnessWorkflowFinalResult {\n  if (state.status === 'failed') {\n    throw new Error(state.error ?? 'harness workflow failed');\n  }\n  if (state.finalResult) {\n    return state.finalResult;\n  }\n  return { sessionId: state.sessionId, finishReason: 'unknown' };\n}\n","import type {\n  HarnessV1ContinueTurnState,\n  HarnessV1Prompt,\n  HarnessV1ResumeSessionState,\n} from '@ai-sdk/harness';\nimport type { HarnessAgentSession } from '@ai-sdk/harness/agent';\nimport type {\n  HarnessWorkflowModelMessage,\n  HarnessWorkflowSerializedChunk,\n  HarnessWorkflowState,\n  HarnessWorkflowStreamContext,\n  HarnessWorkflowUsageSummary,\n} from './harness-workflow-state';\n\n/** The non-string arm of {@link HarnessV1Prompt} — a single `UserModelMessage`. */\ntype HarnessV1UserMessage = Exclude<HarnessV1Prompt, string>;\n\n/*\n * Default wall-clock budget for one slice, in seconds.\n *\n * Vercel Fluid Compute recycles a function instance at ~800s, forcing it to\n * reconnect; freezing the slice at 750s lands just before that with a small\n * safety buffer, so the next invocation reattaches to the still-running sandbox\n * rather than being torn down mid-turn.\n */\nconst DEFAULT_SLICE_TIMEOUT_SECONDS = 750;\n\n/** A UI-message-stream chunk. Kept structural so this package need not depend on `ai`. */\nexport interface HarnessWorkflowChunk {\n  readonly type: string;\n  readonly [key: string]: unknown;\n}\n\n/**\n * The subset of a harness `stream()` / `continueStream()` result the slice loop uses.\n * `StreamTextResult` satisfies it structurally.\n */\nexport interface HarnessWorkflowStreamResult {\n  toUIMessageStream(): ReadableStream<HarnessWorkflowChunk>;\n  readonly finishReason: PromiseLike<unknown>;\n  readonly totalUsage: PromiseLike<unknown>;\n}\n\n/**\n * The subset of `HarnessAgent` the slice loop drives. Declared structurally so\n * the engine is decoupled from the concrete agent generics and easy to mock.\n */\nexport interface HarnessWorkflowAgent {\n  createSession(options?: {\n    sessionId?: string;\n    resumeFrom?: HarnessV1ResumeSessionState;\n    continueFrom?: HarnessV1ContinueTurnState;\n  }): Promise<HarnessAgentSession>;\n  stream(\n    options:\n      | {\n          session: HarnessAgentSession;\n          /**\n           * The new user turn. A string or an array of user messages — the shape\n           * `HarnessAgent.stream` accepts (it collapses an array to its last user\n           * entry). The engine passes the run's single {@link HarnessV1Prompt}.\n           */\n          prompt: string | HarnessV1UserMessage[];\n          messages?: undefined;\n        }\n      | {\n          session: HarnessAgentSession;\n          prompt?: undefined;\n          messages: HarnessWorkflowModelMessage[];\n        },\n  ): Promise<HarnessWorkflowStreamResult>;\n  continueStream(options: {\n    session: HarnessAgentSession;\n  }): Promise<HarnessWorkflowStreamResult>;\n}\n\nexport interface RunHarnessAgentSliceOptions {\n  readonly agent: HarnessWorkflowAgent;\n  readonly state: HarnessWorkflowState;\n  /** Wall-clock budget for this slice. Defaults to {@link DEFAULT_SLICE_TIMEOUT_SECONDS}. */\n  readonly sliceTimeoutSeconds?: number;\n  /**\n   * When the turn finishes, whether to destroy the sandbox. Defaults to `false`:\n   * the session is parked or stopped and a fresh resume state is returned in\n   * `resumeFrom`, so the next user turn reattaches to the same conversation\n   * (multi-turn chat). Set `true` for a one-shot run that should release the\n   * sandbox when the turn completes.\n   */\n  readonly destroyOnFinish?: boolean;\n  /**\n   * Where to write the turn's UI-message chunks. Defaults to the workflow's\n   * output stream (`getWritable()` from `workflow`). Inject a stream in tests\n   * to run the engine without a workflow runtime.\n   */\n  readonly writable?: WritableStream<HarnessWorkflowChunk>;\n}\n\n/**\n * Run one durable slice of a harness agent turn.\n *\n * Intended to be the body of a consumer's `'use step'`: it resumes (or starts)\n * the session, streams the turn's chunks to the workflow output, and races the\n * turn against a wall-clock budget. If the budget fires first it freezes the\n * turn with `session.suspendTurn()` (the sandbox keeps running) and returns a\n * `timed_out` state carrying continuation state for the next slice; if the\n * turn finishes first it returns a `finished` state with the result.\n *\n * The returned {@link HarnessWorkflowState} is serializable and is meant to be\n * the step's return value — the Workflow DevKit persists it as the durable\n * checkpoint between slices.\n */\nexport async function runHarnessAgentSlice(\n  options: RunHarnessAgentSliceOptions,\n): Promise<HarnessWorkflowState> {\n  const { agent, state } = options;\n  const sliceTimeoutSeconds =\n    options.sliceTimeoutSeconds ?? DEFAULT_SLICE_TIMEOUT_SECONDS;\n  const destroyOnFinish = options.destroyOnFinish ?? false;\n\n  const session =\n    state.continueFrom != null\n      ? await agent.createSession({\n          sessionId: state.sessionId,\n          continueFrom: state.continueFrom,\n        })\n      : state.resumeFrom != null\n        ? await agent.createSession({\n            sessionId: state.sessionId,\n            resumeFrom: state.resumeFrom,\n          })\n        : await agent.createSession({ sessionId: state.sessionId });\n\n  let result: HarnessWorkflowStreamResult;\n  try {\n    result =\n      state.messages != null\n        ? await agent.stream({\n            session,\n            messages: state.messages,\n          })\n        : state.continueFrom != null\n          ? await agent.continueStream({ session })\n          : await agent.stream({\n              session,\n              prompt:\n                typeof state.prompt === 'string'\n                  ? state.prompt\n                  : [state.prompt],\n            });\n  } catch (err) {\n    await destroyQuietly(session);\n    return {\n      sessionId: state.sessionId,\n      prompt: state.prompt,\n      status: 'failed',\n      ...(state.resumeFrom != null ? { resumeFrom: state.resumeFrom } : {}),\n      ...(state.continueFrom != null\n        ? { continueFrom: state.continueFrom }\n        : {}),\n      error: errorMessage(err),\n    };\n  }\n\n  const writable = options.writable ?? (await resolveWorkflowWritable());\n  const writer = writable.getWriter();\n  const streamContext = createMutableStreamContext(state.streamContext);\n  const slicePartState = createSlicePartState();\n\n  let suspendPromise: Promise<HarnessV1ContinueTurnState> | undefined;\n  const timer = setTimeout(() => {\n    suspendPromise = session.suspendTurn();\n  }, sliceTimeoutSeconds * 1000);\n  (timer as { unref?: () => void }).unref?.();\n\n  let sawError = false;\n  // Tracks whether the writable was closed (only on a finished turn). The\n  // `finally` then releases the lock only when we did NOT close, since closing\n  // already releases it.\n  let writerClosed = false;\n  try {\n    const reader = result.toUIMessageStream().getReader();\n    try {\n      while (true) {\n        const { value, done } = await reader.read();\n        if (done) break;\n        if (value == null) continue;\n        /*\n         * One continuous assistant message per user turn: the slice that starts\n         * the turn keeps the opening `start`; slices that continue an already\n         * suspended turn drop it. Intermediate `finish` chunks are dropped and\n         * the loop writes a single terminal `finish` itself when the run\n         * completes. A new user turn keeps its `start` so the UI renders it as\n         * a fresh assistant message.\n         */\n        if (value.type === 'start' && state.continueFrom != null) continue;\n        if (value.type === 'finish') continue;\n        if (value.type === 'error') {\n          const errorText = (value as { errorText?: unknown }).errorText;\n          /*\n           * When a suspend is in flight we tore the turn down at the slice\n           * boundary, so an *abort* error is the expected consequence — swallow\n           * it (surfacing it would replace the streamed content with an error,\n           * and the next slice continues the turn). Any non-abort error is\n           * unanticipated and must NOT be silenced: surface it and fail the\n           * slice, even mid-suspend.\n           */\n          if (suspendPromise != null && isAbortError(errorText)) {\n            continue;\n          }\n          sawError = true;\n        }\n        await writeWorkflowChunk({\n          chunk: value,\n          writer,\n          streamContext,\n          slicePartState,\n        });\n      }\n    } finally {\n      clearTimeout(timer);\n      reader.releaseLock();\n    }\n\n    // A non-abort error (anything `sawError` survived the abort filter for) is a\n    // real failure and takes priority over the budget — don't let `timed_out`\n    // mask it. (Abort errors during suspend were already filtered above.)\n    if (sawError) {\n      if (suspendPromise != null) await suspendPromise.catch(() => {});\n      await destroyQuietly(session);\n      return {\n        sessionId: state.sessionId,\n        prompt: state.prompt,\n        status: 'failed',\n        ...(state.resumeFrom != null ? { resumeFrom: state.resumeFrom } : {}),\n        ...(state.continueFrom != null\n          ? { continueFrom: state.continueFrom }\n          : {}),\n        error: 'harness turn emitted an error',\n      };\n    }\n\n    // Budget fired: the turn keeps running in the sandbox; persist the cursor\n    // so the next slice attaches and continues the same in-flight turn.\n    if (suspendPromise != null) {\n      const continueFrom = await suspendPromise;\n      await closeOpenSliceParts({\n        writer,\n        streamContext,\n        slicePartState,\n      });\n      return {\n        sessionId: state.sessionId,\n        prompt: state.prompt,\n        status: 'timed_out',\n        continueFrom,\n        ...serializeStreamContextField(streamContext),\n      };\n    }\n\n    const [finishReason, usage] = await Promise.all([\n      Promise.resolve(result.finishReason).catch(() => undefined),\n      Promise.resolve(result.totalUsage).catch(() => undefined),\n    ]);\n    const normalizedFinishReason = toFinishReasonString(finishReason);\n\n    if (normalizedFinishReason === 'tool-calls') {\n      const continueFrom = await session.suspendTurn();\n      await writer.write({ type: 'finish', finishReason: 'tool-calls' });\n      await writer.close();\n      writerClosed = true;\n      return {\n        sessionId: state.sessionId,\n        prompt: state.prompt,\n        status: 'awaiting_tool_approval',\n        continueFrom,\n      };\n    }\n\n    // The turn finished on its own: write the single terminal `finish` for the\n    // UI message, then CLOSE the writable. Closing matters: the workflow output\n    // stream (`getWritable()`) is what the run's `readable` is fed from, and the\n    // DevKit only marks that run stream \"done\" when the writable is closed — a\n    // released-but-open writer leaves it open forever, so a consumer piping\n    // `run.readable` into a UI-message-stream response never receives the\n    // terminal close and the client stays \"streaming\" indefinitely. (`timed_out`\n    // and `failed` deliberately do NOT close — the next slice keeps writing, or\n    // the failure propagates.)\n    await writer.write({ type: 'finish' });\n    await writer.close();\n    writerClosed = true;\n\n    /*\n     * Capture resume state for the *next user turn* before ending this local\n     * session handle. `detach()` parks the session without stopping the sandbox;\n     * bridge-backed sessions usually resume by attach/replay, while\n     * host-resident sessions may resume by rerun. A one-shot consumer opts into\n     * `destroyOnFinish` to destroy the sandbox instead.\n     */\n    let resumeFrom = state.resumeFrom;\n    if (destroyOnFinish) {\n      await destroyQuietly(session);\n      resumeFrom = undefined;\n    } else {\n      resumeFrom = await session.detach().catch(() => state.resumeFrom);\n    }\n\n    return {\n      sessionId: state.sessionId,\n      prompt: state.prompt,\n      status: 'finished',\n      ...(resumeFrom != null ? { resumeFrom } : {}),\n      finalResult: {\n        sessionId: state.sessionId,\n        finishReason: normalizedFinishReason,\n        usage: toUsageSummary(usage),\n      },\n    };\n  } finally {\n    if (!writerClosed) writer.releaseLock();\n  }\n}\n\ntype MutableStreamContext = {\n  activeTextParts: Record<string, HarnessWorkflowSerializedChunk>;\n  activeReasoningParts: Record<string, HarnessWorkflowSerializedChunk>;\n  pendingToolInputs: Record<string, HarnessWorkflowSerializedChunk>;\n};\n\ntype SlicePartState = {\n  openedTextParts: Set<string>;\n  openedReasoningParts: Set<string>;\n  writtenToolInputs: Set<string>;\n};\n\nfunction createMutableStreamContext(\n  context: HarnessWorkflowStreamContext | undefined,\n): MutableStreamContext {\n  return {\n    activeTextParts: { ...(context?.activeTextParts ?? {}) },\n    activeReasoningParts: { ...(context?.activeReasoningParts ?? {}) },\n    pendingToolInputs: { ...(context?.pendingToolInputs ?? {}) },\n  };\n}\n\nfunction createSlicePartState(): SlicePartState {\n  return {\n    openedTextParts: new Set(),\n    openedReasoningParts: new Set(),\n    writtenToolInputs: new Set(),\n  };\n}\n\nasync function writeWorkflowChunk(options: {\n  chunk: HarnessWorkflowChunk;\n  writer: WritableStreamDefaultWriter<HarnessWorkflowChunk>;\n  streamContext: MutableStreamContext;\n  slicePartState: SlicePartState;\n}): Promise<void> {\n  await writeRequiredPrelude(options);\n  await options.writer.write(options.chunk);\n  recordWorkflowChunk(options);\n}\n\nasync function writeRequiredPrelude(options: {\n  chunk: HarnessWorkflowChunk;\n  writer: WritableStreamDefaultWriter<HarnessWorkflowChunk>;\n  streamContext: MutableStreamContext;\n  slicePartState: SlicePartState;\n}): Promise<void> {\n  const { chunk, writer, streamContext, slicePartState } = options;\n  const id = stringProperty({ chunk, key: 'id' });\n\n  if (\n    (chunk.type === 'text-delta' || chunk.type === 'text-end') &&\n    id != null &&\n    streamContext.activeTextParts[id] != null &&\n    !slicePartState.openedTextParts.has(id)\n  ) {\n    await writer.write(streamContext.activeTextParts[id]);\n    slicePartState.openedTextParts.add(id);\n  }\n\n  if (\n    (chunk.type === 'reasoning-delta' || chunk.type === 'reasoning-end') &&\n    id != null &&\n    streamContext.activeReasoningParts[id] != null &&\n    !slicePartState.openedReasoningParts.has(id)\n  ) {\n    await writer.write(streamContext.activeReasoningParts[id]);\n    slicePartState.openedReasoningParts.add(id);\n  }\n\n  const toolCallId = stringProperty({ chunk, key: 'toolCallId' });\n  if (\n    toolCallId != null &&\n    needsToolInputPrelude(chunk) &&\n    streamContext.pendingToolInputs[toolCallId] != null &&\n    !slicePartState.writtenToolInputs.has(toolCallId)\n  ) {\n    await writer.write(streamContext.pendingToolInputs[toolCallId]);\n    slicePartState.writtenToolInputs.add(toolCallId);\n  }\n}\n\nfunction recordWorkflowChunk(options: {\n  chunk: HarnessWorkflowChunk;\n  streamContext: MutableStreamContext;\n  slicePartState: SlicePartState;\n}): void {\n  const { chunk, streamContext, slicePartState } = options;\n  const id = stringProperty({ chunk, key: 'id' });\n  const toolCallId = stringProperty({ chunk, key: 'toolCallId' });\n\n  if (chunk.type === 'text-start' && id != null) {\n    streamContext.activeTextParts[id] = cloneChunk(chunk);\n    slicePartState.openedTextParts.add(id);\n    return;\n  }\n\n  if (chunk.type === 'text-end' && id != null) {\n    delete streamContext.activeTextParts[id];\n    slicePartState.openedTextParts.delete(id);\n    return;\n  }\n\n  if (chunk.type === 'reasoning-start' && id != null) {\n    streamContext.activeReasoningParts[id] = cloneChunk(chunk);\n    slicePartState.openedReasoningParts.add(id);\n    return;\n  }\n\n  if (chunk.type === 'reasoning-end' && id != null) {\n    delete streamContext.activeReasoningParts[id];\n    slicePartState.openedReasoningParts.delete(id);\n    return;\n  }\n\n  if (chunk.type === 'tool-input-available' && toolCallId != null) {\n    streamContext.pendingToolInputs[toolCallId] = cloneChunk(chunk);\n    slicePartState.writtenToolInputs.add(toolCallId);\n    return;\n  }\n\n  if (chunk.type === 'tool-input-error' && toolCallId != null) {\n    delete streamContext.pendingToolInputs[toolCallId];\n    slicePartState.writtenToolInputs.add(toolCallId);\n    return;\n  }\n\n  if (\n    (chunk.type === 'tool-output-error' ||\n      chunk.type === 'tool-output-denied' ||\n      (chunk.type === 'tool-output-available' &&\n        (chunk as { preliminary?: unknown }).preliminary !== true)) &&\n    toolCallId != null\n  ) {\n    delete streamContext.pendingToolInputs[toolCallId];\n  }\n}\n\nasync function closeOpenSliceParts(options: {\n  writer: WritableStreamDefaultWriter<HarnessWorkflowChunk>;\n  streamContext: MutableStreamContext;\n  slicePartState: SlicePartState;\n}): Promise<void> {\n  const { writer, streamContext, slicePartState } = options;\n\n  for (const id of slicePartState.openedTextParts) {\n    if (streamContext.activeTextParts[id] != null) {\n      await writer.write({ type: 'text-end', id });\n    }\n  }\n  slicePartState.openedTextParts.clear();\n\n  for (const id of slicePartState.openedReasoningParts) {\n    if (streamContext.activeReasoningParts[id] != null) {\n      await writer.write({ type: 'reasoning-end', id });\n    }\n  }\n  slicePartState.openedReasoningParts.clear();\n}\n\nfunction serializeStreamContextField(context: MutableStreamContext): {\n  streamContext?: HarnessWorkflowStreamContext;\n} {\n  const streamContext: HarnessWorkflowStreamContext = {\n    ...(Object.keys(context.activeTextParts).length > 0\n      ? { activeTextParts: context.activeTextParts }\n      : {}),\n    ...(Object.keys(context.activeReasoningParts).length > 0\n      ? { activeReasoningParts: context.activeReasoningParts }\n      : {}),\n    ...(Object.keys(context.pendingToolInputs).length > 0\n      ? { pendingToolInputs: context.pendingToolInputs }\n      : {}),\n  };\n  return Object.keys(streamContext).length > 0 ? { streamContext } : {};\n}\n\nfunction needsToolInputPrelude(chunk: HarnessWorkflowChunk): boolean {\n  return (\n    chunk.type === 'tool-approval-request' ||\n    chunk.type === 'tool-output-available' ||\n    chunk.type === 'tool-output-error' ||\n    chunk.type === 'tool-output-denied'\n  );\n}\n\nfunction stringProperty(options: {\n  chunk: HarnessWorkflowChunk;\n  key: string;\n}): string | undefined {\n  const value = options.chunk[options.key];\n  return typeof value === 'string' ? value : undefined;\n}\n\nfunction cloneChunk(\n  chunk: HarnessWorkflowChunk,\n): HarnessWorkflowSerializedChunk {\n  return { ...chunk };\n}\n\n/**\n * Resolve the workflow's default output stream lazily, so importing this module\n * never requires the `workflow` runtime (tests inject their own `writable`).\n */\nasync function resolveWorkflowWritable(): Promise<\n  WritableStream<HarnessWorkflowChunk>\n> {\n  const { getWritable } = (await import('workflow')) as {\n    getWritable: <T>() => WritableStream<T>;\n  };\n  return getWritable<HarnessWorkflowChunk>();\n}\n\nasync function destroyQuietly(session: HarnessAgentSession): Promise<void> {\n  await session.destroy().catch(() => {});\n}\n\nfunction errorMessage(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n\n/**\n * Whether an error (or UI `error` part's `errorText`) is an abort — the\n * expected consequence of `suspendTurn()` tearing the turn down at a slice\n * boundary. Only these are safe to swallow during a suspend; any other error is\n * unanticipated and must surface.\n */\nfunction isAbortError(value: unknown): boolean {\n  if (value == null) return false;\n  if (\n    typeof value === 'object' &&\n    (value as { name?: unknown }).name === 'AbortError'\n  ) {\n    return true;\n  }\n  const text =\n    typeof value === 'string'\n      ? value\n      : value instanceof Error\n        ? value.message\n        : String(value);\n  return /\\baborted\\b|AbortError|operation was aborted/i.test(text);\n}\n\nfunction toFinishReasonString(finishReason: unknown): string {\n  if (typeof finishReason === 'string') return finishReason;\n  if (\n    finishReason != null &&\n    typeof finishReason === 'object' &&\n    typeof (finishReason as { unified?: unknown }).unified === 'string'\n  ) {\n    return (finishReason as { unified: string }).unified;\n  }\n  return 'stop';\n}\n\nfunction toUsageSummary(\n  usage: unknown,\n): HarnessWorkflowUsageSummary | undefined {\n  if (usage == null || typeof usage !== 'object') return undefined;\n  const u = usage as {\n    inputTokens?: { total?: number };\n    outputTokens?: { total?: number };\n  };\n  const inputTokens = u.inputTokens?.total;\n  const outputTokens = u.outputTokens?.total;\n  if (inputTokens == null && outputTokens == null) return undefined;\n  return {\n    ...(inputTokens != null ? { inputTokens } : {}),\n    ...(outputTokens != null ? { outputTokens } : {}),\n  };\n}\n"],"mappings":";AA2HO,SAAS,2BACd,OACsB;AACtB,SAAO;AAAA,IACL,WAAW,MAAM;AAAA,IACjB,QAAQ,MAAM,UAAU;AAAA,IACxB,GAAI,MAAM,YAAY,OAAO,EAAE,UAAU,MAAM,SAAS,IAAI,CAAC;AAAA,IAC7D,QAAQ;AAAA,IACR,GAAI,MAAM,cAAc,OAAO,EAAE,YAAY,MAAM,WAAW,IAAI,CAAC;AAAA,IACnE,GAAI,MAAM,gBAAgB,OAAO,EAAE,cAAc,MAAM,aAAa,IAAI,CAAC;AAAA,EAC3E;AACF;AAMO,SAAS,wBACd,OAC4B;AAC5B,MAAI,MAAM,WAAW,UAAU;AAC7B,UAAM,IAAI,MAAM,MAAM,SAAS,yBAAyB;AAAA,EAC1D;AACA,MAAI,MAAM,aAAa;AACrB,WAAO,MAAM;AAAA,EACf;AACA,SAAO,EAAE,WAAW,MAAM,WAAW,cAAc,UAAU;AAC/D;;;AC7HA,IAAM,gCAAgC;AAsFtC,eAAsB,qBACpB,SAC+B;AAC/B,QAAM,EAAE,OAAO,MAAM,IAAI;AACzB,QAAM,sBACJ,QAAQ,uBAAuB;AACjC,QAAM,kBAAkB,QAAQ,mBAAmB;AAEnD,QAAM,UACJ,MAAM,gBAAgB,OAClB,MAAM,MAAM,cAAc;AAAA,IACxB,WAAW,MAAM;AAAA,IACjB,cAAc,MAAM;AAAA,EACtB,CAAC,IACD,MAAM,cAAc,OAClB,MAAM,MAAM,cAAc;AAAA,IACxB,WAAW,MAAM;AAAA,IACjB,YAAY,MAAM;AAAA,EACpB,CAAC,IACD,MAAM,MAAM,cAAc,EAAE,WAAW,MAAM,UAAU,CAAC;AAEhE,MAAI;AACJ,MAAI;AACF,aACE,MAAM,YAAY,OACd,MAAM,MAAM,OAAO;AAAA,MACjB;AAAA,MACA,UAAU,MAAM;AAAA,IAClB,CAAC,IACD,MAAM,gBAAgB,OACpB,MAAM,MAAM,eAAe,EAAE,QAAQ,CAAC,IACtC,MAAM,MAAM,OAAO;AAAA,MACjB;AAAA,MACA,QACE,OAAO,MAAM,WAAW,WACpB,MAAM,SACN,CAAC,MAAM,MAAM;AAAA,IACrB,CAAC;AAAA,EACX,SAAS,KAAK;AACZ,UAAM,eAAe,OAAO;AAC5B,WAAO;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,QAAQ,MAAM;AAAA,MACd,QAAQ;AAAA,MACR,GAAI,MAAM,cAAc,OAAO,EAAE,YAAY,MAAM,WAAW,IAAI,CAAC;AAAA,MACnE,GAAI,MAAM,gBAAgB,OACtB,EAAE,cAAc,MAAM,aAAa,IACnC,CAAC;AAAA,MACL,OAAO,aAAa,GAAG;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,WAAW,QAAQ,YAAa,MAAM,wBAAwB;AACpE,QAAM,SAAS,SAAS,UAAU;AAClC,QAAM,gBAAgB,2BAA2B,MAAM,aAAa;AACpE,QAAM,iBAAiB,qBAAqB;AAE5C,MAAI;AACJ,QAAM,QAAQ,WAAW,MAAM;AAC7B,qBAAiB,QAAQ,YAAY;AAAA,EACvC,GAAG,sBAAsB,GAAI;AAC7B,EAAC,MAAiC,QAAQ;AAE1C,MAAI,WAAW;AAIf,MAAI,eAAe;AACnB,MAAI;AACF,UAAM,SAAS,OAAO,kBAAkB,EAAE,UAAU;AACpD,QAAI;AACF,aAAO,MAAM;AACX,cAAM,EAAE,OAAO,KAAK,IAAI,MAAM,OAAO,KAAK;AAC1C,YAAI,KAAM;AACV,YAAI,SAAS,KAAM;AASnB,YAAI,MAAM,SAAS,WAAW,MAAM,gBAAgB,KAAM;AAC1D,YAAI,MAAM,SAAS,SAAU;AAC7B,YAAI,MAAM,SAAS,SAAS;AAC1B,gBAAM,YAAa,MAAkC;AASrD,cAAI,kBAAkB,QAAQ,aAAa,SAAS,GAAG;AACrD;AAAA,UACF;AACA,qBAAW;AAAA,QACb;AACA,cAAM,mBAAmB;AAAA,UACvB,OAAO;AAAA,UACP;AAAA,UACA;AAAA,UACA;AAAA,QACF,CAAC;AAAA,MACH;AAAA,IACF,UAAE;AACA,mBAAa,KAAK;AAClB,aAAO,YAAY;AAAA,IACrB;AAKA,QAAI,UAAU;AACZ,UAAI,kBAAkB,KAAM,OAAM,eAAe,MAAM,MAAM;AAAA,MAAC,CAAC;AAC/D,YAAM,eAAe,OAAO;AAC5B,aAAO;AAAA,QACL,WAAW,MAAM;AAAA,QACjB,QAAQ,MAAM;AAAA,QACd,QAAQ;AAAA,QACR,GAAI,MAAM,cAAc,OAAO,EAAE,YAAY,MAAM,WAAW,IAAI,CAAC;AAAA,QACnE,GAAI,MAAM,gBAAgB,OACtB,EAAE,cAAc,MAAM,aAAa,IACnC,CAAC;AAAA,QACL,OAAO;AAAA,MACT;AAAA,IACF;AAIA,QAAI,kBAAkB,MAAM;AAC1B,YAAM,eAAe,MAAM;AAC3B,YAAM,oBAAoB;AAAA,QACxB;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AACD,aAAO;AAAA,QACL,WAAW,MAAM;AAAA,QACjB,QAAQ,MAAM;AAAA,QACd,QAAQ;AAAA,QACR;AAAA,QACA,GAAG,4BAA4B,aAAa;AAAA,MAC9C;AAAA,IACF;AAEA,UAAM,CAAC,cAAc,KAAK,IAAI,MAAM,QAAQ,IAAI;AAAA,MAC9C,QAAQ,QAAQ,OAAO,YAAY,EAAE,MAAM,MAAM,MAAS;AAAA,MAC1D,QAAQ,QAAQ,OAAO,UAAU,EAAE,MAAM,MAAM,MAAS;AAAA,IAC1D,CAAC;AACD,UAAM,yBAAyB,qBAAqB,YAAY;AAEhE,QAAI,2BAA2B,cAAc;AAC3C,YAAM,eAAe,MAAM,QAAQ,YAAY;AAC/C,YAAM,OAAO,MAAM,EAAE,MAAM,UAAU,cAAc,aAAa,CAAC;AACjE,YAAM,OAAO,MAAM;AACnB,qBAAe;AACf,aAAO;AAAA,QACL,WAAW,MAAM;AAAA,QACjB,QAAQ,MAAM;AAAA,QACd,QAAQ;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAWA,UAAM,OAAO,MAAM,EAAE,MAAM,SAAS,CAAC;AACrC,UAAM,OAAO,MAAM;AACnB,mBAAe;AASf,QAAI,aAAa,MAAM;AACvB,QAAI,iBAAiB;AACnB,YAAM,eAAe,OAAO;AAC5B,mBAAa;AAAA,IACf,OAAO;AACL,mBAAa,MAAM,QAAQ,OAAO,EAAE,MAAM,MAAM,MAAM,UAAU;AAAA,IAClE;AAEA,WAAO;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,QAAQ,MAAM;AAAA,MACd,QAAQ;AAAA,MACR,GAAI,cAAc,OAAO,EAAE,WAAW,IAAI,CAAC;AAAA,MAC3C,aAAa;AAAA,QACX,WAAW,MAAM;AAAA,QACjB,cAAc;AAAA,QACd,OAAO,eAAe,KAAK;AAAA,MAC7B;AAAA,IACF;AAAA,EACF,UAAE;AACA,QAAI,CAAC,aAAc,QAAO,YAAY;AAAA,EACxC;AACF;AAcA,SAAS,2BACP,SACsB;AACtB,SAAO;AAAA,IACL,iBAAiB,EAAE,GAAI,SAAS,mBAAmB,CAAC,EAAG;AAAA,IACvD,sBAAsB,EAAE,GAAI,SAAS,wBAAwB,CAAC,EAAG;AAAA,IACjE,mBAAmB,EAAE,GAAI,SAAS,qBAAqB,CAAC,EAAG;AAAA,EAC7D;AACF;AAEA,SAAS,uBAAuC;AAC9C,SAAO;AAAA,IACL,iBAAiB,oBAAI,IAAI;AAAA,IACzB,sBAAsB,oBAAI,IAAI;AAAA,IAC9B,mBAAmB,oBAAI,IAAI;AAAA,EAC7B;AACF;AAEA,eAAe,mBAAmB,SAKhB;AAChB,QAAM,qBAAqB,OAAO;AAClC,QAAM,QAAQ,OAAO,MAAM,QAAQ,KAAK;AACxC,sBAAoB,OAAO;AAC7B;AAEA,eAAe,qBAAqB,SAKlB;AAChB,QAAM,EAAE,OAAO,QAAQ,eAAe,eAAe,IAAI;AACzD,QAAM,KAAK,eAAe,EAAE,OAAO,KAAK,KAAK,CAAC;AAE9C,OACG,MAAM,SAAS,gBAAgB,MAAM,SAAS,eAC/C,MAAM,QACN,cAAc,gBAAgB,EAAE,KAAK,QACrC,CAAC,eAAe,gBAAgB,IAAI,EAAE,GACtC;AACA,UAAM,OAAO,MAAM,cAAc,gBAAgB,EAAE,CAAC;AACpD,mBAAe,gBAAgB,IAAI,EAAE;AAAA,EACvC;AAEA,OACG,MAAM,SAAS,qBAAqB,MAAM,SAAS,oBACpD,MAAM,QACN,cAAc,qBAAqB,EAAE,KAAK,QAC1C,CAAC,eAAe,qBAAqB,IAAI,EAAE,GAC3C;AACA,UAAM,OAAO,MAAM,cAAc,qBAAqB,EAAE,CAAC;AACzD,mBAAe,qBAAqB,IAAI,EAAE;AAAA,EAC5C;AAEA,QAAM,aAAa,eAAe,EAAE,OAAO,KAAK,aAAa,CAAC;AAC9D,MACE,cAAc,QACd,sBAAsB,KAAK,KAC3B,cAAc,kBAAkB,UAAU,KAAK,QAC/C,CAAC,eAAe,kBAAkB,IAAI,UAAU,GAChD;AACA,UAAM,OAAO,MAAM,cAAc,kBAAkB,UAAU,CAAC;AAC9D,mBAAe,kBAAkB,IAAI,UAAU;AAAA,EACjD;AACF;AAEA,SAAS,oBAAoB,SAIpB;AACP,QAAM,EAAE,OAAO,eAAe,eAAe,IAAI;AACjD,QAAM,KAAK,eAAe,EAAE,OAAO,KAAK,KAAK,CAAC;AAC9C,QAAM,aAAa,eAAe,EAAE,OAAO,KAAK,aAAa,CAAC;AAE9D,MAAI,MAAM,SAAS,gBAAgB,MAAM,MAAM;AAC7C,kBAAc,gBAAgB,EAAE,IAAI,WAAW,KAAK;AACpD,mBAAe,gBAAgB,IAAI,EAAE;AACrC;AAAA,EACF;AAEA,MAAI,MAAM,SAAS,cAAc,MAAM,MAAM;AAC3C,WAAO,cAAc,gBAAgB,EAAE;AACvC,mBAAe,gBAAgB,OAAO,EAAE;AACxC;AAAA,EACF;AAEA,MAAI,MAAM,SAAS,qBAAqB,MAAM,MAAM;AAClD,kBAAc,qBAAqB,EAAE,IAAI,WAAW,KAAK;AACzD,mBAAe,qBAAqB,IAAI,EAAE;AAC1C;AAAA,EACF;AAEA,MAAI,MAAM,SAAS,mBAAmB,MAAM,MAAM;AAChD,WAAO,cAAc,qBAAqB,EAAE;AAC5C,mBAAe,qBAAqB,OAAO,EAAE;AAC7C;AAAA,EACF;AAEA,MAAI,MAAM,SAAS,0BAA0B,cAAc,MAAM;AAC/D,kBAAc,kBAAkB,UAAU,IAAI,WAAW,KAAK;AAC9D,mBAAe,kBAAkB,IAAI,UAAU;AAC/C;AAAA,EACF;AAEA,MAAI,MAAM,SAAS,sBAAsB,cAAc,MAAM;AAC3D,WAAO,cAAc,kBAAkB,UAAU;AACjD,mBAAe,kBAAkB,IAAI,UAAU;AAC/C;AAAA,EACF;AAEA,OACG,MAAM,SAAS,uBACd,MAAM,SAAS,wBACd,MAAM,SAAS,2BACb,MAAoC,gBAAgB,SACzD,cAAc,MACd;AACA,WAAO,cAAc,kBAAkB,UAAU;AAAA,EACnD;AACF;AAEA,eAAe,oBAAoB,SAIjB;AAChB,QAAM,EAAE,QAAQ,eAAe,eAAe,IAAI;AAElD,aAAW,MAAM,eAAe,iBAAiB;AAC/C,QAAI,cAAc,gBAAgB,EAAE,KAAK,MAAM;AAC7C,YAAM,OAAO,MAAM,EAAE,MAAM,YAAY,GAAG,CAAC;AAAA,IAC7C;AAAA,EACF;AACA,iBAAe,gBAAgB,MAAM;AAErC,aAAW,MAAM,eAAe,sBAAsB;AACpD,QAAI,cAAc,qBAAqB,EAAE,KAAK,MAAM;AAClD,YAAM,OAAO,MAAM,EAAE,MAAM,iBAAiB,GAAG,CAAC;AAAA,IAClD;AAAA,EACF;AACA,iBAAe,qBAAqB,MAAM;AAC5C;AAEA,SAAS,4BAA4B,SAEnC;AACA,QAAM,gBAA8C;AAAA,IAClD,GAAI,OAAO,KAAK,QAAQ,eAAe,EAAE,SAAS,IAC9C,EAAE,iBAAiB,QAAQ,gBAAgB,IAC3C,CAAC;AAAA,IACL,GAAI,OAAO,KAAK,QAAQ,oBAAoB,EAAE,SAAS,IACnD,EAAE,sBAAsB,QAAQ,qBAAqB,IACrD,CAAC;AAAA,IACL,GAAI,OAAO,KAAK,QAAQ,iBAAiB,EAAE,SAAS,IAChD,EAAE,mBAAmB,QAAQ,kBAAkB,IAC/C,CAAC;AAAA,EACP;AACA,SAAO,OAAO,KAAK,aAAa,EAAE,SAAS,IAAI,EAAE,cAAc,IAAI,CAAC;AACtE;AAEA,SAAS,sBAAsB,OAAsC;AACnE,SACE,MAAM,SAAS,2BACf,MAAM,SAAS,2BACf,MAAM,SAAS,uBACf,MAAM,SAAS;AAEnB;AAEA,SAAS,eAAe,SAGD;AACrB,QAAM,QAAQ,QAAQ,MAAM,QAAQ,GAAG;AACvC,SAAO,OAAO,UAAU,WAAW,QAAQ;AAC7C;AAEA,SAAS,WACP,OACgC;AAChC,SAAO,EAAE,GAAG,MAAM;AACpB;AAMA,eAAe,0BAEb;AACA,QAAM,EAAE,YAAY,IAAK,MAAM,OAAO,UAAU;AAGhD,SAAO,YAAkC;AAC3C;AAEA,eAAe,eAAe,SAA6C;AACzE,QAAM,QAAQ,QAAQ,EAAE,MAAM,MAAM;AAAA,EAAC,CAAC;AACxC;AAEA,SAAS,aAAa,KAAsB;AAC1C,SAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AACxD;AAQA,SAAS,aAAa,OAAyB;AAC7C,MAAI,SAAS,KAAM,QAAO;AAC1B,MACE,OAAO,UAAU,YAChB,MAA6B,SAAS,cACvC;AACA,WAAO;AAAA,EACT;AACA,QAAM,OACJ,OAAO,UAAU,WACb,QACA,iBAAiB,QACf,MAAM,UACN,OAAO,KAAK;AACpB,SAAO,gDAAgD,KAAK,IAAI;AAClE;AAEA,SAAS,qBAAqB,cAA+B;AAC3D,MAAI,OAAO,iBAAiB,SAAU,QAAO;AAC7C,MACE,gBAAgB,QAChB,OAAO,iBAAiB,YACxB,OAAQ,aAAuC,YAAY,UAC3D;AACA,WAAQ,aAAqC;AAAA,EAC/C;AACA,SAAO;AACT;AAEA,SAAS,eACP,OACyC;AACzC,MAAI,SAAS,QAAQ,OAAO,UAAU,SAAU,QAAO;AACvD,QAAM,IAAI;AAIV,QAAM,cAAc,EAAE,aAAa;AACnC,QAAM,eAAe,EAAE,cAAc;AACrC,MAAI,eAAe,QAAQ,gBAAgB,KAAM,QAAO;AACxD,SAAO;AAAA,IACL,GAAI,eAAe,OAAO,EAAE,YAAY,IAAI,CAAC;AAAA,IAC7C,GAAI,gBAAgB,OAAO,EAAE,aAAa,IAAI,CAAC;AAAA,EACjD;AACF;","names":[]}

package/package.json

@@ -1 +1,72 @@
-{"name":"@ai-sdk/workflow-harness","version":"0.0.0"}
+{
+  "name": "@ai-sdk/workflow-harness",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
+  "files": [
+    "dist/**/*",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "!src/**/__snapshots__",
+    "!src/**/__fixtures__",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@ai-sdk/harness": "1.0.0-beta.22"
+  },
+  "peerDependencies": {
+    "workflow": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.19",
+    "tsup": "^8.5.1",
+    "typescript": "5.8.3",
+    "workflow": "4.2.1",
+    "@vercel/ai-tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://ai-sdk.dev/docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercel/ai",
+    "directory": "packages/workflow-harness"
+  },
+  "bugs": {
+    "url": "https://github.com/vercel/ai/issues"
+  },
+  "keywords": [
+    "ai",
+    "harness",
+    "workflow",
+    "durable"
+  ],
+  "scripts": {
+    "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
+    "build:watch": "pnpm clean && tsup --watch",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "type-check": "tsc --build",
+    "test": "pnpm test:node",
+    "test:watch": "vitest --config vitest.node.config.js",
+    "test:node": "vitest --config vitest.node.config.js --run"
+  }
+}

package/src/harness-workflow-state.ts

@@ -0,0 +1,151 @@
+import type {
+  HarnessV1ContinueTurnState,
+  HarnessV1Prompt,
+  HarnessV1ResumeSessionState,
+} from '@ai-sdk/harness';
+
+export 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.
+ */
+export type HarnessWorkflowStatus =
+  | 'running'
+  | 'timed_out'
+  | 'awaiting_tool_approval'
+  | 'finished'
+  | 'failed';
+
+export interface HarnessWorkflowUsageSummary {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+}
+
+export interface HarnessWorkflowFinalResult {
+  readonly sessionId: string;
+  readonly finishReason: string;
+  readonly usage?: HarnessWorkflowUsageSummary;
+}
+
+export interface HarnessWorkflowSerializedChunk {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+export 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.
+ */
+export 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.
+ */
+export interface HarnessWorkflowInput {
+  prompt?: HarnessV1Prompt;
+  messages?: HarnessWorkflowModelMessage[];
+  sessionId: string;
+  resumeFrom?: HarnessV1ResumeSessionState;
+  continueFrom?: HarnessV1ContinueTurnState;
+}
+
+/** Initial state for one user turn (see {@link HarnessWorkflowInput}). */
+export function createHarnessWorkflowState(
+  input: HarnessWorkflowInput,
+): HarnessWorkflowState {
+  return {
+    sessionId: input.sessionId,
+    prompt: input.prompt ?? '',
+    ...(input.messages != null ? { messages: input.messages } : {}),
+    status: 'running',
+    ...(input.resumeFrom != null ? { resumeFrom: input.resumeFrom } : {}),
+    ...(input.continueFrom != null ? { continueFrom: input.continueFrom } : {}),
+  };
+}
+
+/**
+ * Collapse a terminal state into its result. Throws if the run failed; returns
+ * the captured `finalResult` when finished, or a best-effort result otherwise.
+ */
+export function finalizeHarnessWorkflow(
+  state: HarnessWorkflowState,
+): HarnessWorkflowFinalResult {
+  if (state.status === 'failed') {
+    throw new Error(state.error ?? 'harness workflow failed');
+  }
+  if (state.finalResult) {
+    return state.finalResult;
+  }
+  return { sessionId: state.sessionId, finishReason: 'unknown' };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  createHarnessWorkflowState,
+  finalizeHarnessWorkflow,
+  type HarnessWorkflowFinalResult,
+  type HarnessWorkflowInput,
+  type HarnessWorkflowModelMessage,
+  type HarnessWorkflowState,
+  type HarnessWorkflowStatus,
+  type HarnessWorkflowUsageSummary,
+} from './harness-workflow-state';
+export {
+  runHarnessAgentSlice,
+  type HarnessWorkflowAgent,
+  type HarnessWorkflowChunk,
+  type HarnessWorkflowStreamResult,
+  type RunHarnessAgentSliceOptions,
+} from './run-harness-agent-slice';