@pylonsync/create-pylon 0.19.1 → 0.20.0

package/templates/imessage/functions/beginTurn.ts

@@ -0,0 +1,101 @@
+import { mutation, v } from "@pylonsync/functions";
+import { buildTurnInput, MAX_RUN_MESSAGES } from "../lib/assistant";
+import { loadSettings, toContact, toConversation, TURN_STALE_MS } from "../lib/store";
+
+const MAX_TEXTS_PER_TURN = 20;
+const CONTEXT_LINES = 12;
+
+// Claim the next agent turn for a conversation, in one transaction:
+//   - a turn already running → flag the conversation so that turn runs again
+//     when it finishes, and return "busy"
+//   - nothing waiting → "idle"
+//   - otherwise mark the waiting texts "processing" under a new turn id and
+//     return the agent input built from them.
+// Internal: called by processTurn only.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: { conversationId: v.string() },
+  async handler(ctx, args) {
+    const row = await ctx.db.get("Conversation", args.conversationId);
+    if (!row) return { state: "idle" as const };
+    const conversation = toConversation(row);
+    const now = new Date();
+
+    if (conversation.turnState === "running") {
+      const started = Date.parse(conversation.turnStartedAt ?? "") || 0;
+      if (now.getTime() - started < TURN_STALE_MS) {
+        await ctx.db.update("Conversation", conversation.id, { needsAnotherTurn: true });
+        return { state: "busy" as const };
+      }
+    }
+
+    const pending = await ctx.db.query("Message", {
+      conversationId: conversation.id,
+      status: "received",
+      $order: { createdAt: "asc" },
+      $limit: MAX_TEXTS_PER_TURN,
+    });
+    if (pending.length === 0) {
+      await ctx.db.update("Conversation", conversation.id, { turnState: "idle", needsAnotherTurn: false });
+      return { state: "idle" as const };
+    }
+
+    const turnId = crypto.randomUUID();
+    for (const m of pending) {
+      await ctx.db.update("Message", String(m.id), { status: "processing", turnId });
+    }
+    await ctx.db.update("Conversation", conversation.id, {
+      turnState: "running",
+      turnId,
+      turnStartedAt: now.toISOString(),
+      needsAnotherTurn: false,
+    });
+
+    const contactRow = await ctx.db.get("Contact", conversation.contactId);
+    const contact = contactRow ? toContact(contactRow) : null;
+    const settings = await loadSettings(ctx);
+
+    // One AgentRun holds the model transcript. When it grows past the cap, the
+    // next turn starts a new run and carries recent texts as plain context.
+    let runId = conversation.agentRunId;
+    let context: string[] = [];
+    if (runId) {
+      const transcript = await ctx.db.query("AgentMessage", { runId, $limit: MAX_RUN_MESSAGES + 1 });
+      if (transcript.length > MAX_RUN_MESSAGES) runId = null;
+    }
+    if (!runId) {
+      const recent = await ctx.db.query("Message", {
+        conversationId: conversation.id,
+        $order: { createdAt: "desc" },
+        $limit: CONTEXT_LINES + pending.length,
+      });
+      const pendingIds = new Set(pending.map((m) => String(m.id)));
+      context = recent
+        .filter((m) => !pendingIds.has(String(m.id)) && (m.direction === "out" || m.status === "answered"))
+        .slice(0, CONTEXT_LINES)
+        .reverse()
+        .map((m) => `${m.direction === "in" ? "Them" : "You"}: ${String(m.text).replace(/\s+/g, " ").slice(0, 300)}`);
+    }
+
+    const input = buildTurnInput(
+      {
+        ownerName: settings.ownerName || null,
+        contactName: contact?.displayName ?? null,
+        handle: conversation.handle,
+        timezone: settings.timezone,
+        now,
+      },
+      pending.map((m) => String(m.text)),
+      context,
+    );
+
+    return {
+      state: "started" as const,
+      turnId,
+      conversationId: conversation.id,
+      runId,
+      input,
+    };
+  },
+});

