@holon-run/agentinbox 0.1.0 → 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.13.3 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`
@@ -82,15 +127,34 @@ Register the current terminal session:
 ```bash
 agentinbox agent register
 agentinbox agent register --agent-id agent-alpha
+agentinbox agent current
 ```
 
 Create a local source and publish an event:
 
 ```bash
 agentinbox source add local_event local-demo
-agentinbox subscription add <agent_id> <source_id>
+agentinbox subscription add <source_id>
+agentinbox subscription add <source_id> --agent-id <agent_id>
+agentinbox subscription add <source_id> --filter-file ./filter.json
+cat filter.json | agentinbox subscription add <source_id> --filter-stdin
 agentinbox source event <source_id> --native-id demo-1 --event local.demo
-agentinbox inbox read <agent_id>
+agentinbox inbox read
+agentinbox inbox read --agent-id <agent_id>
+```
+
+Update an existing source in place:
+
+```bash
+agentinbox source update <source_id> --config-json '{"channel":"infra"}'
+agentinbox source update <source_id> --clear-config-ref
+```
+
+Pause and resume a managed remote source:
+
+```bash
+agentinbox source pause <remote_source_id>
+agentinbox source resume <remote_source_id>
 ```
 
 Remove a task-specific subscription without deleting the whole agent:
@@ -108,7 +172,7 @@ Public docs live in the mdorigin site under [`docs/site`](./docs/site).
 - onboarding with the agent skill: [`docs/site/guides/onboarding-with-agent-skill.md`](./docs/site/guides/onboarding-with-agent-skill.md)
 - getting started: [`docs/site/guides/getting-started.md`](./docs/site/guides/getting-started.md)
 - review workflows: [`docs/site/guides/review-workflows.md`](./docs/site/guides/review-workflows.md)
-- skill docs: [`docs/site/skills/README.md`](./docs/site/skills/README.md)
+- skill docs: [`skills/README.md`](./skills/README.md)
 - CLI reference: [`docs/site/reference/cli.md`](./docs/site/reference/cli.md)
 - source types: [`docs/site/reference/source-types.md`](./docs/site/reference/source-types.md)
 - architecture: [`docs/site/concepts/architecture.md`](./docs/site/concepts/architecture.md)
@@ -148,20 +212,16 @@ Build docs directory indexes:
 npm run docs:index
 ```
 
-## Release
-
-`AgentInbox` releases are tag-driven.
+Generate new SQLite migrations after schema changes:
 
-- update [package.json](./package.json) and [CHANGELOG.md](./CHANGELOG.md) in a PR before release
-- merge to `main`
-- run the manual terminal smoke matrix in [testcases/manual/manual-terminal-qa.md](./testcases/manual/manual-terminal-qa.md)
-- push a tag in the form `v<package.json version>`
-
-Public beta tags such as `v0.1.0-beta.1` publish to npm with the `beta`
-dist-tag. Stable tags such as `v0.1.0` publish with the `latest` dist-tag.
+```bash
+npm run db:migrations:generate
+```
 
-The operational checklist lives in
-[testcases/manual/release-checklist.md](./testcases/manual/release-checklist.md).
+`AgentInbox` now upgrades SQLite state with versioned SQL migrations in
+`drizzle/migrations`. On upgrade with pending migrations, the daemon creates a
+local backup next to the DB file (for example,
+`~/.agentinbox/agentinbox.sqlite.backup-<timestamp>`).
 
 ## License
 

package/dist/src/adapters.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdapterRegistry = void 0;
 const feishu_1 = require("./sources/feishu");
 const github_1 = require("./sources/github");
