codex-toys 0.140.13 → 0.140.15

package/docs/pages/components/proxy.md

@@ -1,62 +0,0 @@
----
-title: Proxy
-description: Optional HTTP edge for browser dashboards backed by toybox methods.
----
-
-# Proxy
-
-`codex-toys-proxy` is the optional HTTP edge for browser dashboards. Core
-codex-toys commands stay stdio-first; the proxy is explicit.
-
-```bash
-codex-toys-proxy serve --cwd <workbench> --static ./dashboard
-codex-toys-proxy serve --ssh <target> --cwd <remote-workbench> --static ./dashboard
-```
-
-## Routes
-
-The proxy exposes generic routes:
-
-```text
-GET  /api/status
-GET  /api/schema
-POST /api/rpc
-POST /api/host/overview
-POST /api/app/:method
-POST /api/workbench/:method
-POST /api/workbench/overview
-```
-
-`/api/schema` is derived from `toybox.initialize`. Dashboards should discover
-method names and metadata instead of hard-coding duplicate product routes.
-
-`POST /api/workbench/overview` calls the `workbench.overview` method.
-`POST /api/host/overview` calls the `host.overview` method.
-
-## Browser Client
-
-```ts
-import { createCodexToysBrowserClient } from "codex-toys/proxy/browser";
-
-const codexToys = createCodexToysBrowserClient();
-const schema = await codexToys.schema();
-const overview = await codexToys.workbench.overview();
-const threads = await codexToys.app.call("thread/list", { limit: 20 });
-```
-
-The browser client talks to the proxy with `fetch`; it does not include a direct
-app-server client or WebSocket transport.
-
-## CORS
-
-Direct browser calls to the proxy API receive CORS headers only for loopback
-origins such as `localhost`, `127.0.0.1`, `::1`, and `*.localhost`. Prefer the
-Vite plugin or `--static` same-origin serving for local dashboards.
-
-## Vite
-
-`codex-toys/proxy/vite` provides middleware for local dashboards that want the
-same proxy routes during development.
-
-The proxy remains an edge over the toybox. It does not own workflow semantics,
-queue semantics, product routing, or domain decisions.

package/docs/pages/components/toybox.md

@@ -1,108 +0,0 @@
----
-title: Toybox
-description: Local and SSH stdio runtime for codex-toys workbench methods.
----
-
-# Toybox
-
-The toybox is the stdio JSON-RPC runtime behind codex-toys workbench operation.
-It is not an HTTP service. Local commands spawn it over stdio. SSH commands start
-the same toybox on the remote host and speak JSON-RPC over SSH stdio.
-
-```bash
-codex-toys toybox serve --cwd <workbench>
-codex-toys --ssh <target> --cwd <remote-workbench> fetch
-```
-
-## Method Families
-
-`toybox.initialize` advertises available methods and metadata. Built-in method
-families include:
-
-- app-server pass-through through `app.call`
-- workflow list/run methods
-- workbench functions from `.codex/functions.ts`, `.js`, or `.mjs`
-- feed methods
-- delegation methods
-- dispatch, prompt queue, and local handoff methods
-- workbench doctor, task, and overview methods
-- host overview methods
-
-## Direct App Calls
-
-Use app calls for native Codex app-server methods:
-
-```bash
-codex-toys app thread/list '{"limit":20,"sourceKinds":[]}'
-codex-toys app thread/read --params-json '{"threadId":"<thread-id>"}'
-codex-toys --ssh <target> --cwd <remote-workbench> app thread/list '{"limit":20,"sourceKinds":[]}'
-```
-
-The toybox forwards those methods without turning them into workbench-owned
-state.
-
-## Workbench Calls
-
-Use workbench calls for toybox-owned behavior:
-
-```bash
-codex-toys workbench methods
-codex-toys workbench overview --json
-codex-toys workbench delegation.list
-codex-toys workbench dispatch.list --params-json '{"limit":5}'
-```
-
-The shorter command groups, such as `workbench delegate` and `workbench
-dispatch`, are CLI porcelain over these JSON-RPC methods.
-
-## SSH
-
-SSH operation keeps the command local while the workbench runs on the remote
-host.
-
-```bash
-codex-toys --ssh <target> --cwd <remote-workbench> remote preflight --json
-codex-toys --ssh <target> --cwd <remote-workbench> workbench doctor
-codex-toys --ssh <target> --cwd <remote-workbench> workflow run release-check --event event.json
-```
-
-Useful remote options:
-
-```bash
---ssh <target>
---cwd <remote-workbench>
---remote-path-prepend /home/user/.local/bin:/home/user/.bun/bin
---toybox-command /home/user/.local/bin/codex-toys
---codex-command /home/user/.local/bin/codex
---codex-arg -s --codex-arg danger-full-access
-```
-
-Useful environment variables:
-
-```bash
-CODEX_TOYS_REMOTE_SSH_TARGET=<target>
-CODEX_TOYS_REMOTE_CWD=<remote-workbench>
-CODEX_TOYS_REMOTE_PATH_PREPEND=/home/user/.local/bin:/home/user/.bun/bin
-CODEX_TOYS_TOYBOX_COMMAND=codex-toys
-CODEX_TOYS_REMOTE_CODEX_COMMAND=codex
-CODEX_TOYS_REMOTE_CODEX_ARGS=["-s","danger-full-access"]
-```
-
-SSH-backed `turn run` requires `--wait`, because the remote toybox exits when the
-command exits. Use delegation or dispatch queues for supervised background work.
-
-## Functions
-
-Workbench functions are JSON-in/JSON-out helpers loaded from the selected
-workbench.
-
-```bash
-codex-toys functions list --json
-codex-toys functions describe <name> --json
-codex-toys functions call <name> --params-json '{"key":"value"}' --json
-codex-toys --ssh <target> --cwd <remote-workbench> functions list --json
-```
-
-Functions are a good fit for dashboard snapshots and product-owned read/write
-helpers. The product owns function semantics; codex-toys owns discovery and
-transport.

