@flow-engineer/flow 0.0.1 → 0.2.0

package/package.json

@@ -1,13 +1,67 @@
 {
   "name": "@flow-engineer/flow",
-  "version": "0.0.1",
-  "description": "Flow Framework (coming soon)",
-  "main": "index.js",
+  "version": "0.2.0",
+  "description": "An open-source runtime for chat agents that feel like a person texting back.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flow-engineer/flow.git"
+  },
+  "homepage": "https://github.com/flow-engineer/flow",
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./simulators": {
+      "types": "./dist/simulators/src/index.d.ts",
+      "default": "./dist/simulators/src/index.js"
+    },
+    "./flow-messaging": {
+      "types": "./dist/flow-messaging/src/index.d.ts",
+      "default": "./dist/flow-messaging/src/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/src/index.d.ts",
+      "default": "./dist/testing/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "flow": "dist/testing/src/cli.js",
+    "chinwag": "dist/testing/src/chinwag.js"
+  },
+  "files": [
+    "dist",
+    "examples/cafe/agent",
+    "examples/cafe/src",
+    "examples/cafe/tests",
+    "examples/http-agent",
+    "flow-messaging/README.md",
+    "coding-agents",
+    "spec",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node -e \"for (const f of ['page.html', 'person.html']) fs.copyFileSync('simulators/src/' + f, 'dist/simulators/src/' + f)\"",
+    "prepack": "npm run build",
+    "test": "node --test --test-timeout=30000 \"test/**/*.test.ts\"",
+    "test:changed": "node scripts/test-changed.ts",
+    "new": "node scripts/new-agent.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "openai": "^7.32.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
+  }
 }

package/spec/agent-endpoint.openapi.yaml

