backprompter-server-sdk 0.1.3 → 0.1.4

package/README.md

@@ -28,6 +28,41 @@ const result = await bp.run({
 console.log(result.response);
 ```
 
+## Continuing a combo agent
+
+When a combo agent reaches its limit of sub-agent calls before the task is
+done, the result has `unfinished: true` and a `checkpoint`. Pass it back to
+carry on from where it stopped (no `userPrompt` needed):
+
+```js
+if (result.unfinished) {
+  const next = await bp.run({ agentId: 'researcher', continueFrom: result.checkpoint });
+}
+```
+
+The checkpoint is a short run id (`bpr_` + 22 characters). The run is saved
+on Backprompter's servers for 7 days, works only for the app it came from, and
+can be retried if a request fails. Continuing counts as a new message.
+`autoContinue: n` continues up to n times (max 20) before returning;
+`result.continued` says how many.
+
+## Code agents
+
+Backprompter's servers never run code. With `clientRunsCode: true`, a combo
+whose code sub-agent writes code pauses with `pending_code: [{ id, agent, code }]`.
+Run it wherever you choose and send the results back:
+
+```js
+let result = await bp.run({ agentId: 'analyst-team', userPrompt: 'Total sales by region', clientRunsCode: true, dataSchemas });
+while (result.pending_code) {
+  const codeResults = result.pending_code.map(({ id, code }) => ({ id, output: runInYourSandbox(code) }));
+  result = await bp.run({ agentId: 'analyst-team', continueFrom: result.checkpoint, codeResults, clientRunsCode: true, dataSchemas });
+}
+```
+
+Send `{ id, error }` for code that failed. Code steps aren't new messages; one
+reply runs code at most 10 times.
+
 ## Attachments
 
 `run()` takes `fileInputs` and `urlInputs`, and which key you use inside

package/index.js

@@ -70,17 +70,33 @@ export default class BackprompterServer {
     // callbacks see the answer as it is written. See _streamRun.
     stream,
     onDelta,
-    onStatus
+    onStatus,
+    // A combo agent's `checkpoint` (a saved run id, "bpr_…", kept for 7 days)
+    // from an earlier result with `unfinished: true` or `pending_code`:
+    // carries on from where it stopped. No userPrompt needed.
+    continueFrom,
+    // Continue an unfinished combo answer up to this many times (max 20)
+    // before returning. The result says how many in `continued`.
+    autoContinue,
+    // Code agents. With clientRunsCode, a combo pauses when a code sub-agent
+    // writes code and returns `pending_code: [{ id, agent, code }]`. Run the
+    // code wherever you choose (Backprompter's servers never run it), then call
+    // run({ continueFrom: result.checkpoint, codeResults: [{ id, output } |
+    // { id, error }] }). dataSchemas: your datasets' schemas, so the code is
+    // written for your columns.
+    clientRunsCode,
+    codeResults,
+    dataSchemas
   } = {}) {
     const resolvedApiKey = String(apiKey || this._apiKey || '').trim();
     if (!resolvedApiKey) throw new Error('BackprompterServer: apiKey is required.');
-    if (!userPrompt) throw new Error('BackprompterServer: userPrompt is required.');
+    if (!userPrompt && !continueFrom) throw new Error('BackprompterServer: userPrompt is required.');
 
     const resolvedTenantId = tenantId || this._tenantId || undefined;
     const body = {
       tenant_id: resolvedTenantId,
       agent_id: agentId,
-      user_prompt: userPrompt,
+      user_prompt: userPrompt || '',
       conversation_history: Array.isArray(conversationHistory) ? conversationHistory : [],
       profileString: String(profileString || ''),
       file_inputs: Array.isArray(fileInputs) ? fileInputs : [],
@@ -92,12 +108,31 @@ export default class BackprompterServer {
     if (genDiff !== undefined) body.gen_diff = genDiff;
     if (baseText !== undefined) body.base_text = baseText;
     if (ragCharBudget !== undefined) body.rag_char_budget = ragCharBudget;
-
-    if (stream) return this._streamRun(resolvedApiKey, body, { onDelta, onStatus });
-    return this._apiFetchWithApiKey('/public/run', resolvedApiKey, {
-      method: 'POST',
-      body: JSON.stringify(body)
-    });
+    if (continueFrom) body.continue_from = continueFrom;
+    if (clientRunsCode) body.client_runs_code = true;
+    if (Array.isArray(codeResults)) body.code_results = codeResults;
+    if (Array.isArray(dataSchemas)) body.data_schemas = dataSchemas;
+
+    const send = (b) => (stream
+      ? this._streamRun(resolvedApiKey, b, { onDelta, onStatus })
+      : this._apiFetchWithApiKey('/public/run', resolvedApiKey, { method: 'POST', body: JSON.stringify(b) }));
+
+    let res = await send(body);
+    const limit = Math.min(Math.max(Math.floor(Number(autoContinue) || 0), 0), 20);
+    let continued = 0;
+    while (res && res.unfinished && res.checkpoint && !res.pending_code && continued < limit) {
+      continued += 1;
+      if (typeof onStatus === 'function') onStatus({ type: 'status', stage: 'continue', count: continued });
+      res = await send({
+        tenant_id: resolvedTenantId,
+        user_prompt: '',
+        continue_from: res.checkpoint,
+        ...(clientRunsCode ? { client_runs_code: true } : {}),
+        ...(Array.isArray(dataSchemas) ? { data_schemas: dataSchemas } : {})
+      });
+    }
+    if (res && continued) res.continued = continued;
+    return res;
   }
 
   // POST /public/run with "stream": true and read the server-sent events.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backprompter-server-sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Backprompter server-side SDK for Node.js backends",
   "type": "module",
   "main": "index.js",