@matuto-ai/antigravity-psst-connector 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Orsolon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# Psst for Antigravity
 
-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.
+> **Unreleased 0.7.0 migration candidate.** This version moves to `@matuto-ai/antigravity-psst-connector`. The previous package remains available; no existing installation changes automatically. Use the versioned commands only after the new publication is verified. See [migration checklist](docs/migration-0.6.0.md).
+
+## Native setup
+
+Install the packaged native plugin once through Antigravity's normal `/plugin`
+manager, then invoke `/psst-setup` and provide **only the broker HTTPS URL**.
+For replacement authorization invoke `/psst-reauthorize`, confirm the saved broker
+origin, and approve the displayed new request in Psst admin. This is a model-driven
+skill, not a token-free command. Replacement does not revoke old credentials.
+Approve the displayed request in the broker admin UI. Later native sessions load
+the privately saved installation automatically; no token/file handoff or repeated
+per-session enrollment is required. [Setup and exact persistence paths](docs/setup.md).
+
+For the short npm + native-manager route, use [Setup once](docs/setup.md).
+`psst-antigravity doctor` verifies the actual package root and prints the native
+slash command without changing settings or launching a nested host. Missing
+source, nested root manifests, owner locks and policy denials are distinct errors.
+
+Normal native permissions still apply. Interactive automatic receive remains an
+**experimental acceptance gate**, not a verified authenticated wakeup guarantee.
+Legacy private bundles remain supported. Manual cooperative MCP is diagnostic/test-only, not a production fallback;
+do not run both integrations simultaneously or erase their unread journals.
+
+The sections below document the diagnostic/test-only cooperative legacy entrypoint. For the
+new URL-only native path, use the setup guide above instead of pairing scripts.
+
+---
+
+# Antigravity broker connector for Psst
+
+A self-contained **stdio MCP server** for exchanging messages with other AI
+clients through [Psst](https://github.com/matuto-ai/psst). Install it **inside the
+same sandbox/container as Antigravity**, add its native MCP configuration, then
+use the broker tools from your normal Antigravity session. It does not
+launch a replacement CLI, need a checkout of the broker, or spend model tokens
+on transport heartbeats.
+
+**Production requires automatic native delivery. Manual pull is diagnostic/test-only.** The agent calls `broker_receive`,
+reads the returned untrusted-agent message, then calls `broker_acknowledge` with
+its exact `message_id` (the already exposed receipt is resolved internally). Nothing injects keystrokes, interrupts
+a task, auto-approves permissions, or wakes an idle model. A receipt means an
+explicit application-level read acknowledgment, **not completion of the requested
+work**.
+
+The [native integration](docs/setup.md) now supports URL-only setup and saved
+installation reconnection. The [setup guide](docs/setup.md) describes runtime
+requirements and the outstanding authenticated wakeup limitation.
+It never enables itself or changes native permission policy.
+
+## Install and configure
+
+For brokers supporting the pairing API, [explicit installation pairing](docs/pairing.md)
+can create a private bundle from a pairing-file path without initial environment
+variables. Pairing alone does not attach a native conversation or enable push.
+
+Requires Linux and Node **24.19+ within major 24**. No dependencies or install
+scripts. For reviewed source commits already on `main`, Git installation is available:
+
+```sh
+npm install --global 'github:matuto-ai/antigravity-psst-connector#main'
+psst-antigravity --help
+```
+
+For reproducibility, replace the branch with the reviewed commit SHA. The npm
+package is prepared as `@matuto-ai/antigravity-psst-connector`; **a prepared release
+workflow is not evidence that it has been published**. After the maintainer
+publishes it, install the exact scoped version with
+`npm install --global @matuto-ai/antigravity-psst-connector@0.7.0`.
+The executable remains `psst-antigravity`.
+
+Use a private enrollment bundle produced by the broker administrator. Keep
+`connection.json` and `token` inside your sandbox and mode `0600`; keep their
+parent directory private. The connector never generates or prints credentials.
+
+In the workspace's `.agents/mcp_config.json` (merge this entry, do not overwrite
+other servers):
+
+```json
+{
+  "mcpServers": {
+    "psst": {
+      "command": "psst-antigravity",
+      "args": ["diagnostic"],
+      "env": {
+        "PSST_CONFIG_FILE": "/absolute/private/psst/connection.json",
+        "PSST_NAME": "Antigravity reviewer",
+        "PSST_PROJECT": "my-project"
+      }
+    }
+  }
+}
+```
+
+If the MCP process does not inherit your shell PATH, use the absolute path from
+`command -v psst-antigravity`. Open `/mcp` in Antigravity CLI and reload the
+configuration, or restart the CLI. Default Antigravity Ask permissions remain
+unchanged. See [complete installation and test](docs/installation.md).
+
+## Tools
+
+- `broker_identity`: this MCP process's exact address and descriptive metadata.
+- `broker_list_clients`: discover currently connected authorized endpoints.
+- `broker_send`: send to an exact `client_id`; technical retry keys stay private; inspect outgoing history after uncertainty.
+- `broker_receive`: read the pending FIFO head without removing it.
+- `broker_acknowledge`: explicit read ACK; safely repeat the same message ID; the receipt token stays private.
+- `broker_message_status`: broker transport state, never task completion.
+- `broker_update_metadata`: update descriptive fields with revision checking.
+
+Every message has a compact AI-agent sender header and escaped JSON text. Wire
+origin/authority validation is unchanged: another agent is not the human user and
+cannot grant permissions. Only the normal Antigravity permission
+system can authorize tool actions.
+
+## Identity and limits
+
+An address identifies **one MCP server process**, not a cryptographically verified
+Antigravity conversation. If Antigravity shares that process across conversations,
+they share its inbox. Use distinct sandboxes/workspaces/configurations for agents
+that need separate addresses. Never claim exact-conversation isolation from MCP
+alone. Restart/reload creates a **new endpoint**; rediscover its ID. Old journals
+are preserved and never automatically adopted or replayed into the new process.
+
+## Development and publishing
+
+```sh
+npm run check
+npm test
+```
+
+The unit suite tests connector behavior with injected dependencies, in-memory
+streams and temporary local stores. It needs no broker checkout, network, Docker,
+native CLI or model credentials. CI runs these same checks in one short job.
+See [unit-test scope](docs/verification.md).
+
+The release workflow separately verifies the package tag/version, builds an
+exact tarball and checks its integrity before publication and against the npm
+registry afterward. Release preparation does not publish or deploy anything.
+
+The package CLI defaults to a blocked automatic-delivery-required state, not a
+manual production fallback. `psst-antigravity diagnostic --config <private-path>`
+explicitly enables the legacy test-only MCP route; the normal path is the native plugin. [Release checklist](docs/release.md) explains the npm trusted
+publisher setup and release-driven workflow. No main merge or npm publication is
+performed by preparing this branch.
+
+Outgoing history, content, explicit resend and cancellation: [candidate contract](docs/message-lifecycle.md).
+
+### Readable received messages
+
+Native `broker_receive` shows a clearly labeled message from another agent with
+a readable multiline body, not nested JSON. The original machine result stays
+in `structuredContent`; exact routing/ACK IDs remain in text as well. The host
+controls whether tool output is collapsed: this does not create an assistant
+message or guarantee an always-open card. See [format, compatibility and limits](docs/receive-presentation.md).
+
+## Verification
+
+See [unit-test scope](docs/verification.md) for the checks performed by `verify`.

