Skip to content
Open
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
2 changes: 2 additions & 0 deletions agent/agent.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
import { openai } from "@ai-sdk/openai";
import { defineAgent } from "eve";
import { scheduledToolApproval } from "./lib/scheduled-tools";

export default defineAgent({
model: openai.responses(process.env.BELL_MODEL ?? "gpt-5.6-sol"),
approval: scheduledToolApproval,
build: {
externalDependencies: [
"@1password/sdk",
Expand Down
31 changes: 27 additions & 4 deletions agent/channels/linq.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
import { linqBrowserEvents, requiredEnvironmentValue } from "../lib/linq";
import { linqBrowserEvents, localTimezone, requiredEnvironmentValue } from "../lib/linq";
import type { Channel, InferChannelMetadata } from "eve/channels";
import type { ChatSdkChannelState, ChatSdkReceiveTarget } from "eve/channels/chat-sdk";
import { defaultLinqAuth, linqChannel, type LinqChannelConfig } from "eve/channels/linq";
import { z } from "zod";

Expand Down Expand Up @@ -28,7 +30,7 @@ export function isAllowedBellMessage(message: Pick<LinqMessage, "author" | "raw"
&& allowedSenders.data.includes(incoming.data.sender_handle.handle);
}

export default linqChannel({
const linq = linqChannel({
events: linqBrowserEvents,
userName: "Bell",
credentials: {
Expand All @@ -40,13 +42,34 @@ 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.",
],
};
},
});

type BellLinqTarget = ChatSdkReceiveTarget & { morningDate?: string };
const receive = linq.receive;
if (!receive) throw new Error("The Eve Linq channel requires a receive handler.");

const channel: Channel<ChatSdkChannelState, BellLinqTarget, InferChannelMetadata<typeof linq>> = {
...linq,
receive(input, ctx) {
const { morningDate } = input.target;
// Eve's address selects a session. The Linq adapter still posts to the real thread ID.
return receive(input, morningDate === undefined ? ctx : {
...ctx,
from: address => ctx.from(`morning:${morningDate}:${address}`),
});
},
};

export default channel;
53 changes: 25 additions & 28 deletions agent/connections/notion.ts
Original file line number Diff line number Diff line change
@@ -1,35 +1,32 @@
import { defineDynamic, defineMcpClientConnection } from "eve/connections";
import { notionAuth } from "../lib/notion-auth";
import { notionReadTools } from "../lib/scheduled-tools";
import { notionEnabled, notionEndpoint, notionOwner, safeNotion } from "../../server/notion/config";
import { getNotionOAuth } from "../../server/notion/oauth";

export default defineDynamic({
events: {
"turn.started": (_event, ctx) => {
if (!notionEnabled()) return null;
const auth = ctx.session.auth.current;
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);
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",
"notion-create-pages", "notion-update-page", "notion-create-database", "notion-update-data-source",
"notion-get-async-task", "notion-delete-pages",
] },
approval: async ({ toolName }) => {
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)
? "user-approval" : "not-applicable";
},
});
export default defineDynamic((ctx) => {
if (!notionEnabled()) return null;
const auth = ctx.session.auth.current;
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;
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: scheduled ? notionReadTools : [...notionReadTools,
"notion-create-pages", "notion-update-page", "notion-create-database", "notion-update-data-source",
"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)
? "user-approval" : "not-applicable";
},
},
});
});
6 changes: 4 additions & 2 deletions agent/extensions/link/lib/spend-requests.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ const total = z.object({
amount: z.number(),
});

const expiration = z.union([z.number(), z.iso.datetime({ offset: true })]);

