Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

<p align="center"> <img width="128" height="128" alt="BELL" src="https://github.com/user-attachments/assets/f4c9363d-2ab0-4205-a3c7-7d7ad61ec6c6"/></p>

[BELL](https://www.browserbase.com/blog/bell-personal-assistant-stack) is a reference architecture and sample app for running your own personal assistant. It combines browser automation, messaging, personal memory, and payments.
[BELL](https://www.browserbase.com/blog/bell-personal-assistant-stack) is a reference architecture and sample app for running your own personal assistant. It combines browser automation, messaging, personal memory, scheduled reminders, and payments.

- Browserbase: Browser + Stagehand
- Eve by Vercel: Agent Framework
Expand Down Expand Up @@ -38,7 +38,7 @@ pnpm dev
| Integration | What it does | Guide |
| --- | --- | --- |
| Browserbase + Stagehand | Browser sessions, automation, saved Contexts, and human handoff | [Browser runtime](docs/browser-runtime.md) |
| Eve by Vercel | Agent configuration, tools, conversation state, and channels | [Eve in Bell](docs/repository.md#eve-by-vercel) |
| Eve by Vercel | Agent configuration, tools, conversation state, channels, and schedules | [Eve in Bell](docs/repository.md#eve-by-vercel) · [Reminders](docs/reminders.md) |
| Notion | Preferences, personal plans, and everyday task history across conversations | [Memory setup](docs/notion.md) |
| Parallel | Public-web research and persistent watches with configurable frequency | Set `PARALLEL_API_KEY` in `.env`; [watch setup](docs/monitors.md) |
| Linq | iMessage and SMS through a signed webhook and sender allowlist | [Messaging setup](docs/linq.md) |
Expand Down
9 changes: 6 additions & 3 deletions agent/channels/linq.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { linqBrowserEvents, requiredEnvironmentValue } from "../lib/linq";
import { linqBrowserEvents, localTimezone, requiredEnvironmentValue } from "../lib/linq";
import { defaultLinqAuth, linqChannel, type LinqChannelConfig } from "eve/channels/linq";
import { z } from "zod";

Expand Down Expand Up @@ -40,12 +40,15 @@ export default linqChannel({
if (!isAllowedBellMessage(message)) return null;
const auth = defaultLinqAuth(message);
const incoming = inboundMessage.parse(message.raw);
const timezone = localTimezone();
return {
auth: { ...auth, attributes: { ...auth.attributes, bell_watch_chat: incoming.chat.id, bell_watch_sender: incoming.sender_handle.handle, bell_watch_line: incoming.chat.owner_handle.handle } },
auth: { ...auth, attributes: { ...auth.attributes, bell_timezone: timezone, bell_watch_chat: incoming.chat.id, bell_watch_sender: incoming.sender_handle.handle, bell_watch_line: incoming.chat.owner_handle.handle } },
context: [
"This request arrived through Bell's private Linq iMessage or SMS channel. "
+ "Reply concisely in this chat. Use the same browser for follow-up requests. "
+ "For a human-only step, send the human_handoff tool's link and wait for a reply.",
+ "For a human-only step, send the human_handoff tool's link and wait for a reply. "
+ `The default local timezone is ${timezone}; current time is ${new Date().toISOString()}. `
+ "Use the user's saved timezone preference when available, otherwise this default. Do not ask for their timezone.",
],
};
},
Expand Down
12 changes: 8 additions & 4 deletions agent/connections/notion.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,23 @@ export default defineDynamic({
if (auth?.principalType !== "user" || !["bell:operator", "linq"].includes(auth.issuer ?? "")) return null;
const principal = { type: "user" as const, id: auth.principalId, issuer: auth.issuer };
const owner = notionOwner(principal);
const scheduled = ctx.session.schedule !== undefined;
const readTools = [
"notion-search", "notion-fetch", "notion-memory-search", "notion-get-self",
"notion-get-tool-access", "notion-query-data-sources", "notion-get-async-task",
];
return defineMcpClientConnection({
url: notionEndpoint,
instanceKey: owner,
description: "Notion: the user's personal preferences, routines, plans, decisions, and notes across conversations. Search before relying on remembered information.",
protocolVersionDiscovery: false,
auth: notionAuth,
tools: { allow: [
"notion-search", "notion-fetch", "notion-memory-search", "notion-get-self",
"notion-get-tool-access", "notion-query-data-sources",
tools: { allow: scheduled ? readTools : [...readTools,
"notion-create-pages", "notion-update-page", "notion-create-database", "notion-update-data-source",
"notion-get-async-task", "notion-delete-pages",
"notion-delete-pages",
] },
approval: async ({ toolName }) => {
if (scheduled && /__notion-(?:create|update|delete)-/.test(toolName)) return "denied";
if (toolName.startsWith("notion__") && (await safeNotion(() => getNotionOAuth().status(principal))).status !== "connected")
return "denied";
return /__(?:notion-create-database|notion-update-data-source|notion-delete-pages)$/.test(toolName)
Expand Down
22 changes: 22 additions & 0 deletions agent/instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,28 @@ before relying on personal context or saving records. Use `notion_status` for st
and `notion_disconnect` to revoke the grant with Eve confirmation. If Notion is unavailable,
continue independent work and report any unsaved record separately.

The morning schedule asks Bell for an 8:30 AM Notion update in existing private Linq chats
whose sender is allowlisted and has Notion connected.
Reply directly in the Linq chat, just as you would answer an incoming message.
Use `schedule__reminders__create` for user-requested reminders and recurring tasks.
For a reminder, notify the user; do not perform the action being reminded about.
The schedule tools manage these user-created tasks; they do not change the fixed morning job.
Do not create recurring messages just because Notion contains a deadline or routine.

Resolve timing from the user's explicit choice or saved Notion timezone preference,
otherwise the channel's local timezone. Do not ask for a timezone or infer one from a
phone number. Use delay for relative reminders, single for one-time dates, and cron with
expression.timezone for recurring local times. Include the resolved timezone in the task.
Use the generated list/get/update/enable/disable/delete tools to manage reminders. Follow
pagination, use returned names, and check existing schedules before retrying creation.
Confirm changes only after the tool succeeds. Changing a Notion note does not change a schedule.

During a scheduled run, do the task and reply without asking questions or starting OAuth.
Use the creator's existing Notion connection and the notion-memory skill for fresh briefings.
Scheduled Notion access is read-only. Do not save memories, make purchases, or create new
commitments during these runs. Report access failures accurately. If a successful briefing
check finds nothing useful, call no_reply. Always deliver an explicit reminder when it is due.

For an explicit request to keep watching public information, use watch_create. Watches use Parallel lite and continue until stopped, independently of this conversation.
Honor an explicitly requested frequency using whole hours, days, or weeks between 1h and 30d.
When no frequency is specified, default to daily and say so. Never silently round an unsupported
Expand Down
4 changes: 4 additions & 0 deletions agent/lib/linq.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,7 @@ export function requiredEnvironmentValue(name: string): string {
if (!value) throw new Error(`${name} is required for the Linq channel.`);
return value;
}

export function localTimezone(): string {
return Intl.DateTimeFormat().resolvedOptions().timeZone;
}
37 changes: 37 additions & 0 deletions agent/schedules/morning.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
import { defineSchedule } from "eve/schedules";
import linq from "../channels/linq";
import { localTimezone } from "../lib/linq";
import { privateLinqRecipients } from "../../server/linq";
import { notionEnabled } from "../../server/notion/config";
import { getNotionOAuth } from "../../server/notion/oauth";

export default defineSchedule({
cron: "*/15 * * * *",
async run({ to }) {
if (!notionEnabled()) return;
const timezone = localTimezone();
const now = new Date();
const parts = new Intl.DateTimeFormat("en-GB", {
timeZone: timezone, hour: "2-digit", minute: "2-digit", hourCycle: "h23",
}).formatToParts(now);
const hour = Number(parts.find(part => part.type === "hour")?.value);
const minute = Number(parts.find(part => part.type === "minute")?.value);
if (hour !== 8 || minute < 30 || minute >= 45) return;

for (const { destination, principalId, subject } of await privateLinqRecipients()) {
if ((await getNotionOAuth().status({ type: "user", issuer: "linq", id: principalId })).status !== "connected") continue;
const chat = destination.chat;
await to(linq, { adapterName: "linq", threadId: `linq:${chat}` }).send(
"Give the user a short morning update. Use notion-memory to check their current priorities, "
+ "unfinished plans, and upcoming deadlines. Reply directly in this chat with useful source links. "
+ `It is ${now.toISOString()}; the local timezone is ${timezone}. `
+ "If there is nothing useful to share, call no_reply.",
{ auth: {
principalType: "user", authenticator: "linq-message", issuer: "linq", principalId,
subject,
attributes: { bell_timezone: timezone, bell_watch_chat: chat, bell_watch_sender: destination.sender, bell_watch_line: destination.line },
} },
);
}
},
});
45 changes: 45 additions & 0 deletions agent/schedules/reminders.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
import { defineDynamicSchedules } from "eve/experimental/schedules";
import { z } from "zod";
import linq from "../channels/linq";
import { localTimezone } from "../lib/linq";
import { allowed, destinationSchema } from "../../server/monitors/config";

const inputSchema = z.object({ task: z.string().trim().min(1).max(2_000) }).strict();
const savedSchema = inputSchema.extend({ destination: destinationSchema, timezone: z.string().optional() }).strict();

export default defineDynamicSchedules({
description: "Schedule one-time reminders or recurring tasks in your private Linq chat, requested by the user. "
+ "Use their local timezone from context or a saved preference without asking. Set expression.timezone for wall-clock times. "
+ "List existing schedules before retrying creation or making changes.",
inputSchema,
preparePayload(payload, { session }) {
const auth = session.auth.current;
if (auth?.principalType !== "user" || auth.authenticator !== "linq-message" || auth.issuer !== "linq")
throw new Error("Create reminders from your private Linq chat.");
const destination = destinationSchema.parse({
chat: auth.attributes.bell_watch_chat,
sender: auth.attributes.bell_watch_sender,
line: auth.attributes.bell_watch_line,
});
if (!allowed(destination)) throw new Error("This Linq sender or receiving line is no longer allowed.");
return { ...payload, destination, timezone: typeof auth.attributes.bell_timezone === "string" ? auth.attributes.bell_timezone : localTimezone() };
},
auth({ principal, payload }) {
const saved = savedSchema.safeParse(payload);
if (!saved.success || principal.type !== "user" || principal.authenticator !== "linq-message"
|| principal.issuer !== "linq" || !allowed(saved.data.destination)) return null;
const { destination } = saved.data;
return {
principalType: principal.type, authenticator: principal.authenticator,
issuer: principal.issuer, principalId: principal.principalId, subject: principal.subject,
attributes: { bell_timezone: saved.data.timezone ?? localTimezone(), bell_watch_chat: destination.chat, bell_watch_sender: destination.sender, bell_watch_line: destination.line },
};
},
async run({ payload, occurrence, to }) {
const { task, destination, timezone } = savedSchema.parse(payload);
await to(linq, { adapterName: "linq", threadId: `linq:${destination.chat}` }).send(
`Do this scheduled task now: ${task}\nScheduled for: ${occurrence.scheduledAt}. `
+ `Local timezone: ${timezone ?? localTimezone()}. Respect a timezone specified in the task.`,
);
},
});
14 changes: 14 additions & 0 deletions agent/skills/notion-memory/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,3 +148,17 @@ Report a Notion save failure separately from the outcome of the user's original

Share the verified Notion link when useful. Confirm reminders, monitors, and background
tasks through the tool that schedules them.

## Scheduled briefings

For a scheduled briefing, read the approved guide and current sources using the existing
memory lookup flow. Summarize useful unfinished priorities, plans, and approaching deadlines
with source links. Honor exclusions and skip completed or cancelled items. Reply directly
in the chat; if a successful check finds nothing useful, call `no_reply`. A failed read is
not an empty task list. Do not run setup, request authorization, save memories, or mark
anything complete. Use the schedule's local timezone to interpret dates.

The fixed morning job reuses the existing private Linq chat and its connected Notion account.
Create additional schedules only when the user asks, through `schedule__reminders__create`.
A saved deadline alone is not a reminder, and editing or forgetting a note does not cancel
one. Verify schedule changes through its tools.
3 changes: 3 additions & 0 deletions agent/tools/no_reply.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
import { noReply } from "eve/tools/no_reply";

export default noReply();
8 changes: 8 additions & 0 deletions docs/linq.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,14 @@ hosted extension and live verification requirements are met. The staged personal
single-step sign-in only; OTP and passkeys are not implemented. Do not send passwords or OTPs
as chat messages.

## Scheduled updates

Bell uses this same channel for [morning Notion updates and user-requested reminders](reminders.md).
The 8:30 AM morning job finds the existing private chat through Linq's API, checks the sender
allowlist, and reuses that sender's Notion connection. There are no separate recipient settings.
Dynamic reminders capture the verified chat when created and recheck access when due.
Both run the existing Bell agent and deliver its reply to Linq. A web Notion grant is separate.

## Verification boundary

`pnpm test` sends signed HTTP requests through the installed Eve/Linq adapter and checks dispatch
Expand Down
7 changes: 6 additions & 1 deletion docs/notion.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,12 @@ and memory instructions. If a write fails, Bell reports the unsaved record separ
the original task outcome and does not repeat the action.

Memory is saved during conversations. There is no background account sync or guaranteed
logging after a process crash, and a saved deadline is not a scheduled reminder.
logging after a process crash. Once Notion is connected in a private Linq chat, the
[morning update](reminders.md) reads fresh plans and deadlines at 8:30 AM in Bell's local
timezone and sends its reply to that existing chat. Additional reminders and recurring
checks are created when the user asks. A saved deadline alone schedules nothing.
Briefings use the Notion account connected in that Linq chat and cannot change notes or mark
plans complete. Editing a note does not change or cancel a schedule.

## Verify

Expand Down
77 changes: 77 additions & 0 deletions docs/reminders.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Scheduled reminders and morning updates

Bell can check Notion and reply through Linq without waiting for a message. The fixed
morning job uses Eve's `defineSchedule`. User-requested reminders and recurring tasks use
`defineDynamicSchedules` from `eve/experimental/schedules`.

## Configure schedules

Complete [Linq setup](linq.md) with Bell's receiving line and your personal sender allowlist.
For morning updates, connect [Notion](notion.md) in that private Linq chat. No additional
Bell environment variables, credentials, or database migration are needed.

The morning job finds existing private chats through Linq's API and uses each participant's
Linq identity to check their existing Notion connection. It skips groups, archived chats,
other receiving lines, senders outside the allowlist, and disconnected Notion accounts.
It does not create chats or send an update to a new recipient.

Bell uses the machine's local timezone without asking the user. Linq does not expose the
phone's device timezone, so a deployed host must use the intended local timezone. An
explicit choice or saved Notion timezone preference takes precedence for user-created tasks.

Bell pins Eve 0.79.1. Fixed cron expressions use UTC on Vercel, so the morning handler checks
every 15 minutes and starts Bell only in the local 8:30 AM slot, before 8:45. This follows
daylight saving changes. Vercel Cron needs a plan that supports this frequency; Hobby
supports daily jobs only. Built Eve servers can also run the fixed job with their schedule
runner active. Plain `pnpm dev` does not fire fixed schedules automatically.

Dynamic schedules use Vercel Schedules and Queues and require the experimental organization
feature flag in this Eve version. For local dynamic delivery, use `vercel dev` with
[local Schedules support](https://vercel.com/docs/schedules/local-development).

## Use from your phone

Once Notion is connected in your private chat, Bell's morning run checks current plans,
unfinished priorities, and approaching deadlines at 8:30 AM. Bell replies in the existing
chat with useful source links. It uses `no_reply` when a successful check finds nothing
to share.

Text Bell for additional reminders:

- "Remind me to buy milk in ten minutes."
- "Every evening at 7 PM, check Notion for tomorrow's travel plans."
- "Move my travel briefing to 6 PM."
- "Cancel my travel briefing."

Eve provides the management tools, approvals, and creator isolation. Bell captures the
verified destination when the user creates a reminder and rechecks the sender allowlist
when it runs. The existing Bell agent handles the task and delivers its reply through Linq.
Explicit reminders do not require Notion.

## Persistence and recovery

Morning runs read existing chats from Linq and reuse the sender's Notion grant. They do not
depend on the conversation staying open. Web and Linq Notion grants remain separate.
Scheduled Notion access is read-only; Bell cannot change notes or mark tasks complete.

Dynamic records persist through Vercel Schedules. Under plain `pnpm dev`, they are
process-local and disappear on restart. Editing a Notion note does not change or cancel
a reminder. Dynamic management tools control user-created reminders; the fixed morning
job is controlled in code and hosting configuration.

Eve 0.79.1 can repeat a dynamic notification after a delivery retry. Cancellation stops
future occurrences and cannot recall a running task or sent message.

## Verify

`pnpm check` covers chat discovery, sender access, local timing, native reminder management,
and Notion read-only access. Provider HTTP and model execution are mocked; tests send no texts.

For a live check, connect Notion in your private Linq chat and verify the morning update
arrives there. Ask for a reminder in a few minutes, then change or cancel a recurring one.
This needs the existing provider credentials and an active scheduler. Automated tests do
not establish live phone delivery.

See Eve's [fixed schedules](https://eve.dev/docs/schedules) and
[dynamic schedules](https://eve.dev/docs/experimental/dynamic-schedules) guides. Their latest
examples may use options introduced after Bell's pinned version.
Loading