# agent-kit Roadmap

`agent-kit` is the platform layer behind Sentinel AI. Each batch lands as
its own focused PR. Batches accumulate into a release; release version is
bumped on the PR that ships the batch.

## Active

| Batch | Scope | Status |
|------|-------|--------|
| F1 Batch 5 | Connections housekeeping — per-seat enforcement + mirror enforcement + connection-key rotation tooling | **queued** |
| F2.x | MCP serving — expose agent-kit capabilities AS an MCP server so other agents / tools can invoke them over the protocol | **future** |
| F2.x | MCP sampling — allow MCP servers to delegate LLM calls back to the connected Claude agent | **future** |
| F3 | "Connect your tools" UX primitives — consumer-facing portal patterns (account selector, scope explainer, reconnect-on-expiry flow) for the Life Admin product | **future** |

## Shipped

### F0 — Foundation

| Batch | Scope | Released |
|------|-------|----------|
| F0.1 | Scaffolding + AgentMemory schema (six discriminators) + typed write/read helpers | **v0.1.0** |
| F0.2 | Telegram dispatcher (webhook, bot client, router, formatting, PendingProposal) | **v0.2.0** |
| F0.3 | Tool dispatcher (typed `ToolDefinition`, `ToolRegistry` with scope enforcement, `runWithTools`) + `SECURITY.md` | **v0.3.0** |
| F0.4 | Photo orchestrator (`PhotoSource`, `PhotoStorage`, `extractWithVision`, `processPhoto`) | **v0.4.0** |
| F0.5 | Voice ingress (`VoiceSource`, `VoiceStorage`, `STTProvider`, `processVoice`) | **v0.5.0** |
| F0.6 | Approval flow primitives (`ProposalRecord` lifecycle, Telegram approval UI, Haiku-merged edits, audit log) | **v0.6.0** |
| F0.7 | Personality framework (`PersonalityDefinition`, `buildSystemPrompt`, channel overrides, calibration nudges) | **v0.7.0** |

### F0.10 — Proactive Surfacing Primitive

| Batch | Scope | Released |
|------|-------|----------|
| F0.10 B1 | Core interfaces (`TriggerSource`, `RelevanceScorer`, `SurfacingChannel`, `CalibrationLearner`) + `RuleBasedRelevanceScorer` + `TelegramSurfacingChannel` + `ProactiveSurfacingPipeline` + `MemoryCalibrationLearner` | **v0.10.0** |
| F0.10 B2 | (folded into v0.10.0) Pipeline orchestrator, `DummyTriggerSource`, in-memory calibration stub | **v0.10.0** |
| F0.10 B3 | `LLMAugmentedRelevanceScorer` (band-aware Sonnet sanity-check) + `Debouncer` + `SurfacingAggregator` + `PipelineCoachingTriggerSource` example | **v0.12.0** |
| F0.10 B3 deltas | Standalone `RateLimiter` (per-source overrides) + `PrismaDebounceStore` (cross-process quota state) + LLM scorer result cache (60s TTL) | **v0.17.0** |
| F0.10 B4 | `DashboardSurfacingChannel` + `SurfacingMessageQueue` + `InMemoryOperatorPreferencesStore` (per-operator threshold / channel / per-source calibration overrides) | **v0.14.0** |

### F1 — Connections Module

| Batch | Scope | Released |
|------|-------|----------|
| F1 B1 | Core interfaces (`Provider`, `ConnectionStore`, `ConnectionManager`), `MemoryConnectionStore`, `GoogleProvider`, `GoogleScopes`, error classes | **v0.11.0** |
| F1 B2 | `PrismaConnectionStore` + AES-256-GCM token encryption at rest (`ConnectionCrypto`, scrypt key derivation, per-write random IV) | **v0.13.0** |
| F1 B3 | `MicrosoftGraphProvider` + `MicrosoftGraphScopes` (multi-tenant by default) + `SlackProvider` + `SlackScopes` (bot-token primary, opt-in rotation supported) | **v0.15.0** |
| F1 B4 (partial) | `HubSpotProvider` + `HubSpotScopes` + `HUBSPOT_SCOPES` groupings (READ_ONLY, READ_WRITE, FULL_CRM) + `XeroProvider` + `XeroScopes` + `XERO_SCOPES` groupings (IDENTITY_ONLY, READ_ONLY_ACCOUNTING, FULL_ACCOUNTING, rotating refresh tokens) + `NotionProvider` (workspace-level, no refresh) | **v0.18.0** |
| F1 B4b — complete | `GitHubProvider` + `GitHubScopes` + `GITHUB_SCOPES` (READ_ONLY, READ_WRITE, FULL_DEV, long-lived tokens) + `LinearProvider` + `LinearScopes` + `LINEAR_SCOPES` (READ_ONLY, READ_WRITE, ADMIN, GraphQL userinfo) + `AtlassianProvider` + `AtlassianScopes` + `ATLASSIAN_SCOPES` (JIRA_READ_ONLY, JIRA_FULL, CONFLUENCE_FULL, FULL_ALL). **F1 Batch 4 complete — 9 providers total.** | **v0.20.0** |

