README

Optional sibling package for conversation surfaces (Telegram first).

Implements core ConversationIngress / ApprovalNotifier contracts. Never embeds domain run() — chat feeds the agent; tools are the capability registry (D-007).

Status: 0.x pre-stable — not Packagist-published. Install via package VCS or monorepo path.

Scope (this package)


Is	Chat ingress (Telegram first): webhooks, identity link/allowlist, threads, approval notifiers; routes messages into the agent with a configured tool profile
Is not	Domain `run()` or any second write path; the capability registry / governance stack; product CLI; AI turn/proposal engine; durable multi-instance identity product (process-local stores residual — L-006); general-purpose notification platform

Requires rawphp/laravel-capabilities. Developed in the monorepo; consumers install this package repo.

Upgrade note (0.x) — CallbackHandler approvals

Telegram\CallbackHandler third constructor argument is ?ApprovalGateway (was ?ApprovalManager). Runtime still accepts ApprovalManager because it implements the gateway; update static analysis / manual type-hints. Pre-accept/reject lookup uses gateway find() (lazy pending TTL expiry, aligned with HTTP accept) — not store()->find(). Missing gateway throws ApprovalGateway is required…. Full consumer impact: CHANGELOG.md Unreleased Breaking.

Doc	Where
User guide	docs/user-guide.md
Changelog	CHANGELOG.md
Core package	rawphp/laravel-capabilities
Sibling AI	rawphp/laravel-capabilities-ai
Monorepo design	laravel-capabilities-monorepo

Install

Requires rawphp/laravel-capabilities.

VCS (package remotes)

This tree is published to github.com/rawphp/laravel-capabilities-messaging from the monorepo on every push to main.

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/rawphp/laravel-capabilities"
    },
    {
      "type": "vcs",
      "url": "https://github.com/rawphp/laravel-capabilities-messaging"
    }
  ],
  "require": {
    "rawphp/laravel-capabilities": "dev-main",
    "rawphp/laravel-capabilities-messaging": "dev-main"
  }
}

Path (monorepo contributors)

Point path repos at packages/laravel-capabilities and packages/laravel-capabilities-messaging in a monorepo clone, require *@dev.

composer update rawphp/laravel-capabilities-messaging
php artisan vendor:publish --tag=capabilities-messaging-config

Install policy: monorepo docs/versioning.md. How-to: docs/user-guide.md.

Production bindings (L-004)

MessagingServiceProvider::register always binds drivers and services (not gated on telegram.enabled). Only webhook routes load when telegram.enabled is true.

Abstract	Production concrete	Testing / `driver=fake`
`MessagingConfig`	config repository	same
`UpdateQueue`	`LaravelUpdateQueue` → bus `ProcessTelegramUpdateJob`	`FakeQueue`
`TelegramBotClient`	`HttpTelegramBotClient`	`FakeTelegramBotClient`
`ProcessTelegramUpdate`	handler	same
`TelegramWebhookController`	injects bound `UpdateQueue` (no FakeQueue default)	inject `FakeQueue` in unit tests
`TelegramApprovalNotifier`	`Rawphp\CapabilitiesMessaging\Notifiers\TelegramApprovalNotifier` (Bot API)	unit tests may inject fakes

Drivers (config/capabilities-messaging.php):

queue_driver: auto | laravel | fake — auto → fake when APP_ENV=testing, otherwise Laravel bus
bot_driver: auto | http | fake — auto → fake when testing, otherwise HTTP

Fake* classes bind only when the matching driver is fake, or auto with APP_ENV=testing. Unit tests never call the live Telegram network; inject a transport on HttpTelegramBotClient or use bot_driver=fake.

Notifier FQCN: production is messaging …Notifiers\TelegramApprovalNotifier. Core’s RecordingTelegramApprovalNotifier is the test recording double; core’s deprecated empty …Approval\Notifiers\TelegramApprovalNotifier is a soft-landing alias only — do not use it in hosts.

Residual: durable identity / threads (L-006)

Not silent: IdentityLinker and ThreadStore remain process-local in-memory stores. They are not durable across processes or deploys. Durable DB-backed identity linking and thread history are deferred (L-006) — plan for host-level persistence or a future package revision before multi-instance production traffic depends on them.

rawphp / laravel-capabilities-messaging

Maintainers

Package info

Statistics

Security