@pylonsync/create-pylon 0.19.0 → 0.20.0

package/templates/imessage/README.md

@@ -0,0 +1,187 @@
+# __APP_NAME__
+
+An AI assistant people text over iMessage, built on Pylon. You choose who it
+answers; everything it says and does shows up live in your dashboard.
+
+```bash
+cp .env.example .env     # set PYLON_ADMIN_EMAILS, a model key, and a transport
+bun install
+bun run dev              # http://localhost:4321
+```
+
+Sign in at `/login` with the email in `PYLON_ADMIN_EMAILS`. In `pylon dev` the
+six-digit code appears on the page; in production it is emailed.
+
+`pylon dev` never sends texts: replies are stored and marked "Dry run". A dev
+server listens on your local network and returns sign-in codes in its
+responses, so anyone on the network who knows your email could sign in as you.
+Set `IMESSAGE_ALLOW_DEV_SENDS=1` only on a network you trust. The dashboard
+opens with three sample threads (marked "Sample"); remove them from Setup once
+real texts arrive.
+
+## How it works
+
+```
+ iPhone ──iMessage──▶ Sendblue ──webhook──────────▶ sendblueWebhook ─┐
+                      your Mac (relay/) ──relaySync─▶ relaySync ──────┤
+                                                                      ▼
+                     ingestInbound: dedupe → allowlist → rate limit → store
+                                                                      │
+                                              processTurn (job) ◀─────┘
+                                                   │  runs agent() as the owner
+                                                   ▼
+                     assistant: history + tools (notes, reminders)
+                                                   │
+                     reply → split into bubbles → queued → transport → iPhone
+```
+
+- **Transports** (`lib/transport.ts`). One `MessageTransport` interface, two
+  adapters. `IMESSAGE_TRANSPORT=sendblue` uses Sendblue's API
+  (`lib/sendblue.ts`). `IMESSAGE_TRANSPORT=relay` uses the Bun script in
+  `relay/` on a Mac you own.
+- **Allowlist** (`lib/gate.ts`). Only contacts marked Allowed get answers.
+  Anyone else is stored under Requests and ignored, or gets one fixed reply if
+  you turn that on. Blocked contacts are never answered. STOP and START work
+  for everyone.
+- **Rate limit.** Each contact gets at most N answered texts per rolling hour
+  (Setup, default 30). A number that is not on the allowlist can store at most
+  20 texts per hour, and at most 50 new numbers are stored per hour; the rest
+  are dropped. STOP and START confirmations go out at most once a day each.
+  The assistant can create at most 10 reminders per contact per day, each at
+  least five minutes out, and none fire while the assistant is paused.
+- **The agent** (`functions/assistant.ts`) is Pylon's `agent()`: the tool loop,
+  the transcript in the synced `AgentRun`/`AgentMessage` entities, and token
+  streaming come from the framework. One run per conversation holds its
+  history; after 80 turns a new run starts with the last few texts as context.
+- **Tools.** `remember_note`, `recall_notes`, `forget_note`, `set_reminder`,
+  `list_reminders`, `cancel_reminder`. They act only on the person being
+  answered: the contact comes from the server (`functions/resolveTurn.ts`),
+  never from the model. Reminders run on Pylon's job scheduler
+  (`ctx.scheduler.runAt` → `functions/fireReminder.ts`).
+- **Replies** are converted from Markdown to plain text and split into up to
+  four bubbles along paragraph breaks (`lib/chunk.ts`).
+- **Dashboard.** Owner-only. Every entity policy is `auth.isAdmin`, and the
+  owner is the account whose verified email is in `PYLON_ADMIN_EMAILS`.
+  Anonymous visitors and other accounts read nothing.
+
+### Why the server calls itself
+
+`agent()` stores each run under the signed-in user who called it. A webhook
+has no user, so `processTurn` opens a session for the owner
+(`POST /api/auth/session`) and calls `/api/fn/assistant` over HTTP
+(`lib/agent-call.ts`). The session token stays in server memory. In
+`pylon dev` this needs nothing. In production set `PYLON_ADMIN_TOKEN` (only the
+server uses it, to open that session). The call goes to `127.0.0.1:$PYLON_PORT`
+when the port is known, otherwise to `APP_URL`, which must be https.
+
+## Transport 1: Sendblue
+
+No Mac needed. Sendblue hosts the iMessage line.
+
+1. Create an account and a number at [dashboard.sendblue.com](https://dashboard.sendblue.com).
+2. Set in `.env` (or `pylon secrets set` on Stack0 Cloud):
+   ```
+   IMESSAGE_TRANSPORT=sendblue
+   SENDBLUE_API_KEY=...
+   SENDBLUE_API_SECRET=...
+   SENDBLUE_FROM_NUMBER=+15125550100
+   SENDBLUE_WEBHOOK_SECRET=<openssl rand -hex 32>
+   ```
+3. In Sendblue, set the receive webhook to
+   `https://<your app>/api/webhooks/sendblueWebhook` with the same secret.
+   Sendblue sends it back in the `sb-signing-secret` header on every delivery;
+   the webhook compares it in constant time and rejects anything else. Because
+   that secret is not bound to the body, Sendblue's `message_handle` is also
+   stored as a unique key, so a replayed or retried delivery is stored once.
+4. Add your own number on the Allowlist page and text the Sendblue number.
+
+## Transport 2: Mac relay
+
+Uses your Mac and Apple ID. The relay reads new messages from Messages'
+database and sends replies through Messages.app.
+
+1. On the server: `IMESSAGE_TRANSPORT=relay` and `RELAY_TOKEN=<openssl rand -hex 32>`.
+2. On a Mac that stays on and is signed in to Messages, copy this project and
+   run `bun install`. Create `relay/.env` from `relay/.env.example`:
+   ```
+   PYLON_URL=https://<your app>
+   RELAY_TOKEN=<same value as the server>
+   ```
+3. **Full Disk Access.** System Settings → Privacy & Security → Full Disk
+   Access → add the app that runs the relay (Terminal, iTerm, or the `bun`
+   binary if you run it under launchd). The relay opens
+   `~/Library/Messages/chat.db` read-only and never writes to it.
+4. **Automation.** Start it with `bun run relay`. The first reply makes macOS
+   ask whether it may control Messages; allow it. You can change this later
+   under Privacy & Security → Automation.
+5. Keep it running. With launchd, a `~/Library/LaunchAgents` plist that runs
+   `bun relay/main.ts` from the project directory with `KeepAlive` works well.
+
+`RELAY_TOKEN` is as sensitive as your Apple ID: whoever holds it can post
+texts as any sender and read every reply waiting to go out. Keep it only in
+the server environment and in `relay/.env` on the Mac.
+
+The relay forwards every one-to-one text your Apple ID receives, including
+texts from numbers not on the allowlist (for example sign-in codes from
+services that text from a full phone number). They are stored under Requests
+and never answered. Short-code senders are dropped.
+
+How the relay works (`relay/main.ts`):
+
+- It starts at the newest message, so your existing history is never sent to
+  the server. Its position (a chat.db ROWID) is saved in
+  `~/.pylon-imessage-relay/state.json` and only advances past messages the
+  server accepted.
+- Every `POLL_MS` (default 3s, minimum 2.5s) it makes one call to `/api/fn/relaySync` with
+  `Authorization: Bearer <RELAY_TOKEN>`: new messages in, acks for sent replies,
+  and the next replies to send back. The server compares the token in constant
+  time.
+- Group chats, your own messages, and reactions are skipped. Messages that
+  macOS stores only in `attributedBody` (common since macOS 13) are decoded.
+- Replies are sent with `osascript`. The message text and the recipient are
+  passed as arguments to a fixed AppleScript (`on run argv`), never inserted
+  into script source, so a message cannot change what the script does.
+- A reply is recorded as sent on disk before it is acknowledged, so a crash
+  does not send it twice. Unacknowledged replies return to the queue after 60
+  seconds and are marked failed after 5 attempts.
+
+## Environment
+
+| Variable | Needed for |
+|---|---|
+| `PYLON_ADMIN_EMAILS` | The owner's email. Required. |
+| `ANTHROPIC_API_KEY` (or `PYLON_LLM_PROVIDER=openai` + `OPENAI_API_KEY`) | Replies. Without it texts are stored and marked "waiting for setup". The model id is `ASSISTANT_MODEL` in `lib/assistant.ts`. |
+| `IMESSAGE_TRANSPORT` | `sendblue` or `relay`. |
+| `SENDBLUE_*` | The Sendblue transport. |
+| `RELAY_TOKEN` | The relay transport. At least 24 characters. |
+| `IMESSAGE_DRY_RUN=1` | Store replies without sending them (both transports). Always on in `pylon dev` unless `IMESSAGE_ALLOW_DEV_SENDS=1`. |
+| `PYLON_ADMIN_TOKEN`, `APP_URL` | Production: how the server reaches its own API to run the agent. `APP_URL` must be https and is used only when `PYLON_PORT` is not set. |
+
+The Setup page shows which of these are set (never their values), when the
+last text came in, and when the relay last checked in.
+
+## Tests
+
+```bash
+bun test tests
+```
+
+Covers webhook verification (valid, wrong, missing, unconfigured secret),
+idempotency, the allowlist and rate limit, STOP/START, relay token auth,
+AppleScript argument passing (including a real `osascript` echo run on macOS
+with quotes, backslashes, newlines, and unicode), the chat.db reader against a
+fixture database built in a temp directory, the agent call over SSE, and
+reply chunking. Nothing in the suite sends a message or calls Sendblue.
+
+## Deploy
+
+```bash
+pylon deploy
+pylon secrets set PYLON_ADMIN_EMAILS=you@example.com ANTHROPIC_API_KEY=... \
+  IMESSAGE_TRANSPORT=sendblue SENDBLUE_API_KEY=... SENDBLUE_API_SECRET=... \
+  SENDBLUE_FROM_NUMBER=+1... SENDBLUE_WEBHOOK_SECRET=... \
+  APP_URL=https://<your app> PYLON_ADMIN_TOKEN=<openssl rand -hex 32>
+```
+
+Sign-in codes in production need an email provider (`PYLON_EMAIL_PROVIDER`);
+Stack0 Cloud has one configured.

package/templates/imessage/app/console.tsx

@@ -0,0 +1,382 @@
+"use client";
+
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { callFn, db, useRouter } from "@pylonsync/react";
+import { useAuth } from "@pylonsync/client";
+import { ContactPanel, type PanelActivity } from "@/components/contact-panel";
+import { ContactsView, type ContactRowView } from "@/components/contacts-view";
+import { ConversationList, type ConversationSummary } from "@/components/conversation-list";
+import { NavRail, type View } from "@/components/nav-rail";
+import { setupIssueCount, SetupView, type SetupStatus, type SettingsView, type TransportStateView } from "@/components/setup-view";
+import { Thread, type Notice } from "@/components/thread";
+import { describeToolCall, toolRefusal, type ThreadMessage } from "@/lib/format";
+import { DEFAULT_SETTINGS } from "@/lib/gate";
+import { cn } from "@/lib/utils";
+
+interface ContactRow {
+  id: string;
+  handle: string;
+  displayName?: string | null;
+  status: string;
+  optedOut?: boolean | null;
+  lastMessageAt?: string | null;
+  demo?: boolean | null;
+}
+interface ConversationRow {
+  id: string;
+  contactId: string;
+  handle: string;
+  lastMessageAt?: string | null;
+  lastPreview?: string | null;
+  agentRunId?: string | null;
+  turnState?: string | null;
+  lastError?: string | null;
+  demo?: boolean | null;
+}
+interface MessageRow extends ThreadMessage {
+  conversationId: string;
+}
+interface NoteRow {
+  id: string;
+  contactId: string;
+  text: string;
+  createdAt: string;
+}
+interface ReminderRow {
+  id: string;
+  contactId: string;
+  text: string;
+  dueAt: string;
+  status: string;
+}
+interface AgentRunRow {
+  id: string;
+  status: string;
+  steps?: number | null;
+  error?: string | null;
+  updatedAt: string;
+  title?: string | null;
+}
+interface AgentMessageRow {
+  id: string;
+  runId: string;
+  role: string;
+  content: unknown;
+  createdAt: string;
+}
+interface SettingsRow extends Partial<SettingsView> {
+  id: string;
+  key: string;
+}
+
+const UNANSWERED = new Set(["awaiting_setup", "failed", "rate_limited"]);
+
+function errorMessage(err: unknown): string {
+  if (err && typeof err === "object" && "message" in err) return String((err as { message: unknown }).message);
+  return "Something went wrong";
+}
+
+/**
+ * The dashboard, and the only module that touches `db` / `callFn`. Every
+ * `db.useQuery` below is a live subscription: a text that arrives through the
+ * webhook or the relay shows up in the list and the open thread without a
+ * reload, and so does the assistant's reply.
+ */
+export function Console({ view, initialConversationId }: { view: View; initialConversationId: string | null }) {
+  const router = useRouter();
+  const { signOut } = useAuth();
+  const { data: contacts } = db.useQuery<ContactRow>("Contact");
+  const { data: conversations, loading } = db.useQuery<ConversationRow>("Conversation");
+  const { data: messages } = db.useQuery<MessageRow>("Message");
+  const { data: notes } = db.useQuery<NoteRow>("Note");
+  const { data: reminders } = db.useQuery<ReminderRow>("Reminder");
+  const { data: runs } = db.useQuery<AgentRunRow>("AgentRun");
+  const { data: agentMessages } = db.useQuery<AgentMessageRow>("AgentMessage");
+  const { data: settingsRows } = db.useQuery<SettingsRow>("Settings");
+  const { data: transportRows } = db.useQuery<TransportStateView & { id: string }>("TransportState");
+
+  const [status, setStatus] = useState<SetupStatus | null>(null);
+  const [selectedId, setSelectedId] = useState<string | null>(initialConversationId);
+  const [query, setQuery] = useState("");
+  const [detailsOpen, setDetailsOpen] = useState(false);
+  const [toast, setToast] = useState<string | null>(null);
+  const seeded = useRef(false);
+
+  useEffect(() => {
+    callFn<SetupStatus>("setupStatus", {}).then(setStatus, () => setStatus(null));
+  }, []);
+
+  // A fresh install gets the sample threads once, so the dashboard never opens empty.
+  useEffect(() => {
+    if (loading || seeded.current) return;
+    seeded.current = true;
+    if ((conversations ?? []).length > 0) return;
+    callFn("seedDemo", {}).catch(() => {
+      seeded.current = false;
+    });
+  }, [loading, conversations]);
+
+  const contactById = useMemo(() => new Map((contacts ?? []).map((c) => [c.id, c] as const)), [contacts]);
+
+  const summaries: ConversationSummary[] = useMemo(() => {
+    const unansweredByConversation = new Map<string, number>();
+    for (const m of messages ?? []) {
+      if (m.direction === "in" && UNANSWERED.has(m.status)) {
+        unansweredByConversation.set(m.conversationId, (unansweredByConversation.get(m.conversationId) ?? 0) + 1);
+      }
+    }
+    const q = query.trim().toLowerCase();
+    return (conversations ?? [])
+      .map((c) => {
+        const contact = contactById.get(c.contactId);
+        const status = (contact?.status ?? "unknown") as ConversationSummary["status"];
+        return {
+          id: c.id,
+          name: contact?.displayName ?? null,
+          handle: c.handle,
+          preview: c.lastPreview ?? "",
+          lastMessageAt: c.lastMessageAt ?? null,
+          status,
+          thinking: c.turnState === "running",
+          needsAttention: status === "allowed" && (unansweredByConversation.get(c.id) ?? 0) > 0,
+          demo: Boolean(c.demo),
+        };
+      })
+      .filter((c) => !q || (c.name ?? "").toLowerCase().includes(q) || c.handle.includes(q) || c.preview.toLowerCase().includes(q))
+      .sort((a, b) => ((a.lastMessageAt ?? "") < (b.lastMessageAt ?? "") ? 1 : -1));
+  }, [conversations, contactById, messages, query]);
+
+  // Desktop opens the newest conversation; phones start on the list.
+  useEffect(() => {
+    if (view !== "messages" || selectedId || summaries.length === 0) return;
+    if (typeof window !== "undefined" && window.matchMedia("(min-width: 768px)").matches) {
+      setSelectedId(summaries[0].id);
+    }
+  }, [view, selectedId, summaries]);
+
+  function select(id: string | null) {
+    setSelectedId(id);
+    setDetailsOpen(false);
+    // Keep the URL shareable without a navigation round trip.
+    window.history.replaceState(null, "", id ? `/?c=${encodeURIComponent(id)}` : "/");
+  }
+
+  async function run<T>(fn: string, args: Record<string, unknown>): Promise<T> {
+    try {
+      return await callFn<T>(fn, args);
+    } catch (err) {
+      const message = errorMessage(err);
+      setToast(message);
+      setTimeout(() => setToast(null), 4000);
+      throw new Error(message);
+    }
+  }
+
+  const settingsRow = (settingsRows ?? []).find((s) => s.key === "main");
+  const settings: SettingsView = {
+    ownerName: settingsRow?.ownerName ?? "",
+    timezone: settingsRow?.timezone ?? DEFAULT_SETTINGS.timezone,
+    unknownSenderPolicy: settingsRow?.unknownSenderPolicy ?? DEFAULT_SETTINGS.unknownSenderPolicy,
+    unknownSenderReply: settingsRow?.unknownSenderReply ?? DEFAULT_SETTINGS.unknownSenderReply,
+    rateLimitPerHour: settingsRow?.rateLimitPerHour ?? DEFAULT_SETTINGS.rateLimitPerHour,
+    paused: Boolean(settingsRow?.paused),
+  };
+  const transport = (transportRows ?? []).find((t) => t.name === status?.transport) ?? null;
+  const requests = (contacts ?? []).filter((c) => c.status === "unknown").length;
+
+  const nav = (
+    <NavRail
+      view={view}
+      setupIssues={setupIssueCount(status)}
+      requests={requests}
+      onSignOut={() => {
+        void signOut();
+        window.location.assign("/login");
+      }}
+    />
+  );
+
+  let body: React.ReactNode;
+  if (view === "contacts") {
+    const rows: ContactRowView[] = (contacts ?? [])
+      .map((c) => ({
+        id: c.id,
+        name: c.displayName ?? null,
+        handle: c.handle,
+        status: (c.status ?? "unknown") as ContactRowView["status"],
+        optedOut: Boolean(c.optedOut),
+        lastMessageAt: c.lastMessageAt ?? null,
+        demo: Boolean(c.demo),
+      }))
+      .sort((a, b) => ((a.lastMessageAt ?? "") < (b.lastMessageAt ?? "") ? 1 : -1));
+    body = (
+      <ContactsView
+        contacts={rows}
+        onAdd={async (handle, name) => {
+          await run("saveContact", { handle, displayName: name, status: "allowed" });
+        }}
+        onStatus={(id, s) => void run("setContactStatus", { contactId: id, status: s }).catch(() => {})}
+        onOpen={(contactId) => {
+          const conv = (conversations ?? []).find((c) => c.contactId === contactId);
+          router.push(conv ? `/?c=${encodeURIComponent(conv.id)}` : "/");
+        }}
+      />
+    );
+  } else if (view === "setup") {
+    body = (
+      <SetupView
+        status={status}
+        transport={transport}
+        settings={settings}
+        hasDemo={(conversations ?? []).some((c) => c.demo)}
+        onSaveSettings={async (patch) => {
+          await run("updateSettings", patch);
+        }}
+        onClearDemo={async () => {
+          await run("clearDemo", {});
+        }}
+      />
+    );
+  } else {
+    const conversation = (conversations ?? []).find((c) => c.id === selectedId) ?? null;
+    const contact = conversation ? contactById.get(conversation.contactId) : undefined;
+    const threadMessages = conversation ? (messages ?? []).filter((m) => m.conversationId === conversation.id) : [];
+    const unanswered = threadMessages.filter((m) => m.direction === "in" && UNANSWERED.has(m.status)).length;
+    const runRow = conversation ? (runs ?? []).find((r) => r.id === conversation.agentRunId || r.title === conversation.id) : undefined;
+    const activity: PanelActivity[] = [];
+    if (conversation) {
+      const runIds = new Set((runs ?? []).filter((r) => r.title === conversation.id).map((r) => r.id));
+      const refusals = new Map<string, string | null>();
+      for (const m of agentMessages ?? []) {
+        if (!runIds.has(m.runId) || m.role !== "user" || !Array.isArray(m.content)) continue;
+        for (const block of m.content as { type?: string; tool_use_id?: string; content?: unknown; is_error?: boolean }[]) {
+          if (block.type === "tool_result" && block.tool_use_id) {
+            refusals.set(block.tool_use_id, toolRefusal(block.content, block.is_error === true));
+          }
+        }
+      }
+      for (const m of agentMessages ?? []) {
+        if (!runIds.has(m.runId) || m.role !== "assistant" || !Array.isArray(m.content)) continue;
+        for (const block of m.content as { type?: string; id?: string; name?: string; input?: Record<string, unknown> }[]) {
+          if (block.type === "tool_use" && block.name) {
+            const refused = block.id ? refusals.get(block.id) : null;
+            const label = describeToolCall(block.name, block.input ?? {});
+            activity.push({
+              id: block.id ?? `${m.id}-${activity.length}`,
+              label: refused ? `Refused: ${label.charAt(0).toLowerCase()}${label.slice(1)}. ${refused}` : label,
+              at: m.createdAt,
+            });
+          }
+        }
+      }
+      activity.sort((a, b) => (a.at < b.at ? 1 : -1)).splice(8);
+    }
+
+    let notice: Notice | null = null;
+    if (conversation && contact) {
+      if (status && !status.transport) {
+        notice = { tone: "warn", title: "No transport", body: <>Set IMESSAGE_TRANSPORT to sendblue or relay. See Setup.</> };
+      } else if (status && !status.provider.configured && contact.status === "allowed") {
+        notice = {
+          tone: "warn",
+          title: "Replies are off",
+          body: <>No model key is set, so new texts wait here unanswered. Add ANTHROPIC_API_KEY to the server environment, then answer them from the contact details.</>,
+        };
+      } else if (settings.paused && contact.status === "allowed") {
+        notice = { tone: "muted", title: "Assistant paused", body: <>Texts are stored. Turn replies back on in Setup.</> };
+      } else if (conversation.lastError && unanswered > 0) {
+        notice = { tone: "warn", title: "Last reply failed", body: conversation.lastError };
+      }
+    }
+
+    const panel = (onClose?: () => void) =>
+      conversation && contact ? (
+        <ContactPanel
+          name={contact.displayName ?? null}
+          handle={contact.handle}
+          status={(contact.status ?? "unknown") as "allowed" | "unknown" | "blocked"}
+          optedOut={Boolean(contact.optedOut)}
+          unanswered={unanswered}
+          notes={(notes ?? []).filter((n) => n.contactId === contact.id).sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))}
+          reminders={(reminders ?? [])
+            .filter((r) => r.contactId === contact.id && r.status !== "cancelled")
+            .sort((a, b) => (a.dueAt < b.dueAt ? -1 : 1))}
+          run={runRow ? { status: runRow.status, steps: Number(runRow.steps) || 0, updatedAt: runRow.updatedAt, error: runRow.error ?? null } : null}
+          activity={activity}
+          onClose={onClose}
+          onStatus={(s) => void run("setContactStatus", { contactId: contact.id, status: s }).catch(() => {})}
+          onRename={(name) =>
+            void run("saveContact", { handle: contact.handle, displayName: name, status: contact.status }).catch(() => {})
+          }
+          onAnswerNow={() => void run("answerNow", { conversationId: conversation.id }).catch(() => {})}
+          onDeleteNote={(id) => void run("deleteNote", { noteId: id }).catch(() => {})}
+          onCancelReminder={(id) => void run("cancelReminder", { reminderId: id }).catch(() => {})}
+        />
+      ) : null;
+
+    body = (
+      <div className="flex h-full min-h-0">
+        <div
+          className={cn(
+            "h-full min-h-0 w-full flex-col border-r bg-rail/50 pt-3 md:flex md:w-[320px] md:shrink-0",
+            conversation ? "hidden" : "flex",
+          )}
+        >
+          <div className="flex items-baseline justify-between px-4 pb-2">
+            <h1 className="text-[22px] font-semibold tracking-[-0.025em]">Messages</h1>
+            <span className="text-[12px] text-muted-foreground">{summaries.length} threads</span>
+          </div>
+          <ConversationList conversations={summaries} selectedId={selectedId} query={query} onQuery={setQuery} onSelect={select} />
+        </div>
+        {conversation && contact ? (
+          <>
+            <div className="h-full min-h-0 min-w-0 flex-1">
+              <Thread
+                key={conversation.id}
+                contact={{
+                  name: contact.displayName ?? null,
+                  handle: contact.handle,
+                  status: (contact.status ?? "unknown") as "allowed" | "unknown" | "blocked",
+                  optedOut: Boolean(contact.optedOut),
+                }}
+                messages={threadMessages}
+                thinking={conversation.turnState === "running"}
+                notice={notice}
+                demo={Boolean(conversation.demo)}
+                onBack={() => select(null)}
+                onToggleDetails={() => setDetailsOpen((o) => !o)}
+                onSend={async (text) => {
+                  await run("sendOwnerMessage", { conversationId: conversation.id, text });
+                }}
+              />
+            </div>
+            <div className="hidden h-full w-[300px] shrink-0 border-l xl:block">{panel()}</div>
+            {detailsOpen ? (
+              <div className="fixed inset-0 z-30 flex justify-end bg-black/20 xl:hidden" onClick={() => setDetailsOpen(false)}>
+                <div className="h-full w-[min(340px,92vw)] bg-background shadow-2xl" onClick={(e) => e.stopPropagation()}>
+                  {panel(() => setDetailsOpen(false))}
+                </div>
+              </div>
+            ) : null}
+          </>
+        ) : (
+          <div className="hidden flex-1 items-center justify-center bg-background text-[14px] text-muted-foreground md:flex">
+            {loading ? "Loading…" : summaries.length ? "Select a conversation." : "No conversations yet."}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex h-[100dvh] flex-col overflow-hidden md:flex-row">
+      {nav}
+      <main className="min-h-0 min-w-0 flex-1">{body}</main>
+      {toast ? (
+        <div role="alert" className="fixed bottom-20 left-1/2 z-40 -translate-x-1/2 rounded-full bg-foreground px-4 py-2 text-[13px] text-background shadow-lg md:bottom-6">
+          {toast}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/templates/imessage/app/contacts/page.tsx

@@ -0,0 +1,13 @@
+import React from "react";
+import type { Metadata, PageProps } from "@pylonsync/react";
+import { Console } from "../console";
+import { ownerGate } from "../gate";
+
+export const metadata: Metadata = { title: "Allowlist", robots: "noindex" };
+
+// `/contacts` — who the assistant answers.
+export default function ContactsPage({ auth, response }: PageProps) {
+  const blocked = ownerGate({ auth, response });
+  if (blocked) return blocked;
+  return <Console view="contacts" initialConversationId={null} />;
+}

package/templates/imessage/app/error.tsx

@@ -0,0 +1,16 @@
+"use client";
+
+import React from "react";
+import type { ErrorBoundaryProps } from "@pylonsync/react";
+
+export default function ErrorPage({ error, reset }: ErrorBoundaryProps) {
+  return (
+    <main className="flex min-h-[100dvh] flex-col items-center justify-center gap-3 px-4 text-center">
+      <h1 className="text-[22px] font-semibold tracking-[-0.02em]">Something went wrong</h1>
+      <p className="max-w-[48ch] text-[14px] text-muted-foreground">{error.message}</p>
+      <button type="button" onClick={reset} className="rounded-full bg-foreground px-5 py-2 text-[13px] font-medium text-background">
+        Try again
+      </button>
+    </main>
+  );
+}

package/templates/imessage/app/gate.tsx

@@ -0,0 +1,31 @@
+import React from "react";
+import type { PageProps } from "@pylonsync/react";
+import { SignOutAndRetry } from "./sign-out";
+
+/**
+ * Server-side gate shared by the dashboard pages. Anonymous visitors and guest
+ * sessions go to /login. A signed-in account that is not the owner (not an
+ * admin via PYLON_ADMIN_EMAILS) gets an explanation and no data: every entity
+ * policy denies non-admins as well, so this is presentation, not the fence.
+ */
+export function ownerGate({ auth, response }: Pick<PageProps, "auth" | "response">): React.ReactNode | null {
+  if (!auth.user_id || auth.user_id.startsWith("guest_")) {
+    response.redirect("/login");
+    return <></>;
+  }
+  if (!auth.is_admin) {
+    return (
+      <main className="flex min-h-[100dvh] items-center justify-center px-4">
+        <div className="max-w-[420px] text-center">
+          <h1 className="text-[22px] font-semibold tracking-[-0.02em]">This dashboard belongs to its owner</h1>
+          <p className="mt-2 text-[14px] leading-relaxed text-muted-foreground">
+            You are signed in, but your email is not the owner email set in PYLON_ADMIN_EMAILS on this server, or it has
+            not been verified with a sign-in code yet.
+          </p>
+          <SignOutAndRetry />
+        </div>
+      </main>
+    );
+  }
+  return null;
+}