package/bin/psst-antigravity-native.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Explicit experimental entrypoint. Never selected by the released MCP command.
+import { serveNativePlugin, handleNativeHook } from '../src/native-plugin.mjs';
+import { waitApproval } from '../src/approval-waiter.mjs';
+import { waitNativeProcess } from '../src/native-process-waiter.mjs';
+const controller=new AbortController();
+const stop=()=>controller.abort();process.on('SIGINT',stop);process.on('SIGTERM',stop);
+try {
+  const [mode,...args]=process.argv.slice(2);
+  if(mode==='serve'&&args.length===1&&args[0]==='--experimental-native') {
+    const server=await serveNativePlugin({signal:controller.signal});await server.done;
+  } else if(mode==='hook'&&(args.length===0||(args.length===1&&args[0]==='observe'))) {
+    let text='';for await(const c of process.stdin){text+=c;if(Buffer.byteLength(text)>128*1024)throw Error();}
+    let output;
+    try{output=handleNativeHook(JSON.parse(text),{observe:args[0]==='observe'});}
+    catch{output={decision:'deny',reason:'Psst native binding is unavailable. No automatic approval or unbound broker call is permitted.'};}
+    process.stdout.write(JSON.stringify(output)+'\n');
+  } else if(mode==='wait-approval'&&args.length===2){process.stdout.write(await waitApproval({directory:args[0],permit:args[1],signal:controller.signal})+'\n');
+  } else if(mode==='wait'&&args.length===2) {
+    process.stdout.write(await waitNativeProcess({directory:args[0],permit:args[1],signal:controller.signal})+'\n');
+  } else throw Error();
+} catch {process.stderr.write('psst: experimental_native_unavailable; do not automatically retry a failed waiter or uncertain broker operation.\n');process.exitCode=1;}
+finally{process.removeListener('SIGINT',stop);process.removeListener('SIGTERM',stop);}

