@pylonsync/create-pylon 0.19.0 → 0.20.0

package/templates/imessage/functions/resolveTurn.ts

@@ -0,0 +1,25 @@
+import { query, v } from "@pylonsync/functions";
+import { AGENT_NAME } from "../lib/assistant";
+
+// Map the agent's current stream id to the conversation it is answering.
+// Internal: called by the assistant's tools only (functions/assistant.ts).
+//
+// Returns null unless all of these hold:
+//   - an AgentRun of the assistant carries this stream id and belongs to the caller
+//   - its title is a conversation id (processTurn sets it)
+//   - that conversation has a turn running right now
+export default query({
+  internal: true,
+  auth: "admin",
+  args: { streamId: v.string() },
+  async handler(ctx, args) {
+    if (args.streamId === "") return null;
+    const runs = await ctx.db.query("AgentRun", { streamId: args.streamId, $limit: 2 });
+    if (runs.length !== 1) return null;
+    const run = runs[0];
+    if (run.agent !== AGENT_NAME || run.userId !== ctx.auth.userId || run.status !== "running") return null;
+    const conversation = await ctx.db.get("Conversation", String(run.title ?? ""));
+    if (!conversation || conversation.turnState !== "running") return null;
+    return { conversationId: String(conversation.id), contactId: String(conversation.contactId) };
+  },
+});

package/templates/imessage/functions/saveContact.ts

@@ -0,0 +1,27 @@
+import { mutation, v } from "@pylonsync/functions";
+import { normalizeHandle } from "../lib/handles";
+import { getOrCreateContact, getOrCreateConversation } from "../lib/store";
+
+// Add a contact or update one: name and allowlist status. Owner only.
+export default mutation({
+  auth: "admin",
+  args: {
+    handle: v.string(),
+    displayName: v.optional(v.string()),
+    status: v.union(v.literal("allowed"), v.literal("blocked"), v.literal("unknown")),
+  },
+  async handler(ctx, args) {
+    const normalized = normalizeHandle(args.handle);
+    if (!normalized) {
+      throw ctx.error("INVALID_HANDLE", "Enter a phone number like +1 512 555 0100 or an email address");
+    }
+    const name = (args.displayName ?? "").replace(/\s+/g, " ").trim().slice(0, 80);
+    const contact = await getOrCreateContact(ctx, normalized.handle, { status: args.status });
+    await ctx.db.update("Contact", contact.id, {
+      status: args.status,
+      ...(args.displayName !== undefined ? { displayName: name || null } : {}),
+    });
+    const conversation = await getOrCreateConversation(ctx, contact);
+    return { contactId: contact.id, conversationId: conversation.id, handle: normalized.handle };
+  },
+});

package/templates/imessage/functions/seedDemo.ts

