@flow-engineer/flow 0.2.1 → 0.2.3

package/dist/src/store.js

@@ -153,6 +153,24 @@ export class Store {
     async addIdentity(conversationId, channel, address, verifiedBy) {
         await this.db.run("INSERT INTO identities (agent_id, channel, address, conversation_id, verified_by) VALUES (?, ?, ?, ?, ?) ON CONFLICT DO NOTHING", [this.agentId, channel, address, conversationId, verifiedBy]);
     }
+    /** Bind verified login proof; an identity already owned by another account cannot move. */
+    async linkIdentity(conversationId, channel, address) {
+        return this.db.transaction(async (tx) => {
+            const lock = this.db.dialect === "postgres" ? " FOR UPDATE" : "";
+            const [previous] = await tx.query(`SELECT conversation_id FROM identities WHERE agent_id = ? AND channel = ? AND address = ?${lock}`, [this.agentId, channel, address]);
+            const rows = await tx.query(`INSERT INTO identities (agent_id, channel, address, conversation_id, verified_by)
+        VALUES (?, ?, ?, ?, 'resolver') ON CONFLICT (agent_id, channel, address) DO UPDATE SET
+        conversation_id = excluded.conversation_id, verified_by = excluded.verified_by
+        WHERE identities.conversation_id = excluded.conversation_id OR EXISTS (
+          SELECT 1 FROM conversations c WHERE c.agent_id = identities.agent_id
+          AND c.id = identities.conversation_id AND c.person_key NOT LIKE 'key:%') RETURNING conversation_id`, [this.agentId, channel, address, conversationId]);
+            if (rows.length && previous && previous.conversation_id !== conversationId) {
+                // Signing in must not undo an anonymous sender's STOP or other no-contact preferences.
+                await tx.run("UPDATE no_contact SET conversation_id = ? WHERE agent_id = ? AND conversation_id = ?", [conversationId, this.agentId, previous.conversation_id]);
+            }
+            return rows.length > 0;
+        });
+    }
     async touchIdentity(channel, address, at) {
         await this.db.run("UPDATE identities SET last_message_at = ? WHERE agent_id = ? AND channel = ? AND address = ?", [at, this.agentId, channel, address]);
     }

package/dist/src/tools.d.ts

@@ -13,6 +13,8 @@ export interface ToolContext {
     key: string | null;
     /** The channel of their latest message. */
     channel: string;
+    /** Provider/server-issued address on a chat channel; absent for standalone MCP calls. */
+    address?: string;
     /** The model's id for this call, as the history keeps it. */
     callId: string;
     /**
@@ -23,7 +25,40 @@ export interface ToolContext {
     idempotencyKey: string;
     /** Aborted when the conversation closes (the person was forgotten): stop and drop the work. */
     signal: AbortSignal;
+    /** Server-side backend access for this verified person. Never supplied by the model or serialized into history or traces. */
+    credentials?: Credentials;
 }
+/** A business supplies named backend credentials or clients, resolved afresh for the verified person. */
+export type CredentialProvider = (name: string, context: Readonly<Omit<ToolContext, "credentials">>) => unknown | Promise<unknown>;
+export interface Credentials {
+    /** The business decides how to obtain, refresh and revoke access. The name is written by the tool author, not an account id from the model. */
+    get<T = unknown>(name: string): Promise<T>;
+}
+/** Server-side identity at a chat tool boundary. No credentials or model-supplied account ids. */
+export interface ChatAuthContext {
+    conversationId: string;
+    person: string;
+    key: string | null;
+    channel: string;
+    address: string;
+    tool: string;
+    signal: AbortSignal;
+}
+/** Brand-owned login: OAuth, an existing login page, verified phone, or a custom challenge. */
+export interface ChatAuth {
+    /** Recheck a resolved account's current access. Without this, a non-null resolved key is enough. */
+    verify?: (context: Readonly<ChatAuthContext>) => boolean | Promise<boolean>;
+    /** Called only when a protected operation needs authentication. A custom in-chat prompt needs no URL. */
+    signIn: (context: Readonly<ChatAuthContext>) => {
+        message: string;
+        url?: string;
+    } | Promise<{
+        message: string;
+        url?: string;
+    }>;
+}
+/** Bind backend access without putting secrets on an enumerable context or in any event. */
+export declare function toolContext(context: Omit<ToolContext, "credentials">, provider?: CredentialProvider): ToolContext;
 export interface Tool<Input = any> {
     name: string;
     description: string;
@@ -31,6 +66,35 @@ export interface Tool<Input = any> {
     run(input: Input, context: ToolContext): Promise<unknown> | unknown;
     /** The longest the reply waits for this tool before it moves to the background (default: the agent's, 60 s). */
     deadlineMs?: number;
+    /** A name for people ("Place an order"); derived from `name` when absent. */
+    title?: string;
+    /** The result's shape. Over MCP the result is checked against it and sent as structured content too. */
+    output?: z.ZodType;
+    /** Short lines a host shows while the tool runs and once it is done (at most 64 characters each). */
+    status?: {
+        running?: string;
+        done?: string;
+    };
+    /**
+     * Whether the person must be signed in. "required" (the default) refuses a call without sign-in,
+     * "optional" runs either way, "none" never needs it. Enforced where sign-in is configured:
+     * createAgent({ auth }) for chat, or mcpServer({ auth }) for MCP. Existing agents without auth
+     * keep their current behaviour.
+     */
+    signIn?: SignIn;
+    /** How the tool behaves, for hosts to decide what to ask the person first. Nothing enforces them. */
+    hints?: ToolHints;
+}
+export type SignIn = "required" | "optional" | "none";
+export interface ToolHints {
+    /** It changes nothing (default false: a tool counts as a write). */
+    readOnly?: boolean;
+    /** A write that may delete or overwrite (default true for writes; always false for reads). */
+    destructive?: boolean;
+    /** Calling it again with the same input changes nothing more (default false). */
+    idempotent?: boolean;
+    /** It reaches things outside the business's own systems, such as the web (default true). */
+    openWorld?: boolean;
 }
 /**
  * Marks a tool the test cloud plays in place of a built-in (get_user_profile): it is offered only
@@ -38,6 +102,11 @@ export interface Tool<Input = any> {
  */
 export declare const STAND_IN: unique symbol;
 export declare function tool<Input>(definition: Tool<Input>): Tool<Input>;
+/**
+ * Marks a tool whose input schema is given as JSON Schema (a tool another MCP server defines): the
+ * model is shown that schema exactly, not one rebuilt from the zod that validates it.
+ */
+export declare const INPUT_SCHEMA: unique symbol;
 export declare function toSpec(t: Tool): ToolSpec;
 /** A tool's output as the model reads it. */
 export declare function render(output: unknown): string;

package/dist/src/tools.js

@@ -1,6 +1,16 @@
 // Tools are plain functions with a zod input. The runtime decides at call time whether one runs
 // in the reply or carries on in the background; tool authors mark nothing.
 import { z } from "zod";
+/** Bind backend access without putting secrets on an enumerable context or in any event. */
+export function toolContext(context, provider) {
+    const identity = Object.freeze({ ...context });
+    if (provider)
+        Object.defineProperty(context, "credentials", {
+            value: Object.freeze({ get: (name) => Promise.resolve().then(() => provider(name, identity)) }),
+            enumerable: false,
+        });
+    return context;
+}
 /**
  * Marks a tool the test cloud plays in place of a built-in (get_user_profile): it is offered only
  * to an agent that has that built-in, and then instead of it, so a test never runs the real one.
@@ -9,8 +19,14 @@ export const STAND_IN = Symbol("chinwag.standIn");
 export function tool(definition) {
     return definition;
 }
+/**
+ * Marks a tool whose input schema is given as JSON Schema (a tool another MCP server defines): the
+ * model is shown that schema exactly, not one rebuilt from the zod that validates it.
+ */
+export const INPUT_SCHEMA = Symbol("chinwag.inputSchema");
 export function toSpec(t) {
-    const { $schema: _ignored, ...parameters } = z.toJSONSchema(t.input);
+    const given = t[INPUT_SCHEMA];
+    const { $schema: _ignored, ...parameters } = given ?? z.toJSONSchema(t.input);
     return { name: t.name, description: t.description, parameters };
 }
 /** A tool's output as the model reads it. */

package/dist/src/traces.js

@@ -41,10 +41,14 @@ export function tracesFromEnv(env = process.env) {
     return { key, url: setting("TRACES_URL", env)?.trim() || OBSERVE_URL, content: setting("TRACES_CONTENT", env) === "1" };
 }
 /** The endpoint's channel names: Flow Framework's custom UIs are web or app chats. */
-const CHANNEL_KIND = { sms: "sms", whatsapp: "whatsapp", custom: "web" };
+const CHANNEL_KIND = { sms: "sms", mms: "mms", whatsapp: "whatsapp", telegram: "telegram", imessage: "imessage", web: "web", voice: "voice", other: "other", custom: "web", cli: "cli" };
 let warnedMetadataOnly = false;
 export function traces(options, agent) {
-    const base = (options.url ?? "").replace(/\/+$/, "");
+    const url = options.url ?? "";
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 47)
+        end--;
+    const base = url.slice(0, end);
     if (!options.key)
         throw new Error("flow: traces need a key");
     if (!base)
@@ -58,6 +62,7 @@ export function traces(options, agent) {
         console.warn("flow: traces are metadata only. Set FLOW_FRAMEWORK_TRACES_CONTENT=1 to send what was written.");
     }
     const open = new Map();
+    const calls = new Map();
     /** Messages and background results that came while no turn was open: they join the next one. */
     const waiting = new Map();
     const queue = [];
@@ -168,6 +173,29 @@ export function traces(options, agent) {
         }
     }
     function handle(e) {
+        // An MCP/CLI call has no conversation or model turn. Reuse the same bounded exporter.
+        if (["mcp", "mcp-plugin", "cli"].includes(String(e.surface))) {
+            const call = String(e.callId);
+            if (e.type === "tool.start") {
+                calls.set(call, { at: e.at, ...(content ? { input: e.input } : {}) });
+                if (calls.size > MAX_QUEUED)
+                    calls.delete(calls.keys().next().value);
+            }
+            else if (e.type === "tool.end") {
+                const started = calls.get(call);
+                calls.delete(call);
+                const attributes = toolAttributes(e, started?.input);
+                attributes.push(attr("chinwag.surface", String(e.surface)), attr("openinference.span.kind", "TOOL"));
+                for (const [field, key] of Object.entries({ client: "chinwag.mcp.client", clientVersion: "chinwag.mcp.client_version", session: "chinwag.mcp.session", person: "chinwag.person", command: "chinwag.command" })) {
+                    if (typeof e[field] === "string")
+                        attributes.push(attr(key, e[field]));
+                }
+                if (e.ok === false)
+                    attributes.push(attr("error", typeof e.error === "string" ? clip(e.error) : "Tool failed"));
+                enqueue([span(hex(16), `mcp.call ${e.tool}`, started?.at ?? e.at - Number(e.ms ?? 0), e.at, attributes, undefined, e.ok === false)]);
+            }
+            return;
+        }
         const id = e.conversationId;
         const turn = open.get(id);
         switch (e.type) {
@@ -241,8 +269,8 @@ export function traces(options, agent) {
         const attributes = [attr("gen_ai.operation.name", "execute_tool"), attr("gen_ai.tool.name", String(e.tool)), attr("gen_ai.tool.call.id", String(e.callId))];
         if (content && input !== undefined)
             attributes.push(attr("gen_ai.tool.call.arguments", clip(JSON.stringify(input))));
-        if (content && typeof e.output === "string")
-            attributes.push(attr("gen_ai.tool.call.result", clip(e.output)));
+        if (content && e.output !== undefined)
+            attributes.push(attr("gen_ai.tool.call.result", clip(typeof e.output === "string" ? e.output : JSON.stringify(e.output))));
         return attributes;
     }
     return {

package/dist/src/types.d.ts

@@ -85,6 +85,8 @@ export interface ListRow {
 export type Outbound = {
     type: "message";
     text: string;
+    /** A framework-generated login challenge; its link opens real authentication in simulators. */
+    authentication?: boolean;
     /** The person's message this one quotes (channels with replies). */
     replyTo?: string;
     /** Reply buttons; a tap comes back as the person's message. */
@@ -105,6 +107,8 @@ export type Outbound = {
     };
     /** The channel's own params (see Channel.params), as the agent filled them in. */
     fields?: Record<string, unknown>;
+    /** The same in every process for one send the business starts (a nudge, a scheduled text), for providers that take one. */
+    idempotencyKey?: string;
 }
 /** The agent has picked these messages up (WhatsApp's blue ticks). */
  | {
@@ -120,6 +124,7 @@ export type Outbound = {
 /** A template the owner set up with the channel (WhatsApp), sent as is, even outside its window. */
  | ({
     type: "template";
+    idempotencyKey?: string;
 } & Template)
 /** A short line of what the agent is doing, shown in the loading indicator; null clears it. */
  | {

package/dist/testing/src/account.d.ts

@@ -1,4 +1,4 @@
 export declare const ACCOUNT_COMMANDS: Set<string>;
-export declare const ACCOUNT_LINES = "  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]\n                            Sign in to flow.engineer: opens the browser, prints the link and code,\n                            and waits up to --timeout (default 120) for approval; --wait goes on\n                            waiting for the same code, --no-wait returns at once\n  flow logout [--json]      End this machine's sign-in and delete its token\n  flow whoami [--json]      Show the account you are signed in as\n  flow setup [--replace] [--ci] [--json]\n                            Write this agent's keys (test cloud, traces, Flow Messaging) and each\n                            open channel's sender into ./.env (in an agent's folder: package.json)\n  flow link [--channel telegram|whatsapp|imessage] [--timeout <s>] [--no-browser] [--json]\n                            Print the link that opens a chat with this agent from a phone; signs in\n                            and runs setup first when this folder is not set up yet";
+export declare const ACCOUNT_LINES = "  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]\n                            Sign in to flow.engineer: opens the browser, prints the link and code,\n                            and waits up to --timeout (default 120) for approval; --wait goes on\n                            waiting for the same code, --no-wait returns at once\n  flow logout [--json]      End this machine's sign-in and delete its token\n  flow whoami [--json]      Show the account you are signed in as\n  flow setup [--replace] [--rotate <keys> [--now]] [--ci] [--json]\n                            Write this agent's keys (its Flow key FLOW_KEY, which also pays for the\n                            model on the account's trial credit when there is no provider key, test\n                            cloud, traces, Flow Messaging) and each open channel's sender into\n                            ./.env (in an agent's folder: package.json); --rotate key,cloud,traces,\n                            messaging or all makes those keys again (the old FLOW_KEY works 24 h\n                            more; --now ends it at once)\n  flow link [--channel telegram|whatsapp|imessage] [--timeout <s>] [--no-browser] [--json]\n                            Print the link that opens a chat with this agent from a phone; signs in\n                            and runs setup first when this folder is not set up yet\n  flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their\n                            values) with the trial credit left, the\n                            sign-in, each channel's sender in .env, and, signed in, which channels\n                            are open now and their free-trial counts";
 /** Runs one account command; resolves to the exit status. */
 export declare function accountCli(command: string, args: string[]): Promise<number>;