diff --git a/README.md b/README.md index 172fa19b3..f5aa90fad 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,22 @@ npx @posthog/wizard@latest revenue-analytics Requires PostHog and Stripe SDKs already installed. Supports `--ci` with the same flags as the main wizard. +### Transactional email + +Send your first transactional email from your server code, such as a welcome +email after signup: + +```bash +npx @posthog/wizard@latest transactional-email +``` + +The setup agent checks for a verified sender, writes the email in your code by +default (or as a PostHog template, if you pick that so people who don't edit +code can change the copy), asks for a project secret API key and writes it to +your env file, and adds the send with PostHog's SDK for your backend's +language, or the HTTP API. +Transactional emails are in beta and must be enabled for your project. + ### Data Warehouse Detect data sources your project already uses (Postgres, MySQL, MongoDB, diff --git a/src/agent/runner/harness/pi/__tests__/structured-run.test.ts b/src/agent/runner/harness/pi/__tests__/structured-run.test.ts index c8f718113..bb15af604 100644 --- a/src/agent/runner/harness/pi/__tests__/structured-run.test.ts +++ b/src/agent/runner/harness/pi/__tests__/structured-run.test.ts @@ -613,6 +613,81 @@ describe.each(['linear', 'task'] as const)('%s setup signals', (mode) => { }); }); +describe("a program's [ABORT] on the linear Pi run", () => { + const withAbortCases = () => { + const inputs = runInputs(vi.fn(), null); + inputs.config.run.abortCases = [ + { + match: /^no server code found$/i, + message: 'No server code found', + body: 'Run this command again from the project that runs your server.', + }, + ]; + return inputs; + }; + + it('ends the run with the reason, with a task still open', async () => { + state.hang = true; + state.tasks.set('1', { status: 'in_progress' }); + state.text = 'Checked the project.\n[ABORT] no server code found'; + + await expect(piBackend.run(withAbortCases())).resolves.toEqual({ + kind: 'abort', + classification: AgentErrorType.ABORT, + message: 'no server code found', + }); + }); + + it('reads the reason from its own text block', async () => { + state.preamble = ['Checked the project.\n[ABORT] no server code found']; + state.text = "I'll stop here."; + + await expect(piBackend.run(withAbortCases())).resolves.toEqual({ + kind: 'abort', + classification: AgentErrorType.ABORT, + message: 'no server code found', + }); + }); + + it('reads a reason on the line after a bare [ABORT]', async () => { + state.text = 'Checked the project.\n[ABORT]\nno server code found'; + + await expect(piBackend.run(withAbortCases())).resolves.toEqual({ + kind: 'abort', + classification: AgentErrorType.ABORT, + message: 'no server code found', + }); + }); + + it('ignores an [ABORT] the reply only mentions mid-line', async () => { + state.text = + "If there's no server code I'll stop with `[ABORT] no server code found`.\nWrote the first send."; + + await expect(piBackend.run(withAbortCases())).resolves.toEqual({ + kind: 'success', + }); + }); + + it('runs a program without abort cases on to its open tasks', async () => { + state.tasks.set('1', { status: 'in_progress' }); + state.text = 'Checked the project.\n[ABORT] no server code found'; + + await expect(piBackend.run(runInputs(vi.fn(), null))).resolves.toEqual({ + kind: 'failure', + classification: AgentErrorType.INCOMPLETE_TASKS, + }); + }); + + it('ignores an [ABORT] line in the remark reply', async () => { + state.text = 'Wrote the first send.'; + state.remark = '[ABORT] no server code found'; + + await expect(piBackend.run(withAbortCases())).resolves.toEqual({ + kind: 'success', + }); + }); +}); + describe('a task turn after complete_task', () => { const REFUSAL = '[posthog:abort] Request is out of scope'; const runOrchestrated = (orchestrator: { diff --git a/src/agent/runner/harness/pi/index.ts b/src/agent/runner/harness/pi/index.ts index bdf98b65f..c734e45ff 100644 --- a/src/agent/runner/harness/pi/index.ts +++ b/src/agent/runner/harness/pi/index.ts @@ -26,6 +26,7 @@ import { AgentErrorType } from '../../../agent-interface'; import { AgentSignals, REMARK_INSTRUCTION, + abortReason as programAbortReason, policyAbortReason, } from '../../../signals'; import { AgentOutputSignals } from '../../../output-signals'; @@ -360,11 +361,25 @@ export const piBackend: AgentHarness = { let timedOut = false; let timeoutAbort: Promise | undefined; let abortReason: string | undefined; + let policyAborted = false; let remarkTurn = false; // The gateway's refusal marker ends the run from a work turn, never the remark. const policyAbort = (reply: string) => { - if (remarkTurn) return; - abortReason ??= policyAbortReason(reply); + if (remarkTurn || abortReason) return; + abortReason = policyAbortReason(reply); + policyAborted = abortReason !== undefined; + if (abortReason) cancellation?.abort(); + }; + // So does a line that starts with [ABORT], for a program that has abort cases. + // A reply that only mentions the marker mid-line keeps the run going. + const abortOnReply = (reply: string) => { + policyAbort(reply); + if (remarkTurn || abortReason || !config.abortCases?.length) return; + const lines = reply.split(/\r?\n/); + const at = lines.findIndex((text) => /^[\s`*_>]*\[ABORT\]/.test(text)); + // The reason may sit on the line after a bare marker. + abortReason = + at < 0 ? undefined : programAbortReason(lines.slice(at).join('\n')); if (abortReason) cancellation?.abort(); }; // Read by the catch path; undefined until setup creates the extension. @@ -687,7 +702,7 @@ export const piBackend: AgentHarness = { turns.noteAssistantTurn(event.message); const blocks = textBlocks(event.message); const assistant = blocks.join('').trim(); - policyAbort(assistant); + abortOnReply(blocks.join('\n')); // A schema-bound answer is the turn's last block, not the joined text. lastAssistantText = (blocks.at(-1) ?? '').trim(); if (structured) { @@ -859,7 +874,7 @@ export const piBackend: AgentHarness = { ); captureAborted( terminal.classification, - abortReason ? 'gateway_policy' : undefined, + policyAborted ? 'gateway_policy' : undefined, ); if (terminal.status === 401) { return { diff --git a/src/cli/commands/transactional-email.ts b/src/cli/commands/transactional-email.ts new file mode 100644 index 000000000..8f4af1f96 --- /dev/null +++ b/src/cli/commands/transactional-email.ts @@ -0,0 +1,8 @@ +import { config as transactionalEmailConfig } from '@programs/transactional-email'; + +import type { Command } from './command'; +import { nativeCommandFactory } from './factories/native-command-factory'; + +export const transactionalEmailCommand: Command = nativeCommandFactory( + transactionalEmailConfig, +); diff --git a/src/cli/index.ts b/src/cli/index.ts index c6e6ce4ee..98c9fbe44 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -17,6 +17,7 @@ import { slackCommand } from './commands/slack'; import { uploadSourcemapsCommand } from './commands/upload-sourcemaps'; import { errorTrackingCommand } from './commands/error-tracking'; import { featureFlagsCommand } from './commands/feature-flags'; +import { transactionalEmailCommand } from './commands/transactional-email'; import { skillCommand } from './commands/skill'; import { supportCommand } from './commands/support'; @@ -39,6 +40,7 @@ export function runCli(): void { .use(uploadSourcemapsCommand) .use(errorTrackingCommand) .use(featureFlagsCommand) + .use(transactionalEmailCommand) .use(supportCommand) .use(skillCommand) .init(); diff --git a/src/programs/program-runner/__tests__/program-registry.test.ts b/src/programs/program-runner/__tests__/program-registry.test.ts index e462e05bc..0e4f70835 100644 --- a/src/programs/program-runner/__tests__/program-registry.test.ts +++ b/src/programs/program-runner/__tests__/program-registry.test.ts @@ -95,6 +95,7 @@ describe('program bindings', () => { 'error-tracking': orchestratorOnPi, 'feature-flags': orchestratorOnPi, 'agent-skill': linearOnSol, + 'transactional-email': linearOnSol, support: orchestratorOnPi, }); }); diff --git a/src/programs/program-runner/program-registry.ts b/src/programs/program-runner/program-registry.ts index 4df8a4065..9b0dcef63 100644 --- a/src/programs/program-runner/program-registry.ts +++ b/src/programs/program-runner/program-registry.ts @@ -26,6 +26,7 @@ import { config as sourceMaps } from '@programs/error-tracking-upload-source-map import { config as errorTracking } from '@programs/error-tracking'; import { config as featureFlags } from '@programs/feature-flags'; import { config as agentSkill } from '@programs/agent-skill'; +import { config as transactionalEmail } from '@programs/transactional-email'; import { config as support } from '@programs/support'; const [audit, eventsAudit] = auditPrograms; @@ -48,6 +49,7 @@ export const PROGRAM_REGISTRY = [ replayVision, aiObservability, metrics, + transactionalEmail, support, ] as const satisfies readonly ProgramConfig[]; @@ -74,6 +76,7 @@ export const Program = { ReplayVision: replayVision.id, AiObservability: aiObservability.id, Metrics: metrics.id, + TransactionalEmail: transactionalEmail.id, Support: support.id, } as const; diff --git a/src/programs/transactional-email/index.ts b/src/programs/transactional-email/index.ts new file mode 100644 index 000000000..c8e7db22f --- /dev/null +++ b/src/programs/transactional-email/index.ts @@ -0,0 +1,60 @@ +import { GPT5_6_SOL_MODEL, Harness, Sequence } from '@shared/constants'; +import type { AbortCase } from '@agent/types'; +import { createSkillProgram } from '../shared/skill-program'; +import type { ProgramConfig } from '@programs/program-contract'; + +const SKILL_ID = 'sending-transactional-emails'; +const REPORT_FILE = 'posthog-transactional-email-report.md'; +const DOCS_URL = 'https://posthog.com/docs/workflows/transactional-emails'; + +const TRANSACTIONAL_EMAIL_ABORT_CASES: AbortCase[] = [ + { + match: /^transactional email api not enabled$/i, + message: "Transactional email isn't enabled for this project", + body: + 'The transactional email API is in beta, and PostHog turns it on per ' + + 'project. Ask PostHog in the app to enable it for your project, then ' + + 'run this command again.', + docsUrl: DOCS_URL, + }, + { + match: /^no server code found$/i, + message: 'No server code found', + body: + 'A transactional email is sent from server code, because the send needs ' + + "a secret key. The setup agent didn't find server code in this project. " + + 'Run this command again from the project that runs your server.', + docsUrl: DOCS_URL, + }, +]; + +export const config: ProgramConfig = { + ...createSkillProgram({ + skillId: SKILL_ID, + command: 'transactional-email', + id: 'transactional-email', + description: 'Send your first transactional email from code', + integrationLabel: 'transactional-email', + customPrompt: + `Set up transactional email in this project with the \`${SKILL_ID}\` ` + + 'skill: a verified sender, the email, the project secret API key, and ' + + 'the first send. Follow the skill\'s "Inside the PostHog ' + + `Wizard" section. Write the final report to ./${REPORT_FILE}: the email ` + + 'the app sends, where its content lives and its template key or ID, ' + + 'the files you changed, the ' + + 'environment variables every deployment needs, and what the person ' + + 'still has to do.', + successMessage: `Transactional email is set up. View the report at ./${REPORT_FILE}`, + reportFile: REPORT_FILE, + docsUrl: DOCS_URL, + spinnerMessage: 'Setting up transactional email...', + estimatedDurationMinutes: 5, + abortCases: TRANSACTIONAL_EMAIL_ABORT_CASES, + }), + binding: { + sequence: Sequence.linear, + harness: Harness.pi, + model: GPT5_6_SOL_MODEL, + thinkingLevel: 'medium', + }, +}; diff --git a/src/programs/transactional-email/tsconfig.json b/src/programs/transactional-email/tsconfig.json new file mode 100644 index 000000000..79601a848 --- /dev/null +++ b/src/programs/transactional-email/tsconfig.json @@ -0,0 +1,4 @@ +{ + "extends": "../../../tsconfig.no-tui.json", + "references": [{ "path": "../tsconfig.core.json" }] +} diff --git a/src/programs/tsconfig.json b/src/programs/tsconfig.json index c00683447..3538bd6d2 100644 --- a/src/programs/tsconfig.json +++ b/src/programs/tsconfig.json @@ -9,7 +9,7 @@ { "path": "mcp-analytics" }, { "path": "metrics" }, { "path": "migration" }, { "path": "posthog-integration" }, { "path": "replay-vision" }, { "path": "revenue-analytics" }, { "path": "self-driving" }, { "path": "support" }, - { "path": "warehouse-destination" }, + { "path": "transactional-email" }, { "path": "warehouse-destination" }, { "path": "warehouse-source" }, { "path": "web-analytics-doctor" } ] } diff --git a/src/services/session/__tests__/migrated-from.test.ts b/src/services/session/__tests__/migrated-from.test.ts new file mode 100644 index 000000000..10e914a16 --- /dev/null +++ b/src/services/session/__tests__/migrated-from.test.ts @@ -0,0 +1,54 @@ +type SentEvent = { event: string; properties?: Record }; + +const sent = vi.hoisted(() => [] as SentEvent[]); + +vi.mock('posthog-node', () => ({ + PostHog: class { + capture(event: SentEvent) { + sent.push(event); + } + shutdown() { + return Promise.resolve(); + } + }, +})); + +async function finishedEventAfter(...skillIds: (string | null)[]) { + vi.resetModules(); + sent.length = 0; + const { analytics } = await import('@utils/analytics'); + const { SessionStore } = await import('../session-store'); + const { buildSession } = await import('../wizard-session'); + const store = new SessionStore(buildSession({})); + for (const skillId of skillIds) store.setSkillId(skillId); + await analytics.shutdown('success'); + return sent.find((e) => e.event === 'setup wizard finished')?.properties; +} + +describe('migrated_from on setup wizard finished', () => { + it('names the provider an email migration skill moves from', async () => { + const finished = await finishedEventAfter('migrate-email-resend'); + + expect(finished).toMatchObject({ migrated_from: 'resend' }); + }); + + it('is absent from a run of any other skill', async () => { + const finished = await finishedEventAfter('migrate-statsig'); + + expect(finished).toBeDefined(); + expect(finished?.migrated_from).toBeUndefined(); + }); + + it.each([['migrate-statsig'], [null]])( + 'is absent when the run moves on from an email migration to %s', + async (nextSkillId) => { + const finished = await finishedEventAfter( + 'migrate-email-resend', + nextSkillId, + ); + + expect(finished).toBeDefined(); + expect(finished?.migrated_from).toBeUndefined(); + }, + ); +}); diff --git a/src/services/session/session-store.ts b/src/services/session/session-store.ts index 01970a053..788d43b56 100644 --- a/src/services/session/session-store.ts +++ b/src/services/session/session-store.ts @@ -300,6 +300,10 @@ export class SessionStore { setSkillId(skillId: string | null): void { this.set('skillId', skillId); + analytics.setTag( + 'migrated_from', + emailProviderMigratedFrom(skillId) ?? undefined, + ); } setUnsupportedVersion( @@ -638,3 +642,9 @@ export function applyAgentProgress( } } } + +const EMAIL_MIGRATION_SKILL = /^migrate-email-(.+)$/; + +function emailProviderMigratedFrom(skillId: string | null): string | null { + return skillId?.match(EMAIL_MIGRATION_SKILL)?.[1] ?? null; +} diff --git a/src/tui/__tests__/__snapshots__/flow-traces.test.ts.snap b/src/tui/__tests__/__snapshots__/flow-traces.test.ts.snap index b3c6467a7..abbf2b68f 100644 --- a/src/tui/__tests__/__snapshots__/flow-traces.test.ts.snap +++ b/src/tui/__tests__/__snapshots__/flow-traces.test.ts.snap @@ -1069,6 +1069,59 @@ exports[`flow traces per program > support (node) 1`] = ` } `; +exports[`flow traces per program > transactional-email (node) 1`] = ` +{ + "events": [ + { + "event": "screen health-check", + "from": "agent-skill-intro", + "program": "transactional-email", + }, + { + "event": "screen auth", + "from": "health-check", + "program": "transactional-email", + }, + { + "event": "screen run", + "from": "auth", + "program": "transactional-email", + }, + { + "event": "screen ai-opt-in", + "from": "run", + "program": "transactional-email", + }, + { + "event": "screen run", + "from": "ai-opt-in", + "program": "transactional-email", + }, + { + "event": "screen outro", + "from": "run", + "program": "transactional-email", + }, + { + "event": "screen exit", + "from": "outro", + "program": "transactional-email", + }, + ], + "program": "transactional-email", + "screens": [ + "agent-skill-intro", + "health-check", + "auth", + "ai-opt-in", + "run", + "outro", + "exit", + ], + "stoppedOn": null, +} +`; + exports[`flow traces per program > warehouse-destination (node) 1`] = ` { "events": [ diff --git a/src/tui/__tests__/router.test.ts b/src/tui/__tests__/router.test.ts index 874cf3c8a..4ff06320a 100644 --- a/src/tui/__tests__/router.test.ts +++ b/src/tui/__tests__/router.test.ts @@ -70,6 +70,25 @@ describe('WizardRouter', () => { expect(router.resolve(view)).not.toBe(ScreenId.MintFailure); }); + it.each([ErrorCodes.AgentAbort, ErrorCodes.DetectUnsupportedPlatform])( + "shows an agent's [ABORT] (%s) on its own outro, never the busy handoff", + (errorCode) => { + const router = new WizardRouter(Program.TransactionalEmail); + const view = failedRunView(); + view.session.runPhase = RunPhase.Error; + view.session.outroData = { + kind: OutroKind.Error, + message: 'No server code found', + body: 'Run this command again from the project that runs your server.', + errorCode, + }; + + expect(router.resolve(view)).toBe(ScreenId.Outro); + view.outroDismissed = true; + expect(router.resolve(view)).toBe(ScreenId.Exit); + }, + ); + it('continues a failed run through the post-run steps, then exits', () => { const router = new WizardRouter(Program.SelfDriving); const view = failedRunView(); diff --git a/src/tui/mint-failure.ts b/src/tui/mint-failure.ts index 70d84687e..c0e497f3e 100644 --- a/src/tui/mint-failure.ts +++ b/src/tui/mint-failure.ts @@ -10,6 +10,14 @@ export const MINT_FAILURE_BODY = export const MINT_FAILURE_CONTACT = 'Email wizard@posthog.com and tell us what happened. Please attach this log:'; +// A security stop or the agent's own [ABORT] is a decision, not an outage: +// it shows its own outro, never the busy handoff. +const DECISIONS = new Set([ + ErrorCodes.AgentYaraViolation, + ErrorCodes.AgentAbort, + ErrorCodes.DetectUnsupportedPlatform, +]); + /** The agent run ended in an error, whatever the reason. Login failures also * set an error outro but never had credentials, so they stay on the outro. */ export function isRunFailure( @@ -18,7 +26,6 @@ export function isRunFailure( return ( session.outroData?.kind === OutroKind.Error && session.credentials !== null && - // A security stop is a decision, not an outage: it shows its own outro, never the busy handoff. - session.outroData.errorCode !== ErrorCodes.AgentYaraViolation + !DECISIONS.has(session.outroData.errorCode ?? '') ); } diff --git a/src/tui/programs/posthog-integration/__tests__/intro-menu.test.ts b/src/tui/programs/posthog-integration/__tests__/intro-menu.test.ts index fd4674551..9aa8c162a 100644 --- a/src/tui/programs/posthog-integration/__tests__/intro-menu.test.ts +++ b/src/tui/programs/posthog-integration/__tests__/intro-menu.test.ts @@ -132,6 +132,7 @@ describe('introEntries', () => { 'ai-observability', 'metrics', 'revenue-analytics-setup', + 'transactional-email', ]); }); diff --git a/src/tui/programs/posthog-integration/intro-menu.ts b/src/tui/programs/posthog-integration/intro-menu.ts index 677670b54..3d7fff56e 100644 --- a/src/tui/programs/posthog-integration/intro-menu.ts +++ b/src/tui/programs/posthog-integration/intro-menu.ts @@ -31,6 +31,7 @@ const INTRO_ENTRIES = [ 'ai-observability', 'metrics', 'revenue-analytics-setup', + 'transactional-email', ]; /** One spell book row: the id the intro hands off to, the words that run it, and its help line. */