@@ -0,0 +1,70 @@
+import { mutation } from "@pylonsync/functions";
+import { DEMO_THREADS } from "../lib/demo";
+import { ensureSettings, getOrCreateContact, getOrCreateConversation } from "../lib/store";
+
+// Insert the sample threads (lib/demo.ts) once, on the owner's first visit to
+// an empty dashboard. Owner only. A no-op after the first run, and a no-op if
+// any real conversation exists.
+export default mutation({
+  auth: "admin",
+  args: {},
+  async handler(ctx) {
+    const settings = await ensureSettings(ctx);
+    if (settings.demoSeededAt) return { seeded: false };
+    const existing = await ctx.db.query("Conversation", { $limit: 1 });
+    await ctx.db.update("Settings", String(settings.id), { demoSeededAt: new Date().toISOString() });
+    if (existing.length > 0) return { seeded: false };
+
+    const now = Date.now();
+    for (const thread of DEMO_THREADS) {
+      const contact = await getOrCreateContact(ctx, thread.handle, {
+        status: thread.status,
+        displayName: thread.displayName,
+        demo: true,
+      });
+      const conversation = await getOrCreateConversation(ctx, contact, true);
+      let last = { at: "", text: "", direction: "in" };
+      for (const m of thread.messages) {
+        const at = new Date(now - m.ago * 60_000).toISOString();
+        const inbound = m.from === "them";
+        await ctx.db.insert("Message", {
+          conversationId: conversation.id,
+          contactId: contact.id,
+          direction: inbound ? "in" : "out",
+          kind: inbound ? "inbound" : "agent",
+          text: m.text,
+          status: inbound ? (thread.status === "allowed" ? "answered" : "ignored") : "sent",
+          detail: inbound && thread.status !== "allowed" ? "unknown_sender" : null,
+          transport: "demo",
+          attempts: 0,
+          sentAt: at,
+          demo: true,
+          createdAt: at,
+        });
+        last = { at, text: m.text, direction: inbound ? "in" : "out" };
+      }
+      await ctx.db.update("Conversation", conversation.id, {
+        lastMessageAt: last.at,
+        lastPreview: last.text,
+        lastDirection: last.direction,
+      });
+      await ctx.db.update("Contact", contact.id, { lastMessageAt: last.at });
+      for (const text of thread.notes ?? []) {
+        await ctx.db.insert("Note", { contactId: contact.id, text, demo: true, createdAt: new Date(now).toISOString() });
+      }
+      if (thread.reminder) {
+        await ctx.db.insert("Reminder", {
+          contactId: contact.id,
+          conversationId: conversation.id,
+          text: thread.reminder.text,
+          dueAt: new Date(now + thread.reminder.inMinutes * 60_000).toISOString(),
+          // Sample reminders are never scheduled, so they can never send.
+          status: "scheduled",
+          demo: true,
+          createdAt: new Date(now).toISOString(),
+        });
+      }
+    }
+    return { seeded: true };
+  },
+});

package/templates/imessage/functions/sendOwnerMessage.ts

@@ -0,0 +1,28 @@
+import { mutation, v } from "@pylonsync/functions";
+import { queueOutbound, toContact } from "../lib/store";
+
+// The owner types a message into a thread and it goes out through the
+// active transport. Owner only. Refused for contacts who texted STOP.
+export default mutation({
+  auth: "admin",
+  args: { conversationId: v.string(), text: v.string() },
+  async handler(ctx, args) {
+    const text = args.text.trim();
+    if (text === "") throw ctx.error("INVALID_ARGS", "Type a message first");
+    if (text.length > 4000) throw ctx.error("INVALID_ARGS", "Keep it under 4,000 characters");
+    const conversation = await ctx.db.get("Conversation", args.conversationId);
+    if (!conversation) throw ctx.error("NOT_FOUND", "No such conversation");
+    const contactRow = await ctx.db.get("Contact", String(conversation.contactId));
+    if (!contactRow) throw ctx.error("NOT_FOUND", "No such contact");
+    const contact = toContact(contactRow);
+    if (contact.optedOut) throw ctx.error("OPTED_OUT", "This person texted STOP. They have to text START first.");
+    const id = await queueOutbound(ctx, {
+      conversationId: String(conversation.id),
+      contactId: contact.id,
+      handle: contact.handle,
+      text,
+      kind: "owner",
+    });
+    return { messageId: id };
+  },
+});

package/templates/imessage/functions/sendblueWebhook.ts

