@pstdio/pocketcoder-sdk 0.4.0 → 0.5.0

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,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;
@@ -1140,15 +865,150 @@ declare class WorkspacesApi {
       };
       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;
+    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;
+    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;
+  }>;
+  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;
+    };
   }>;
-  preserve(id: string, input: PreserveRequest, key: string, options?: RequestOptions): Promise<{
+  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,6 +1467,11 @@ 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
@@ -1452,4 +1511,4 @@ declare class WorkspaceTurnResolver {
   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 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 };
+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

@@ -703,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,
@@ -751,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) => {
@@ -817,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",
@@ -901,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",
 			"--",
@@ -1108,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: [
@@ -1118,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",
@@ -1782,6 +1826,16 @@ 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;
 }
@@ -1803,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")}"`;
@@ -1841,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 } : {},
@@ -2284,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);
 	}
@@ -2323,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);
@@ -2482,4 +2551,4 @@ var WorkspaceTurnResolver = class {
 	}
 };
 //#endregion
-export { AdministrationApi, AgentApi, AttachmentsApi, CheckpointsApi, ConversationGoneError, ConversationsApi, LogsApi, NetworkEventsApi, OperationsApi, OutputsApi, PocketCoderClient, PocketCoderError, TERMINAL_WORKSPACE_STATES, TemplatesApi, TerminalConnection, TerminalsApi, WorkspaceTerminalError, WorkspaceTurnResolutionError, WorkspaceTurnResolver, WorkspacesApi, isPocketCoderErrorCode, splitAttachmentManifest };
+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.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Runtime-validated TypeScript client for the PocketCoder control plane.",
   "type": "module",