Skip to content
Merged
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
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**An open-source agent that does real work in your tools — and can't be talked into doing the wrong thing.**

SynapseAI works in the services you already use (Gmail, Google Calendar, Drive, Contacts and Slack built in; GitHub, Linear, Notion, Jira, Sentry, or any [MCP](https://modelcontextprotocol.io) server), takes multi-step actions on your behalf, and asks before anything that writes, sends or deletes. It doesn't wait to be asked: automations start work on a schedule, when an email arrives, or when another app calls a webhook. Approvals are enforced in code, not in the prompt; once the agent has read untrusted content such as an email or a web page, every outward action needs your sign-off. Self-host it with one command, bring your own model keys, and see exactly what it did and what it cost.
SynapseAI works in the services you already use (Gmail, Google Calendar, Drive, Sheets, Contacts and Slack built in; GitHub, Linear, Notion, Jira, Sentry, or any [MCP](https://modelcontextprotocol.io) server), takes multi-step actions on your behalf, and asks before anything that writes, sends or deletes. It doesn't wait to be asked: automations start work on a schedule, when an email arrives, or when another app calls a webhook. Approvals are enforced in code, not in the prompt; once the agent has read untrusted content such as an email or a web page, every outward action needs your sign-off. Self-host it with one command, bring your own model keys, and see exactly what it did and what it cost.

![A task waiting for approval: the agent drafted an email and shows it as an editable card, with the activity timeline on the right](docs/screenshots/task.png)

Expand All @@ -26,9 +26,11 @@ Agent products that act in your tools share three problems: approvals that live
## Features

- Chat with live streaming (reasoning, tool calls, results) that resumes after reconnects
- Built-in Gmail and Google Calendar: search, read threads, draft, reply in-thread, label and archive, find free time, book and move meetings, answer invitations ([setup](docs/google.md))
- Built-in Gmail and Google Calendar: search, read threads, open attachments (PDFs read, photos seen), draft, reply in-thread, label and archive, find free time, book and move meetings, answer invitations ([setup](docs/google.md))
- Built-in Google Drive and Contacts: search Drive and read Docs, Sheets, Slides and PDFs, create Google Docs (with approval), and look people up by name so "email Sam" just works
- Built-in Google Sheets: read any sheet by link, add rows, update cells and create spreadsheets, each write shown as a table on the approval card ("save the invoice from that email and add its total to my Expenses sheet")
- Automations triggered by a cron schedule, new Gmail messages matching a search, or a secret webhook URL
- Reminders and follow-ups from chat: "remind me Friday at 9 to send the report" notifies you by push, Slack or email at that time; "in 3 days, check whether Sam replied and nudge him if not" brings the agent back to the same conversation, with its context, to do it. One-off or repeating, in your time zone, listed (and cancellable) under Automations. Scheduling from a task that read an email or web page always asks first, so outside content can't plant a scheduled instruction ([how it works](docs/api.md#scheduled-from-chat))
- MCP connections over Streamable HTTP with OAuth 2.1 + PKCE, or bearer tokens; presets for GitHub, Linear, Notion, Atlassian, Sentry
- Approval inbox, editable approvals, deny-with-reason, cancel now / after this step
- Approve a plan, not every step: the agent proposes the exact actions it will take, you untick what you don't want, and the kept actions run without asking again (even after the task read outside content, because you saw each one, unless a step names a recipient that first appeared in that content)
Expand Down Expand Up @@ -96,7 +98,7 @@ The server is stateless apart from Postgres. Run the API and workers separately
|---|---|
| `packages/core` | Host-agnostic agent runtime: run loop, approval state machine, policy, compaction, model fallback, client event reducer. No database or HTTP. |
| `packages/db` | Drizzle schema and migrations, Postgres store for the runtime, run leasing, ordered event log, secret encryption. |
| `packages/tools` | Gmail, Calendar, Drive and Contacts, Slack, MCP client with OAuth, SSRF guard, web search/fetch, knowledge base, memory. |
| `packages/tools` | Gmail, Calendar, Drive, Sheets and Contacts, Slack, MCP client with OAuth, SSRF guard, web search/fetch, knowledge base, memory. |
| `packages/evals` | Scenario harness (task + safety) with simulated users; `bun run evals`. |
| `apps/server` | HTTP API, auth, SSE, worker. |
| `apps/web` | Next.js UI. |
Expand Down
91 changes: 88 additions & 3 deletions apps/server/src/google-tools.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { afterAll, beforeAll, expect, test } from "bun:test";
import { type ScriptedStep, scriptedModel } from "@synapse/core/testing";
import { schema } from "@synapse/db";
import { fakeGoogle, LEGACY_GOOGLE_SCOPE } from "@synapse/tools/testing";
import { fakeGoogle, LEGACY_GOOGLE_SCOPE, tinyPdf } from "@synapse/tools/testing";
import { and, eq } from "drizzle-orm";
import { createApp } from "./app";
import { loadConfig } from "./config";
Expand Down Expand Up @@ -89,14 +89,15 @@ async function run(runId: string) {
return row!;
}

test("a grant from before Drive and Contacts keeps working and asks for a reconnect", async () => {
test("a grant from before Drive, Contacts and Sheets keeps working and asks for a reconnect", async () => {
const ada = await signUp("legacy@gtools.test");
await connectGoogle(ada, LEGACY_GOOGLE_SCOPE);
const status = await ada("/api/integrations");
expect(status.json.google.connection.status).toBe("active");
expect(status.json.google.connection.missing.map((m: { label: string }) => m.label)).toEqual([
"Drive",
"Contacts",
"Sheets",
]);
expect(
status.json.google.tools.find((t: { name: string }) => t.name === "drive_create_doc").group,
Expand All @@ -111,7 +112,7 @@ test("a grant from before Drive and Contacts keeps working and asks for a reconn
await worker.processNow(chat.json.runId);
expect((await toolCall(chat.json.runId, "d1")).status).not.toBe("succeeded");
const prompt = JSON.stringify(model.calls[0]?.prompt);
expect(prompt).toContain("Drive and Contacts: not granted yet");
expect(prompt).toContain("Drive, Contacts and Sheets: not granted yet");

await connectGoogle(ada);
expect((await ada("/api/integrations")).json.google.connection.missing).toEqual([]);
Expand Down Expand Up @@ -171,3 +172,87 @@ test("creating a Doc asks first, then uploads it as a Google Doc", async () => {
expect(google.state.createdDocs.map((d) => d.name)).toEqual(["Launch plan"]);
expect(google.state.createdDocs[0]!.html).toContain("<h1>Launch</h1>");
});

test("“save the invoice PDF and add its total to my sheet”: reads run, the append asks", async () => {
const ada = await signUp("sheets@gtools.test");
await connectGoogle(ada);
await ada("/api/settings", { method: "PUT", json: { undoSeconds: 0 } });
const id = "1ExPeNsEs0123456789abcdefghij";
google.state.spreadsheets.push({
id,
title: "Expenses",
sheets: [{ sheetId: 0, title: "Sheet1", rows: [["Date", "Vendor", "Total"]] }],
});
const mail = google.receive({
from: "billing@acme.example",
subject: "Invoice 4471",
body: "Your invoice is attached.",
attachments: [
{ filename: "invoice-4471.pdf", mimeType: "application/pdf", data: tinyPdf("Total 1234.50") },
],
});
const link = `https://docs.google.com/spreadsheets/d/${id}/edit`;
const chat = await ada("/api/chats", {
method: "POST",
json: {
content: `Save the invoice PDF from Acme's email and add its total to my sheet ${link}`,
},
});
const append = {
spreadsheet: link,
spreadsheetTitle: "Expenses",
range: "Sheet1",
rows: [["2026-10-31", "Acme", 1234.5]],
};
script([
{ toolCalls: [{ name: "gmail_read_thread", id: "r1", input: { threadId: mail.threadId } }] },
{
toolCalls: [
{
name: "gmail_save_attachment",
id: "a1",
// An id from an earlier fetch: Gmail's change every time, the name still matches.
input: { messageId: mail.id, attachmentId: "stale", filename: "invoice-4471.pdf" },
},
{ name: "sheets_read", id: "q1", input: { spreadsheet: link, range: "Sheet1" } },
],
},
{ toolCalls: [{ name: "sheets_append", id: "w1", input: append }] },
{ text: "Added Acme's 1,234.50 to Expenses." },
]);
await worker.processNow(chat.json.runId);
for (const read of ["r1", "a1", "q1"])
expect((await toolCall(chat.json.runId, read)).status).toBe("succeeded");
const saved = (await toolCall(chat.json.runId, "a1")).output as unknown as {
value: { fileId: string; mimeType: string };
};
expect(saved.value.mimeType).toBe("application/pdf");
const [file] = await services.database.db
.select()
.from(schema.files)
.where(eq(schema.files.id, saved.value.fileId));
expect(file?.text).toContain("Total 1234.50");
expect((await ada(`/api/files/${saved.value.fileId}`)).status).toBe(200);
expect((await run(chat.json.runId)).tainted).toBe(true);

const waiting = await toolCall(chat.json.runId, "w1");
expect(waiting.status).toBe("awaiting_approval");
expect(waiting.preview).toBe("Add 1 row to “Expenses” › Sheet1");
expect(google.state.sheetWrites).toHaveLength(0);
const [approval] = (await ada("/api/approvals")).json.approvals;
expect(approval.facts).toEqual(["After reading outside content"]);

await ada(`/api/runs/${chat.json.runId}/tool-calls/w1/decision`, {
method: "POST",
json: { approved: true },
});
await worker.processNow(chat.json.runId);
expect((await toolCall(chat.json.runId, "w1")).status).toBe("succeeded");
expect(google.state.spreadsheets[0]!.sheets[0]!.rows).toEqual([
["Date", "Vendor", "Total"],
["2026-10-31", "Acme", 1234.5],
]);
expect(google.state.sheetWrites).toEqual([
{ kind: "append", range: "Sheet1", valueInputOption: "USER_ENTERED" },
]);
});
40 changes: 39 additions & 1 deletion apps/server/src/notify/email.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import nodemailer from "nodemailer";
import { log } from "../log";
import type { Services } from "../services";
import { detailLines, TITLE } from "./text";
import type { NotificationChannel, PendingApproval } from "./types";
import type { NotificationChannel, PendingApproval, UserNotice } from "./types";

export interface MailMessage {
from: string;
Expand Down Expand Up @@ -56,6 +56,44 @@ export class EmailChannel implements NotificationChannel {
}),
);
}

/** Reminders go out on the same opt-in as approval alerts. */
async notice(notices: UserNotice[]): Promise<void> {
if (notices.length === 0) return;
const people = await this.services()
.database.db.select({ id: schema.user.id, email: schema.user.email })
.from(schema.user)
.innerJoin(schema.userSettings, eq(schema.userSettings.userId, schema.user.id))
.where(
and(
inArray(schema.user.id, [...new Set(notices.map((n) => n.userId))]),
eq(schema.userSettings.emailAlerts, true),
),
);
const to = new Map(people.map((p) => [p.id, p.email]));
await Promise.all(
notices.map(async (n) => {
const address = to.get(n.userId);
if (!address) return;
try {
await this.transport.sendMail({
from: this.from,
to: address,
subject: oneLine(n.title, 100),
text: `${n.body}\n\nOpen: ${n.url}`,
html: `<!doctype html><html><body style="margin:0;padding:24px;background:#f4f1ea;color:#15140f;font:15px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif">
<div style="max-width:560px;margin:0 auto;background:#fffdf8;border:1px solid #e2dccf;border-radius:12px;padding:24px">
<p style="margin:0 0 8px;font-weight:600">${esc(n.title)}</p>
<p style="margin:0 0 16px;white-space:pre-wrap">${esc(n.body)}</p>
<a href="${esc(n.url)}" style="color:#3b48cc">Open the conversation</a>
</div></body></html>`,
});
} catch (error) {
log.warn("reminder email failed", { userId: n.userId, error: String(error) });
}
}),
);
}
}

export function render(items: PendingApproval[]): Pick<MailMessage, "subject" | "text" | "html"> {
Expand Down
24 changes: 23 additions & 1 deletion apps/server/src/notify/notifier.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import {
approvalTiming,
claimAnnouncement,
type DueCall,
type FiredReminder,
membershipOf,
schema,
workspaceAdminIds,
Expand All @@ -12,7 +13,13 @@ import { and, eq, inArray } from "drizzle-orm";
import { alias } from "drizzle-orm/pg-core";
import { log } from "../log";
import type { Services } from "../services";
import type { NoticeKind, NotificationChannel, PendingApproval, ResolvedApproval } from "./types";
import type {
NoticeKind,
NotificationChannel,
PendingApproval,
ResolvedApproval,
UserNotice,
} from "./types";

/**
* Tells people about approvals through every registered channel: when they start waiting,
Expand Down Expand Up @@ -60,6 +67,21 @@ export class Notifier {
await this.each("resolved", (c) => c.resolved?.(decided));
}

/** Reminders the user scheduled, on every channel they set up. Returns what was sent. */
async reminders(fired: FiredReminder[]): Promise<UserNotice[]> {
if (fired.length === 0) return [];
const { config } = this.services();
const notices = fired.map((r) => ({
userId: r.userId,
title: `Reminder: ${r.title}`,
body: r.text,
url: `${config.PUBLIC_URL}/t/${r.chatId}`,
tag: `reminder:${r.automationId}`,
}));
await this.each("notice", (c) => c.notice?.(notices));
return notices;
}

private async byRun(calls: DueCall[], kind: NoticeKind) {
const runs = new Map<string, string[]>();
for (const c of calls) runs.set(c.runId, [...(runs.get(c.runId) ?? []), c.toolCallId]);
Expand Down
15 changes: 14 additions & 1 deletion apps/server/src/notify/push.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import type { PushConfig } from "../config";
import { log } from "../log";
import type { Services } from "../services";
import { detailLines, TITLE } from "./text";
import type { NotificationChannel, PendingApproval } from "./types";
import type { NotificationChannel, PendingApproval, UserNotice } from "./types";

/** What the service worker receives (public/sw.js reads exactly these fields). */
export interface PushMessage {
Expand Down Expand Up @@ -120,6 +120,19 @@ export class PushChannel implements NotificationChannel {
);
}

async notice(notices: UserNotice[]): Promise<void> {
await Promise.all(
notices.map((n) =>
this.sendToUser(n.userId, {
title: n.title,
body: clip(n.body, 300),
tag: n.tag,
data: { url: n.url },
}),
),
);
}

/** Sends one message to all of a user's devices. */
async sendToUser(
userId: string,
Expand Down
36 changes: 36 additions & 0 deletions apps/server/src/notify/slack.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import type {
NotificationChannel,
PendingApproval,
ResolvedApproval,
UserNotice,
} from "./types";

/** Slack block, loosely typed: we only build a handful of kinds. */
Expand Down Expand Up @@ -298,6 +299,41 @@ export class SlackChannel implements NotificationChannel {
}
}

/** Reminders as plain DMs, with a link to the conversation. */
async notice(notices: UserNotice[]) {
const app = this.app;
if (!app || notices.length === 0) return;
const accounts = await this.services()
.database.db.select()
.from(schema.slackAccounts)
.where(
and(
inArray(schema.slackAccounts.userId, [...new Set(notices.map((n) => n.userId))]),
eq(schema.slackAccounts.status, "active"),
),
);
for (const account of accounts) {
try {
const token = await this.services().box.open(account.botToken);
const channel = await openDm(app, token, account.slackUserId);
for (const n of notices.filter((x) => x.userId === account.userId)) {
await slackCall(app, token, "chat.postMessage", {
channel,
text: `${n.title}\n${n.body}`,
blocks: [
section(`*${esc(n.title)}*\n${esc(clip(n.body, 2500))}`),
context(`<${n.url}|Open in Synapse>`),
],
unfurl_links: false,
unfurl_media: false,
});
}
} catch (error) {
await this.failed(account.userId, error);
}
}
}

/** Sends a hello DM so people can see where approvals will land. */
async sendTest(userId: string): Promise<boolean> {
const app = this.app;
Expand Down
13 changes: 13 additions & 0 deletions apps/server/src/notify/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,17 @@ export interface ResolvedApproval {
/** Where a decision was made; `expiry` is nobody deciding in time. */
export type DecisionSource = "web" | "push" | "slack" | "email" | "expiry";

/** Something to tell a person that is not an approval, e.g. a reminder they scheduled. */
export interface UserNotice {
userId: string;
title: string;
body: string;
/** Where to open it in the web app. */
url: string;
/** Replaces an earlier notice with the same tag on a device. */
tag: string;
}

/**
* A way to reach a person about approvals: web push, Slack, email. Channels decide for
* themselves whether a user has them set up; `notify` is called for every new approval.
Expand All @@ -76,4 +87,6 @@ export interface NotificationChannel {
notify(approvals: PendingApproval[]): Promise<void>;
/** Optional: the approvals were decided (anywhere). */
resolved?(decided: ResolvedApproval[]): Promise<void>;
/** Optional: plain notices, such as reminders, for people who set this channel up. */
notice?(notices: UserNotice[]): Promise<void>;
}
12 changes: 11 additions & 1 deletion apps/server/src/prompt.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ How you work:
- When you draft something that will be sent or published (an email, a message, an issue), put the complete final content in the tool call. The user reviews exactly that on an approval card.
- Some actions need the user's approval. The system asks for it automatically; you do not need to ask in text first. If an action is denied, do not retry it in another form; acknowledge it and continue or ask what they want instead.
- When a task needs several actions that change things (sending, writing, deleting), first call propose_plan with the exact calls you intend to make, so the user can approve them once. After approval, make exactly the approved calls with exactly the same inputs, and nothing the user removed. For a single action, just make the call.
- When the user wants a reminder or something done later ("remind me Friday at 9", "in 3 days, check whether Sam replied"), use schedule_task: kind "reminder" when they only need to be told, kind "task" when you should act then. Confirm the time back in their time zone.
- If a tool fails, read the error, fix your input once if it is clearly your mistake, and otherwise tell the user what failed.
- Keep answers concise and skimmable. Cite sources (page titles and URLs, document names) for facts you looked up.

Expand All @@ -28,9 +29,18 @@ export function buildSystemPrompt(args: {
connections: string[];
/** The enabled skills' listing (`skillsPromptBlock`): names and descriptions only. */
skills?: string | null;
/** The user's IANA time zone, when they set one: the date is theirs, not the server's. */
timezone?: string | null;
now?: Date;
}): string {
const date = (args.now ?? new Date()).toISOString().slice(0, 10);
const now = args.now ?? new Date();
let date = now.toISOString().slice(0, 10);
if (args.timezone) {
try {
// en-CA formats as YYYY-MM-DD.
date = `${new Intl.DateTimeFormat("en-GB", { timeZone: args.timezone, weekday: "long" }).format(now)} ${new Intl.DateTimeFormat("en-CA", { timeZone: args.timezone }).format(now)}, time zone ${args.timezone}`;
} catch {}
}
const parts = [BASE];
parts.push(
`Connected services: ${args.connections.length > 0 ? args.connections.join(", ") : "none yet (the user can add them under Connections)"}.`,
Expand Down
Loading
Loading