package/templates/imessage/functions/cancelReminder.ts

@@ -0,0 +1,13 @@
+import { mutation, v } from "@pylonsync/functions";
+
+// Cancel an upcoming reminder from the dashboard. Owner only.
+export default mutation({
+  auth: "admin",
+  args: { reminderId: v.string() },
+  async handler(ctx, args) {
+    const reminder = await ctx.db.get("Reminder", args.reminderId);
+    if (!reminder || reminder.status !== "scheduled") throw ctx.error("NOT_FOUND", "No upcoming reminder with that id");
+    await ctx.db.update("Reminder", args.reminderId, { status: "cancelled", detail: "Cancelled by the owner" });
+    return { ok: true };
+  },
+});

package/templates/imessage/functions/claimOutbound.ts

@@ -0,0 +1,44 @@
+import { mutation, v } from "@pylonsync/functions";
+
+/** Longer than a full batch can take: 5 sends × 20 s fetch timeout, plus settling. */
+const LEASE_MS = 3 * 60 * 1000;
+const BATCH = 5;
+
+// Lease a conversation's queued Sendblue messages for deliverOutbound, oldest
+// first. The lease carries a random token; settleOutbound accepts a result
+// only with that token, so a job whose lease expired and was taken over
+// cannot settle (or be followed by a resend of) a message it no longer holds.
+// Internal.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: { conversationId: v.string() },
+  async handler(ctx, args) {
+    const conversation = await ctx.db.get("Conversation", args.conversationId);
+    if (!conversation) return { leaseToken: null, messages: [] };
+    const now = new Date();
+    const rows = await ctx.db.query("Message", {
+      conversationId: args.conversationId,
+      status: { $in: ["queued", "leased"] },
+      $order: { createdAt: "asc" },
+      $limit: 50,
+    });
+    const leaseToken = crypto.randomUUID();
+    const leaseUntil = new Date(now.getTime() + LEASE_MS).toISOString();
+    const messages: { id: string; handle: string; text: string }[] = [];
+    for (const row of rows) {
+      if (messages.length >= BATCH) break;
+      if (row.direction !== "out" || row.transport !== "sendblue") continue;
+      // A live lease belongs to another delivery job; stop so order holds.
+      if (row.status === "leased" && String(row.leaseUntil ?? "") > now.toISOString()) break;
+      await ctx.db.update("Message", String(row.id), {
+        status: "leased",
+        leaseUntil,
+        leaseToken,
+        attempts: (Number(row.attempts) || 0) + 1,
+      });
+      messages.push({ id: String(row.id), handle: String(conversation.handle), text: String(row.text) });
+    }
+    return { leaseToken: messages.length > 0 ? leaseToken : null, messages };
+  },
+});

package/templates/imessage/functions/clearDemo.ts

@@ -0,0 +1,18 @@
+import { mutation } from "@pylonsync/functions";
+
+// Delete every sample row (demo: true). Owner only.
+export default mutation({
+  auth: "admin",
+  args: {},
+  async handler(ctx) {
+    let removed = 0;
+    for (const entity of ["Message", "Note", "Reminder", "Conversation", "Contact"]) {
+      const rows = await ctx.db.query(entity, { demo: true });
+      for (const row of rows) {
+        await ctx.db.delete(entity, String(row.id));
+        removed += 1;
+      }
+    }
+    return { removed };
+  },
+});

package/templates/imessage/functions/deleteNote.ts

@@ -0,0 +1,11 @@
+import { mutation, v } from "@pylonsync/functions";
+
+// Remove a saved fact from the dashboard. Owner only.
+export default mutation({
+  auth: "admin",
+  args: { noteId: v.string() },
+  async handler(ctx, args) {
+    const deleted = await ctx.db.delete("Note", args.noteId);
+    return { deleted };
+  },
+});

package/templates/imessage/functions/deliverOutbound.ts

