patchcord 0.5.58 → 0.5.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.5.58",
+  "version": "0.5.60",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",

package/per-project-skills/codex/SKILL.md

@@ -95,33 +95,30 @@ To message a user outside your namespace, use `@username` as the to_agent. Examp
 
 ## File sharing
 
-Three modes:
-
-**Relay from URL (preferred for public files):**
+**Files on disk → `patchcord upload` (CLI, preferred):**
 ```
-attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
+patchcord upload /path/to/report.md --mime text/markdown
 ```
-Server fetches the URL and stores it. ~50 tokens instead of thousands for the file content.
+Prints the storage path. Pass it to `send_message`. No curl, no base64 in chat. 25MB cap.
 
-**Presigned upload (preferred for local files):**
+**Public URLs → `attachment(relay=true, ...)`:**
 ```
-attachment(upload=true, filename="report.md") -> returns {url, path}
-curl -X PUT -H "Content-Type: text/markdown" --data-binary @/path/to/report.md "<url>"
+attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
 ```
-Then send the `path` to the other agent. No base64, no token waste.
+Server fetches and stores. Use when the file already lives at a public URL.
 
-**Inline base64 (last resort — small generated content only):**
+**Inline base64 last resort:**
 ```
 attachment(upload=true, filename="notes.txt", file_data="<base64>")
 ```
-Base64 adds ~33% overhead and wastes context tokens. Never use this for files on disk — use presigned upload above instead.
+Only if you cannot run shell commands. Wastes context tokens.
 
 **Downloading:**
 ```
 attachment(path_or_url="namespace/agent/timestamp_file.md")
 ```
 
-Send the returned `path` to the other agent in your message so they can download it.
+Always send the storage path (not file content) to the other agent.
 
 ## Rules
 

package/scripts/subscribe.mjs

@@ -22,6 +22,11 @@ const RECONNECT_BACKOFF_MS = [1000, 2000, 4000, 8000, 15_000, 30_000];
 // gap means three missed heartbeats. Force a reconnect via the outer loop.
 const FRESHNESS_CHECK_INTERVAL_MS = 30_000;
 const FRESHNESS_STALE_MS = 90_000;
+// Re-emit pending count every minute as a safety net. The Realtime push
+// + Monitor pipeline can drop notifications when an agent is mid-tool-call
+// (especially for long-running work like vector-DB searches). Re-emitting
+// gives Monitor multiple chances to surface the line on a later idle tick.
+const PENDING_HEARTBEAT_MS = 60_000;
 
 // Short HH:MM:SS prefix so the Monitor output can be scanned at a glance.
 // Local time — Monitor's reader is always a human looking at one machine.
@@ -243,6 +248,7 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
     let heartbeatTimer = null;
     let refreshTimer = null;
     let freshnessTimer = null;
+    let pendingHeartbeatTimer = null;
     let lastEventAt = Date.now();
     let currentJwt = ticket.jwt;
     let settled = false;
@@ -253,6 +259,7 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
       if (heartbeatTimer) clearInterval(heartbeatTimer);
       if (refreshTimer) clearTimeout(refreshTimer);
       if (freshnessTimer) clearInterval(freshnessTimer);
+      if (pendingHeartbeatTimer) clearInterval(pendingHeartbeatTimer);
       try {
         ws.close();
       } catch (_) {}
@@ -311,6 +318,20 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
         }
       }, FRESHNESS_CHECK_INTERVAL_MS);
 
+      // Pending-inbox heartbeat. The Realtime INSERT push that triggers the
+      // initial "PATCHCORD: 1 new from <sender>" notification can be lost
+      // by the Monitor → agent-context surface layer if the agent happens
+      // to be mid-tool-call when the line is emitted (heavy agents with
+      // long tool calls — vector-DB search, CrossRef lookups — are most
+      // exposed). Re-emit the pending count once a minute as long as the
+      // inbox is non-empty so a later idle tick has another chance to
+      // wake the agent. drainQueueOnce stays silent if pending_count == 0.
+      pendingHeartbeatTimer = setInterval(() => {
+        drainQueueOnce(baseUrl, token).catch((e) => {
+          logErr(`subscribe: pending heartbeat failed: ${e.message}`);
+        });
+      }, PENDING_HEARTBEAT_MS);
+
       const scheduleRefresh = (ttlSec) => {
         const refreshIn = Math.max((ttlSec - JWT_REFRESH_SAFETY_MARGIN_SEC) * 1000, 30_000);
         refreshTimer = setTimeout(doRefresh, refreshIn);

package/skills/inbox/SKILL.md

@@ -83,34 +83,31 @@ To message a user outside your namespace, use `@username` as the to_agent. Examp
 
 ## File sharing
 
-Three modes, choose based on context:
-
-**Relay from URL (preferred for public files):**
+**Files on disk → `patchcord upload` (CLI, preferred):**
 ```
-attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
+patchcord upload /path/to/report.md --mime text/markdown
 ```
-Server fetches the URL and stores it. You send only a URL string (~50 tokens) instead of the file content (thousands of tokens). Always prefer relay when the file is at a public URL.
+Prints the storage path. Pass that path to `send_message`. No curl, no base64 in chat, no presigned URLs. 25MB cap.
 
-**Presigned upload (preferred for local files):**
+**Public URLs → `attachment(relay=true, ...)`:**
 ```
-attachment(upload=true, filename="report.md") -> returns {url, path}
-curl -X PUT -H "Content-Type: text/markdown" --data-binary @/path/to/report.md "<url>"
+attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
 ```
-Then send the `path` to the other agent. No base64, no token waste.
+Server fetches the URL and stores it. Use when the file already lives at a public URL.
 
-**Inline base64 (last resort — small generated content only):**
+**Web agents (no shell) → inline base64 last resort:**
 ```
 attachment(upload=true, filename="notes.txt", file_data="<base64>")
 ```
-Base64 adds ~33% overhead and wastes context tokens. Never use this for files on disk — use presigned upload above instead.
+Only for agents that cannot run shell commands. Wastes context tokens. Never use if you can run `patchcord upload`.
 
 **Downloading:**
 ```
 attachment(path_or_url="namespace/agent/timestamp_file.md")
 ```
-Use the path from the sender's message.
+Pass the storage path from the sender's message.
 
-Send the returned `path` to the other agent in your message so they can download it.
+Always send the storage path (not the file content) to the other agent.
 
 ## Identity (`patchcord whoami` / `patchcord agents`)