@holon-run/agentinbox 0.1.1 → 0.1.3

package/README.md

@@ -16,6 +16,43 @@ In practice, that means `AgentInbox` can:
 - wake or drive agent sessions running in `tmux` or `iTerm2`, even when the
   agent runtime does not expose a notification API
 
+## Event Flow
+
+At a high level, `AgentInbox` sits between external events and the current
+agent session:
+
+![AgentInbox Event Flow](./docs/site/assets/agentinbox-event-flow-v1.png)
+
+## Review Workflow
+
+One concrete workflow is reviewer / developer collaboration around a PR:
+
+```mermaid
+sequenceDiagram
+    participant D as Developer Agent
+    participant G as GitHub / CI
+    participant A as AgentInbox
+    participant R as Reviewer Agent
+
+    D->>G: Open PR / Push fix
+    G->>A: PR opened / CI started
+    A->>R: Wake reviewer
+
+    R->>G: Leave review comment
+    G->>A: Review comment created
+    A->>D: Wake developer
+
+    D->>G: Push fix
+    G->>A: CI completed
+    A->>D: Wake developer
+    A->>R: Wake reviewer
+
+    R->>G: Approve / Merge
+```
+
+`AgentInbox` is what lets both agents stay in the loop without polling GitHub
+manually or relying on the agent runtime to expose its own notification API.
+
 ## Status
 
 `AgentInbox` is public beta software.
@@ -32,7 +69,8 @@ In practice, that means `AgentInbox` can:
 Requires:
 
 - Node.js 20 or newer
-- `uxc` 0.14.0 or newer if you want to use GitHub or Feishu adapters
+- `uxc` 0.15.0 or newer if you want to use GitHub or Feishu adapters:
+  https://github.com/holon-run/uxc
 
 Install globally:
 
@@ -61,6 +99,13 @@ If you are using Codex or Claude Code, start with the bundled AgentInbox skill:
 - repo copy: [`skills/agentinbox/SKILL.md`](./skills/agentinbox/SKILL.md)
 - docs site copy: `https://agentinbox.holon.run/skills/agentinbox/SKILL`
 
+If you use the community `skills` installer, you can install the bundled skill
+directly:
+
+```bash
+npx skills add holon-run/agentinbox --skill agentinbox -a codex -a claude-code
+```
+
 That skill is the recommended onboarding path. It can guide the agent through:
 
 - checking or installing `agentinbox`

package/dist/src/cli.js

