Added endpoint for sending SMS (Depends of Catalyst change) #207

Huijiro · 2025-10-27T17:56:28Z

Summary by CodeRabbit

New Features
- Twilio-based SMS sending via a request/context-aware send API.
- SMS service exposed in the agent runtime for outbound messaging and replies.
Updates
- Enhanced observability: tracing spans and richer metadata for send and reply flows.
- Improved error reporting and timeout handling for SMS operations.
- Tightened type constraints for vector search parameters.

coderabbitai · 2025-10-27T17:56:52Z

Walkthrough

Adds Sms.send(req, ctx, to, message, from?) with Twilio auth validation, OpenTelemetry spans, and POSTs to /sms/send; augments Sms.sendReply to use its own tracing span and child context; adds an SmsApi implementing SMSService and exposes sms: SMSService on AgentContext; tightens VectorSearchParams<T> generic.

Changes

Cohort / File(s)	Summary
Core SMS implementation `src/io/sms.ts`	Added `async send(req: AgentRequest, ctx: AgentContext, to: string[], message: SmsReply, from?: string)` validating `twilio-auth-token`, starting spans (`agentuity.twilio.send`, `agentuity.twilio.reply`), POSTing JSON to `/sms/send` and `/sms/twilio/reply` with headers/timeouts, handling 200 vs non-200 responses, recording exceptions, and ensuring spans end; adjusted `sendReply` to create child span and include `X-Agentuity-Message-Id`.
API adapter `src/apis/sms.ts`	New `SmsApi` class implementing `SMSService` with `send(_req, ctx, to, message, from?)` (tracing, POST `/sms/send`, 15s timeout, error handling) and a deprecated `sendReply(...)` that throws "reply not supported in context".
Types & context `src/types.ts`	Added `SMSService.send(req, context, to, message, from)` signature; exposed `sms: SMSService` on `AgentContext`; tightened `VectorSearchParams<T>` to `T extends JsonObject = JsonObject`; minor formatting fixes.
Server context wiring `src/server/server.ts`	Imported and instantiated `SmsApi` and exposed it on the server context returned by `createServerContext`, adding `sms` to the runtime context.
Manifest `package.json`	Listed in manifest summary (no functional changes shown).

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Agent as Agent Handler
    participant IO as src/io/sms.ts
    participant API as src/apis/sms.ts
    participant Tracer as OpenTelemetry
    participant Backend as Agentuity SMS Backend

    Client->>Agent: request to send SMS
    Agent->>IO: call send(req, ctx, to, message, from)
    IO->>IO: validate twilio-auth-token (throw if missing)
    IO->>Tracer: start span "agentuity.twilio.send"
    IO->>API: delegate POST /sms/send (agentId, from, to, message.text)
    API->>Backend: HTTP POST /sms/send (JSON, Content-Type, timeout)

    alt 200 OK
        Backend-->>API: 200 OK
        API->>Tracer: set span OK
        API-->>IO: success
    else non-200
        Backend-->>API: error response
        API->>Tracer: recordException, set error status
        API-->>IO: throw with response details
    end

    API->>Tracer: end span
    IO->>Tracer: end span

    Note right of IO: sendReply creates child span "agentuity.twilio.reply", swaps to/from, sets X-Agentuity-Message-Id header, POSTs to /sms/twilio/reply

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Inspect OpenTelemetry span lifecycle and attribute usage in src/io/sms.ts and src/apis/sms.ts.
Verify secure extraction and error messages around twilio-auth-token.
Review HTTP payloads, headers (including X-Agentuity-Message-Id), and timeout handling.
Confirm AgentContext.sms wiring in src/server/server.ts and type changes in src/types.ts do not break consumers.

Poem

🐰
I hopped through spans with nimble paws,
Sent little texts with careful laws,
A token kept, a header bright,
Replies returned on moonlit night,
The rabbit grins — the messages hop.

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'Added endpoint for sending SMS (Depends of Catalyst change)' directly aligns with the changeset, which adds a new SMS sending endpoint across multiple files including src/io/sms.ts, src/types.ts, src/apis/sms.ts, and src/server/server.ts. The title is concise, specific, and clearly communicates the primary change from the developer's perspective. The addition of the dependency note in parentheses is reasonable context.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch sms-send

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e9729c8 and 838846d.

