@pstdio/pocketcoder-sdk 0.7.0 → 0.9.0

package/README.md

@@ -52,6 +52,38 @@ 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`.
 
+## Managed sessions
+
+Applications that use PocketCoder as their agent runtime work with logical sessions
+and never name a workspace. PocketCoder places, replaces and stops compute itself.
+
+```ts
+const session = await client.sessions.create({ sessionId, profileId, profileRevision: 1 });
+const file = await client.files.put(session.sessionId, { inputId, name: "notes.txt", mediaType: "text/plain", bytes });
+// Store this body before sending it. After a lost reply, send the identical body again.
+const body = { requestId, message: "Summarize the notes", attachments: [file.reference], dispatchDeadline };
+await client.requests.submit(session.sessionId, body);
+
+const { records, eventCursor } = await client.sessions.snapshot(session.sessionId);
+for await (const event of client.sessions.events(session.sessionId, { after: eventCursor, signal })) {
+  // Delivered at least once: skip resource revisions you already applied, keep event.cursor.
+}
+```
+
+| Resource | Methods |
+| --- | --- |
+| `client.sessions` | `create`, `get`, `resume`, `close`, `history`, `snapshot`, `events`, `openPreview` |
+| `client.requests` | `submit`, `get`, `cancel`, `collection` |
+| `client.files` | `put`, `register`, `upload`, `get`, `exports`, `content` |
+| `client.authority` | `grantScope`, `putPolicy`, `getPolicy`, `usage`, `putProfile`, `putCredentialBinding` |
+
+`events` resumes after the last delivered cursor (also sent as `Last-Event-ID`) when a
+stream ends. It throws `events.cursor_expired` when the cursor is no longer retained:
+read a new snapshot and follow its `eventCursor`. `cancel` and `close` return a receipt
+that stays `pending` until the stop has evidence; retry with the same `cancelId`.
+Budgets cover physical capacity only; model usage belongs to the model gateway. See the
+[reference consumer](../../examples/clients/managed-runtime/README.md).
+
 ## Resolve one user turn after preservation
 
 Create one long-lived `WorkspaceTurnResolver` in a trusted backend. Call it
@@ -90,13 +122,21 @@ const resolver = new WorkspaceTurnResolver({
 
 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 };
+  const conversationId = crypto.randomUUID();
+  let request = await client.workspaceRequests.submit(workspace.id, {
+    requestId: crypto.randomUUID(), conversationId, message: prompt, files: [],
+  });
+  while (!request.finalizedAt) {
+    await new Promise(resolve => setTimeout(resolve, 250));
+    request = await client.workspaceRequests.get(workspace.id, request.acceptance.execution.requestId, conversationId);
+  }
+  const history = await client.conversations.read(workspace.id, conversationId);
+  return { workspace_id: workspace.id, conversation_id: conversationId, messages: history.items };
 }
 ```
 
 The key needs `workspaces:read`; a callback that calls `resume()` also needs
-`workspaces:restore`. Prompt relay and attachments need `services:relay` and
+`workspaces:restore`. Native session requests and attachments need `services:relay` and
 `attachments:write` respectively.
 
 The resolver stores no A-to-B mapping. Return the resolved id through your