@@ -0,0 +1,148 @@
+openapi: 3.1.0
+info:
+  title: Flow Framework agent endpoint
+  version: 0.1.0
+  license:
+    name: MIT
+    identifier: MIT
+  description: |
+    The HTTP endpoint an agent on any framework, in any language, exposes so Flow Framework's test suite
+    can talk to it: `flow test --agent-url <url>`. Implement this one operation and the test
+    cloud's simulated people can chat with your agent; `flow check-endpoint <url>` checks an
+    implementation against this file without a cloud, a key or a model call.
+
+    How a run uses it:
+    - Each of the person's messages is one POST to the URL you give, from the machine running
+      `flow test` (so `http://localhost` works and the agent never has to be reachable from the
+      internet). The path is yours; `/flow` is the examples'.
+    - A conversation's messages are sent one at a time, in order: the next is POSTed once the last
+      one's answer is in. Different conversations may be in flight at once.
+    - Keep each conversation's history by `conversationId`, as you would per phone number. The
+      request carries only the new message.
+    - Ignore request fields you do not know: later versions may add optional ones. The request
+      schema is exact for this version; do not reject requests that have more.
+    - Answer with status 200 and `{ "replies": [...] }`, the replies to send in order, in the same
+      HTTP response. `{ "replies": [] }` sends nothing (not 204, not an empty body). Answering
+      later, through a callback, is not supported.
+    - Your agent's own tools run on its side, for real: the suite's `tests/tools/*.yaml` simulators
+      are not used, and outcome checks see no tool calls, so write what must be true as `judge`
+      items.
+    - The person's reactions to the agent's messages are not sent in this version.
+
+    What fails a message's turn (the run records why and goes on to the next message):
+    - any status other than 200 (redirects are followed; the final status counts), with the
+      first 200 characters of the body in the reason;
+    - a 200 whose body is not JSON, or has no `replies` array;
+    - no answer within the timeout: 60 seconds by default, `--agent-timeout <s>` to change it;
+    - the URL cannot be reached.
+
+    A reply that is valid JSON but does not fit the run's platform (buttons on SMS, text over its
+    maxLength, an unknown key) is not sent; the run says why and the other replies still go.
+    `x-chinwag-platforms` below lists what each platform shows.
+servers:
+  - url: http://localhost:3000
+    description: Wherever your agent listens; `flow test --agent-url` takes the full URL.
+security:
+  - {}
+  - bearer: []
+paths:
+  /flow:
+    post:
+      operationId: receiveMessage
+      summary: One message from the person; answer with the replies to send.
+      description: |
+        Sent with `content-type: application/json`. When FLOW_FRAMEWORK_AGENT_TOKEN is set where
+        `flow test` runs, every request carries `authorization: Bearer <token>`: check it, and
+        answer 401 to anything else.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ./request.schema.json
+            examples:
+              text:
+                summary: A typed message
+                value:
+                  conversationId: whatsapp:ses_8f2a.opening-hours.whatsapp.1
+                  messageId: m1
+                  channel: whatsapp
+                  message: { text: "hi, what time are you open today?" }
+              photo:
+                summary: A photo with no caption
+                value:
+                  conversationId: whatsapp:ses_8f2a.receipt.whatsapp.1
+                  messageId: m2
+                  channel: whatsapp
+                  message:
+                    text: ""
+                    attachments: [{ kind: image, mime: image/png, name: receipt.png, data: iVBORw0KGgo= }]
+              tap:
+                summary: A tapped button, replying to the agent's message
+                value:
+                  conversationId: whatsapp:ses_8f2a.order.whatsapp.1
+                  messageId: m3
+                  channel: whatsapp
+                  message:
+                    text: Oat
+                    choice: { title: Oat }
+                    replyTo: { text: "Which milk?", fromAgent: true }
+      responses:
+        "200":
+          description: The replies to send, in order; `[]` is no reply.
+          content:
+            application/json:
+              schema:
+                $ref: ./response.schema.json
+              examples:
+                answer:
+                  value:
+                    replies:
+                      - { type: reaction, emoji: "👍", messageId: m1 }
+                      - { type: message, text: "We're open 8am to 6pm today.", buttons: [Order ahead] }
+                nothing:
+                  value: { replies: [] }
+        default:
+          description: Any other status fails this message's turn; the body's first 200 characters are the reason shown in the run.
+components:
+  securitySchemes:
+    bearer:
+      type: http
+      scheme: bearer
+      description: The value of FLOW_FRAMEWORK_AGENT_TOKEN, when it is set where `flow test` runs.
+# What each platform a run plays shows, as ChannelInfo in src/types.ts: a reply is checked against
+# its run's platform. A key that is absent means the platform does not have that feature. maxLength
+# absent is 4,000. Kept in step with simulators/src/platforms.ts by test/check-endpoint.test.ts.
+x-chinwag-platforms:
+  sms:
+    reactions: false
+    status: false
+    formatting: plain
+    maxLength: 1530
+  whatsapp:
+    reactions: true
+    status: false
+    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
+  imessage:
+    reactions: true
+    status: false
+    formatting: plain
+    images: { captionMax: 4000 }
+  telegram:
+    reactions: true
+    status: false
+    formatting: markdown
+    images: { captionMax: 1024 }
+  web:
+    reactions: true
+    status: true
+    formatting: markdown
+    linkButton: { labelMax: 20 }
+    images: { captionMax: 4000 }

package/spec/nudges.openapi.yaml

