@flow-engineer/flow 0.2.3 → 0.3.1

package/dist/testing/src/cli.js

@@ -32,7 +32,7 @@ import { request as httpsRequest } from "node:https";
 import { basename, dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
-import { hasModelKey, NO_MODEL_KEY } from "../../src/model.js";
+import { hasModelKey } from "../../src/model.js";
 import { PLUGIN_LINE, pluginCli } from "./plugin.js";
 import { OBSERVE_URL, setting } from "../../src/traces.js";
 import { cloudHeaders, runInCloud, SessionStopped } from "./client.js";
@@ -122,10 +122,11 @@ const USAGE = `Usage:\n${NEW_LINE}\n${CHAT_LINE}\n${TEST_LINE}\n${SHOW_LINE}\n${
 ${PLUGIN_LINE}\n${ACCOUNT_LINES}\n  flow --version         Show the version\n\n${TEST_OPTIONS}`;
 /** What to do after new or init, from step 2; a model key comes first when none is set here. */
 function nextSteps() {
+    // link signs in and writes the keys first, FLOW_KEY (the model, on Flow's free trial credit) among
+    // them, so npm start comes after it and has the model key and the channels from its first start.
     const steps = [
-        ...(hasModelKey(process.env) ? [] : [`Model key: none yet. ${NO_MODEL_KEY.nextLine.replace(/^Next: r/, "R")} (in .env: cp .env.example .env; the file says where to make one)`]),
-        `npm start, and open the link it prints: try it in the playground as its test people, channels side by side`,
-        `npx @flow-engineer/flow link: signs in, writes the other keys, prints the link for your phone;\n     keep npm start running and text it`,
+        `npx @flow-engineer/flow link --channel telegram (or whatsapp, imessage): signs in, writes the keys\n     into .env (FLOW_KEY pays for the model on Flow's free trial credit; ${hasModelKey(process.env) ? "your own model key in .env still wins" : "or put your own model key in .env"}) and prints the link for your phone`,
+        `npm start, and open the link it prints: try it in the playground as its test people, channels side by side;\n     keep it running and text it from your phone`,
         `Tell your coding agent what to build: its skills are in .claude/skills/`,
     ];
     return steps.map((step, i) => `  ${i + 2}. ${step}`).join("\n");
@@ -203,7 +204,7 @@ async function askDisplayName(given, packageName) {
 }
 const namedLine = (dir) => {
     const displayName = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).displayName;
-    return `People call it "${displayName}" (package.json displayName): a phone reaches it with "Hi ${displayName} (ref <code>)".`;
+    return `People call it "${displayName}" (package.json displayName, and its prompt agent/AGENTS.md): a phone reaches it with "Hi ${displayName} (ref <code>)".`;
 };
 const displayNameFlag = values["display-name"];
 if (command === "new") {
@@ -218,7 +219,7 @@ if (command === "new") {
         console.error(error.message);
         process.exit(1);
     }
-    console.log(`Made ./${name}/ from the café example (Pip). ${namedLine(dir)} Next:
+    console.log(`Made ./${name}/ from the café example. ${namedLine(dir)} Next:
   1. cd ${name} && npm install
 ${nextSteps()}`);
     process.exit(0);
@@ -235,7 +236,7 @@ if (command === "init") {
         process.exit(1);
     }
     loadEnv(undefined); // a .env already here may hold a model key
-    console.log(`Made ${name}, started from the café example (Pip), in this folder. ${namedLine(process.cwd())} Next:
+    console.log(`Made ${name}, started from the café example, in this folder. ${namedLine(process.cwd())} Next:
   1. npm install
 ${nextSteps()}`);
     process.exit(0);
@@ -303,7 +304,8 @@ else {
     if (typeof module.buildAgent !== "function" || !Array.isArray(module.tools)) {
         invalid("src/agent.ts must export buildAgent({ model, events, tools }) and tools, or pass --agent-url to test an agent by its HTTP endpoint.");
     }
-    agent = { tools: module.tools, build: ({ tools, events }) => module.buildAgent({ tools, events }) };
+    // A business run's agent also gets its channels and clock (testing/src/business.ts); buildAgent passes them on to createAgent.
+    agent = { tools: module.tools, build: ({ tools, events, channels, testing }) => module.buildAgent({ tools, events, ...(channels ? { channels, testing } : {}) }) };
 }
 /** With --agent-url the agent's own tools run for real: the suite's tool simulators do not apply. */
 function forUrl(files) {

package/dist/testing/src/client.d.ts

@@ -1,6 +1,7 @@
 import { type Agent, type EventSink, type Tool } from "../../src/index.ts";
 import type { Opened, RunSummary, SessionSummary } from "./protocol.ts";
 import { type SuiteFile } from "./suite.ts";
+import { type BusinessBuild } from "./business.ts";
 export interface ConnectOptions {
     /** The cloud's address, such as http://127.0.0.1:8900. */
     cloud: string;
@@ -10,11 +11,12 @@ export interface ConnectOptions {
     title?: string;
     /** The agent's real tools: only their names, descriptions and inputs are used. */
     tools: Tool[];
-    /** Builds the agent with the tools and events it is given: a Flow Framework Agent, or anything that answers like one (http-agent.ts). */
+    /** Builds the agent with the tools and events it is given: a Flow Framework Agent, or anything that answers like one (http-agent.ts).
+     * A business run (protocol.ts) builds one more per run, with its own channels and clock (`BusinessBuild`); that needs a Flow Framework Agent. */
     build: (options: {
         tools: Tool[];
         events: EventSink[];
-    }) => AgentUnderTest;
+    } & Partial<BusinessBuild>) => AgentUnderTest;
     files: SuiteFile[];
     /** The tests folder: files a scenario attaches are read from here, and never leave this machine. */
     testsDir?: string;

package/dist/testing/src/client.js

@@ -10,6 +10,7 @@ import { toSpec } from "../../src/index.js";
 import { PROFILE_TOOL, profileTool } from "../../src/conversation.js";
 import { STAND_IN } from "../../src/tools.js";
 import { mimeOf, parseScenario, parseToolFile, suiteHash } from "./suite.js";
+import { businessRuns } from "./business.js";
 /** The session opened, then the cloud ended it with a `failed` command. `code` is the reason's leading
  * code (`capacity: ...` gives capacity), when it starts with one. */
 export class CloudEnded extends Error {
@@ -351,6 +352,8 @@ async function playSession(options, only) {
     events.context = true;
     try {
         const agent = options.build({ tools, events: [events] });
+        // Business runs need an agent of this framework: its own channels, routes, clock and nudges.
+        const canBusiness = typeof agent.reach === "function" && typeof agent.fetch === "function";
         const open = {
             agent: { name: options.name, title: options.title, tools: [...options.tools, ...(agent.hasProfile?.() ? standIn : [])].map(toSpec), channels: agent.channels() },
             files: options.files.map(({ path, hash }) => ({ path, hash })),
@@ -359,6 +362,7 @@ async function playSession(options, only) {
             retries: true,
             resume: true,
             reopen: true,
+            ...(canBusiness ? { business: true } : {}),
             ...(only ? { only } : {}),
         };
         const opened = await openOnce(`${base}/api/sessions`, open, options.openHeaders, controller.signal, postTimeoutMs, openRetryCapMs, log);
@@ -382,6 +386,20 @@ async function playSession(options, only) {
         options.onDashboard?.(dashboard, opened.sessionId, typeof opened.agent === "string" && opened.agent ? opened.agent : undefined);
         log(`Watch it: ${opened.dashboard}`);
         session = `${tunnel}/api/sessions/${opened.sessionId}`;
+        const business = canBusiness && opened.business === true
+            ? businessRuns({
+                sessionAgent: agent,
+                build: (built) => options.build(built),
+                tunnelTools: tools,
+                realTools: options.tools,
+                events,
+                post: (path, body, key, what) => postRetry(`${session}/${path}`, body, auth, controller.signal, log, postTimeoutMs, {
+                    mode: idempotent ? "idempotent" : path === "outbound" ? "outbound" : "never", key, budgetMs: retryBudgetMs, what,
+                }),
+                watch,
+                log,
+            })
+            : null;
         if (failure)
             throw failure;
         startFlush();
@@ -447,6 +465,8 @@ async function playSession(options, only) {
         const handle = async (command) => {
             if (draining && (command.type === "message" || command.type === "reaction"))
                 throw new Error("the cloud sent a command after drain");
+            if (business && (business.handle(command, (incoming) => withFiles(incoming, options.testsDir, log))))
+                return;
             if (command.type === "message") {
                 const deliveries = [];
                 // Not async: register the promise during receive(), before its fire-and-forget

package/dist/testing/src/index.d.ts

@@ -1,3 +1,3 @@
 export { runInCloud, type CloudSummary, type ConnectOptions } from "./client.ts";
-export { hashOf, loadSuite, parseScenario, parseToolFile, suiteHash, type Scenario, type SuiteFile, type ToolFile } from "./suite.ts";
-export type { Check, Command, OpenSession, Opened, RunKey, RunSummary, SessionSummary, ToolCallRequest, ToolCallResult, UploadFile, Usage, WireIncoming } from "./protocol.ts";
+export { hashOf, isBusiness, loadSuite, parseScenario, parseToolFile, suiteHash, waitMs, type OpeningStep, type Scenario, type SentItem, type SuiteFile, type ToolFile } from "./suite.ts";
+export type { BusinessCommand, BusinessNudge, BusinessOutbound, Check, Command, FlowEventEnvelope, StepAnswer, OpenSession, Opened, RunKey, RunSummary, SessionSummary, ToolCallRequest, ToolCallResult, UploadFile, Usage, WireIncoming } from "./protocol.ts";

package/dist/testing/src/index.js

@@ -1,2 +1,2 @@
 export { runInCloud } from "./client.js";
-export { hashOf, loadSuite, parseScenario, parseToolFile, suiteHash } from "./suite.js";
+export { hashOf, isBusiness, loadSuite, parseScenario, parseToolFile, suiteHash, waitMs } from "./suite.js";

package/dist/testing/src/new.d.ts

@@ -6,6 +6,15 @@ export declare function packageRoot(from?: string): string;
 export declare const MAX_DISPLAY_NAME = 60;
 /** The name people call the agent, from the package name when none was given: "my-shop" is "my shop". */
 export declare function displayNameOf(given: string | undefined, packageName: string): string;
+/**
+ * Renames the agent in `dir`: package.json's displayName, and in its prompt the old display name
+ * (and the café's Pip) become the new one. Returns the name and whether the prompt changed (a prompt
+ * rewritten by hand may name neither).
+ */
+export declare function setDisplayName(dir: string, given: string): {
+    displayName: string;
+    prompt: boolean;
+};
 interface MakeOptions {
     root?: string;
     /** What people call the agent; the package name in words when not given. */

package/dist/testing/src/new.js

@@ -1,10 +1,13 @@
-// `flow new <name>`: makes ./<name>/, an agent of its own started from the café example (Pip),
+// `flow new <name>`: makes ./<name>/, an agent of its own started from the café example,
 // that depends on the @flow-engineer/flow package. Its imports become "@flow-engineer/flow",
 // "@flow-engineer/flow/simulators" and "@flow-engineer/flow/flow-messaging", and the coding-agent
 // skills go in .claude/skills/, with an AGENTS.md (and a CLAUDE.md importing it) pointing at them.
 // `flow init` makes the same agent in the current folder. Inside a clone, `npm run new -- <name>`
 // makes agents/<name>/ instead. `--display-name` is what people call the agent ("FlatX agent"), kept
 // as package.json's displayName: the message a phone sends to reach it is "Hi <it> (ref <code>)".
+// The café's agent is Pip; the display name takes Pip's place in its prompt (agent/AGENTS.md), and
+// its playground and MCP server read the name from package.json. `flow link --display-name` (and
+// `setup`) renames an agent made already, the same way (setDisplayName).
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -66,13 +69,15 @@ FLOW_FRAMEWORK_TRACES_KEY=
 `;
 const agentsMd = (name) => `# ${name}
 
-A chat agent on Flow Framework (https://github.com/flow-engineer/flow), started from its café example (Pip).
+A chat agent on Flow Framework (https://github.com/flow-engineer/flow), started from its café example.
 
 - Load the skills in \`.claude/skills/\` before changing it: \`flow-framework\` to build the agent (and its MCP
   server and CLI), \`flow-framework-tools\` for its tools and their test files, \`flow-framework-tests\` for its test
   scenarios, \`flow-framework-context\` to gather what the tools are written from out of an existing
   codebase, and \`flow-framework-auth\` for sign-in.
-- \`agent/AGENTS.md\` is the agent's own prompt, not instructions for coding agents.
+- \`agent/AGENTS.md\` is the agent's own prompt, not instructions for coding agents. What people call
+  the agent is package.json's \`displayName\`; \`npx @flow-engineer/flow link --display-name <name>\`
+  changes it there and in that prompt.
 - The model key goes in \`.env\` (never read or print it): \`npx @flow-engineer/flow link\` (or \`setup\`)
   writes \`FLOW_KEY\`, the agent's one Flow key, which calls models on Flow's free trial credit, so no provider key is needed; a key the owner types
   (\`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`) wins over it. \`npm start\` runs it in the playground,
@@ -97,6 +102,39 @@ export function displayNameOf(given, packageName) {
         throw new Error(`--display-name is at most ${MAX_DISPLAY_NAME} characters, such as "FlatX agent".`);
     return name || packageName.replace(/-/g, " ");
 }
+/** The café's name for its agent, in its prompt; a new agent's display name takes its place. */
+const TEMPLATE_NAME = "Pip";
+/** Puts `to` in place of each of `from` (whole words, the longest first, in one pass) in the agent's prompt; true when it changed. */
+function renameInPrompt(dir, from, to) {
+    const file = join(dir, "agent", "AGENTS.md");
+    const names = [...new Set(from.filter((n) => n && n !== to))].sort((a, b) => b.length - a.length);
+    if (!names.length || !existsSync(file))
+        return false;
+    const text = readFileSync(file, "utf8");
+    const word = new RegExp(`(?<![\\p{L}\\p{N}_])(?:${names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(?![\\p{L}\\p{N}_])`, "gu");
+    const renamed = text.replace(word, () => to);
+    if (renamed === text)
+        return false;
+    writeFileSync(file, renamed);
+    return true;
+}
+/**
+ * Renames the agent in `dir`: package.json's displayName, and in its prompt the old display name
+ * (and the café's Pip) become the new one. Returns the name and whether the prompt changed (a prompt
+ * rewritten by hand may name neither).
+ */
+export function setDisplayName(dir, given) {
+    const file = join(dir, "package.json");
+    const pkg = JSON.parse(readFileSync(file, "utf8"));
+    const displayName = displayNameOf(given, pkg.name ?? folderName(dir));
+    const before = typeof pkg.displayName === "string" ? pkg.displayName : "";
+    if (before !== displayName) {
+        // displayName stays right after name, where flow init puts it.
+        const { name, displayName: _, ...rest } = pkg;
+        writeFileSync(file, `${JSON.stringify({ ...(name !== undefined ? { name } : {}), displayName, ...rest }, null, 2)}\n`);
+    }
+    return { displayName, prompt: renameInPrompt(dir, [before, TEMPLATE_NAME], displayName) };
+}
 /** Makes `<into>/<name>` (the current folder by default) and returns it. */
 export function newStandalone(name, options = {}) {
     checkName(name);
@@ -126,6 +164,7 @@ function makeAgent(dir, name, displayName, root) {
     const cafe = join(root, "examples", "cafe");
     for (const part of ["agent", "src", "tests"])
         cpSync(join(cafe, part), join(dir, part), { recursive: true });
+    renameInPrompt(dir, [TEMPLATE_NAME], displayName);
     for (const file of readdirSync(join(dir, "src"), { recursive: true, encoding: "utf8" }).filter((f) => f.endsWith(".ts"))) {
         const path = join(dir, "src", file);
         const source = readFileSync(path, "utf8")
@@ -134,8 +173,8 @@ function makeAgent(dir, name, displayName, root) {
             .replace(/(["'])(\.\.\/)+flow-messaging\/src\/index\.ts\1/g, '"@flow-engineer/flow/flow-messaging"')
             .replace(/(["'])(\.\.\/)+mcp\/src\/index\.ts\1/g, '"@flow-engineer/flow/mcp"')
             .replace(/(["'])(\.\.\/)+cli\/src\/index\.ts\1/g, '"@flow-engineer/flow/cli"');
-        // The CLI is the agent's own command, named after it.
-        const text = file === "cli.ts" ? source.replace(/name: "cafe"/, `name: "${name}"`).replace(/CAFE_SERVER/g, `${name.toUpperCase().replace(/-/g, "_")}_SERVER`) : source;
+        // The CLI is the agent's own command, named after it (and so is its server's setting, which mcp.ts names too).
+        const text = (file === "cli.ts" ? source.replace(/name: "cafe"/, `name: "${name}"`) : source).replace(/CAFE_SERVER/g, `${name.toUpperCase().replace(/-/g, "_")}_SERVER`);
         if (/["']\.\.\/\.\.\//.test(text))
             throw new Error(`flow: ${file} imports a file outside the agent; only Flow Framework's public entries can be rewritten.`);
         writeFileSync(path, text);

package/dist/testing/src/protocol.d.ts

@@ -1,4 +1,4 @@
-import type { Attachment, ChannelInfo, ChannelSummary, Incoming, ToolSpec } from "../../src/index.ts";
+import type { Attachment, ChannelInfo, ChannelSummary, Incoming, Outbound, Template, ToolSpec } from "../../src/index.ts";
 /** One graded expect item of a run. */
 export interface Check {
     kind: "outcome" | "judge";
@@ -35,6 +35,8 @@ export interface OpenSession {
     resume?: boolean;
     /** The client opens one new session for the unfinished runs when this cloud says session_gone. */
     reopen?: boolean;
+    /** The client plays business runs (open, event, nudge, advance, close). */
+    business?: boolean;
     /** Play only these runs, numbered as given: a re-open after session_gone. Sent only to a cloud whose Opened said reopen,
      * and only when some run finished: the cloud checks it against the suite's files it already stores. */
     only?: RunKey[];
@@ -67,6 +69,8 @@ export interface Opened {
     resume?: boolean;
     /** This cloud answers session_gone for a session it lost, and plays `only` on an open. Absent on an older cloud. */
     reopen?: boolean;
+    /** This cloud plays business runs; the client sent `business`. Absent on an older cloud. */
+    business?: boolean;
 }
 export interface UploadFile {
     hash: string;
@@ -98,7 +102,101 @@ export type Command = {
  | {
     type: "failed";
     error: string;
+} | BusinessCommand;
+/**
+ * A business run's commands. `step` numbers the run's business commands from 1 in the order the
+ * cloud sends them (`open` is 0; a step with `at:` is an `advance` and then its own command); its
+ * StepAnswer carries the same number. The client treats it as opaque.
+ */
+export type BusinessCommand = 
+/** A run starts: build its agent with its clock at `now` (epoch ms). The person is `address` on `channelName`;
+ * `realTools` run the agent's own code in place of the cloud's simulation. */
+{
+    type: "open";
+    conversationId: string;
+    channelName: string;
+    channel: ChannelInfo;
+    address: string;
+    now: number;
+    realTools?: string[];
+}
+/** The business's backend sends an event: POST `path` (default /v1/events) to the agent's own routes with this
+ * envelope as the body, signed with the run's test secret (`signature` bad: with another secret; missing: no header). */
+ | {
+    type: "event";
+    conversationId: string;
+    step: number;
+    envelope: FlowEventEnvelope;
+    path?: string;
+    signature?: "bad" | "missing";
+}
+/** The business nudges the run's person. */
+ | {
+    type: "nudge";
+    conversationId: string;
+    step: number;
+    nudge: BusinessNudge;
+}
+/** Time passes: the clock moves to `to` (epoch ms), a minute at a time, and what came due runs at each step. */
+ | {
+    type: "advance";
+    conversationId: string;
+    step: number;
+    to: number;
+}
+/** The run is over: its agent is dropped. */
+ | {
+    type: "close";
+    conversationId: string;
 };
+/** A Flow event as a business's backend sends it: one envelope for every type. */
+export interface FlowEventEnvelope {
+    /** Unique per event; the agent processes one id once. */
+    id: string;
+    type: string;
+    /** ISO 8601. */
+    occurredAt: string;
+    /** What it is about: "user:<id>", "listing:<slug>". */
+    subject: string;
+    /** How binding a send it asks for, e.g. critical, standard or optional; the agent decides what each means. */
+    delivery?: string;
+    data: Record<string, unknown>;
+}
+/** A nudge as a scenario writes it; `to` is the run's person. */
+export interface BusinessNudge {
+    text?: string;
+    prompt?: string;
+    template?: Template;
+    respectQuietHours?: boolean;
+    /** Epoch ms. */
+    expiresAt?: number;
+    idempotencyKey?: string;
+}
+/** What one business step came to. */
+export interface StepAnswer {
+    conversationId: string;
+    step: number;
+    /** The agent's HTTP answer to an event. */
+    answer?: {
+        status: number;
+        body: unknown;
+    };
+    /** A nudge's result. */
+    nudge?: {
+        status: string;
+        reason?: string;
+    };
+    /** The run's clock when the step settled, epoch ms. */
+    at: number;
+    /** The step could not be played on the agent's side (the agent threw, no such route ...). */
+    error?: string;
+}
+/** A business run's outbound: what the agent sent, and when on the run's clock. */
+export interface BusinessOutbound {
+    conversationId: string;
+    outbound: Outbound;
+    at: number;
+}
 /**
  * A person's message as it travels: a scenario's file goes by its path in the tests folder, and the
  * agent's side reads it there, so the file never leaves the developer's machine.

package/dist/testing/src/protocol.js

@@ -13,6 +13,15 @@
 // says idempotency, a repeat of a key is the stored answer and the client may send it again.
 //   POST /api/sessions/:id/receipts    Receipt → { ok }
 //   POST /api/sessions/:id/drained     {} → { ok }   flush before the terminal command
+//   POST /api/sessions/:id/steps       StepAnswer → { ok }   a business run's step done (below)
+//
+// Business runs (both sides said `business`): a scenario the business starts, with an event its
+// backend sends, a nudge, or time passing on the test's clock. Each such run gets an agent of its
+// own on the agent's side, built with a clock the commands move (its own `now`, no schedule timer),
+// and the agent's own channels, whose sends come to the cloud as an outbound with `at`, the run's
+// clock. The cloud sends `open` first, then any of `message`, `reaction`, `event`, `nudge`,
+// `advance`, and `close` when the run is over. `open`, `event`, `nudge` and `advance` are each
+// answered by one StepAnswer once the agent has settled: everything they set off has been sent.
 //
 // When Opened says resume, every command on the stream carries `id: N` (1, 2, 3, ... per session).
 // A stream that drops, or sits silent past the idle watch, is opened again with Last-Event-ID set

package/dist/testing/src/suite.d.ts

@@ -21,6 +21,15 @@ declare const expectedCall: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     tool: z.ZodString;
     args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>]>;
+/** A wait's length in ms, or null when it is not one. */
+export declare function waitMs(text: string): number | null;
+/** One thing the agent sent (`expect.sent`), or must not have (`expect.not_sent`; `{}` is anything at all). */
+declare const sentItem: z.ZodObject<{
+    at: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+    phrased: z.ZodOptional<z.ZodLiteral<true>>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 declare const scenarioSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -34,12 +43,13 @@ declare const scenarioSchema: z.ZodObject<{
     timezone: z.ZodOptional<z.ZodString>;
     now: z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>;
     person: z.ZodObject<{
+        address: z.ZodOptional<z.ZodString>;
         persona: z.ZodString;
         goal: z.ZodString;
         knows: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
-    opening: z.ZodArray<z.ZodObject<{
-        say: z.ZodDefault<z.ZodString>;
+    opening: z.ZodArray<z.ZodPipe<z.ZodObject<{
+        say: z.ZodOptional<z.ZodString>;
         attach: z.ZodOptional<z.ZodObject<{
             kind: z.ZodEnum<{
                 audio: "audio";
@@ -49,7 +59,120 @@ declare const scenarioSchema: z.ZodObject<{
             file: z.ZodString;
         }, z.core.$strip>>;
         after_ms: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>;
+        event: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+            occurredAt: z.ZodOptional<z.ZodString>;
+            subject: z.ZodString;
+            delivery: z.ZodOptional<z.ZodString>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>>;
+        path: z.ZodOptional<z.ZodString>;
+        signature: z.ZodOptional<z.ZodEnum<{
+            bad: "bad";
+            missing: "missing";
+        }>>;
+        answer: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            status: z.ZodNumber;
+            field: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>;
+        nudge: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            prompt: z.ZodOptional<z.ZodString>;
+            template: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                language: z.ZodOptional<z.ZodString>;
+                body: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    index: z.ZodNumber;
+                    value: z.ZodString;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+            respectQuietHours: z.ZodOptional<z.ZodBoolean>;
+            expiresAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        wait: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodTransform<{
+        say?: string | undefined;
+        attach?: {
+            kind: "audio" | "document" | "image";
+            file: string;
+        } | undefined;
+        after_ms?: number | undefined;
+        event?: {
+            id?: string | undefined;
+            type: string;
+            occurredAt?: string | undefined;
+            subject: string;
+            delivery?: string | undefined;
+            data: Record<string, unknown>;
+        } | undefined;
+        path?: string | undefined;
+        signature?: "bad" | "missing" | undefined;
+        answer?: number | {
+            status: number;
+            field?: string | undefined;
+        } | undefined;
+        nudge?: {
+            text?: string | undefined;
+            prompt?: string | undefined;
+            template?: {
+                name: string;
+                language?: string | undefined;
+                body?: string[] | undefined;
+                buttons?: {
+                    index: number;
+                    value: string;
+                }[] | undefined;
+            } | undefined;
+            respectQuietHours?: boolean | undefined;
+            expiresAt?: string | undefined;
+        } | undefined;
+        wait?: string | undefined;
+        at?: string | undefined;
+    }, {
+        say?: string | undefined;
+        attach?: {
+            kind: "audio" | "document" | "image";
+            file: string;
+        } | undefined;
+        after_ms?: number | undefined;
+        event?: {
+            id?: string | undefined;
+            type: string;
+            occurredAt?: string | undefined;
+            subject: string;
+            delivery?: string | undefined;
+            data: Record<string, unknown>;
+        } | undefined;
+        path?: string | undefined;
+        signature?: "bad" | "missing" | undefined;
+        answer?: number | {
+            status: number;
+            field?: string | undefined;
+        } | undefined;
+        nudge?: {
+            text?: string | undefined;
+            prompt?: string | undefined;
+            template?: {
+                name: string;
+                language?: string | undefined;
+                body?: string[] | undefined;
+                buttons?: {
+                    index: number;
+                    value: string;
+                }[] | undefined;
+            } | undefined;
+            respectQuietHours?: boolean | undefined;
+            expiresAt?: string | undefined;
+        } | undefined;
+        wait?: string | undefined;
+        at?: string | undefined;
+    }>>>;
+    tools: z.ZodOptional<z.ZodObject<{
+        real: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     world: z.ZodOptional<z.ZodString>;
     max_turns: z.ZodDefault<z.ZodNumber>;
     expect: z.ZodDefault<z.ZodObject<{
@@ -63,6 +186,18 @@ declare const scenarioSchema: z.ZodObject<{
             tool: z.ZodString;
             args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strict>]>>>;
+        sent: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            at: z.ZodOptional<z.ZodString>;
+            template: z.ZodOptional<z.ZodString>;
+            phrased: z.ZodOptional<z.ZodLiteral<true>>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        not_sent: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            at: z.ZodOptional<z.ZodString>;
+            template: z.ZodOptional<z.ZodString>;
+            phrased: z.ZodOptional<z.ZodLiteral<true>>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const toolFileSchema: z.ZodObject<{
@@ -79,6 +214,10 @@ declare const toolFileSchema: z.ZodObject<{
 /** The type of a file a scenario attaches, from its extension. */
 export declare function mimeOf(path: string): string;
 export type Scenario = z.infer<typeof scenarioSchema>;
+export type OpeningStep = Scenario["opening"][number];
+export type SentItem = z.infer<typeof sentItem>;
+/** The business starts something in it (an event, a nudge, time passing), or it checks what was sent: a business run. */
+export declare function isBusiness(scenario: Scenario): boolean;
 export type ToolFile = z.infer<typeof toolFileSchema>;
 export type ExpectedCall = z.infer<typeof expectedCall>;
 /** Parse and check a scenario. The error has one line per problem: `file:line: field: what is wrong`. */