npm - @flow-engineer/flow - Versions diffs - 0.0.1 → 0.2.0 - Mend

@flow-engineer/flow 0.0.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (96) hide show

package/LICENSE +21 -0
package/README.md +595 -0
package/coding-agents/skill.md +321 -0
package/coding-agents/test-skill.md +223 -0
package/coding-agents/tools-skill.md +89 -0
package/dist/flow-messaging/src/client.d.ts +34 -0
package/dist/flow-messaging/src/client.js +130 -0
package/dist/flow-messaging/src/index.d.ts +37 -0
package/dist/flow-messaging/src/index.js +409 -0
package/dist/simulators/src/index.d.ts +2 -0
package/dist/simulators/src/index.js +2 -0
package/dist/simulators/src/page.html +1245 -0
package/dist/simulators/src/person.html +100 -0
package/dist/simulators/src/platforms.d.ts +29 -0
package/dist/simulators/src/platforms.js +72 -0
package/dist/simulators/src/server.d.ts +201 -0
package/dist/simulators/src/server.js +759 -0
package/dist/src/agent.d.ts +504 -0
package/dist/src/agent.js +818 -0
package/dist/src/channels.d.ts +178 -0
package/dist/src/channels.js +243 -0
package/dist/src/conversation.d.ts +361 -0
package/dist/src/conversation.js +1487 -0
package/dist/src/db.d.ts +18 -0
package/dist/src/db.js +57 -0
package/dist/src/events.d.ts +17 -0
package/dist/src/events.js +20 -0
package/dist/src/http.d.ts +45 -0
package/dist/src/http.js +269 -0
package/dist/src/index.d.ts +14 -0
package/dist/src/index.js +11 -0
package/dist/src/model.d.ts +21 -0
package/dist/src/model.js +96 -0
package/dist/src/names.d.ts +17 -0
package/dist/src/names.js +38 -0
package/dist/src/nudges.d.ts +23 -0
package/dist/src/nudges.js +117 -0
package/dist/src/postgres.d.ts +20 -0
package/dist/src/postgres.js +62 -0
package/dist/src/schedules.d.ts +60 -0
package/dist/src/schedules.js +249 -0
package/dist/src/skills.d.ts +12 -0
package/dist/src/skills.js +69 -0
package/dist/src/store.d.ts +214 -0
package/dist/src/store.js +448 -0
package/dist/src/talk.d.ts +57 -0
package/dist/src/talk.js +166 -0
package/dist/src/time.d.ts +71 -0
package/dist/src/time.js +170 -0
package/dist/src/tools.d.ts +43 -0
package/dist/src/tools.js +26 -0
package/dist/src/traces.d.ts +31 -0
package/dist/src/traces.js +303 -0
package/dist/src/types.d.ts +260 -0
package/dist/src/types.js +2 -0
package/dist/testing/src/check-endpoint.d.ts +31 -0
package/dist/testing/src/check-endpoint.js +158 -0
package/dist/testing/src/chinwag.d.ts +2 -0
package/dist/testing/src/chinwag.js +6 -0
package/dist/testing/src/cli.d.ts +2 -0
package/dist/testing/src/cli.js +563 -0
package/dist/testing/src/client.d.ts +115 -0
package/dist/testing/src/client.js +955 -0
package/dist/testing/src/http-agent.d.ts +47 -0
package/dist/testing/src/http-agent.js +155 -0
package/dist/testing/src/index.d.ts +3 -0
package/dist/testing/src/index.js +2 -0
package/dist/testing/src/new.d.ts +9 -0
package/dist/testing/src/new.js +122 -0
package/dist/testing/src/print-run.d.ts +3 -0
package/dist/testing/src/print-run.js +22 -0
package/dist/testing/src/protocol.d.ts +159 -0
package/dist/testing/src/protocol.js +28 -0
package/dist/testing/src/report.d.ts +74 -0
package/dist/testing/src/report.js +90 -0
package/dist/testing/src/show.d.ts +36 -0
package/dist/testing/src/show.js +280 -0
package/dist/testing/src/suite.d.ts +87 -0
package/dist/testing/src/suite.js +198 -0
package/examples/cafe/agent/AGENTS.md +10 -0
package/examples/cafe/agent/skills/allergens/SKILL.md +7 -0
package/examples/cafe/src/agent.ts +39 -0
package/examples/cafe/src/main.ts +16 -0
package/examples/cafe/src/tools.ts +62 -0
package/examples/cafe/tests/scenarios/latte-correction.yaml +30 -0
package/examples/cafe/tests/scenarios/order-fails.yaml +26 -0
package/examples/cafe/tests/tools/get_menu.yaml +14 -0
package/examples/cafe/tests/tools/place_order.yaml +29 -0
package/examples/http-agent/server.mjs +32 -0
package/examples/http-agent/tests/scenarios/opening-hours.yaml +16 -0
package/flow-messaging/README.md +152 -0
package/package.json +62 -8
package/spec/agent-endpoint.openapi.yaml +148 -0
package/spec/nudges.openapi.yaml +167 -0
package/spec/request.schema.json +121 -0
package/spec/response.schema.json +284 -0

