@commonlyai/cli 0.1.192 → 0.1.194

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

@@ -0,0 +1,54 @@
+"""
+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.
+"""
+
+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 {}
+    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,231 @@
+"""
+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('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. "
+                            "The token is likely revoked; re-issue 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.192",
+  "version": "0.1.194",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "files": [
     "src",
+    "assets",
     "README.md",
     "skills"
   ],
@@ -32,7 +33,7 @@
     "lint:fix": "eslint src --ext .js --fix",
     "test": "node --experimental-vm-modules node_modules/.bin/jest",
     "test:temp-cleanup": "node scripts/verify-temp-cleanup.mjs",
-    "prepack": "node scripts/require-bundled-seats.mjs",
+    "prepack": "node scripts/require-bundled-seats.mjs && node scripts/bundle-sdk-examples.mjs",
     "prepublishOnly": "node -e \"require('fs').copyFileSync('../docs/agents/skills/commonly/SKILL.md','skills/commonly/SKILL.md')\""
   },
   "dependencies": {

package/src/commands/agent.js

@@ -3340,19 +3340,20 @@ const SUPPORTED_LANGUAGES = ['python'];
 // three levels up. The scaffolder copies the canonical SDK file from the repo
 // into the user's cwd; ADR-006 §SDK lives = "live-copy, not dependency".
 //
-// Removal condition: ADR-006 §Migration path Phase 4 — when the CLI is
-// published as `@commonlyai/cli` on npm, the example files won't sit at a
-// repo-relative path; we'll need to bundle them into the package at build
-// time and resolve via `import.meta.resolve` or a packaged-data lookup.
-// Until that phase, repo-relative is the simplest correct answer.
-const repoFile = (...parts) => pathResolve(
-  dirname(fileURLToPath(import.meta.url)), '..', '..', '..', ...parts,
-);
+// The published package carries these files under cli/assets/webhook-sdk/,
+// bundled from examples/ by scripts/bundle-sdk-examples.mjs at prepack (npm
+// pack and publish run it). A repo clone that has not packed yet falls back to
+// the examples/ tree, which stays the single source of truth.
+const cliRoot = pathResolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const sdkAsset = (bundledRel, repoRel) => {
+  const bundled = pathResolve(cliRoot, 'assets', 'webhook-sdk', bundledRel);
+  return existsSync(bundled) ? bundled : pathResolve(cliRoot, '..', 'examples', repoRel);
+};
 
 const SDK_SOURCES = {
   python: {
-    sdkSrc: () => repoFile('examples', 'sdk', 'python', 'commonly.py'),
-    botSrc: () => repoFile('examples', 'hello-world-python', 'bot.py'),
+    sdkSrc: () => sdkAsset('python/commonly.py', join('sdk', 'python', 'commonly.py')),
+    botSrc: () => sdkAsset('python/bot.py', join('hello-world-python', 'bot.py')),
     sdkOut: 'commonly.py',
     botOut: (name) => `${name}.py`,
     runHint: (name) => `COMMONLY_TOKEN=$(cat .commonly-env) python3 ${name}.py`,

package/src/lib/commit-attribution.js

@@ -70,13 +70,27 @@ const seatAddressId = (agentName, instanceId) => {
   return `sha256-${createHash('sha256').update(identity).digest('base64url')}`;
 };
 
+// This probe runs before every turn and blocks the listener's event loop, so a
+// git child that never exits (one waiting on an inherited stdin, or one whose
+// open() the OS holds pending consent) must not stall the seat. On timeout
+// spawnSync kills the child and sets result.error; the wrapper hook then
+// resolves the original hooks itself at commit time.
+const GIT_PROBE_TIMEOUT_MS = 5000;
+
 const resolveOriginalHooksPath = (cwd, env) => {
   const result = spawnSync(
     'git',
     ['rev-parse', '--path-format=absolute', '--git-path', 'hooks'],
-    { cwd, env, encoding: 'utf8' },
+    {
+      cwd,
+      env,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: GIT_PROBE_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
+    },
   );
-  if (result.status !== 0 || !result.stdout.trim()) return null;
+  if (result.error || result.status !== 0 || !result.stdout?.trim()) return null;
   const hooksPath = resolve(result.stdout.trim());
   try {
     return statSync(hooksPath).isDirectory() ? hooksPath : null;