@@ -0,0 +1,167 @@
+openapi: 3.1.0
+info:
+  title: Flow Framework nudges over HTTP
+  version: 0.1.0
+  license:
+    name: MIT
+    identifier: MIT
+  description: |
+    The endpoint `nudgeHandler(agent, { token, base })` serves in the agent's own server, so a
+    backend that is a separate service can send nudges (messages the business starts) without a
+    route of its own. Paths are under `base`, `/nudges` by default; anything outside it gets 404.
+
+    - A POST answers as soon as the nudge is recorded, before it is sent or the agent's turn for it
+      runs: usually `queued`. Read how it ended with the GET.
+    - What is decided as it is recorded is in the POST's answer, still a 202: it is the nudge's
+      state, not an HTTP error. `refused` with `unknown_person` (they never wrote on that channel;
+      nothing is recorded, so `id` is "" and there is nothing to GET) or `outside_window` (past
+      WhatsApp's 24-hour window, for text and prompt nudges); `dropped` (they texted STOP);
+      `scheduled` (it has `at`).
+    - Every request needs `Authorization: Bearer <token>`. Wrong tokens are limited per address:
+      after 10 in 15 minutes the address gets 429 for the rest of that window, the right token too.
+    - Answers are JSON with `cache-control: no-store`.
+servers:
+  - url: http://localhost:3000
+    description: Wherever the agent's server listens.
+security:
+  - bearer: []
+paths:
+  /nudges:
+    post:
+      operationId: recordNudge
+      summary: Record a nudge; answers at once with its id and state.
+      requestBody:
+        required: true
+        description: At most 16,384 bytes of JSON. Unknown fields are refused.
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NudgeRequest"
+            examples:
+              prompt:
+                summary: The agent writes it, in the context of the chat
+                value:
+                  to: { channel: whatsapp, address: "+15550100100" }
+                  prompt: Their order is ready for pickup.
+                  idempotency_key: order-1042-ready
+              text:
+                summary: Sent as written, later
+                value:
+                  to: { channel: sms, address: "+15550100100" }
+                  text: Your table is booked for 7pm.
+                  at: 1792335600000
+      responses:
+        "202":
+          description: Recorded (or, for an `idempotency_key` already used, the first nudge with that key).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NudgeState"
+              examples:
+                queued:
+                  value: { id: n_3f9c2a1b, status: queued }
+                unknownPerson:
+                  value: { id: "", status: refused, reason: unknown_person }
+        "400":
+          description: The body is not JSON, too large, or does not fit; the channel is not one of the agent's; a declared template's values do not fit it.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          description: No token, or a wrong one.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "429":
+          description: Too many wrong tokens from this address.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /nudges/{id}:
+    get:
+      operationId: nudgeState
+      summary: A nudge's state now.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: Its state now.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NudgeState"
+              example: { id: n_3f9c2a1b, status: sent }
+        "401":
+          description: No token, or a wrong one.
+        "404":
+          description: The agent never recorded a nudge with this id.
+        "429":
+          description: Too many wrong tokens from this address.
+components:
+  securitySchemes:
+    bearer:
+      type: http
+      scheme: bearer
+      description: The token given to `nudgeHandler`, at least 32 characters.
+  schemas:
+    NudgeRequest:
+      type: object
+      additionalProperties: false
+      required: [to]
+      description: Exactly one of `text`, `prompt` or `template`.
+      properties:
+        to:
+          type: object
+          additionalProperties: false
+          required: [channel, address]
+          description: The person, by a channel identity they have written from.
+          properties:
+            channel: { type: string, description: One of the agent's channels, by name. }
+            address: { type: string, description: "Their address on it: a phone number, or the custom UI's user id." }
+        text: { type: string, minLength: 1, description: Sent as written, with no model call. }
+        prompt: { type: string, minLength: 1, description: The agent gets a turn with this note and writes the message itself, or sends nothing. }
+        template:
+          type: object
+          additionalProperties: false
+          required: [name]
+          description: A WhatsApp template the owner set up with Meta, as `Template` in src/types.ts. Cannot be combined with `at` yet.
+          properties:
+            name: { type: string }
+            language: { type: string }
+            header:
+              oneOf:
+                - { type: object, additionalProperties: false, required: [kind, text], properties: { kind: { const: text }, text: { type: string } } }
+                - { type: object, additionalProperties: false, required: [kind], properties: { kind: { enum: [image, video, document] }, url: { type: string }, fileId: { type: string } } }
+            body: { type: array, items: { type: string } }
+            buttons:
+              type: array
+              items: { type: object, additionalProperties: false, required: [index, value], properties: { index: { type: integer, minimum: 0 }, value: { type: string } } }
+            variables: { type: object, additionalProperties: { type: string } }
+        at: { type: integer, minimum: 0, description: Send it later, at this time, in milliseconds since the epoch. }
+        idempotency_key: { type: string, minLength: 1, maxLength: 200, description: The same key twice sends once; the second call gets the first nudge's id and state. }
+        respect_quiet_hours: { type: boolean, description: "Wait for the end of the person's quiet hours (default true); false sends it now." }
+        expires_at: { type: integer, minimum: 0, description: "Milliseconds since the epoch: held for quiet hours past this, it is dropped as expired (default 24 hours on)." }
+    NudgeState:
+      type: object
+      required: [id, status]
+      properties:
+        id: { type: string }
+        status:
+          enum: [queued, sent, silent, dropped, refused, failed, scheduled, held, expired]
+          description: |
+            queued (waiting for its send or turn); sent; silent (the agent chose to send nothing);
+            dropped (a no-contact rule covers it, or their STOP); refused (outside_window,
+            unknown_person); failed (it could not be sent, or the model failed); scheduled; held (their
+            quiet hours, until they end or the person writes); expired (held past expires_at).
+        reason: { type: string, description: Why, for dropped, refused and failed. }
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error: { type: string }

package/spec/request.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/flow-engineer/flow/blob/main/spec/request.schema.json",
+  "title": "AgentRequest",
+  "description": "One of the person's messages, as `flow test --agent-url` POSTs it to the agent's endpoint. This schema lists exactly what this version sends (additionalProperties is false so it stays exact); later versions may add optional fields, so an endpoint should ignore fields it does not know rather than validate requests strictly against this file.",
+  "type": "object",
+  "required": [
+    "conversationId",
+    "messageId",
+    "channel",
+    "message"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "conversationId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The conversation, as a phone number or chat would be: keep the history by it. In a test run it is \"<platform>:<session>.<scenario>.<platform>.<run>\", such as \"whatsapp:ses_8f2a.opening-hours.whatsapp.1\"."
+    },
+    "messageId": {
+      "type": "string",
+      "description": "The id this message has in the conversation (m1, m2, ...): what a reply's `replyTo`, a reaction's `messageId` or a read's `messageIds` names."
+    },
+    "channel": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The platform the run plays (whatsapp, sms, imessage, telegram, web), or the name given with --channel."
+    },
+    "message": {
+      "$ref": "#/$defs/message"
+    }
+  },
+  "$defs": {
+    "message": {
+      "type": "object",
+      "required": [
+        "text"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "type": "string",
+          "description": "What the person wrote; \"\" when they only sent a file (then it is the file's caption, if any)."
+        },
+        "replyTo": {
+          "type": "object",
+          "description": "The message they replied to (theirs or the agent's), quoted.",
+          "required": [
+            "text",
+            "fromAgent"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "text": {
+              "type": "string"
+            },
+            "fromAgent": {
+              "type": "boolean",
+              "description": "true when the quoted message is the agent's."
+            }
+          }
+        },
+        "choice": {
+          "type": "object",
+          "description": "They tapped a button or picked a list row rather than typing.",
+          "required": [
+            "title"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "The list row's id, when it has one."
+            },
+            "title": {
+              "type": "string"
+            }
+          }
+        },
+        "attachments": {
+          "type": "array",
+          "description": "Photos, voice notes and documents sent with the message.",
+          "items": {
+            "$ref": "#/$defs/attachment"
+          }
+        }
+      }
+    },
+    "attachment": {
+      "type": "object",
+      "required": [
+        "kind",
+        "mime",
+        "data"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "image",
+            "audio",
+            "document"
+          ]
+        },
+        "mime": {
+          "type": "string",
+          "description": "Such as image/jpeg, audio/ogg, application/pdf."
+        },
+        "name": {
+          "type": "string",
+          "description": "The file name, when the platform gives one (documents)."
+        },
+        "data": {
+          "type": "string",
+          "contentEncoding": "base64",
+          "description": "The file's bytes, base64 (standard alphabet, with padding)."
+        }
+      }
+    }
+  }
+}