Photon/iMessage¶
Photon/iMessage uses Photon Spectrum through the bundled Node.js sidecar and the shared gateway bridge.
Photon Setup¶
Create or select a Photon Spectrum project, then put the project credentials in
team.env:
PHOTON_PROJECT_ID=...
PHOTON_PROJECT_SECRET=...
The Python adapter launches the bundled sidecar by default. The runtime image must include Node.js and the sidecar npm dependencies.
Minimal instance_config.yaml:
interactive_apps:
plugins:
builtin.photon:
settings:
enabled: true
When project_id is empty, the adapter reads PHOTON_PROJECT_ID from the
environment. The project secret is always read through
project_secret_env_var, which defaults to PHOTON_PROJECT_SECRET.
Common explicit form:
interactive_apps:
plugins:
builtin.photon:
settings:
enabled: true
project_id_env_var: "PHOTON_PROJECT_ID"
project_secret_env_var: "PHOTON_PROJECT_SECRET"
sidecar_autostart: true
node_bin: "node"
allowed_sender_ids: []
allowed_group_ids: []
PHOTON_SIDECAR_TOKEN is optional. It is not a Photon/Spectrum credential; it
is only the shared loopback token used between the Python adapter and the local
Node sidecar. If it is unset, the adapter generates a fresh token for the
sidecar process it starts.
Onboarding Flags¶
.venv/bin/python assistant_cli.py onboard \
--enable-photon \
--photon-project-id "$PHOTON_PROJECT_ID" \
--photon-allow-sender-id imessage:+15551234567
For groups:
--photon-allow-group-id imessage:group-space-id \
--photon-group-policy mention \
--photon-mention-marker @Lisa
Inbound Identity¶
Direct Photon sessions bind to Photon sender.id when available. If Photon
does not emit a sender id, the adapter uses the emitted iMessage phone or space
id, such as imessage:+15551234567. Rejected sender logs include
newuser_target=... for admin onboarding.
To find the direct sender id, temporarily leave direct allowlisting open:
interactive_apps:
plugins:
builtin.photon:
settings:
enabled: true
allowed_sender_ids: []
allowed_group_ids: []
Start the adapter and send an iMessage from the account you want to allow. Look for a gateway log line like:
Photon inbound to manager: user_id=... chat_id=... group=False message_id=... session=...
Use the exact logged user_id or chat_id in allowed_sender_ids. For
proactive delivery, prefer the exact logged chat_id.
Group Chats¶
Photon group chats are selected by the group/space id and a text marker, not by a native iMessage mention. First allow the group id:
interactive_apps:
plugins:
builtin.photon:
settings:
enabled: true
allowed_group_ids:
- "THE_LOGGED_GROUP_CHAT_ID"
group_policy: "mention"
mention_markers:
- "Nova"
- "@Nova"
- "nova:"
Then address the assistant in the group with one of the configured markers:
Nova what is on my schedule today?
@Nova summarize this thread
When group_policy is mention, the adapter ignores group messages that do
not contain one of the configured mention_markers. When a marker is present,
the marker is stripped and the rest of the message is forwarded to the manager.
To find the group id, temporarily enable the group or inspect logs from a group
message. Use the logged chat_id from:
Photon inbound to manager: user_id=... chat_id=... group=True message_id=... session=...
Photon must deliver the group event before Universal Agents can discover or
allowlist it. On Photon shared-pool plans, the group must include the exact
Photon line assigned to the user; shared mode cannot create a new group chat
for you. Existing iMessage groups appear as chat ids such as
any;+;<group-guid> only after Spectrum sees traffic for that group. If direct
messages work but no sidecar metadata log appears for the group, changing
allowed_group_ids or mention markers will not help because the message has
not reached the adapter yet. Confirm the group includes the assigned Photon
line shown in the Photon dashboard or move to a dedicated line if you need
reliable group routing and group creation.
Proactive Delivery¶
If Photon/iMessage should receive proactive agent messages:
--default-delivery-channel photon \
--default-delivery-chat-id imessage:+15551234567
For group spaces, use the configured Photon group/space id as the chat id.
Equivalent instance_config.yaml:
delivery:
default_target:
channel_name: "photon"
chat_id: "THE_LOGGED_CHAT_ID"
thread_id: ""
Verification¶
- Confirm Node.js 24.5 or newer is available in the runtime.
- Confirm
PHOTON_PROJECT_IDandPHOTON_PROJECT_SECRETare loaded. - Start the gateway with Photon enabled.
- Confirm logs show the Photon sidecar is healthy.
- Send an iMessage through the Photon-backed channel.
- Confirm the gateway logs the inbound sender id.
- Confirm the agent replies through Photon/iMessage.
- If using a group, send a message with a configured marker such as
Nova.
Photon requires Node 24.5's default-certificate API to remove the compromised
emSign ECC Root CA - G3 root before loading the Spectrum SDK. Node 24.0 through
24.4 are no longer supported. All other effective default roots, including
private CAs from NODE_EXTRA_CA_CERTS, remain available. If
GRPC_DEFAULT_SSL_ROOTS_FILE_PATH names a custom bundle, remove the compromised
root from that bundle; an unreadable, invalid or distrusted bundle stops startup.
Use an official Node build in its default bundled-CA mode or with
--use-system-ca. Photon refuses --use-openssl-ca and custom builds with
additional OpenSSL default stores because Node cannot enumerate those roots
safely. Supply private roots through NODE_EXTRA_CA_CERTS instead. This avoids
silently discarding a private root or adding unrelated trusted roots.
Interrupting Active Work¶
Photon continues reading new iMessages while an earlier request is waiting for
the manager. Send /stop in the same conversation to cancel the active task;
the stop message is handled through the gateway control path rather than queued
behind the reply. Ordinary follow-up text can likewise reach the manager's
mid-turn steering path. This does not run multiple model turns concurrently.
Each inbound message is tracked independently. A processing or reply-delivery error is logged for that message and does not disconnect the inbound sidecar stream.
Spectrum read receipts and reactions are status events. Photon logs their metadata but does not create manager tasks from them.
Troubleshooting¶
- Startup fails: verify Photon credentials and Node.js 24.5-or-newer availability.
- Sidecar health fails: run
npm ciin the sidecar directory or rebuild the Docker image with Node.js support. - Direct messages are ignored: check
allowed_sender_idsor onboard the user with/user. - A Markdown reply with a link fails: confirm the sidecar lockfile contains the scoped Spectrum v12 packages. Spectrum v8+ leaves Apple data detection and link previews to iMessage instead of sending IMAgentKit's unsupported option; send errors are not broadly retried.
- Groups are ignored: configure
allowed_group_idsand mention markers. - The assistant replies in direct messages but not a group: if a sidecar
metadata log appears for the group, use the exact logged group
chat_id, setgroup_policy: "mention", and include a configured marker such asNovaor@Novain the group message. If no sidecar metadata log appears, the Photon/Spectrum stream has not delivered that group event; confirm the group includes the assigned Photon line, and remember that shared-pool mode cannot create group chats. - To distinguish adapter filtering from Photon/Spectrum delivery, look for
Photon sidecar: photon-sidecar: inbound metadata .... This sidecar log is emitted before the Python adapter applies allowlists and contains only metadata such as message id, direction, space id, space type, sender id, and content type. If direct messages produce this log but group messages do not, Spectrum is not delivering that group event to the sidecar.