Follow Command And Template Expansion

Summary

AgentInbox should add a high-level follow command for the common operator workflow:

• express what to follow
• let AgentInbox ensure the required host, stream, and subscription objects
• reuse existing shared runtime state when possible

This command should not replace the internal host and stream model.

Instead, it should sit above the existing model and compile a user intent into an idempotent ensure plan.

The key architecture rule is:

• core owns generic ensure orchestration
• source modules own follow templates and intent expansion

That keeps the product simpler to operate without hardcoding provider-specific flows into the core.

Problem

The current mental model is correct but too operational for common use:

1. create or find a host
2. create or find a stream
3. add a subscription

This exposes storage and runtime structure directly to the user even when the user intent is much simpler:

• follow this repo
• follow this PR
• follow this issue
• follow this search

That makes the CLI feel heavier than it needs to be, especially for remote-module-backed providers where the actual provider logic should stay at the edge.

There is also a naming problem:

• inbox watch already suggests a foreground, ongoing, stream-like read loop
• reusing watch for lifecycle setup would suggest long-lived connection behavior instead of declarative follow intent

So the simplification should not be a watch alias.

Goals

• add one high-level command for common subscription setup
• preserve the existing host, stream, and subscription architecture
• keep shared source reuse and idempotent stream reuse
• avoid hardcoding provider-specific follow flows in the core
• let source modules advertise what follow intents they support
• keep low-level commands available for debugging and advanced operations
• avoid conflating declarative setup with foreground inbox reading

Non-Goals

• do not remove host add, source add, or subscription add
• do not flatten the model into one private connector per agent
• do not turn follow into a long-running read loop
• do not require every provider to expose identical follow templates
• do not move provider SDK logic or runtime semantics into the core

Terms

Follow Intent

A user-facing declaration of what ongoing thing should be tracked.

Examples:

• GitHub repo activity for holon-run/agentinbox
• GitHub PR #167 with CI
• X filtered stream for a query

Follow Template

A provider- or module-defined template that knows how to expand a follow intent into concrete AgentInbox resources.

Examples:

• github.repo
• github.pr
• github.issue
• x.filtered_stream
• x.recent_search

Ensure Plan

The compiled plan returned by a module and executed by the core.

It should describe:

• which host to create or reuse
• which stream or streams to create or reuse
• which subscriptions to create or reuse

Proposed UX

The high-level command should be:

agentinbox follow ...

This verb communicates:

• ongoing interest
• durable setup
• not a foreground read loop

watch should remain reserved for commands like:

agentinbox inbox watch

where the operator expects an active blocking read path.

Example Intents

Illustrative examples:

agentinbox follow github repo holon-run/agentinbox
agentinbox follow github pr holon-run/agentinbox 167 --with-ci
agentinbox follow github issue holon-run/agentinbox 166
agentinbox follow x recent-search "from:holon_run agentinbox"

The exact CLI argument shape can vary by module, but the user should always be thinking in terms of a follow intent, not in terms of hand-assembling storage objects.

Core Design

1. Keep Host, Stream, Subscription As Internal Reality

The follow command is a user-facing convenience layer, not a model rewrite.

The core operational model remains:

• host
• stream
• subscription

follow should compile into these existing objects.

This preserves:

• shared host reuse
• shared stream reuse
• separate checkpoints per stream
• agent-specific filters and cleanup on subscriptions

2. Modules Advertise Follow Templates

The core should not know that GitHub has a pr --withCi pattern or that X has recent_search versus filtered_stream.

Instead, each source module should advertise follow templates as capability metadata.

Suggested shape:

{
  "templateId": "github.pr",
  "label": "GitHub pull request",
  "description": "Follow one pull request and optionally its CI.",
  "arguments": [
    { "name": "owner", "type": "string", "required": true },
    { "name": "repo", "type": "string", "required": true },
    { "name": "number", "type": "number", "required": true },
    { "name": "withCi", "type": "boolean", "required": false }
  ]
}

