@pstdio/pocketcoder-sdk 0.3.1 → 0.4.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

@@ -1413,5 +1413,43 @@ declare class WorkspaceTerminalError extends Error {
   readonly workspace: WorkspaceResource;
   constructor(workspace: WorkspaceResource);
 }
+declare function isPocketCoderErrorCode(value: unknown): value is ErrorCode;
 //#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 };
+//#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 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),
@@ -1779,6 +1782,9 @@ var WorkspaceTerminalError = class extends Error {
 		this.workspace = workspace;
 	}
 };
+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({
@@ -2332,4 +2338,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, 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.4.0",
   "private": false,
   "description": "Runtime-validated TypeScript client for the PocketCoder control plane.",
   "type": "module",