@@ -0,0 +1,55 @@
+import { action, v } from "@pylonsync/functions";
+import { sendblueConfig, sendblueTransport } from "../lib/sendblue";
+import { isDryRun } from "../lib/transport";
+
+interface Claimed {
+  leaseToken: string | null;
+  messages: { id: string; handle: string; text: string }[];
+}
+
+// Send a conversation's queued Sendblue messages, oldest first, one at a time
+// so bubbles arrive in order. claimOutbound leases the batch in a transaction
+// under a token only this job holds, so two concurrent jobs for the same
+// conversation never send a message twice.
+// Scheduled by queueOutbound (lib/store.ts); internal.
+export default action({
+  internal: true,
+  auth: "admin",
+  timeout: 120,
+  args: { conversationId: v.string() },
+  async handler(ctx, args) {
+    const claim = await ctx.runMutation<Claimed>("claimOutbound", { conversationId: args.conversationId });
+    const batch = claim.messages;
+    if (batch.length === 0 || !claim.leaseToken) return { sent: 0 };
+    let failed = false;
+    const transport = sendblueTransport(sendblueConfig(ctx.env, isDryRun(ctx.env)));
+    let sent = 0;
+    for (const message of batch) {
+      const result = await transport.send({ messageId: message.id, to: message.handle, text: message.text });
+      const settled = await ctx.runMutation<{ ok: boolean }>("settleOutbound", {
+        messageId: message.id,
+        leaseToken: claim.leaseToken,
+        status: result.status === "sent" || result.status === "queued" ? "sent" : result.status,
+        externalId: result.status === "sent" ? result.externalId : null,
+        error: result.status === "failed" ? result.error : null,
+      });
+      // The lease was lost (expired and taken over): stop, the new holder owns the rest.
+      if (!settled.ok) break;
+      if (result.status === "failed") {
+        failed = true;
+        // Release the rest so a later attempt keeps the order intact.
+        await ctx.runMutation("releaseOutbound", {
+          leaseToken: claim.leaseToken,
+          messageIds: batch.slice(batch.indexOf(message) + 1).map((m) => m.id),
+        });
+        break;
+      }
+      sent += 1;
+    }
+    // More may be waiting behind this batch.
+    if (!failed && batch.length === 5) {
+      await ctx.scheduler.runAfter(0, "deliverOutbound", { conversationId: args.conversationId });
+    }
+    return { sent };
+  },
+});

package/templates/imessage/functions/finishTurn.ts

