@pstdio/pocketcoder-remote 0.2.2 → 0.3.1

package/README.md

@@ -15,10 +15,10 @@ final-response polling path.
 ## Install
 
 ```sh
-npm install -g @pstdio/pocketcoder-remote   # or: bun add -g @pstdio/pocketcoder-remote
+bun add -g @pstdio/pocketcoder-remote
 ```
 
-Or run without installing: `npx @pstdio/pocketcoder-remote`.
+Or run without installing: `bunx @pstdio/pocketcoder-remote`.
 
 ## Usage
 
@@ -55,7 +55,7 @@ you already use Pi, you can load the extension directly instead:
 
 ```sh
 POCKETCODER_URL=... POCKETCODER_KEY=... POCKETCODER_WORKSPACE_ID=... \
-pi --extension node_modules/@pstdio/pocketcoder-remote/src/extension.ts \
+pi --extension node_modules/@pstdio/pocketcoder-remote/dist/extension.js \
    --provider pocketcoder-agentapi --model remote-agent --api-key local-ui \
    --no-tools --no-extensions --no-skills --no-context-files \
    --no-prompt-templates --no-session --offline
@@ -81,6 +81,60 @@ a normal local coding session is not supported. This package pins
 `@earendil-works/pi-coding-agent` to an exact version; running the extension
 under a different Pi version is untested.
 
+## Embed the Pi adapter with workspace resume
+
+Products that can issue fresh workspace bootstrap input may pass the public SDK
+resolver into the typed extension factory:
+
+```ts
+import { createRemoteExtension } from "@pstdio/pocketcoder-remote/extension";
+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 }) => {
+    const launchInput = await issueWorkspaceBootstrap({ signal });
+    const result = await client.workspaces.resume(
+      source.id,
+      { external_id: `pi-${attemptId}`, launch_input: launchInput },
+      attemptId,
+      { signal },
+    );
+    return result.workspace;
+  },
+});
+
+export default createRemoteExtension({ resolver });
+```
+
+The bootstrap input must be new, workspace-scoped, and expire with the resumed
+workspace. The key needs `workspaces:read`, `workspaces:restore`, and
+`services:relay`; attachments also need `attachments:write`.
+
+Resume runs only for a user turn. The adapter uploads one captured attachment
+batch to the resolved workspace and retries only a verified terminal failure
+before the prompt is accepted. `/attach` entries remain queued until that
+acceptance point. After acceptance, relay or history failures never replay the
+prompt.
+
+If the same Pi UI is still open, it changes its local target to the resumed
+workspace for later turns, status, attachments, and `/workspace-cancel`. A user
+workspace switch or session shutdown wins over a late result. No full history
+is replayed into that live UI, and no A-to-B mapping is stored. Canceling the
+caller only stops its wait; an accepted server resume may continue.
+
+The package launcher uses the default extension without a resolver. It does not
+resume automatically. A preserved workspace therefore returns the fixed
+no-handler error until an embedded product supplies the callback.
+
 ## In-UI commands
 
 - `/workspace` — pick and switch to another ready workspace (replays its history)
@@ -98,7 +152,8 @@ the PocketCoder attachment API when the turn is sent:
 - queue one explicitly with `/attach <path>`.
 
 The agent receives each file's workspace path under `$HOME/.pcd/attachments`.
-If an upload fails the message is not sent. With a direct AgentAPI URL
+If an upload fails the message is not sent, and explicit queued files remain
+for the next safe attempt. With a direct AgentAPI URL
 (`POCKETCODER_AGENTAPI_URL`) managed uploads are unavailable — attachment
 gestures fail with an explanation while plain text keeps working.
 

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/bin.js

@@ -1,98 +1,77 @@
 #!/usr/bin/env node
-var __defProp = Object.defineProperty;
-var __returnValue = (v) => v;
-function __exportSetter(name, newValue) {
-  this[name] = __returnValue.bind(null, newValue);
-}
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: __exportSetter.bind(all, name)
-    });
-};
-
-// src/bin.ts
 import { spawn } from "node:child_process";
-
-// src/launch.ts
 import { readFileSync } from "node:fs";
 import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-var PI_FLAGS = [
-  "--provider",
-  "pocketcoder-agentapi",
-  "--model",
-  "remote-agent",
-  "--api-key",
-  "local-ui",
-  "--no-tools",
-  "--no-extensions",
-  "--no-skills",
-  "--no-context-files",
-  "--no-prompt-templates",
-  "--no-session",
-  "--offline"
+//#region src/launch.ts
+const PI_FLAGS = [
+	"--provider",
+	"pocketcoder-agentapi",
+	"--model",
+	"remote-agent",
+	"--api-key",
+	"local-ui",
+	"--no-tools",
+	"--no-extensions",
+	"--no-skills",
+	"--no-context-files",
+	"--no-prompt-templates",
+	"--no-session",
+	"--offline"
 ];
 function piBinPath(resolvePath) {
-  const entry = resolvePath("@earendil-works/pi-coding-agent");
-  const marker = `${sep}pi-coding-agent${sep}`;
-  const index = entry.lastIndexOf(marker);
-  if (index === -1) {
-    throw new Error(`could not locate @earendil-works/pi-coding-agent from ${entry}`);
-  }
-  const packageRoot = entry.slice(0, index + marker.length - 1);
-  const manifest = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
-  const bin = manifest.bin?.pi;
-  if (!bin)
-    throw new Error("@earendil-works/pi-coding-agent does not declare a pi bin");
-  return resolve(packageRoot, bin);
+	const entry = resolvePath("@earendil-works/pi-coding-agent");
+	const marker = `${sep}pi-coding-agent${sep}`;
+	const index = entry.lastIndexOf(marker);
+	if (index === -1) throw new Error(`could not locate @earendil-works/pi-coding-agent from ${entry}`);
+	const packageRoot = entry.slice(0, index + marker.length - 1);
+	const bin = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")).bin?.pi;
+	if (!bin) throw new Error("@earendil-works/pi-coding-agent does not declare a pi bin");
+	return resolve(packageRoot, bin);
 }
 function extensionPath(moduleDir) {
-  return resolve(moduleDir, moduleDir.endsWith(`${sep}src`) ? "extension.ts" : "extension.js");
+	return resolve(moduleDir, moduleDir.endsWith(`${sep}src`) ? "extension.ts" : "extension.js");
 }
 function resolvePiInvocation(options = {}) {
-  const env = options.env ?? process.env;
-  if (!env.POCKETCODER_KEY) {
-    throw new Error("POCKETCODER_KEY is required. Issue a machine key with `pcd keys issue` and export it, along with POCKETCODER_URL for your PocketCoder server.");
-  }
-  const resolvePath = options.resolvePath ?? ((specifier) => fileURLToPath(import.meta.resolve(specifier)));
-  const childEnv = { ...env };
-  delete childEnv.OPENAI_API_KEY;
-  return {
-    command: options.execPath ?? process.execPath,
-    args: [
-      piBinPath(resolvePath),
-      ...PI_FLAGS,
-      "--extension",
-      extensionPath(dirname(fileURLToPath(import.meta.url))),
-      ...options.argv ?? []
-    ],
-    env: childEnv
-  };
+	const env = options.env ?? process.env;
+	if (!env.POCKETCODER_KEY) throw new Error("POCKETCODER_KEY is required. Issue a machine key with `pcd keys issue` and export it, along with POCKETCODER_URL for your PocketCoder server.");
+	const resolvePath = options.resolvePath ?? ((specifier) => fileURLToPath(import.meta.resolve(specifier)));
+	const childEnv = { ...env };
+	delete childEnv.OPENAI_API_KEY;
+	return {
+		command: options.execPath ?? process.execPath,
+		args: [
+			piBinPath(resolvePath),
+			...PI_FLAGS,
+			"--extension",
+			extensionPath(dirname(fileURLToPath(import.meta.url))),
+			...options.argv ?? []
+		],
+		env: childEnv
+	};
 }
-
-// src/bin.ts
+//#endregion
+//#region src/bin.ts
 function main() {
-  let invocation;
-  try {
-    invocation = resolvePiInvocation({ argv: process.argv.slice(2) });
-  } catch (error) {
-    console.error(`pocketcoder-remote: ${error instanceof Error ? error.message : String(error)}`);
-    process.exit(1);
-  }
-  const child = spawn(invocation.command, invocation.args, {
-    stdio: "inherit",
-    env: invocation.env
-  });
-  child.on("error", (error) => {
-    console.error(`pocketcoder-remote: failed to launch pi: ${error.message}`);
-    process.exit(1);
-  });
-  child.on("exit", (code, signal) => {
-    process.exit(code ?? (signal ? 1 : 0));
-  });
+	let invocation;
+	try {
+		invocation = resolvePiInvocation({ argv: process.argv.slice(2) });
+	} catch (error) {
+		console.error(`pocketcoder-remote: ${error instanceof Error ? error.message : String(error)}`);
+		process.exit(1);
+	}
+	const child = spawn(invocation.command, invocation.args, {
+		stdio: "inherit",
+		env: invocation.env
+	});
+	child.on("error", (error) => {
+		console.error(`pocketcoder-remote: failed to launch pi: ${error.message}`);
+		process.exit(1);
+	});
+	child.on("exit", (code, signal) => {
+		process.exit(code ?? (signal ? 1 : 0));
+	});
 }
 main();
+//#endregion
+export {};

package/dist/extension.d.ts

@@ -0,0 +1,10 @@
+import { WorkspaceTurnResolver } from "@pstdio/pocketcoder-sdk";
+import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+//#region src/extension.d.ts
+interface RemoteExtensionOptions {
+  resolver?: WorkspaceTurnResolver;
+}
+declare function createRemoteExtension(options?: RemoteExtensionOptions): (pi: ExtensionAPI) => void;
+declare const _default: (pi: ExtensionAPI) => void;
+//#endregion
+export { RemoteExtensionOptions, createRemoteExtension, _default as default };