-const github_ci_1 = require("./sources/github_ci");
+const remote_1 = require("./sources/remote");
 class NoopSourceAdapter {
     sourceType;
     constructor(sourceType) {
@@ -12,6 +12,9 @@ class NoopSourceAdapter {
     async ensureSource(_source) {
         return;
     }
+    async validateSource(_source) {
+        return;
+    }
     async pollSource(sourceId) {
         return {
             sourceId,
@@ -29,24 +32,19 @@ class NoopDeliveryAdapter {
     }
 }
 class AdapterRegistry {
-    fixtureSource = new NoopSourceAdapter("fixture");
     localEventSource = new NoopSourceAdapter("local_event");
-    remoteSource = new NoopSourceAdapter("remote_source");
-    feishuSource;
-    githubSource;
-    githubCiSource;
-    fixtureDelivery = new NoopDeliveryAdapter();
+    remoteSource;
+    defaultDelivery = new NoopDeliveryAdapter();
     feishuDelivery = new feishu_1.FeishuDeliveryAdapter();
     githubDelivery = new github_1.GithubDeliveryAdapter();
-    constructor(store, appendSourceEvent) {
-        this.feishuSource = new feishu_1.FeishuSourceRuntime(store, appendSourceEvent);
-        this.githubSource = new github_1.GithubSourceRuntime(store, appendSourceEvent);
-        this.githubCiSource = new github_ci_1.GithubCiSourceRuntime(store, appendSourceEvent);
+    constructor(store, appendSourceEvent, options) {
+        this.remoteSource = new remote_1.RemoteSourceRuntime(store, appendSourceEvent, {
+            homeDir: options?.homeDir,
+            client: options?.remoteSourceClient,
+            profileRegistry: options?.remoteProfileRegistry,
+        });
     }
     sourceAdapterFor(type) {
-        if (type === "fixture") {
-            return this.fixtureSource;
-        }
         if (type === "local_event") {
             return this.localEventSource;
         }
@@ -54,37 +52,30 @@ class AdapterRegistry {
             return this.remoteSource;
         }
         if (type === "github_repo") {
-            return this.githubSource;
+            return this.remoteSource;
         }
         if (type === "github_repo_ci") {
-            return this.githubCiSource;
+            return this.remoteSource;
         }
         if (type === "feishu_bot") {
-            return this.feishuSource;
+            return this.remoteSource;
         }
-        return this.fixtureSource;
+        return this.localEventSource;
     }
     deliveryAdapterFor(provider) {
-        if (provider === "fixture") {
-            return this.fixtureDelivery;
-        }
         if (provider === "feishu") {
             return this.feishuDelivery;
         }
         if (provider === "github") {
             return this.githubDelivery;
         }
-        return this.fixtureDelivery;
+        return this.defaultDelivery;
     }
     async start() {
-        await this.feishuSource.start?.();
-        await this.githubSource.start?.();
-        await this.githubCiSource.start?.();
+        await this.remoteSource.start?.();
     }
     async stop() {
-        await this.feishuSource.stop?.();
-        await this.githubSource.stop?.();
-        await this.githubCiSource.stop?.();
+        await this.remoteSource.stop?.();
     }
     async pollSource(source) {
         const adapter = this.sourceAdapterFor(source.sourceType);
@@ -100,11 +91,27 @@ class AdapterRegistry {
         }
         return adapter.pollSource(source.sourceId);
     }
+    async pauseSource(source) {
+        const adapter = this.sourceAdapterFor(source.sourceType);
+        if (!adapter.pauseSource) {
+            throw new Error(`source type ${source.sourceType} does not support pause`);
+        }
+        await adapter.pauseSource?.(source.sourceId);
+    }
+    async resumeSource(source) {
+        const adapter = this.sourceAdapterFor(source.sourceType);
+        if (!adapter.resumeSource) {
+            throw new Error(`source type ${source.sourceType} does not support resume`);
+        }
+        await adapter.resumeSource?.(source.sourceId);
+    }
+    async removeSource(source) {
+        const adapter = this.sourceAdapterFor(source.sourceType);
+        await adapter.removeSource?.(source.sourceId);
+    }
     status() {
         return {
-            feishu: this.feishuSource.status?.() ?? {},
-            github: this.githubSource.status?.() ?? {},
-            githubCi: this.githubCiSource.status?.() ?? {},
+            remote: this.remoteSource.status?.() ?? {},
         };
     }
 }