@flow-engineer/flow 0.2.1 → 0.2.3

package/coding-agents/skill.md

@@ -1,6 +1,6 @@
 ---
 name: flow-framework
-description: Build or change a chat agent on Flow Framework (WhatsApp, SMS, iMessage, Telegram, web). Load when creating a Flow Framework agent, editing its prompt or skills, wiring it into the playground, or when code imports @flow-engineer/flow (formerly chinwag). Also load the flow-framework-tools skill (tools-skill.md) before writing tools and flow-framework-tests (test-skill.md) before writing tests.
+description: Build or change a chat agent on Flow Framework (WhatsApp, SMS, iMessage, Telegram, web), and serve its tools as an MCP server for Claude and ChatGPT or as a CLI. Load when creating a Flow Framework agent, editing its prompt or skills, wiring it into the playground, adding MCP or a CLI, or when code imports @flow-engineer/flow. Also load the flow-framework-tools skill (tools-skill.md) before writing tools and flow-framework-tests (test-skill.md) before writing tests.
 ---
 
 # Building an agent on Flow Framework
@@ -10,17 +10,20 @@ reply, acknowledges people fast, runs tools in parallel and waits for them, movi
 background only when the person writes again or it passes its limit.
 You write the agent's prompt, skills and tools; Flow Framework handles the conversation.
 
-Two more skills go with this one: `flow-framework-tools` (`tools-skill.md`) before writing or changing a
-tool, and `flow-framework-tests` (`test-skill.md`) before writing or changing a test.
+More skills go with this one: `flow-framework-tools` (`tools-skill.md`) before writing or changing a
+tool, `flow-framework-tests` (`test-skill.md`) before writing or changing a test, `flow-framework-context`
+(`context-skill.md`) before writing tools for a company that already has an app, API or database,
+and `flow-framework-auth` (`auth-skill.md`) when tools need to know who the person is.
 
 ## Start a new agent
 
 `npx @flow-engineer/flow new <name>` (lowercase letters, digits and dashes) makes `./<name>/` from the café
 example: a complete agent with tools and tests that depends on the `@flow-engineer/flow` package and imports
 `@flow-engineer/flow` and `@flow-engineer/flow/simulators`, with these skills in `.claude/skills/`. Run `npm install` there.
-Build in it, changing Pip's prompt, skills, tools and tests into yours. The owner copies
-`.env.example` to `.env` and puts one model key in it (never read or print it). Flow Framework does not
-issue that key; it is made at the provider: `OPENROUTER_API_KEY` at https://openrouter.ai/keys,
+Build in it, changing Pip's prompt, skills, tools and tests into yours. A provider key is optional:
+`npx @flow-engineer/flow link` (or `setup`) writes `FLOW_KEY`, the agent's one Flow key, into `.env` (never
+read or print it), and the agent calls models through Flow with it on $2 of Flow trial credit. A key of the owner's own wins over it, made
+at the provider: `OPENROUTER_API_KEY` at https://openrouter.ai/keys,
 `OPENAI_API_KEY` at https://platform.openai.com/api-keys, `ANTHROPIC_API_KEY` at
 https://console.anthropic.com/settings/keys, or `GEMINI_API_KEY` at https://aistudio.google.com/apikey.
 The first one with a value is used, and `CAFE_MODEL` sets the café's model id. Then `npm start`
@@ -41,6 +44,10 @@ my-agent/
   src/tools.ts                 the agent's tools (see tools-skill.md)
   src/agent.ts                 buildAgent(): the one place the agent is built
   src/main.ts                  runs it in the playground