@@ -0,0 +1,84 @@
+import { mutation, v } from "@pylonsync/functions";
+import { queueOutbound, toContact, toConversation } from "../lib/store";
+
+// Close a turn claimed by beginTurn: settle its inbound texts, store the
+// reply bubbles and queue them for delivery, record the agent run, and
+// schedule another turn when texts arrived meanwhile. Internal: processTurn only.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: {
+    conversationId: v.string(),
+    turnId: v.string(),
+    outcome: v.union(v.literal("answered"), v.literal("awaiting_setup"), v.literal("failed")),
+    detail: v.optional(v.string()),
+    runId: v.optional(v.string()),
+    chunks: v.optional(v.array(v.string())),
+  },
+  async handler(ctx, args) {
+    const row = await ctx.db.get("Conversation", args.conversationId);
+    if (!row) return { ok: false };
+    const conversation = toConversation(row);
+    // A sweep may have taken the turn over; a stale finisher must not clobber it.
+    if (conversation.turnId !== args.turnId) return { ok: false };
+
+    const turnMessages = await ctx.db.query("Message", {
+      conversationId: conversation.id,
+      turnId: args.turnId,
+    });
+    const now = new Date().toISOString();
+    for (const m of turnMessages) {
+      if (m.direction !== "in" || m.status !== "processing") continue;
+      await ctx.db.update("Message", String(m.id), {
+        status: args.outcome,
+        detail: args.outcome === "answered" ? null : (args.detail ?? null),
+        agentRunId: args.runId ?? null,
+      });
+    }
+
+    const contactRow = await ctx.db.get("Contact", conversation.contactId);
+    const contact = contactRow ? toContact(contactRow) : null;
+    // Re-check at send time: the owner may have blocked the contact, or the
+    // contact may have texted STOP, while the model was thinking.
+    const maySend = contact !== null && contact.status === "allowed" && !contact.optedOut;
+    if (args.outcome === "answered" && maySend) {
+      for (const text of args.chunks ?? []) {
+        await queueOutbound(ctx, {
+          conversationId: conversation.id,
+          contactId: conversation.contactId,
+          handle: conversation.handle,
+          text,
+          kind: "agent",
+          turnId: args.turnId,
+          agentRunId: args.runId ?? null,
+        });
+      }
+    }
+
+    const patch: Record<string, unknown> = {
+      turnState: "idle",
+      turnId: null,
+      turnStartedAt: null,
+      needsAnotherTurn: false,
+    };
+    if (args.runId) patch.agentRunId = args.runId;
+    if (args.outcome === "answered") {
+      patch.lastError = null;
+      patch.lastErrorAt = null;
+    } else {
+      patch.lastError = args.detail ?? args.outcome;
+      patch.lastErrorAt = now;
+    }
+    await ctx.db.update("Conversation", conversation.id, patch);
+
+    const waiting = await ctx.db.query("Message", {
+      conversationId: conversation.id,
+      status: "received",
+      $limit: 1,
+    });
+    if (conversation.needsAnotherTurn || waiting.length > 0) {
+      await ctx.scheduler.runAfter(0, "processTurn", { conversationId: conversation.id });
+    }
+    return { ok: true };
+  },
+});

package/templates/imessage/functions/fireReminder.ts

@@ -0,0 +1,42 @@
+import { mutation, v } from "@pylonsync/functions";
+import { loadSettings, queueOutbound, toContact } from "../lib/store";
+
+// Send a due reminder. Scheduled with ctx.scheduler.runAt by toolSetReminder;
+// internal. A cancelled or already-sent reminder is a no-op, so a job retry
+// never texts twice.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: { reminderId: v.string() },
+  async handler(ctx, args) {
+    const reminder = await ctx.db.get("Reminder", args.reminderId);
+    if (!reminder || reminder.status !== "scheduled") return { sent: false };
+    const contactRow = await ctx.db.get("Contact", String(reminder.contactId));
+    const conversation = await ctx.db.get("Conversation", String(reminder.conversationId));
+    const contact = contactRow ? toContact(contactRow) : null;
+    if ((await loadSettings(ctx)).paused) {
+      await ctx.db.update("Reminder", args.reminderId, { status: "cancelled", detail: "The assistant was paused" });
+      return { sent: false };
+    }
+    if (!contact || !conversation || contact.status !== "allowed" || contact.optedOut) {
+      await ctx.db.update("Reminder", args.reminderId, {
+        status: "cancelled",
+        detail: "The contact is no longer on the allowlist",
+      });
+      return { sent: false };
+    }
+    const messageId = await queueOutbound(ctx, {
+      conversationId: String(conversation.id),
+      contactId: contact.id,
+      handle: contact.handle,
+      text: String(reminder.text),
+      kind: "reminder",
+    });
+    await ctx.db.update("Reminder", args.reminderId, {
+      status: "sent",
+      sentAt: new Date().toISOString(),
+      detail: null,
+    });
+    return { sent: true, messageId };
+  },
+});

package/templates/imessage/functions/ingestInbound.ts

@@ -0,0 +1,22 @@
+import { mutation, v } from "@pylonsync/functions";
+import { ingestInbound } from "../lib/store";
+
+// Store one verified inbound message and act on it (lib/store.ts ingestInbound).
+// Internal: reachable only from sendblueWebhook after its secret check.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: {
+    transport: v.union(v.literal("sendblue"), v.literal("relay")),
+    message: v.object({
+      externalId: v.string(),
+      handle: v.string(),
+      text: v.string(),
+      sentAt: v.string(),
+      service: v.string(),
+    }),
+  },
+  async handler(ctx, args) {
+    return ingestInbound(ctx, args.message, args.transport);
+  },
+});

