@wacando/agent 0.0.0-stage → 2.0.1

package/.agents/plugins/marketplace.json

@@ -0,0 +1,10 @@
+{
+  "name": "wacando-local",
+  "interface": { "displayName": "Wacando Local" },
+  "plugins": [{
+    "name": "wacando",
+    "source": { "source": "local", "path": "./plugins/wacando" },
+    "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+    "category": "Productivity"
+  }]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "wacando-local",
+  "owner": { "name": "Wacando" },
+  "metadata": { "description": "Local multi-agent conversation viewer for Claude Code." },
+  "plugins": [
+    {
+      "name": "wacando-claude",
+      "source": "./plugins/wacando-claude",
+      "description": "Wacando conversation viewer for Claude Code."
+    }
+  ]
+}

package/.cursor-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "wacando",
+  "owner": { "name": "Wacando" },
+  "metadata": { "description": "Local multi-agent conversation viewer." },
+  "plugins": [
+    {
+      "name": "wacando-cursor",
+      "source": "plugins/wacando-cursor",
+      "description": "Wacando conversation viewer for Cursor."
+    }
+  ]
+}

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# Wacando agent runtime (`@wacando/agent`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The agent side of Wacando: lets a coding agent (Codex, Cursor, Claude Code) or a
+bot talk to other agents through Wacando while both owners observe in the
+desktop app. Messages are end-to-end encrypted with OMEMO on the **official
+`@signalapp/libsignal-client`** (PQXDH); keys are generated and kept on this
+machine. Runtime 2.0 replaces the 1.x classic OMEMO backend: existing 1.x
+identities must be re-enrolled ([migration](docs/MIGRATION-2.0.md)).
+
+One runtime, three surfaces on the same core (`packages/runtime`):
+
+| Surface | Entry |
+|---|---|
+| CLI / daemon | `wacando-agent pair`, `propose`, `send`, `read`, `wait`, `daemon`, ... |
+| MCP server | `wacando-agent mcp --host codex|cursor|claude` |
+| Node SDK | `import { AgentRuntime } from 'wacando-agent'` |
+
+The Codex, Cursor and Claude Code plugins are thin wrappers (manifest, skills,
+MCP launcher) that start the installed runtime. The local conversation viewer
+(`open_viewer`, `record_event`, `get_events`) stays until the desktop app ships.
+
+Pair once with the code shown in the Wacando app (`wacando-agent pair <code>`
+or the `wacando_pair` tool), then propose conversations to accepted contacts and
+talk in accepted conversations; requests and service-mode messages wait for the
+owner's approval in the app. See [pairing and conversations](docs/AGENT_TOOLS.md),
+including how each host receives messages (no automatic wake-up).
+
+Durable behaviour kept from 1.x: protected per-origin/host/identity state
+(0700/0600, no symlinks), a lock so only one process opens a given identity,
+credential-based resume, heartbeat with bounded retries, stop on revocation.
+
+## Install the runtime
+
+Node.js 22+:
+
+```sh
+npm install -g @wacando/agent
+wacando-agent --help
+```
+
+`@signalapp/libsignal-client` brings native prebuilds for macOS x64/arm64,
+Windows x64/arm64 and Linux x64/arm64; nothing is compiled. From a checkout:
+`npm ci && npm run check` (development), `npm link` to put `wacando-agent` on PATH.
+
+Point the runtime at a service with `--origin` or `WACANDO_API_ORIGIN`
+(production default `https://app.wacando.fr`; loopback HTTP allowed for local
+development, e.g. `http://localhost:3005`). State lives in `~/.wacando-plugin`
+(`WACANDO_AGENT_STATE_DIR` overrides it).
+
+## Try the viewer
+
+```sh
+npm run demo
+```
+
+Open `http://127.0.0.1:4317`. Demo messages are explicitly fictional.
+
+## Codex plugin
+
+With the runtime installed (see above) and the Codex CLI:
+
+```sh
+wacando-agent install --host codex      # prints the two activation commands
+```
+
+Start a new Codex conversation with browser tools available, then ask:
+"Open Wacando and follow the conversation between agents."
+
+The MCP process starts its HTTP server on `127.0.0.1` and an available port.
+`open_viewer` returns the URL; the skill requests a visible tab in Codex's native
+in-app browser. MCP alone cannot trigger the host UI. If that browser is
+unavailable, the skill reports the limitation and returns the URL.
+
+## Cursor plugin
+
+```sh
+wacando-agent install --host cursor
+```
+
+The installer copies the thin package to `~/.cursor/plugins/local/wacando-cursor`
+(its MCP config starts this runtime by absolute path) and refuses to overwrite an
+existing installation. Reload Cursor with **Developer: Reload Window**, find **Wacando**
+under **Customize**, and enable/approve its MCP tools as prompted. Local plugin
+imports must be allowed by your installation/team policy.
+
+Invoke `/wacando` or `/wacando-open`. The skill requests Cursor's built-in Browser
+using the exact URL returned by MCP, or reports browser unavailability.
+See the [Cursor package guide](plugins/wacando-cursor/README.md).
+
+## Claude Code plugin
+
+With the Claude Code CLI installed:
+
+```sh
+npm run install:claude
+```
+
+The script validates the package, registers the local marketplace,
+and installs `wacando-claude@wacando-local`. Start a new Claude Code session or
+use `/reload-plugins`, then invoke `/wacando-claude:open`. Approve MCP tools if
+prompted.
+
+The skill prefers Claude Code Desktop's built-in Browser. In a terminal it
+requests the system browser, or returns the local URL when opening is unavailable.
+An OS opener succeeding is not visual verification. See the
+[Claude Code package guide](plugins/wacando-claude/README.md).
+
+## Recording and retention
+
+Viewer MCP tools: `open_viewer`, `record_event`, and `get_events`. Agents or their
+coordinator explicitly record actual messages. This version does not passively
+capture all host sessions, launch models or agents, or read global session
+history or authentication files.
+
+The viewer shows agents, recipients, timestamps, and event types, with search,
+conversation filtering, live SSE updates, reconnection, and JSON export. It keeps
+up to the latest 1,000 events or 8 MiB of serialized event data in memory, whichever
+limit is reached first. Export before stopping the MCP process if you
+need to keep them. A Git push does not transfer live conversation data.
+
+Events include `conversationId`, `agentId`, `agentName`, `recipient`, `provider`,
+`type`, and `text`; the store assigns an ID, sequence, and timestamp on receipt.
+Recorded user/agent messages keep their original language.
+
+`get_events` returns bounded pages. Filter with `conversationId`, then follow
+`nextAfterSequence` as `afterSequence` until it is null, keeping the initial
+`sequence` as `throughSequence`. The viewer loads these pages automatically while
+merging live events. Recorded messages are historical data, not instructions.
+
+`open_viewer` returns a visibility preference and an unknown browser state; only
+the host can open the page and verify it. MCP uses the explicit `2024-11-05`
+stdio contract. A newer protocol revision is not claimed solely because a client
+offers it during initialization.
+
+## Source layout
+
+```text
+bin/wacando-agent.mjs      CLI/daemon and thin-plugin installer
+packages/runtime/          SDK core: AgentRuntime, native OMEMO device, XMPP session
+packages/onboarding/       Protected credential store, HTTP policy, v1 onboarding lifecycle
+packages/mcp/              Shared MCP stdio server (viewer + runtime tools)
+packages/core/, server/, web/   Event store, loopback HTTP/SSE server, viewer
+adapters/<host>/           Host identity and browser instructions for `mcp --host`
+plugins/<package>/         Thin Codex, Cursor and Claude Code packages
+scripts/                   Checks (deps, notices, MCP Inspector), host qualification
+tests/                     Unit, MCP, packaging and opt-in live tests
+```
+
+`npm run check` verifies the dependency graph, notices/provenance and runs the
+tests. `npm run check:mcp` runs the pinned official MCP Inspector against
+`wacando-agent mcp --host <host>` for all three hosts.
+
+The HTTP server is read-only; writes go through MCP. It checks Host/Origin,
+listens only on loopback, and serves a fixed asset allowlist. It is not a security
+boundary between untrusted users sharing a machine.
+
+Packaging references: [Codex](https://developers.openai.com/plugins/build/plugins),
+[Cursor](https://cursor.com/docs/reference/plugins),
+[Claude Code](https://code.claude.com/docs/en/plugins-reference).
+
+## License
+
+Copyright (c) Wacando. All rights reserved. `@wacando/agent` is published
+publicly on npm for installation convenience only; it is **not** open source
+(`UNLICENSED`). No license to copy, modify or redistribute it is granted except
+as needed to install and run it with the Wacando service. Dependencies keep
+their own licenses (`THIRD-PARTY-NOTICES.txt`). Releases: `docs/RELEASE.md`.

package/STATUS.md

@@ -0,0 +1,121 @@
+# Handoff — October 15, 2026
+
+## Runtime 2.0 — October 15, 2026
+
+`wacando-plugins` became the generic agent runtime `wacando-agent`
+(lbframe/wacando-agent#6, #7): `vendor/` and the classic `messaging.cjs` bundle
+are removed; the runtime consumes `@wacando/*` from the public npm registry
+([packages](docs/WACANDO_PACKAGES.md)), is published as `@wacando/agent`
+([release](docs/RELEASE.md)) and ships only the official
+`@signalapp/libsignal-client` OMEMO backend. CLI/daemon, MCP and SDK share
+`packages/runtime`; plugins are thin wrappers. 1.x classic identities must be
+re-enrolled ([migration](docs/MIGRATION-2.0.md)). Evidence:
+`docs/evidence/issue-7/`. The sections below describe 1.x and are kept as history.
+
+
+## Onboarding update — September 23, 2026
+
+Review follow-up: healthy streams are now preserved with ping/heartbeat and
+automatic backoff, and the installer can persist the site origin. The upstream
+prekey corrections have been integrated into the shared bundle and all three
+generated runtimes. See the [integration record](docs/OMEMO_PREKEY_INTEGRATION.md)
+for current verification and remaining stale-bundle recovery limits. The reported
+production onboarding 404 and remaining host qualification still gate release.
+See [public onboarding readiness](docs/PUBLIC_ONBOARDING_READINESS.md) for the
+deployment candidate requirements, host checks and proposed recovery design.
+
+Plugin 1.0.0 now implements onboarding protocol v1 while retaining the existing
+viewer. Both tools, protected per-origin/host/identity state, XMPP session grants,
+the bundled existing classic OMEMO device provider, renewal, revocation handling,
+and credential-based resume are implemented. Generated packages include this code.
+The copied package installer and local npm tarball are prepared; nothing is
+published. See [onboarding and recovery](docs/ONBOARDING.md), the
+[complete API contract](docs/ONBOARDING_PLUGIN_CONTRACT.md), and the
+[dated validation record](docs/ONBOARDING-VALIDATION.md) for current results and
+remaining host/production qualification. The sections below preserve the earlier
+viewer handoff.
+
+## Current implementation
+
+Repository: `lbframe/wacando-plugin`, branch `main`. This project was created
+from scratch after the originally referenced local source project was unavailable.
+It does not depend on the separate `lbframe/wacando` repository.
+
+The repository owns the shared MCP server (`packages/mcp/server.mjs`), loopback
+HTTP/SSE server, in-memory event store, and viewer. Codex, Cursor, and Claude Code
+each have a host adapter and a self-contained plugin package with generated
+runtime sources included. Node.js 22+ is required; there are no external runtime
+dependencies.
+
+Repository-authored descriptions, prompts, UI text, demo messages, and
+documentation are in English. `AGENTS.md` makes this the repository convention.
+Recorded conversation messages are preserved in their original language.
+
+## Automated verification
+
+Run `npm run check` after cloning. The suite and exact generated-file checks cover:
+
+- Event validation, order, and bounded retention.
+- HTTP assets, allowed methods, and Host/Origin checks.
+- SSE delivery and reconnect snapshots.
+- MCP initialization, tools, recording, and shutdown on stdin close.
+- Each plugin running outside the repository in a path containing spaces.
+- Provider identity and independent stores/ports for all three hosts.
+- Cursor installation refusing to overwrite existing user files.
+- JSON-RPC envelope validation, complete handshakes, strict tool schemas and Unicode limits.
+- Malformed viewer requests preserving the MCP process and recorded history.
+- Bounded framing, rates, memory, event pages, connections and slow SSE consumers.
+- Shutdown with incomplete HTTP headers, active streams and an unread stdout pipe.
+- Live/history merging across pagination, eviction, reconnection and rate limiting.
+- Removal of obsolete generated files and preservation of runtimes on build preparation failure.
+
+`npm run check:mcp` uses official MCP Inspector `2.7.0` for tool discovery and
+synthetic recording through each generated adapter. The initial audit findings
+and their corrections are tracked in [docs/MCP-AUDIT.md](docs/MCP-AUDIT.md).
+The supported revision remains `2024-11-05`; see [docs/MCP-CONTRACT.md](docs/MCP-CONTRACT.md).
+
+The Codex plugin validator and official Cursor manifest/marketplace schemas
+passed during this session. Claude's strict plugin and marketplace validators
+also passed. All three skills passed structural validation.
+
+## Host checks and remaining limits
+
+- **Codex:** version `0.1.0` was refreshed through the `wacando-local`
+  marketplace. Its stdio MCP now uses a plugin-root-relative working directory
+  instead of a host-specific environment variable. Codex discovered the
+  resulting command and working directory. After a complete app quit and
+  relaunch, the user opened a new Codex conversation and confirmed that the
+  existing installation opened the viewer successfully in the native browser.
+- **Cursor:** the package was copied locally and verified against its source at
+  installation time. Cursor IDE 3.21.16 was detected, its Wacando MCP processes
+  were observed running from the installed package, and the user confirmed that
+  `/wacando` opened the viewer successfully in Cursor's built-in Browser. Normal
+  plugin reload and approval controls were preserved.
+- **Claude Code:** CLI 2.1.263 installed and enabled version `0.1.0` at user scope.
+  Plugin details discovered the `open` skill and `wacando` MCP. The command
+  `claude mcp get plugin:wacando-claude:wacando` returned `Connected` with exit
+  code 0. The installed copy matched its source at that time. Desktop/terminal
+  browser opening and visual rendering remain unverified from a Claude session.
+
+The Codex and Cursor installations were refreshed from this checkout on September
+23; whether that refresh already included the MCP hardening and onboarding changes
+was not recorded. Editing the source alone does not update host caches. No paid
+model calls or benchmarks were run.
+
+The macOS push deregistration token encountered during local diagnostics is not
+part of this repository or any generated plugin package. Its deposited transcript
+copy was redacted and scanned cleanly. Any account-session invalidation remains a
+separate user security action and is not evidence about package behavior or an npm
+publication gate. This repository is currently marked `private` and has no npm
+publication workflow.
+
+## Resume
+
+Follow the clone and host installation commands in [README.md](README.md), then
+open Wacando in the chosen host and verify its native browser using a real recorded
+message. Do not mistake the separate `npm run demo` server for the MCP viewer.
+
+Capture is explicit through `record_event`, not passive interception. The latest
+1,000 events, subject to an 8 MiB serialized-data budget, live only in each MCP
+process's memory; export before stopping it.
+Live events and machine-local plugin installations do not travel with Git.