@@ -0,0 +1,49 @@
+import { action, v } from "@pylonsync/functions";
+import { parseSendblueInbound, sendblueConfig, verifySendblueWebhook } from "../lib/sendblue";
+import { isDryRun, selectedTransport } from "../lib/transport";
+
+// Sendblue's receive webhook. Point Sendblue at:
+//   https://<your app>/api/webhooks/sendblueWebhook
+// with the same secret as SENDBLUE_WEBHOOK_SECRET.
+//
+// Public by necessity (Sendblue has no session). The handler rejects the
+// request unless the `sb-signing-secret` header matches the configured secret,
+// and only then elevates to store the message.
+export default action({
+  auth: "public",
+  // /api/webhooks/* passes { rawBody }; the handler always reads the raw
+  // request so the body it parses is the one that arrived with the header.
+  args: { rawBody: v.optional(v.string()) },
+  async handler(ctx) {
+    if (selectedTransport(ctx.env) !== "sendblue") {
+      throw ctx.error("TRANSPORT_DISABLED", "The Sendblue transport is not enabled on this server");
+    }
+    const request = ctx.request;
+    if (!request) throw ctx.error("BAD_REQUEST", "This endpoint only accepts HTTP webhook deliveries");
+
+    const config = sendblueConfig(ctx.env, isDryRun(ctx.env));
+    const check = verifySendblueWebhook(request.headers, config.webhookSecret);
+    if (!check.ok) {
+      if (check.reason === "not_configured") {
+        throw ctx.error("NOT_CONFIGURED", "SENDBLUE_WEBHOOK_SECRET is not set");
+      }
+      throw ctx.error("UNAUTHORIZED", "Webhook secret missing or invalid");
+    }
+
+    let body: unknown;
+    try {
+      body = JSON.parse(request.rawBody);
+    } catch {
+      throw ctx.error("INVALID_JSON", "Webhook body is not JSON");
+    }
+    const parsed = parseSendblueInbound(body, config.fromNumber);
+    if ("skip" in parsed) return { ok: true, skipped: parsed.skip };
+
+    await ctx.auth.elevate({ admin: true, reason: "sendblue webhook secret verified" });
+    const result = await ctx.runMutation<{ status: string }>("ingestInbound", {
+      transport: "sendblue",
+      message: parsed.message,
+    });
+    return { ok: true, status: result.status };
+  },
+});

package/templates/imessage/functions/setContactStatus.ts

@@ -0,0 +1,17 @@
+import { mutation, v } from "@pylonsync/functions";
+
+// Allow, block, or reset a contact. Allowing a contact who has texts waiting
+// does not answer them; use answerNow for that. Owner only.
+export default mutation({
+  auth: "admin",
+  args: {
+    contactId: v.string(),
+    status: v.union(v.literal("allowed"), v.literal("blocked"), v.literal("unknown")),
+  },
+  async handler(ctx, args) {
+    const contact = await ctx.db.get("Contact", args.contactId);
+    if (!contact) throw ctx.error("NOT_FOUND", "No such contact");
+    await ctx.db.update("Contact", args.contactId, { status: args.status });
+    return { ok: true };
+  },
+});

package/templates/imessage/functions/settleOutbound.ts

@@ -0,0 +1,35 @@
+import { mutation, v } from "@pylonsync/functions";
+import { touchTransport } from "../lib/store";
+
+// Record the result of one Sendblue send. Internal: deliverOutbound only.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: {
+    messageId: v.string(),
+    leaseToken: v.string(),
+    status: v.union(v.literal("sent"), v.literal("dry_run"), v.literal("failed")),
+    externalId: v.optional(v.string()),
+    error: v.optional(v.string()),
+  },
+  async handler(ctx, args) {
+    const row = await ctx.db.get("Message", args.messageId);
+    if (!row || row.status !== "leased" || row.leaseToken !== args.leaseToken) return { ok: false };
+    const now = new Date().toISOString();
+    await ctx.db.update("Message", args.messageId, {
+      status: args.status,
+      leaseUntil: null,
+      leaseToken: null,
+      sentAt: args.status === "failed" ? null : now,
+      detail: args.error ?? null,
+      // The provider's id for the sent message. Unique like inbound ids.
+      ...(args.externalId ? { externalId: args.externalId } : {}),
+    });
+    await touchTransport(
+      ctx,
+      "sendblue",
+      args.status === "failed" ? { lastError: args.error ?? "Send failed", lastErrorAt: now } : { lastOutboundAt: now },
+    );
+    return { ok: true };
+  },
+});

package/templates/imessage/functions/setupStatus.ts