@@ -310,7 +310,8 @@ async function main() {
     }
     if (command === "inbox" && normalized[1] === "read") {
         const args = normalized.slice(2);
-        if (positionalArgs(args, ["--agent-id", "--after-item"]).length > 0) {
+        const allowedFlags = ["--agent-id", "--after-item", "--include-acked"];
+        if (positionalArgs(args, ["--agent-id", "--after-item"]).length > 0 || unexpectedFlags(args, allowedFlags).length > 0) {
             throw new Error("usage: agentinbox inbox read [--agent-id ID] [--after-item ID] [--include-acked]");
         }
         const selection = await selectAgentForCommand(client, {
@@ -693,6 +694,10 @@ function positionalArgs(args, flagsWithValues) {
     }
     return positionals;
 }
+function unexpectedFlags(args, allowedFlags) {
+    const allowed = new Set(allowedFlags);
+    return args.filter((token) => token.startsWith("--") && !allowed.has(token));
+}
 function printHelp(path = []) {
     const key = path[0] ?? "root";
     const helpByKey = {

package/dist/src/sources/feishu.js

@@ -1,60 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FeishuDeliveryAdapter = exports.FeishuSourceRuntime = exports.FeishuUxcClient = exports.DEFAULT_FEISHU_EVENT_TYPES = exports.FEISHU_IM_SCHEMA_URL = exports.FEISHU_OPENAPI_ENDPOINT = void 0;
+exports.FeishuDeliveryAdapter = exports.FeishuUxcClient = exports.DEFAULT_FEISHU_EVENT_TYPES = exports.FEISHU_IM_SCHEMA_URL = exports.FEISHU_OPENAPI_ENDPOINT = void 0;
 exports.normalizeFeishuBotEvent = normalizeFeishuBotEvent;
 exports.parseFeishuSourceConfig = parseFeishuSourceConfig;
 const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
 exports.FEISHU_OPENAPI_ENDPOINT = "https://open.feishu.cn/open-apis";
 exports.FEISHU_IM_SCHEMA_URL = "https://raw.githubusercontent.com/holon-run/uxc/main/skills/feishu-openapi-skill/references/feishu-im.openapi.json";
 exports.DEFAULT_FEISHU_EVENT_TYPES = ["im.message.receive_v1"];
-const DEFAULT_SYNC_INTERVAL_SECS = 2;
-const MAX_ERROR_BACKOFF_MULTIPLIER = 8;
 class FeishuUxcClient {
     client;
     constructor(client = new uxc_daemon_client_1.UxcDaemonClient({ env: process.env })) {
         this.client = client;
     }
-    async ensureLongConnectionSubscription(config, checkpoint) {
-        if (checkpoint.uxcJobId) {
-            try {
-                const status = await this.client.subscribeStatus(checkpoint.uxcJobId);
-                if (status.status === "running" || status.status === "reconnecting") {
-                    return {
-                        job_id: checkpoint.uxcJobId,
-                        mode: "stream",
-                        protocol: "feishu_long_connection",
-                        endpoint: config.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
-                        sink: "memory:",
-                        status: status.status,
-                    };
-                }
-            }
-            catch {
-                // Recreate the job below.
-            }
-        }
-        return this.client.subscribeStart({
-            endpoint: config.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
-            mode: "stream",
-            options: { auth: config.uxcAuth },
-            sink: "memory:",
-            ephemeral: false,
-            transportHint: "feishu_long_connection",
-        });
-    }
-    async readSubscriptionEvents(jobId, afterSeq) {
-        const response = await this.client.subscriptionEvents({
-            jobId,
-            afterSeq,
-            limit: 100,
-            waitMs: 10,
-        });
-        return {
-            events: response.events,
-            nextAfterSeq: response.next_after_seq,
-            status: response.status,
-        };
-    }
     async sendChatMessage(input) {
         await this.client.call({
             endpoint: input.endpoint ?? exports.FEISHU_OPENAPI_ENDPOINT,
@@ -91,176 +48,6 @@ class FeishuUxcClient {
     }
 }
 exports.FeishuUxcClient = FeishuUxcClient;
-class FeishuSourceRuntime {
-    store;
-    appendSourceEvent;
-    client;
-    interval = null;
-    inFlight = new Set();
-    errorCounts = new Map();
-    nextRetryAt = new Map();
-    constructor(store, appendSourceEvent, client) {
-        this.store = store;
-        this.appendSourceEvent = appendSourceEvent;
-        this.client = client ?? new FeishuUxcClient();
-    }
-    async ensureSource(source) {
-        if (source.sourceType !== "feishu_bot") {
-            return;
-        }
-        const config = parseFeishuSourceConfig(source);
-        const checkpoint = parseFeishuCheckpoint(source.checkpoint);
-        const started = await this.client.ensureLongConnectionSubscription(config, checkpoint);
-        this.store.updateSourceRuntime(source.sourceId, {
-            status: "active",
-            checkpoint: JSON.stringify({
-                ...checkpoint,
-                uxcJobId: started.job_id,
-            }),
-        });
-    }
-    async start() {
-        if (this.interval) {
-            return;
-        }
-        this.interval = setInterval(() => {
-            void this.syncAll();
-        }, 2_000);
-        try {
-            await this.syncAll();
-        }
-        catch (error) {
-            console.warn("feishu_bot initial sync failed:", error);
-        }
-    }
-    async stop() {
-        if (this.interval) {
-            clearInterval(this.interval);
-            this.interval = null;
-        }
-    }
-    async pollSource(sourceId) {
-        return this.syncSource(sourceId);
-    }
-    status() {
-        return {
-            activeSourceIds: Array.from(this.inFlight.values()).sort(),
-            erroredSourceIds: Array.from(this.errorCounts.keys()).sort(),
-        };
-    }
-    async syncAll() {
-        const sources = this.store
-            .listSources()
-            .filter((source) => source.sourceType === "feishu_bot" && source.status !== "paused");
-        for (const source of sources) {
-            try {
-                await this.syncSource(source.sourceId);
-            }
-            catch (error) {
-                console.warn(`feishu_bot sync failed for ${source.sourceId}:`, error);
-            }
-        }
-    }
-    async syncSource(sourceId) {
-        if (this.inFlight.has(sourceId)) {
-            return {
-                sourceId,
-                sourceType: "feishu_bot",
-                appended: 0,
-                deduped: 0,
-                eventsRead: 0,
-                note: "source sync already in flight",
-            };
-        }
-        this.inFlight.add(sourceId);
-        try {
-            const source = this.store.getSource(sourceId);
-            if (!source) {
-                throw new Error(`unknown source: ${sourceId}`);
-            }
-            const config = parseFeishuSourceConfig(source);
-            if (source.status === "error") {
-                const retryAt = this.nextRetryAt.get(sourceId) ?? 0;
-                if (Date.now() < retryAt) {
-                    return {
-                        sourceId,
-                        sourceType: "feishu_bot",
-                        appended: 0,
-                        deduped: 0,
-                        eventsRead: 0,
-                        note: "error backoff not elapsed",
-                    };
-                }
-            }
-            let checkpoint = parseFeishuCheckpoint(source.checkpoint);
-            const subscription = await this.client.ensureLongConnectionSubscription(config, checkpoint);
-            if (subscription.job_id !== checkpoint.uxcJobId) {
-                checkpoint = { ...checkpoint, uxcJobId: subscription.job_id };
-            }
-            const batch = await this.client.readSubscriptionEvents(checkpoint.uxcJobId, checkpoint.afterSeq ?? 0);
-            let appended = 0;
-            let deduped = 0;
-            for (const event of batch.events) {
-                if (event.event_kind !== "data") {
-                    continue;
-                }
-                const normalized = normalizeFeishuBotEvent(source, config, event.data);
-                if (!normalized) {
-                    continue;
-                }
-                const result = await this.appendSourceEvent(normalized);
-                appended += result.appended;
-                deduped += result.deduped;
-            }
-            this.store.updateSourceRuntime(sourceId, {
-                status: "active",
-                checkpoint: JSON.stringify({
-                    ...checkpoint,
-                    uxcJobId: checkpoint.uxcJobId,
-                    afterSeq: batch.nextAfterSeq,
-                    lastEventAt: new Date().toISOString(),
-                    lastError: null,
-                }),
-            });
-            this.errorCounts.delete(sourceId);
-            this.nextRetryAt.delete(sourceId);
-            return {
-                sourceId,
-                sourceType: "feishu_bot",
-                appended,
-                deduped,
-                eventsRead: batch.events.length,
-                note: `subscription status=${batch.status}`,
-            };
-        }
-        catch (error) {
-            const source = this.store.getSource(sourceId);
-            if (source) {
-                const checkpoint = parseFeishuCheckpoint(source.checkpoint);
-                const nextErrorCount = (this.errorCounts.get(sourceId) ?? 0) + 1;
-                this.errorCounts.set(sourceId, nextErrorCount);
-                this.nextRetryAt.set(sourceId, Date.now() + computeErrorBackoffMs(DEFAULT_SYNC_INTERVAL_SECS, nextErrorCount));
-                this.store.updateSourceRuntime(sourceId, {
-                    status: "error",
-                    checkpoint: JSON.stringify({
-                        ...checkpoint,
-                        lastError: error instanceof Error ? error.message : String(error),
-                    }),
-                });
-            }
-            throw error;
-        }
-        finally {
-            this.inFlight.delete(sourceId);
-        }
-    }
-}
-exports.FeishuSourceRuntime = FeishuSourceRuntime;
-function computeErrorBackoffMs(syncIntervalSecs, errorCount) {
-    const baseMs = Math.max(1, syncIntervalSecs) * 1000;
-    const multiplier = Math.min(2 ** Math.max(0, errorCount - 1), MAX_ERROR_BACKOFF_MULTIPLIER);
-    return baseMs * multiplier;
-}
 class FeishuDeliveryAdapter {
     client;
     constructor(client) {
@@ -376,17 +163,6 @@ function parseFeishuSourceConfig(source) {
         chatIds: asStringArray(config.chatIds) ?? undefined,
     };
 }
-function parseFeishuCheckpoint(checkpoint) {
-    if (!checkpoint) {
-        return {};
-    }
-    try {
-        return JSON.parse(checkpoint);
-    }
-    catch {
-        return {};
-    }
-}
 function parseDeliveryConfig(payload) {
     return {
         endpoint: asString(payload.endpoint) ?? undefined,

package/dist/src/sources/github.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GithubDeliveryAdapter = exports.GithubSourceRuntime = exports.GithubUxcClient = exports.DEFAULT_GITHUB_EVENT_TYPES = exports.GITHUB_ENDPOINT = void 0;
+exports.GithubDeliveryAdapter = exports.GithubUxcClient = exports.DEFAULT_GITHUB_EVENT_TYPES = exports.GITHUB_ENDPOINT = void 0;
 exports.normalizeGithubRepoEvent = normalizeGithubRepoEvent;
 exports.parseGithubSourceConfig = parseGithubSourceConfig;
 const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
@@ -11,64 +11,11 @@ exports.DEFAULT_GITHUB_EVENT_TYPES = [
     "PullRequestEvent",
     "PullRequestReviewCommentEvent",
 ];
-const MAX_ERROR_BACKOFF_MULTIPLIER = 8;
 class GithubUxcClient {
     client;
     constructor(client = new uxc_daemon_client_1.UxcDaemonClient({ env: process.env })) {
         this.client = client;
     }
-    async ensureRepoEventsSubscription(config, checkpoint) {
-        if (checkpoint.uxcJobId) {
-            try {
-                const status = await this.client.subscribeStatus(checkpoint.uxcJobId);
-                if (status.status === "running" || status.status === "reconnecting") {
-                    return {
-                        job_id: checkpoint.uxcJobId,
-                        mode: "poll",
-                        protocol: "openapi",
-                        endpoint: exports.GITHUB_ENDPOINT,
-                        sink: "memory:",
-                        status: status.status,
-                    };
-                }
-            }
-            catch {
-                // Recreate the job below.
-            }
-        }
-        const started = await this.client.subscribeStart({
-            endpoint: exports.GITHUB_ENDPOINT,
-            operationId: "get:/repos/{owner}/{repo}/events",
-            args: { owner: config.owner, repo: config.repo, per_page: config.perPage ?? 10 },
-            mode: "poll",
-            pollConfig: {
-                interval_secs: config.pollIntervalSecs ?? 30,
-                extract_items_pointer: "",
-                checkpoint_strategy: {
-                    type: "item_key",
-                    item_key_pointer: "/id",
-                    seen_window: 1024,
-                },
-            },
-            options: { auth: config.uxcAuth },
-            sink: "memory:",
-            ephemeral: false,
-        });
-        return started;
-    }
-    async readSubscriptionEvents(jobId, afterSeq) {
-        const response = await this.client.subscriptionEvents({
-            jobId,
-            afterSeq,
-            limit: 100,
-            waitMs: 10,
-        });
-        return {
-            events: response.events,
-            nextAfterSeq: response.next_after_seq,
-            status: response.status,
-        };
-    }
     async createIssueComment(input) {
         await this.client.call({
             endpoint: exports.GITHUB_ENDPOINT,
@@ -98,177 +45,6 @@ class GithubUxcClient {
     }
 }
 exports.GithubUxcClient = GithubUxcClient;
-class GithubSourceRuntime {
-    store;
-    appendSourceEvent;
-    client;
-    interval = null;
-    inFlight = new Set();
-    errorCounts = new Map();
-    nextRetryAt = new Map();
-    constructor(store, appendSourceEvent, client) {
-        this.store = store;
-        this.appendSourceEvent = appendSourceEvent;
-        this.client = client ?? new GithubUxcClient();
-    }
-    async ensureSource(source) {
-        if (source.sourceType !== "github_repo") {
-            return;
-        }
-        const config = parseGithubSourceConfig(source);
-        const checkpoint = parseGithubCheckpoint(source.checkpoint);
-        const started = await this.client.ensureRepoEventsSubscription(config, checkpoint);
-        this.store.updateSourceRuntime(source.sourceId, {
-            status: "active",
-            checkpoint: JSON.stringify({
-                ...checkpoint,
-                uxcJobId: started.job_id,
-            }),
-        });
-    }
-    async start() {
-        if (this.interval) {
-            return;
-        }
-        this.interval = setInterval(() => {
-            void this.syncAll();
-        }, 2_000);
-        try {
-            await this.syncAll();
-        }
-        catch (error) {
-            console.warn("github_repo initial sync failed:", error);
-        }
-    }
-    async stop() {
-        if (this.interval) {
-            clearInterval(this.interval);
-            this.interval = null;
-        }
-    }
-    async pollSource(sourceId) {
-        return this.syncSource(sourceId);
-    }
-    status() {
-        return {
-            activeSourceIds: Array.from(this.inFlight.values()).sort(),
-            erroredSourceIds: Array.from(this.errorCounts.keys()).sort(),
-        };
-    }
-    async syncAll() {
-        const sources = this.store
-            .listSources()
-            .filter((source) => source.sourceType === "github_repo" && source.status !== "paused");
-        for (const source of sources) {
-            try {
-                await this.syncSource(source.sourceId);
-            }
-            catch (error) {
-                console.warn(`github_repo sync failed for ${source.sourceId}:`, error);
-            }
-        }
-    }
-    async syncSource(sourceId) {
-        if (this.inFlight.has(sourceId)) {
-            return {
-                sourceId,
-                sourceType: "github_repo",
-                appended: 0,
-                deduped: 0,
-                eventsRead: 0,
-                note: "source sync already in flight",
-            };
-        }
-        this.inFlight.add(sourceId);
-        try {
-            const source = this.store.getSource(sourceId);
-            if (!source) {
-                throw new Error(`unknown source: ${sourceId}`);
-            }
-            const config = parseGithubSourceConfig(source);
-            if (source.status === "error") {
-                const retryAt = this.nextRetryAt.get(sourceId) ?? 0;
-                if (Date.now() < retryAt) {
-                    return {
-                        sourceId,
-                        sourceType: "github_repo",
-                        appended: 0,
-                        deduped: 0,
-                        eventsRead: 0,
-                        note: "error backoff not elapsed",
-                    };
-                }
-            }
-            let checkpoint = parseGithubCheckpoint(source.checkpoint);
-            const subscription = await this.client.ensureRepoEventsSubscription(config, checkpoint);
-            if (subscription.job_id !== checkpoint.uxcJobId) {
-                checkpoint = { ...checkpoint, uxcJobId: subscription.job_id };
-            }
-            const batch = await this.client.readSubscriptionEvents(checkpoint.uxcJobId, checkpoint.afterSeq ?? 0);
-            let appended = 0;
-            let deduped = 0;
-            for (const event of batch.events) {
-                if (event.event_kind !== "data") {
-                    continue;
-                }
-                const normalized = normalizeGithubRepoEvent(source, config, event.data);
-                if (!normalized) {
-                    continue;
-                }
-                const result = await this.appendSourceEvent(normalized);
-                appended += result.appended;
-                deduped += result.deduped;
-            }
-            this.store.updateSourceRuntime(sourceId, {
-                status: "active",
-                checkpoint: JSON.stringify({
-                    ...checkpoint,
-                    uxcJobId: checkpoint.uxcJobId,
-                    afterSeq: batch.nextAfterSeq,
-                    lastEventAt: new Date().toISOString(),
-                    lastError: null,
-                }),
-            });
-            this.errorCounts.delete(sourceId);
-            this.nextRetryAt.delete(sourceId);
-            return {
-                sourceId,
-                sourceType: "github_repo",
-                appended,
-                deduped,
-                eventsRead: batch.events.length,
-                note: `subscription status=${batch.status}`,
-            };
-        }
-        catch (error) {
-            const source = this.store.getSource(sourceId);
-            if (source) {
-                const checkpoint = parseGithubCheckpoint(source.checkpoint);
-                const config = parseGithubSourceConfig(source);
-                const nextErrorCount = (this.errorCounts.get(sourceId) ?? 0) + 1;
-                this.errorCounts.set(sourceId, nextErrorCount);
-                this.nextRetryAt.set(sourceId, Date.now() + computeErrorBackoffMs(config.pollIntervalSecs ?? 30, nextErrorCount));
-                this.store.updateSourceRuntime(sourceId, {
-                    status: "error",
-                    checkpoint: JSON.stringify({
-                        ...checkpoint,
-                        lastError: error instanceof Error ? error.message : String(error),
-                    }),
-                });
-            }
-            throw error;
-        }
-        finally {
-            this.inFlight.delete(sourceId);
-        }
-    }
-}
-exports.GithubSourceRuntime = GithubSourceRuntime;
-function computeErrorBackoffMs(pollIntervalSecs, errorCount) {
-    const baseMs = Math.max(1, pollIntervalSecs) * 1000;
-    const multiplier = Math.min(2 ** Math.max(0, errorCount - 1), MAX_ERROR_BACKOFF_MULTIPLIER);
-    return baseMs * multiplier;
-}
 class GithubDeliveryAdapter {
     client;
     constructor(client) {
@@ -332,7 +108,7 @@ function normalizeGithubRepoEvent(source, config, raw) {
     const url = asString(comment.html_url) ??
         asString(issue.html_url) ??
         asString(pullRequest.html_url) ??
-        asString(event["url"]);
+        asString(event.url);
     const deliveryHandle = buildGithubDeliveryHandle(config, eventType, number, comment);
     return {
         sourceId: source.sourceId,
@@ -416,17 +192,6 @@ function parseGithubSourceConfig(source) {
         eventTypes: asStringArray(config.eventTypes) ?? exports.DEFAULT_GITHUB_EVENT_TYPES,
     };
 }
-function parseGithubCheckpoint(checkpoint) {
-    if (!checkpoint) {
-        return {};
-    }
-    try {
-        return JSON.parse(checkpoint);
-    }
-    catch {
-        return {};
-    }
-}
 function extractLabels(raw) {
     if (!Array.isArray(raw)) {
         return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@fastify/swagger": "^9.5.2",
-    "@holon-run/uxc-daemon-client": "^0.14.0",
+    "@holon-run/uxc-daemon-client": "^0.15.0",
     "fastify": "^5.6.1",
     "jexl": "^2.3.0",
     "sql.js": "^1.13.0"