📒 Files selected for processing (1)

src/apis/sms.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

src/apis/sms.ts

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

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

coderabbitai

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

src/io/sms.ts (1)
167-176: Docs: “email” wording in SMS code

Update comments to reflect SMS, not email.
-/**
- * Parse an email from a buffer and return an Email object.
- */
+/**
+ * Parse an SMS from a buffer and return an Sms object.
+ */
Also update the SmsReply comment at Lines 15–23 similarly.
src/types.ts (1)
575-586: Remove embedded diff markers from interface definition — file will not compile

The file contains literal diff markers embedded as text within the VectorSearchParams interface (lines 576–577), which creates invalid TypeScript syntax. This truncates the first interface and prevents compilation.

Fix: Remove lines 576–577 entirely (the diff markers with - and + prefixes), and apply the generic constraint directly to the original interface declaration at line 543:
-export interface VectorSearchParams<T = unknown> {
+export interface VectorSearchParams<T extends JsonObject = JsonObject> {
The interface should then continue with all its properties (query, limit, similarity, metadata) without the embedded diff syntax.

🧹 Nitpick comments (1)

src/io/sms.ts (1)
111-161: Add explicit return type and timeout to sendReply() for consistency with send()

The interface already defines sendReply(): Promise<void>, so adding the explicit return type annotation is good practice. Both send() and sendReply() currently pass undefined as the timeout parameter to POST(). Adding a 15-second timeout to sendReply() improves reliability; consider applying the same timeout to send() for true parity.

Note: The suggestion to return a provider message ID conflicts with the interface definition (Promise<void>); verify if the interface should be updated instead.
-	async sendReply(req: AgentRequest, ctx: AgentContext, reply: string) {
+	async sendReply(
+		req: AgentRequest,
+		ctx: AgentContext,
+		reply: string
+	): Promise<void> {
+		const timeoutMs = 15_000;
@@
-				const resp = await POST(
+				const resp = await POST(
 					'/sms/twilio/reply',
 					safeStringify({
 						to: this.from,
 						from: this.to,
 						reply: reply,
 						agentId: ctx.agent.id,
 					}),
 					{
 						'Content-Type': 'application/json',
 						'X-Agentuity-Message-Id': this.messageId,
 					},
-					undefined,
+					timeoutMs,
 					authToken
 				);

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 95347fe and 67b1c4d.

📒 Files selected for processing (2)

src/io/sms.ts (2 hunks)
src/types.ts (4 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

{src,test}/**/!(*.d).ts

📄 CodeRabbit inference engine (AGENT.md)

{src,test}/**/!(*.d).ts: Use strict TypeScript and prefer unknown over any
Use ESM import/export syntax; avoid CommonJS require/module.exports
Use relative imports for internal modules
Keep imports organized (sorted, no unused imports)
Use tabs with a visual width of 2 spaces
Limit lines to a maximum of 80 characters
Use single quotes for strings
Use proper Error types; do not throw strings
Prefer template literals over string concatenation

Files:

src/types.ts
src/io/sms.ts

src/io/**

📄 CodeRabbit inference engine (AGENT.md)

I/O handlers (Discord, Slack, Email, SMS, Telegram) live under src/io/

Files:

src/io/sms.ts

🧬 Code graph analysis (2)

src/types.ts (2)

src/io/sms.ts (2)

to (46-48)

from (49-51)

src/io/email.ts (1)

to (291-302)

src/io/sms.ts (4)

src/types.ts (2)

AgentRequest (1085-1105)

AgentContext (957-1080)

src/router/router.ts (2)

getTracer (61-66)

recordException (108-128)

src/apis/api.ts (1)

POST (253-270)

src/server/util.ts (1)

safeStringify (17-28)

🔇 Additional comments (1)

src/types.ts (1)

1071-1075: AgentContext.sms exposure

Looks good and aligns with the new service.

src/io/sms.ts

src/types.ts

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a8251f9 and e9729c8.

📒 Files selected for processing (2)

src/apis/sms.ts (1 hunks)
src/server/server.ts (3 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

src/apis/**

📄 CodeRabbit inference engine (AGENT.md)

Place core API implementations under src/apis/ (email, discord, keyvalue, vector, objectstore)

Files:

src/apis/sms.ts

{src,test}/**/!(*.d).ts

📄 CodeRabbit inference engine (AGENT.md)

{src,test}/**/!(*.d).ts: Use strict TypeScript and prefer unknown over any
Use ESM import/export syntax; avoid CommonJS require/module.exports
Use relative imports for internal modules
Keep imports organized (sorted, no unused imports)
Use tabs with a visual width of 2 spaces
Limit lines to a maximum of 80 characters
Use single quotes for strings
Use proper Error types; do not throw strings
Prefer template literals over string concatenation

Files:

src/apis/sms.ts
src/server/server.ts

src/apis/**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/code-generation.mdc)

src/apis/**/*.ts: Do not hardcode generated prompt content (e.g., copyWriter) in source files; load it dynamically
Avoid overly complex TypeScript generics for generated content; prefer simple, maintainable types
Maintain type safety for dynamically loaded content by generating and referencing TypeScript definitions, with proper annotations for require() results
Do not use relative imports to generated artifacts; resolve via absolute node_modules paths or the package entry
Generated content is loaded at runtime, not build time; avoid static imports of generated modules
Prefer bracket notation for accessing slug-named properties with hyphens (e.g., prompts['slug-name'])
Avoid relative require('./generated/_index.js'); resolve absolute paths from process.cwd() into node_modules for generated assets

Files:

src/apis/sms.ts

src/server/{server,bun,node,agents}.ts

📄 CodeRabbit inference engine (AGENT.md)

Server components live in src/server/ as server.ts, bun.ts, node.ts, and agents.ts

Files:

src/server/server.ts

src/server/*.ts

📄 CodeRabbit inference engine (.cursor/rules/code-generation.mdc)

src/server/*.ts: Load generated content during server context creation and provide fallbacks when signatures or content are missing
In compile helpers, prefer using generated signature functions when present and provide a manual compilation fallback when absent

Files:

src/server/server.ts

🧬 Code graph analysis (2)

src/apis/sms.ts (4)

src/types.ts (3)

SMSService (723-744)

AgentRequest (1087-1107)

AgentContext (959-1082)

src/io/sms.ts (2)

SmsReply (18-23)

from (49-51)

src/router/router.ts (2)

getTracer (61-66)

recordException (108-128)

src/apis/api.ts (1)

POST (253-270)

src/server/server.ts (1)

src/router/data.ts (1)

sms (255-261)

🔇 Additional comments (1)

src/server/server.ts (1)

186-228: Sms service wiring looks good.

The singleton registration mirrors the other API clients and cleanly exposes ctx.sms to agents.

src/apis/sms.ts

Added endpoint for sending SMS (Depends of Catalyst change)

67b1c4d

AMP being dumb

2182956

coderabbitai bot reviewed Oct 27, 2025

View reviewed changes

src/io/sms.ts Show resolved Hide resolved

src/types.ts Outdated Show resolved Hide resolved

src/types.ts Outdated Show resolved Hide resolved

src/types.ts Show resolved Hide resolved

Huijiro added 2 commits October 27, 2025 21:20

Implemented feedback

a8251f9

Re-structured code

e9729c8

coderabbitai bot reviewed Oct 31, 2025

View reviewed changes

src/apis/sms.ts Outdated Show resolved Hide resolved

Implemented feedback

838846d

Huijiro merged commit a05651f into main Nov 4, 2025
3 checks passed

Huijiro deleted the sms-send branch November 4, 2025 16:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Added endpoint for sending SMS (Depends of Catalyst change) #207

Added endpoint for sending SMS (Depends of Catalyst change) #207

Uh oh!

Huijiro commented Oct 27, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Oct 27, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Added endpoint for sending SMS (Depends of Catalyst change) #207

Added endpoint for sending SMS (Depends of Catalyst change) #207

Uh oh!

Conversation

Huijiro commented Oct 27, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Huijiro commented Oct 27, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Oct 27, 2025 •

edited

Loading