@@ -0,0 +1,33 @@
+import { query } from "@pylonsync/functions";
+import { selfBaseUrl } from "../lib/agent-call";
+import { providerStatus } from "../lib/provider";
+import { findOwner } from "../lib/store";
+import { isDevMode, isDryRun, selectedTransport, transportChecklist } from "../lib/transport";
+
+// What the server is configured with, for the dashboard's setup panel.
+// Reports which variables are present, never their values. Owner only.
+export default query({
+  auth: "admin",
+  args: {},
+  async handler(ctx) {
+    const transport = selectedTransport(ctx.env);
+    const provider = providerStatus(ctx.env);
+    const owner = await findOwner(ctx);
+    const base = selfBaseUrl(ctx.env);
+    const devMode = isDevMode(ctx.env);
+    return {
+      transport,
+      dryRun: isDryRun(ctx.env),
+      checklist: transport ? transportChecklist(ctx.env, transport) : [],
+      provider,
+      ownerConfigured: owner !== null,
+      adminEmailsSet: (ctx.env.PYLON_ADMIN_EMAILS ?? "").trim() !== "",
+      adminTokenSet: (ctx.env.PYLON_ADMIN_TOKEN ?? "").trim() !== "",
+      appUrlSet: (ctx.env.APP_URL ?? ctx.env.PYLON_PUBLIC_URL ?? "").trim() !== "",
+      devMode,
+      baseUrl: base,
+      webhookUrl: `${base}/api/webhooks/sendblueWebhook`,
+      relayUrl: base,
+    };
+  },
+});

package/templates/imessage/functions/sweep.ts

@@ -0,0 +1,58 @@
+import { mutation } from "@pylonsync/functions";
+import { TURN_STALE_MS } from "../lib/store";
+
+// Every five minutes (app.ts crons):
+//   - release turns whose worker died so the conversation can answer again,
+//     and mark their texts failed;
+//   - restart Sendblue delivery for conversations with messages still queued
+//     or leased past expiry (the delivery job died). Relay leases need no
+//     sweep: the relay's next sync picks expired ones up.
+// Internal.
+export default mutation({
+  internal: true,
+  args: {},
+  async handler(ctx) {
+    await ctx.auth.elevate({ admin: true, reason: "scheduled sweep of stuck agent turns" });
+    const cutoff = new Date(Date.now() - TURN_STALE_MS).toISOString();
+    const running = await ctx.db.query("Conversation", { turnState: "running", $limit: 100 });
+    let released = 0;
+    for (const conversation of running) {
+      if (String(conversation.turnStartedAt ?? "") > cutoff) continue;
+      const stuck = await ctx.db.query("Message", {
+        conversationId: String(conversation.id),
+        status: "processing",
+      });
+      for (const m of stuck) {
+        await ctx.db.update("Message", String(m.id), {
+          status: "failed",
+          detail: "The reply took too long and was abandoned",
+        });
+      }
+      await ctx.db.update("Conversation", String(conversation.id), {
+        turnState: "idle",
+        turnId: null,
+        turnStartedAt: null,
+        lastError: "A reply timed out",
+        lastErrorAt: new Date().toISOString(),
+      });
+      released += 1;
+    }
+    const stale = new Date(Date.now() - 60_000).toISOString();
+    const pending = await ctx.db.query("Message", {
+      status: { $in: ["queued", "leased"] },
+      createdAt: { $lt: stale },
+      $limit: 500,
+    });
+    const restart = new Set<string>();
+    const nowIso = new Date().toISOString();
+    for (const m of pending) {
+      if (m.transport !== "sendblue" || m.direction !== "out") continue;
+      if (m.status === "leased" && String(m.leaseUntil ?? "") > nowIso) continue;
+      restart.add(String(m.conversationId));
+    }
+    for (const conversationId of restart) {
+      await ctx.scheduler.runAfter(0, "deliverOutbound", { conversationId });
+    }
+    return { released, deliveriesRestarted: restart.size };
+  },
+});

package/templates/imessage/functions/toolCancelReminder.ts

@@ -0,0 +1,17 @@
+import { mutation, v } from "@pylonsync/functions";
+
+// cancel_reminder. Internal. The reminder must belong to the current contact.
+// The scheduled job still fires and finds it cancelled.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: { contactId: v.string(), reminderId: v.string() },
+  async handler(ctx, args) {
+    const reminder = await ctx.db.get("Reminder", args.reminderId);
+    if (!reminder || reminder.contactId !== args.contactId || reminder.status !== "scheduled") {
+      return { cancelled: false, error: "No such upcoming reminder." };
+    }
+    await ctx.db.update("Reminder", args.reminderId, { status: "cancelled", detail: "Cancelled in conversation" });
+    return { cancelled: true };
+  },
+});