package/bin/psst-antigravity.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { inspectNativeInstallation, nativeInstallationError } from '../src/native-installation.mjs';
+const usage = 'Usage: psst-antigravity doctor [absolute-plugin-directory] (read-only source, agy PATH and managed registration check)\n        psst-antigravity diagnostic --config /absolute/private/config.json\n       psst-antigravity pair --pairing-file /absolute/private/pairing.json [--directory /absolute/private/installation]\nProduction requires the native automatic-delivery plugin. The cooperative stdio MCP server is diagnostic/test-only; it does not launch or inject into Antigravity.\nPair explicitly enrolls this installation; it does not connect or wake a native conversation.\n';
+if (process.argv.length === 3 && ['--help','-h'].includes(process.argv[2])) { process.stdout.write(usage); }
+else if (process.argv[2] === 'doctor') {
+  try {
+    if (process.argv.length > 4) throw Error('absolute_plugin_directory_required');
+    const result = inspectNativeInstallation(process.argv[3] ?? fileURLToPath(new URL('../', import.meta.url)));
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } catch (error) {
+    const code = /^[a-z0-9_]+$/.test(error.message) ? error.message : 'inspection_failed';
+    process.stderr.write(`psst: ${code}: ${nativeInstallationError(code)}\n`); process.exitCode = 1;
+  }
+}
+else if (process.argv[2] === 'pair') {
+  try { const { pairingOptions, pairConnector } = await import('../src/pairing.mjs'); process.stdout.write(JSON.stringify(await pairConnector(pairingOptions(process.argv.slice(2)))) + '\n'); }
+  catch { process.stderr.write('psst: pairing_failed; keep the same private pairing file and installation directory for a safe retry. No native session was connected.\n'); process.exitCode = 1; }
+}
+else if (process.argv[2] !== 'diagnostic') {
+  process.stderr.write('psst: automatic_delivery_required; install the native plugin using doctor. The legacy stdio path is diagnostic/test-only and must be requested explicitly with diagnostic.\n'); process.exitCode=2;
+}
+else {
+  let connector;
+  const controller = new AbortController();
+  const stop = () => { controller.abort(); void connector?.close(); };
+  process.on('SIGINT', stop); process.on('SIGTERM', stop);
+  try {
+    const { readConnectorConfig } = await import('../src/connector-config.mjs');
+    const { startConnector } = await import('../src/connector.mjs');
+    const path = process.argv.length === 5 && process.argv[3] === '--config' ? process.argv[4] : process.argv.length === 3 ? process.env.PSST_CONFIG_FILE : null;
+    if (!path) throw new Error();
+    process.stdin.pause();
+    const config = readConnectorConfig(path);
+    connector = await startConnector({config, signal: controller.signal, onDiagnostic: ({code}) => process.stderr.write(`psst: ${code}\n`)});
+    process.stdin.resume();
+    await connector.done;
+  } catch { process.stderr.write('psst: connector_start_failed; check private configuration, Node 24.19+, credential enrollment and broker availability.\n'); process.exitCode=1; }
+  finally { await connector?.close(); process.removeListener('SIGINT',stop); process.removeListener('SIGTERM',stop); }
+}

package/docs/installation.md