package/templates/imessage/functions/ownerAccount.ts

@@ -0,0 +1,13 @@
+import { query } from "@pylonsync/functions";
+import { findOwner } from "../lib/store";
+
+// The owner's user id (lib/store.ts findOwner). Internal: the agent runs as
+// this account, so the id never leaves the server.
+export default query({
+  internal: true,
+  auth: "admin",
+  args: {},
+  async handler(ctx) {
+    return findOwner(ctx);
+  },
+});

package/templates/imessage/functions/processTurn.ts

@@ -0,0 +1,74 @@
+import { action, v } from "@pylonsync/functions";
+import { runAgentAsOwner } from "../lib/agent-call";
+import { chunkReply } from "../lib/chunk";
+import { providerStatus } from "../lib/provider";
+
+type Begin =
+  | { state: "idle" | "busy" }
+  | { state: "started"; turnId: string; conversationId: string; runId: string | null; input: string };
+
+// One agent turn for a conversation: claim the waiting texts, run the
+// `assistant` agent as the owner, split the reply into bubbles, and hand them
+// to finishTurn for delivery. Scheduled by ingestInbound; internal.
+//
+// Every failure is recorded on the texts and the conversation rather than
+// thrown, so the job queue does not retry a turn that already reached the
+// model.
+export default action({
+  internal: true,
+  auth: "admin",
+  timeout: 300,
+  args: { conversationId: v.string() },
+  async handler(ctx, args) {
+    const begin = await ctx.runMutation<Begin>("beginTurn", { conversationId: args.conversationId });
+    if (begin.state !== "started") return { state: begin.state };
+
+    const finish = (fields: Record<string, unknown>) =>
+      ctx.runMutation("finishTurn", {
+        conversationId: begin.conversationId,
+        turnId: begin.turnId,
+        ...fields,
+      });
+
+    try {
+      if (!providerStatus(ctx.env).configured) {
+        await finish({
+          outcome: "awaiting_setup",
+          detail: "No model provider key is set. Add ANTHROPIC_API_KEY or OPENAI_API_KEY, then answer from the contact details.",
+        });
+        return { state: "awaiting_setup" };
+      }
+      const owner = await ctx.runQuery<{ userId: string } | null>("ownerAccount", {});
+      if (!owner) {
+        await finish({
+          outcome: "awaiting_setup",
+          detail: "No owner account yet. Sign in at /login with the email in PYLON_ADMIN_EMAILS.",
+        });
+        return { state: "awaiting_setup" };
+      }
+
+      const outcome = await runAgentAsOwner(ctx.env, owner.userId, {
+        input: begin.input,
+        ...(begin.runId ? { runId: begin.runId } : {}),
+        // The run's title carries the conversation id. The agent's tools read
+        // it back (functions/resolveTurn.ts) to know which contact they act on.
+        title: begin.conversationId,
+      });
+      if (!outcome.ok) {
+        await finish({ outcome: "failed", detail: `${outcome.code}: ${outcome.message}`.slice(0, 500) });
+        return { state: "failed" };
+      }
+      const chunks = chunkReply(outcome.result.text);
+      if (chunks.length === 0) {
+        await finish({ outcome: "failed", detail: "The model returned an empty reply", runId: outcome.result.runId });
+        return { state: "failed" };
+      }
+      await finish({ outcome: "answered", runId: outcome.result.runId, chunks });
+      return { state: "answered", bubbles: chunks.length };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      await finish({ outcome: "failed", detail: message.slice(0, 500) });
+      return { state: "failed" };
+    }
+  },
+});

package/templates/imessage/functions/relayApply.ts