This should be surfaced through resolved schema or adjacent capability discovery, not hardcoded in CLI help alone.

3. Modules Expand Intents Into Ensure Plans

The main extension point should be something conceptually like:

• listFollowTemplates()
• expandFollowTemplate(input)

The output should be an ensure plan that the core can execute generically.

Suggested plan shape:

{
  "host": {
    "hostType": "github",
    "hostKey": "uxcAuth:github-default"
  },
  "streams": [
    {
      "streamKind": "repo_events",
      "streamKey": "holon-run/agentinbox"
    },
    {
      "streamKind": "ci_runs",
      "streamKey": "holon-run/agentinbox"
    }
  ],
  "subscriptions": [
    {
      "streamRef": "repo_events",
      "filter": { "metadata": { "number": 167, "isPullRequest": true } },
      "trackedResourceRef": "repo:holon-run/agentinbox:pr:167",
      "cleanupPolicy": { "mode": "on_terminal" }
    },
    {
      "streamRef": "ci_runs",
      "filter": { "metadata": { "pullRequestNumbers": [167] } },
      "trackedResourceRef": "repo:holon-run/agentinbox:pr:167",
      "cleanupPolicy": { "mode": "on_terminal" }
    }
  ]
}

The core should only validate and execute this plan. It should not contain provider-specific branching for template semantics.

4. Ensure Must Be Idempotent

Repeated follow calls should prefer reuse over duplication.

That means:

• hosts should be keyed by provider and auth/runtime identity
• streams should be keyed by concrete feed identity
• subscriptions may still be agent-specific, but should dedupe when the same agent follows the same intent with the same filter and lifecycle policy

This is especially important after local resets or re-onboarding.

The system should continue to reuse existing shared streams when the underlying managed source already exists.

5. Follow Should Return The Expanded Result

The command result should show what was reused or created.

Suggested response:

{
  "templateId": "github.pr",
  "agentId": "agt_bronze-mole",
  "host": { "hostId": "hst_xxx", "created": false },
  "streams": [
    { "sourceId": "src_repo", "streamKind": "repo_events", "created": false },
    { "sourceId": "src_ci", "streamKind": "ci_runs", "created": false }
  ],
  "subscriptions": [
    { "subscriptionId": "sub_repo", "created": true },
    { "subscriptionId": "sub_ci", "created": true }
  ]
}

This keeps the system debuggable and makes follow safe for automation.

6. Keep Low-Level Commands

The existing low-level commands should remain first-class:

• host add
• source add
• subscription add
• source schema

They are still needed for:

• debugging
• custom filters
• advanced operator workflows
• providers that do not yet expose a template

follow should be the common path, not the only path.

Relationship To Existing RFCs

This RFC depends on the direction already established by:

• source hosts versus streams
• resolved source kinds and capability discovery
• shared source reuse

follow is the operator-facing convenience layer on top of those model decisions.

It does not replace them.

Why follow Instead Of watch

watch is the wrong verb for this setup layer because it implies:

• a foreground loop
• a long-lived connection
• immediate streaming output

That is appropriate for inbox watch, but not for durable subscription setup.

follow better communicates:

• establish ongoing interest
• keep tracking over time
• let the system decide how hosting and polling happen underneath

Under the current command set, the preferred naming is:

• follow
• track
• watch

in that order.

Migration Strategy

The rollout can be incremental:

1. keep existing low-level commands unchanged
2. add module capability discovery for follow templates
3. add agentinbox follow as a thin orchestration layer
4. progressively teach builtin and remote modules to expose templates

This allows the simplification to land without destabilizing the core storage and runtime model.

Open Questions

• whether follow templates should be discovered from the host, the stream kind, or a separate module capability namespace
• whether subscription dedupe should be strict equality or tracked-resource aware for common templates
• whether a follow preview mode should exist for planning and debugging

Recommendation

Proceed with follow as the high-level command name.

Implement it as generic core orchestration over module-provided template expansion, while keeping host, stream, and subscription as the real internal model and keeping watch reserved for foreground inbox observation.