@mquan/portal 0.0.1

package/docs/remote-demo.md

@@ -0,0 +1,346 @@
+# Remote agent collaboration demo
+
+Status: implemented locally; public packaging and tunnel validation deferred
+Updated: 2026-09-05
+
+## Goal
+
+Demonstrate two people on different computers starting Portal-managed Codex
+agents, discovering one another through a temporary public endpoint, agreeing
+on a task, working independently in parallel, and exchanging progress and
+results without either person copying messages between sessions.
+
+Target host experience after distribution and tunnel setup:
+
+```bash
+npx -y @mquan/portal@demo serve --listen 127.0.0.1:8787
+ngrok http 8787
+
+npx -y @mquan/portal@demo codex \
+  --agent kai \
+  --server wss://abc.ngrok.app/ws
+```
+
+Friend:
+
+```bash
+npx -y @mquan/portal@demo codex \
+  --agent leo \
+  --server wss://abc.ngrok.app/ws
+```
+
+The demo package is published under the `demo` dist-tag so it cannot replace a
+future stable `latest` release. Tunnel-provider automation remains deferred.
+
+## Demo contract
+
+1. `portal serve` runs an in-memory registry and WebSocket message relay on the
+   host computer. It binds to loopback and is exposed through an HTTPS tunnel
+   that supports WebSocket upgrades.
+2. `portal codex --agent <name> --server <url>` lazily initializes Portal,
+   starts or connects to the local daemon, launches a Portal-managed Codex
+   session, and advertises only that session to the specified server.
+3. An agent can list or search live agents connected to the same server.
+   Discovery is server-wide for this demo. Names are not reserved or verified;
+   ambiguous names return candidates and perform no action.
+4. An agent can send a non-blocking task offer to a discovered agent. The
+   target sees a new attributed Codex turn automatically and can accept or
+   decline it.
+5. An accepted task runs under the target Codex session's existing sandbox and
+   approval policy. Both agents can continue working independently and send
+   task-scoped updates.
+6. Completion, failure, questions, and progress are routed back into the peer
+   session as new turns. No inbox polling or human message relay is required.
+
+This demo does not require Git or a shared filesystem. Tasks may produce a
+textual answer, tool result, file summary, URL, patch, commit, or any other
+artifact reference the agents agree to exchange.
+
+## Architecture
+
+```text
+host Codex                                       friend Codex
+    |                                                 |
+managed runner                                  managed runner
+    |                                                 |
+host portald                                     friend portald
+    |                                                 |
+    +------ outbound WebSocket ----+---- WebSocket ---+
+                                   |
+                            ngrok HTTPS tunnel
+                                   |
+                    local `portal serve` process
+                    registry | presence | relay
+```
+
+Both daemons initiate outbound connections, so the friend does not expose an
+inbound port. Messages remain relayed through the server for this phase. P2P,
+STUN, TURN, and direct connection negotiation add no value to the demo and are
+deferred.
+
+The daemon owns remote connections and multiplexes its managed sessions over
+them. Connections are keyed by normalized server URL so sessions may join
+different demo servers without interfering with one another.
+
+## Server behavior
+
+`portal serve` provides:
+
+- `GET /health` for tunnel and operator diagnostics;
+- `WS /ws` for presence, discovery, task events, and acknowledgements;
+- an in-memory connection table;
+- an in-memory live-agent registry with renewable leases; and
+- envelope routing between currently connected clients.
+
+Initial protocol operations:
+
+```text
+client.hello
+agent.register
+agent.renew
+agent.unregister
+agent.discover
+envelope.send
+envelope.acknowledge
+```
+
+An advertised agent record contains only bounded metadata:
+
+```json
+{
+  "routeId": "route_a81d",
+  "sessionId": "ps_56d0",
+  "agentName": "leo",
+  "provider": "codex",
+  "description": "Implementation coding agent",
+  "capabilities": ["message", "task"],
+  "state": "available",
+  "expiresAt": "2026-09-05T20:01:00Z"
+}
+```
+
+The server never receives transcripts, absolute filesystem paths, environment
+variables, process details, or historical session inventory. A disconnected
+agent disappears after its presence lease expires. Server restart clears all
+connections and registrations.
+
+## Collaboration flow
+
+```text
+discover -> offer -> accept/decline -> progress/questions -> complete/fail
+```
+
+The initiator uses a non-blocking delegation tool. This is separate from the
+current blocking `portal.send` behavior so the initiating agent can keep
+working while its peer runs.
+
+A task has a globally unique ID, sender and target routes, objective, optional
+context and expected result, timestamps, expiry, and a correlated event
+stream. The minimum state machine is:
+
+```text
+offered ----> accepted ----> running ----> completed
+   |                            |
+   +-------> declined           +-------> failed
+```
+
+Starting a remote task creates a visible turn in the target Codex session. The
+target calls an MCP action to accept or decline. Acceptance is immediately
+sent back to the initiator; it does not wait for the target turn to finish.
+Progress, questions, and final results are durable in each local Portal
+database and are delivered to a managed session when it is ready for another
+turn. Portal never starts two concurrent turns in the same Codex session.
+
+## Trust boundary for the demo
+
+There are no accounts, verified identities, signing keys, relationship records,
+or authorization grants. Agent names and installation identifiers are
+self-asserted. The tunnel URL is an ephemeral demo-room address, not a security
+credential.
+
+Every remote agent and event must therefore be labeled `unauthenticated` in
+tool results and injected turns. Only sessions explicitly launched with both
+`--agent` and `--server` are remotely advertised. Vendor sandbox and approval
+settings remain unchanged, and Portal never auto-approves a tool action.
+
+Anyone who learns the tunnel URL can discover agents, impersonate a name, and
+send task offers. The server must not be used with sensitive sessions or left
+running after the demonstration. These constraints are acceptable only for a
+controlled validation and must block production positioning.
+
+## Milestones
+
+### M0: Protocol and process contract
+
+Status: complete.
+
+Define versioned schemas for presence, discovery, envelopes, task events, and
+acknowledgements. Define limits for names, descriptions, message size, task
+expiry, heartbeat interval, and protocol mismatch errors. Add a transport
+interface so the local message service does not depend directly on WebSocket
+implementation details.
+
+Checkpoint:
+
+- protocol fixtures round-trip through validation;
+- unknown versions and malformed or oversized messages are rejected;
+- a documented compatibility rule determines whether two versions may talk;
+- existing local messaging tests remain unchanged and pass.
+
+### M1: Local registry and WebSocket relay
+
+Status: complete.
+
+Add `portal serve --listen <address>`. Implement the health endpoint,
+WebSocket lifecycle, live presence leases, discovery queries, envelope
+forwarding, and delivery acknowledgements. Keep all network state in memory.
+
+Checkpoint:
+
+- two test clients connect to the local server;
+- one registers `leo`, the other discovers it;
+- disconnect or missed heartbeats removes `leo` within the lease window;
+- duplicate names return both candidates;
+- an envelope is delivered once and acknowledged;
+- the server binds to `127.0.0.1` by default.
+
+### M2: Daemon remote presence and discovery
+
+Status: complete for explicitly advertised managed Codex sessions.
+
+Teach `portald` to open and reuse connections keyed by server URL. Associate a
+managed session with its selected server, publish it after the real Codex
+session ID is known, renew its lease, and unregister it on exit. Merge remote
+results into a new MCP discovery tool without treating them as local indexed
+sessions.
+
+Checkpoint:
+
+- two daemons connected to one local server discover each other's advertised
+  sessions;
+- unadvertised observed and historical sessions never leave the machine;
+- exact unique names resolve and ambiguous names do not send;
+- tunnel interruption produces a visible unavailable state and reconnects;
+- sessions connected to different server URLs remain isolated.
+
+### M3: Remote invitation and visible delivery
+
+Status: complete.
+
+Route a remote task offer through the server and import it into the target's
+existing managed-runner queue. Represent the sender as an explicit remote,
+unauthenticated peer rather than a locally observed vendor session. Preserve
+event IDs, attribution, correlation, expiry, and idempotency across the relay.
+
+Checkpoint:
+
+- agent A sends an offer to agent B on another daemon;
+- B receives a visible attributed Codex turn without checking an inbox;
+- replaying an event does not create a second turn;
+- invalid, expired, unknown-target, and disconnected-target deliveries fail
+  clearly;
+- the target transcript and MCP result both say the sender is unauthenticated.
+
+### M4: Asynchronous task agreement and collaboration
+
+Status: complete for managed Codex sessions.
+
+Add non-blocking task delegation and task-scoped event tools. Support offer,
+accept, decline, progress, question, completion, and failure. Update managed
+agent instructions so a target explicitly accepts or declines before acting,
+and so results automatically return to the initiating session.
+
+Checkpoint:
+
+- A delegates to B and continues its own turn without waiting for B;
+- B accepts and A automatically sees the acceptance;
+- both agents execute work concurrently;
+- B sends a question or progress update and receives A's response;
+- B completes and A automatically receives the correlated result;
+- no session receives simultaneous Codex turns;
+- failure and disconnect leave an inspectable terminal or retryable state.
+
+### M5: Single-command local UX
+
+Status: implemented; clean-tarball validation is complete, publication remains deferred.
+
+Make `portal codex` lazily initialize local state and start a compatible
+daemon. Add `--agent` and `--server`, with `--server` taking precedence over an
+environment variable or stored default. Keep `portal run codex` temporarily as
+a compatibility alias. Validate the packaged layout locally without publishing
+it.
+
+Checkpoint:
+
+- `npm pack` installs and runs in a clean temporary directory;
+- the packed tarball installs and `portal codex --agent leo --server <url>`
+  works from a clean temporary environment;
+- a stale daemon is detected through a version handshake and restarted safely;
+- Portal flags are not forwarded to Codex, while arguments after `--` are;
+- exiting Codex unregisters the advertised agent and cleans up its lease.
+
+### M6: Two-machine demonstration
+
+Status: two isolated local daemons pass; physical two-Mac/tunnel validation remains deferred.
+
+First run two isolated Portal daemons and managed-agent fixtures against the
+local server. Once a tunnel provider and package distribution are selected,
+repeat the same protocol flow across two Macs without changing the application
+protocol. Execute a task that requires negotiation, parallel work, at least one
+progress exchange, and a returned result.
+
+Checkpoint:
+
+- the local two-daemon flow passes before tunnel or npm publication work;
+- later, the friend uses only the supplied single command after installing
+  Codex;
+- the initiating agent discovers the friend's agent without a session ID;
+- both users visibly see offer, acceptance, progress, and completion;
+- the agents collaborate without either user relaying text;
+- logs correlate every hop by task and event ID;
+- the demo succeeds twice from a fresh server process.
+
+## Execution order
+
+M0 is the integration boundary. After it lands, the M1 server and most of the
+M2 daemon connection work can proceed in parallel. M3 joins those paths. M4
+depends on reliable remote delivery, and M5 should package the behavior only
+after the protocol is stable. M6 is the release gate.
+
+```text
+M0 ---> M1 ---+
+   \           +---> M3 ---> M4 ---> M5 ---> M6
+    +---> M2 --+
+```
+
+## Reuse from the local MVP
+
+- user-only daemon and JSON-RPC control plane;
+- SQLite persistence;
+- Portal-managed Codex app-server and runner;
+- automatic visible-turn delivery;
+- session profiles and ambiguity-safe resolution;
+- MCP injection and session credentials;
+- message IDs, reply correlation, idempotency, rate limits, and receipts; and
+- captured Codex answers and bounded tool-result summaries.
+
+The remote path extends these components but does not expose the local RPC
+socket or local session credential to the network.
+
+## Not in scope
+
+- production authentication, authorization, invitations, blocking, or abuse
+  controls;
+- durable public names, accounts, or a production nameserver;
+- offline remote delivery or persistence in the relay;
+- public deployment of the Portal server;
+- npm publication and package-name selection;
+- tunnel-provider selection and tunnel setup automation;
+- end-to-end encryption;
+- peer-to-peer transport, WebRTC, STUN, or TURN;
+- remote transcript recall;
+- automatic artifact synchronization or Git workflows;
+- Claude or unmanaged Codex active delivery;
+- browser, desktop, and Slack sessions;
+- a Portal-owned autonomous supervisor agent; and
+- production availability, scaling, federation, or multi-region operation.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@mquan/portal",
+  "version": "0.0.1",
+  "description": "Local cross-agent session awareness, recall, and messaging",
+  "type": "module",
+  "bin": {
+    "portal": "./dist/src/cli.js",
+    "portal-mcp": "./dist/src/mcp.js"
+  },
+  "files": [
+    "dist/src",
+    "docs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "demo"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "dev": "node --import tsx src/cli.ts",
+    "mcp": "node --import tsx src/mcp.ts",
+    "probe:codex": "node --import tsx src/provider/codex/probe.ts",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "probe:claude": "PORTAL_REAL_CLAUDE_PROBE=1 node --import tsx --test test/claude-provider.real.test.ts",
+    "prepack": "npm run check && npm test && npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.251",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "ws": "^8.21.3",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "@types/ws": "^8.18.1",
+    "tsx": "latest",
+    "typescript": "latest"
+  },
+  "overrides": {
+    "qs": "6.16.0"
+  }
+}