### F2 — MCP Integration Layer

| Batch | Scope | Released |
|------|-------|----------|
| F2 Foundation | `MCPClient` (stdio + HTTP+SSE transports, connect/listTools/callTool/listResources/readResource/close) + `ToolRegistryBridge` (MCP tools → `ToolRegistry` bridge, merged `toAnthropicTools()`) + `dispatchMcpToolUse` helper + four named error classes | **v0.19.0** |

### F3 — Cross-Agent Learning Module

| Batch | Scope | Released |
|------|-------|----------|
| F3 Foundation | `ErrorAggregator` + `EmergenceDetector` + `RolloutOrchestrator` — cross-deployment error rollups + capability-emergence detection + staged-rollout primitives | **v0.23.0** |

### F4 — Relationship Cadence Module (Nyx foundation)

| Batch | Scope | Released |
|------|-------|----------|
| F4 Phase A | `RelationshipTracker` / `InMemoryRelationshipTracker` + `computeHeatScore` + `getCadencePolicy` / `DEFAULT_POLICIES` (5 verticals) + `PolicyInterventionRecommender` + `ClaudeInterventionDrafter` | **v0.23.0** |
| F4 Phase B | Detectors: `detectGoingCold` / `detectFrequencyShift` / `detectUnilateralSilence` / `detectEscalationNeeded` + `runAllCadenceDetectors` orchestrator + `PolicyNextTouchpointRecommender` + `ClaudeDraftSuggester` + `Nyx` sub-agent (scan / recommendNextAction / draftOutreach, F0.6 approval-gated) | **v0.30.0** |

### F5 — Compliance Freshness Module (Vera / Cora foundation)

| Batch | Scope | Released |
|------|-------|----------|
| F5 Phase A | `RegulatorWatcher` + `ComplianceRefresher` + `RegulatorPublicationFetcher` interface | **v0.22.0** |
| F5 Phase B | Six concrete regulator scanners (AUSTRAC / ASIC / ATO / AHPRA / NDIS Commission / OAIC) + `ScannerOrchestrator` + content-hash dedupe + `asFetcher()` adapter onto Phase A | **v0.29.0** |

### F6 — Cost Monitoring Module (Ledger / Tally foundation)

| Batch | Scope | Released |
|------|-------|----------|
| F6 Foundation | Per-customer + per-model + per-agent spend tracking + anomaly detection + model-recommendation primitives + pricing-adapter interface | **v0.24.0** |

### F7 — Pattern Analysis Engine (flagship)

| Batch | Scope | Released |
|------|-------|----------|
| F7 Phase A | `PatternDetector` + `InsightRanker` + `ProactiveSurface` + `CustomerImpactMapper` + `MarketIntelligenceScanner` + `CrossCustomerAnonymiser` | **v0.27.0** |
| F7 Phase B | Standalone detector modules: `detectTemporalClusters` / `detectCooccurrences` / `detectClusters` / `detectTrajectoryShifts` / `detectSentimentTrends` + `runAllDetectors` orchestrator + pluggable sentiment scorer | **v0.28.0** |

## Versioning

Semver. Breaking changes to the API surface bump the major. The Prisma
schema fragments shipped in `src/memory/schema.prisma`,
`src/connections/schema.prisma.example`, and
`src/proactive-surfacing/schema.prisma.example` are part of the API surface
— adding columns is a minor, removing or renaming columns is a major.

Versions 0.8, 0.9, and 0.16 were reserved during planning but never
released — the work folded forward into the next published version. The
package version skipped them rather than introducing empty changelog
entries.

## Design principles

- **Schema shared, data isolated.** Every consumer has its own database.
  Only the schema text is shared.
- **Helpers are thin.** They take a `PrismaClient` from the consumer and
  do the most common CRUD + retrieval patterns. Anything specialised
  stays in the consumer.
- **No runtime state inside the package.** No singletons, no
  module-scoped caches (where caches do exist — e.g. the LLM scorer
  result cache — they are scoped to the instance and disclosed in the
  module README).
- **Peer dependencies, not bundled dependencies.** `@prisma/client` is a
  peer dep so consumers control the version and the singleton.
- **Personal/Business credential separation is non-negotiable.**
  See [`SECURITY.md`](./SECURITY.md) for the rule and how the tool
  dispatcher enforces it at registration time.