@pstdio/pocketcoder-sdk 0.3.1 → 0.5.0

package/README.md

@@ -42,3 +42,57 @@ metadata-only terminal audit history.
 Use `client.raw(path, init)` for endpoints not yet represented by a typed
 resource client. API failures throw `PocketCoderError`; expired or deleted
 conversation history throws the more specific `ConversationGoneError`.
+
+## Resolve one user turn after preservation
+
+Create one long-lived `WorkspaceTurnResolver` in a trusted backend. Call it
+only when handling a user turn. A ready workspace is returned unchanged. A
+preserved workspace is resumed through your callback, checked against the
+source checkpoint, and returned only after it becomes ready.
+
+```ts
+import {
+  PocketCoderClient,
+  WorkspaceTurnResolver,
+} from "@pstdio/pocketcoder-sdk";
+
+const client = new PocketCoderClient({
+  baseUrl: process.env.POCKETCODER_URL!,
+  apiKey: process.env.POCKETCODER_KEY!,
+});
+
+const resolver = new WorkspaceTurnResolver({
+  client,
+  resumeWorkspace: async ({ source, attemptId, signal }) => {
+    // Mint fresh workspace-scoped input. It must expire with the new workspace.
+    const launchInput = await issueWorkspaceBootstrap({ signal });
+    const result = await client.workspaces.resume(
+      source.id,
+      {
+        external_id: `turn-${attemptId}`,
+        launch_input: launchInput,
+      },
+      attemptId,
+      { signal },
+    );
+    return result.workspace;
+  },
+});
+
+export async function handleTurn(sourceWorkspaceId: string, prompt: string) {
+  const { workspace } = await resolver.resolve(sourceWorkspaceId);
+  await client.agent.sendMessage(workspace.id, { content: prompt });
+  return { workspace_id: workspace.id };
+}
+```
+
+The key needs `workspaces:read`; a callback that calls `resume()` also needs
+`workspaces:restore`. Prompt relay and attachments need `services:relay` and
+`attachments:write` respectively.
+
+The resolver stores no A-to-B mapping. Return the resolved id through your
+normal request or session state if a later request needs it. Canceling one
+caller stops that caller's wait. It does not roll back a resume request already
+accepted by the server, and another caller may join the same in-memory attempt.
+Lifecycle failures use fixed messages and never expose callback errors or
+launch input.

package/dist/index.d.ts

@@ -98,6 +98,8 @@ type ErrorCode = keyof typeof ERROR_CODES;
 //#region ../contracts/src/workspace.d.ts
 declare const WORKSPACE_STATES: readonly ["queued", "provisioning", "connected", "ready", "preserving", "terminating", "succeeded", "failed", "canceled", "expired", "preserved"];
 type WorkspaceState = (typeof WORKSPACE_STATES)[number];