package/templates/imessage/functions/toolForgetNote.ts

@@ -0,0 +1,15 @@
+import { mutation, v } from "@pylonsync/functions";
+
+// forget_note. Internal. The note must belong to the current contact, so a
+// note id guessed or copied from elsewhere does nothing.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: { contactId: v.string(), noteId: v.string() },
+  async handler(ctx, args) {
+    const note = await ctx.db.get("Note", args.noteId);
+    if (!note || note.contactId !== args.contactId) return { deleted: false, error: "No such note." };
+    await ctx.db.delete("Note", args.noteId);
+    return { deleted: true };
+  },
+});

package/templates/imessage/functions/toolListNotes.ts

@@ -0,0 +1,16 @@
+import { query, v } from "@pylonsync/functions";
+
+// recall_notes. Internal: the contact id comes from resolveTurn, never the model.
+export default query({
+  internal: true,
+  auth: "admin",
+  args: { contactId: v.string() },
+  async handler(ctx, args) {
+    const notes = await ctx.db.query("Note", {
+      contactId: args.contactId,
+      $order: { createdAt: "desc" },
+      $limit: 50,
+    });
+    return notes.map((n) => ({ id: String(n.id), text: String(n.text), savedAt: String(n.createdAt) }));
+  },
+});

package/templates/imessage/functions/toolListReminders.ts

@@ -0,0 +1,17 @@
+import { query, v } from "@pylonsync/functions";
+
+// list_reminders. Internal: the contact id comes from resolveTurn.
+export default query({
+  internal: true,
+  auth: "admin",
+  args: { contactId: v.string() },
+  async handler(ctx, args) {
+    const rows = await ctx.db.query("Reminder", {
+      contactId: args.contactId,
+      status: "scheduled",
+      $order: { dueAt: "asc" },
+      $limit: 50,
+    });
+    return rows.map((r) => ({ id: String(r.id), dueAt: String(r.dueAt), text: String(r.text) }));
+  },
+});

package/templates/imessage/functions/toolSaveNote.ts

@@ -0,0 +1,22 @@
+import { mutation, v } from "@pylonsync/functions";
+import { cleanStoredText, MAX_NOTE_CHARS, MAX_NOTES_PER_CONTACT } from "../lib/reminders";
+
+// remember_note. Internal: the contact id comes from resolveTurn, never the model.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: { contactId: v.string(), text: v.string() },
+  async handler(ctx, args) {
+    const text = cleanStoredText(args.text, MAX_NOTE_CHARS);
+    if (text === "") return { saved: false, error: "The note is empty." };
+    const existing = await ctx.db.query("Note", { contactId: args.contactId, $limit: MAX_NOTES_PER_CONTACT + 1 });
+    if (existing.length >= MAX_NOTES_PER_CONTACT) {
+      return { saved: false, error: "Too many notes for this person. Forget an old one first." };
+    }
+    if (existing.some((n) => String(n.text).toLowerCase() === text.toLowerCase())) {
+      return { saved: true, duplicate: true };
+    }
+    const id = await ctx.db.insert("Note", { contactId: args.contactId, text, createdAt: new Date().toISOString() });
+    return { saved: true, id };
+  },
+});

package/templates/imessage/functions/toolSetReminder.ts

