@flow-engineer/flow 0.2.3 → 0.3.0

package/examples/cafe/src/main.ts

@@ -1,14 +1,19 @@
-// Pip in the playground: `npm start`, then open the printed link and pick a test person. With
-// FLOW_MESSAGING_KEY in .env (`npx @flow-engineer/flow link` puts it there), Pip is on Telegram
+// The agent in the playground: `npm start`, then open the printed link and pick a test person. With
+// FLOW_MESSAGING_KEY in .env (`npx @flow-engineer/flow link` puts it there), it is on Telegram
 // too (and WhatsApp and iMessage when .env names their senders), through Flow Messaging's event
-// stream: an outbound connection, so no public URL or tunnel.
+// stream: an outbound connection, so no public URL or tunnel. It listens on PORT, else 8788 or the
+// next free port above it.
 
+import { readFileSync } from "node:fs";
+import { choosePort, markRunning } from "../../../src/index.ts";
 import { flowMessaging } from "../../../flow-messaging/src/index.ts";
 import { simulators } from "../../../simulators/src/index.ts";
 import { buildAgent } from "./agent.ts";
 import { channelNames, flowChannels } from "./channels.ts";
 
-const play = simulators({ title: "Pip · Bean & Leaf" });
+// What people call it: package.json's displayName (`npx @flow-engineer/flow link --display-name <name>` changes it).
+const { displayName: name = "Pip" } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { displayName?: string };
+const play = simulators({ title: `${name} · Bean & Leaf` });
 const fm = process.env.FLOW_MESSAGING_KEY ? flowMessaging() : undefined;
 const channels = fm ? flowChannels(fm) : [];
 let agent: ReturnType<typeof buildAgent>;
@@ -18,12 +23,22 @@ try {
   console.error((error as Error).message); // such as no model key in .env
   process.exit(1);
 }
-const port = Number(process.env.PORT ?? 8788);
-const { url } = await play.listen(agent, port);
-console.log(`Pip's playground: ${url}/`);
+let url: string;
+try {
+  const { port, note } = await choosePort("PORT", 8788, { command: "npm start" });
+  if (note) console.log(note);
+  ({ url } = await play.listen(agent, port));
+} catch (error) {
+  console.error((error as Error).message); // such as the port PORT names being in use
+  process.exit(1);
+}
+const port = Number(new URL(url).port);
+// `npx @flow-engineer/flow link` reads it (.flow/running.json) to say whether to start or restart this.
+markRunning(url);
+console.log(`${name}'s playground: ${url}/`);
 console.log(`Every channel side by side: ${url}/person`);
 if (fm) {
-  // Events sent while Pip was not running come when it starts again (.flow/ keeps the last one handled).
+  // Events sent while it was not running come when it starts again (.flow/ keeps the last one handled).
   const live = fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor", port: port + 1 });
   console.log(`On ${channelNames(channels)} through Flow Messaging (${live.mode}). The phone link: npx @flow-engineer/flow link`);
   live.stopped.then((why) => console.error(`Flow Messaging stopped: ${why.message} Then: npx @flow-engineer/flow setup`));

package/examples/cafe/src/mcp.ts

@@ -1,9 +1,11 @@
-// Pip's tools and skills as an MCP server, for Claude, ChatGPT or any MCP host: `npm run mcp`.
+// The agent's tools and skills as an MCP server, for Claude, ChatGPT or any MCP host: `npm run mcp`.
 // The same tools the chat agent uses; no model key needed, since the host brings its own model.
 
+import { readFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { fileURLToPath } from "node:url";
 import { mcpServer } from "../../../mcp/src/index.ts";
+import { choosePort } from "../../../src/index.ts";
 import { tools } from "./tools.ts";
 
 export const mcp = mcpServer({
@@ -15,8 +17,24 @@ export const mcp = mcpServer({
   // auth: { issuer, resource, scopes, verify } (the chinwag-auth skill).
 });
 
-const port = Number(process.env.MCP_PORT ?? 8790);
-createServer((req, res) => void mcp.node(req, res)).listen(port, "127.0.0.1", () => {
-  console.log(`Pip's MCP server: http://127.0.0.1:${port}/mcp`);
-  console.log(`Try it in Claude Code: claude mcp add --transport http bean-and-leaf http://127.0.0.1:${port}/mcp`);
-});
+// What people call it: package.json's displayName.
+const { displayName: name = "Pip" } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { displayName?: string };
+// MCP_PORT, else 8790 or the next free port above it.
+let port: number;
+try {
+  const chosen = await choosePort("MCP_PORT", 8790, { command: "npm run mcp" });
+  port = chosen.port;
+  if (chosen.note) console.log(`${chosen.note} The CLI then needs CAFE_SERVER=http://127.0.0.1:${port}/mcp.`);
+} catch (error) {
+  console.error((error as Error).message);
+  process.exit(1);
+}
+createServer((req, res) => void mcp.node(req, res))
+  .once("error", (error) => {
+    console.error(`${error.message}. Run: MCP_PORT=<port> npm run mcp`);
+    process.exit(1);
+  })
+  .listen(port, "127.0.0.1", () => {
+    console.log(`${name}'s MCP server: http://127.0.0.1:${port}/mcp`);
+    console.log(`Try it in Claude Code: claude mcp add --transport http bean-and-leaf http://127.0.0.1:${port}/mcp`);
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-engineer/flow",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "An open-source runtime for chat agents that feel like a person texting back.",
   "license": "Apache-2.0",
   "repository": {