@zetaloop/chappie 0.5.0 → 1.0.0

package/docs/setup.md

@@ -0,0 +1,82 @@
+# Setup and configuration
+
+The broker is available as `chappie` after global installation, or through `pnpx -y @zetaloop/chappie`. Agent plugins connect to it from their own devices.
+
+## Codex
+
+Install the plugin from this repository's marketplace:
+
+```sh
+codex plugin marketplace add zetaloop/chappie
+codex plugin add chappie@chappie
+```
+
+### Using an ordinary model
+
+Enable `localTools` in Chappie's configuration. The installed plugin provides tools for working with other Chappie sessions.
+
+### Using the Chappie model
+
+To receive work in Codex, save the [model catalog](https://raw.githubusercontent.com/zetaloop/chappie/main/src/codex.json) locally and reference its absolute path in Codex's user configuration, `~/.codex/config.toml` or `$CODEX_HOME/config.toml`:
+
+```toml
+model_provider = "chappie"
+model = "chatgpt"
+model_catalog_json = "/absolute/path/to/codex.json"
+
+[model_providers.chappie]
+name = "Chappie"
+base_url = "http://127.0.0.1:24275/v1"
+
+[mcp_servers.chappie]
+command = "pnpx"
+args = ["-y", "@zetaloop/chappie", "codex", "--chatgpt"]
+env_vars = ["CODEX_HOME"]
+```
+
+Restart the Codex app after changing its provider configuration. The plugin starts the local provider service.
+
+To return to an ordinary model, restore its model, provider, and catalog settings and remove the `[mcp_servers.chappie]` override shown above, then restart the app. The installed plugin supplies the local tools.
+
+## Configuration
+
+Settings live in `~/.chappie/config.json`. The broker and agent plugins read this file at startup; an absent file uses the defaults.
+
+| Setting | Default | Used by | Purpose |
+|---|---|---|---|
+| `ask` | `true` | Broker | Enable question widgets in ChatGPT. |
+| `cooldown` | `20` | Broker | Participation window, in seconds. |
+| `listen` | `false` | Broker | Accept TCP connections; `true` uses port `24274`, or supply a port number. |
+| `connect` | Local socket | Agent plugins | Broker hostname, optionally followed by `:port`. |
+| `localTools` | `false` | Agent plugins | Provide collaboration tools to ordinary models. |
+
+`cooldown` applies to each ChatGPT conversation and target session. Repeated initialization within the window returns [observation instructions](tools.md#participation). The window refreshes when a question widget first loads or a resource is accessed; `0` disables it.
+
+### Multiple devices
+
+On the broker's device:
+
+```json
+{ "listen": true }
+```
+
+On each other device:
+
+```json
+{ "connect": "<broker>.local" }
+```
+
+The default TCP port is `24274`. All connected agents share the session directory and file transfer service. Paths are resolved on their respective devices.
+
+### OpenCode
+
+Chappie discovers OpenCode's local background service automatically. For a standalone server, set `opencode.url` to its HTTP address and `opencode.password` when authentication is enabled.
+
+### Codex service
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `codex.port` | `24275` | Local provider HTTP port. |
+| `codex.appServer` | Default control socket | Codex app-server endpoint: `unix://<path>` or a WebSocket URL. |
+
+When changing `codex.port`, update `model_providers.chappie.base_url` in Codex's configuration to match.

package/docs/tools.md

@@ -1,66 +1,38 @@
 # Tools
 
+ChatGPT uses the tools below. Agent sessions using ordinary models have a [local tool set](#local-models).
+
 | Tool | Purpose |
 |---|---|
-| `init` | Select this ChatGPT conversation's default Pi session and read its environment. |
-| `history` | Read the current Pi branch with timestamps and entry IDs. |
-| `sessions` | List connected Pi sessions and the current default. |
-| `tools` | Read full definitions of active Pi tools for `call`. |
-| `chat` | Send an assistant message to Pi. |
+| `sessions` | Find sessions by agent, device, directory, or name. |
+| `init` | Select this ChatGPT conversation's default session and read its environment. |
+| `tools` | Read the selected session's native tool definitions. |
+| `call` | Execute a native tool batch. |
+| `chat` | Send an assistant message or answer a model request. |
+| `history` | Read the agent's transcript with entry IDs and timestamps. |
+| `transfer` | Exchange files and images with ChatGPT or another session. |
 | `ask` | Create a persistent question in ChatGPT. |
-| `ask_assert` | Confirm that an `ask` widget loaded. |
-| `call` | Run one or more Pi tools as one native batch. |
-| `read` | Read local text or images. |
-| `bash` | Run a shell command. |
-| `edit` | Apply text replacements. |
-| `write` | Write text to a file. |
-| `transfer` | Move files between ChatGPT and Pi, copy between Pi sessions, or export a Pi image. |
+| `ask_assert` | Confirm that its widget loaded. |
 
 ## Sessions
 
-Call `init` at the start of local work. Without `sessionId`, it reuses the conversation's saved default or selects an online Pi session with no saved ChatGPT binding. Pass a Pi session ID to resume a specific task, including from another ChatGPT conversation or branch. Read recent `history` to recover progress before continuing the current task.
-
-When `globalAgents` is present, read and follow the instructions at `globalAgents.path` on the selected Pi session. Follow the participation guidance in `initialization.instructions`.
-
-`sessions` lists connected sessions with their ID, device, working directory, name, execution status, and binding count. The first execution tool call establishes the default using its `sessionId` or an online session with no saved bindings. Once a default exists, another tool's `sessionId` selects only that operation's target; `init({ sessionId })` changes the default.
-
-Several ChatGPT conversations can use the same Pi session. One conversation can also operate on several Pi sessions explicitly. Requests already assigned to a session continue there even if the conversation later changes its default.
-
-Remote Pi sessions appear in the same list when they connect to a broker exposed through `listen` and `connect`. Their tools, global `AGENTS.md`, files, images, and Pi interfaces come from the remote device.
-
-## History
-
-`history` reads the current branch of a Pi session. It uses the saved default or an explicit `sessionId`, independently of default-session selection.
-
-```json
-{ "sessionId": "<session-id>", "limit": 20, "before": "<entry-id>" }
-```
-
-Omit `before` for the latest entries. Use `after` to read forward from an entry. Both fields can delimit a range, with the named entries outside the returned range. The default limit is 20 readable entries. Results follow branch order and contain each entry's original ID and timestamp. `hasMore` indicates additional entries in the requested direction.
-
-To follow progress, pass `after` with `wait: true`. Available entries return immediately; at the end of the branch, the request waits up to 30 seconds for new readable entries. A timeout returns an empty page. Reads with `before` return immediately. Cancellation, disconnection, or an invalidated branch cursor ends the request. Waiting for history leaves the session available for other requests.
-
-Set `observer: true` to read as an observer. New messages and work activity wake waiting readers; idle status alone does not indicate task completion.
-
-History includes saved messages, tool calls and results, summaries, images, file links, and work activity. Truncation notices and full-output paths are included so complete output can be read when needed. Reading history leaves new input and pending results available for normal delivery.
-
-## Participation
+`init` accepts a `sessionId` to resume a task, including from another ChatGPT conversation or branch. Read recent `history` to recover its progress. When `globalAgents` is present, its path identifies the host's global instruction file.
 
-The executing assistant uses `chat` to share progress and completion in Pi. When initialization directs an assistant to observe, it follows that work through `history` with `observer: true` and `wait: true`, thinks independently, and explains the recorded results in ChatGPT when the task is complete.
+Without `sessionId`, `init` reuses the saved default or selects an online session with no saved ChatGPT binding. The first execution tool can also establish a default. Once a default exists, another tool's `sessionId` selects only that operation's target; `init({ sessionId })` changes the default.
 
-## Pi tools
+Several conversations can share a session, and one conversation can work with several sessions. An operation stays associated with the target selected when it started. Conversation bindings survive broker restarts.
 
-ChatGPT truncates tool responses exceeding 10,000 tokens.
+`sessions` returns IDs, agents, devices, working directories, names, models, execution status, and binding counts. A session registers while its Chappie provider is selected. Devices using `listen` and `connect` share this directory of sessions.
 
-`read`, `bash`, `edit`, `write`, and `transfer` are available directly. `init` includes a short catalog of the active Pi tools; use `tools` for their complete definitions and `call` to invoke extension tools.
+## Native tools
 
-For example:
+`init` includes a short tool catalog. `tools` returns full definitions, optionally selected by name:
 
 ```json
-{ "names": ["ask_user", "ctx_search"] }
+{ "names": ["read", "bash"] }
 ```
 
-A `call` array is one Pi tool batch:
+Names and parameters come from the selected agent. For example, a Pi session accepts this batch:
 
 ```json
 {
@@ -71,92 +43,82 @@ A `call` array is one Pi tool batch:
 }
 ```
 
-Pi controls execution inside that batch. Separate requests run in order within one Pi session, while different Pi sessions can work independently. Extension tools retain their native Pi behavior, including interactive interfaces.
+A `calls` array executes as one native batch. Separate requests are ordered within a session; different sessions can execute independently. Tools retain their host's execution, interaction, and transcript behavior.
 
-`chat` creates a normal assistant message in Pi:
+`call` also accepts `base64`: the same `calls` array serialized as UTF-8 JSON and encoded as Base64. Supply either representation, with `sessionId` outside the encoded array.
+
+`chat` sends progress and completion messages to the selected session:
 
 ```json
 { "text": "Updated the parser and its callers." }
 ```
 
-Pi user input consumed during the work accompanies later Chappie results, including images.
-
-If a request is explicitly cancelled after local work has produced results, those results can accompany a later response to the originating ChatGPT conversation. Long-running local work is better run through the environment's persistent process facilities instead of occupying one tool request.
-
-The active model remains the current ChatGPT conversation. Starting another `chappie/chatgpt` agent inside Pi does not create another browser conversation; tools that need another model should use a separately configured provider.
-
-## Webpage questions
+Local user input accompanies later results, including images. Completed output from an interrupted request can be delivered to its originating conversation with a later response.
 
-When enabled, `ask` saves a question and requests a widget in ChatGPT, returning its ID immediately. Display depends on the host:
+A session can request generated text, such as a summary or title. The result includes a `request` ID, its `sessionId`, instructions, and the original input. Reply with `chat`:
 
 ```json
 {
-  "header": "Export format",
-  "question": "Which export format should the command use?",
-  "context": "Both preserve the required data.",
-  "options": [
-    { "title": "JSON", "description": "Convenient for programs.", "recommended": true },
-    { "title": "CSV", "description": "Convenient for spreadsheets." }
-  ]
+  "sessionId": "<session-id>",
+  "replyTo": "<request-id>",
+  "text": "The requested summary."
 }
 ```
 
-Call `ask_assert` with the returned ID to confirm that the widget loaded:
+During a pending model request, `call` reports the batch as unexecuted with `cancelled` and an error status. Read context with `history`, reply to the request, then submit the tools still needed. Each request has its own ID; a reply can include another request when the session needs several summaries.
+
+ChatGPT removes the middle of tool responses exceeding 10,000 tokens. Use history pagination or limit native tool output when needed; local tools have no such response limit.
+
+## History
+
+`history` reads the native transcript using the saved default or an explicit `sessionId`:
 
 ```json
-{ "questionId": "<question-id>" }
+{ "sessionId": "<session-id>", "limit": 20, "before": "<entry-id>" }
 ```
 
-If the widget has not loaded within 10 seconds, `ask_assert` fails and saves the unanswered question as skipped. Use a Pi interactive tool when an answer is needed. The user can still answer or edit the saved question when its widget is available.
-
-Answers, revisions, and skips arrive later as `webAnswer` in normal Chappie results. `options` can be omitted for a text answer, and `allowMultiple: true` allows several choices. `sessionId` associates the question with a Pi session using the session selection rules above.
+The default is the latest 20 readable entries. `before` pages backward and `after` pages forward; both can delimit a range. Named entries are excluded from that range. Results follow transcript order, with native IDs and recorded timestamps. `hasMore` indicates more entries in the requested direction.
 
-Questions remain available after the assistant response and across broker restarts. Pi's own interactive tools remain ordinary Pi tools and can be invoked through `call`.
+Use `after` with `wait: true` to follow progress. Available entries return immediately; at the end of the transcript the request waits up to 30 seconds, returning an empty page when no entries arrive. Reads with `before` return immediately.
 
-## Files
+History includes native messages, tool calls and results, summaries, images, and resource references. Each read reflects the host's current records, including work in progress. Re-read the same range to see updates to existing entries.
 
-`transfer.paths` always names paths or image references on the Pi side. Relative paths resolve from the selected Pi session's working directory; absolute paths and `~/` are accepted.
+### Participation
 
-### ChatGPT to Pi
+The executing assistant uses `chat` for progress and completion. When `initialization.instructions` assigns observation, read that work through `history` with `observer: true` and `wait: true`, then report its recorded outcome in ChatGPT.
 
-Pair Pi destinations with ChatGPT files:
+## Files and images
 
-```json
-{
-  "paths": ["assets/reference.png", "data/input.csv"],
-  "files": ["/mnt/data/reference.png", "/mnt/data/input.csv"]
-}
-```
+`paths` names files on the selected session's device. Relative paths use its working directory; absolute paths and `~/` are accepted. Each transfer pairs source and destination paths by position.
 
-The ChatGPT host turns the cloud paths or attachment references into downloadable file objects before the call reaches Chappie. Parent directories are created as needed.
+### From ChatGPT
 
-Existing targets produce an error by default. Use `overwrite: true` when replacement is intended:
+Pair destination paths with ChatGPT attachments:
 
 ```json
 {
-  "paths": ["assets/reference.png"],
-  "files": ["/mnt/data/reference.png"],
-  "overwrite": true
+  "paths": ["assets/reference.png", "data/input.csv"],
+  "files": ["/mnt/data/reference.png", "/mnt/data/input.csv"]
 }
 ```
 
-A failed or cancelled transfer removes the incomplete destination opened by that operation. Successful members of a multi-file transfer remain in place.
+ChatGPT converts the attachment references into downloadable file objects. Chappie creates parent directories. `overwrite: true` replaces existing targets.
 
-### Pi to ChatGPT
+### To ChatGPT
 
-Omit `files` to export existing Pi files:
+Export files from the selected session:
 
 ```json
 { "paths": ["build/output.zip", "renders/preview.png"] }
 ```
 
-Chappie returns MCP resource links. ChatGPT retrieves the bytes when it materializes those resources, which can require user confirmation. A resource remains associated with the Pi session that exported it, so that Pi process and source file need to remain available until the bytes are read.
+The returned resource links identify the original session and file. ChatGPT retrieves their bytes through resource materialization, which may prompt for approval. The producing connection and source file provide those bytes even after the conversation changes its default session.
 
-For a directory, create an archive with a Pi tool and export the resulting file.
+Native image results also carry `chappie://` references. Pass a reference to `transfer.paths` to retrieve those exact bytes, or use the original file path to export the source image.
 
-### Pi to Pi
+### Between sessions
 
-Supply `to` to copy files to another connected Pi session:
+Send files using `to`:
 
 ```json
 {
@@ -169,12 +131,60 @@ Supply `to` to copy files to another connected Pi session:
 }
 ```
 
-Source and destination paths correspond by position. Each session resolves its own relative paths, absolute paths, and `~/`. Image references can also be copied. `files` and `to` select different sources and are mutually exclusive.
+Retrieve files using `from`:
+
+```json
+{
+  "paths": ["downloads/output.zip"],
+  "from": {
+    "sessionId": "<source-session>",
+    "paths": ["build/output.zip"]
+  }
+}
+```
+
+Both sides use their existing broker connections and resolve paths on their own devices. Different agents use the same transfer operations. Completed files remain available when another file in the batch fails or is cancelled.
+
+## Local models
+
+Enable `localTools` in Chappie's configuration to provide these tools to ordinary models:
+
+| Tool | Target |
+|---|---|
+| `sessions` | Online Chappie sessions, with the current local ID reported as `self`. |
+| `remote_tools` | Tool definitions from the required `sessionId`. |
+| `remote_call` | One native tool batch in the required `sessionId`. |
+| `remote_chat` | An assistant message or model-request reply in the required `sessionId`. |
+| `history` | The current local transcript, or a Chappie session named by `sessionId`. |
+| `transfer` | Local files and resources exchanged with Chappie sessions. |
 
-Both Pi sessions need to stay connected during the transfer. `overwrite: true` replaces an existing destination. Cancellation or failure discards the incomplete file; successfully copied files remain available.
+Use an ordinary model in the controlling session and the Chappie model in each target. This supports agent-to-agent collaboration, such as building a project on another operating system.
 
-### Images
+Local `history` reads the controlling session; pass `sessionId` for a target's transcript. `transfer` uses local paths and exchanges files with targets through `from` and `to`.
+
+Use `remote_tools` to discover a target's definitions, then `remote_call` to execute them. When `globalAgents.path` is returned, read that file for the target's instructions. `remote_chat` sends an assistant message to the target:
+
+```json
+{ "sessionId": "<target-session>", "text": "The build completed successfully." }
+```
+
+Model requests include instructions naming the local tools. Supply `replyTo` to answer with `remote_chat`, then submit the tools still needed with `remote_call`. These operations use native session IDs, independently of ChatGPT conversation bindings.
+
+## Questions in ChatGPT
+
+`ask` saves a question and requests its widget:
+
+```json
+{
+  "header": "Export format",
+  "question": "Which export format should the command use?",
+  "options": [
+    { "title": "JSON", "description": "Structured data for programs.", "recommended": true },
+    { "title": "CSV", "description": "Tabular data for spreadsheets." }
+  ]
+}
+```
 
-`read` and Pi tool results send images directly to ChatGPT for visual inspection. Chappie also returns a `chappie://` image reference with Pi images. Pass that reference to `transfer.paths` when the same bytes are needed as a file in ChatGPT's cloud environment.
+Call `ask_assert` with the returned `question.id`. It confirms loading or marks the question skipped after 10 seconds. Native agent interaction tools are also available through `call`.
 
-Use the original local path with `transfer` when the original image file is required; Pi can resize or convert images used only for display.
+Answers, revisions, and skips arrive as `webAnswer` in later results. Omit `options` for a text answer; use `allowMultiple: true` for multiple choices. Questions persist across replies and broker restarts.

package/package.json

@@ -1,57 +1,101 @@
 {
-	"name": "@zetaloop/chappie",
-	"version": "0.5.0",
-	"description": "Connect ChatGPT to Pi",
-	"devDependencies": {
-		"@earendil-works/pi-ai": "^0.85.1",
-		"@earendil-works/pi-coding-agent": "^0.85.1",
-		"@earendil-works/pi-tui": "^0.85.1",
-		"@types/node": "^26.5.1",
-		"typebox": "^1.3.30",
-		"typescript": "^7.0.2"
-	},
-	"scripts": {
-		"format": "biome check --write .",
-		"check": "biome check . && tsc"
-	},
-	"keywords": [
-		"pi-package",
-		"chatgpt",
-		"mcp"
-	],
-	"author": "zetaloop",
-	"license": "MIT",
-	"packageManager": "pnpm@12.4.1",
-	"type": "module",
-	"engines": {
-		"node": ">=26",
-		"pnpm": ">=12"
-	},
-	"pi": {
-		"extensions": [
-			"./src/index.ts"
-		]
-	},
-	"peerDependencies": {
-		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
-		"typebox": "*"
-	},
-	"dependencies": {
-		"@modelcontextprotocol/server": "^2.0.0",
-		"mime": "^4.1.0",
-		"zod": "^4.6.4"
-	},
-	"files": [
-		"src",
-		"docs"
-	],
-	"publishConfig": {
-		"access": "public"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/zetaloop/chappie.git"
-	}
-}
+  "name": "@zetaloop/chappie",
+  "version": "1.0.0",
+  "description": "Connect ChatGPT and coding agents across devices",
+  "devDependencies": {
+    "@ai-sdk/provider": "^3.0.8",
+    "@earendil-works/pi-ai": "^0.87.1",
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-tui": "^0.87.1",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "@oh-my-pi/pi-ai": "^18.3.0",
+    "@oh-my-pi/pi-coding-agent": "^18.3.0",
+    "@oh-my-pi/pi-utils": "^18.3.0",
+    "@opencode/client": "^2.0.18",
+    "@opencode/plugin": "^2.0.18",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^26.5.1",
+    "@types/ws": "^8.18.1",
+    "cross-spawn": "^7.0.6",
+    "esbuild": "^0.28.2",
+    "mime": "^4.1.0",
+    "typebox": "^1.3.30",
+    "typescript": "^7.0.2",
+    "ws": "^8.21.3",
+    "zod": "^4.6.4"
+  },
+  "keywords": [
+    "pi-package",
+    "chatgpt",
+    "mcp"
+  ],
+  "author": "zetaloop",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=26",
+    "pnpm": ">=12"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@oh-my-pi/pi-ai": "*",
+    "@oh-my-pi/pi-coding-agent": "*",
+    "@oh-my-pi/pi-utils": "*"
+  },
+  "files": [
+    "dist",
+    "docs",
+    ".codex-plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zetaloop/chappie.git"
+  },
+  "bin": {
+    "chappie": "./dist/cli.js"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "@oh-my-pi/pi-ai": {
+      "optional": true
+    },
+    "@oh-my-pi/pi-coding-agent": {
+      "optional": true
+    },
+    "@oh-my-pi/pi-utils": {
+      "optional": true
+    }
+  },
+  "omp": {
+    "extensions": [
+      "./dist/omp.js"
+    ]
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": "./dist/opencode.js"
+  },
+  "scripts": {
+    "format": "biome check --write .",
+    "check": "biome check . && tsc --noEmit",
+    "build": "node scripts/build.ts"
+  }
+}

package/src/activity.ts

@@ -1,21 +0,0 @@
-export interface Source {
-	chatId: string;
-	requestId?: string;
-}
-
-export interface Activity extends Partial<Source> {
-	event?: string;
-	initialization?: "explicit" | "implicit";
-}
-
-export function source(chatId: string, requestId: unknown): Source {
-	return {
-		chatId,
-		...(typeof requestId === "string" ? { requestId } : {}),
-	};
-}
-
-export function chatLabel({ chatId, requestId }: Source): string {
-	const workflow = requestId?.match(/^wfr_([^/]+)\//)?.[1];
-	return `ChatGPT ${chatId.slice(-4)}${workflow ? `(${workflow.slice(-4)})` : ""}`;
-}