@@ -0,0 +1,55 @@
+import { mutation, v } from "@pylonsync/functions";
+import {
+  checkReminderTime,
+  cleanStoredText,
+  MAX_OPEN_REMINDERS_PER_CONTACT,
+  MAX_REMINDER_CHARS,
+  MAX_REMINDERS_PER_CONTACT_PER_DAY,
+} from "../lib/reminders";
+
+// set_reminder. Internal: contact and conversation come from resolveTurn. The
+// reminder always goes to the contact being answered.
+export default mutation({
+  internal: true,
+  auth: "admin",
+  args: { contactId: v.string(), conversationId: v.string(), when: v.string(), text: v.string() },
+  async handler(ctx, args) {
+    const time = checkReminderTime(args.when, new Date());
+    if (!time.ok) return { scheduled: false, error: time.error };
+    const text = cleanStoredText(args.text, MAX_REMINDER_CHARS);
+    if (text === "") return { scheduled: false, error: "The reminder text is empty." };
+    const conversation = await ctx.db.get("Conversation", args.conversationId);
+    if (!conversation || conversation.contactId !== args.contactId) {
+      return { scheduled: false, error: "No conversation for this person." };
+    }
+    const open = await ctx.db.query("Reminder", {
+      contactId: args.contactId,
+      status: "scheduled",
+      $limit: MAX_OPEN_REMINDERS_PER_CONTACT + 1,
+    });
+    if (open.length >= MAX_OPEN_REMINDERS_PER_CONTACT) {
+      return { scheduled: false, error: "Too many upcoming reminders for this person." };
+    }
+    // A daily cap on created reminders, whatever their state, so fired
+    // reminders do not free slots for an unbounded stream of texts.
+    const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    const today = await ctx.db.query("Reminder", {
+      contactId: args.contactId,
+      createdAt: { $gte: since },
+      $limit: MAX_REMINDERS_PER_CONTACT_PER_DAY + 1,
+    });
+    if (today.filter((r) => !r.demo).length >= MAX_REMINDERS_PER_CONTACT_PER_DAY) {
+      return { scheduled: false, error: "This person has reached today's reminder limit." };
+    }
+    const id = await ctx.db.insert("Reminder", {
+      contactId: args.contactId,
+      conversationId: args.conversationId,
+      text,
+      dueAt: time.dueAt,
+      status: "scheduled",
+      createdAt: new Date().toISOString(),
+    });
+    await ctx.scheduler.runAt(time.dueMs, "fireReminder", { reminderId: id });
+    return { scheduled: true, id, dueAt: time.dueAt };
+  },
+});

package/templates/imessage/functions/updateSettings.ts

@@ -0,0 +1,48 @@
+import { mutation, v } from "@pylonsync/functions";
+import { ensureSettings } from "../lib/store";
+
+function validTimezone(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Owner settings. Owner only.
+export default mutation({
+  auth: "admin",
+  args: {
+    ownerName: v.optional(v.string()),
+    timezone: v.optional(v.string()),
+    unknownSenderPolicy: v.optional(v.union(v.literal("ignore"), v.literal("reply_once"))),
+    unknownSenderReply: v.optional(v.string()),
+    rateLimitPerHour: v.optional(v.int()),
+    paused: v.optional(v.boolean()),
+  },
+  async handler(ctx, args) {
+    const settings = await ensureSettings(ctx);
+    const patch: Record<string, unknown> = { updatedAt: new Date().toISOString() };
+    if (args.ownerName !== undefined) patch.ownerName = args.ownerName.trim().slice(0, 80);
+    if (args.timezone !== undefined) {
+      if (!validTimezone(args.timezone)) throw ctx.error("INVALID_ARGS", "Unknown timezone");
+      patch.timezone = args.timezone;
+    }
+    if (args.unknownSenderPolicy !== undefined) patch.unknownSenderPolicy = args.unknownSenderPolicy;
+    if (args.unknownSenderReply !== undefined) {
+      const reply = args.unknownSenderReply.trim().slice(0, 320);
+      if (reply === "") throw ctx.error("INVALID_ARGS", "The reply to unknown senders cannot be empty");
+      patch.unknownSenderReply = reply;
+    }
+    if (args.rateLimitPerHour !== undefined) {
+      if (args.rateLimitPerHour < 1 || args.rateLimitPerHour > 500) {
+        throw ctx.error("INVALID_ARGS", "The hourly limit must be between 1 and 500");
+      }
+      patch.rateLimitPerHour = args.rateLimitPerHour;
+    }
+    if (args.paused !== undefined) patch.paused = args.paused;
+    await ctx.db.update("Settings", String(settings.id), patch);
+    return { ok: true };
+  },
+});

package/templates/imessage/gitignore

@@ -0,0 +1,11 @@
+node_modules/
+.pylon/
+pylon.manifest.json
+pylon.client.ts
+web/dist/
+dist/
+*.db
+*.db-*
+.env
+.env.local
+.DS_Store