package/docs/pages/guides/dashboard-over-toybox.md

@@ -1,145 +0,0 @@
----
-title: Dashboard Over Toybox
-description: Build a browser dashboard backed by the codex-toys proxy and workbench functions.
----
-
-# Dashboard Over Toybox
-
-A dashboard over toybox is a browser UI that talks to the optional
-`codex-toys-proxy` HTTP edge. The proxy forwards generic app and workbench calls
-to the toybox. It does not create a separate product API model.
-
-Use this guide when a workbench needs an inspectable browser surface for status,
-functions, queues, feed state, or operator actions.
-
-## 1. Start With Overview
-
-The default workbench snapshot is usually enough for a first dashboard:
-
-```bash
-codex-toys workbench overview --json
-```
-
-Serve static dashboard files through the proxy:
-
-```bash
-codex-toys-proxy serve --cwd . --static ./dashboard
-```
-
-The dashboard can call:
-
-```text
-GET  /api/status
-GET  /api/schema
-POST /api/workbench/overview
-POST /api/workbench/functions.list
-POST /api/workbench/functions.call
-```
-
-## 2. Use the Browser Client
-
-In browser code:
-
-```ts
-import { createCodexToysBrowserClient } from "codex-toys/proxy/browser";
-
-const codexToys = createCodexToysBrowserClient();
-const schema = await codexToys.schema();
-const overview = await codexToys.workbench.call("workbench.overview");
-const functions = await codexToys.functions.list();
-const snapshot = await codexToys.functions.call("statusSnapshot");
-```
-
-For a Vite dev server, use the Vite plugin:
-
-```ts
-import { codexToysRemote } from "codex-toys/proxy/vite";
-
-export default {
-  plugins: [
-    codexToysRemote({
-      cwd: process.cwd()
-    })
-  ]
-};
-```
-
-The Vite plugin serves the proxy under `/__codex_toys/api`. Point the browser
-client at that base path:
-
-```ts
-const codexToys = createCodexToysBrowserClient({
-  basePath: "/__codex_toys/api"
-});
-```
-
-## 3. Add Narrow Workbench Functions
-
-Create `.codex/functions.ts` when the dashboard needs data not already present
-in `workbench.overview`:
-
-```ts
-export default {
-  statusSnapshot: {
-    description: "Read a compact status snapshot.",
-    sideEffects: "read-only",
-    handler: async () => {
-      return {
-        status: "ok",
-        updatedAt: new Date().toISOString()
-      };
-    }
-  }
-};
-```
-
-Keep functions JSON-in and JSON-out. Return plain JSON values. Avoid streams,
-class instances, circular objects, BigInts, secrets, broad filesystem dumps, and
-arbitrary shell execution.
-
-Use side effects accurately:
-
-```text
-none
-read-only
-writes-local
-external-write
-```
-
-Dashboard code should treat `writes-local` and `external-write` functions as
-explicit actions, not background refresh calls.
-
-## 4. Use a Remote Workbench Without Remote HTTP
-
-Run the proxy locally and connect it to a remote toybox over SSH:
-
-```bash
-codex-toys-proxy serve \
-  --ssh workbox \
-  --cwd /srv/codex/workbenches/ops \
-  --static ./dashboard
-```
-
-Or configure Vite:
-
-```ts
-import { codexToysRemote } from "codex-toys/proxy/vite";
-
-export default {
-  plugins: [
-    codexToysRemote({
-      ssh: "workbox",
-      cwd: "/srv/codex/workbenches/ops"
-    })
-  ]
-};
-```
-
-The browser talks to localhost. The remote host exposes no HTTP port.
-
-## Boundary
-
-The proxy owns HTTP transport, schema discovery, browser helpers, and forwarding
-to app or workbench methods. The workbench owns functions and overview data. The
-product dashboard owns layout, refresh cadence, action confirmation, and domain
-policy.

