@holon-run/agentinbox 1.0.2 → 1.0.4

package/dist/src/store.js

@@ -288,8 +288,10 @@ class AgentInboxStore {
         ]);
         this.persist();
     }
-    listSourceHosts() {
-        const rows = this.getAll("select * from source_hosts order by created_at asc");
+    listSourceHosts(limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from source_hosts order by created_at asc, host_id asc limit ?", [limit])
+            : this.getAll("select * from source_hosts order by created_at asc, host_id asc");
         return rows.map((row) => this.mapSourceHost(row));
     }
     updateSourceHostDefinition(hostId, input) {
@@ -362,8 +364,10 @@ class AgentInboxStore {
         });
         this.persist();
     }
-    listSources() {
-        const rows = this.getAll("select * from sources order by created_at asc");
+    listSources(limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from sources order by created_at asc, source_id asc limit ?", [limit])
+            : this.getAll("select * from sources order by created_at asc, source_id asc");
         return rows.map((row) => this.mapSource(row));
     }
     getSourceIdleState(sourceId) {
@@ -505,8 +509,10 @@ class AgentInboxStore {
         this.persist();
         return this.getAgent(agentId);
     }
-    listAgents() {
-        const rows = this.getAll("select * from agents order by created_at asc");
+    listAgents(limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from agents order by created_at asc, agent_id asc limit ?", [limit])
+            : this.getAll("select * from agents order by created_at asc, agent_id asc");
         return rows.map((row) => this.mapAgent(row));
     }
     getInbox(inboxId) {
@@ -556,8 +562,10 @@ class AgentInboxStore {
         this.persist();
         return this.getInbox(inboxId);
     }
-    listInboxes() {
-        const rows = this.getAll("select * from inboxes order by created_at asc");
+    listInboxes(limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from inboxes order by created_at asc, inbox_id asc limit ?", [limit])
+            : this.getAll("select * from inboxes order by created_at asc, inbox_id asc");
         return rows.map((row) => this.mapInbox(row));
     }
     getSubscription(subscriptionId) {
@@ -583,16 +591,41 @@ class AgentInboxStore {
         ]);
         this.persist();
     }
-    listSubscriptions() {
-        const rows = this.getAll("select * from subscriptions order by created_at asc");
+    listSubscriptions(limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from subscriptions order by created_at asc, subscription_id asc limit ?", [limit])
+            : this.getAll("select * from subscriptions order by created_at asc, subscription_id asc");
         return rows.map((row) => this.mapSubscription(row));
     }
-    listSubscriptionsForSource(sourceId) {
-        const rows = this.getAll("select * from subscriptions where source_id = ? order by created_at asc", [sourceId]);
+    listSubscriptionsFiltered(filters) {
+        const clauses = [];
+        const params = [];
+        if (filters?.sourceId) {
+            clauses.push("source_id = ?");
+            params.push(filters.sourceId);
+        }
+        if (filters?.agentId) {
+            clauses.push("agent_id = ?");
+            params.push(filters.agentId);
+        }
+        const where = clauses.length > 0 ? ` where ${clauses.join(" and ")}` : "";
+        const limitClause = typeof filters?.limit === "number" ? " limit ?" : "";
+        if (typeof filters?.limit === "number") {
+            params.push(filters.limit);
+        }
+        const rows = this.getAll(`select * from subscriptions${where} order by created_at asc, subscription_id asc${limitClause}`, params);
+        return rows.map((row) => this.mapSubscription(row));
+    }
+    listSubscriptionsForSource(sourceId, limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from subscriptions where source_id = ? order by created_at asc, subscription_id asc limit ?", [sourceId, limit])
+            : this.getAll("select * from subscriptions where source_id = ? order by created_at asc, subscription_id asc", [sourceId]);
         return rows.map((row) => this.mapSubscription(row));
     }
-    listSubscriptionsForAgent(agentId) {
-        const rows = this.getAll("select * from subscriptions where agent_id = ? order by created_at asc", [agentId]);
+    listSubscriptionsForAgent(agentId, limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from subscriptions where agent_id = ? order by created_at asc, subscription_id asc limit ?", [agentId, limit])
+            : this.getAll("select * from subscriptions where agent_id = ? order by created_at asc, subscription_id asc", [agentId]);
         return rows.map((row) => this.mapSubscription(row));
     }
     listSubscriptionsForHostTrackedResourceRef(hostId, trackedResourceRef) {
@@ -821,12 +854,16 @@ class AgentInboxStore {
         this.persist();
         return this.getActivationTarget(targetId);
     }
-    listActivationTargets() {
-        const rows = this.getAll("select * from activation_targets order by created_at asc");
+    listActivationTargets(limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from activation_targets order by created_at asc, target_id asc limit ?", [limit])
+            : this.getAll("select * from activation_targets order by created_at asc, target_id asc");
         return rows.map((row) => this.mapActivationTarget(row));
     }
-    listActivationTargetsForAgent(agentId) {
-        const rows = this.getAll("select * from activation_targets where agent_id = ? order by created_at asc", [agentId]);
+    listActivationTargetsForAgent(agentId, limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from activation_targets where agent_id = ? order by created_at asc, target_id asc limit ?", [agentId, limit])
+            : this.getAll("select * from activation_targets where agent_id = ? order by created_at asc, target_id asc", [agentId]);
         return rows.map((row) => this.mapActivationTarget(row));
     }
     deleteActivationTarget(agentId, targetId) {
@@ -902,12 +939,16 @@ class AgentInboxStore {
         const row = this.getOne("select * from timers where schedule_id = ?", [scheduleId]);
         return row ? this.mapTimer(row) : null;
     }
-    listTimers() {
-        const rows = this.getAll("select * from timers order by created_at asc");
+    listTimers(limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from timers order by created_at asc, schedule_id asc limit ?", [limit])
+            : this.getAll("select * from timers order by created_at asc, schedule_id asc");
         return rows.map((row) => this.mapTimer(row));
     }
-    listTimersForAgent(agentId) {
-        const rows = this.getAll("select * from timers where agent_id = ? order by created_at asc", [agentId]);
+    listTimersForAgent(agentId, limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from timers where agent_id = ? order by created_at asc, schedule_id asc limit ?", [agentId, limit])
+            : this.getAll("select * from timers where agent_id = ? order by created_at asc, schedule_id asc", [agentId]);
         return rows.map((row) => this.mapTimer(row));
     }
     listDueTimers(cutoffIso) {
@@ -1015,8 +1056,8 @@ class AgentInboxStore {
         this.db.run(`
       insert or ignore into inbox_items (
         item_id, source_id, source_native_id, event_variant, inbox_id, occurred_at,
-        metadata_json, raw_payload_json, delivery_handle_json, acked_at
-      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        metadata_json, raw_payload_json, provider_raw_payload_json, delivery_handle_json, acked_at
+      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `, [
             item.itemId,
             item.sourceId,
@@ -1026,6 +1067,7 @@ class AgentInboxStore {
             item.occurredAt,
             JSON.stringify(item.metadata),
             JSON.stringify(item.rawPayload),
+            item.providerRawPayload ? JSON.stringify(item.providerRawPayload) : null,
             item.deliveryHandle ? JSON.stringify(item.deliveryHandle) : null,
             item.ackedAt ?? null,
         ]);
@@ -1059,6 +1101,7 @@ class AgentInboxStore {
                 occurredAt: item.occurredAt,
                 metadata: item.metadata,
                 rawPayload: item.rawPayload,
+                providerRawPayload: item.providerRawPayload,
                 deliveryHandle: item.deliveryHandle ?? null,
             }),
             count: 1,
@@ -1092,7 +1135,11 @@ class AgentInboxStore {
             filters.push("sequence > ?");
             params.push(Number(anchor.sequence));
         }
-        const rows = this.getAll(`select * from inbox_entries where ${filters.join(" and ")} order by sequence asc`, params);
+        const sql = `select * from inbox_entries where ${filters.join(" and ")} order by sequence asc${typeof options?.limit === "number" ? " limit ?" : ""}`;
+        if (typeof options?.limit === "number") {
+            params.push(options.limit);
+        }
+        const rows = this.getAll(sql, params);
         return this.mapInboxEntries(rows);
     }
     getInboxEntry(entryId) {
@@ -1273,7 +1320,11 @@ class AgentInboxStore {
         if (!includeAcked) {
             filters.push("acked_at is null");
         }
-        const rows = this.getAll(`select * from inbox_items where ${filters.join(" and ")} order by coalesce(inbox_sequence, rowid) asc`, params);
+        const sql = `select * from inbox_items where ${filters.join(" and ")} order by coalesce(inbox_sequence, rowid) asc${typeof options?.limit === "number" ? " limit ?" : ""}`;
+        if (typeof options?.limit === "number") {
+            params.push(options.limit);
+        }
+        const rows = this.getAll(sql, params);
         return rows.map((row) => this.mapInboxItem(row));
     }
     ackItems(inboxId, itemIds, ackedAt) {
@@ -1406,8 +1457,10 @@ class AgentInboxStore {
         const row = this.getOne("select * from streams where stream_id = ?", [streamId]);
         return row ? this.mapStream(row) : null;
     }
-    listStreams() {
-        const rows = this.getAll("select * from streams order by created_at asc");
+    listStreams(limit) {
+        const rows = typeof limit === "number"
+            ? this.getAll("select * from streams order by created_at asc, stream_id asc limit ?", [limit])
+            : this.getAll("select * from streams order by created_at asc, stream_id asc");
         return rows.map((row) => this.mapStream(row));
     }
     getStreamBySourceId(sourceId) {
@@ -1418,14 +1471,15 @@ class AgentInboxStore {
         const occurredAt = event.occurredAt ?? (0, util_1.nowIso)();
         const metadataJson = JSON.stringify(event.metadata ?? {});
         const rawPayloadJson = JSON.stringify(event.rawPayload ?? {});
+        const providerRawPayloadJson = event.providerRawPayload ? JSON.stringify(event.providerRawPayload) : null;
         const deliveryHandleJson = event.deliveryHandle ? JSON.stringify(event.deliveryHandle) : null;
         for (let attempt = 0; attempt < 5; attempt += 1) {
             const before = this.changes();
             this.db.run(`
         insert or ignore into stream_events (
           stream_event_id, stream_id, source_id, source_native_id, event_variant,
-          occurred_at, metadata_json, raw_payload_json, delivery_handle_json, created_at
-        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          occurred_at, metadata_json, raw_payload_json, provider_raw_payload_json, delivery_handle_json, created_at
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `, [
                 (0, util_1.generateCanonicalId)("evt"),
                 streamId,
@@ -1435,6 +1489,7 @@ class AgentInboxStore {
                 occurredAt,
                 metadataJson,
                 rawPayloadJson,
+                providerRawPayloadJson,
                 deliveryHandleJson,
                 (0, util_1.nowIso)(),
             ]);
@@ -1821,6 +1876,9 @@ class AgentInboxStore {
             occurredAt: String(row.occurred_at),
             metadata: parseJson(row.metadata_json),
             rawPayload: parseJson(row.raw_payload_json),
+            providerRawPayload: row.provider_raw_payload_json
+                ? parseJson(row.provider_raw_payload_json)
+                : undefined,
             deliveryHandle: row.delivery_handle_json
                 ? parseJson(row.delivery_handle_json)
                 : null,
@@ -1858,6 +1916,7 @@ class AgentInboxStore {
                 occurredAt: item.occurredAt,
                 metadata: item.metadata,
                 rawPayload: item.rawPayload,
+                providerRawPayload: item.providerRawPayload,
                 item,
             };
         }
@@ -2130,6 +2189,9 @@ class AgentInboxStore {
             occurredAt: String(row.occurred_at),
             metadata: parseJson(row.metadata_json),
             rawPayload: parseJson(row.raw_payload_json),
+            providerRawPayload: row.provider_raw_payload_json
+                ? parseJson(row.provider_raw_payload_json)
+                : undefined,
             deliveryHandle: row.delivery_handle_json
                 ? parseJson(row.delivery_handle_json)
                 : null,

package/drizzle/migrations/0004_provider_raw_payload.sql

@@ -0,0 +1,3 @@
+alter table inbox_items add column provider_raw_payload_json text;
+
+alter table stream_events add column provider_raw_payload_json text;

package/drizzle/schema.ts

@@ -173,6 +173,7 @@ export const inboxItems = sqliteTable("inbox_items", {
   occurredAt: text("occurred_at").notNull(),
   metadataJson: text("metadata_json").notNull(),
   rawPayloadJson: text("raw_payload_json").notNull(),
+  providerRawPayloadJson: text("provider_raw_payload_json"),
   deliveryHandleJson: text("delivery_handle_json"),
   ackedAt: text("acked_at"),
 }, (table) => ({
@@ -302,6 +303,7 @@ export const streamEvents = sqliteTable("stream_events", {
   occurredAt: text("occurred_at").notNull(),
   metadataJson: text("metadata_json").notNull(),
   rawPayloadJson: text("raw_payload_json").notNull(),
+  providerRawPayloadJson: text("provider_raw_payload_json"),
   deliveryHandleJson: text("delivery_handle_json"),
   createdAt: text("created_at").notNull(),
 }, (table) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {
@@ -20,6 +20,7 @@
   "files": [
     "dist/src/",
     "scripts/",
+    "skills/",
     "drizzle/",
     "README.md",
     "LICENSE"
@@ -43,7 +44,7 @@
   },
   "dependencies": {
     "@fastify/swagger": "^9.5.2",
-    "@holon-run/uxc-daemon-client": "^0.15.3",
+    "@holon-run/uxc-daemon-client": "^0.15.4",
     "fastify": "^5.6.1",
     "jexl": "^2.3.0",
     "sql.js": "^1.13.0"

package/skills/README.md

@@ -0,0 +1,18 @@
+# Skills
+
+The docs site exposes selected repository skills so they can be handed directly
+to another agent.
+
+For `AgentInbox`, the preferred first-run path is skill-first onboarding:
+
+- hand the bundled `AgentInbox` skill to the agent
+- let the agent verify `agentinbox`, `uxc`, and GitHub auth
+- let the agent register the current session and set up standing subscriptions
+
+<!-- INDEX:START -->
+
+- [agentinbox](./agentinbox/)
+  Use the local AgentInbox service to onboard the current session, connect GitHub through UXC, and operate sources, subscriptions, and the agent inbox.
+  <!-- mdorigin:index kind=article -->
+
+<!-- INDEX:END -->

package/skills/agentinbox/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: agentinbox
+description: Use the local AgentInbox service to onboard the current session, manage shared sources and subscriptions, connect external providers such as GitHub through UXC, and operate the agent inbox.
+metadata:
+  short-description: Operate AgentInbox sources and subscriptions
+---
+
+# AgentInbox Skill
+
+Use this skill when the current agent should set up or use the local
+`agentinbox` daemon.
+
+Primary docs:
+
+- `https://agentinbox.holon.run/guides/onboarding-with-agent-skill`
+- `https://agentinbox.holon.run/guides/getting-started`
+- `https://agentinbox.holon.run/guides/review-workflows`
+- `https://agentinbox.holon.run/reference/cli`
+
+## Install
+
+Install `agentinbox` if it is not already available:
+
+```bash
+npm install -g @holon-run/agentinbox
+```
+
+Install `uxc` if GitHub or Feishu adapters are needed:
+
+```bash
+brew tap holon-run/homebrew-tap
+brew install uxc
+```
+
+UXC repository:
+
+- `https://github.com/holon-run/uxc`
+
+## First-Run Onboarding
+
+Recommended first-run sequence:
+
+1. if GitHub access is needed and `gh` is already authenticated, import that auth into `uxc`
+2. register the current terminal session
+3. follow the required sources or resources using the docs examples
+
+If GitHub-backed adapters are needed:
+
+```bash
+gh auth status
+uxc auth credential import github --from gh
+```
+
+This `gh` import path requires `uxc` 0.15.3 or newer.
+
+Register the current terminal/runtime session:
+
+```bash
+agentinbox agent register
+```
+
+Treat the returned `agentId` as the stable identity for later commands.
+
+## Usage Discipline
+
+Defaults:
+
+- do not create one GitHub source per PR unless the source itself must be PR-
+  scoped
+- prefer shared repo/repo-CI sources plus narrow follows or subscriptions
+- prefer `agentinbox follow` over manual `subscription add` when a follow
+  template exists
+- if a source exposes only subscription shortcuts, prefer the shortcut over
+  manually reconstructing the same filter and lifecycle fields
+- treat unused task-specific subscriptions as cleanup debt
+- if GitHub polling volume looks high, inspect old subscriptions and duplicate
+  temporary sources before adding more
+
+This matches the AgentInbox model: sources are shared hosting units, while
+subscriptions carry agent-specific filtering and delivery intent.
+
+## Default Async Lifecycle
+
+Default to AgentInbox when the work is not purely synchronous in the current
+session.
+
+Typical cases:
+
+- delayed follow-up that should happen after you stop actively looking at the
+  terminal
+- waiting for PR review, CI completion, issue replies, or other external
+  events
+- anything that must survive session boundaries instead of living only in chat
+  memory
+- reminders that should fire at a specific time or on a recurring schedule
+
+Important boundary:
+
+- inbox items, subscriptions, and timers can outlive the current terminal
+  session
+- terminal delivery does not automatically survive session boundaries just
+  because the inbox state does
+- if the original runtime/terminal disappears, items may keep accumulating in
+  the inbox while notifications stop reaching you
+- if a later session should resume the same logical agent, re-register or
+  explicitly rebind that agent to the current terminal before assuming prompt
+  delivery is live again
+
+Lifecycle:
+
+1. register once per live terminal/runtime session
+2. reuse broad shared sources
+3. add narrow task-scoped follows, subscriptions, or timers
+4. read inbox items in bounded batches and ack only the reviewed batch
+5. clean up task-scoped subscriptions/timers after merge, closure, or abandonment
+
+For PR and review workflows, prefer `follow` templates. They reuse shared
+sources, expand the source-specific filters, and attach cleanup behavior:
+
+```bash
+agentinbox agent register
+agentinbox follow github pr --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=87 --arg withCi=true
+agentinbox inbox read --agent-id <agentId>
+agentinbox inbox ack --agent-id <agentId> --through <lastEntryId>
+```
+
+Ack discipline:
+
+- prefer `agentinbox inbox ack --agent-id <agentId> --through <lastEntryId>`
+  after reading a reviewed batch
+- avoid `ack --all` unless you explicitly verified that every current item
+  should be cleared
+- do not ack speculative future work just because the current terminal message
+  was seen
+
+Timer intent:
+
+- use `agentinbox timer add` when the trigger is time-based rather than source-based
+- prefer timers over inventing fake local events for reminders like "check CI
+  in 30 minutes" or "revisit this PR tomorrow morning"
+
+## Core Commands
+
+Follow high-level templates:
+
+```bash
+agentinbox follow github repo --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox
+agentinbox follow github pr --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=87 --arg withCi=true
+agentinbox follow github issue --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=180
+agentinbox follow github pr --agent-id <agentId> --args-json '{"owner":"holon-run","repo":"agentinbox","number":87,"withCi":true}'
+```
+
+Use `follow` as the default path for GitHub repo, PR, and issue tracking. Drop
+to `source schema` plus `subscription add` only when you need a custom filter or
+the source has no follow template.
+
+Advanced source/subscription commands:
+
+```bash
+agentinbox source list
+agentinbox source show <sourceId>
+agentinbox source schema <sourceId>
+agentinbox source add <hostId> repo_events <owner>/<repo> --config-json '{"owner":"holon-run","repo":"agentinbox"}'
+agentinbox source add <hostId> ci_runs <owner>/<repo> --config-json '{"owner":"holon-run","repo":"agentinbox","pollIntervalSecs":30}'
+agentinbox subscription add <sourceId> --shortcut pr --shortcut-args-json '{"number":87}'
+agentinbox subscription add <sourceId> --filter-json '{"metadata":{"headBranch":"main","conclusion":"failure"}}'
+agentinbox subscription list --agent-id <agentId>
+agentinbox subscription remove <subscriptionId>
+```
+
+Use manual subscriptions for advanced filters, custom source kinds, or when
+debugging template expansion. If `subscriptionSchema.shortcuts` is non-empty
+but no follow template is available, prefer those shortcut entries first.
+
+Read and ack the inbox:
+
+```bash
+agentinbox inbox read --agent-id <agentId>
+agentinbox inbox ack --agent-id <agentId> --through <lastEntryId>
+agentinbox inbox send --agent-id <agentId> --message "Please review PR #87"
+agentinbox inbox watch --agent-id <agentId>
+agentinbox inbox ack --agent-id <agentId> --all
+```
+
+Default to a batch-bounded ack flow:
+
+1. read the inbox items you intend to process
+2. identify the last item you actually reviewed in that batch
+3. ack with `--through <lastEntryId>`
+
+Use `ack --all` only after explicitly verifying every current item should be
+cleared. Use `inbox send` for local operator/direct text ingress.
+
+Manage timers:
+
+```bash
+agentinbox timer add --agent-id <agentId> --at <RFC3339_TIMESTAMP> --message "Check the morning build"
+agentinbox timer add --agent-id <agentId> --every 24h --message "Review today's open PRs"
+agentinbox timer add --agent-id <agentId> --cron "0 8 * * *" --timezone Asia/Shanghai --message "Daily triage"
+agentinbox timer list
+agentinbox timer list --agent-id <agentId>
+agentinbox timer pause <scheduleId>
+agentinbox timer resume <scheduleId>
+agentinbox timer remove <scheduleId>
+```
+
+Activation targets:
+
+```bash
+agentinbox agent target list <agentId>
+agentinbox agent target add webhook <agentId> --url http://127.0.0.1:8787/webhook
+agentinbox agent target remove <agentId> <targetId>
+```
+
+For filtering strategy and review workflow setup, follow the docs links above
+instead of re-explaining the full architecture here.
+
+## Troubleshooting
+
+Do not start every task by checking daemon status; normal CLI commands should
+auto-connect or surface actionable errors. Use these checks after the first
+AgentInbox command fails, notifications stop arriving, or you suspect a stale
+terminal binding:
+
+```bash
+agentinbox --version
+agentinbox daemon status
+agentinbox daemon start
+agentinbox agent register --agent-id <agentId> --force-rebind
+```
+
+If GitHub-backed sources fail, verify UXC and imported GitHub auth only after
+the failure points there:
+
+```bash
+uxc --version
+gh auth status
+uxc auth credential import github --from gh
+```

package/skills/agentinbox/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: AgentInbox
+short_description: Operate the local AgentInbox service for shared sources, subscriptions, inbox workflows, activation targets, and external providers such as GitHub.
+default_prompt: Use AgentInbox to register the current session, inspect sources and subscriptions, prefer broad reusable sources with subscription-side filtering, remove stale subscriptions when they are no longer needed, and read or watch the agent inbox.