+  src/mcp.ts                   optional: the tools as an MCP server (below)
+  src/cli.ts                   optional: the CLI file, for the organization's command line (below)
+  context/                     optional: the context pack the tools are written from (context-skill.md)
+  mcp.lock.json                optional: the tools of other MCP servers the agent uses (tools-skill.md)
   tests/tools/*.yaml           how each tool behaves in tests (see tools-skill.md)
   tests/scenarios/*.yaml       the tests (see test-skill.md)
 ```
@@ -89,8 +96,10 @@ is how long a finished tool's result waits for the others of its response; `shar
 guidance with a string.
 
 Models are reached through any OpenAI-compatible API. `openAICompatible()` with no key reads the
-first of `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and `GEMINI_API_KEY` that has a
-value, and uses that provider's default model (`MODEL` overrides it). With none it stops at once and
+first of `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` and
+`FLOW_KEY` (the agent's Flow key, on its trial credit, from `setup`) that has a value, and uses that provider's
+default model (`MODEL` overrides it). `flowModel()` uses Flow alone; when its credit is used up a
+call fails with code `trial_credit_used` and a next step (tell the owner to add their own key). With none it stops at once and
 names them. Pass `apiKey` and `baseURL` for anywhere else (`baseURL` alone for a local server that needs no key).
 
 Which model: recommend Claude Haiku 5.5 (`anthropic/claude-haiku-5.5`, the default above) or OpenAI
@@ -294,23 +303,32 @@ To demo what your backend does (an order ships), send the nudge it would send fr
 On a deployed agent, mount it in your own server with a token of at least 32 characters, from a
 secret: `const playground = play.handler(agent, { token: process.env.PLAYGROUND_TOKEN!, base: "/playground" })`,
 and hand it the requests under `/playground` (`if (url.pathname.startsWith("/playground")) return playground(req, res)`).
-Open `/playground/?token=...` once (it becomes an HttpOnly cookie and leaves the URL) or call the API
-with `Authorization: Bearer <token>`. Wrong tokens are limited per address, and every simulated
-message is logged with the person, channel, time and address.
+Open `/playground/?token=...` once (it becomes an HttpOnly, SameSite=Lax cookie and leaves the URL) or call the API
+with `Authorization: Bearer <token>`. The cookie survives a top-level return from sign-in on another site;
+the API still accepts only requests from the playground’s own origin. Wrong tokens are limited per address,
+and every simulated message is logged with the person, channel, time and address.
 
 ## Put it on a phone
 
 To chat with the agent from the owner's phone, with no tunnel and no key made by hand, run these
-from the agent's folder (`npx @flow-engineer/flow init` makes a starter in an empty one). Only
-`chat` reads stdin; nothing else asks for input or needs a terminal.
+from the agent's folder (`npx @flow-engineer/flow init --display-name "<name>"` makes a starter in
+an empty one: first ask the owner what people should call their agent, such as "FlatX agent"; the
+phone's first message is `Hi FlatX agent (ref <code>)`, and `package.json`'s `displayName` keeps it).
+Only `chat` reads stdin; `init` asks for the name only in a terminal, and nothing else asks for input.
 
 ```sh
-printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat   # locally, no account: one message per line, replies printed
-npx @flow-engineer/flow link --json          # signs in and runs setup when needed, then the link; give its say_to_person to the owner
-npx @flow-engineer/flow test --synthetic     # the tests, on the key setup wrote
-npm start                                    # the agent; the owner texts it while it runs
+npx @flow-engineer/flow link --json          # signs in and runs setup when needed (Flow's trial model key too), then the channel's own link (t.me, wa.me, sms:); give its say_to_person to the owner
+npm start                                    # the agent: its playground link, and the owner texts it while it runs
+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
 ```
 
+When the owner asks how to test it, recommend first the playground (`npm start`, then open the
+link it prints: the test people and the channels side by side, with Debug), then their phone (the
+`link`, while `npm start` runs). `chat` and `test --synthetic` are for you to check your own work;
+do not offer them to the owner as ways to test.
+
 `link` runs `login` first when not signed in: it opens the owner's browser itself and prints the
 link and code at once (with `--json` the first line is `{"status":"pending","verification_uri":...,
 "user_code":...,"next":...}`), waits at most 120 s (`--timeout <s>`), then exits 4 with the code
@@ -351,3 +369,187 @@ touches a chat; call `await agent.flushTraces()` before the process exits. Tests
 `node --test` never send from the environment. Under `flow test` the traces say they are a test's
 (`chinwag.run_kind` is "test", else "production", and each turn names the test session as
 `chinwag.test.session`), so the dashboard keeps them apart from real conversations.
+
+## Serve the tools over MCP
+
+The same tools and skills go to Claude, ChatGPT and any MCP host as an MCP server. Install the
+SDK it runs on (`npm i @modelcontextprotocol/server@2.3.1`, the version Flow Framework pins) and add
+`src/mcp.ts`:
+
+```ts
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { mcpServer } from "@flow-engineer/flow/mcp";
+import { tools } from "./tools.ts";
+
+export const mcp = mcpServer({
+  name: "acme",
+  version: "1.0.0",
+  tools,
+  dir: fileURLToPath(new URL("../agent", import.meta.url)),   // its skills; AGENTS.md is not sent
+  // auth: { issuer, resource, scopes, verify }               // sign-in: the flow-framework-auth skill
+});
+createServer((req, res) => void mcp.node(req, res)).listen(8790);   // Streamable HTTP at /mcp
+```
+
+- `mcp.fetch(request)` serves a web-standard `Request` instead (Cloudflare Workers, Deno, Bun), so
+  it mounts beside the chat agent in one process or runs on its own: it needs no model, channels
+  or store.
+- Hosts get the skills as the server's instructions (each one's description) and read one with the
+  `read_skill` tool. A skill that tells the chat agent to use `send_*` or `share_updates` makes
+  no sense to a host: `flow check` warns about it.
+- Every part can be changed: `instructions` replaces the instructions, `descriptor(tool, generated)`
+  changes any tool's MCP descriptor, `extend(server)` adds handlers of your own (resources,
+  prompts) to the SDK's server, `path` moves the endpoint, `allowedHosts` checks the Host header.
+- Try it locally with `claude mcp add --transport http acme http://localhost:8790/mcp`.
+- Run `npx flow check` from the agent's folder before serving: it refuses tools that cannot be
+  described exactly (the `flow-framework-tools` skill lists the rules).
+
+## A CLI for the organization
+
+The same tools as commands, over the organization's MCP server, with the same sign-in and gating.
+It runs on Stricli (`@stricli/core`, the framework Sentry's CLI is built on). Every tool is already a
+command under its own name (`place_order` is `acme place-order`); a CLI file adds what needs
+judgement. Install `@modelcontextprotocol/client@2.3.1` and `@stricli/core@1.3.0` (the versions
+Flow Framework pins) and write `src/cli.ts`:
+
+```ts
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { defineCli, runCli } from "@flow-engineer/flow/cli";
+
+export const cli = defineCli({
+  name: "acme",
+  server: process.env.ACME_SERVER ?? "https://acme.example.com/mcp",
+  description: "Acme's orders and customers",
+  groups: { order: "Place and track orders" },
+  commands: {
+    "order list": { tool: "list_orders", columns: ["order_id", "status", "total"], alias: "orders" },
+    "order view": { tool: "get_order", args: ["order_id"], examples: ["acme order view BL-1042 --json"] },
+    "order place": { tool: "place_order" },
+  },
+});
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exit(await runCli(cli, process.argv.slice(2)));
+```
+
+- Words are groups then a verb: `order` is a **command group**, `list`, `view` and `place` its
+  subcommands. `acme order` and `acme order -h` list the group's subcommands, `acme order place -h`
+  that command's flags and examples, and `acme -h` the groups and top-level commands. A word is a
+  group or a command, never both. `groups` gives each group its line in help.
+- `args` are the input fields taken as positional arguments, `columns` a list's table, `view` one
+  record's fields, `alias` another name, `examples` lines for help. Every other input field is a
+  flag (`order_id` is `--order-id`); a list is a repeatable or comma-separated flag; an object or a
+  list of objects takes JSON, or `@file.json`, and its help shows the shape
+  (`JSON list of {item, size, milk?}`).
+- A command of the team's own is any Stricli command: `"report daily": { command: buildCommand({ ... }) }`
+  with `buildCommand` from `@stricli/core`; inside it, `this.cli.call(tool, input)` calls the server's
+  tools and `this.cli.print(value, { json })` prints like the rest.
+- Installed, it is the organization's own command: `"bin": { "acme": "src/cli.ts" }` in its package
+  (node runs `.ts` files outside `node_modules`; publish a compiled `.js` bin to npm). While building
+  it, run it with `npm run cli -- order -h`: npm takes flags before `--` as its own.
+- Every tool command takes `--json` and `--fields a,b`; one that changes things takes `--dry-run`; one
+  that may delete or overwrite asks first in a terminal and needs `--yes` without one. Exit codes: 0
+  done, 1 the tool failed, 2 wrong command or arguments (with the help to read), 3 sign-in needed, 4
+  needs `--yes`, 5 the server could not be reached. `--server <url>` and `--token <token>` work on
+  every command. `acme auth login` signs in on the organization's own login (tokens in
+  `~/.config/acme/`, mode 600), `ACME_TOKEN` is for CI, `acme tools` lists every tool and schema, and
+  `acme skill --write ~/.claude/skills` installs the CLI's SKILL.md, made from the tools and the CLI
+  file, for coding agents. For any MCP server without a CLI file, `npx flow cli --server <url> -h`.
+- `npx flow check` checks the CLI file against the tools: a command naming a tool that does not
+  exist, an `args` field the input lacks, a `columns` or `view` field the output lacks, two commands
+  with one name, a word that is both a command and a group, or one of the CLI's own words (`auth`,
+  `tools`, `skill`) is an error; a tool no command names is a warning (it keeps its own name).
+
+
+### Native plugins and standalone MCP
+
+The standalone `/mcp` endpoint includes the skills list and `read_skill`. Native plugins
+copy the agent's `agent/skills/` folder and connect to `/mcp/plugin`, which serves tools only,
+so a host receives each skill once. Both paths share tools, auth and descriptor overrides.
+`mcpServer({ ..., plugin: false })` disables the plugin path; `plugin: { path: "/native" }`
+moves it. `handle.plugin` exposes its path and descriptors. Your `instructions` override
+applies to both endpoints, and `extend` can add SDK handlers on both.
+
+From the agent folder, run:
+
+```sh
+flow plugin --server https://agent.example.com/mcp --out plugins
+flow check --plugin plugins
+```
+
+`plugins/claude/` uses Claude Code's `.claude-plugin/plugin.json` and `.mcp.json` with
+`type: "http"`. `plugins/agent-plugins/` uses Agent Plugins 1.0.0 root `plugin.json` and
+`mcp.json` with `type: "streamable-http"`; Codex supports this portable format.
+Pass `--name` to override the package name. For a custom plugin route, pass its URL ending
+in `/plugin`, or edit the generated MCP config. No token is written into either package.
+Regenerate after changing a skill or its assets; `check --plugin` compares content hashes.
+Generated files remain plain files in your repository: customize manifests and add components
+alongside them. Regeneration rewrites manifests and source skill copies; keep hand-written
+skills outside those source paths.
+
+Formats checked 18 October 2026: [Agent Plugins 1.0.0](https://agent-plugins.org/specification),
+[OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins), and
+[Claude Code plugin reference](https://code.claude.com/docs/en/plugins-reference).
+
+MCP calls emit `tool.start`/`tool.end` with surface (`mcp`, `mcp-plugin`, `cli`), client name
+and version, session, person, duration, outcome and error. CLI calls send command and an
+idempotency key in `_meta`; a caller can reuse its key on a retry. `defineCli`'s `version`
+sets its client version (default `"1"`). Neither CLI arguments nor trace credentials go in `_meta`.
+`mcpServer` uses `FLOW_FRAMEWORK_TRACES_*`, like chat agents, or explicit `traces` options;
+`traces: false` disables export without disabling your event sinks. `await handle.flushTraces()`
+flushes its bounded background queue. Each tool call is a root trace without a conversation;
+arguments and results require `FLOW_FRAMEWORK_TRACES_CONTENT=1`. Legacy clients' initialization
+metadata is retained for up to 24 hours in at most 4,096 sessions; bearer tokens are never cached.
+
+### Local playground CLI
+
+To exercise the real CLI on your computer, pass `localCli: { channel: "terminal", config: cli }`
+to `play.listen(agent, port, options)` or a locally mounted `play.handler(agent, options)`.
+`cli` is the team's existing `defineCli` configuration, with its server URL; the named channel
+must exist. This opens an independent CLI session in that tab, with real stdout/stderr, exit
+codes, interactive input and confirmation prompts. It does not use the selected test person's
+identity. Run `auth login`, open the login link and return, then use commands or `chat` (`/exit`
+leaves chat). Reload reconnects. New CLI session discards only this runner's temporary sign-in;
+server restart or 30 minutes without browser activity also ends it. Clear output keeps sign-in.
+An operation already accepted by the agent may still complete after its client session ends.
+
+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
+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;
+`CliIO.env` overrides the inherited process environment and `CliIO.signal` cancels sign-in and
+terminal HTTP requests. Installed CLI defaults stay unchanged.
+
+### Terminal conversations
+
+`chat` talks directly to the agent, using the same bearer as MCP; it is not an MCP tool. `defineCli({ name: "acme", server, agent: "https://agent.example.com/agent/terminal" })`
+overrides the terminal URL; the default is the MCP server's origin plus `/agent/terminal`.
+`acme chat "Which orders are ready?" --json` prints one response; `acme chat` reads a TTY until
+Ctrl-D or `/exit`. Without a TTY pass a message to `chat` (an interactive chat exits 2); sign-in failures exit 3.
+Human chat shows a `You ›` input prompt, a waiting indicator and agent replies under the CLI's
+name. `--json` keeps stdout as one JSON response per line, without those labels. Embedded CLIs
+can supply `CliIO.lines(prompt?)` and their own output handlers to replace the presentation.
+`chat.json` is mode 600 and scoped by terminal endpoint. `--new` forgets the terminal's saved
+reference; the agent keeps its one-person history across channels. It does not erase a person's
+WhatsApp history. Teams can replace `chat` with their own Stricli command in `commands`.
+
+Mount the optional terminal handler beside MCP (no model or extra dependency in the CLI):
+
+```ts
+import { terminalServer } from "@flow-engineer/flow/mcp";
+const terminal = terminalServer({ agent: () => agent, auth });
+const agent = createAgent({ ...options, channels: [...channels, terminal.channel] });
+// Route terminal.path to terminal.fetch(request), and MCP's paths to mcp.fetch(request).
+```
+
+`terminalServer` accepts `path` and `channel` overrides. It verifies auth on every POST,
+serializes concurrent requests per person, and returns `{ conversationId, replies }` after the
+turn settles. The authenticated key becomes the same person that `resolve` returns on other
+channels. A body cannot choose its own person; a conversation reference from another person is
+refused. Its custom UI uses Markdown and exports turns as channel `cli`.
+For your own HTTP adapters, `agent.request({ channel, key, text, conversationId? })` exposes this
+without the handler. Supply a verified key and serialize calls for that channel and person.

package/coding-agents/test-skill.md

@@ -5,7 +5,9 @@ description: Write or change tests for a Flow Framework agent (tests/scenarios/*
 
 # Writing tests for a Flow Framework agent
 
-Read the `flow-framework` skill (`skill.md`) first if you haven't.
+Read the `flow-framework` skill (`skill.md`) first if you haven't. Turn the situations in
+`context/examples/` (the `flow-framework-context` skill) into scenarios, and run `npx flow check`
+before the tests when the agent serves MCP or a CLI.
 
 A test is a scenario: a situation to put the agent in, played through a platform simulator by a
 model acting as the person, with the agent's tools played by a model from `tests/tools/*.yaml`

package/coding-agents/tools-skill.md

@@ -6,7 +6,9 @@ description: Write or change a Flow Framework agent's tools and their test files
 # Writing tools for a Flow Framework agent
 
 Read the `flow-framework` skill (`skill.md`) first if you haven't. Tests that use these tool files are
-in the `flow-framework-tests` skill (`test-skill.md`).
+in the `flow-framework-tests` skill (`test-skill.md`). For a company with an existing app or API, build
+the context pack first (the `flow-framework-context` skill, `context-skill.md`) and write the tools from
+it.
 
 ## The tool
 
@@ -49,6 +51,77 @@ export const findSlots = tool({
   searched ("Mon Oct 12 through Sun Oct 18", "all open times") and never cut results short
   silently. If there are more, say so.
 
+## Tools from the context pack
+
+- One tool per task in `context/workflows.arazzo.yaml`, never one per endpoint: "place an order"
+  is one tool even when it is three API calls. A host or a small model chooses well among a few
+  task-shaped tools and badly among dozens of raw ones.
+- Take the input and output shapes from `context/openapi.yaml` with `context/overlay.yaml` applied,
+  the words and rules from `business.md`, and leave out the personal fields `data.md` marks unless
+  the task needs them.
+- `signIn` and `hints` come from `context/access.yaml` (below).
+- When the team sends a new spec, re-read the overlay and the workflows against it, change only the
+  tools whose operations changed, and run `flow check` and the tests.
+
+## The fields MCP and the CLI read
+
+The same tool is served to Claude and ChatGPT over MCP (`@flow-engineer/flow/mcp`) and as a command (`@flow-engineer/flow/cli`).
+These optional fields describe it there. **Chat ignores all of them**: they change nothing on
+WhatsApp, SMS or iMessage.
+
+```ts
+export const placeOrder = tool({
+  name: "place_order",
+  title: "Place an order",                         // default: "Place order", from the name
+  description: "Place a confirmed pickup order. Returns the order number and when it will be ready.",
+  input: z.object({ name: z.string(), items: z.array(item) }),
+  output: z.object({ order_id: z.string(), ready_by: z.string() }),  // the result's shape
+  status: { running: "Placing your order…", done: "Order placed" },  // at most 64 characters each
+  signIn: "required",                              // "required" (default) | "optional" | "none"
+  hints: { readOnly: false, destructive: false, idempotent: false, openWorld: false },
+  run: async (input, context) => pos.place(input, context.idempotencyKey),
+});
+```
+
+- `output`: over MCP the result is checked against it and sent as structured content, and the CLI
+  shows its fields with `--json` and `--fields`. Give it whenever the result has a fixed shape.
+- `signIn`: "none" for what anyone may do signed out (the menu, opening hours), "optional" for what
+  works either way and does more signed in, "required" (the default) for everything about a
+  person's own account. It applies only where sign-in is set up (the `flow-framework-auth` skill).
+- `hints` describe the tool to hosts, which ask the person before risky calls; nothing enforces
+  them. `readOnly` (default false: a tool counts as a write), `destructive` (a write that may delete
+  or overwrite; default true for writes), `idempotent` (calling again with the same input changes
+  nothing more; default false), `openWorld` (reaches outside the business's own systems, such as the
+  web; default true). Set them honestly: a read-only tool should say so, or hosts treat it as a
+  write and the CLI asks for `--yes`.
+- `flow check` (from the agent's folder) refuses what cannot be served exactly: a name outside
+  1 to 128 of `A-Z a-z 0-9 _ - .`, an empty description, a description naming a chat-only tool
+  (`send_*`, `share_updates`, `load_skill`), an input that is not a `z.object`, an input or output
+  with no exact JSON Schema (`z.date()`, transforms; use an ISO string), `readOnly` with
+  `destructive`, or a status line over 64 characters.
+
+## Tools from another MCP server
+
+An existing MCP server's tools become the agent's own, so the agent uses them on WhatsApp or
+iMessage like any tool:
+
+```ts
+import { mcpTools } from "@flow-engineer/flow/mcp";
+
+export const tools = [
+  ...myTools,
+  ...(await mcpTools({ name: "todoist", url: "https://ai.todoist.net/mcp", headers: { authorization: `Bearer ${process.env.TODOIST_KEY}` } })),
+];
+```
+
+- They are pinned: `flow mcp update` (from the agent's folder) writes the server's tools to
+  `mcp.lock.json`, and only those are used. Commit it with the tests. A tool the server changes or
+  removes later is refused with a clear error until the lock is updated, tested and committed; a
+  tool it adds is not offered until then. `only: [...]` keeps a few of its tools, `prefix` keeps
+  two servers' names apart, and `live: true` skips the lock (for a server you do not build around).
+- Each needs a `tests/tools/<tool>.yaml` like any tool. A tool without `readOnlyHint` counts as a
+  write. Keep keys in the environment, never in the lock.
+
 ## The tool's test file
 
 In tests no real tool runs: a model plays each tool from the scenario's world. `tests/tools/<tool>.yaml`
@@ -87,3 +160,7 @@ responses:
   never as written dates, which go stale.
 - Latency lives only here. Scenarios describe situations ("the point of sale is slow this
   morning"); the simulator picks the matching response and latency on each call.
+
+## Authenticated backend access
+
+A tool can use `await context.credentials!.get<YourClient>("backend")` when the agent/server supplies a `credentials` provider. That provider resolves access from Flow Framework’s verified `context.key`/`context.person`, independently of model input. Share it between chat and MCP; never put credentials into tool schemas, outputs, errors or logs. See `auth-skill.md` for verified-phone and OAuth entry points.

package/dist/cli/src/auth.d.ts

@@ -0,0 +1,11 @@
+import { type OAuthClientProvider } from "@modelcontextprotocol/client";
+import type { CliConfig } from "./commands.ts";
+export declare function configDir(config: CliConfig): string;
+/** An OAuth client provider whose state lives in the CLI's auth file, for one server. */
+export declare function storedProvider(config: CliConfig, server: string, redirectUrl?: string, signal?: AbortSignal): OAuthClientProvider;
+/** Terminal HTTP uses the same stored OAuth session as MCP, including refresh and issuer binding. */
+export declare function storedAccessToken(config: CliConfig, server: string, forceRefresh?: boolean, signal?: AbortSignal): Promise<string | undefined>;
+export declare function isSignedIn(config: CliConfig, server: string): boolean;
+export declare function signOut(config: CliConfig, server: string): void;
+/** Sign in: the browser goes to the organization's own login, and comes back to a loopback port. */
+export declare function signIn(config: CliConfig, server: string, signal?: AbortSignal): Promise<void>;