package/docs/pages/guides/delegated-repo-work.md

@@ -1,119 +0,0 @@
----
-title: Delegated Repo Work
-description: Start and track Codex work in another checkout from a controlling workbench.
----
-
-# Delegated Repo Work
-
-Delegated repo work starts a normal Codex thread in another cwd and records the
-delegation in the controlling workbench. Use it when one workbench should fan
-out review, repair, or inspection tasks into sibling checkouts.
-
-Delegation is not the same as SSH. SSH chooses where the toybox runs.
-Delegation chooses where the Codex turn runs relative to that toybox's
-workbench root.
-
-## 1. Discover Targets
-
-From the controlling workbench:
-
-```bash
-codex-toys workbench delegate list --json
-```
-
-Common target forms:
-
-```text
-@
-@/repos/example
-@/workbenches/ops
-./relative-target
-```
-
-Absolute paths require deliberate opt-in with `--allow-absolute-cwd`.
-
-## 2. Start a Delegation
-
-Start and record a delegation:
-
-```bash
-codex-toys workbench delegate start \
-  --cwd @/repos/example \
-  --prompt "Inspect the current branch and report risks." \
-  --return-mode record_only
-```
-
-Wait for completion when the caller needs the result immediately:
-
-```bash
-codex-toys workbench delegate start \
-  --cwd @/repos/example \
-  --prompt "Run the focused test suite and summarize failures." \
-  --wait
-```
-
-Use return modes to describe how the caller should be notified:
-
-```text
-detached
-record_only
-wake_on_done
-wake_on_group
-manual
-```
-
-## 3. Delegate Through SSH
-
-With SSH, `--cwd` selects the remote controlling workbench. The delegated target
-uses `--target-cwd`:
-
-```bash
-codex-toys --ssh workbox --cwd /srv/codex/root workbench delegate start \
-  --target-cwd @/repos/example \
-  --prompt "Review the repository status." \
-  --return-mode record_only
-```
-
-The remote toybox resolves `@/repos/example` under `/srv/codex/root`.
-
-## 4. Delegate From a Workflow
-
-Workflow scripts can delegate when they run through the workbench surface:
-
-```ts
-export default async function run(context) {
-  const delegation = await context.delegate.start({
-    cwd: "@/repos/example",
-    prompt: "Inspect this repository and summarize risks.",
-    returnMode: "wake_on_done"
-  });
-
-  return { status: "delegated", delegation };
-}
-```
-
-`context.delegate.*` requires the toybox/workbench surface. It is not available
-when a workflow deliberately runs through direct app-server calls.
-
-## 5. Choose Delegation vs Dispatch Queues
-
-Use delegation when:
-
-- the work belongs in another checkout
-- the target should get a normal Codex thread
-- the controlling workbench should keep a delegation record
-
-Use dispatch queues when:
-
-- the work should run later
-- retries, attempts, output capture, or claiming matter
-- the target is a prompt, command, workflow, task, or handoff intent
-
-Use direct SSH `turn run --wait` only for short remote checks tied to the
-current command lifecycle.
-
-## Boundary
-
-The controlling workbench owns target resolution and delegation records. The
-target Codex thread owns its own prompts, tools, files, and output. The caller
-owns return policy and any follow-up action after the delegated work completes.

