agent-inbox 0.0.1 → 0.1.2

package/hooks/register-hook.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart hook — auto-registers the agent with Agent Inbox
+ * so it can receive messages immediately.
+ *
+ * Connects to the Agent Inbox IPC socket and sends a register_agent
+ * request. If the socket isn't running, silently continues.
+ *
+ * Setup (in .claude/settings.json or ~/.claude/settings.json):
+ *
+ *   {
+ *     "hooks": {
+ *       "SessionStart": [{
+ *         "hooks": [{
+ *           "type": "command",
+ *           "command": "node /path/to/agent-inbox/hooks/register-hook.mjs"
+ *         }]
+ *       }]
+ *     }
+ *   }
+ *
+ * Environment:
+ *   INBOX_AGENT_ID   — Agent ID to register (required)
+ *   INBOX_AGENT_NAME — Display name (optional, defaults to agent ID)
+ *   INBOX_SOCKET     — IPC socket path
+ *                      (default: ~/.cache/agent-inbox/inbox.sock)
+ */
+
+import * as net from "node:net";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const agentId = process.env.INBOX_AGENT_ID;
+if (!agentId) {
+  process.exit(0);
+}
+
+const agentName = process.env.INBOX_AGENT_NAME || agentId;
+const socketPath =
+  process.env.INBOX_SOCKET ||
+  path.join(os.homedir(), ".cache", "agent-inbox", "inbox.sock");
+
+const request = JSON.stringify({
+  action: "register_agent",
+  agentId,
+  name: agentName,
+  program: "claude-code",
+}) + "\n";
+
+const client = net.createConnection(socketPath, () => {
+  client.write(request);
+  // Read one response then close
+  client.once("data", () => {
+    client.end();
+    process.exit(0);
+  });
+});
+
+// Best-effort — if socket doesn't exist, just continue
+client.on("error", () => {
+  process.exit(0);
+});
+
+// Timeout after 2 seconds
+setTimeout(() => {
+  client.destroy();
+  process.exit(0);
+}, 2000);

package/package.json

@@ -1,30 +1,21 @@
 {
   "name": "agent-inbox",
-  "version": "0.0.1",
-  "description": "Agent inbox",
+  "version": "0.1.2",
+  "description": "Agent Inbox — message routing, traceability, and MCP tools for multi-agent systems",
+  "type": "module",
   "main": "dist/index.js",
-  "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "prepublishOnly": "npm run build"
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/index.js",
+    "publish:npm": "npm publish --access public",
+    "prepublishOnly": "npm run build",
+    "version:patch": "npm version patch && git push && git push --tags",
+    "version:minor": "npm version minor && git push && git push --tags",
+    "version:major": "npm version major && git push && git push --tags"
   },
   "repository": {
     "type": "git",
@@ -37,9 +28,26 @@
     "url": "https://github.com/alexngai/agent-inbox/issues"
   },
   "homepage": "https://github.com/alexngai/agent-inbox#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "better-sqlite3": "^12.6.2",
+    "ulid": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@multi-agent-protocol/sdk": "*"
+  },
+  "peerDependenciesMeta": {
+    "@multi-agent-protocol/sdk": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@types/node": "^25.3.5",
-    "tsup": "^8.0.0",
-    "typescript": "^5.9.3"
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   }
 }

package/rules/agent-inbox.md

@@ -0,0 +1,78 @@
+# Agent Inbox — Messaging Rules
+
+You have access to a message inbox for communicating with other agents.
+Messages may be injected into your context automatically, or you can check manually.
+
+## Tools
+
+You have 4 messaging tools: `send_message`, `check_inbox`, `read_thread`, `list_agents`.
+
+## Sending messages
+
+Use `send_message` to send a message or reply:
+
+```
+send_message({ to: "alice", body: "Task complete, results in /tmp/output.json" })
+```
+
+To reply to a specific message, include `inReplyTo`:
+
+```
+send_message({ to: "alice", body: "Acknowledged, proceeding.", inReplyTo: "msg-id-here" })
+```
+
+**Parameters:**
+- `to` (required) — Recipient agent ID, or array of IDs. Use `"agent@system"` for federated agents.
+- `body` — Plain text message (shorthand for content)
+- `from` — Your agent ID (set automatically if registered)
+- `subject` — Short subject line
+- `threadTag` — Group related messages under a tag (e.g. `"deploy-v2"`)
+- `inReplyTo` — Message ID you're replying to
+- `importance` — `"low"`, `"normal"` (default), `"high"`, or `"urgent"`
+
+## Checking your inbox
+
+Use `check_inbox` to pull messages addressed to you:
+
+```
+check_inbox({ agentId: "your-agent-id" })
+```
+
+If inbox messages are injected automatically (via hook), they appear as a block like:
+
+```
+## [Inbox] 2 new message(s)
+
+**From alice** (5m ago) [high] — Deploy status
+> Cluster is healthy, ready for rollout
+```
+
+## Threads
+
+Use `threadTag` to group related messages. Read an entire thread with:
+
+```
+read_thread({ threadTag: "deploy-v2" })
+```
+
+## Addressing
+
+- `"bob"` — local agent on this system
+- `"bob@system-2"` — agent on a federated remote system
+- `"@system-2"` — broadcast to all agents on a remote system
+
+## Discovering other agents
+
+Use `list_agents` to see who's available:
+
+```
+list_agents({})
+list_agents({ includeFederated: true })
+```
+
+## Conventions
+
+- Reply to messages promptly so senders know you received them
+- Use `importance: "high"` or `"urgent"` sparingly — only for time-sensitive coordination
+- Use threads (`threadTag`) for multi-step workflows so context stays grouped
+- Keep messages concise — other agents have limited context windows too

package/src/federation/address.ts

@@ -0,0 +1,61 @@
+import type { FederatedAddress } from "../types.js";
+
+/**
+ * Parse a federated address string into its components.
+ *
+ * Formats:
+ *   "agent-id"              → { agent: "agent-id" }               (local)
+ *   "agent-id@system-id"    → { agent: "agent-id", system: "system-id" } (federated)
+ *   "@system-id"            → { system: "system-id" }             (broadcast to system)
+ *   "agent-id@system/scope" → { agent: "agent-id", system: "system", scope: "scope" }
+ */
+export function parseAddress(address: string): FederatedAddress {
+  const atIdx = address.indexOf("@");
+  if (atIdx === -1) {
+    // No @ — local address
+    return { agent: address };
+  }
+
+  const agent = atIdx > 0 ? address.slice(0, atIdx) : undefined;
+  const rest = address.slice(atIdx + 1);
+
+  // Check for scope separator (/)
+  const slashIdx = rest.indexOf("/");
+  if (slashIdx === -1) {
+    return { agent, system: rest };
+  }
+
+  return {
+    agent,
+    system: rest.slice(0, slashIdx),
+    scope: rest.slice(slashIdx + 1),
+  };
+}
+
+/**
+ * Serialize a FederatedAddress back to string form.
+ */
+export function formatAddress(addr: FederatedAddress): string {
+  let result = addr.agent ?? "";
+  if (addr.system) {
+    result += `@${addr.system}`;
+    if (addr.scope) {
+      result += `/${addr.scope}`;
+    }
+  }
+  return result;
+}
+
+/**
+ * Check if an address targets a remote system.
+ */
+export function isRemoteAddress(addr: FederatedAddress): boolean {
+  return addr.system !== undefined;
+}
+
+/**
+ * Check if an address is a broadcast (no specific agent).
+ */
+export function isBroadcastAddress(addr: FederatedAddress): boolean {
+  return addr.system !== undefined && addr.agent === undefined;
+}