package/dist/cli/src/auth.js

@@ -0,0 +1,147 @@
+// The CLI's sign-in: the same OAuth a host such as Claude runs against the organization's MCP
+// server, as a native app with a loopback redirect, so people sign in on the organization's own
+// pages. Tokens are kept per server in ~/.config/<name>/auth.json (XDG_CONFIG_HOME), mode 600, and
+// refreshed by the SDK. A token in <NAME>_TOKEN (CI, agents) is used as is and never stored.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { auth, discoverOAuthServerInfo, refreshAuthorization, } from "@modelcontextprotocol/client";
+export function configDir(config) {
+    return config.directory ?? join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), config.name);
+}
+function authFile(config) {
+    return join(configDir(config), "auth.json");
+}
+function readAll(config) {
+    const file = authFile(config);
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+}
+function writeAll(config, all) {
+    mkdirSync(configDir(config), { recursive: true, mode: 0o700 });
+    const file = authFile(config);
+    writeFileSync(file, JSON.stringify(all, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(file, 0o600);
+}
+/** An OAuth client provider whose state lives in the CLI's auth file, for one server. */
+export function storedProvider(config, server, redirectUrl, signal) {
+    const read = () => readAll(config)[server] ?? {};
+    const write = (change) => {
+        signal?.throwIfAborted();
+        const all = readAll(config);
+        all[server] = { ...all[server], ...change };
+        writeAll(config, all);
+    };
+    const metadata = {
+        client_name: `${config.name} CLI`,
+        application_type: "native",
+        redirect_uris: redirectUrl ? [redirectUrl] : [],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+    };
+    return {
+        get redirectUrl() {
+            return redirectUrl;
+        },
+        get clientMetadata() {
+            return metadata;
+        },
+        ...(config.clientMetadataUrl ? { clientMetadataUrl: config.clientMetadataUrl } : {}),
+        clientInformation: () => config.clientId ? { client_id: config.clientId } : read().client,
+        saveClientInformation: (client) => write({ client }),
+        tokens: () => read().tokens,
+        saveTokens: (tokens) => write({ tokens, tokensSavedAt: Date.now() }),
+        state: () => { const state = randomBytes(32).toString("base64url"); write({ state }); return state; },
+        discoveryState: () => read().discovery,
+        saveDiscoveryState: (discovery) => write({ discovery }),
+        redirectToAuthorization: async (url) => {
+            if (config.openUrl)
+                await config.openUrl(url.toString());
+            else
+                console.error(`Open this link to sign in:\n  ${url}`);
+        },
+        saveCodeVerifier: (verifier) => write({ verifier }),
+        codeVerifier: () => {
+            const verifier = read().verifier;
+            if (!verifier)
+                throw new Error("No sign-in in progress.");
+            return verifier;
+        },
+    };
+}
+/** Terminal HTTP uses the same stored OAuth session as MCP, including refresh and issuer binding. */
+export async function storedAccessToken(config, server, forceRefresh = false, signal) {
+    signal?.throwIfAborted();
+    const saved = readAll(config)[server];
+    if (!saved?.tokens)
+        return undefined;
+    const { tokens } = saved;
+    const expired = saved.tokensSavedAt !== undefined && tokens.expires_in !== undefined && saved.tokensSavedAt + tokens.expires_in * 1000 <= Date.now() + 30_000;
+    if (!expired && !forceRefresh)
+        return tokens.access_token;
+    if (!tokens.refresh_token || (!saved.client && !config.clientId))
+        return undefined;
+    const info = await discoverOAuthServerInfo(server);
+    const issuer = info.authorizationServerMetadata?.issuer ?? String(info.authorizationServerUrl);
+    if (tokens.issuer && tokens.issuer !== issuer)
+        throw new Error("The authorization server changed; sign in again.");
+    const fresh = await refreshAuthorization(info.authorizationServerUrl, { metadata: info.authorizationServerMetadata, clientInformation: config.clientId ? { client_id: config.clientId } : saved.client, refreshToken: tokens.refresh_token, resource: info.resourceMetadata?.resource });
+    await storedProvider(config, server, undefined, signal).saveTokens({ ...fresh, issuer });
+    return fresh.access_token;
+}
+export function isSignedIn(config, server) {
+    return Boolean(readAll(config)[server]?.tokens);
+}
+export function signOut(config, server) {
+    const all = readAll(config);
+    delete all[server];
+    writeAll(config, all);
+}
+/** Sign in: the browser goes to the organization's own login, and comes back to a loopback port. */
+export async function signIn(config, server, signal) {
+    signal?.throwIfAborted();
+    const callback = createServer();
+    await new Promise((resolve, reject) => { callback.once("error", reject); callback.listen(config.redirectPort ?? 0, "127.0.0.1", resolve); });
+    const { port } = callback.address();
+    const redirectUrl = `http://127.0.0.1:${port}/callback`;
+    let cancel;
+    try {
+        const provider = storedProvider(config, server, redirectUrl, signal);
+        const code = new Promise((resolve, reject) => {
+            cancel = () => reject(new Error("Sign-in cancelled."));
+            signal?.addEventListener("abort", cancel, { once: true });
+            if (signal?.aborted)
+                cancel();
+            callback.on("request", (req, res) => {
+                const url = new URL(req.url ?? "/", redirectUrl);
+                if (url.pathname !== "/callback")
+                    return void res.writeHead(404).end();
+                const error = url.searchParams.get("error");
+                const got = url.searchParams.get("code");
+                if (req.method !== "GET" || req.headers.host !== `127.0.0.1:${port}` || !readAll(config)[server]?.state || url.searchParams.get("state") !== readAll(config)[server]?.state) {
+                    res.writeHead(400, { "content-type": "text/plain" }).end("Invalid sign-in response.");
+                    return;
+                }
+                res.writeHead(200, { "content-type": "text/plain; charset=utf-8" }).end(got ? `Signed in. You can close this tab and go back to ${config.name}.` : `Sign-in failed: ${error ?? "no code"}.`);
+                if (got)
+                    resolve({ code: got, iss: url.searchParams.get("iss") ?? undefined });
+                else
+                    reject(new Error(`Sign-in failed: ${error ?? "no code came back"}.`));
+            });
+        });
+        // Cancellation may arrive while discovery or the authorization request is still in flight.
+        void code.catch(() => { });
+        const first = await auth(provider, { serverUrl: server });
+        if (first === "AUTHORIZED")
+            return;
+        const answer = await code;
+        await auth(provider, { serverUrl: server, authorizationCode: answer.code, iss: answer.iss });
+    }
+    finally {
+        if (cancel)
+            signal?.removeEventListener("abort", cancel);
+        callback.close();
+    }
+}