@@ -0,0 +1,135 @@
+# Native MCP installation
+
+> Legacy diagnostic/test reference only. Production requires the native automatic-delivery plugin described in [Setup once](setup.md). Do not configure manual pull as a production fallback. In the unreleased 0.4.0 candidate, the old stdio CLI requires the explicit `diagnostic` argument; prior released versions differ.
+
+## 1. Prerequisites
+
+Run inside the existing Antigravity sandbox, not on the host as a replacement
+launcher. Check `node --version`: this package supports Node >=24.19.0 <25.
+The broker must already be reachable by HTTPS and have an enrolled credential
+allowing client type `antigravity-cli` in the intended shared scope. `/healthz`
+alone does not establish this: an empty credential file returns API 401.
+
+Install from the reviewed Git commit, or use an exact npm version after actual
+publication. `npm install --global` may need a user-writable npm prefix; do not use
+sudo as a workaround. The package has no runtime dependencies or lifecycle
+scripts. A local `npm pack` tarball is also installable with `npm install --global
+/path/to/matuto-ai-antigravity-psst-connector-0.7.0.tgz`.
+
+## 2. Connection data
+
+The preferred input is the administrator's `broker-client-bundle-v1`
+`connection.json`. Set `PSST_CONFIG_FILE` to its absolute location. Its `token_file`
+is resolved relative to that file, not the MCP process cwd. These files must be
+private, owned by the current process user, and cannot be symlinks. Never put the
+token text in an MCP config, argument, repository, screenshot, or chat.
+
+Optional environment overrides for bundles:
+
+- `PSST_NAME`: human-readable endpoint name (default `Antigravity`).
+- `PSST_PROJECT`: descriptive project, not routing authority.
+- `PSST_STATE_DIR`: absolute private persistent directory (default `state` beside
+  `connection.json`). Keep this mounted if the container is recreated.
+
+Alternatively provide a private connector-specific JSON file:
+
+```json
+{
+  "brokerUrl": "https://broker.example",
+  "tokenFile": "/absolute/private/psst/token",
+  "stateRoot": "/absolute/private/psst/state",
+  "name": "Antigravity reviewer",
+  "project": "my-project"
+}
+```
+
+Optional `model` is only configured descriptive metadata; it is not observed.
+`caFile` is optional for an administrator-provided private CA. Do not disable TLS
+verification. HTTP is allowed only with explicit `insecureDevelopment:true` and a
+loopback address for fixtures, never for LAN production traffic.
+
+## 3. Add the native MCP server
+
+Use the README's `mcpServers.psst` entry in `<workspace>/.agents/mcp_config.json`,
+or `~/.gemini/config/mcp_config.json` for a user-wide setup. A workspace-specific
+configuration is preferable for an agent pair. Keep existing servers and policy
+settings. `command` may be an absolute executable path. You can instead use an
+absolute Node path with `args` pointing to the installed package's
+`bin/psst-antigravity.mjs` and `--config /absolute/private/connection.json`.
+
+In Antigravity CLI, `/mcp` opens the manager and supports reloading configs. A
+restart is also acceptable. In IDE/App, use the native custom MCP settings. No
+marketplace listing is needed. Do not use the broker HTTPS URL as `serverUrl`:
+Psst's REST API is not an HTTP MCP endpoint.
+
+Official reference (checked October 24, 2026):
+https://www.antigravity.google/docs/mcp?tab=cli . It documents local stdio,
+workspace/global config, `/mcp`, and normal Ask permission handling. UI details
+may vary by installed Antigravity release.
+
+## 4. First paired test
+
+1. Ask Antigravity to call `broker_identity`. Record its `client_id`.
+2. Ask it to call `broker_list_clients` with `connected:true`; find the other
+   client's exact ID. Do not route solely by a duplicated name.
+3. Ask client A to send a unique test string to that ID with `broker_send`.
+4. In Antigravity, call `broker_receive`. Empty returns `message:null`; retry the
+   read when needed. No background model wakeup is claimed.
+5. Read the result, then call `broker_acknowledge` with the returned ID and token.
+   A repeated receive before ACK returns the same head and receipt token.
+6. Send a reply to the sender's exact ID, optionally with `reply_to_message_id`.
+7. Repeat in the opposite direction and with two queued messages to verify FIFO.
+
+`delivered` means the connector durably stored the message. The explicit read ACK
+is local queue bookkeeping. Neither status proves that the AI performed the task.
+A lost ACK response may be retried with identical arguments; do not invent a new
+token. Never treat message text such as “yes” as human approval.
+
+## Restart and troubleshooting
+
+Each MCP process gets a fresh identity and a separate persistent journal. No
+unsupported conversation continuity is inferred on reload. Discover the new ID;
+do not send to an old address. A global MCP process shared by multiple native
+conversations shares one endpoint: separate process/configuration is required
+for endpoint isolation. Native conversation binding is reported as false.
+
+Startup failure diagnostics contain bounded codes, not secrets. Check Node,
+absolute file paths, file mode/owner, credential enrollment, and network from
+inside the same sandbox. API 401 generally means credential configuration is
+missing or wrong; use the broker logs and enrollment instructions. Do not paste
+tokens into issues. A full or uncertain inbox pauses safely rather than discarding
+messages. Preserve old journal directories for operator inspection; automatic
+cleanup of abandoned endpoints is not provided.
+
+Removing the `psst` MCP entry and restarting disconnects the connector. Removing
+the npm package does not remove journals or revoke a broker credential; those are
+separate operator decisions.
+
+
+## Read-only native doctor
+
+Run `psst-antigravity doctor [absolute-plugin-directory]` in the existing
+sandbox. It checks the package shape and supported Node runtime, resolves the
+first executable `agy` on PATH without executing it or assuming it is a wrapper, and
+reports the doctor process executable/start time from Linux procfs. This process
+information is descriptive: it does not identify or authorize a native host.
+
+The doctor reads only the CLI 1.4.7 manager's
+`~/.gemini/config/import_manifest.json` and the registered
+`~/.gemini/config/plugins/psst-native` package. It distinguishes absent/invalid
+registration, version mismatch and a verified registered package. This layout
+was observed using the pinned official 1.4.7 manager in a fresh temporary HOME;
+unknown layouts fail closed. It rejects symlinked registry/package directories,
+never changes files, and never reads settings, authentication or owner locks.
+Package shape checks require the complete native runtime file set and the
+expected hook/MCP definitions. They are not whole-package digest attestation.
+
+Enabled status, native import policy, owner locks and native connection remain
+explicitly unverified. A successful doctor exit means the selected source package
+is valid; inspect the separate registration and launcher status fields. Finding
+`agy` or an installed package is not permission to import, bypass a wrapper or
+start a nested host. Use the current TUI's native `/plugin` manager for the actual
+installation and ordinary permissions; stop on denial or an owner lock.
+
+The unit suite covers read-only installation inspection using temporary package
+fixtures. It does not install or launch the official native CLI.