package/docs/pages/guides/remote-codex-workbench.md

@@ -1,147 +0,0 @@
----
-title: Remote Codex Workbench
-description: Set up a VPS as a separate Codex workbench and operate it from local over SSH.
----
-
-# Remote Codex Workbench
-
-A remote Codex workbench is a separate Codex environment on a VPS or other SSH
-host. The local machine sends commands over SSH. The remote machine owns Codex
-auth, Codex state, the workbench root, and command execution.
-
-Use this guide when the remote host should run Codex work while local tools
-inspect or control it without opening a remote HTTP service.
-
-## 1. Prepare the Remote Host
-
-Install these on the remote host:
-
-```text
-node
-codex
-codex-toys
-git
-```
-
-Create or choose a workbench root:
-
-```bash
-mkdir -p /srv/codex/workbenches/ops
-cd /srv/codex/workbenches/ops
-codex-toys workbench doctor --json
-```
-
-Authenticate Codex on the remote host. Commands sent through `--ssh` use the
-remote Codex home and remote config; they do not use local Codex auth.
-
-## 2. Verify SSH Preflight
-
-From the local machine:
-
-```bash
-codex-toys --ssh <host-or-alias> --cwd /srv/codex/workbenches/ops remote preflight --json
-codex-toys --ssh <host-or-alias> --cwd /srv/codex/workbenches/ops fetch
-codex-toys --ssh <host-or-alias> --cwd /srv/codex/workbenches/ops workbench doctor --json
-```
-
-Prefer a stable OpenSSH host alias when possible:
-
-```bash
-codex-toys --ssh workbox --cwd /srv/codex/workbenches/ops fetch
-```
-
-The local command starts `codex-toys toybox serve` on the remote host over SSH
-stdio. No backend tunnel, remote WebSocket URL, or long-running remote service
-is required.
-
-## 3. Fix Non-Interactive PATH
-
-Non-interactive SSH often has a smaller PATH than an interactive shell. If
-preflight cannot find Node, Codex, or codex-toys, pass explicit paths:
-
-```bash
-codex-toys \
-  --ssh workbox \
-  --cwd /srv/codex/workbenches/ops \
-  --remote-path-prepend /opt/node/bin:/usr/local/bin \
-  --toybox-command /usr/local/bin/codex-toys \
-  --codex-command /usr/local/bin/codex \
-  workbench doctor --json
-```
-
-Equivalent environment defaults:
-
-```text
-CODEX_TOYS_REMOTE_SSH_TARGET=workbox
-CODEX_TOYS_REMOTE_CWD=/srv/codex/workbenches/ops
-CODEX_TOYS_REMOTE_PATH_PREPEND=/opt/node/bin:/usr/local/bin
-CODEX_TOYS_TOYBOX_COMMAND=/usr/local/bin/codex-toys
-CODEX_TOYS_REMOTE_CODEX_COMMAND=/usr/local/bin/codex
-CODEX_TOYS_REMOTE_CODEX_ARGS=["-s","danger-full-access"]
-```
-
-Keep private SSH keys local. If a managed identity is not available to OpenSSH,
-add a local SSH config entry instead of copying keys to the remote host.
-
-## 4. Run Remote Work
-
-Use direct remote calls for quick checks:
-
-```bash
-codex-toys --ssh workbox --cwd /srv/codex/workbenches/ops functions list --json
-codex-toys --ssh workbox --cwd /srv/codex/workbenches/ops workflow list --json
-codex-toys --ssh workbox --cwd /srv/codex/workbenches/ops workflow run release-check --event event.json
-```
-
-SSH-backed `turn run` must wait because the remote toybox exits when the command
-exits:
-
-```bash
-codex-toys --ssh workbox --cwd /srv/codex/workbenches/ops turn run \
-  "Check workbench status." \
-  --wait \
-  --sandbox danger-full-access \
-  --approval-policy never
-```
-
-For background work, use workbench delegation or dispatch queues instead of a
-detached SSH command.
-
-## 5. Inspect Remote State
-
-Remote state stays remote:
-
-```text
-<remote-workbench>/.codex/workbench/local/
-<remote-workbench>/.codex/feed/local/
-<remote-codex-home>/sessions/
-<remote-codex-home>/memories/
-```
-
-The local machine receives command results over SSH. It does not automatically
-copy remote Codex sessions, memories, or workbench state.
-
-## 6. Optional Local Dashboard
-
-For a browser UI, run the proxy locally and let it speak SSH to the remote
-toybox:
-
-```bash
-codex-toys-proxy serve \
-  --ssh workbox \
-  --cwd /srv/codex/workbenches/ops \
-  --static ./dashboard
-```
-
-The browser talks to the local proxy. The remote host still exposes no HTTP
-port.
-
-## Troubleshooting
-
-- `remote preflight` fails before toybox startup: SSH target, remote cwd,
-  remote PATH, Node, Codex, or codex-toys is missing.
-- Toybox starts but app calls fail: inspect remote Codex auth and remote Codex
-  config.
-- Shell commands inside a turn are blocked: pass a sandbox mode or permissions
-  profile supported by the remote Codex config.
-- Inline JSON fails in a shell: use `--params-file` instead of inline JSON.

