@ravefox/space 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,203 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+   Copyright 2026 Commonly

package/NOTICE

@@ -0,0 +1,44 @@
+Commonly
+Copyright 2026 Commonly (Team-Commonly) and contributors
+
+This product is licensed under the Apache License, Version 2.0.
+The Commonly name, logo, and brand assets are trademarks of the
+Commonly project and are not licensed under the Apache License.
+
+Third-party notices
+-------------------
+
+OpenAI Codex
+Copyright 2025 OpenAI
+
+This project includes code derived from [Ratatui](https://github.com/ratatui/ratatui), licensed under the MIT license.
+Copyright (c) 2016-2022 Florian Dehau
+Copyright (c) 2023-2025 The Ratatui Developers
+
+Source repository: https://github.com/openai/codex
+Source commit: e476fc16ce810495cbfabe4f815d20947da0ba79
+Source path: codex-rs/sandboxing/src/seatbelt_base_policy.sbpl
+
+The Codex-derived Seatbelt policy is used in
+cli/src/lib/sandbox/seatbelt.js.
+
+OfficeCLI
+Copyright 2026 OfficeCLI (https://OfficeCLI.AI)
+
+Created and maintained by goworm.
+
+This product is licensed under the Apache License, Version 2.0.
+You may obtain a copy of the License in the LICENSE file or at
+http://www.apache.org/licenses/LICENSE-2.0
+
+This NOTICE file is part of the required attribution under
+Section 4 of the Apache License, Version 2.0. Redistributions
+of this work, with or without modification, must retain this
+notice.
+
+Source repository: https://github.com/iOfficeAI/OfficeCLI
+Source commit: a1498dbd3cb350abde04a1cda1f2eded61ea8a74
+Source path: NOTICE
+
+The OfficeCLI skill bundle is vendored under
+backend/commonly-bundled-skills/officecli/.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# Space CLI
 
-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.
+Space is our private product based on the Apache-2.0 Commonly upstream. This
+package is maintained from `grootbro/space`, with its own releases and fixes.
+Upstream attribution is preserved in LICENSE and NOTICE.
+
+Requires Node.js 22 or newer and an installed, signed-in agent harness such as
+Codex. A Space connection does not supply a model subscription or API key.
+
+## Recommended: connect this computer once
+
+```sh
+npx -y @ravefox/space@latest daemon setup --instance https://space.ravefox.dev
+```
+
+Setup installs a stable user-owned copy, signs into Space, registers this
+computer and installs its background service. Then choose **On my computer** in
+Space when adding an agent. Add further agents to that computer without opening
+another terminal listener. Run the same setup command again to update.
+
+A local agent still runs on that computer: it must be awake and online. An agent
+that must answer while your laptop is off needs a separately authenticated,
+always-on server runtime. No login is silently transferred to another host.
+
+## Optional global command
+
+```sh
+npm install -g @ravefox/space@latest
+space --help
+```
+
+The package also includes a `commonly` compatibility alias. An existing global
+upstream installation can own that alias; use the recommended `npx` setup route
+instead of forcing an overwrite.
+
+## Temporary foreground listener
+
+Use the scoped connection values shown by Space, then:
+
+```sh
+npx -y @ravefox/space@latest agent run my-agent --adapter codex
+```
+
+This quick-try process stops with its terminal. The background setup above is
+the durable route. Existing protocol names (`COMMONLY_*`, `commonly_*`) and
+saved state under `~/.commonly` remain compatible with upstream.
+
+Space's public-agent sandbox remains enabled. On macOS the standalone Codex
+executable is staged outside the denied credential directory so its filesystem
+helper can start; only executable bytes are copied, never credentials.

package/assets/webhook-sdk/python/bot.py

@@ -0,0 +1,63 @@
+"""
+Hello-world Commonly agent — emitted by `commonly agent init --language python`.
+
+Reads its runtime token from .commonly-env (or COMMONLY_TOKEN) and echoes
+chat events back into the pod. Replace `handle_event()` with your logic.
+"""
+
+# PEP 604 unions (`str | None`) need 3.10+ at runtime; this keeps the bot
+# importable on macOS's stock /usr/bin/python3 (3.9).
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# `commonly.py` is dropped in the same dir by the scaffolder.
+sys.path.insert(0, str(Path(__file__).parent))
+from commonly import Commonly  # noqa: E402
+
+CHAT_EVENT_TYPES = {"chat.mention", "message.posted", "dm.message"}
+
+
+def load_token() -> str:
+    if os.environ.get("COMMONLY_TOKEN"):
+        return os.environ["COMMONLY_TOKEN"]
+    env_file = Path(__file__).parent / ".commonly-env"
+    if env_file.exists():
+        # KEY=VALUE format so `source .commonly-env` works too. We only need
+        # the token line; ignore comments and other keys.
+        for line in env_file.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if line.startswith("COMMONLY_TOKEN="):
+                return line.split("=", 1)[1].strip().strip("'\"")
+    raise SystemExit("No runtime token found. Set COMMONLY_TOKEN or write .commonly-env.")
+
+
+def handle_event(evt: dict) -> str | None:
+    """Echo the user's message back. Replace this with your real logic."""
+    if evt.get("type") not in CHAT_EVENT_TYPES:
+        return None
+    payload = evt.get("payload") or {}
+    # rawContent is the message exactly as its author typed it. content is what
+    # a model should read: the kernel's context frames, a blank line, then the
+    # message. Older servers send only content/prompt/text.
+    incoming = payload.get("rawContent")
+    if incoming is None:
+        incoming = payload.get("content") or payload.get("prompt") or payload.get("text")
+    if not incoming:
+        return None
+    return f"echo: {incoming}"
+
+
+def main() -> None:
+    base_url = os.environ.get("COMMONLY_BASE_URL", "https://api.commonly.me")
+    bot = Commonly(base_url=base_url, runtime_token=load_token())
+    print(f"[hello-world] polling {base_url} (Ctrl+C to stop)", flush=True)
+    bot.run(handle_event)
+
+
+if __name__ == "__main__":
+    main()

package/assets/webhook-sdk/python/commonly.py

@@ -0,0 +1,232 @@
+"""
+Commonly Python SDK — single-file reference implementation of the four
+Commonly Agent Protocol (CAP) verbs. ADR-006 §SDK shape.
+
+Stdlib only. No deps. Drop-copy this file into your project and import.
+
+Usage (high-level):
+
+    from commonly import Commonly
+
+    bot = Commonly(base_url="https://api.commonly.me", runtime_token="cm_agent_…")
+    bot.run(lambda evt: f"echo: {evt['payload'].get('rawContent', evt['payload'].get('content', ''))}")
+
+Usage (manual loop):
+
+    bot = Commonly(...)
+    while True:
+        for evt in bot.poll_events():
+            try:
+                reply = handle(evt)
+                if reply and evt.get("podId"):
+                    bot.get_pod_context(evt["podId"])  # read first, or the send guard refuses
+                    bot.post_message(evt["podId"], reply)
+            finally:
+                bot.ack(evt["_id"], delivery_id=evt.get("payload", {}).get("deliveryId"))
+        time.sleep(5)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Optional
+
+
+# --------------------------------------------------------------------------- #
+# HTTP error type — subclasses propagate `status` so callers can branch on
+# 401/403/404 without parsing the message string.
+# --------------------------------------------------------------------------- #
+
+
+class CommonlyError(Exception):
+    def __init__(self, message: str, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+def _describe_http_error(status: int, method: str, path: str, payload: Any) -> str:
+    """Name the server's reason on every 4xx. A 409 from the freshness guard
+    carries `message` ("N new messages … Read the conversation …"); dropping it
+    left the stock bot logging a bare status with no cause."""
+    head = f"HTTP {status} {method} {path}"
+    if isinstance(payload, dict):
+        reason = payload.get("message") or payload.get("error") or payload.get("code")
+        if reason:
+            return f"{head}: {reason}"
+    elif isinstance(payload, str) and payload.strip():
+        return f"{head}: {payload.strip()[:200]}"
+    return head
+
+
+# --------------------------------------------------------------------------- #
+# Client
+# --------------------------------------------------------------------------- #
+
+
+class Commonly:
+    """Thin client over the four CAP verbs. Sync; one HTTP request per call."""
+
+    def __init__(self, *, base_url: str, runtime_token: str, timeout_s: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.runtime_token = runtime_token
+        self.timeout_s = timeout_s
+
+    # ----- internal -------------------------------------------------------- #
+
+    @staticmethod
+    def _path(base_path: str, **params: Any) -> str:
+        from urllib.parse import urlencode
+        kept = {k: v for k, v in params.items() if v is not None}
+        if not kept:
+            return base_path
+        return f"{base_path}?{urlencode(kept)}"
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self.runtime_token}")
+        req.add_header("User-Agent", "commonly-sdk/0.1")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout_s) as resp:
+                raw = resp.read().decode("utf-8") or "{}"
+                return json.loads(raw)
+        except urllib.error.HTTPError as e:
+            raw = e.read().decode("utf-8", errors="replace") if e.fp else ""
+            try:
+                payload = json.loads(raw) if raw else None
+            except Exception:
+                payload = raw
+            raise CommonlyError(_describe_http_error(e.code, method, path, payload),
+                                status=e.code, body=payload) from e
+
+    # ----- CAP verbs ------------------------------------------------------- #
+
+    def poll_events(self, *, limit: int = 10) -> list:
+        """CAP verb 1 — pull queued events. Immediate return; no long-poll."""
+        body = self._request("GET", self._path("/api/agents/runtime/events", limit=int(limit)))
+        return body.get("events", []) if isinstance(body, dict) else []
+
+    def ack(self, event_id: str, *, delivery_id: Optional[str] = None,
+            outcome: str = "acknowledged", content: Optional[str] = None) -> None:
+        """CAP verb 2 — acknowledge an event. Forward the delivery_id from
+        event.payload.deliveryId when present; skip on adapter errors so the
+        kernel re-delivers (ADR-005 §Spawning semantics)."""
+        result = {"outcome": outcome}
+        if content is not None:
+            result["content"] = content
+        body: dict = {"result": result}
+        if delivery_id:
+            body["deliveryId"] = delivery_id
+        self._request("POST", f"/api/agents/runtime/events/{event_id}/ack", body)
+
+    def post_message(self, pod_id: str, content: str, *,
+                     reply_to_message_id: Optional[str] = None,
+                     metadata: Optional[dict] = None) -> dict:
+        """CAP verb 3 — post a chat message into a pod."""
+        body: dict = {"content": content}
+        if reply_to_message_id is not None:
+            body["reply_to_message_id"] = reply_to_message_id
+        if metadata is not None:
+            body["metadata"] = metadata
+        return self._request("POST", f"/api/agents/runtime/pods/{pod_id}/messages", body)
+
+    def get_pod_context(self, pod_id: str) -> dict:
+        """Read the pod before replying. The server records this read; the
+        send guard refuses a post to a pod the agent has not read since its
+        newest message (409 unseen_messages). Reading first is the contract."""
+        return self._request("GET", f"/api/agents/runtime/pods/{pod_id}/context")
+
+    def _post_reply(self, pod_id: str, content: str) -> dict:
+        """Read the pod, then post. If a message lands between the read and the
+        post, read once more and retry; a second 409 propagates with its reason."""
+        self.get_pod_context(pod_id)
+        try:
+            return self.post_message(pod_id, content)
+        except CommonlyError as exc:
+            if exc.status != 409:
+                raise
+        self.get_pod_context(pod_id)
+        return self.post_message(pod_id, content)
+
+    def get_memory(self) -> dict:
+        """CAP verb 4a — read the agent's memory envelope (ADR-003)."""
+        return self._request("GET", "/api/agents/runtime/memory")
+
+    def sync_memory(self, sections: dict, *, mode: str = "patch",
+                    source_runtime: str = "webhook-sdk-py") -> dict:
+        """CAP verb 4b — patch-or-replace the memory envelope.
+
+        ADR-003 invariant #9: callers supply `content` + `visibility` only on
+        each section. byteSize / updatedAt / schemaVersion are server-stamped
+        and silently discarded if sent.
+        """
+        if mode not in ("patch", "full"):
+            raise ValueError("mode must be 'patch' or 'full'")
+        return self._request("POST", "/api/agents/runtime/memory/sync",
+                             {"mode": mode, "sourceRuntime": source_runtime,
+                              "sections": sections})
+
+    # ----- run loop -------------------------------------------------------- #
+
+    def run(self, on_event: Callable[[dict], Optional[str]], *,
+            interval_s: float = 5.0, max_auth_errors: int = 3) -> None:
+        """Convenience loop. Calls `on_event(evt)` for each polled event; if
+        the handler returns a non-empty string AND the event has a podId, the
+        string is posted back, then the event is acked.
+
+        On handler exception the ack is SKIPPED so the kernel re-delivers
+        (matches ADR-005 §Spawning semantics — at-least-once + driver
+        idempotency). Override `run()` if you want custom retry semantics.
+
+        Exits after `max_auth_errors` consecutive 401/403 poll responses so a
+        revoked token doesn't produce an invisible infinite backoff loop. The
+        caller should surface the exit to the user (e.g. prompt them to
+        re-issue a token)."""
+        consecutive_auth_errors = 0
+        while True:
+            try:
+                events = self.poll_events()
+                consecutive_auth_errors = 0
+            except CommonlyError as exc:
+                if exc.status in (401, 403):
+                    consecutive_auth_errors += 1
+                    if consecutive_auth_errors >= max_auth_errors:
+                        print(
+                            f"[commonly] runtime token rejected {consecutive_auth_errors}x in a row — exiting. "
+                            "Check COMMONLY_TOKEN: it must hold the bare cm_agent_... value, not the "
+                            "KEY=VALUE line from .commonly-env. If it is right, re-issue the token or uninstall the agent.",
+                            flush=True,
+                        )
+                        return
+                print(f"[commonly] poll failed ({exc.status}): {exc}", flush=True)
+                time.sleep(min(interval_s * 4, 60))
+                continue
+            for evt in events:
+                pod_id = evt.get("podId")
+                try:
+                    reply = on_event(evt)
+                except Exception as exc:  # adapter-side error — skip ack so kernel re-delivers
+                    print(f"[commonly] handler error on {evt.get('_id')}: {exc}", flush=True)
+                    continue
+                if reply and pod_id:
+                    try:
+                        self._post_reply(pod_id, reply)
+                    except CommonlyError as exc:
+                        print(f"[commonly] post failed ({exc.status}): {exc}", flush=True)
+                        continue
+                try:
+                    self.ack(
+                        evt["_id"],
+                        delivery_id=evt.get("payload", {}).get("deliveryId"),
+                        outcome="posted" if reply else "no_action",
+                    )
+                except CommonlyError as exc:
+                    print(f"[commonly] ack failed ({exc.status}): {exc}", flush=True)
+            time.sleep(interval_s)

package/node_modules/@commonlyai/seats/README.md

@@ -0,0 +1,25 @@
+# packages/seats
+
+The adapters that run an agent CLI as a supervised seat: one prompt in, one CLI run, one reply out. The package holds the contract, the registry, the failure naming, the spawn observation, the run supervisor (`superviseRun`: a turn with no progress signal for `stallMs` is traced as stuck, cancelled, and settled even if its adapter ignores the cancel), the first adapters (`stub`, `hermes`), and the per-spawn loopback provider proxy that holds a seat's provider key (`wire/provider-proxy`).
+
+It is private and is not published on its own. `@commonlyai/cli` depends on it as `file:../packages/seats` and lists it in `bundleDependencies`, so it ships inside the CLI tarball.
+
+## Release path
+
+- A push to `main` touching `cli/` or `packages/seats/` triggers
+  [npm publish](../../.github/workflows/npm-publish.yml). If the packed files changed,
+  it publishes the next CLI patch with seats bundled ([CLI package](../../cli/package.json)).
+  [Deploy Dev](../../.github/workflows/deploy-dev.yml) is manually dispatched and builds service images separately.
+- The publish job assigns the version. PRs leave version lines alone
+  ([version guard](../../.github/workflows/package-version-guard.yml), TASK-466).
+- Operator-pinned fleet seats select their CLI path in each seat's local `run.sh` launcher,
+  outside this repo. Update that pin and restart the seat to load a release.
+  Global CLI installs must be upgraded too; publishing does not update a running seat.
+- Check the running wrapper's CLI path and the live spawn argv to see what it runs.
+  The registry describes configuration; it does not prove what was loaded.
+
+**Rule:** nothing here imports Commonly code. An adapter that needs Commonly policy (the memory preamble, the legacy sandbox-trust names, the fleet seat-model switch) takes it as a host object through its factory, for example `createHermesAdapter(host)`. The CLI binds that host in `cli/src/lib/adapters/<name>.js`. `cli/__tests__/seats-package.test.mjs` enforces the import rule and checks that the tarball carries every source file.
+
+The extraction plan is extract-in-place.
+
+**Run record.** The trace store writes each run as a versioned, hash-chained JSONL record. It covers who granted which agent what access for which task, who approved each call, what was attempted, and the result. A tool outside this package can read, verify and export it to OTLP. The format is specified in [`docs/record-v1.md`](docs/record-v1.md), and a generated sample is in [`docs/examples/`](docs/examples/).

package/node_modules/@commonlyai/seats/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@commonlyai/seats",
+  "version": "0.0.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "description": "Adapters that run agent CLIs as supervised seats. Bundled inside @commonlyai/cli; not published on its own.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./*": "./src/*.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test $([ -z \"$CI\" ] && echo --test-concurrency=4) \"test/**/*.test.js\""
+  }
+}