@@ -0,0 +1,102 @@
+import { mutation, v } from "@pylonsync/functions";
+import { MAX_OUTBOUND_PER_SYNC, MAX_RELAY_ATTEMPTS, OUTBOUND_LEASE_MS } from "../lib/relay-protocol";
+import { ingestInbound, touchTransport } from "../lib/store";
+
+// One relay sync, in one transaction: record the heartbeat, settle the acks
+// for replies the relay sent, store new inbound messages, and lease the next
+// batch of queued replies. Internal: reachable only from relaySync after its
+// token check.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: {
+    relayVersion: v.string(),
+    host: v.string(),
+    messages: v.array(
+      v.object({
+        externalId: v.string(),
+        handle: v.string(),
+        text: v.string(),
+        sentAt: v.string(),
+        service: v.string(),
+      }),
+    ),
+    skipped: v.array(v.string()),
+    acks: v.array(
+      v.object({ id: v.string(), ok: v.boolean(), error: v.optional(v.string()), dryRun: v.optional(v.boolean()) }),
+    ),
+  },
+  async handler(ctx, args) {
+    const now = new Date();
+    const nowIso = now.toISOString();
+    const statePatch: Record<string, unknown> = {
+      relayLastSeenAt: nowIso,
+      relayVersion: args.relayVersion,
+      relayHost: args.host,
+    };
+
+    for (const ack of args.acks) {
+      const row = await ctx.db.get("Message", ack.id);
+      // Only a leased relay reply can be settled; anything else is stale.
+      if (!row || row.direction !== "out" || row.transport !== "relay" || row.status !== "leased") continue;
+      if (ack.ok && ack.dryRun) {
+        await ctx.db.update("Message", ack.id, {
+          status: "dry_run",
+          sentAt: nowIso,
+          leaseUntil: null,
+          detail: "RELAY_DRY_RUN is on; the relay did not send it.",
+        });
+      } else if (ack.ok) {
+        await ctx.db.update("Message", ack.id, { status: "sent", sentAt: nowIso, leaseUntil: null, detail: null });
+        statePatch.lastOutboundAt = nowIso;
+      } else {
+        const error = ack.error || "The relay could not send this message";
+        await ctx.db.update("Message", ack.id, { status: "failed", detail: error, leaseUntil: null });
+        statePatch.lastError = error;
+        statePatch.lastErrorAt = nowIso;
+      }
+    }
+
+    const accepted: string[] = [...args.skipped];
+    for (const message of args.messages) {
+      await ingestInbound(ctx, message, "relay");
+      // "dropped" is accepted too: the server decided not to store it, and
+      // resending the same row would get the same answer.
+      accepted.push(message.externalId.replace(/^relay:/, ""));
+    }
+
+    // Queued replies plus leases the relay let expire, oldest first.
+    const queued = await ctx.db.query("Message", {
+      status: { $in: ["queued", "leased"] },
+      $order: { createdAt: "asc" },
+      $limit: 200,
+    });
+    const outbound: { id: string; handle: string; text: string }[] = [];
+    const leaseUntil = new Date(now.getTime() + OUTBOUND_LEASE_MS).toISOString();
+    for (const row of queued) {
+      if (outbound.length >= MAX_OUTBOUND_PER_SYNC) break;
+      if (row.transport !== "relay" || row.direction !== "out") continue;
+      if (row.status === "leased" && String(row.leaseUntil ?? "") > nowIso) continue;
+      const attempts = Number(row.attempts) || 0;
+      if (attempts >= MAX_RELAY_ATTEMPTS) {
+        await ctx.db.update("Message", String(row.id), {
+          status: "failed",
+          leaseUntil: null,
+          detail: `The relay did not confirm delivery after ${attempts} attempts`,
+        });
+        continue;
+      }
+      const conversation = await ctx.db.get("Conversation", String(row.conversationId));
+      if (!conversation) continue;
+      await ctx.db.update("Message", String(row.id), {
+        status: "leased",
+        leaseUntil,
+        attempts: attempts + 1,
+      });
+      outbound.push({ id: String(row.id), handle: String(conversation.handle), text: String(row.text) });
+    }
+
+    await touchTransport(ctx, "relay", statePatch);
+    return { accepted, outbound };
+  },
+});