package/docs/pages/primitives/delegation.md

@@ -1,74 +0,0 @@
----
-title: Delegation
-description: Start, track, and return Codex work in another workbench-relative cwd.
----
-
-# Delegation
-
-Delegation starts normal Codex threads in another cwd and records workbench
-metadata under `.codex/workbench/local/delegations.json`.
-
-Use delegation when background work should be supervised by the toybox instead
-of tied to a single SSH command lifecycle.
-
-```bash
-codex-toys workbench delegate list --json
-codex-toys workbench delegate start --cwd @/repos/example --prompt "Inspect this repository."
-codex-toys workbench delegate start --cwd @/workbenches/ops --prompt "Run the check." --wait
-```
-
-## Cwd Rules
-
-Delegation cwd values are resolved relative to the toybox workbench root:
-
-- `@` means the workbench root
-- `@/repos/name` means a path under the workbench root
-- `@/workbenches/name` means a path under the workbench root
-- relative paths are resolved under the workbench root
-- absolute paths require `--allow-absolute-cwd`
-
-For SSH, `--cwd` selects the remote workbench root and `--target-cwd` selects the
-delegated target inside that remote root:
-
-```bash
-codex-toys --ssh <target> --cwd <remote-root> workbench delegate start \
-  --target-cwd @/repos/example \
-  --prompt "Review the branch"
-```
-
-## Return Modes
-
-Delegations can record return behavior:
-
-- `detached`: start and record, no return wake
-- `record_only`: record result for manual collection
-- `wake_on_done`: wake the requesting thread when this delegation finishes
-- `wake_on_group`: wake when the delegation group finishes
-- `manual`: operator-managed return
-
-```bash
-codex-toys workbench delegate start \
-  --cwd @/repos/example \
-  --prompt "Run the review." \
-  --return-mode wake_on_done
-```
-
-## Workflow Integration
-
-Workflow scripts can delegate through `context.delegate.start` when running via
-the workbench surface:
-
-```ts
-export default async function run(context) {
-  const delegated = await context.delegate.start({
-    cwd: "@/repos/example",
-    prompt: "Inspect this repository and report findings.",
-    returnMode: "record_only"
-  });
-
-  return { status: "delegated", delegated };
-}
-```
-
-`context.delegate.read` and `context.delegate.wait` can refresh or wait on the
-recorded delegation.