From 60a210db26bb7b9e6cfd975368f277f973231250 Mon Sep 17 00:00:00 2001 From: Gale W Date: Tue, 14 Jul 2026 14:58:41 -0400 Subject: [PATCH] docs: record messaging phase 3 readiness Why: Preserve the evidence-backed reference consumers and integration boundaries before shared Phase 3 helper work begins. Verification: uv run scripts/validate_socket_metadata.py --- ROADMAP.md | 1 + ...ng-collaboration-phase-3-readiness-plan.md | 125 ++++++++++++++++++ ...saging-collaboration-skills-plugin-plan.md | 3 + 3 files changed, 129 insertions(+) create mode 100644 docs/maintainers/messaging-collaboration-phase-3-readiness-plan.md diff --git a/ROADMAP.md b/ROADMAP.md index 268be8c5..a97d2039 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -851,6 +851,7 @@ Completed - [x] Validate every authored skill and the root marketplace metadata before release. - [x] Add Phase 2.5 workflows for iMessage collaboration, communication notifications and NSE processing, Push to Talk, VoIP/SIP calling, and default communication-app roles with an app-owned macOS client boundary. - [x] Export the complete Messaging Collaboration skill inventory through the Hermes skill tap and validate its generated grouping. +- [x] Record Phase 3 readiness evidence for iMessage collaboration, Push-to-Talk with a Hummingbird/APNs Lambda backend, iOS/iPadOS default messaging, and Discord user-app/webhook/bot reference consumers before adding shared runtime helpers. ### Exit Criteria diff --git a/docs/maintainers/messaging-collaboration-phase-3-readiness-plan.md b/docs/maintainers/messaging-collaboration-phase-3-readiness-plan.md new file mode 100644 index 00000000..a4201983 --- /dev/null +++ b/docs/maintainers/messaging-collaboration-phase-3-readiness-plan.md @@ -0,0 +1,125 @@ +# Messaging Collaboration Phase 3 Readiness Plan + +## Decision + +Phase 3 remains a readiness and evidence pass until the reference consumers +below demonstrate a repeated implementation need. Do not create a +provider-neutral messaging SDK, universal webhook runtime, shared credential +store, or Messages automation bridge first. + +A helper may graduate into Phase 3 only when at least two real consumers need +the same narrowly defined behavior and can share the same privacy, credential, +failure, and validation contract. + +## Reference Consumers + +### iMessage Collaboration App + +Build an iOS/iPadOS app with an iMessage extension for a user-driven, +participant-visible collaborative activity. `MSMessage` carries versioned, +app-defined state; `MSSession` coordinates updates; the containing app or a +server owns durable state, account authorization, merge rules, and recovery. +Use Shared with You only when the app owns the shared item and collaboration +metadata. + +This is not a server-side iMessage bot and does not grant access to a person's +Messages history or unattended sending. Validate with two accounts/devices, +stale state, missing app account, backend outage, and participant rejoin. + +### Push-To-Talk App With Hummingbird Lambda + +Build a channel-based Apple PushToTalk client with app-owned identity, +membership, media transport, encryption, retention, and moderation. The client +uses `PTChannelManager` for system controls and channel lifecycle, waits for the +framework to activate audio before recording, and treats Core Bluetooth accessory +events as user-initiated transmission triggers only. + +Bootstrap the backend as a fresh Hummingbird Lambda application through the +official `hb` CLI. Its narrow jobs are channel authorization, participant state, +short-lived APNs PTT-token registration, PTT notification dispatch, and a +health/audit surface. It is not the media relay unless a later transport decision +explicitly requires that. Keep APNs credentials and channel tokens server-side; +send PTT pushes using the documented `pushtotalk` type and `.voip-ptt` topic. + +Validate physical-device channel join/leave, token rotation, PTT push delivery, +Bluetooth/wired-headset trigger behavior, audio interruption and route changes, +half-duplex handoff, and backend unavailable/recovery states. + +### Default Messaging App Exploration + +Build an iOS/iPadOS app-owned instant-messaging service that can opt into the +documented default messaging role. It must use its own identity, conversation, +delivery, and retention model. The `im:` URL route supplies a recipient address; +it is not an API to send or read iMessage content. + +Treat carrier SMS/MMS/RCS as a separate discovery lane. TelephonyMessagingKit +and the Default Carrier Messaging App role have distinct eligibility, privacy, +and EU availability constraints. Do not imply that the default instant-messaging +role can send iMessage, read Apple Messages, or automatically gain RCS access. + +Validate `im:` routing, unavailable-recipient fallback, entitlement and +provisioning behavior, Siri/Apple Intelligence message-domain integration, and +regional carrier-messaging gates independently. + +### Discord Personal Projects + +Use Fizze Assistant as the first real bot reference: a private Swift Gateway bot +that combines realtime events with Discord HTTP commands and keeps its local +state deliberately small. Build the next projects as distinct consumers: + +- a user-installed app with installation and private-channel command boundaries; +- an HTTP interaction/webhook integration that validates signatures and responds + within Discord's deadline; and +- a Gateway bot when realtime guild events or long-lived state are required. + +Do not derive a shared Discord runtime until these projects identify a common +contract beyond routine REST/Gateway plumbing. + +## Supported Hook Inventory + +| Hook | Supported use | Boundary | +| --- | --- | --- | +| Messages extension | User-driven interactive iMessage payload and session | No inbox/history or unattended iMessage bot access. | +| Shared with You | App-owned shared item and collaboration metadata | Not a Messages transcript API. | +| Default messaging | App-owned instant messaging through `im:` routing | Does not control iMessage or carrier messaging. | +| Carrier messaging | SMS/MMS/RCS through TelephonyMessagingKit when eligible | Separate entitlement and EU availability gate. | +| Communication notifications/NSE | This app's alert enrichment, intent donation, and Focus-aware presentation | NSE cannot inspect or filter other apps' notifications. | +| App extension targets | Containing-app extension lifecycle, app groups, entitlements, activation, and process isolation | Each extension point has its own host contract. | +| PushToTalk and accessories | System PTT controls; Core Bluetooth, headset, or CarPlay transmission triggers | App owns transport/media; wait for system audio activation. | +| Group Activities | Synchronize an app-defined SharePlay activity over FaceTime/Messages | No public remote-screen-control or FaceTime-control API. | +| App Intents | Expose app-owned actions/data to Siri, Shortcuts, Spotlight, Apple Intelligence | Never exposes another app's private messages. | +| User-owned Mac/VPS | Run the user's own client, agent bridge, webhook receiver, or backend | Access only data and APIs the user/app explicitly owns and authorizes. | + +## Agent Integration Contract + +Agents may act through a user-owned app's App Intents, explicit in-app actions, +Shortcuts, authenticated server APIs, Discord interactions/webhooks, or a +user-owned Mac/VPS bridge for that app's own data. Every mutation needs an +identity, authorization scope, audit event, user-visible result, and failure +path. Do not present private Apple Messages/FaceTime/Phone state as an agent +integration surface without a documented API and explicit authorization. + +## Phase 3 Helper Gate + +Candidate helpers must satisfy every condition before implementation: + +1. Two reference consumers need the same behavior without platform-specific policy differences. +2. The helper has one owner and no credentials or user-message content by default. +3. Its failure behavior, idempotency/retry contract, and audit data can be specified and tested independently. +4. A fixture can prove it against the real platform contract. + +Initial candidates to evaluate, not implement yet: signed Discord interaction or +webhook verification fixtures, platform-local event replay fixtures, and PTT +channel/auth state test fixtures. + +## Sources + +- [Messages](https://developer.apple.com/documentation/messages) +- [Default messaging app](https://developer.apple.com/documentation/messages/preparing-your-app-to-be-the-default-messaging-app) +- [Carrier messaging app](https://developer.apple.com/documentation/availability/creating-a-carrier-messaging-app) +- [Creating a Push to Talk app](https://developer.apple.com/documentation/pushtotalk/creating-a-push-to-talk-app) +- [Group Activities](https://developer.apple.com/documentation/groupactivities/groupactivity) +- [Messages App Intents domain](https://developer.apple.com/documentation/appintents/app-schema-domain-messages) +- [Discord interactions and commands](https://docs.discord.com/developers/platform/interactions) +- [Discord Gateway](https://docs.discord.com/developers/events/gateway) +- [Hummingbird server workflow](../../plugins/server-side-swift/skills/hummingbird-server-workflow/SKILL.md) diff --git a/docs/maintainers/messaging-collaboration-skills-plugin-plan.md b/docs/maintainers/messaging-collaboration-skills-plugin-plan.md index 85340ca1..d5c9fb68 100644 --- a/docs/maintainers/messaging-collaboration-skills-plugin-plan.md +++ b/docs/maintainers/messaging-collaboration-skills-plugin-plan.md @@ -93,6 +93,9 @@ Phase 2.5 exit criteria: each Apple communication lane names its documented syst Only after repeated implementation evidence, assess narrow helpers for webhook verification fixtures, event replay tests, or platform-local samples. Do not create a shared service unless its ownership, credentials, state, and failure behavior are proven common across at least two live consumers. +The current proof targets and agent-integration boundaries are maintained in the +[Phase 3 readiness plan](./messaging-collaboration-phase-3-readiness-plan.md). + ### Phase 4: MCP Evaluation And Operator Workflows Evaluate external messaging MCP products by source, supported API, data access, authorization model, auditability, and runtime proof. A bundled MCP server remains out of scope until a concrete, maintainable operator need is approved.