package/dist/simulators/src/person.html ADDED Viewed

@@ -0,0 +1,100 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{title}} · one person</title>
+<style>
+  :root { --bg: #f4f4f1; --panel: #ffffff; --ink: #1c1c1a; --quiet: #6b6b66; --line: #e2e1dc; --accent: #2f6fed; }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) { --bg: #161615; --panel: #1f1f1d; --ink: #ecebe6; --quiet: #9a9a94; --line: #33332f; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: var(--bg); color: var(--ink); }
+  button, select { font: inherit; }
+  .top { display: flex; align-items: center; gap: 12px; padding: 12px 16px; border-bottom: 1px solid var(--line); background: var(--panel); flex-wrap: wrap; }
+  .top h1 { font-size: 15px; margin: 0; font-weight: 600; }
+  .top h1 small { color: var(--quiet); font-weight: 400; }
+  .spacer { flex: 1; }
+  label { display: flex; align-items: center; gap: 6px; color: var(--quiet); }
+  select { padding: 6px 10px; border: 1px solid var(--line); border-radius: 8px; background: var(--bg); color: var(--ink); max-width: 240px; }
+  .note code { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 1px 6px; }
+  .ghost { padding: 6px 10px; border: 1px solid var(--line); border-radius: 8px; background: transparent; color: var(--ink); cursor: pointer; }
+  .ghost[aria-pressed="true"] { border-color: var(--accent); color: var(--accent); }
+  main { display: grid; grid-auto-flow: column; grid-auto-columns: minmax(0, 400px); justify-content: center; gap: 16px; padding: 16px; height: calc(100vh - 58px); }
+  @media (max-width: 820px) { main { grid-auto-flow: row; grid-auto-columns: auto; height: auto; } .device { height: 640px; } }
+  .device { display: flex; flex-direction: column; gap: 6px; min-height: 0; }
+  .device h2 { margin: 0; font-size: 12px; font-weight: 500; color: var(--quiet); text-align: center; }
+  iframe { flex: 1; width: 100%; border: 1px solid var(--line); border-radius: 28px; background: var(--panel); min-height: 0; }
+  .note { padding: 24px; text-align: center; color: var(--quiet); }
+</style>
+</head>
+<body>
+<div class="top">
+  <h1>{{title}} <small>· one person on every channel</small></h1>
+  <div class="spacer"></div>
+  <label>Test person <select id="person" aria-label="Test person"></select></label>
+  <button class="ghost" id="debug" type="button" aria-pressed="false" title="Show the agent's tool calls in each conversation">Debug</button>
+  <button class="ghost" id="clear" type="button" title="Forget this person: their history, schedules and everything the agent kept about them">Clear history</button>
+</div>
+<main id="devices"></main>
+<script>
+  // Where the simulators are mounted ("" on their own port).
+  const BASE = "{{base}}";
+  const $ = (id) => document.getElementById(id);
+  const params = new URLSearchParams(location.search);
+  const remember = (k, v) => { try { localStorage.setItem(k, v); } catch {} };
+  const recall = (k) => { try { return localStorage.getItem(k); } catch { return null; } };
+  let person = params.get("person") || recall("chinwag.person");
+  let debug = recall("chinwag.debug") === "1";
+  let people = [];
+  let channels = [];
+  function note(html) {
+    $("devices").innerHTML = `<div class='note'>${html}</div>`;
+  }
+  function draw() {
+    remember("chinwag.person", person);
+    $("person").value = person;
+    $("debug").setAttribute("aria-pressed", String(debug));
+    const devices = $("devices");
+    devices.innerHTML = "";
+    for (const c of channels) {
+      const device = document.createElement("section");
+      device.className = "device";
+      const h = document.createElement("h2");
+      h.textContent = c.name;
+      const frame = document.createElement("iframe");
+      frame.title = c.name;
+      frame.src = `${BASE}/?${new URLSearchParams({ channel: c.name, person, embed: "1", debug: debug ? "1" : "0" })}`;
+      device.append(h, frame);
+      devices.appendChild(device);
+    }
+  }
+  $("person").addEventListener("change", () => { person = $("person").value; draw(); });
+  $("debug").addEventListener("click", () => { debug = !debug; remember("chinwag.debug", debug ? "1" : "0"); draw(); });
+  $("clear").addEventListener("click", async () => {
+    const who = people.find((p) => p.phone === person);
+    if (!who || !confirm(`Forget ${who.name}? Their history, schedules and everything the agent kept about them go, on every channel.`)) return;
+    await fetch(`${BASE}/api/clear?${new URLSearchParams({ person })}`, { method: "POST" });
+  });
+  (async () => {
+    ({ people = [], channels = [] } = await (await fetch(`${BASE}/api/platforms`)).json());
+    if (!channels.length) return note("This agent has no channels. Declare them in <code>createAgent({ channels: [...] })</code> to test it here.");
+    if (!people.length) return note("This agent has no test people. Declare who may be played here in <code>createAgent({ testPeople: [{ name, phone }] })</code>.");
+    for (const p of people) {
+      const o = document.createElement("option");
+      o.value = p.phone;
+      o.textContent = `${p.name} · ${p.phone}`;
+      $("person").appendChild(o);
+    }
+    if (!people.some((p) => p.phone === person)) person = people[0].phone;
+    draw();
+  })();
+</script>
+</body>
+</html>

package/dist/simulators/src/platforms.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+import type { ChannelInfo } from "../../src/index.ts";
+export interface Platform extends ChannelInfo {
+    id: "sms" | "whatsapp" | "imessage" | "telegram" | "web";
+    name: string;
+    /** Shows "typing…" while the agent works. Plain SMS has no typing indicator. */
+    typing: boolean;
+    /** SMS: texts are billed and split into segments (160 GSM-7 characters, 70 with Unicode). */
+    segments?: boolean;
+    /** SMS: the carrier answers STOP, START and HELP itself, and blocks texts after STOP. */
+    carrierKeywords?: boolean;
+    /** SMS: an iPhone's tapback reaches the agent as a text, like `Liked "…"`. */
+    tapbacksAsText?: boolean;
+    /** The person can react to the agent's messages (WhatsApp). */
+    personReactions?: string[];
+    /** The simulator models every feature and limit of the real platform. */
+    complete: boolean;
+    /** Simple Icons slug for the logo (cdn.simpleicons.org). */
+    icon: string;
+}
+export declare const PLATFORMS: Platform[];
+export declare function platform(id: string | null): Platform;
+/** The parts of a platform the agent's runtime needs. */
+export declare function channelOf(p: Platform): ChannelInfo;
+/** How an SMS is split: its encoding, segment count, and characters left in the last segment. */
+export declare function smsSegments(text: string): {
+    encoding: "GSM-7" | "Unicode";
+    segments: number;
+    remaining: number;
+};

package/dist/simulators/src/platforms.js ADDED Viewed

@@ -0,0 +1,72 @@
+// What each chat platform can do, used by the simulators and the test harness, so an
+// agent meets the same rules it would on the real platform. Nothing here sends real messages.
+// SMS and WhatsApp are modelled in full; the others are being brought up to the same standard.
+export const PLATFORMS = [
+    {
+        id: "sms",
+        name: "SMS",
+        reactions: false,
+        status: false,
+        typing: false,
+        formatting: "plain",
+        // Providers join up to 10 segments into one text: 1,530 GSM-7 characters.
+        maxLength: 1530,
+        segments: true,
+        carrierKeywords: true,
+        tapbacksAsText: true,
+        complete: true,
+        icon: "googlemessages",
+    },
+    {
+        id: "whatsapp",
+        name: "WhatsApp",
+        reactions: true,
+        status: false,
+        typing: true,
+        formatting: "whatsapp",
+        maxLength: 4096,
+        replies: true,
+        buttons: { max: 3, labelMax: 20 },
+        lists: { maxRows: 10, titleMax: 24, buttonMax: 20 },
+        linkButton: { labelMax: 20 },
+        images: { captionMax: 1024 },
+        readReceipts: true,
+        personReactions: ["👍", "❤️", "😂", "😮", "😢", "🙏"],
+        complete: true,
+        icon: "whatsapp",
+    },
+    { id: "imessage", name: "iMessage", reactions: true, status: false, typing: true, formatting: "plain", images: { captionMax: 4000 }, complete: false, icon: "imessage" },
+    { id: "telegram", name: "Telegram", reactions: true, status: false, typing: true, formatting: "markdown", images: { captionMax: 1024 }, complete: false, icon: "telegram" },
+    { id: "web", name: "Web", reactions: true, status: true, typing: true, formatting: "markdown", linkButton: { labelMax: 20 }, images: { captionMax: 4000 }, complete: false, icon: "googlechrome" },
+];
+export function platform(id) {
+    return PLATFORMS.find((p) => p.id === id) ?? PLATFORMS[0];
+}
+/** The parts of a platform the agent's runtime needs. */
+export function channelOf(p) {
+    return {
+        reactions: p.reactions,
+        status: p.status,
+        formatting: p.formatting,
+        maxLength: p.maxLength,
+        replies: p.replies,
+        buttons: p.buttons,
+        lists: p.lists,
+        linkButton: p.linkButton,
+        images: p.images,
+        readReceipts: p.readReceipts,
+    };
+}
+const GSM7 = /^[@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞÆæßÉ !"#¤%&'()*+,\-./0-9:;<=>?¡A-ZÄÖÑÜ§¿a-zäöñüà^{}\\[~\]|€]*$/;
+/** How an SMS is split: its encoding, segment count, and characters left in the last segment. */
+export function smsSegments(text) {
+    const gsm = GSM7.test(text);
+    // GSM-7 extension characters take two septets.
+    const length = gsm ? [...text].reduce((n, c) => n + ("^{}\\[~]|€".includes(c) ? 2 : 1), 0) : [...text].length;
+    const single = gsm ? 160 : 70;
+    const multi = gsm ? 153 : 67;
+    if (length <= single)
+        return { encoding: gsm ? "GSM-7" : "Unicode", segments: 1, remaining: single - length };
+    const segments = Math.ceil(length / multi);
+    return { encoding: gsm ? "GSM-7" : "Unicode", segments, remaining: segments * multi - length };
+}

package/dist/simulators/src/server.d.ts ADDED Viewed

@@ -0,0 +1,201 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type Attachment, type ChannelInfo, type ChannelSummary, type Deliver, type EventSink, type FilledTemplate, type Incoming, type ListRow, type PlaygroundSink, type TemplateDefinition, type TestPerson, type TranscriptEntry } from "../../src/index.ts";
+import type { Agent } from "../../src/agent.ts";
+/** What the test cloud's simulators need from an agent. */
+export interface AgentConnection {
+    /** A person's message; returns its id, or null when the agent answered it without a turn. */
+    receive(conversationId: string, incoming: Incoming, deliver: Deliver, options: {
+        channel: ChannelInfo;
+        channelName?: string;
+    }): string | null;
+    /**
+     * The agent's own channels, if it has any: a simulator plays the one of its kind (SMS, WhatsApp,
+     * and the web simulator for a custom UI) with its definition.
+     */
+    channels?(conversationId: string): ChannelSummary[];
+    /** The person reacted to one of the agent's messages. */
+    reacted(conversationId: string, emoji: string, toText: string): void;
+    status(): {
+        busy: boolean;
+        idleForMs: number;
+        backgroundTasks: number;
+        conversations: number;
+    };
+}
+/** What the playground needs from an agent. Flow Framework's Agent is one as it is. */
+export interface PlaygroundAgent {
+    testPeople(): TestPerson[];
+    channels(): ChannelSummary[];
+    simulate(input: {
+        person: string;
+        channel: string;
+        message: Incoming;
+    }): Promise<{
+        conversationId: string;
+        messageId: string;
+    } | null>;
+    testConversation(phone: string): Promise<string | null>;
+    transcript(conversationId: string): Promise<TranscriptEntry[]>;
+    reacted(conversationId: string, emoji: string, toText: string): void;
+    forgetPerson(conversationId: string): Promise<void>;
+    attachPlayground(sink: PlaygroundSink | null): void;
+    status(): {
+        busy: boolean;
+        idleForMs: number;
+        backgroundTasks: number;
+        conversations: number;
+    };
+    /** The WhatsApp templates the agent declared, shown as WhatsApp would show them. */
+    templates?(): TemplateDefinition[];
+    /** The Person panel (Flow Framework's Agent has them all): what is set and waiting for a person, nudges, the clock's due work. */
+    contact?: Agent["contact"];
+    outbox?: Agent["outbox"];
+    recordNudge?: Agent["recordNudge"];
+    setTimeZone?: Agent["setTimeZone"];
+    setQuietHours?: Agent["setQuietHours"];
+    runDue?: Agent["runDue"];
+}
+/**
+ * The playground's clock: the agent's `now` (createAgent({ now: clock.now })), which the Person
+ * panel moves forward to bring scheduled and held messages due. Real time plus an offset.
+ */
+export interface PlaygroundClock {
+    now(): number;
+    /** Moves the clock to `at` (ms since the epoch); never backwards. */
+    set(at: number): void;
+}
+export declare function playgroundClock(): PlaygroundClock;
+export interface SimulatorsOptions {
+    /** The agent's name, shown in each simulator's header. */
+    title?: string;
+    /** The SMS provider's own replies; HELP is usually set to say who the agent is. */
+    sms?: {
+        helpReply?: string;
+    };
+    /** How a custom UI shows the links in its params: the first card whose `match` is in the URL. */
+    cards?: LinkCard[];
+    /** The pages' HTML, for a host with no file system (Cloudflare); else read from this folder. */
+    pages?: {
+        page: string;
+        person: string;
+    };
+    /** The agent's clock (playgroundClock(), passed to createAgent as `now`): the Person panel can move it. */
+    clock?: PlaygroundClock;
+}
+export interface LinkCard {
+    /** Text the link's URL contains, such as "/video/". */
+    match: string;
+    /** The card's button, such as "Start video call". */
+    label: string;
+    /** What opening it shows: a call screen, or a page of the app (the default). */
+    kind?: "call" | "page";
+}
+type Handler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+type Listening = {
+    close(): Promise<void>;
+    url: string;
+};
+export interface Playground {
+    /** Pass to the agent's `events`: the trace and tool calls of test people's conversations. */
+    events: EventSink;
+    /** Serves the playground on 127.0.0.1 only; a token is optional there. */
+    listen(agent: PlaygroundAgent, port: number, options?: {
+        token?: string;
+    }): Promise<Listening>;
+    /** The playground as a request handler under `base`, for a deployed agent's own server: a token is required. */
+    handler(agent: PlaygroundAgent, options: {
+        token: string;
+        base?: string;
+    }): Handler;
+}
+export interface TestCloudSimulators {
+    events: EventSink;
+    listen(agent: AgentConnection, port: number): Promise<Listening>;
+    handler(agent: AgentConnection, base?: string): Handler;
+}
+export type Line = {
+    kind: "in";
+    id: string | null;
+    text: string;
+    at: number;
+    replyTo?: string;
+    choice?: boolean;
+    attachments?: Array<{
+        kind: Attachment["kind"];
+        name?: string;
+    }>;
+} | {
+    kind: "out";
+    id: string;
+    text: string;
+    at: number;
+    replyTo?: string;
+    buttons?: string[];
+    list?: {
+        button: string;
+        rows: ListRow[];
+    };
+    /** A button under the message that opens this page. */
+    link?: {
+        label: string;
+        url: string;
+    };
+    /** A photo above the text, which is its caption. */
+    image?: {
+        url: string;
+    };
+    /** The channel's own params the agent filled in (an app_link): shown under the message. */
+    fields?: Record<string, unknown>;
+    /**
+     * A WhatsApp template, by name; declared, with its header, footer and buttons, the text its
+     * filled body. Not declared, the text lists the values it was sent with.
+     */
+    template?: {
+        name: string;
+        header?: FilledTemplate["header"];
+        footer?: string;
+        buttons?: FilledTemplate["buttons"];
+    };
+    sms?: {
+        segments: number;
+        encoding: string;
+    };
+    /** Sent by the SMS carrier itself (STOP, START, HELP replies), not the agent. */
+    carrier?: boolean;
+} | {
+    kind: "reaction";
+    messageId: string;
+    emoji: string;
+    at: number;
+    by: "agent" | "person";
+} | {
+    kind: "read";
+    messageIds: string[];
+    at: number;
+}
+/** A tool call by the agent: shown only in the simulator's debug mode, never to the person. */
+ | {
+    kind: "tool";
+    callId: string;
+    tool: string;
+    input: unknown;
+    at: number;
+    status: "running" | "background" | "done" | "failed";
+    ms?: number;
+    output?: string;
+    /** Cloud tests: which kind of response the tool simulator played, and what it changed. */
+    played?: string;
+    changes?: string[];
+} | {
+    kind: "undelivered";
+    text: string;
+    reason: string;
+    at: number;
+};
+export declare function simulators(options: SimulatorsOptions & {
+    testCloud: true;
+}): TestCloudSimulators;
+export declare function simulators(options?: SimulatorsOptions & {
+    testCloud?: false;
+}): Playground;
+export {};