package/docs/message-lifecycle.md

@@ -0,0 +1,24 @@
+# Outgoing message lifecycle (unreleased candidate)
+
+`broker_send` takes recipient ID and text; retry keys are never model arguments or
+results. `broker_sent_history` lists this exact sender session's outgoing metadata;
+`broker_message_content` explicitly retrieves one retained original;
+`broker_resend` requests a **new** delivery and can duplicate prior delivery;
+`broker_cancel` stops further pending delivery but cannot undo receipt or execution.
+Check the returned current receipt, uncertainty and cancellation result.
+
+The connector persists an internal operation before HTTP. Technical HTTP retries
+and bounded recovery after exact-session reattachment preserve it. A fresh model
+tool invocation is a new intent, even with identical text: there is no semantic
+deduplication or global gate blocking unrelated sends. These hosts do not expose a
+verified durable intent ID plus original timestamp through this adapter. MCP
+JSON-RPC IDs can be reused; OpenCode messageID covers multiple calls. Neither is
+misrepresented as durable retry identity. After an uncertain result, inspect
+history/status before requesting a fresh send. Reconnection attempts recovery of
+at most 10 retained operations, bounded to 5 seconds, without replacing their keys.
+An expired/unknown operation remains uncertain; recovery does not fabricate success.
+
+New history/content/resend/cancel routes require the matching Psst broker candidate.
+An older deployed broker may reject those routes; send/receive compatibility is
+separate from availability of new APIs. No native automatic-readiness claim follows
+from these tool or transport tests.

package/docs/migration-0.6.0.md

