@pstdio/pocketcoder-remote 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pufflig AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @pstdio/pocketcoder-remote
+
+A terminal UI for PocketCoder workspaces, built on the [Pi coding agent](https://github.com/badlogic/pi-mono). The coding agent and all file operations stay inside the remote workspace; this package runs Pi locally as a thin client that sends turns through PocketCoder's service relay and replays the workspace's durable conversation history.
+
+```text
+local Pi TUI → PocketCoder service relay → AgentAPI → remote coding agent
+```
+
+AgentAPI message snapshots stream into Pi while a turn is running. Each
+snapshot replaces Pi's mutable partial message, so terminal rewrites render
+without duplicated text; the completed message still comes from AgentAPI's
+stable history. Older servers and workspace snapshots automatically use the
+final-response polling path.
+
+## Install
+
+```sh
+npm install -g @pstdio/pocketcoder-remote   # or: bun add -g @pstdio/pocketcoder-remote
+```
+
+Or run without installing: `npx @pstdio/pocketcoder-remote`.
+
+## Usage
+
+```sh
+POCKETCODER_URL=http://127.0.0.1:7080 \
+POCKETCODER_KEY=pkt_... \
+POCKETCODER_WORKSPACE_ID=<uuid> \
+pocketcoder-remote [initial prompt]
+```
+
+`POCKETCODER_WORKSPACE_ID` is optional — without it, a workspace picker opens on startup.
+
+Environment variables:
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `POCKETCODER_URL` | yes* | PocketCoder server base URL |
+| `POCKETCODER_KEY` | yes | Machine key (`pkt_...`) |
+| `POCKETCODER_WORKSPACE_ID` | no | Workspace to attach to; omit to pick interactively |
+| `POCKETCODER_AGENTAPI_URL` | no | Direct AgentAPI URL (bypasses the relay; disables history, picker, and status features) |
+
+*Not required when `POCKETCODER_AGENTAPI_URL` is set.
+
+The machine key needs scopes `workspaces:read`, `services:relay`, and
+`conversations:read`. File attachments additionally require `attachments:write`.
+The in-UI create and cancel commands use `templates:read`, `workspaces:create`,
+and `workspaces:cancel`; they degrade gracefully when the key lacks them.
+
+## Using your own Pi install
+
+The `pocketcoder-remote` launcher is a thin wrapper: it spawns the Pi version
+pinned by this package with the extension and the thin-client flags below. If
+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 \
+   --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
+```
+
+The flags are part of the contract, not decoration:
+
+- `--no-session` keeps Pi from persisting a local transcript. History replay
+  appends the server transcript on every attach, so a persisted local session
+  would duplicate it on resume; the durable server conversation is the only
+  source of truth.
+- `--no-tools` (with the extension also clearing active tools) ensures the
+  local Pi never reads or edits local files — the remote agent owns all
+  workspace operations.
+- `--provider pocketcoder-agentapi --model remote-agent` routes every turn
+  through the PocketCoder relay; `--offline` and the remaining `--no-*` flags
+  keep local skills, context files, and other extensions out of a session that
+  a remote agent is actually driving.
+
+Do not install the extension into `~/.pi/agent/extensions/` for everyday use:
+it registers a remote provider and expects the flags above, so loading it into
+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.
+
+## In-UI commands
+
+- `/workspace` — pick and switch to another ready workspace (replays its history)
+- `/workspace-create` — pick a template, create a workspace, wait for ready, switch to it
+- `/workspace-cancel` — cancel the current workspace (with confirmation)
+- `/attach <path>` — queue a local file to upload with the next message
+
+## File attachments
+
+Three gestures turn local files into workspace files, all uploaded through
+the PocketCoder attachment API when the turn is sent:
+
+- paste or drop an image (stored as `pasted-image.<ext>`),
+- mention a file as `@./report.pdf` (or `@"my report.pdf"` for spaces),
+- 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
+(`POCKETCODER_AGENTAPI_URL`) managed uploads are unavailable — attachment
+gestures fail with an explanation while plain text keeps working.
+
+## Behavior notes
+
+- The server's durable conversation is the source of truth: every attach replays history from `GET /v1/workspaces/{id}/conversation`. Pi's local session persistence is disabled.
+- Live text uses AgentAPI's `GET /events` stream when the workspace snapshot and protocol support it. Intermediate snapshots are never persisted.
+- Local Pi coding tools are disabled; the remote agent does all the work.
+- The status bar shows the workspace id, workspace state, and agent state, updated via the durable change cursor.

package/dist/bin.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+// 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"
+];
+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);
+}
+function extensionPath() {
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  return resolve(packageRoot, "src/extension.ts");
+}
+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(),
+      ...options.argv ?? []
+    ],
+    env: childEnv
+  };
+}
+
+// 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));
+  });
+}
+main();

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@pstdio/pocketcoder-remote",
+	"nx": {
+		"tags": [
+			"scope:remote",
+			"type:app"
+		]
+	},
+	"version": "0.2.0",
+	"private": false,
+	"description": "Pi-based terminal UI for PocketCoder workspaces.",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pufflyai/pocketcoder.git",
+		"directory": "packages/remote"
+	},
+	"files": [
+		"dist",
+		"src",
+		"!src/**/*.test.ts",
+		"README.md",
+		"LICENSE"
+	],
+	"bin": {
+		"pocketcoder-remote": "dist/bin.js"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"scripts": {
+		"build": "bun build ./src/bin.ts --outdir ./dist --target node",
+		"start": "bun ./src/bin.ts",
+		"test": "bun test",
+		"typecheck": "tsc --project ./tsconfig.json --noEmit"
+	},
+	"dependencies": {
+		"@pstdio/pocketcoder-client": "workspace:*",
+		"@earendil-works/pi-ai": "0.83.0",
+		"@earendil-works/pi-coding-agent": "0.83.0",
+		"@earendil-works/pi-tui": "0.83.0"
+	},
+	"devDependencies": {
+		"@types/bun": "1.3.14",
+		"typescript": "5.9.3"
+	}
+}

package/src/agentapi-events.ts

@@ -0,0 +1,104 @@
+interface MessageUpdate {
+	event: "message_update";
+	data: {
+		id: number;
+		message: string;
+		role: string;
+		time?: string;
+	};
+}
+
+interface StatusChange {
+	event: "status_change";
+	data: {
+		agent_type?: string;
+		status: "running" | "stable";
+	};
+}
+
+interface AgentError {
+	event: "agent_error";
+	data: {
+		level?: string;
+		message: string;
+		time?: string;
+	};
+}
+
+export type AgentApiEvent = MessageUpdate | StatusChange | AgentError;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function eventPayload(block: string): { event: string; parsed: Record<string, unknown> } | null {
+	let event = "message";
+	const data: string[] = [];
+	for (const line of block.split("\n")) {
+		if (line.startsWith(":")) continue;
+		const separator = line.indexOf(":");
+		const field = separator === -1 ? line : line.slice(0, separator);
+		const value = separator === -1 ? "" : line.slice(separator + 1).replace(/^ /, "");
+		if (field === "event") event = value;
+		if (field === "data") data.push(value);
+	}
+	if (data.length === 0) return null;
+	try {
+		const parsed = JSON.parse(data.join("\n")) as unknown;
+		return isRecord(parsed) ? { event, parsed } : null;
+	} catch {
+		return null;
+	}
+}
+
+function parseEvent(block: string): AgentApiEvent | null {
+	const payload = eventPayload(block);
+	if (!payload) return null;
+	const { event, parsed } = payload;
+	if (
+		event === "message_update" &&
+		typeof parsed.id === "number" &&
+		typeof parsed.message === "string" &&
+		typeof parsed.role === "string"
+	) {
+		return { event, data: parsed as MessageUpdate["data"] };
+	}
+	if (event === "status_change" && (parsed.status === "running" || parsed.status === "stable")) {
+		return { event, data: parsed as StatusChange["data"] };
+	}
+	if (event === "agent_error" && typeof parsed.message === "string") {
+		return { event, data: parsed as AgentError["data"] };
+	}
+	return null;
+}
+
+export async function* readAgentApiEvents(
+	body: ReadableStream<Uint8Array>,
+	signal: AbortSignal,
+): AsyncGenerator<AgentApiEvent> {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const abort = () => {
+		void reader.cancel(signal.reason).catch(() => {});
+	};
+	if (signal.aborted) abort();
+	else signal.addEventListener("abort", abort, { once: true });
+	try {
+		while (!signal.aborted) {
+			const next = await reader.read();
+			if (next.done) break;
+			buffer = `${buffer}${decoder.decode(next.value, { stream: true })}`.replaceAll("\r\n", "\n");
+			let boundary = buffer.indexOf("\n\n");
+			while (boundary >= 0) {
+				const event = parseEvent(buffer.slice(0, boundary));
+				buffer = buffer.slice(boundary + 2);
+				if (event) yield event;
+				boundary = buffer.indexOf("\n\n");
+			}
+		}
+	} finally {
+		signal.removeEventListener("abort", abort);
+		reader.releaseLock();
+	}
+}

package/src/attachments.ts

@@ -0,0 +1,158 @@
+import { readFileSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, resolve } from "node:path";
+import type { Context } from "@earendil-works/pi-ai";
+import type { CommandContext, CommandRegistrar } from "./commands";
+import type { ControlPlaneClient } from "./control-plane";
+import type { TargetRef } from "./session-target";
+
+// Turn-level attachment capture for the Pi remote: pasted images, explicit
+// @path tokens, and the /attach queue all upload through the PocketCoder
+// attachment API before the message referencing them is sent.
+
+export const DIRECT_MODE_ATTACHMENT_ERROR =
+	"file attachments need the PocketCoder workspace API; a direct AgentAPI URL (POCKETCODER_AGENTAPI_URL) cannot accept managed uploads";
+
+export interface TurnFile {
+	name: string;
+	mediaType: string;
+	bytes: Uint8Array;
+	localPath?: string;
+}
+
+const IMAGE_EXTENSIONS: Record<string, string> = {
+	"image/gif": "gif",
+	"image/jpeg": "jpg",
+	"image/png": "png",
+	"image/svg+xml": "svg",
+	"image/webp": "webp",
+};
+
+const MEDIA_TYPES: Record<string, string> = {
+	".csv": "text/csv",
+	".gif": "image/gif",
+	".html": "text/html",
+	".jpeg": "image/jpeg",
+	".jpg": "image/jpeg",
+	".json": "application/json",
+	".md": "text/markdown",
+	".pdf": "application/pdf",
+	".png": "image/png",
+	".svg": "image/svg+xml",
+	".txt": "text/plain",
+	".webp": "image/webp",
+};
+
+function lastUserContent(context: Context): Context["messages"][number]["content"] | undefined {
+	const message = context.messages.findLast((candidate) => candidate.role === "user");
+	return message?.role === "user" ? message.content : undefined;
+}
+
+export function userTextOf(context: Context): string {
+	const content = lastUserContent(context);
+	if (content === undefined) throw new Error("local Pi did not provide a user message");
+	if (typeof content === "string") return content;
+	return content
+		.filter((part) => part.type === "text")
+		.map((part) => part.text)
+		.join("\n");
+}
+
+function imageParts(context: Context): TurnFile[] {
+	const content = lastUserContent(context);
+	if (content === undefined || typeof content === "string") return [];
+	return content
+		.filter((part) => part.type === "image")
+		.map((part) => ({
+			name: `pasted-image.${IMAGE_EXTENSIONS[part.mimeType] ?? "bin"}`,
+			mediaType: part.mimeType,
+			bytes: Uint8Array.from(Buffer.from(part.data, "base64")),
+		}));
+}
+
+// Explicit `@path` tokens that resolve to a local regular file; quoted forms
+// (`@"my file.pdf"`) support spaces.
+export function pathTokens(text: string, cwd = process.cwd()): string[] {
+	const paths: string[] = [];
+	for (const match of text.matchAll(/@(?:"([^"]+)"|(\S+))/g)) {
+		const token = (match[1] ?? match[2]) as string;
+		const path = isAbsolute(token) ? token : resolve(cwd, token);
+		if (isFile(path) && !paths.includes(path)) paths.push(path);
+	}
+	return paths;
+}
+
+function isFile(path: string): boolean {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function fileFromPath(path: string): TurnFile {
+	return {
+		name: basename(path),
+		mediaType: MEDIA_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream",
+		bytes: new Uint8Array(readFileSync(path)),
+		localPath: path,
+	};
+}
+
+export function collectTurnFiles(context: Context, queue: string[], cwd?: string): TurnFile[] {
+	const text = userTextOf(context);
+	const paths = [...queue];
+	for (const path of pathTokens(text, cwd)) {
+		if (!paths.includes(path)) paths.push(path);
+	}
+	return [...imageParts(context), ...paths.map(fileFromPath)];
+}
+
+export async function uploadTurnFiles(
+	controlPlane: ControlPlaneClient,
+	workspaceId: string,
+	files: TurnFile[],
+): Promise<string[]> {
+	const ids: string[] = [];
+	for (const file of files) {
+		const uploaded = await controlPlane.attachments.upload(workspaceId, {
+			name: file.name,
+			mediaType: file.mediaType,
+			body: file.bytes,
+			sizeBytes: file.bytes.byteLength,
+		});
+		ids.push(uploaded.id);
+	}
+	return ids;
+}
+
+export interface AttachCommandDeps {
+	targets: TargetRef;
+	queue: string[];
+}
+
+export function registerAttachCommand(pi: CommandRegistrar, deps: AttachCommandDeps): void {
+	pi.registerCommand("attach", {
+		description: "Queue a local file to upload with the next message",
+		handler: async (args, ctx: CommandContext) => {
+			if (deps.targets.current.mode === "direct") {
+				ctx.ui.notify(DIRECT_MODE_ATTACHMENT_ERROR, "warning");
+				return;
+			}
+			const token = args.trim();
+			if (!token) {
+				ctx.ui.notify("usage: /attach <path>", "info");
+				return;
+			}
+			const path = isAbsolute(token) ? token : resolve(process.cwd(), token);
+			if (!isFile(path)) {
+				ctx.ui.notify(`no such file: ${token}`, "warning");
+				return;
+			}
+			deps.queue.push(path);
+			ctx.ui.notify(
+				`queued ${basename(path)} (${deps.queue.length} attachment${deps.queue.length === 1 ? "" : "s"})`,
+				"info",
+			);
+		},
+	});
+}

package/src/bin.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { resolvePiInvocation } from "./launch";
+
+function main(): void {
+	let invocation: ReturnType<typeof resolvePiInvocation>;
+	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();