package/templates/imessage/functions/relaySync.ts

@@ -0,0 +1,63 @@
+import { action, v } from "@pylonsync/functions";
+import {
+  MAX_INBOUND_PER_SYNC,
+  parseRelayInbound,
+  type RelaySyncResponse,
+} from "../lib/relay-protocol";
+import { bearerToken, checkSecret, headerValue } from "../lib/secrets";
+import { selectedTransport, type InboundMessage } from "../lib/transport";
+
+// The Mac relay's single endpoint (see lib/relay-protocol.ts for the contract).
+// Public by necessity; the handler rejects the call unless the bearer token
+// matches RELAY_TOKEN (constant-time), and only then elevates to write.
+export default action({
+  auth: "public",
+  args: {
+    relayVersion: v.string(),
+    host: v.string(),
+    inbound: v.array(v.any()),
+    acks: v.array(
+      v.object({
+        id: v.string(),
+        ok: v.boolean(),
+        error: v.optional(v.string()),
+        dryRun: v.optional(v.boolean()),
+      }),
+    ),
+  },
+  async handler(ctx, args): Promise<RelaySyncResponse> {
+    if (selectedTransport(ctx.env) !== "relay") {
+      throw ctx.error("TRANSPORT_DISABLED", "The relay transport is not enabled on this server");
+    }
+    const presented = bearerToken(headerValue(ctx.request?.headers, "authorization"));
+    const check = checkSecret(presented, ctx.env.RELAY_TOKEN);
+    if (!check.ok) {
+      if (check.reason === "not_configured") throw ctx.error("NOT_CONFIGURED", "RELAY_TOKEN is not set");
+      throw ctx.error("UNAUTHORIZED", "Relay token missing or invalid");
+    }
+    if (args.inbound.length > MAX_INBOUND_PER_SYNC || args.acks.length > 100) {
+      throw ctx.error("TOO_LARGE", `Send at most ${MAX_INBOUND_PER_SYNC} messages per sync`);
+    }
+
+    const messages: InboundMessage[] = [];
+    // Items the server deliberately skips (group chats, attachments without
+    // text) still count as accepted, so the relay's watermark moves past them.
+    const skipped: string[] = [];
+    for (const item of args.inbound) {
+      const parsed = parseRelayInbound(item);
+      if ("message" in parsed) messages.push(parsed.message);
+      else if (typeof (item as { guid?: unknown })?.guid === "string") {
+        skipped.push(String((item as { guid: string }).guid).slice(0, 128));
+      }
+    }
+
+    await ctx.auth.elevate({ admin: true, reason: "relay token verified" });
+    return ctx.runMutation<RelaySyncResponse>("relayApply", {
+      relayVersion: args.relayVersion.slice(0, 32),
+      host: args.host.slice(0, 64),
+      messages,
+      skipped,
+      acks: args.acks.map((a) => ({ id: a.id, ok: a.ok, error: a.error?.slice(0, 300), dryRun: a.dryRun === true })),
+    });
+  },
+});

package/templates/imessage/functions/releaseOutbound.ts

@@ -0,0 +1,18 @@
+import { mutation, v } from "@pylonsync/functions";
+
+// Return leased Sendblue messages to the queue after an earlier message in the
+// same batch failed. Internal: deliverOutbound only.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: { leaseToken: v.string(), messageIds: v.array(v.string()) },
+  async handler(ctx, args) {
+    for (const id of args.messageIds) {
+      const row = await ctx.db.get("Message", id);
+      if (row?.status === "leased" && row.leaseToken === args.leaseToken) {
+        await ctx.db.update("Message", id, { status: "queued", leaseUntil: null, leaseToken: null });
+      }
+    }
+    return { released: args.messageIds.length };
+  },
+});