const metadata = z.object({
id: spendRequestId,
status: z.string(),
Expand All @@ -56,7 +58,7 @@ const metadata = z.object({
totals: z.array(total).optional(),
approval_url: z.string().optional(),
activity_url: z.string().optional(),
expires_at: z.number().optional(),
expires_at: expiration.optional(),
recurring: z.object({
interval: z.string(),
interval_count: z.number().optional(),
Expand All @@ -83,7 +85,7 @@ const metadata = z.object({
display_message: z.string().optional(),
action_url: z.string().nullable().optional(),
resolution: z.string().optional(),
expires_at: z.number().nullable().optional(),
expires_at: expiration.nullable().optional(),
}).optional(),
}).optional(),
}).nullable().optional(),
Expand Down
1 change: 1 addition & 0 deletions agent/extensions/link/tools/checkout.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ export default defineTool({
description: "Submit an already-approved Link purchase in the existing browser. Supply exact CSS payment-field mappings and the approved amount/currency. Virtual-card values stay server-side. Shared Payment Tokens and Link Pay Tokens require a separate integration and are not accepted. Use only once per purchase; an uncertain outcome requires checking the merchant and Link before any retry. Human handoff remains available for 3DS.",
inputSchema: checkoutInput,
async execute(args, ctx) {
if (ctx.session.schedule !== undefined) throw new Error("Link checkout requires an interactive Linq conversation.");
const input = checkoutInput.parse(args);
linkPrincipal(ctx);
ctx.abortSignal.throwIfAborted();
Expand Down
2 changes: 2 additions & 0 deletions agent/extensions/link/tools/mpp_decode.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
import { disableTool } from "eve/tools";
export default disableTool();
2 changes: 2 additions & 0 deletions agent/extensions/link/tools/mpp_pay.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
import { disableTool } from "eve/tools";
export default disableTool();
2 changes: 2 additions & 0 deletions agent/extensions/link/tools/retrieve_approval_policy.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
import { disableTool } from "eve/tools";
export default disableTool();
4 changes: 2 additions & 2 deletions agent/hooks/browser-lifecycle.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ import { saveBrowserRuntime } from "../lib/browser-runtime";

export default defineHook({
events: {
async "turn.completed"(_event, ctx) {
await saveBrowserRuntime(ctx.session.id);
async "turn.settled"(event, ctx) {
if (event.data.outcome === "completed") await saveBrowserRuntime(ctx.session.id);
},
},
});
34 changes: 14 additions & 20 deletions agent/hooks/task-state.ts
Original file line number Diff line number Diff line change
@@ -1,36 +1,30 @@
import { defineHook, type HookEvent } from "eve/hooks";
import { defineHook, type HookContext, type HookEvent } from "eve/hooks";

import { closeBrowserRuntime, resumeBrowserAfterHumanInput } from "../lib/browser-runtime";
import { applyTaskEvent, taskState } from "../lib/task-state";

const update = (event: HookEvent, ctx: { session: { id: string } }) =>
taskState.update((current) => applyTaskEvent(current, event, ctx.session.id));

const cancel = async (event: HookEvent<"turn.cancelled">, ctx: { session: { id: string } }) => {
await closeBrowserRuntime(ctx.session.id);
update(event, ctx);
};
const update = (event: HookEvent, ctx: HookContext) =>
taskState.update((current) => applyTaskEvent(current, event, ctx.session.id, ctx.position, ctx.now.toISOString()));

export default defineHook({
events: {
"session.started": update,
"turn.started": update,
"message.received": (event, ctx) => {
"delivery.consumed": (event, ctx) => {
taskState.update((current) => {
const next = applyTaskEvent(current, event, ctx.session.id);
if (next !== current && current.status === "waiting_for_user")
const next = applyTaskEvent(current, event, ctx.session.id, ctx.position, ctx.now.toISOString());
if (next !== current && current.status === "waiting_for_user" && event.data.parts.length > 0)
resumeBrowserAfterHumanInput(ctx.session.id);
return next;
});
},
"step.started": update,
"input.requested": update,
"input.resolved": update,
"turn.completed": update,
"turn.failed": update,
"turn.cancelled": cancel,
"session.waiting": update,
"session.failed": update,
"session.completed": update,
"model.started": update,
"interaction.opened": update,
"interaction.settled": update,
async "turn.settled"(event, ctx) {
if (event.data.outcome === "cancelled") await closeBrowserRuntime(ctx.session.id);
update(event, ctx);
},
"session.ended": update,
},
});
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
6 changes: 1 addition & 5 deletions agent/lib/browser-runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -358,12 +358,8 @@ function scheduleIdleClose(sessionId: string, runtime: BrowserRuntime): void {
}

// Channel callbacks also run when Eve ends a session outside a turn.
// Global stream hooks do not run on that path in Eve 0.79.1.
export const browserChannelEvents = {
async "session.completed"(_event: unknown, _channel: unknown, ctx: { session: { id: string } }) {
async "session.ended"(_event: unknown, ctx: { session: { id: string } }) {
await closeBrowserRuntime(ctx.session.id);
},
async "session.failed"(event: { sessionId: string }) {
await closeBrowserRuntime(event.sessionId);
},
};
10 changes: 7 additions & 3 deletions agent/lib/linq.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@ import { browserChannelEvents } from "./browser-runtime";

export const linqBrowserEvents: NonNullable<LinqChannelConfig["events"]> = {
...browserChannelEvents,
async "session.failed"(event, channel) {
async "session.ended"(event, ctx) {
try {
await browserChannelEvents["session.failed"](event);
await browserChannelEvents["session.ended"](event, ctx);
} finally {
await channel.thread?.post("This session could not recover from an error. Start a new conversation to continue.");
if (event.data.outcome === "failed") await ctx.channel.thread?.post("This session could not recover from an error. Start a new conversation to continue.");
}
},
};
Expand All @@ -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;
}
17 changes: 17 additions & 0 deletions agent/lib/scheduled-tools.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
import type { AgentDefinition } from "eve";

export const notionReadTools = [
"notion-search", "notion-fetch", "notion-memory-search", "notion-get-self",
"notion-get-tool-access", "notion-query-data-sources", "notion-get-async-task",
];

const scheduledTools = new Set([
...notionReadTools.map(name => `notion__${name}`),
"no_reply", "notion_status", "web_search", "web_fetch",
]);

export const scheduledToolApproval: NonNullable<AgentDefinition["approval"]> = ({ session, toolName }) => {
if (session.schedule && !scheduledTools.has(toolName)) {
return { type: "denied", reason: "Scheduled turns can only look up information and report it." };
}
};
Loading