@ai-sdk/harness 1.0.0-canary.3 → 1.0.0-canary.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ai-sdk/harness
 
+## 1.0.0-canary.4
+
+### Patch Changes
+
+- 3d9a50c: feat(harness): implement harness adapters for Claude Code, Codex, Pi
+
 ## 1.0.0-canary.3
 
 ### Patch Changes

package/dist/agent/index.d.ts

@@ -62,7 +62,7 @@ interface HarnessV1NetworkSandboxSession extends Experimental_SandboxSession {
     /**
      * Stable identifier for the underlying sandbox resource. Used by the
      * harness session manager as the durable lookup key for cross-process
-     * resume — the framework persists this on the resume payload so a future
+     * resume — the framework persists this on lifecycle state so a future
      * process can call `HarnessV1SandboxProvider.resume?({ sessionId })` and
      * reach the same resource. Providers populate it from their native
      * identifier (Vercel: the sandbox name; just-bash: a UUID minted at
@@ -298,19 +298,10 @@ type HarnessV1PendingToolApproval = {
     readonly providerExecuted?: boolean;
     readonly nativeName?: string;
 };
-/**
- * Opaque payload returned by resumable session lifecycle methods and accepted
- * by a future `HarnessV1.doStart({ resumeFrom })` to resume the same
- * underlying session.
- *
- * The contents are entirely adapter-defined. Consumers (including
- * `HarnessAgent`) treat the value as opaque; adapters describe and validate
- * their own schemas via `HarnessV1.resumeStateSchema`.
- */
-type HarnessV1ResumeState = {
+type HarnessV1LifecycleStateBase = {
     /**
      * Identifier of the harness that produced this state. Used by adapters to
-     * refuse mismatched resume payloads.
+     * refuse mismatched payloads.
      */
     readonly harnessId: string;
     /**
@@ -324,11 +315,27 @@ type HarnessV1ResumeState = {
     readonly data: JSONValue;
     /**
      * Framework-owned pending approval records. These are intentionally outside
-     * adapter-defined `data` so callers can persist the entire resume payload
+     * adapter-defined `data` so callers can persist the entire lifecycle payload
      * without the harness framework owning storage.
      */
     readonly pendingToolApprovals?: readonly HarnessV1PendingToolApproval[];
 };
+/**
+ * Opaque payload returned by between-turn session lifecycle methods and
+ * accepted by a future `HarnessV1.doStart({ resumeFrom })` to resume the same
+ * underlying session before starting a new turn.
+ */
+type HarnessV1ResumeSessionState = HarnessV1LifecycleStateBase & {
+    readonly type: 'resume-session';
+};
+/**
+ * Opaque payload returned by `doSuspendTurn` and accepted by a future
+ * `HarnessV1.doStart({ continueFrom })` to reconnect to the same session before
+ * continuing the interrupted turn.
+ */
+type HarnessV1ContinueTurnState = HarnessV1LifecycleStateBase & {
+    readonly type: 'continue-turn';
+};
 
 /**
  * A self-contained instruction bundle the underlying runtime can load into
@@ -515,11 +522,17 @@ type HarnessV1StartOptions = {
      */
     readonly skills?: ReadonlyArray<HarnessV1Skill>;
     /**
-     * Optional resume payload returned by a prior session lifecycle method. When
-     * provided, the adapter should resume the existing session rather than create
-     * a fresh one.
+     * Optional resume payload returned by a prior between-turn session lifecycle
+     * method. When provided, the adapter should resume the existing session before
+     * accepting a new prompt.
+     */
+    readonly resumeFrom?: HarnessV1ResumeSessionState;
+    /**
+     * Optional continuation payload returned by `doSuspendTurn`. When provided,
+     * the adapter should resume the existing session in a shape ready for
+     * `doContinueTurn` rather than for a fresh prompt.
      */
-    readonly resumeFrom?: HarnessV1ResumeState;
+    readonly continueFrom?: HarnessV1ContinueTurnState;
     /**
      * Approval policy for built-in adapter-native tool use. Custom host-executed
      * tools are approved by the framework before results are submitted back to
@@ -631,8 +644,8 @@ type HarnessV1Session = {
      */
     readonly sessionId: string;
     /**
-     * Whether this session was created from a resume payload. Fresh sessions
-     * report `false`; resumed sessions report `true`.
+     * Whether this session was created from `resumeFrom` or `continueFrom`. Fresh
+     * sessions report `false`; resumed sessions report `true`.
      */
     readonly isResume: boolean;
     /**
@@ -664,7 +677,7 @@ type HarnessV1Session = {
      * Continue the in-flight turn **without a new user prompt**, returning the
      * same control surface as `doPromptTurn`. Used to keep consuming a turn that
      * was interrupted at a process boundary (the workflow slice loop), after the
-     * session itself has been resumed via `doStart({ resumeFrom })`:
+     * session itself has been resumed via `doStart({ continueFrom })`:
      *
      *  - When the runtime's turn is still live and reachable (bridge `attach` /
      *    `replay`), the adapter subscribes to its events and resolves `done` on
@@ -680,7 +693,7 @@ type HarnessV1Session = {
     doContinueTurn(options: HarnessV1ContinueTurnOptions): PromiseLike<HarnessV1PromptControl>;
     /**
      * Gracefully freeze the active turn **at a precise cursor while keeping the
-     * runtime alive**, returning the resume payload.
+     * runtime alive**, returning the continuation payload.
      *
      * This is the slice-boundary primitive. The adapter stops host-side
      * consumption of the in-flight turn without telling the runtime to stop:
@@ -697,24 +710,24 @@ type HarnessV1Session = {
      * this is for an active turn at a slice boundary rather than a between-turn
      * session handoff. Required on every adapter.
      */
-    doSuspendTurn(): PromiseLike<HarnessV1ResumeState>;
+    doSuspendTurn(): PromiseLike<HarnessV1ContinueTurnState>;
     /**
      * Detach from the underlying runtime without tearing it down, returning a
-     * payload the host can later pass to `HarnessV1.doStart({ resumeFrom })`
-     * to reconnect. After `doDetach`, no further methods on this session
-     * instance may be called.
+     * payload the host can later pass to
+     * `HarnessV1.doStart({ resumeFrom })` to reconnect before a new turn. After
+     * `doDetach`, no further methods on this session instance may be called.
      *
      * Required. Adapters that cannot keep a live runtime parked still return the
-     * best resume state they can while leaving the sandbox running.
+     * best resume session state they can while leaving the sandbox running.
      */
-    doDetach(): PromiseLike<HarnessV1ResumeState>;
+    doDetach(): PromiseLike<HarnessV1ResumeSessionState>;
     /**
      * Persist enough state to resume later, then stop the underlying runtime.
      * After `doStop`, no further methods on this session instance may be called.
      */
-    doStop(): PromiseLike<HarnessV1ResumeState>;
+    doStop(): PromiseLike<HarnessV1ResumeSessionState>;
     /**
-     * Stop the underlying runtime without returning resume state. After
+     * Stop the underlying runtime without returning lifecycle state. After
      * `doDestroy`, no further methods on this session instance may be called.
      */
     doDestroy(): PromiseLike<void>;
@@ -763,12 +776,12 @@ type HarnessV1<TBuiltinTools extends ToolSet = ToolSet> = {
      */
     readonly supportsBuiltinToolApprovals?: boolean;
     /**
-     * Optional schema for resume payloads returned by the session lifecycle.
-     * When present, the adapter promises that exported state validated by this
-     * schema can be re-imported in a future `doStart({ resumeFrom })` call.
-     * Hosts use this to persist and re-hydrate resume payloads safely.
+     * Optional schema for the adapter-defined `data` payload returned by session
+     * lifecycle methods. When present, the adapter promises that exported state
+     * validated by this schema can be re-imported in a future
+     * `doStart({ resumeFrom })` or `doStart({ continueFrom })` call.
      */
-    readonly resumeStateSchema?: FlexibleSchema<unknown>;
+    readonly lifecycleStateSchema?: FlexibleSchema<unknown>;
     /**
      * Optional bootstrap recipe. When defined, the harness session manager
      * computes a stable identity from the recipe, passes it (along with a
@@ -784,9 +797,9 @@ type HarnessV1<TBuiltinTools extends ToolSet = ToolSet> = {
         abortSignal?: AbortSignal;
     }) => PromiseLike<HarnessV1Bootstrap>;
     /**
-     * Start a fresh session (or resume via `resumeFrom`). The host then issues
-     * prompts against the returned session, ending with `doDetach`, `doStop`, or
-     * `doDestroy`.
+     * Start a fresh session, resume a parked session via `resumeFrom`, or resume
+     * an interrupted turn via `continueFrom`. The host then issues prompts against
+     * the returned session, ending with `doDetach`, `doStop`, or `doDestroy`.
      */
     doStart(options: HarnessV1StartOptions): PromiseLike<HarnessV1Session>;
 };
@@ -1261,8 +1274,8 @@ declare class HarnessAgentSession {
     private readonly pendingToolApprovals;
     private stopped;
     /**
-     * Whether this session was created from a resume payload. Captured at
-     * construction so it survives lifecycle cleanup.
+     * Whether this session was created from `resumeFrom` or `continueFrom`.
+     * Captured at construction so it survives lifecycle cleanup.
      */
     readonly isResume: boolean;
     constructor(options: {
@@ -1311,13 +1324,13 @@ declare class HarnessAgentSession {
      * The runtime and sandbox keep running; this local session handle becomes
      * unusable.
      */
-    detach(): Promise<HarnessV1ResumeState>;
+    detach(): Promise<HarnessV1ResumeSessionState>;
     /**
      * Persist enough state to resume later, then stop the runtime and sandbox.
      * Returns the resume state for a future
      * `agent.createSession({ sessionId, resumeFrom })` call.
      */
-    stop(): Promise<HarnessV1ResumeState>;
+    stop(): Promise<HarnessV1ResumeSessionState>;
     /**
      * Stop the runtime and discard resumability. The sandbox is destroyed when
      * the provider supports destruction; otherwise it is stopped.
@@ -1325,8 +1338,8 @@ declare class HarnessAgentSession {
     destroy(): Promise<void>;
     /**
      * Gracefully freeze the active turn at the slice boundary and return the
-     * resume payload, **leaving the sandbox/runtime running** so the next process
-     * can resume. Resolves once the in-flight `stream()`/`continueTurn()`
+     * continuation payload, **leaving the sandbox/runtime running** so the next
+     * process can continue. Resolves once the in-flight `stream()`/`continueTurn()`
      * has cleanly wound down at a precise cursor (see
      * {@link HarnessV1Session.doSuspendTurn}).
      *
@@ -1336,7 +1349,7 @@ declare class HarnessAgentSession {
      * released, because bridge-backed adapters may still have a live bridge on
      * that port.
      */
-    suspendTurn(): Promise<HarnessV1ResumeState>;
+    suspendTurn(): Promise<HarnessV1ContinueTurnState>;
     private getPendingToolApprovals;
     private withPendingToolApprovals;
     private endLocalHandle;
@@ -1381,7 +1394,9 @@ interface HarnessAgentCallExtensions {
  *  - **Cross-process resume.** `createSession({ sessionId, resumeFrom })`
  *    resumes from state previously returned by `session.detach()` or
  *    `session.stop()`. The framework validates `resumeFrom` against the
- *    harness's `resumeStateSchema` before handing it to the adapter.
+ *    harness's `lifecycleStateSchema` before handing it to the adapter.
+ *    `createSession({ sessionId, continueFrom })` resumes from state returned
+ *    by `session.suspendTurn()` before `continueTurn()`.
  *  - **Host tool execution.** User tools passed in `settings.tools` are
  *    executed on the host whenever the underlying runtime calls them;
  *    the result is fed back to the harness via `submitToolResult`.
@@ -1427,12 +1442,17 @@ declare class HarnessAgent<THarness extends HarnessV1<any> = HarnessV1, TUserToo
         sessionId?: string;
         /**
          * Resume payload returned by a prior `session.detach()` or
-         * `session.stop()`. Must be
-         * accompanied by the original `sessionId`; the framework
-         * validates it against `harness.resumeStateSchema` before handing
-         * it to the adapter.
+         * `session.stop()`. Must be accompanied by the original `sessionId`; the
+         * framework validates it against `harness.lifecycleStateSchema` before
+         * handing it to the adapter.
+         */
+        resumeFrom?: HarnessV1ResumeSessionState;
+        /**
+         * Continuation payload returned by a prior `session.suspendTurn()`. Must be
+         * accompanied by the original `sessionId`; the framework validates it before
+         * handing it to the adapter.
          */
-        resumeFrom?: HarnessV1ResumeState;
+        continueFrom?: HarnessV1ContinueTurnState;
         abortSignal?: AbortSignal;
     }): Promise<HarnessAgentSession>;
     generate(options: AgentCallParameters<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT> & HarnessAgentCallExtensions): Promise<GenerateTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, never>>;

package/dist/agent/index.js

@@ -71,34 +71,40 @@ function releaseBridgePort(options) {
   entry.leases.delete(options.sessionId);
 }
 
-// src/agent/internal/resume-state-validation.ts
+// src/agent/internal/lifecycle-state-validation.ts
 import { safeValidateTypes } from "@ai-sdk/provider-utils";
-async function validateResumeStateData(input) {
+async function validateLifecycleStateData(input) {
   const { harness, state } = input;
+  if (state.type !== input.expectedType) {
+    throw new HarnessError({
+      message: `Lifecycle state has unexpected type '${state.type}'; expected '${input.expectedType}'.`
+    });
+  }
   if (state.specificationVersion !== "harness-v1") {
     throw new HarnessError({
-      message: `Resume state has unexpected specificationVersion '${state.specificationVersion}'; expected 'harness-v1'.`
+      message: `Lifecycle state has unexpected specificationVersion '${state.specificationVersion}'; expected 'harness-v1'.`
     });
   }
   if (state.harnessId !== harness.harnessId) {
     throw new HarnessError({
-      message: `Resume state was produced by harness '${state.harnessId}' but this agent uses '${harness.harnessId}'.`
+      message: `Lifecycle state was produced by harness '${state.harnessId}' but this agent uses '${harness.harnessId}'.`
     });
   }
-  if (harness.resumeStateSchema == null) {
+  if (harness.lifecycleStateSchema == null) {
     return state;
   }
   const result = await safeValidateTypes({
     value: state.data,
-    schema: harness.resumeStateSchema
+    schema: harness.lifecycleStateSchema
   });
   if (!result.success) {
     throw new HarnessError({
-      message: `Resume state failed schema validation for harness '${harness.harnessId}': ${result.error.message}`,
+      message: `Lifecycle state failed schema validation for harness '${harness.harnessId}': ${result.error.message}`,
       cause: result.error
     });
   }
   return {
+    type: state.type,
     harnessId: state.harnessId,
     specificationVersion: state.specificationVersion,
     data: result.value,
@@ -1796,9 +1802,10 @@ var HarnessAgentSession = class {
     const session = this.underlyingSession;
     try {
       const raw = await session.doDetach();
-      const validated = await validateResumeStateData({
+      const validated = await validateLifecycleStateData({
         harness: this.harness,
-        state: raw
+        state: raw,
+        expectedType: "resume-session"
       });
       return this.withPendingToolApprovals(validated);
     } finally {
@@ -1820,9 +1827,10 @@ var HarnessAgentSession = class {
     const sandboxSession = this.getSandboxSession();
     try {
       const raw = await session.doStop();
-      const validated = await validateResumeStateData({
+      const validated = await validateLifecycleStateData({
         harness: this.harness,
-        state: raw
+        state: raw,
+        expectedType: "resume-session"
       });
       return this.withPendingToolApprovals(validated);
     } finally {
@@ -1852,8 +1860,8 @@ var HarnessAgentSession = class {
   }
   /**
    * Gracefully freeze the active turn at the slice boundary and return the
-   * resume payload, **leaving the sandbox/runtime running** so the next process
-   * can resume. Resolves once the in-flight `stream()`/`continueTurn()`
+   * continuation payload, **leaving the sandbox/runtime running** so the next
+   * process can continue. Resolves once the in-flight `stream()`/`continueTurn()`
    * has cleanly wound down at a precise cursor (see
    * {@link HarnessV1Session.doSuspendTurn}).
    *
@@ -1871,9 +1879,10 @@ var HarnessAgentSession = class {
     }
     const session = this.underlyingSession;
     const raw = await session.doSuspendTurn();
-    const validated = await validateResumeStateData({
+    const validated = await validateLifecycleStateData({
       harness: this.harness,
-      state: raw
+      state: raw,
+      expectedType: "continue-turn"
     });
     this.stopped = true;
     this.underlyingSession = void 0;
@@ -1887,6 +1896,7 @@ var HarnessAgentSession = class {
     const pendingToolApprovals = this.getPendingToolApprovals();
     if (pendingToolApprovals.length === 0) {
       return {
+        type: state.type,
         harnessId: state.harnessId,
         specificationVersion: state.specificationVersion,
         data: state.data
@@ -2159,17 +2169,32 @@ var HarnessAgent = class {
    * `session.destroy()`.
    */
   async createSession(options) {
-    var _a3;
+    var _a3, _b3;
     const sessionId = (_a3 = options == null ? void 0 : options.sessionId) != null ? _a3 : generateId5();
     const resumeFrom = options == null ? void 0 : options.resumeFrom;
+    const continueFrom = options == null ? void 0 : options.continueFrom;
     const abortSignal = options == null ? void 0 : options.abortSignal;
     const harness = this.settings.harness;
     const sandboxProvider = this.settings.sandbox;
+    if (resumeFrom != null && continueFrom != null) {
+      throw new Error(
+        "HarnessAgent.createSession: pass either `resumeFrom` or `continueFrom`, not both."
+      );
+    }
     let validatedResumeFrom;
     if (resumeFrom != null) {
-      validatedResumeFrom = await validateResumeStateData({
+      validatedResumeFrom = await validateLifecycleStateData({
+        harness,
+        state: resumeFrom,
+        expectedType: "resume-session"
+      });
+    }
+    let validatedContinueFrom;
+    if (continueFrom != null) {
+      validatedContinueFrom = await validateLifecycleStateData({
         harness,
-        state: resumeFrom
+        state: continueFrom,
+        expectedType: "continue-turn"
       });
     }
     let recipe;
@@ -2181,7 +2206,7 @@ var HarnessAgent = class {
     const acquiredSandboxSession = await this._acquireSandbox({
       sandboxProvider,
       sessionId,
-      isResume: validatedResumeFrom != null,
+      isResume: validatedResumeFrom != null || validatedContinueFrom != null,
       recipe,
       identity,
       abortSignal
@@ -2228,6 +2253,7 @@ var HarnessAgent = class {
         sessionId,
         skills: this.settings.skills,
         resumeFrom: validatedResumeFrom,
+        continueFrom: validatedContinueFrom,
         permissionMode: this.permissionMode,
         abortSignal,
         observability: buildObservability({ settings: this.settings })
@@ -2246,7 +2272,7 @@ var HarnessAgent = class {
         leasedBridgePort,
         sessionWorkDir,
         toolApproval: this.settings.toolApproval,
-        pendingToolApprovals: validatedResumeFrom == null ? void 0 : validatedResumeFrom.pendingToolApprovals
+        pendingToolApprovals: (_b3 = validatedResumeFrom == null ? void 0 : validatedResumeFrom.pendingToolApprovals) != null ? _b3 : validatedContinueFrom == null ? void 0 : validatedContinueFrom.pendingToolApprovals
       });
     } catch (error) {
       await cleanupAfterStartFailure({