feat: add system identity and message support

[noodleonthecape]

Summary

• add backend/type support for system identities/messages alongside existing human and agent concepts
• propagate explicit agent/system type metadata through message transforms and delivery paths
• add tests and API/docs updates needed for Relay SDK SystemHandle integration

Notes

This PR is intended to support Relay-side semantics so system-origin messages are not modeled as human messages.

[github-actions]

Preview deployed!

Environment	URL
API	https://pr116-api.relaycast.dev
Health	https://pr116-api.relaycast.dev/health
Observer	https://pr116-observer.relaycast.dev/observer

This preview shares the staging database and will be cleaned up when the PR is merged or closed.

Run E2E tests

npm run e2e -- https://pr116-api.relaycast.dev --ci

Open observer dashboard

https://pr116-observer.relaycast.dev/observer

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5533936f-8cb8-4a99-8b99-70f194c33d8e

📥 Commits

Reviewing files that changed from the base of the PR and between 5560181 and 8220b52.

📒 Files selected for processing (14)

• README.md
• openapi.yaml
• packages/server/src/durable-objects/agent.ts
• packages/server/src/engine/__tests__/wsTransform.test.ts
• packages/server/src/engine/dm.ts
• packages/server/src/engine/groupDm.ts
• packages/server/src/engine/message.ts
• packages/server/src/engine/thread.ts
• packages/server/src/engine/wsTransform.ts
• packages/server/src/routes/__tests__/agent.test.ts
• packages/server/src/routes/__tests__/fanout.test.ts
• packages/types/src/__tests__/types.test.ts
• packages/types/src/dm.ts
• packages/types/src/message.ts

---

📝 Walkthrough

Walkthrough

This PR adds an agent_type field to message payloads system-wide, allowing clients to distinguish between agent, human, and system senders without additional identity lookups. Type schemas, all message APIs, WebSocket transformations, database replay paths, and public contracts are updated consistently.

Changes

Agent Type Field Propagation

Layer / File(s)	Summary
Type schema definitions packages/types/src/message.ts, packages/types/src/dm.ts, packages/types/src/__tests__/types.test.ts	Zod schemas CoreMessagePayloadSchema, MessageWithMetaSchema, and DmLastMessageSchema gain optional agent_type field validated by AgentTypeSchema. Type assertion test verifies DmMessage includes the field.
Message engine queries and returns packages/server/src/engine/message.ts	postMessage, getMessages, and getMessage fetch agents.type and return agent_type in message payloads alongside existing agent identity fields.
DM engine queries and returns packages/server/src/engine/dm.ts	sendDm, listConversations, and getDmMessages extend database selections to fetch sender agents.type. A SenderType alias (AgentType | undefined) is introduced for response mapping. All three functions populate agent_type in their returned message payloads.
Thread reply and group DM engines packages/server/src/engine/thread.ts, packages/server/src/engine/groupDm.ts	postReply and getThread fetch and map agent_type for parent messages and replies. postGroupMessage includes sender agent's type in the canonical message object.
WebSocket client transformation packages/server/src/engine/wsTransform.ts	transformForClient maps internal agent_type (or msg.agent_type with fallback) into client event payloads for message.created, message.updated, thread.reply, dm.received, and group_dm.received.
Database resync/replay packages/server/src/durable-objects/agent.ts	replayFromDb extends SQL joins to select agents.type (aliased as agent_type) for both channel messages and DM/group-DM messages. Buffered replay payloads include the agent_type field.
Public API contracts openapi.yaml, README.md	OpenAPI schemas for Message, CoreDmMessagePayload, and FlatDmMessage add agent_type string enum (agent, human, system). README documents the new field in core concepts.
Test fixtures and assertions packages/server/src/engine/__tests__/wsTransform.test.ts, packages/server/src/routes/__tests__/agent.test.ts, packages/server/src/routes/__tests__/fanout.test.ts	WebSocket transformation tests include agent_type in event data and expected message objects across all message event types. Agent route test verifies system agent registration. Fanout tests include agent_type in input and asserted payloads.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A type hops through the message flow,
Marking agents high and humans low,
Systems stamp each word they send,
No lookup need—the type's your friend!
Agent, human, system clear,
Discrimination everywhere!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add system identity and message support' directly and clearly describes the main change: adding system identity and message support to the codebase.
Description check	✅ Passed	The description is related to the changeset, explaining the addition of system identity/message support, propagation of type metadata, and Relay SDK integration requirements.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/system-handle

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.