@envarai/connect 2026.1107.1 → 2026.1107.2

package/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Use Node.js 22.14+ (24 recommended). Run `npm ci --ignore-scripts`, `npm test`, and verify a packed tarball with `node scripts/verify-package.mjs ARTIFACT_DIRECTORY`.
+
+Keep task identities, durable recovery, owner-scoped authorization and local credentials intact. Native models/tools remain owned by the native runtime. Add adapter and recovery tests with isolated profiles; never use real user credentials in fixtures. Describe the reproduced behavior and tests in your PR. Changes are MIT licensed; preserve upstream notices.
+
+Start with the [code map and adapter contract](docs/adapter-development.md), then pick a [scoped contribution brief](docs/contribution-tasks.md). Include a reproduction, file locations, expected original-task behavior and acceptance commands. Public tests use isolated fixtures and need no production account.
+
+Package and website versions have separate release owners; see [compatibility](docs/compatibility.md). The normal test suite checks current install examples against package.json.

package/README.md

@@ -14,10 +14,21 @@ This repository does not include a self-hosted copy of that platform. Installing
 Connect grants no account access or spending authority; approve each Agent
 connection and any spending grant separately.
 
+## Choose your starting point
+
+| Goal | Start |
+| --- | --- |
+| Connect an existing Hermes/OpenClaw to Envar | [Native setup](docs/native-connector.md) |
+| Develop or inspect the Connector without cloud credentials | [Adapter development and local contract tests](docs/adapter-development.md) |
+| Understand package, website and bundled Pay versions | [Compatibility](docs/compatibility.md) |
+| Make a first contribution | [Concrete task briefs](docs/contribution-tasks.md) |
+
+For the independent seller-side developer path, start with [EnvarPay](https://github.com/EnvarAI/EnvarPay). Connect itself is the client and native adapter; a compatible enrollment/WorkService server is still required for a live connection.
+
 ## Install
 
 ```sh
-npm install --global --ignore-scripts @envarai/connect@2026.1029.1
+npm install --global --ignore-scripts @envarai/connect@2026.1107.2
 envar-connect --version
 ```
 

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security policy
+
+EnvarConnect runs beside a user-owned Agent and holds its scoped Envar credential, A2A access tokens, model-key references, encrypted balance claims, and local Task ledger. Keep its state directory owner-only and separate from untrusted Skill code.
+
+Paid execution must wait for a captured claim that matches the original Envar order, seller, service revision, quote, amount, input digest, and Task ID. A timeout is an unknown original operation; never create another charge to recover it. The platform Wallet remains gated until real funding, refunds, and seller settlement are accepted.
+
+Report a vulnerability using [GitHub private vulnerability reporting](https://github.com/EnvarAI/EnvarConnect/security/advisories/new). Include the affected version and a synthetic reproduction. Do not post Agent tokens, model keys, claim tokens, state databases, customer input, or active exploits in public issues.
+
+The latest stable calendar release is the maintenance target. There is no promised response SLA or production security certification.

package/docs/adapter-development.md

@@ -0,0 +1,60 @@
+# Build and verify a runtime adapter
+
+Start with the existing interfaces, rather than inventing another task protocol:
+
+| Code | Responsibility |
+| --- | --- |
+| `src/adapters/types.ts` | RuntimeAdapter, capabilities, observation and original execution reference |
+| `src/adapters/a2a-runtime.ts` | Existing Hermes/OpenClaw A2A implementation |
+| `src/adapters/native-a2a.ts` | Native Card and endpoint validation, SendMessage/GetTask transport |
+| `src/connector/loop.ts` | Claim, admission, heartbeat, dispatch, pending reports and recovery |
+| `src/connector/state.ts` | Durable journal and original runtime binding |
+| `contracts/agent-work/v1/schema.json` | Public work/report contract |
+
+## Adapter contract
+
+- `probe()` reports the runtime and capabilities it can actually demonstrate.
+- `start(work, executionKey)` receives the original work ID after durable admission.
+  Call the native operation once. Do not retry an uncertain POST.
+- `observe(reference)` only reads the original Task/session handle. The reference
+  must bind the original runtime and must contain no credential.
+- `provideInput` and `cancel` must distinguish a request from a confirmed native
+  action. An unsupported capability is not a successful cancellation.
+- `close()` releases the adapter's client resources; the runtime lifecycle belongs
+  to its operator.
+
+Do not reuse display names as authorization, move model/provider credentials
+into the platform, or create a substitute execution when the original is unknown.
+
+## Work locally without a production account
+
+```sh
+npm ci --ignore-scripts
+npm test
+# Focused iteration:
+node --test test/connector-adapters.test.mjs test/connector-loop.test.mjs
+```
+
+These tests run actual local transports and journals against isolated fixtures.
+They require no Envar account or model payment. They are protocol tests, not a
+claim that a public WorkService server or a real model ran.
+
+Use the current fixtures in those files as the reference for a new adapter.
+An implementation should show:
+
+1. One native dispatch for an admitted original task.
+2. Restart reads the same saved handle and replays the same pending event.
+3. A lost send response remains unknown, without another SendMessage.
+4. A changed Card/origin/reference cannot redirect the native credential.
+5. Result delivery persists before acknowledgement.
+6. Unsupported input/cancel is reported honestly.
+
+For a real native integration, use an isolated profile you own and document its
+exact version. Keep keys, prompts, private files and personal profiles out of the
+PR. Include sanitized original IDs and observed state transitions, not secrets.
+
+## First contributions
+
+The maintained task briefs are in [contribution tasks](contribution-tasks.md).
+Discuss a new runtime or incompatible schema change before building it. Contract
+tests can be reviewed publicly; access to production credentials is not needed.

package/docs/compatibility.md

@@ -0,0 +1,61 @@
+# Versions and compatibility
+
+Install the release documented by this checkout:
+
+```sh
+npm install --global --ignore-scripts @envarai/connect@2026.1107.2
+envar-connect --version
+```
+
+The version above comes from package.json. `npm run version:date` updates it and
+the other current installation examples; the normal test suite rejects stale
+commands. Historical migration examples keep their original versions.
+
+## Which version controls what?
+
+| Component | Source of truth | Upgrade behavior |
+| --- | --- | --- |
+| Standalone Connector | This package's package.json / npm release | Upgrade the package, preserve the original directory, and restart its receiver and native MCP process as instructed. |
+| Envar's browser-generated command | The deployed server/web release's fixed package and SHA-512 manifest | The website may deliberately pin a reviewed version. It is not automatically npm latest. |
+| Legacy `envarpay connector` | The Connect dependency bundled in that installed Pay package | Updating standalone Connect does not replace the version inside Pay. Use standalone Connect for a new native connection. |
+| Agent Work protocol | [v1 schema](../contracts/agent-work/v1/schema.json) | Package calendar versions do not change the protocol version. Incompatible changes require a new protocol version. |
+| Native runtime | The existing Hermes/OpenClaw installation | Installing Connect does not upgrade the runtime, change its model, or grant tool permissions. |
+
+Keep only one receiver for a journal. The website and Pay dependency should be
+promoted only after that consumer's contract and installation checks pass.
+A newer package release alone does not establish that an existing receiver was
+upgraded or that every supported runtime was retested.
+
+## Runtime scope
+
+Node.js 22.14+ is required; Node 24 is recommended. CI runs the minimum 22.14.0
+and current Node 22/24 lines. Linux process locks require util-linux `flock`;
+the managed container includes it. Preserve the journal on a filesystem that
+supports the locks.
+
+The last recorded native setup baseline is Hermes 2026.9.24 and OpenClaw
+2026.10.4. The local adapter tests cover the protocol and recovery boundaries;
+they do not call a model or prove acceptance on every later native version.
+Report your exact native version with any compatibility issue.
+
+Both native adapters currently observe original Tasks, but do not advertise
+input continuation or confirmed cancellation. A gateway restart may lose its
+in-memory Task. Keep that operation unknown and inspect it; never create a
+replacement simply because observation timed out.
+
+## Another Envar origin
+
+The Connector accepts an explicitly selected HTTPS origin:
+
+```sh
+envar-connect connect --origin https://your-envar.example --agent AGENT_UUID --framework hermes
+```
+
+The origin must implement the same enrollment and Agent Work contract. This
+package does not contain that server. Loopback HTTP is a deliberate development
+option, not a way to send credentials to arbitrary HTTP hosts. The original
+journal binds the origin, connection, Agent and native adapter; do not edit those
+fields to reuse another connection's task or spending authority.
+
+Read [native setup](native-connector.md), [migration](migration.md), and
+[adapter development](adapter-development.md) before changing an installation.

package/docs/contribution-tasks.md

@@ -0,0 +1,34 @@
+# Contribution tasks
+
+These are scoped contribution briefs, not promises that every runtime is
+supported. Open an issue describing the brief and your proposed work before
+starting a large change; maintainers can confirm whether someone is already
+working on it.
+
+| Brief | Reproduce / inspect | Files | Acceptance |
+| --- | --- | --- | --- |
+| C1 — Document one additional native version | Use an isolated profile with the [native guide](native-connector.md); record installation, probe, then an explicitly authorized free task separately. | `docs/native-connector.md`, `docs/compatibility.md` | Exact OS/Node/runtime versions, sanitized failure or real result; no “all versions supported” claim. A model call is optional and its own operator's responsibility. |
+| C2 — Multi-byte result boundary coverage | The adapter limits text by UTF-8 bytes and rejects empty completion. Add a case straddling that limit with multi-byte text. | `src/adapters/a2a-runtime.ts`, `test/connector-adapters.test.mjs` | The oversized original result fails clearly without a second native send; valid boundary text is preserved. |
+| C3 — Actionable missing-runtime diagnostics | Reproduce missing executable, ambiguous OpenClaw profile or missing Linux flock in an isolated setup. Improve only a demonstrated unclear error. | `src/adapters/configure-native.ts`, `src/connector/state.ts`, `test/connector-setup.test.mjs` | The error identifies the operator action; it does not select another profile, remove an active lock, or print a credential. |
+| C4 — Consumer compatibility recipe | Build a small consumer using the public EnvarWorkClient/RuntimeAdapter contracts against a local test fixture. | `src/index.ts`, `src/adapters/types.ts`, `contracts/agent-work/v1/` | Document inputs, exact IDs and replay behavior; distinguish fixture execution from native acceptance, and use no cloud secret. |
+
+Every PR should state the problem, before/after behavior, tests, and compatibility
+impact. Run `npm test`; focused file tests help iteration but do not replace the
+normal CI discovery command.
+
+## Maintenance and feedback
+
+GitHub Issues is the public support and design entry. Maintainers aim to give
+an initial response within two business days and a substantive review or an
+explicit next step within five business days. This is a best-effort maintenance
+target, not a service-level agreement; availability and scope should be stated
+on the issue when a response takes longer.
+
+Issues are triaged as reproducible bug, documentation, compatible enhancement,
+design discussion, or outside current scope. A decision to defer is useful when
+it includes the reason and the supported alternative. Security reports follow
+[SECURITY.md](../SECURITY.md), not a public issue with credentials.
+
+Current focus: reproducible setup, compatibility, original-operation recovery,
+and useful adapters. Hosted models, implicit spending permissions and automatic
+resubmission of unknown work are outside this Connector's responsibility.

package/docs/migration.md

@@ -0,0 +1,10 @@
+# Moving from EnvarPay Connector
+
+EnvarConnect is extracted from the MIT EnvarPay Connector at `2a9e03ebfd0beb9a167ad57473ead56ec5dd9bf5`. It retains the v1 protocol and SQLite journal layout.
+
+1. Keep the original state directory and its owner-only permissions. Stop the old receiver before starting the new one; do not remove its journal or binding files.
+2. Install the reviewed `@envarai/connect` version. `envar-connect run --agent ID` reads the existing `~/.envarpay/connectors/ID` binding. A custom installation uses the original `--directory PATH`.
+3. Run `envar-connect connect` with the same Agent/framework/profile to update the native MCP entry. It preserves the active connection and native peer credential. Restart the existing native gateway when requested, then start one receiver.
+4. Read the original task/order after restart. Reuse persisted request IDs; never buy again to recover a delayed result.
+
+Rollback uses the prior EnvarPay package against the same state directory, after stopping the new receiver. Both implementations understand the same journal. Rerun its original connect command if its native MCP command needs restoring. Connection permissions and spending grants are unchanged.

package/docs/native-connector.md

@@ -0,0 +1,79 @@
+# Native Agent Connector
+
+Requires the matching Envar native enrollment/WorkService deployment. A package install or authenticated Agent Card is not a real task acceptance test.
+
+## 1. Open the correct terminal
+
+Use the same OS user and profile as the native Agent. It must already have a working model and Node.js 22.14+ (24 recommended).
+
+| Runtime | Terminal in an official container |
+| --- | --- |
+| Hermes | `docker exec --user hermes -e HOME=/opt/data -it CONTAINER sh` |
+| OpenClaw | `docker exec --user node -e HOME=/home/node -it CONTAINER sh` |
+
+Replace `CONTAINER` with your container name. Run `node --version` there. On a local install, use the terminal where the native Agent normally runs. Do not install the Connector under root while the gateway runs as another user.
+
+## 2. Connect and approve
+
+Create a private Envar Agent and copy its connection command. The command installs a fixed, bundled package through Envar and selects that exact Agent ID. The official npm package is also available:
+
+```sh
+npm install --prefix "$HOME/.envarpay/cli" --ignore-scripts --no-audit --no-fund @envarai/connect@2026.1107.2
+"$HOME/.envarpay/cli/node_modules/.bin/envar-connect" connect --agent AGENT_UUID --framework hermes
+```
+
+For OpenClaw choose `--framework openclaw`. The command prints a short code and an Envar approval link. Sign in as the owner, verify the Agent and code, and approve. A private polling secret is stored locally and never included in the URL. The request expires in ten minutes. The connection credential lasts up to 30 days and is limited to one Agent.
+
+Optional free outgoing permission does not permit spending. The receiving owner must also permit each caller under **Free task permissions**.
+
+For multiple OpenClaw Agents, select `--native-agent ID`. Use `--home PATH` for a secondary profile. Hermes honors `HERMES_HOME`; OpenClaw honors `OPENCLAW_STATE_DIR` and `OPENCLAW_CONFIG_PATH`. Setup changes only the managed peer, routing and MCP entry, preserving existing credentials, tools and private configuration backups.
+
+### Managed Ace Data Cloud instances
+
+Reuse an existing instance when its subscription and model configuration are
+valid. Keep the existing EnvarPay seller profile and ledger; a new private Envar
+Agent must have its own Connector directory. A seller Agent Card is not a native
+Connector pairing.
+
+If Hermes reports that A2A peers are supplied by the deployment environment,
+finish the setup through that deployment's peer configuration. Editing `.env`
+alone cannot override those values. Preserve existing peers, use the generated
+private `native.token` for this Connector only, and never paste it into Envar or
+logs. Have the deployment supervisor run the receiver against its durable
+original directory; an interactive terminal alone does not survive replacement
+of the container.
+
+## 3. Start receiving
+
+When setup says a restart is needed, restart the existing native gateway using its normal service/container controls. In Docker, restart the container from the host, then reopen the same user shell. Do not start a second gateway alongside an already supervised one.
+
+```sh
+"$HOME/.envarpay/cli/node_modules/.bin/envar-connect" run --agent AGENT_UUID
+```
+
+Keep this process and the gateway running. For persistent deployment, have your existing supervisor launch this command with the same user, HOME and durable state volume. It uses outbound HTTPS; no public A2A tunnel is required.
+
+## 4. Verify the actual result
+
+Send the free connection test from the Agent page. Wait for the exact returned result. `doctor` checks authenticated native A2A and connection status without invoking the model; it cannot establish model/task success.
+
+After enabling free outgoing tasks and the recipient's permission, ask the native Agent to use `list_peers`, `send_message`, then `wait_work`/`get_work`. Preserve the same request ID after any lost response. Native MCP also exposes original input/cancel requests and received results. Incoming claims and reports belong to the Connector, not a second model loop.
+
+## Recovery and disconnection
+
+- Restart the Connector using its original directory. Its private SQLite journal restores pending reports and original native handles before taking new work.
+- Both currently tested native A2A servers hold Tasks in memory. A native gateway restart may lose the original Task. That state stays **unknown** and is never resubmitted automatically.
+- A lost response after a native send also stays unknown when no original handle can be recovered. Do not replace it with a new paid order.
+- Native input continuation and cancellation are not advertised in this release. A cancellation request after execution starts must wait for the original outcome.
+- `envar-connect disconnect --agent AGENT_UUID` revokes this credential and preserves journals. To reconnect after a website disconnection, stop the old receiver, rerun the original connection command with `--new-pairing`, then approve the new code. A fresh connection cannot recover another connection's admitted work.
+- Expired credentials need owner reauthorization. Inspect unresolved work before disconnecting; do not delete its journal to silence an error.
+
+## Verified versions and remaining acceptance
+
+Fresh-container preflight uses OpenClaw `2026.10.4` and the Hermes `2026.9.24` CLI. It verifies installation, dedicated native A2A authorization and native MCP tool discovery. Real inference, six directed Agent exchanges and balance orders are separate release acceptance gates. Unsupported native versions should fail with a concrete setup/protocol error rather than trigger a different runtime.
+
+## Service discovery and budgeted purchases
+
+With the companion Envar commerce release, the native Agent can use `list_services`, `quote_service`, `confirm_order`, `get_order`, `wait_order`, `list_orders` and `recover_order`. The owner separately creates a spending grant for one Agent and one immutable service revision, with per-order/total limits and expiry. The connection's optional sending permission is not a spending grant. Without an eligible grant, the confirmation response points to the same original Envar order for owner approval.
+
+The Connector persists quote request identities before its network call. Retries preserve the request and original quote; financial POSTs are never retried invisibly. A package upgrade prompts a reload of the native MCP process, preserving the existing journals and runtime credentials.

package/docs/releasing.md

@@ -0,0 +1,19 @@
+# Stable releases
+
+Versions use `YEAR.MONTHDAY.SEQUENCE` in Asia/Shanghai, matching EnvarPay. Run `npm run version:date` when package or image contents change; commit package.json, package-lock.json and the updated current install examples together. The version command synchronizes README/native/compatibility commands; `node scripts/sync-doc-versions.mjs --check` is also covered by `npm test`.
+
+Pushes to main that change runtime/package/container files run `publish-npm.yml`. The workflow tests Node 22 and 24, packs once per Node version, installs the actual tarball offline with an empty cache, and builds/runs containers on amd64 and arm64. After those checks it publishes `ghcr.io/envarai/connect:VERSION`, verifies its source/version labels, publishes the tested Node 24 tarball to npm with provenance, verifies version and integrity, updates image latest, and attaches the tarball to GitHub release `vVERSION`.
+
+A retry reuses the same npm artifact and source commit. Changed tarballs cannot overwrite published versions; latest cannot move backwards. Rerun failed jobs on the original run. Workflow-only changes do not publish automatically.
+
+## One-time npm setup
+
+Configure the npm Trusted Publisher for `@envarai/connect`: GitHub owner `EnvarAI`, repository `EnvarConnect`, workflow `publish-npm.yml`, environment `npm`. The GitHub environment is restricted to main. npm must grant the initial package publication/Trusted Publisher binding to an authorized maintainer; the workflow has no long-lived npm token. Package publication is complete only after the public registry readback succeeds.
+
+## Contracts
+
+`contracts/agent-work/v1/schema.json` is the source. Run `node scripts/generate-work-contract.mjs` after editing it. Commit generated types. Publish compatible contracts before updating EnvarAI's pinned copy; incompatible v1 changes require a new contract version. Runtime code never downloads a schema.
+
+## Promote consumers after publication
+
+Read the public npm version and SHA-512 integrity before updating the website download manifest or Pay's pinned/bundled Connect dependency. Test each consumer and preserve the original state directory. A website pin may lag a package release deliberately; record that reason in its release/compatibility notes. No receiver is upgraded merely by publishing npm latest.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/connect",
-  "version": "2026.1107.1",
+  "version": "2026.1107.2",
   "description": "Connect your own Agent to Envar: tasks, native adapters and recovery",
   "type": "module",
   "license": "MIT",
@@ -31,7 +31,10 @@
     "dist",
     "contracts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
   ],
   "repository": {
     "type": "git",
@@ -73,5 +76,15 @@
     "json5",
     "yaml",
     "zod"
+  ],
+  "homepage": "https://github.com/EnvarAI/EnvarConnect#readme",
+  "keywords": [
+    "ai-agents",
+    "a2a",
+    "mcp",
+    "agent-work",
+    "hermes",
+    "openclaw",
+    "typescript"
   ]
 }