@flow-engineer/flow 0.3.3 → 0.4.1

package/README.md

@@ -50,7 +50,7 @@ Test it first in the playground (the link `npm start` prints: the test people an
 
 **Stability.** 0.x: the CLI's commands, `--json` fields and exit codes in [docs/agents.md](docs/agents.md) stay compatible within 0.2.x; a breaking change comes with a minor version bump and a release note. Pin the version in `package.json` for production.
 
-**Host it.** Coming soon: `npx @flow-engineer/flow deploy`, to keep the agent answering while the laptop sleeps.
+**Host it.** `npx @flow-engineer/flow deploy` puts the agent on Flow's hosting, so it keeps answering while the laptop sleeps: staging first, then `deploy promote` to production; it sends the `.env`'s keys as the agent's secrets itself. `deploy status` shows what is live and its URL, `flow logs` its log lines. It needs the agent's CI key (`FLOW_FRAMEWORK_CLOUD_KEY`, which `flow setup` writes) and a `buildAgent` that passes `options.host` on to `createAgent` ([docs/agents.md](docs/agents.md), "Host it").
 
 ### In a folder of your own
 
@@ -648,7 +648,7 @@ cd agents/my-agent && npm start
 
 **Which channels are real?** WhatsApp, SMS and your own UI (`customUI`) have production definitions today; you plug in any provider by writing `sendMessage`. Telegram and iMessage are real through Flow Messaging (`fm.telegram()`, `fm.imessage()`, [flow-messaging/README.md](flow-messaging/README.md)); in core they are in the playground for now.
 
-**Does it host my agent?** No. It runs in your Node process, on your machine or servers. You pay your model and messaging providers directly.
+**Does it host my agent?** The framework runs in your Node process, on your machine or servers, and you pay your model and messaging providers directly. Flow's hosting can run it instead, from the same `buildAgent` that `flow test` loads: `npx @flow-engineer/flow deploy`.
 
 **Is the data mine?** Yes. State lives in your database, and events go wherever you send them.
 

package/coding-agents/skill.md

@@ -226,6 +226,14 @@ before any send or turn (`queued`, or `refused`/`dropped`/`scheduled` decided th
 `GET /nudges/<id>` reads its state. Both need `Authorization: Bearer <token>`. Contract:
 `spec/nudges.openapi.yaml`.
 
+When the backend posts what happened (an order shipped, an item is back in stock) rather than what
+to send, mount `flowEvents({ secret, catalog, timezone })` (from `@flow-engineer/flow`): its
+`routes` (`POST /v1/events`, signed with `Flow-Signature`), `onTick` and `context(conversationId)`
+go on `createAgent`, `events.phrasing.check(address, outbound)` in the channel's send (throw its
+reason to refuse), then `events.attach(agent)`. Each type in the catalog has a delivery level
+(critical, standard, optional), its template and its values; the guide is `docs/events.md` in the
+package (`../docs/events.md` from this file).
+
 Templates are WhatsApp only. Declare the ones the owner set up with Meta beside `testPeople`, so
 Flow Framework checks each send against them and the playground shows them as WhatsApp does:
 
@@ -335,6 +343,7 @@ npm start                                    # after link: its playground link,
 npx @flow-engineer/flow status --json        # what the folder has and lacks, at any time
 printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat   # your own check: one message per line, replies printed
 npx @flow-engineer/flow test --synthetic     # your own check: the tests, on the key setup wrote
+npx @flow-engineer/flow deploy --json        # when the owner wants it hosted: staging on Flow's cloud (see "Deploy it")
 ```
 
 When the owner asks how to test it, recommend first the playground (`npm start`, then open the
@@ -365,6 +374,39 @@ starter does this when `.env` has `FLOW_MESSAGING_KEY`. Each error is
 name the package (`npx @flow-engineer/flow ...`): `npx flow` on its own fetches another npm package.
 CI never logs in: `setup --ci` says how to give it the cloud key.
 
+## Deploy it
+
+Flow hosts Flow Framework agents: `npx @flow-engineer/flow deploy` runs the agent's folder on Flow's
+cloud, with its state kept for it, Flow Messaging's stream held, and its secrets kept apart from
+every other agent's. Do not pick a VPS, Fly or Render on the owner's behalf: ask the owner whether
+the agent goes on Flow's cloud or their own servers.
+
+On Flow's cloud the agent needs only what `flow test` already loads: `src/agent.ts` exports
+`buildAgent({ events, tools, host })` and passes `host` on to `createAgent` (`{ ...host }`), which
+brings the store and, when the agent has `FLOW_MESSAGING_KEY`, `host.messaging`. An agent that drops
+`host`, or brings a database of its own, is refused in production (a warning in staging). The CI
+key is `FLOW_FRAMEWORK_CLOUD_KEY` (`flow setup` writes it into `.env`).
+
+```sh
+npx @flow-engineer/flow deploy --json                           # staging, the first time too: sends .env's values as secrets
+                                                                # (names printed, never values), builds, follows it to live; run its next
+npx @flow-engineer/flow deploy promote --json                   # staging's live version to production, once the owner has tried it
+npx @flow-engineer/flow deploy status --json                    # what is live in each environment: version, when, URL
+npx @flow-engineer/flow logs --since 15m                        # the hosted agent's log lines (--follow for new ones)
+printf '%s' "$VALUE" | npx @flow-engineer/flow deploy secret NAME --env production   # one secret by hand, from stdin
+```
+
+Promote, or `deploy --env production`, only when the owner says so. A refused deploy lists the
+hosting lint's findings (`deploy.findings`): fix the errors and deploy again. One `deploy` is the whole first deploy: there is no
+separate secrets step (it sends only new or changed `.env` values each time; promote sends them to
+production). Commit first, or the version reads `<sha>+dirty`. Stop the laptop's `npm start` once the deployed one is live: two copies on one key
+both answer every message.
+
+On the owner's own servers: one instance, kept warm, CPU always on, a durable `database`
+(`postgres(pool)`), `await agent.resume()` at start, the secrets from the platform's secret store
+(never the `.env`), and Flow Messaging's stream (`fm.start`) with its cursor file on a disk that
+survives a restart, or its webhook (`FLOW_MESSAGING_WEBHOOK_SECRET`) on a public https address.
+
 ## Send traces to a dashboard
 
 Every turn can go to a traces endpoint as an OTLP/JSON trace, posted to `<url>/v1/traces`, so
@@ -534,7 +576,7 @@ An operation already accepted by the agent may still complete after its client s
 Enable this only in local startup code. The runner is off by default, rejects non-loopback or
 forwarded connections, and is not part of the hosted test cloud. It calls the actual CLI runner
 only locally. Hosted CLI support is deferred pending security review; do not add it to cloud startup
-or deployment wiring. See the hosted CLI TODO in the README. The runner invokes the CLI
+or deployment wiring (that is `flow deploy`). See the hosted CLI TODO in the README. The runner invokes the CLI
 without a shell: quoting works, pipelines/expansion do not. The browser cannot override server
 or token flags, or use `skill --write` to write onto the developer's computer.
 For other embedded clients, `CliConfig.directory` overrides credential/conversation storage;

package/dist/src/business-events/engine.d.ts

@@ -0,0 +1,316 @@
+import type { NudgeInput, NudgeResult } from "../agent.ts";
+import type { Template } from "../types.ts";
+import { type Phrasing } from "./phrasing.ts";
+import { type EventQuietHours } from "./quiet.ts";
+export type DeliveryLevel = "critical" | "standard" | "optional";
+export declare const DELIVERY_LEVELS: readonly DeliveryLevel[];
+/** The event cancelling one not yet sent: `data.cancels` is its id. */
+export declare const CANCELLED_EVENT = "notification.cancelled";
+/** One event, as the business posts it. */
+export interface BusinessEvent {
+    /** Unique per event: the same id twice is processed once. */
+    id: string;
+    type: string;
+    occurredAt: string;
+    /** What it is about, as the business names it ("user:...", "order:..."). */
+    subject: string;
+    /** The floor: never sent at a lower level. Default: the type's in the catalog. */
+    delivery?: DeliveryLevel;
+    /** The business sent this message itself: kept as context, never sent. */
+    sentBy?: string;
+    /** Don't send after this (ISO time). Also read from `data.expiresAt`. */
+    expiresAt?: string;
+    /** A newer one with the same key replaces one still held. Also read from `data.collapseKey`. */
+    collapseKey?: string;
+    data: Record<string, any>;
+}
+/** A message ready either way: the template, its text as the person would see it, its values and its button link. */
+export interface EventMessage {
+    template: Template;
+    text: string;
+    values: string[];
+    link: {
+        label: string;
+        url: string;
+    };
+}
+/** A type that becomes a message for one person. */
+export interface NotificationType {
+    kind?: "notification";
+    /** Its default level, when the event names none. */
+    level: DeliveryLevel;
+    /** Its message, or the field it lacks (a 400 names it). */
+    message(event: BusinessEvent): EventMessage | {
+        missing: string;
+    };
+    /** Its button acts on a live topic: dropped once the topic closes, whatever the level. */
+    liveOnly?: boolean;
+    /** What the message is about (an order, a product): how watches raise it, closing drops it, caps count it. */
+    topic?(event: BusinessEvent): string | undefined;
+    /** The topic's name, to find a watch when the event names no topic. */
+    title?(event: BusinessEvent): string | undefined;
+}
+/** A type the app handles itself in `onEvent` (no message of its own). */
+export interface AppEventType {
+    kind: "event";
+    /** Why it is malformed, naming the field; null when fine. */
+    validate?(event: BusinessEvent): EventProblem | null;
+}
+export type EventType = NotificationType | AppEventType;
+export type EventCatalog = Record<string, EventType>;
+export interface EventProblem {
+    field: string;
+    error: string;
+}
+/** A send, held or about to go. */
+export interface PendingSend {
+    eventId: string;
+    /** The event type it came from (a nudge: `nudge.<kind>`), for logs. */
+    type?: string;
+    address: string;
+    delivery: DeliveryLevel | "nudge";
+    /** Raised by a watch: "watch" is kept, "urgent" also goes at once. */
+    raised?: "watch" | "urgent";
+    /** Never dropped as stale, whatever closes. */
+    sticky?: true;
+    /** Dropped when its topic closes, whatever the level. */
+    liveOnly?: true;
+    /** A nudge's kind, as the app names it. */
+    nudge?: string;
+    topic?: string;
+    collapseKey?: string;
+    notBefore: number;
+    expiresAt?: number;
+    /** The template, never the agent's words. */
+    exact: boolean;
+    message: EventMessage;
+}
+/** What a person asked to be told about. Apps add their own fields. */
+export interface Watch {
+    id: string;
+    address: string;
+    /** Only watches with a topic raise messages. */
+    topic?: string;
+    /** The topic's name, as the agent saw it. */
+    title?: string;
+    /** "As soon as": raised messages go at once, even in quiet hours. */
+    urgent?: true;
+    createdAt: number;
+    /** When its topic closed. */
+    endedAt?: number;
+}
+/** A message the business sent itself (`sentBy`), kept as context. */
+export interface EventCopy {
+    eventId: string;
+    type: string;
+    /** When it was sent (the envelope's occurredAt), ms. */
+    at: number;
+    text: string;
+    values: string[];
+    link: {
+        label: string;
+        url: string;
+    };
+}
+export interface SentNudge {
+    address: string;
+    topic?: string;
+    kind?: string;
+    at: number;
+}
+/** What the events side keeps. Pass your own (with extra fields of your app's) to share it. */
+export declare function createEventState<W extends Watch = Watch>(): {
+    seen: Set<string>;
+    cancelled: Set<string>;
+    outbox: PendingSend[];
+    watches: W[];
+    /** Closed topics. */
+    closed: Set<string>;
+    /** `${address} ${topic}`: no more nudges about it. */
+    muted: Set<string>;
+    nudges: SentNudge[];
+    /** `${address} ${collapseKey|eventId}` -> when an optional last went. */
+    optionalLast: Map<string, number>;
+    /** The last nudged topic per address, for "not interested". */
+    lastNudged: Map<string, string>;
+    /** Address -> copies the business sent itself, newest last. */
+    copies: Map<string, EventCopy[]>;
+    /** `${address}\n${text}` -> when it reached them: the same message never goes again within a day. */
+    told: Map<string, number>;
+    /** Conversation id -> address. */
+    addresses: Map<string, string>;
+};
+export type EventState<W extends Watch = Watch> = ReturnType<typeof createEventState<W>>;
+/** What sends: the agent (its nudge, and reach for copies). */
+export interface EventSender {
+    nudge(input: NudgeInput): Promise<NudgeResult>;
+    reach?(to: {
+        channel: string;
+        address: string;
+    }): Promise<{
+        conversationId: string;
+    }>;
+}
+export interface FlowEventsOptions<W extends Watch = Watch> {
+    /** The whsec_ secret the business signs with; without it every POST is refused (503). */
+    secret?: string;
+    /** Every type accepted (plus notification.cancelled); any other is a 400. */
+    catalog: EventCatalog;
+    now?: () => number;
+    /** The channel messages go on. Default whatsapp. */
+    channel?: string;
+    /** The zone quiet hours and copies' times are read in. Default UTC. */
+    timezone?: string;
+    /** How the zone reads in log reasons and notes ("Pacific time"). Default the zone's name. */
+    timezoneName?: string;
+    /** Default 22:00 to 08:00; null: none. */
+    quietHours?: EventQuietHours | null;
+    /** Nudge caps (raised nudges skip them). Default 2 a day, 1 per topic a day, 5 a week. */
+    caps?: {
+        perDay: number;
+        perKeyPerDay: number;
+        perWeek: number;
+    };
+    /** How long a watch lasts. Default 30. */
+    watchDays?: number;
+    state?: EventState<W>;
+    /** Who may post copies (`sentBy`); none: sentBy is refused. */
+    sentBy?: string | string[];
+    /** The business's name in log reasons ("Acme"). Default the first sentBy, else "the business". */
+    businessName?: string;
+    /** Off production, who a business-started send may go to (eventTestList). */
+    testList?: {
+        allows(address: string): boolean;
+    };
+    /** A send the test list stopped. */
+    onUnlisted?(send: {
+        event: string;
+        type: string;
+        address: string;
+    }): void;
+    /** Each decision as fields (ids, types, outcomes; never text). Default one JSON line, numbers masked. */
+    log?(fields: Record<string, unknown>): void;
+    /** The default log line's msg. Default "flow event". */
+    logName?: string;
+    /** What a topic is called in log reasons ("order"). Default "topic". */
+    topicNoun?: string;
+    /** The log reason for a muted nudge. Default "muted (not interested)". */
+    mutedReason?: string;
+    /** Where a notification's person is. Default data.user.phone. */
+    addressOf?(event: BusinessEvent): string | undefined;
+    /** Whether they agreed to messages. Default data.consent.whatsappUpdates === true. */
+    consented?(event: BusinessEvent): boolean;
+    wording?: {
+        /** The note the agent gets to phrase a message (nudge: one the business started from a watch). */
+        prompt?(message: EventMessage, options: {
+            nudge: boolean;
+        }): string;
+        /** The stop line a nudge sent as text ends with. */
+        stopLine?: string;
+        /** The text fallback puts the link in the text instead of a link button. */
+        linkInText?: boolean;
+    };
+    copies?: {
+        kept?: number;
+        shown?: number;
+        days?: number;
+        /** The agent's note on recent copies; "" for none. */
+        note?(copies: EventCopy[], options: {
+            timezone: string;
+            timezoneName: string;
+        }): string;
+    };
+    rules?: {
+        /** Before the raise: "handled" when the app sent (or dropped) it itself; else it goes on. */
+        notification?(event: BusinessEvent, send: PendingSend, events: FlowEvents<W>): "send" | "handled" | Promise<"send" | "handled">;
+        /** A copy arrived: the app's own bookkeeping, and held sends it also counts as told. */
+        copy?(event: BusinessEvent, message: EventMessage, events: FlowEvents<W>): ((held: PendingSend) => boolean) | void;
+    };
+    /** Types of kind "event", in order with the rest. */
+    onEvent?(event: BusinessEvent, events: FlowEvents<W>): Promise<void> | void;
+    /** After held sends came due, in order with the rest. */
+    onTick?(now: number, events: FlowEvents<W>): Promise<void> | void;
+}
+/**
+ * The events side of an agent: mount `routes` and `onTick` on createAgent, `phrasing.check` in the
+ * channel's send, `context` in the agent's context, then `attach(agent)`.
+ */
+export declare function flowEvents<W extends Watch = Watch>(options: FlowEventsOptions<W>): {
+    state: {
+        seen: Set<string>;
+        cancelled: Set<string>;
+        outbox: PendingSend[];
+        watches: W[];
+        /** Closed topics. */
+        closed: Set<string>;
+        /** `${address} ${topic}`: no more nudges about it. */
+        muted: Set<string>;
+        nudges: SentNudge[];
+        /** `${address} ${collapseKey|eventId}` -> when an optional last went. */
+        optionalLast: Map<string, number>;
+        /** The last nudged topic per address, for "not interested". */
+        lastNudged: Map<string, string>;
+        /** Address -> copies the business sent itself, newest last. */
+        copies: Map<string, EventCopy[]>;
+        /** `${address}\n${text}` -> when it reached them: the same message never goes again within a day. */
+        told: Map<string, number>;
+        /** Conversation id -> address. */
+        addresses: Map<string, string>;
+    };
+    phrasing: Phrasing;
+    handler: (req: Request) => Promise<Response>;
+    /** For createAgent's `routes`. */
+    routes: Record<string, (request: Request) => Promise<Response>>;
+    /** For createAgent's `onTick`. */
+    onTick: () => Promise<undefined>;
+    attach(s: EventSender): void;
+    invalid: (body: unknown) => EventProblem | null;
+    accept: (e: BusinessEvent) => boolean;
+    tick: () => Promise<unknown>;
+    /** Resolves once everything accepted so far is processed. */
+    idle: () => Promise<undefined>;
+    report: (fields: Record<string, unknown>) => void;
+    schedule: (p: PendingSend, exempt?: boolean) => Promise<void>;
+    drop: (match: (p: PendingSend) => boolean) => number;
+    raise: (event: string, type: string, delivery: DeliveryLevel, watch: Watch | undefined) => {
+        delivery: DeliveryLevel;
+        raised?: "watch" | "urgent";
+    };
+    /** This person's live watch on a topic (by topic, else by its name, with `titleOf` the app's names for topics). */
+    watchFor: (address: string, topic: string | undefined, title?: unknown) => W | undefined;
+    /** How a topic's name is found, for watches matched by name. */
+    setTitles(fn: (topic: string) => string | undefined): void;
+    /** Whether a watch is within its days. */
+    alive: (w: Watch, t?: number) => boolean;
+    told: (address: string, text: string) => boolean;
+    muted: (address: string, topic: string | undefined) => boolean;
+    isCopy: (e: BusinessEvent) => boolean;
+    /**
+     * Saves a watch; `same` finds one this person already has (it is refreshed: another 30 days, its
+     * title kept, urgent kept). "saved" or "already watching".
+     */
+    watch(w: Omit<W, "id" | "createdAt"> & {
+        createdAt?: number;
+    }, same?: (existing: W) => boolean): {
+        outcome: "saved" | "already watching";
+        watch: W;
+    };
+    /**
+     * A topic closed (sold, cancelled, ended): held sends about it are dropped, except a critical or
+     * raised one, a sticky one, and never a live-only one; its watches end. How many were dropped.
+     */
+    close(topic: string): number;
+    /** No more nudges to this person about this topic. */
+    mute(address: string, topic: string): void;
+    /** "Not interested" on a nudge: that topic is muted, its watch and held nudges go. The topic, or null. */
+    notInterested(address: string): string | null;
+    /** STOP: their watches end and held nudges go (the agent itself stops every send). */
+    stopped(address: string): void;
+    /** Which address a conversation is (from tool calls, copies). */
+    remember(conversationId: string, address: string): void;
+    /** The note on recent copies for this person; "" when none. */
+    copiesNote(address: string): string;
+    /** The turn's context: recent copies for this conversation's person ("" when none). `address` when the caller knows it. */
+    context(conversationId: string, address?: string | null): string;
+};
+export type FlowEvents<W extends Watch = Watch> = ReturnType<typeof flowEvents<W>>;