+declare const AGENT_STATES: readonly ["unknown", "running", "stable"];
+type AgentState = (typeof AGENT_STATES)[number];
 declare const WorkspaceCreateRequestSchema: z.ZodObject<{
   external_id: z.ZodString;
   template: z.ZodObject<{
@@ -483,33 +485,6 @@ declare class AdministrationApi {
   }>;
 }
 //#endregion
-//#region src/attachments.d.ts
-type UploadBody = NonNullable<RequestInit["body"]>;
-interface AttachmentUploadInput {
-  id?: string;
-  name: string;
-  mediaType?: string;
-  body: UploadBody;
-  sizeBytes: number;
-  signal?: AbortSignal;
-  onProgress?: (uploadedBytes: number, totalBytes: number) => void;
-}
-interface AgentMessageInput {
-  content: string;
-  attachmentIds?: string[];
-  signal?: AbortSignal;
-}
-declare class AttachmentsApi {
-  private readonly transport;
-  constructor(transport: PocketCoderTransport);
-  upload(workspaceId: string, input: AttachmentUploadInput): Promise<AttachmentDescriptor>;
-}
-declare class AgentApi {
-  private readonly transport;
-  constructor(transport: PocketCoderTransport);
-  sendMessage(workspaceId: string, input: AgentMessageInput): Promise<void>;
-}
-//#endregion
 //#region src/common.d.ts
 interface Page<T> {
   items: T[];
@@ -520,256 +495,6 @@ interface CursorListQuery {
   cursor?: string;
 }
 //#endregion
-//#region src/checkpoints.d.ts
-declare class CheckpointsApi {
-  private readonly transport;
-  constructor(transport: PocketCoderTransport);
-  list(workspaceId: string, query?: CursorListQuery & {
-    state?: CheckpointState;
-  }, options?: RequestOptions): Promise<Page<{
-    id: string;
-    workspace_id: string;
-    state: "deleted" | "creating" | "ready" | "failed" | "deleting";
-    reason_code: string | null;
-    template: {
-      name: string;
-      version: string;
-      digest: string;
-    };
-    manifest_digest: string | null;
-    logical_bytes: number | null;
-    stored_bytes: number | null;
-    file_count: number | null;
-    mounts: string[];
-    conversation_restore: "unknown" | "supported" | "filesystem_only";
-    label: string | null;
-    created_at: string;
-    ready_at: string | null;
-    expires_at: string | null;
-  }>>;
-  get(id: string, options?: RequestOptions): Promise<{
-    id: string;
-    workspace_id: string;
-    state: "deleted" | "creating" | "ready" | "failed" | "deleting";
-    reason_code: string | null;
-    template: {
-      name: string;
-      version: string;
-      digest: string;
-    };
-    manifest_digest: string | null;
-    logical_bytes: number | null;
-    stored_bytes: number | null;
-    file_count: number | null;
-    mounts: string[];
-    conversation_restore: "unknown" | "supported" | "filesystem_only";
-    label: string | null;
-    created_at: string;
-    ready_at: string | null;
-    expires_at: string | null;
-  }>;
-  verify(id: string, key: string, options?: RequestOptions): Promise<{
-    id: string;
-    kind: "preserve" | "restore" | "verify" | "delete";
-    state: "failed" | "pending" | "running" | "succeeded";
-    workspace_id: string | null;
-    checkpoint_id: string | null;
-    result_workspace_id: string | null;
-    reason_code: string | null;
-    created_at: string;
-    updated_at: string;
-    completed_at: string | null;
-  }>;
-  delete(id: string, key: string, options?: RequestOptions): Promise<{
-    id: string;
-    kind: "preserve" | "restore" | "verify" | "delete";
-    state: "failed" | "pending" | "running" | "succeeded";
-    workspace_id: string | null;
-    checkpoint_id: string | null;
-    result_workspace_id: string | null;
-    reason_code: string | null;
-    created_at: string;
-    updated_at: string;
-    completed_at: string | null;
-  }>;
-  restore(id: string, input: RestoreRequest, key: string, options?: RequestOptions): Promise<{
-    workspace: {
-      id: string;
-      external_id: string;
-      template: {
-        name: string;
-        version: string;
-        digest: string;
-      };
-      state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
-      reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
-      agent_state: "unknown" | "running" | "stable";
-      change_cursor: number;
-      provider_kind: string | null;
-      provisioning_mode: "cold" | "warm" | null;
-      network: {
-        state: "ready" | "disabled" | "starting" | "degraded";
-      };
-      health: Record<string, string>;
-      created_at: string;
-      updated_at: string;
-      connected_at: string | null;
-      ready_at: string | null;
-      deadline_at: string;
-      terminal_at: string | null;
-      metadata: Record<string, string>;
-      origin_workspace_id: string | null;
-      restored_from_checkpoint_id: string | null;
-      source: {
-        kind: "git";
-        repository: string;
-        requested_revision: string;
-        resolved_commit: string | null;
-      } | null;
-      persistence: {
-        enabled: boolean;
-        conversation_restore: "unknown" | "supported" | "filesystem_only";
-        conversation_resume: {
-          status: "unknown" | "supported" | "unsupported";
-          reason: "filesystem_only" | "capability_unknown" | null;
-        };
-        latest_checkpoint_id: string | null;
-      };
-      outputs: Record<string, unknown>;
-      failure: {
-        reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed";
-        log_tail: string;
-        log_tail_truncated: boolean;
-        last_log_seq: number | null;
-      } | null;
-    };
-    operation: {
-      id: string;
-      kind: "preserve" | "restore" | "verify" | "delete";
-      state: "failed" | "pending" | "running" | "succeeded";
-      workspace_id: string | null;
-      checkpoint_id: string | null;
-      result_workspace_id: string | null;
-      reason_code: string | null;
-      created_at: string;
-      updated_at: string;
-      completed_at: string | null;
-    };
-  }>;
-  private operationRequest;
-}
-declare class OperationsApi {
-  private readonly transport;
-  constructor(transport: PocketCoderTransport);
-  get(id: string, options?: RequestOptions): Promise<{
-    id: string;
-    kind: "preserve" | "restore" | "verify" | "delete";
-    state: "failed" | "pending" | "running" | "succeeded";
-    workspace_id: string | null;
-    checkpoint_id: string | null;
-    result_workspace_id: string | null;
-    reason_code: string | null;
-    created_at: string;
-    updated_at: string;
-    completed_at: string | null;
-  }>;
-}
-//#endregion
-//#region src/conversations.d.ts
-type ConversationMessage = ConversationMessageResource;
-type ConversationPage = Page<ConversationMessageResource>;
-declare class ConversationsApi {
-  private readonly transport;
-  constructor(transport: PocketCoderTransport);
-  list(id: string, query?: CursorListQuery, options?: RequestOptions): Promise<Page<{
-    message_id: string;
-    role: "user" | "assistant" | "system" | "tool";
-    content: string;
-    occurred_at: string;
-    metadata: Record<string, string>;
-    seq: number;
-  }>>;
-}
-//#endregion
-//#region src/diagnostics.d.ts
-declare class WorkspaceCursorApi<T> {
-  private readonly transport;
-  private readonly resource;
-  private readonly schema;
-  constructor(transport: PocketCoderTransport, resource: string, schema: z.ZodType<{
-    items: T[];
-    next_cursor: string | null;
-  }>);
-  list(workspaceId: string, query?: CursorListQuery, options?: RequestOptions): Promise<Page<T>>;
-}
-declare class LogsApi extends WorkspaceCursorApi<LogChunk> {
-  constructor(transport: PocketCoderTransport);
-}
-declare class NetworkEventsApi extends WorkspaceCursorApi<NetworkEvent> {
-  constructor(transport: PocketCoderTransport);
-}
-declare class OutputsApi extends WorkspaceCursorApi<OutputResource> {
-  constructor(transport: PocketCoderTransport);
-}
-//#endregion
-//#region src/templates.d.ts
-type TemplateSummary = TemplateListItem;
-declare class TemplatesApi {
-  private readonly transport;
-  constructor(transport: PocketCoderTransport);
-  page(query?: CursorListQuery, options?: RequestOptions): Promise<Page<{
-    name: string;
-    version: string;
-    digest: string;
-    status: "active" | "available" | "retired";
-    description?: string | undefined;
-  }>>;
-  list(options?: RequestOptions): Promise<{
-    name: string;
-    version: string;
-    digest: string;
-    status: "active" | "available" | "retired";
-    description?: string | undefined;
-  }[]>;
-}
-//#endregion
-//#region src/terminals.d.ts
-interface TerminalConnectOptions {
-  sessionId?: string;
-}
-declare class TerminalConnection {
-  readonly socket: WebSocket;
-  private readonly messageListeners;
-  private readonly openListeners;
-  private readonly closeListeners;
-  private readonly errorListeners;
-  private readonly pendingMessages;
-  private opened;
-  private closedEvent;
-  private errored;
-  constructor(socket: WebSocket);
-  onMessage(listener: (message: ServerTerminalMessage) => void): () => void;
-  onOpen(listener: () => void): () => void;
-  onClose(listener: (event: CloseEvent) => void): () => void;
-  onError(listener: () => void): () => void;
-  sendInput(value: Uint8Array | string): void;
-  resize(rows: number, cols: number): void;
-  close(code?: number, reason?: string): void;
-  private handleMessage;
-}
-declare class TerminalsApi {
-  private readonly transport;
-  constructor(transport: PocketCoderTransport);
-  connect(workspaceId: string, options?: TerminalConnectOptions): TerminalConnection;
-  list(workspaceId: string, query?: {
-    cursor?: string;
-    limit?: number;
-  }, options?: RequestOptions): Promise<{
-    items: TerminalSession[];
-    nextCursor: string | null;
-  }>;
-}
-//#endregion
 //#region src/workspaces.d.ts
 interface WorkspaceCreateInput {
   externalId: string;
@@ -800,7 +525,7 @@ declare class WorkspacesApi {
       version: string;
       digest: string;
     };
-    state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+    state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
     reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
     agent_state: "unknown" | "running" | "stable";
     change_cursor: number;
@@ -850,7 +575,7 @@ declare class WorkspacesApi {
       version: string;
       digest: string;
     };
-    state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+    state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
     reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
     agent_state: "unknown" | "running" | "stable";
     change_cursor: number;
@@ -900,7 +625,7 @@ declare class WorkspacesApi {
       version: string;
       digest: string;
     };
-    state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+    state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
     reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
     agent_state: "unknown" | "running" | "stable";
     change_cursor: number;
@@ -950,7 +675,7 @@ declare class WorkspacesApi {
       version: string;
       digest: string;
     };
-    state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+    state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
     reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
     agent_state: "unknown" | "running" | "stable";
     change_cursor: number;
@@ -1000,7 +725,7 @@ declare class WorkspacesApi {
       version: string;
       digest: string;
     };
-    state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+    state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
     reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
     agent_state: "unknown" | "running" | "stable";
     change_cursor: number;
@@ -1053,7 +778,7 @@ declare class WorkspacesApi {
         version: string;
         digest: string;
       };
-      state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+      state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
       reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
       agent_state: "unknown" | "running" | "stable";
       change_cursor: number;
@@ -1106,7 +831,57 @@ declare class WorkspacesApi {
       version: string;
       digest: string;
     };
-    state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+    state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
+    reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
+    agent_state: "unknown" | "running" | "stable";
+    change_cursor: number;
+    provider_kind: string | null;
+    provisioning_mode: "cold" | "warm" | null;
+    network: {
+      state: "ready" | "disabled" | "starting" | "degraded";
+    };
+    health: Record<string, string>;
+    created_at: string;
+    updated_at: string;
+    connected_at: string | null;
+    ready_at: string | null;
+    deadline_at: string;
+    terminal_at: string | null;
+    metadata: Record<string, string>;
+    origin_workspace_id: string | null;
+    restored_from_checkpoint_id: string | null;
+    source: {
+      kind: "git";
+      repository: string;
+      requested_revision: string;
+      resolved_commit: string | null;
+    } | null;
+    persistence: {
+      enabled: boolean;
+      conversation_restore: "unknown" | "supported" | "filesystem_only";
+      conversation_resume: {
+        status: "unknown" | "supported" | "unsupported";
+        reason: "filesystem_only" | "capability_unknown" | null;
+      };
+      latest_checkpoint_id: string | null;
+    };
+    outputs: Record<string, unknown>;
+    failure: {
+      reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed";
+      log_tail: string;
+      log_tail_truncated: boolean;
+      last_log_seq: number | null;
+    } | null;
+  }>;
+  waitForAgentInput(id: string, timeoutMs: number, options?: RequestOptions): Promise<{
+    id: string;
+    external_id: string;
+    template: {
+      name: string;
+      version: string;
+      digest: string;
+    };
+    state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
     reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
     agent_state: "unknown" | "running" | "stable";
     change_cursor: number;
@@ -1148,7 +923,92 @@ declare class WorkspacesApi {
       last_log_seq: number | null;
     } | null;
   }>;
-  preserve(id: string, input: PreserveRequest, key: string, options?: RequestOptions): Promise<{
+  preserve(id: string, input: PreserveRequest, key: string, options?: RequestOptions): Promise<{
+    workspace: {
+      id: string;
+      external_id: string;
+      template: {
+        name: string;
+        version: string;
+        digest: string;
+      };
+      state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
+      reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
+      agent_state: "unknown" | "running" | "stable";
+      change_cursor: number;
+      provider_kind: string | null;
+      provisioning_mode: "cold" | "warm" | null;
+      network: {
+        state: "ready" | "disabled" | "starting" | "degraded";
+      };
+      health: Record<string, string>;
+      created_at: string;
+      updated_at: string;
+      connected_at: string | null;
+      ready_at: string | null;
+      deadline_at: string;
+      terminal_at: string | null;
+      metadata: Record<string, string>;
+      origin_workspace_id: string | null;
+      restored_from_checkpoint_id: string | null;
+      source: {
+        kind: "git";
+        repository: string;
+        requested_revision: string;
+        resolved_commit: string | null;
+      } | null;
+      persistence: {
+        enabled: boolean;
+        conversation_restore: "unknown" | "supported" | "filesystem_only";
+        conversation_resume: {
+          status: "unknown" | "supported" | "unsupported";
+          reason: "filesystem_only" | "capability_unknown" | null;
+        };
+        latest_checkpoint_id: string | null;
+      };
+      outputs: Record<string, unknown>;
+      failure: {
+        reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed";
+        log_tail: string;
+        log_tail_truncated: boolean;
+        last_log_seq: number | null;
+      } | null;
+    };
+    checkpoint: {
+      id: string;
+      workspace_id: string;
+      state: "ready" | "failed" | "creating" | "deleting" | "deleted";
+      reason_code: string | null;
+      template: {
+        name: string;
+        version: string;
+        digest: string;
+      };
+      manifest_digest: string | null;
+      logical_bytes: number | null;
+      stored_bytes: number | null;
+      file_count: number | null;
+      mounts: string[];
+      conversation_restore: "unknown" | "supported" | "filesystem_only";
+      label: string | null;
+      created_at: string;
+      ready_at: string | null;
+      expires_at: string | null;
+    };
+    operation: {
+      id: string;
+      kind: "preserve" | "restore" | "verify" | "delete";
+      state: "succeeded" | "failed" | "running" | "pending";
+      workspace_id: string | null;
+      checkpoint_id: string | null;
+      result_workspace_id: string | null;
+      reason_code: string | null;
+      created_at: string;
+      updated_at: string;
+      completed_at: string | null;
+    };
+  }>;
+  recreate(id: string, input: RestoreRequest, key: string, options?: RequestOptions): Promise<{
     workspace: {
       id: string;
       external_id: string;
@@ -1157,7 +1017,7 @@ declare class WorkspacesApi {
         version: string;
         digest: string;
       };
-      state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+      state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
       reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
       agent_state: "unknown" | "running" | "stable";
       change_cursor: number;
@@ -1199,31 +1059,10 @@ declare class WorkspacesApi {
         last_log_seq: number | null;
       } | null;
     };
-    checkpoint: {
-      id: string;
-      workspace_id: string;
-      state: "deleted" | "creating" | "ready" | "failed" | "deleting";
-      reason_code: string | null;
-      template: {
-        name: string;
-        version: string;
-        digest: string;
-      };
-      manifest_digest: string | null;
-      logical_bytes: number | null;
-      stored_bytes: number | null;
-      file_count: number | null;
-      mounts: string[];
-      conversation_restore: "unknown" | "supported" | "filesystem_only";
-      label: string | null;
-      created_at: string;
-      ready_at: string | null;
-      expires_at: string | null;
-    };
     operation: {
       id: string;
       kind: "preserve" | "restore" | "verify" | "delete";
-      state: "failed" | "pending" | "running" | "succeeded";
+      state: "succeeded" | "failed" | "running" | "pending";
       workspace_id: string | null;
       checkpoint_id: string | null;
       result_workspace_id: string | null;
@@ -1233,7 +1072,7 @@ declare class WorkspacesApi {
       completed_at: string | null;
     };
   }>;
-  recreate(id: string, input: RestoreRequest, key: string, options?: RequestOptions): Promise<{
+  resume(id: string, input: RestoreRequest, key: string, options?: RequestOptions): Promise<{
     workspace: {
       id: string;
       external_id: string;
@@ -1242,7 +1081,7 @@ declare class WorkspacesApi {
         version: string;
         digest: string;
       };
-      state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+      state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
       reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
       agent_state: "unknown" | "running" | "stable";
       change_cursor: number;
@@ -1287,7 +1126,7 @@ declare class WorkspacesApi {
     operation: {
       id: string;
       kind: "preserve" | "restore" | "verify" | "delete";
-      state: "failed" | "pending" | "running" | "succeeded";
+      state: "succeeded" | "failed" | "running" | "pending";
       workspace_id: string | null;
       checkpoint_id: string | null;
       result_workspace_id: string | null;
@@ -1296,8 +1135,118 @@ declare class WorkspacesApi {
       updated_at: string;
       completed_at: string | null;
     };
+    resume: {
+      status: "supported";
+      reason: null;
+      source_workspace_id: string;
+      checkpoint_id: string;
+    };
   }>;
-  resume(id: string, input: RestoreRequest, key: string, options?: RequestOptions): Promise<{
+  private jsonOperation;
+}
+//#endregion
+//#region src/attachments.d.ts
+type UploadBody = NonNullable<RequestInit["body"]>;
+interface AttachmentUploadInput {
+  id?: string;
+  name: string;
+  mediaType?: string;
+  body: UploadBody;
+  sizeBytes: number;
+  signal?: AbortSignal;
+  onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+}
+interface AgentMessageInput {
+  content: string;
+  attachmentIds?: string[];
+  signal?: AbortSignal;
+  readyTimeoutMs?: number;
+}
+declare class AttachmentsApi {
+  private readonly transport;
+  constructor(transport: PocketCoderTransport);
+  upload(workspaceId: string, input: AttachmentUploadInput): Promise<AttachmentDescriptor>;
+}
+declare class AgentApi {
+  private readonly transport;
+  private readonly workspaces;
+  constructor(transport: PocketCoderTransport, workspaces: WorkspacesApi);
+  sendMessage(workspaceId: string, input: AgentMessageInput): Promise<void>;
+}
+//#endregion
+//#region src/checkpoints.d.ts
+declare class CheckpointsApi {
+  private readonly transport;
+  constructor(transport: PocketCoderTransport);
+  list(workspaceId: string, query?: CursorListQuery & {
+    state?: CheckpointState;
+  }, options?: RequestOptions): Promise<Page<{
+    id: string;
+    workspace_id: string;
+    state: "ready" | "failed" | "creating" | "deleting" | "deleted";
+    reason_code: string | null;
+    template: {
+      name: string;
+      version: string;
+      digest: string;
+    };
+    manifest_digest: string | null;
+    logical_bytes: number | null;
+    stored_bytes: number | null;
+    file_count: number | null;
+    mounts: string[];
+    conversation_restore: "unknown" | "supported" | "filesystem_only";
+    label: string | null;
+    created_at: string;
+    ready_at: string | null;
+    expires_at: string | null;
+  }>>;
+  get(id: string, options?: RequestOptions): Promise<{
+    id: string;
+    workspace_id: string;
+    state: "ready" | "failed" | "creating" | "deleting" | "deleted";
+    reason_code: string | null;
+    template: {
+      name: string;
+      version: string;
+      digest: string;
+    };
+    manifest_digest: string | null;
+    logical_bytes: number | null;
+    stored_bytes: number | null;
+    file_count: number | null;
+    mounts: string[];
+    conversation_restore: "unknown" | "supported" | "filesystem_only";
+    label: string | null;
+    created_at: string;
+    ready_at: string | null;
+    expires_at: string | null;
+  }>;
+  verify(id: string, key: string, options?: RequestOptions): Promise<{
+    id: string;
+    kind: "preserve" | "restore" | "verify" | "delete";
+    state: "succeeded" | "failed" | "running" | "pending";
+    workspace_id: string | null;
+    checkpoint_id: string | null;
+    result_workspace_id: string | null;
+    reason_code: string | null;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+  }>;
+  delete(id: string, key: string, options?: RequestOptions): Promise<{
+    id: string;
+    kind: "preserve" | "restore" | "verify" | "delete";
+    state: "succeeded" | "failed" | "running" | "pending";
+    workspace_id: string | null;
+    checkpoint_id: string | null;
+    result_workspace_id: string | null;
+    reason_code: string | null;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+  }>;
+  restore(id: string, input: RestoreRequest, key: string, options?: RequestOptions): Promise<{
     workspace: {
       id: string;
       external_id: string;
@@ -1306,7 +1255,7 @@ declare class WorkspacesApi {
         version: string;
         digest: string;
       };
-      state: "ready" | "failed" | "succeeded" | "queued" | "provisioning" | "connected" | "preserving" | "terminating" | "canceled" | "expired" | "preserved";
+      state: "queued" | "provisioning" | "connected" | "ready" | "preserving" | "terminating" | "succeeded" | "failed" | "canceled" | "expired" | "preserved";
       reason_code: "child_exit_success" | "child_exit_failure" | "setup_failed" | "bootstrap_failed" | "registration_timeout" | "health_failed" | "child_crash" | "provider_lost" | "disconnect_timeout" | "canceled_by_caller" | "deadline_expired" | "idle_expired" | "queue_timeout" | "launch_failed" | "preserve_requested" | "preserved_by_policy" | "checkpoint_created" | "checkpoint_failed" | "checkpoint_corrupt" | "checkpoint_quota_exceeded" | "checkpoint_storage_lost" | "restore_requested" | "restore_failed" | "image_unavailable" | "source_resolution_failed" | "secret_resolution_failed" | "operation_conflict" | "network_policy_failed" | null;
       agent_state: "unknown" | "running" | "stable";
       change_cursor: number;
@@ -1351,7 +1300,7 @@ declare class WorkspacesApi {
     operation: {
       id: string;
       kind: "preserve" | "restore" | "verify" | "delete";
-      state: "failed" | "pending" | "running" | "succeeded";
+      state: "succeeded" | "failed" | "running" | "pending";
       workspace_id: string | null;
       checkpoint_id: string | null;
       result_workspace_id: string | null;
@@ -1360,14 +1309,119 @@ declare class WorkspacesApi {
       updated_at: string;
       completed_at: string | null;
     };
-    resume: {
-      status: "supported";
-      reason: null;
-      source_workspace_id: string;
-      checkpoint_id: string;
-    };
   }>;
-  private jsonOperation;
+  private operationRequest;
+}
+declare class OperationsApi {
+  private readonly transport;
+  constructor(transport: PocketCoderTransport);
+  get(id: string, options?: RequestOptions): Promise<{
+    id: string;
+    kind: "preserve" | "restore" | "verify" | "delete";
+    state: "succeeded" | "failed" | "running" | "pending";
+    workspace_id: string | null;
+    checkpoint_id: string | null;
+    result_workspace_id: string | null;
+    reason_code: string | null;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+  }>;
+}
+//#endregion
+//#region src/conversations.d.ts
+type ConversationMessage = ConversationMessageResource;
+type ConversationPage = Page<ConversationMessageResource>;
+declare class ConversationsApi {
+  private readonly transport;
+  constructor(transport: PocketCoderTransport);
+  list(id: string, query?: CursorListQuery, options?: RequestOptions): Promise<Page<{
+    message_id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    occurred_at: string;
+    metadata: Record<string, string>;
+    seq: number;
+  }>>;
+}
+//#endregion
+//#region src/diagnostics.d.ts
+declare class WorkspaceCursorApi<T> {
+  private readonly transport;
+  private readonly resource;
+  private readonly schema;
+  constructor(transport: PocketCoderTransport, resource: string, schema: z.ZodType<{
+    items: T[];
+    next_cursor: string | null;
+  }>);
+  list(workspaceId: string, query?: CursorListQuery, options?: RequestOptions): Promise<Page<T>>;
+}
+declare class LogsApi extends WorkspaceCursorApi<LogChunk> {
+  constructor(transport: PocketCoderTransport);
+}
+declare class NetworkEventsApi extends WorkspaceCursorApi<NetworkEvent> {
+  constructor(transport: PocketCoderTransport);
+}
+declare class OutputsApi extends WorkspaceCursorApi<OutputResource> {
+  constructor(transport: PocketCoderTransport);
+}
+//#endregion
+//#region src/templates.d.ts
+type TemplateSummary = TemplateListItem;
+declare class TemplatesApi {
+  private readonly transport;
+  constructor(transport: PocketCoderTransport);
+  page(query?: CursorListQuery, options?: RequestOptions): Promise<Page<{
+    name: string;
+    version: string;
+    digest: string;
+    status: "active" | "available" | "retired";
+    description?: string | undefined;
+  }>>;
+  list(options?: RequestOptions): Promise<{
+    name: string;
+    version: string;
+    digest: string;
+    status: "active" | "available" | "retired";
+    description?: string | undefined;
+  }[]>;
+}
+//#endregion
+//#region src/terminals.d.ts
+interface TerminalConnectOptions {
+  sessionId?: string;
+}
+declare class TerminalConnection {
+  readonly socket: WebSocket;
+  private readonly messageListeners;
+  private readonly openListeners;
+  private readonly closeListeners;
+  private readonly errorListeners;
+  private readonly pendingMessages;
+  private opened;
+  private closedEvent;
+  private errored;
+  constructor(socket: WebSocket);
+  onMessage(listener: (message: ServerTerminalMessage) => void): () => void;
+  onOpen(listener: () => void): () => void;
+  onClose(listener: (event: CloseEvent) => void): () => void;
+  onError(listener: () => void): () => void;
+  sendInput(value: Uint8Array | string): void;
+  resize(rows: number, cols: number): void;
+  close(code?: number, reason?: string): void;
+  private handleMessage;
+}
+declare class TerminalsApi {
+  private readonly transport;
+  constructor(transport: PocketCoderTransport);
+  connect(workspaceId: string, options?: TerminalConnectOptions): TerminalConnection;
+  list(workspaceId: string, query?: {
+    cursor?: string;
+    limit?: number;
+  }, options?: RequestOptions): Promise<{
+    items: TerminalSession[];
+    nextCursor: string | null;
+  }>;
 }
 //#endregion
 //#region src/client.d.ts
@@ -1413,5 +1467,48 @@ declare class WorkspaceTerminalError extends Error {
   readonly workspace: WorkspaceResource;
   constructor(workspace: WorkspaceResource);
 }
+declare class AgentNotReadyError extends Error {
+  readonly workspaceId: string;
+  readonly agentState: AgentState;
+  constructor(workspaceId: string, agentState: AgentState, timeoutMs: number);
+}
+declare function isPocketCoderErrorCode(value: unknown): value is ErrorCode;
+//#endregion
+//#region src/workspace-turn-resolver.d.ts
+type WorkspaceTurnResolutionErrorCode = "not_resumable" | "resume_handler_missing" | "resume_failed" | "invalid_resumed_workspace" | "readiness_failed";
+declare class WorkspaceTurnResolutionError extends Error {
+  readonly code: WorkspaceTurnResolutionErrorCode;
+  constructor(code: WorkspaceTurnResolutionErrorCode, cause?: unknown);
+}
+interface ResumeWorkspaceContext {
+  source: WorkspaceResource;
+  attemptId: string;
+  signal: AbortSignal;
+}
+interface WorkspaceTurnResolverOptions {
+  client: PocketCoderClient;
+  resumeWorkspace?: (context: ResumeWorkspaceContext) => Promise<WorkspaceResource>;
+  resumeTimeoutMs?: number;
+}
+interface ResolveWorkspaceTurnOptions {
+  signal?: AbortSignal;
+}
+interface ResolvedWorkspaceTurn {
+  workspace: WorkspaceResource;
+  resumed: boolean;
+}
+declare class WorkspaceTurnResolver {
+  private readonly client;
+  private readonly resumeWorkspace;
+  private readonly resumeTimeoutMs;
+  private readonly attempts;
+  constructor(options: WorkspaceTurnResolverOptions);
+  resolve(sourceWorkspaceId: string, options?: ResolveWorkspaceTurnOptions): Promise<ResolvedWorkspaceTurn>;
+  private start;
+  private run;
+  private waitForPreserved;
+  private assertResumable;
+  private assertLineage;
+}
 //#endregion
-export { AdministrationApi, AgentApi, type AgentMessageInput, type AttachmentDescriptor, type AttachmentUploadInput, AttachmentsApi, type CheckpointResource, type CheckpointState, CheckpointsApi, type ClientErrorCode, ConversationGoneError, type ConversationMessage, type ConversationPage, ConversationsApi, type CursorListQuery, type LogChunk, LogsApi, type NetworkEvent, NetworkEventsApi, type OperationKind, type OperationResource, type OperationState, OperationsApi, type OutputResource, OutputsApi, type Page, PocketCoderClient, type PocketCoderClientConfig, PocketCoderError, type PreserveRequest, type RequestOptions, type RestoreRequest, type ServerTerminalMessage, type StorageState, TERMINAL_WORKSPACE_STATES, type TemplateSummary, TemplatesApi, type TerminalConnectOptions, TerminalConnection, type TerminalSession, TerminalsApi, type WebSocketFactory, type WorkspaceCreateInput, type WorkspaceListQuery, type WorkspaceResource, type WorkspaceState, type WorkspaceSummary, WorkspaceTerminalError, WorkspacesApi, splitAttachmentManifest };
+export { AdministrationApi, AgentApi, type AgentMessageInput, AgentNotReadyError, type AttachmentDescriptor, type AttachmentUploadInput, AttachmentsApi, type CheckpointResource, type CheckpointState, CheckpointsApi, type ClientErrorCode, ConversationGoneError, type ConversationMessage, type ConversationPage, ConversationsApi, type CursorListQuery, type LogChunk, LogsApi, type NetworkEvent, NetworkEventsApi, type OperationKind, type OperationResource, type OperationState, OperationsApi, type OutputResource, OutputsApi, type Page, PocketCoderClient, type PocketCoderClientConfig, PocketCoderError, type PreserveRequest, type RequestOptions, type ResolveWorkspaceTurnOptions, type ResolvedWorkspaceTurn, type RestoreRequest, type ResumeWorkspaceContext, type ServerTerminalMessage, type StorageState, TERMINAL_WORKSPACE_STATES, type TemplateSummary, TemplatesApi, type TerminalConnectOptions, TerminalConnection, type TerminalSession, TerminalsApi, type WebSocketFactory, type WorkspaceCreateInput, type WorkspaceListQuery, type WorkspaceResource, type WorkspaceState, type WorkspaceSummary, WorkspaceTerminalError, WorkspaceTurnResolutionError, type WorkspaceTurnResolutionErrorCode, WorkspaceTurnResolver, type WorkspaceTurnResolverOptions, WorkspacesApi, isPocketCoderErrorCode, splitAttachmentManifest };

package/dist/index.js

@@ -531,7 +531,9 @@ const AttachmentResolvedPayload = z.object({
 	descriptors: z.array(AttachmentDescriptorSchema).optional(),
 	missing_id: z.uuid().optional()
 });
-const errorCodes = Object.keys({
+//#endregion
+//#region ../contracts/src/errors.ts
+const ERROR_CODES = {
 	"auth.invalid_key": 401,
 	"auth.missing_scope": 403,
 	"auth.disabled_principal": 403,
@@ -583,7 +585,8 @@ const errorCodes = Object.keys({
 	"attachment.unsupported": 409,
 	"attachment.interrupted": 503,
 	"internal.error": 500
-});
+};
+const errorCodes = Object.keys(ERROR_CODES);
 const ErrorEnvelopeSchema = z.object({ error: z.object({
 	code: z.enum(errorCodes),
 	message: z.string().min(1),
@@ -700,7 +703,8 @@ const HarnessSchema = z.object({
 const AgentSchema = HarnessSchema.extend({
 	type: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/).default("custom"),
 	transport: z.enum(["pty", "acp"]).default("pty"),
-	termWidth: z.number().int().min(10).max(65535).optional()
+	termWidth: z.number().int().min(10).max(65535).optional(),
+	stateFile: z.string().refine(isAbsolutePath, "expected an absolute path").optional()
 });
 const TerminalSchema = z.object({
 	command: CommandSchema,
@@ -748,7 +752,8 @@ const TimeoutsSchema = z.object({
 });
 const ResourcesSchema = z.object({
 	cpu: z.string().regex(/^\d+(\.\d+)?m?$/),
-	memory: z.string().regex(/^\d+(Mi|Gi)$/)
+	memory: z.string().regex(/^\d+(Mi|Gi)$/),
+	ephemeralStorage: z.string().regex(/^\d+(Mi|Gi)$/).optional()
 });
 const RepositorySchema = z.object({
 	url: z.url().refine((value) => {
@@ -814,11 +819,14 @@ const TemplateSpecSchema = z.object({
 		message: "either agent or harness is required"
 	});
 	if (!spec.agent) return;
-	if (spec.agent.transport === "acp" && spec.agent.termWidth !== void 0) ctx.addIssue({
-		code: "custom",
-		path: ["agent", "termWidth"],
-		message: "termWidth is only valid for PTY transport"
-	});
+	if (spec.agent.transport === "acp") for (const field of ["termWidth", "stateFile"]) {
+		if (spec.agent[field] === void 0) continue;
+		ctx.addIssue({
+			code: "custom",
+			path: ["agent", field],
+			message: `${field} is only valid for PTY transport`
+		});
+	}
 	for (const field of [
 		"harness",
 		"services",
@@ -898,6 +906,7 @@ function agentApiHarness(spec) {
 			spec.agent.type,
 			...spec.agent.transport === "acp" ? ["--experimental-acp"] : [],
 			...spec.agent.termWidth === void 0 ? [] : ["--term-width", String(spec.agent.termWidth)],
+			...spec.agent.stateFile === void 0 ? [] : ["--state-file", spec.agent.stateFile],
 			"--port",
 			"3284",
 			"--",
@@ -1105,6 +1114,7 @@ function validatePersistence(spec, ctx) {
 	const mounts = spec.persistence.mounts;
 	for (const [index, mount] of mounts.entries()) validatePersistenceMount(spec, mounts, mount, index, seenNames, ctx);
 	validateSourceMount(spec, mounts, ctx);
+	validateAgentStateFile(spec, mounts, ctx);
 	if (spec.persistence.conversationRestore === "supported" && (!spec.persistence.sessionCompatibility || mounts.length < 2)) ctx.addIssue({
 		code: "custom",
 		path: [
@@ -1115,6 +1125,43 @@ function validatePersistence(spec, ctx) {
 		message: "supported conversation restore requires sessionCompatibility and a separate harness-state mount"
 	});
 }
+function validateAgentStateFile(spec, mounts, ctx) {
+	if (!isAgentApiNative(spec)) return;
+	const stateFile = spec.agent.stateFile;
+	const normalized = stateFile !== void 0 && isNormalizedFilesystemPath(stateFile);
+	if (stateFile !== void 0 && !normalized) ctx.addIssue({
+		code: "custom",
+		path: [
+			"spec",
+			"agent",
+			"stateFile"
+		],
+		message: "stateFile must be a normalized absolute filesystem path"
+	});
+	if (spec.agent.transport === "acp" && spec.persistence.conversationRestore === "supported") {
+		ctx.addIssue({
+			code: "custom",
+			path: [
+				"spec",
+				"persistence",
+				"conversationRestore"
+			],
+			message: "supported conversation restore requires PTY transport"
+		});
+		return;
+	}
+	if (spec.persistence.conversationRestore !== "supported") return;
+	if (normalized && mounts.some((mount) => stateFile.startsWith(`${mount.target}/`))) return;
+	ctx.addIssue({
+		code: "custom",
+		path: [
+			"spec",
+			"agent",
+			"stateFile"
+		],
+		message: "supported conversation restore requires agent.stateFile below a persistence mount"
+	});
+}
 function validatePersistenceMount(spec, mounts, mount, index, seenNames, ctx) {
 	const path = [
 		"spec",
@@ -1779,6 +1826,19 @@ var WorkspaceTerminalError = class extends Error {
 		this.workspace = workspace;
 	}
 };
+var AgentNotReadyError = class extends Error {
+	workspaceId;
+	agentState;
+	constructor(workspaceId, agentState, timeoutMs) {
+		super(`agent in workspace ${workspaceId} was still ${agentState} after ${timeoutMs}ms and cannot accept a message`);
+		this.name = "AgentNotReadyError";
+		this.workspaceId = workspaceId;
+		this.agentState = agentState;
+	}
+};
+function isPocketCoderErrorCode(value) {
+	return typeof value === "string" && value in ERROR_CODES;
+}
 function responseError(response, body) {
 	const parsed = ErrorEnvelopeSchema.safeParse(body);
 	if (!parsed.success) return new PocketCoderError({
@@ -1797,6 +1857,7 @@ function responseError(response, body) {
 }
 //#endregion
 //#region src/attachments.ts
+const DEFAULT_READY_TIMEOUT_MS = 12e4;
 function contentDisposition(name) {
 	const clean = name.replace(/[\r\n]/g, "");
 	if (/^[ -~]*$/.test(clean)) return `attachment; filename="${clean.replace(/(["\\])/g, "\\$1")}"`;
@@ -1835,10 +1896,13 @@ var AttachmentsApi = class {
 };
 var AgentApi = class {
 	transport;
-	constructor(transport) {
+	workspaces;
+	constructor(transport, workspaces) {
 		this.transport = transport;
+		this.workspaces = workspaces;
 	}
 	async sendMessage(workspaceId, input) {
+		await this.workspaces.waitForAgentInput(workspaceId, input.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS, input.signal ? { signal: input.signal } : {});
 		const response = await this.transport.raw(`/v1/workspaces/${encodeURIComponent(workspaceId)}/agent/message`, {
 			method: "POST",
 			...input.signal ? { signal: input.signal } : {},
@@ -2278,6 +2342,17 @@ var WorkspacesApi = class {
 		}
 		return workspace;
 	}
+	async waitForAgentInput(id, timeoutMs, options = {}) {
+		const deadline = Date.now() + timeoutMs;
+		let workspace = await this.get(id, options);
+		while (workspace.agent_state !== "stable") {
+			if (TERMINAL_STATES.includes(workspace.state)) throw new WorkspaceTerminalError(workspace);
+			const remainingMs = deadline - Date.now();
+			if (remainingMs <= 0) throw new AgentNotReadyError(workspace.id, workspace.agent_state, timeoutMs);
+			workspace = (await this.change(workspace.id, workspace.change_cursor, Math.max(1, Math.min(30, Math.ceil(remainingMs / 1e3))), options)).workspace;
+		}
+		return workspace;
+	}
 	preserve(id, input, key, options = {}) {
 		return this.jsonOperation(`/v1/workspaces/${encodeURIComponent(id)}/preserve`, input, key, PreserveResponseSchema, options);
 	}
@@ -2317,7 +2392,7 @@ var PocketCoderClient = class {
 		this.templates = new TemplatesApi(this.transport);
 		this.workspaces = new WorkspacesApi(this.transport);
 		this.attachments = new AttachmentsApi(this.transport);
-		this.agent = new AgentApi(this.transport);
+		this.agent = new AgentApi(this.transport, this.workspaces);
 		this.conversations = new ConversationsApi(this.transport);
 		this.checkpoints = new CheckpointsApi(this.transport);
 		this.operations = new OperationsApi(this.transport);
@@ -2332,4 +2407,148 @@ var PocketCoderClient = class {
 	}
 };
 //#endregion
-export { AdministrationApi, AgentApi, AttachmentsApi, CheckpointsApi, ConversationGoneError, ConversationsApi, LogsApi, NetworkEventsApi, OperationsApi, OutputsApi, PocketCoderClient, PocketCoderError, TERMINAL_WORKSPACE_STATES, TemplatesApi, TerminalConnection, TerminalsApi, WorkspaceTerminalError, WorkspacesApi, splitAttachmentManifest };
+//#region src/workspace-turn-resolver.ts
+const ERROR_MESSAGES = {
+	not_resumable: "workspace cannot be resumed",
+	resume_handler_missing: "workspace resume handler is not configured",
+	resume_failed: "workspace resume failed",
+	invalid_resumed_workspace: "workspace resume returned an invalid workspace",
+	readiness_failed: "resumed workspace did not become ready"
+};
+var WorkspaceTurnResolutionError = class extends Error {
+	code;
+	constructor(code, cause) {
+		super(ERROR_MESSAGES[code], cause === void 0 ? void 0 : { cause });
+		this.name = "WorkspaceTurnResolutionError";
+		this.code = code;
+	}
+};
+const NON_RESUMABLE_STATES = /* @__PURE__ */ new Set([
+	"failed",
+	"canceled",
+	"expired",
+	"succeeded",
+	"terminating"
+]);
+function aborted(signal) {
+	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+function waitForCaller(promise, signal) {
+	if (!signal) return promise;
+	if (signal.aborted) return Promise.reject(aborted(signal));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(aborted(signal));
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+function requireRemaining(deadline, failure) {
+	const remaining = deadline - Date.now();
+	if (remaining <= 0) throw new WorkspaceTurnResolutionError(failure);
+	return remaining;
+}
+var WorkspaceTurnResolver = class {
+	client;
+	resumeWorkspace;
+	resumeTimeoutMs;
+	attempts = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.client = options.client;
+		this.resumeWorkspace = options.resumeWorkspace;
+		this.resumeTimeoutMs = options.resumeTimeoutMs ?? 3e5;
+	}
+	async resolve(sourceWorkspaceId, options = {}) {
+		if (options.signal?.aborted) throw aborted(options.signal);
+		const attempt = this.attempts.get(sourceWorkspaceId) ?? this.start(sourceWorkspaceId);
+		attempt.waiters += 1;
+		try {
+			return await waitForCaller(attempt.promise, options.signal);
+		} finally {
+			attempt.waiters -= 1;
+			if (attempt.waiters === 0 && !attempt.resumeStarted && !attempt.settled) attempt.controller.abort(new DOMException("No callers remain", "AbortError"));
+		}
+	}
+	start(sourceWorkspaceId) {
+		const attempt = {
+			controller: new AbortController(),
+			promise: Promise.resolve(void 0),
+			waiters: 0,
+			resumeStarted: false,
+			settled: false
+		};
+		this.attempts.set(sourceWorkspaceId, attempt);
+		attempt.promise = this.run(sourceWorkspaceId, attempt).finally(() => {
+			attempt.settled = true;
+			if (this.attempts.get(sourceWorkspaceId) === attempt) this.attempts.delete(sourceWorkspaceId);
+		});
+		attempt.promise.catch(() => {});
+		return attempt;
+	}
+	async run(sourceWorkspaceId, attempt) {
+		const deadline = Date.now() + this.resumeTimeoutMs;
+		let source = await this.client.workspaces.get(sourceWorkspaceId, { signal: attempt.controller.signal });
+		if (source.state === "ready") return {
+			workspace: source,
+			resumed: false
+		};
+		if (source.state === "preserving") source = await this.waitForPreserved(source, deadline, attempt.controller.signal);
+		this.assertResumable(source);
+		if (!this.resumeWorkspace) throw new WorkspaceTurnResolutionError("resume_handler_missing");
+		attempt.resumeStarted = true;
+		const attemptId = crypto.randomUUID();
+		let allocated;
+		try {
+			allocated = await this.resumeWorkspace({
+				source,
+				attemptId,
+				signal: attempt.controller.signal
+			});
+		} catch (error) {
+			throw new WorkspaceTurnResolutionError("resume_failed", error);
+		}
+		let fetched;
+		try {
+			fetched = await this.client.workspaces.get(allocated.id, { signal: attempt.controller.signal });
+		} catch (error) {
+			throw new WorkspaceTurnResolutionError("invalid_resumed_workspace", error);
+		}
+		this.assertLineage(source, fetched);
+		try {
+			return {
+				workspace: await this.client.workspaces.waitForReady(fetched, requireRemaining(deadline, "readiness_failed"), { signal: attempt.controller.signal }),
+				resumed: true
+			};
+		} catch (error) {
+			if (error instanceof WorkspaceTurnResolutionError) throw error;
+			throw new WorkspaceTurnResolutionError("readiness_failed", error);
+		}
+	}
+	async waitForPreserved(initial, deadline, signal) {
+		let workspace = initial;
+		while (workspace.state === "preserving") {
+			const remaining = requireRemaining(deadline, "resume_failed");
+			try {
+				workspace = (await this.client.workspaces.change(workspace.id, workspace.change_cursor, Math.max(1, Math.min(30, Math.ceil(remaining / 1e3))), { signal })).workspace;
+			} catch (error) {
+				if (signal.aborted) throw error;
+				throw new WorkspaceTurnResolutionError("resume_failed", error);
+			}
+		}
+		if (workspace.state === "failed") throw new WorkspaceTurnResolutionError("resume_failed");
+		return workspace;
+	}
+	assertResumable(workspace) {
+		if (workspace.state !== "preserved" || NON_RESUMABLE_STATES.has(workspace.state) || workspace.persistence.conversation_resume.status !== "supported" || !workspace.persistence.latest_checkpoint_id) throw new WorkspaceTurnResolutionError("not_resumable");
+	}
+	assertLineage(source, resumedWorkspace) {
+		if (resumedWorkspace.id === source.id || resumedWorkspace.origin_workspace_id !== source.id || resumedWorkspace.restored_from_checkpoint_id !== source.persistence.latest_checkpoint_id) throw new WorkspaceTurnResolutionError("invalid_resumed_workspace");
+	}
+};
+//#endregion
+export { AdministrationApi, AgentApi, AgentNotReadyError, AttachmentsApi, CheckpointsApi, ConversationGoneError, ConversationsApi, LogsApi, NetworkEventsApi, OperationsApi, OutputsApi, PocketCoderClient, PocketCoderError, TERMINAL_WORKSPACE_STATES, TemplatesApi, TerminalConnection, TerminalsApi, WorkspaceTerminalError, WorkspaceTurnResolutionError, WorkspaceTurnResolver, WorkspacesApi, isPocketCoderErrorCode, splitAttachmentManifest };

package/package.json

@@ -6,7 +6,7 @@
       "type:library"
     ]
   },
-  "version": "0.3.1",
+  "version": "0.5.0",
   "private": false,
   "description": "Runtime-validated TypeScript client for the PocketCoder control plane.",
   "type": "module",