Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
/**
* Event triggers: the registered, authenticated ways an outside event reaches one responsibility.
*
* Every kind ends in the same place: an ingress route verifies the sender with that vendor's own
* signature scheme, applies the trigger's narrow filter, and hands `store.ingestEvent` an event that
* names this trigger and its responsibility. The store commits the event, the run ledger row and the
* `work_items` queue entry in one transaction; the engine then runs the selected Bot through the
* normal headless AG-UI path. There is no second engine and no second queue here.
*
* Paused and completed responsibilities never run: ingress refuses to queue for them, and
* `beginRun` re-checks at dispatch and marks any run that slipped through as skipped.
*/
import { randomBytes, randomUUID } from "node:crypto";
import { and, eq } from "drizzle-orm";
import { z } from "zod";
import {
type CredentialSecretReader,
type CredentialStore,
decryptSecret,
encryptSecret,
} from "../credentials";
import type { Database } from "../db/client";
import {
responsibilities,
responsibilityTriggers,
} from "../db/schema/responsibilities";
import {
ResponsibilityNotFoundError,
ResponsibilityRefusedError,
type ResponsibilitySource,
type ResponsibilityStatus,
} from "./types";
export const triggerKinds = [
"webhook",
"github",
"linear",
"sentry",
"pagerduty",
"email",
"slack",
] as const;
export type TriggerKind = (typeof triggerKinds)[number];
/** Kinds whose secret OpenBot generates; the others' secret is pasted from the vendor. */
const GENERATED_SECRET: ReadonlySet<TriggerKind> = new Set([
"webhook",
"github",
]);
/** Kinds authenticated by a shared secret at all. */
const SECRET_KINDS: ReadonlySet<TriggerKind> = new Set([
"webhook",
"github",
"linear",
"sentry",
"pagerduty",
]);
const shortText = (maximum: number) => z.string().trim().min(1).max(maximum);
export const triggerFilterSchema = z
.object({
/**
* Event types that fire this trigger. Empty means every event this kind delivers. A pattern
* matches the exact type or any sub-type: `issues` matches `issues.opened`.
*/
eventTypes: z.array(shortText(128)).max(20).default([]),
/** One optional payload field that must equal a value, e.g. `data.team.key` = `ENG`. */
field: z
.object({
path: z
.string()
.trim()
.regex(/^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+){0,7}$/, {
message: "Use a dotted field path such as data.team.key.",
}),
equals: shortText(256),
})
.strict()
.optional(),
})
.strict();
export type TriggerFilter = z.infer<typeof triggerFilterSchema>;
const slackMode = z.enum(["mention", "phrase", "reaction", "message"]);
export const triggerConfigSchema = z.discriminatedUnion("kind", [
z
.object({
kind: z.literal("webhook"),
filter: triggerFilterSchema.default({ eventTypes: [] }),
})
.strict(),
z
.object({
kind: z.literal("github"),
/** Optional owner/name lock: deliveries for any other repository are refused. */
repository: z
.string()
.trim()
.regex(/^[\w.-]+\/[\w.-]+$/, {
message: "Use the GitHub repository owner/name.",
})
.max(256)
.optional(),
filter: triggerFilterSchema.default({ eventTypes: [] }),
})
.strict(),
z
.object({
kind: z.literal("linear"),
filter: triggerFilterSchema.default({ eventTypes: [] }),
})
.strict(),
z
.object({
kind: z.literal("sentry"),
filter: triggerFilterSchema.default({ eventTypes: [] }),
})
.strict(),
z
.object({
kind: z.literal("pagerduty"),
filter: triggerFilterSchema.default({ eventTypes: [] }),
})
.strict(),
z
.object({
kind: z.literal("email"),
/**
* Addresses (`ops@example.com`) or domains (`example.com`) allowed to trigger. Empty admits any
* sender. When set, SES must also report DMARC or DKIM as PASS, so a forged From is refused: SES
* reports DKIM as GRAY, not PASS, when the signing domain does not match the From domain.
*/
allowedSenders: z.array(shortText(254)).max(20).default([]),
filter: triggerFilterSchema.default({ eventTypes: [] }),
})
.strict(),
z
.object({
kind: z.literal("slack"),
/** The Slack workspace (T…) the paired Bot receives events from. */
teamId: z
.string()
.trim()
.regex(/^[A-Z0-9]{2,32}$/, {
message: "Use the Slack team ID, e.g. T0123ABCD.",
}),
mode: slackMode,
/** Mode `phrase`: case-insensitive substrings; any one matches. */
phrases: z.array(shortText(200)).max(20).default([]),
/** Mode `reaction`: emoji names without colons. Empty means any reaction. */
reactions: z
.array(
z
.string()
.trim()
.regex(/^[a-z0-9_+'-]{1,100}$/),
)
.max(20)
.default([]),
/** Slack channel IDs. Empty means every channel the Bot is in. */
channels: z
.array(
z
.string()
.trim()
.regex(/^[CDG][A-Z0-9]{2,32}$/),
)
.max(50)
.default([]),
})
.strict()
.superRefine((value, context) => {
if (value.mode === "phrase" && value.phrases.length === 0)
context.addIssue({
code: "custom",
message: "Give at least one phrase to listen for.",
});
}),
]);
export type TriggerConfig = z.infer<typeof triggerConfigSchema>;
export function parseTriggerConfig(input: unknown): TriggerConfig {
const result = triggerConfigSchema.safeParse(input);
if (!result.success)
throw new ResponsibilityRefusedError(
result.error.issues[0]?.message ?? "Invalid trigger.",
);
return result.data;
}
export function sourceForKind(kind: TriggerKind): ResponsibilitySource {
return kind;
}
function valueAt(payload: unknown, path: string): unknown {
let value: unknown = payload;
for (const segment of path.split(".")) {
if (!value || typeof value !== "object") return undefined;
value = (value as Record<string, unknown>)[segment];
}
return value;
}
/** The narrow matching rule: event type (exact or sub-type) plus one optional field equality. */
export function matchesFilter(
filter: TriggerFilter,
eventType: string,
payload: unknown,
): boolean {
const type = eventType.toLowerCase();
if (
filter.eventTypes.length > 0 &&
!filter.eventTypes.some((pattern) => {
const wanted = pattern.toLowerCase();
return wanted === "*" || type === wanted || type.startsWith(`${wanted}.`);
})
)
return false;
if (filter.field) {
const actual = valueAt(payload, filter.field.path);
if (
actual === undefined ||
actual === null ||
typeof actual === "object" ||
String(actual).toLowerCase() !== filter.field.equals.toLowerCase()
)
return false;
}
return true;
}
export const MAX_EVENT_PAYLOAD = 32_768;
/**
* Provider payloads are often larger than the ledger's 32 KiB cap (a Sentry alert carries the whole
* event). The top-level scalars survive intact and the rest is kept as a bounded excerpt, so the
* Bot still sees what happened and the ledger stays bounded.
*/
export function fitPayload(
payload: Record<string, unknown>,
): Record<string, unknown> {
const whole = JSON.stringify(payload);
if (whole.length <= MAX_EVENT_PAYLOAD) return payload;
// The scalars get half the cap. Uncapped, forty 1000-character fields filled it alone, the
// excerpt below could not shrink past "", and the loop that trims it never ended.
const scalars: Record<string, unknown> = {};
let kept = 0;
for (const [key, value] of Object.entries(payload))
if (
value === null ||
["string", "number", "boolean"].includes(typeof value)
) {
const scalar = typeof value === "string" ? value.slice(0, 1000) : value;
const size = JSON.stringify({ [key]: scalar }).length;
if (kept + size > MAX_EVENT_PAYLOAD / 2) continue;
scalars[key] = scalar;
kept += size;
}
const fitted: Record<string, unknown> = {
truncated: true,
...scalars,
excerpt: "",
};
const room = MAX_EVENT_PAYLOAD - JSON.stringify(fitted).length - 64;
fitted.excerpt = Array.from(whole).slice(0, Math.max(0, room)).join("");
while (JSON.stringify(fitted).length > MAX_EVENT_PAYLOAD)
fitted.excerpt = String(fitted.excerpt).slice(0, -1024);
return fitted;
}
/** `whsec_` + base64: usable as a bearer token and, decoded, as a Standard Webhooks HMAC key. */
export function generateWebhookSecret(): string {
return `whsec_${randomBytes(32).toString("base64")}`;
}
export type TriggerRecord = {
id: string;
responsibilityId: string;
kind: TriggerKind;
config: TriggerConfig;
hasSecret: boolean;
/** A paused trigger acknowledges deliveries but never queues a run. */
enabled: boolean;
createdAt: Date;
updatedAt: Date;
};
/** What an ingress route needs: the owner, target, config, lifecycle and the plaintext secret. */
export type ResolvedTrigger = {
id: string;
ownerUserId: string;
responsibilityId: string;
responsibilityStatus: ResponsibilityStatus;
kind: TriggerKind;
config: TriggerConfig;
secret: string | null;
enabled: boolean;
createdAt: Date;
};
/**
* Who may point a Bot at Slack. A Slack trigger feeds other people's messages into a run, so only
* the responsibility's owner may create one (enforced by ownership), only in a workspace where that
* owner has linked their own Slack identity, and only for channels that identity is a member of.
* Checked when the trigger is saved and again for every event, so unlinking or leaving a channel
* stops delivery. Supplied by the Slack pairing; absent means Slack triggers are refused.
*/
export type SlackAccess = {
/** The owner's linked Slack user id in that workspace, or null when not linked. */
linkedIdentity(ownerUserId: string, teamId: string): Promise<string | null>;
/** Null when this deployment cannot check Slack channel membership yet (fail closed). */
isMember:
| ((input: {
teamId: string;
slackUserId: string;
channelId: string;
}) => Promise<boolean>)
| null;
};
export async function slackAccessAllows(
access: SlackAccess | undefined,
ownerUserId: string,
teamId: string,
channelIds: string[],
): Promise<string | null> {
if (!access)
return "Slack triggers are not available on this deployment: the Slack pairing is not connected.";
const slackUserId = await access.linkedIdentity(ownerUserId, teamId);
if (!slackUserId)
return "Link your own Slack account in that workspace first (the Bot's Reaching you page in OpenBot), so the trigger only hears channels you are in.";
if (!access.isMember)
return "Slack channel membership cannot be checked on this deployment yet, so Slack triggers are refused.";
for (const channelId of channelIds)
if (!(await access.isMember({ teamId, slackUserId, channelId })))
return `You are not a member of Slack channel ${channelId}, so a trigger cannot listen there.`;
return null;
}
export type TriggerDirectory = {
resolve(id: string): Promise<ResolvedTrigger | null>;
/** Slack listeners for one workspace, with their responsibility's Bot. */
slackTriggers(
teamId: string,
): Promise<(ResolvedTrigger & { agentId: string })[]>;
};
export function createTriggerStore(
database: Database,
vault: {
store: CredentialStore;
reader: CredentialSecretReader;
encryptionKey: string;
},
options: { slackAccess?: () => SlackAccess | undefined } = {},
) {
async function checkSlack(ownerUserId: string, config: TriggerConfig) {
if (config.kind !== "slack") return;
const refusal = await slackAccessAllows(
options.slackAccess?.(),
ownerUserId,
config.teamId,
config.channels,
);
if (refusal) throw new ResponsibilityRefusedError(refusal);
}
const columns = {
id: responsibilityTriggers.id,
responsibilityId: responsibilityTriggers.responsibilityId,
kind: responsibilityTriggers.kind,
config: responsibilityTriggers.config,
credentialId: responsibilityTriggers.credentialId,
enabled: responsibilityTriggers.enabled,
createdAt: responsibilityTriggers.createdAt,
updatedAt: responsibilityTriggers.updatedAt,
};
type Row = {
id: string;
responsibilityId: string;
kind: TriggerKind;
config: TriggerConfig;
credentialId: string | null;
enabled: boolean;
createdAt: Date;
updatedAt: Date;
};
const record = ({ credentialId, ...row }: Row): TriggerRecord => ({
...row,
hasSecret: credentialId !== null,
});
async function ownedGoal(ownerUserId: string, responsibilityId: string) {
const [goal] = await database
.select({ id: responsibilities.id })
.from(responsibilities)
.where(
and(
eq(responsibilities.id, responsibilityId),
eq(responsibilities.ownerUserId, ownerUserId),
),
);
if (!goal) throw new ResponsibilityNotFoundError();
}
async function ownedTrigger(ownerUserId: string, id: string) {
const [row] = await database
.select(columns)
.from(responsibilityTriggers)
.where(
and(
eq(responsibilityTriggers.id, id),
eq(responsibilityTriggers.ownerUserId, ownerUserId),
),
);
if (!row) throw new ResponsibilityNotFoundError();
return row;
}
function checkSecret(secret: string) {
if (!secret.trim() || secret.length > 4096)
throw new ResponsibilityRefusedError(
"Supply a secret of 1–4096 characters.",
);
return secret.trim();
}
async function secretFor(credentialId: string | null) {
if (!credentialId) return null;
const credential = await vault.reader.readSecret(credentialId);
if (!credential || credential.revokedAt) return null;
return decryptSecret(vault.encryptionKey, credential.encryptedValue);
}
async function resolved(
row: Row & { ownerUserId: string; status: ResponsibilityStatus },
) {
return {
id: row.id,
ownerUserId: row.ownerUserId,
responsibilityId: row.responsibilityId,
responsibilityStatus: row.status,
kind: row.kind,
config: row.config,
secret: await secretFor(row.credentialId),
enabled: row.enabled,
createdAt: row.createdAt,
};
}
const resolvedColumns = {
...columns,
ownerUserId: responsibilityTriggers.ownerUserId,
status: responsibilities.status,
agentId: responsibilities.agentId,
};
return {
async list(
ownerUserId: string,
responsibilityId: string,
): Promise<TriggerRecord[]> {
await ownedGoal(ownerUserId, responsibilityId);
const rows = await database
.select(columns)
.from(responsibilityTriggers)
.where(
and(
eq(responsibilityTriggers.ownerUserId, ownerUserId),
eq(responsibilityTriggers.responsibilityId, responsibilityId),
),
);
return rows.map(record);
},
/** Returns the secret once when OpenBot generated it; vendor secrets are pasted in `input.secret`. */
async create(
ownerUserId: string,
responsibilityId: string,
input: { config: unknown; secret?: string },
): Promise<{ trigger: TriggerRecord; secret: string | null }> {
const config = parseTriggerConfig(input.config);
await ownedGoal(ownerUserId, responsibilityId);
await checkSlack(ownerUserId, config);
const id = randomUUID();
const secret = GENERATED_SECRET.has(config.kind)
? generateWebhookSecret()
: SECRET_KINDS.has(config.kind) && input.secret
? checkSecret(input.secret)
: null;
return database.transaction(async (transaction) => {
const credential = secret
? await vault.store.create(
{
kind: "connector",
provider: `${config.kind}-trigger`,
keyId: id,
metadata: { ownerUserId, responsibilityId },
encryptedValue: await encryptSecret(
vault.encryptionKey,
secret,
),
},
transaction,
)
: null;
const [row] = await transaction
.insert(responsibilityTriggers)
.values({
id,
ownerUserId,
responsibilityId,
kind: config.kind,
config,
credentialId: credential?.id ?? null,
})
.returning(columns);
if (!row) throw new Error("Trigger creation returned no row.");
return {
trigger: record(row),
secret: GENERATED_SECRET.has(config.kind) ? secret : null,
};
});
},
async update(ownerUserId: string, id: string, input: { config: unknown }) {
const existing = await ownedTrigger(ownerUserId, id);
const config = parseTriggerConfig(input.config);
if (config.kind !== existing.kind)
throw new ResponsibilityRefusedError(
"A trigger cannot change kind. Add a new trigger.",
);
await checkSlack(ownerUserId, config);
const [row] = await database
.update(responsibilityTriggers)
.set({ config, updatedAt: new Date() })
.where(eq(responsibilityTriggers.id, id))
.returning(columns);
if (!row) throw new ResponsibilityNotFoundError();
return record(row);
},
async setEnabled(ownerUserId: string, id: string, enabled: boolean) {
await ownedTrigger(ownerUserId, id);
const [row] = await database
.update(responsibilityTriggers)
.set({ enabled, updatedAt: new Date() })
.where(eq(responsibilityTriggers.id, id))
.returning(columns);
if (!row) throw new ResponsibilityNotFoundError();
return record(row);
},
/** Every trigger on this owner's responsibilities carried out by one Bot (the chat tools' view). */
async listForAgent(ownerUserId: string, agentId: string) {
const rows = await database
.select({ ...columns, title: responsibilities.title })
.from(responsibilityTriggers)
.innerJoin(
responsibilities,
eq(responsibilities.id, responsibilityTriggers.responsibilityId),
)
.where(
and(
eq(responsibilityTriggers.ownerUserId, ownerUserId),
eq(responsibilities.agentId, agentId),
),
);
return rows.map(({ title, ...row }) => ({ ...record(row), title }));
},
/**
* Rotate: a new generated secret for webhook/GitHub, or the vendor's new pasted secret for
* Linear/Sentry/PagerDuty. The old credential is revoked in the same transaction.
*/
async setSecret(
ownerUserId: string,
id: string,
pasted?: string,
): Promise<{ trigger: TriggerRecord; secret: string | null }> {
const existing = await ownedTrigger(ownerUserId, id);
if (!SECRET_KINDS.has(existing.kind))
throw new ResponsibilityRefusedError(
"This trigger has no secret to rotate.",
);
const generated = GENERATED_SECRET.has(existing.kind);
if (!generated && !pasted)
throw new ResponsibilityRefusedError(
"Paste the signing secret from the provider.",
);
const secret = generated
? generateWebhookSecret()
: checkSecret(pasted ?? "");
const encryptedValue = await encryptSecret(vault.encryptionKey, secret);
return database.transaction(async (transaction) => {
const value = {
kind: "connector" as const,
provider: `${existing.kind}-trigger`,
keyId: id,
metadata: {
ownerUserId,
responsibilityId: existing.responsibilityId,
},
encryptedValue,
};
const credential = existing.credentialId
? await vault.store.rotate(
{ ...value, previousCredentialId: existing.credentialId },
transaction,
)
: await vault.store.create(value, transaction);
const [row] = await transaction
.update(responsibilityTriggers)
.set({ credentialId: credential.id, updatedAt: new Date() })
.where(eq(responsibilityTriggers.id, id))
.returning(columns);
if (!row) throw new ResponsibilityNotFoundError();
return { trigger: record(row), secret: generated ? secret : null };
});
},
/** The owner re-reading a generated secret (the page's copy button). Vendor secrets are never echoed. */
async revealSecret(ownerUserId: string, id: string): Promise<string> {
const existing = await ownedTrigger(ownerUserId, id);
if (!GENERATED_SECRET.has(existing.kind))
throw new ResponsibilityRefusedError(
"Provider secrets are not shown again. Paste a new one to rotate.",
);
const secret = await secretFor(existing.credentialId);
if (!secret)
throw new ResponsibilityRefusedError(
"This trigger has no live secret. Rotate it.",
);
return secret;
},
async remove(ownerUserId: string, id: string) {
await database.transaction(async (transaction) => {
const [row] = await transaction
.select(columns)
.from(responsibilityTriggers)
.where(
and(
eq(responsibilityTriggers.id, id),
eq(responsibilityTriggers.ownerUserId, ownerUserId),
),
)
.for("update");
if (!row) throw new ResponsibilityNotFoundError();
if (row.credentialId)
await vault.store.revoke(row.credentialId, transaction);
await transaction
.delete(responsibilityTriggers)
.where(eq(responsibilityTriggers.id, id));
});
},
directory: {
async resolve(id: string) {
if (!/^[0-9a-f-]{36}$/i.test(id)) return null;
const [row] = await database
.select(resolvedColumns)
.from(responsibilityTriggers)
.innerJoin(
responsibilities,
eq(responsibilities.id, responsibilityTriggers.responsibilityId),
)
.where(eq(responsibilityTriggers.id, id));
return row ? resolved(row) : null;
},
async slackTriggers(teamId: string) {
const rows = await database
.select(resolvedColumns)
.from(responsibilityTriggers)
.innerJoin(
responsibilities,
eq(responsibilities.id, responsibilityTriggers.responsibilityId),
)
.where(eq(responsibilityTriggers.kind, "slack"));
const matching = rows.filter(
(row) => row.config.kind === "slack" && row.config.teamId === teamId,
);
return Promise.all(
matching.map(async (row) => ({
...(await resolved(row)),
agentId: row.agentId,
})),
);
},
} satisfies TriggerDirectory,
};
}
export type TriggerStore = ReturnType<typeof createTriggerStore>;