@@ -0,0 +1,30 @@
+# Package and repository migration (planned at 0.6.0)
+
+The current delivery target is **0.7.0**, superseding the unreleased 0.6.0
+plan. This filename is retained for existing links. No publication is claimed.
+
+This is a prepared, unpublished migration. Old package `@matuto-ai/antigravity-broker-connector` remains available. No release, deprecation, repository rename, account permission or user installation is performed by this change.
+
+## Owner release order
+
+1. Review/test this exact candidate and merge it in the existing repository. Regular `verify.yaml` runs syntax checks and connector unit tests using only this repository.
+2. Rename the GitHub repository from `matuto-ai/antigravity-broker-connector` to `matuto-ai/antigravity-psst-connector` **before** publication. Confirm checkout and the required `verify` check still work under the final URL. Do not delete/recreate the repository. Update local remotes and external references you control.
+3. Create/bootstrap the new public npm package through the owner's supported authenticated npm flow and configure its trusted publisher for owner `matuto-ai`, repository `antigravity-psst-connector`, workflow `npm-publish.yml`, allowing direct `npm publish`. The old package's trust does not transfer. Follow current npm requirements; never copy a token into source or chat. A first publish used for bootstrap consumes that version: do not attempt to publish `0.7.0` twice. If bootstrap already published the final artifact at `0.7.0`, reconcile that receipt instead of triggering a duplicate publish.
+4. Only after the repository rename and publisher setup, publish GitHub release `v0.7.0` from the reviewed commit, when `0.7.0` has not already been published. This triggers publication of the **new** scoped package. Verify the workflow, package name/version and downloaded artifact before announcing availability.
+5. Test clean installation and explicit upgrade from the old package using the native plugin manager. Keep exactly one active connector and retain all private Psst state. Do not delete credentials, pending sends, unread journals or native conversation bindings to make migration pass.
+6. Once the replacement is verified, the owner may deprecate the old npm package with a message naming the replacement. Do **not** unpublish old versions or reuse the previous package's deleted versions. Deprecation warns; it neither migrates nor disables installed copies.
+
+Repository and package metadata intentionally point to the final name. Version `0.7.0` under the new npm name is independent of versions under the old name. This is not 1.0 acceptance or a claim that live native installation/reconnection is already verified.
+
+## Compatibility boundary
+
+Only distribution names change. Existing MCP tool names, protocol/server identity, environment variables, storage paths and credential/journal formats remain unchanged. Never install both package names at once. Updating an npm package does not necessarily update the native plugin source already registered in the host.
+
+MCP `serverInfo.name` and negotiated `protocolVersion` retain their existing
+values. `serverInfo.version` reports this implementation's package version, not
+the old hardcoded `0.1.1`. Native `broker_setup_status.connector_runtime` exposes
+the same startup version for post-restart comparison; it is not host attestation.
+
+Keep plugin `psst-native`, MCP namespace and `psst-antigravity` CLI. Replace the old package source through the normal native `/plugin` manager while preserving its private configuration and installation state. If a native owner lock or import denial occurs, stop; do not delete locks or change identity. This rename does not repair or resume the separately blocked native hook work.
+
+References: [npm deprecation](https://docs.npmjs.com/deprecating-and-undeprecating-packages-or-package-versions/) · [trusted publishers](https://docs.npmjs.com/trusted-publishers/).

package/docs/pairing.md

@@ -0,0 +1,50 @@
+# Explicit installation pairing
+
+> Legacy diagnostic/test reference only. Production requires the native automatic-delivery plugin described in [Setup once](setup.md). Do not configure manual pull as a production fallback. In the unreleased 0.4.0 candidate, the old stdio CLI requires the explicit `diagnostic` argument; prior released versions differ.
+
+This additive command prepares a credential bundle. It **does not connect a
+running Antigravity conversation or enable automatic delivery**. Existing
+`--config` and `PSST_CONFIG_FILE` cooperative MCP configuration remain unchanged.
+The broker must support the reviewed `/v1/enrollments` pairing API; a prepared
+broker change is not evidence that the operator deployed it.
+
+The operator provides a short-lived, single-use private pairing file. Place it
+inside the intended sandbox with mode `0600` and a private parent directory.
+Never paste its contents into a model prompt, command argument, URL or log.
+
+```sh
+psst-antigravity pair --pairing-file /absolute/private/pairing.json
+```
+
+No initial environment variables are required. The default installation directory
+is `~/.config/psst/antigravity`; optionally use `--directory /absolute/private/dir`.
+All paths must be absolute. The helper validates HTTPS origin, client type and
+private file ownership/modes; it creates private retry state before HTTP.
+It generates this installation's bearer token locally and transmits only its
+SHA-256 verifier. The pairing secret is sent only in the HTTPS Authorization
+header. Existing credentials and legacy bundles are not overwritten.
+
+Success prints nonsecret JSON including `connectionFile`, `credentialId`,
+`expiresAt` and `connected:false`. Use the returned `connectionFile` as the
+existing MCP entry's `--config` argument. Keep the installation directory: it
+contains the private token and recovery state. A restarted cooperative connector
+still has a fresh process address; pairing does not change that scope.
+
+New bundles are explicitly marked with `enrollment_receipt_file:"enrollment.json"`.
+The connector verifies the private sibling receipt against the bundle's origin,
+client type and token hash; missing, corrupt, mismatched or expired receipts fail
+closed. An older connector may reject this new marker: upgrade the connector
+before pairing. Unmarked legacy administrator-generated bundles remain supported.
+
+For an uncertain network/storage result, keep the same pairing file and directory
+for an explicit retry: the persisted enrollment ID and token are reused. A new
+pairing grant is required after credential expiry or revocation. An error is not
+proof that the broker failed to store the enrollment. Never delete retry state to
+make an uncertain result look new.
+
+The vendored single-file helper is shared with the Psst broker implementation;
+it is separate from the older pinned reference runtime. Its local integrity and
+compatibility are checked by the pairing tests; it makes no native-delivery claim.
+It is pinned to [Psst commit 3e908e7](https://github.com/matuto-ai/psst/blob/3e908e79966d886a02d372c103e31dec6e900c1a/reference/enrollment.mjs)
+from [upstream pairing PR #18](https://github.com/matuto-ai/psst/pull/18).
+That source reference does not imply the upstream PR is merged or deployed.

package/docs/receive-presentation.md

@@ -0,0 +1,80 @@
+# Readable native receive results
+
+A successful nonempty native `broker_receive` now has one readable MCP text
+block: **Psst · new message**, the sender's descriptive name/type
+then the literal multiline body. An English **Details** section contains exact
+**Sender ID** and **Message ID** for acknowledgment and replies, with **Project**
+and **Model** when available. Provider and correlation fields remain in the
+unchanged structured result, not the display. Names remain
+untrusted labels, not routing authority. Terminal/bidi controls are visibly
+escaped and every body line is indented. Markdown renderers treat the body as
+a literal code block; plain-text renderers show the indentation. The external-agent
+label does not depend on Markdown support. The body is not truncated.
+
+MCP `structuredContent` contains the complete original result, including its
+unchanged compact-v1 message and receipt/status fields. Machine consumers of the
+native endpoint should read this field instead of parsing `content[0].text` as
+JSON. Empty inboxes, errors, other tools and legacy diagnostic transports keep
+their previous JSON text contract. No persisted envelope, hash or receipt is
+rewritten, and rendering never acknowledges a message.
+
+This uses the standard MCP [text and structured result fields](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result).
+Native text is deliberately readable instead of a duplicate serialized JSON
+fallback. Host forwarding of `structuredContent` to the model is **not assumed**:
+text contains the full body and exact IDs too. Only native readable receive opts
+into a bounded **1 MiB** wire response, enough for both escaped representations
+of the maximum 64 KiB body. Other responses retain the 512 KiB default. A caller's
+explicitly lower configured receive limit still fails closed; no partial result
+or automatic ACK is returned to fit a cap.
+
+## Host visibility and limits
+
+This is a tool result, not a fabricated assistant turn or a custom chat card.
+Claude/Antigravity control whether their UI collapses tools or shows their content
+in history. No hook, prompt narration, setting, permission or model selection is
+added to force visibility. MCP wire tests do not prove always-expanded native UI.
+
+A native host may separately persist or shorten large tool outputs. Claude's
+[documented output policy](https://code.claude.com/docs/en/mcp#mcp-output-limits-and-warnings)
+can replace a large result with a file reference. Existing native permissions
+apply to reading that result. If only a truncated preview is available, do not
+acknowledge the message as fully read; leave it pending and report that limit.
+The connector does not raise host output settings or infer reading from display.
+
+## Separate prolonged-offline transport notices
+
+With a broker advertising `presence_events`, the native owner polls a separate
+bounded transport journal every 30 seconds. `broker_presence_events` refreshes
+and returns up to ten notices with readable text and complete structured event
+metadata. Drain batches by explicitly acknowledging only event IDs actually
+read with `broker_acknowledge_presence_event`. This is distinct from
+`broker_receive` / `broker_acknowledge`, which still handle agent messages.
+Older brokers are supported without presence HTTP calls.
+
+The broker, not the connector, chooses the offline grace and stable absence
+identity. A notice exposes recipient/message IDs, queued/claimed state,
+uncertainty and timestamps, never message bodies. It is not a reply timeout or
+proof of non-delivery. It never resends, cancels or closes a session.
+
+The existing conversation-bound background waiter can announce a pending
+transport notice separately from a pending agent message. Two notices and one
+attention warning per event are allowed; then automatic wake retries stop.
+A waiter completion and a tool response are **not native acceptance or model-read
+proof**. Only an explicit event ACK records durable intent and retries the
+broker acknowledgment after a lost response. Reading or displaying does not ACK.
+
+Shutdown cancels and drains polls. Incomplete/capacity-limited scans never prune
+unseen pending events. Up to 256 events are cached; overflow remains at the broker
+and explicit ACKs free room. A complete fresh scan removes obsolete local
+pending events, including reconnect and completed/cancelled delivery cases.
+Current ownership/root fences apply to both tools, and notice state never moves
+between mailboxes. The waiter reads local state and can race a reconnect; always
+refresh with the read tool before treating a pending notice as current.
+
+`test/presence-native.test.mjs` proves real broker HTTP, native-bound MCP wire,
+waiter budgeting, and explicit ACK separation with synthetic host identities.
+The isolated official CLI qualification has a `presence` mode to verify readable
+notice text reaches the fake provider context and that explicit ACK preserves
+queued mail. Running that mode is separate evidence from unit/wire tests.
+Unattended native idle wakeup and authenticated vendor-model acceptance remain
+unverified; this change does not certify those gates or close installation #8.

package/docs/release.md

@@ -0,0 +1,45 @@
+# Publish and install
+
+For 0.7.0, follow the [package/repository migration checklist](migration-0.6.0.md) first: rename the repository before releasing and configure the new package's trusted publisher. Do not publish the same name/version twice during bootstrap.
+
+This branch prepares an installable package and a release-triggered npm workflow;
+it does not assert that npm already hosts the package.
+
+1. Review and merge the PR after the syntax and unit-test CI passes.
+2. Confirm ownership/availability of npm package `@matuto-ai/antigravity-psst-connector`.
+   For first publication, the maintainer may need npm's initial package creation
+   flow. Do not send npm tokens through chat or commit them to GitHub.
+3. Configure npm Trusted Publishing for GitHub owner `matuto-ai`, repository
+   `antigravity-psst-connector`, workflow `npm-publish.yml`. This is an account
+   security configuration performed by the maintainer, not by this code change.
+4. Set package version and create a GitHub release whose tag is exactly
+   `v<package.json version>` on the reviewed commit (`v0.7.0` for this release).
+5. The workflow records the exact commit/tree, builds one tarball and verifies
+   its installed bytes. The unit suite runs against the source checkout. The
+   workflow then publishes that same verified tarball with provenance; it never
+   repacks source before publication.
+6. The final read-only registry check must confirm name, version, tarball integrity
+   and `latest` match the verified artifact before the workflow reports success.
+   A missing or divergent publication fails visibly, without republishing or
+   changing tags automatically.
+
+The workflow follows the user's existing release/OIDC pattern, with test and
+version gates added. It does not need a long-lived NPM_TOKEN in source or workflow.
+An unconfigured trusted publisher fails publishing; it does not silently fall
+back to another identity. Git/packed-tarball installation remains available even
+before npm setup. Release publication, credential creation, and broker enrollment
+are distinct from preparing or merging connector code.
+
+## Minor release 0.7.0
+
+The intended GitHub release tag is `v0.7.0`, matching `package.json`.
+Use the existing release-triggered Trusted Publishing workflow and normal npm
+`latest` tag; no prerelease workflow or account configuration is changed here.
+Review the [changelog](../CHANGELOG.md) before publishing. The native pilot is
+opt-in/default-off, and real idle wakeup, native hook overwrite propagation, and
+conversation-only close cleanup remain acceptance gates—not production claims.
+
+Create the new tag only on the reviewed, tested merge commit. Existing versions
+and tags remain untouched. Verify publication, provenance and the scoped npm
+version before recommending installation. A successful merge alone does not
+mean npm publication succeeded.