@flow-engineer/flow 0.0.0-stage → 0.2.0

package/dist/src/talk.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import type { ChannelInfo, ToolSpec } from "./types.ts";
+export declare const REACT = "react";
+export declare const UPDATE = "share_updates";
+export declare const reactInput: z.ZodObject<{
+    message_id: z.ZodString;
+    emoji: z.ZodString;
+}, z.core.$strip>;
+export declare const updateInput: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;
+/** A channel the person has written on, by the name the agent's channels use. */
+export interface ChannelView {
+    name: string;
+    info: ChannelInfo;
+    /** The channel's own extra fields on its send tool. */
+    params?: Record<string, z.ZodType>;
+    /** The agent author's own guidance for this channel. */
+    instructions?: string;
+}
+/** The send tool for one channel. */
+export declare function sendToolName(channel: string): string;
+/** A send tool's input on this channel: only the features it has, with its limits, and its own params. */
+export declare function sendInput(channel: ChannelInfo, several?: boolean, params?: Record<string, z.ZodType>): z.ZodObject<{
+    [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}, z.core.$strip>;
+export type SendInput = {
+    text: string;
+    reply_to?: string;
+    buttons?: string[];
+    list?: {
+        button: string;
+        rows: Array<{
+            id: string;
+            title: string;
+            description?: string;
+        }>;
+    };
+    link?: {
+        label: string;
+        url: string;
+    };
+    image?: {
+        url: string;
+    };
+    confirm?: boolean;
+};
+/** Why a send that fits its schema still cannot go out as written (WhatsApp's rules), or null. */
+export declare function sendRefusal(channel: ChannelInfo, input: SendInput): string | null;
+export interface TalkSettings {
+    /** Live status on channels that can show it (web and app UIs). Default on. */
+    shareUpdates: boolean;
+    /** The owner's own guidance for when and what to share; replaces Flow Framework's default line. */
+    shareUpdatesInstructions?: string;
+}
+export declare function talkSpecs(channels: ChannelView[], settings: TalkSettings): ToolSpec[];
+export declare function talkInstructions(channels: ChannelView[], settings: TalkSettings): string;

package/dist/src/talk.js

@@ -0,0 +1,166 @@
+// How the agent talks to the person. Everything the person sees goes through these tools; text the
+// model writes outside them is never shown. They are run by the conversation itself, not as
+// ordinary tools: a sent message gets an empty result, and a failed one comes back to the agent as
+// a message of its own. What a send tool can carry (replies, buttons, lists, length) follows the
+// channel, so the agent is only offered what the platform really has.
+//
+// Each channel the person has written on gets its own send tool, named for it (send_sms,
+// send_whatsapp), shaped for that channel, so the agent always knows where it is talking and can
+// never write somewhere they have not. A second channel adds a tool; the first one's never changes.
+import { z } from "zod";
+import { toSpec, tool } from "./tools.js";
+export const REACT = "react";
+export const UPDATE = "share_updates";
+export const reactInput = z.object({
+    message_id: z.string().describe("The id of the person's message, such as m3"),
+    emoji: z.string().min(1).max(16),
+});
+export const updateInput = z.object({ text: z.string().min(1).max(120) });
+/** The send tool for one channel. */
+export function sendToolName(channel) {
+    return `send_${channel.toLowerCase().replace(/[^a-z0-9]+/g, "_")}`;
+}
+const https = z.url({ protocol: /^https$/ });
+/** A send tool's input on this channel: only the features it has, with its limits, and its own params. */
+export function sendInput(channel, several = false, params = {}) {
+    const shape = {
+        text: z.string().min(1).max(channel.maxLength ?? 4_000),
+    };
+    if (several) {
+        shape.confirm = z.boolean().optional().describe("Only when Chinwag asks: you are sure about this channel though they have not written on it lately");
+    }
+    if (channel.replies) {
+        shape.reply_to = z.string().optional().describe("Quote one of the person's messages, by id (such as m3)");
+    }
+    if (channel.buttons) {
+        shape.buttons = z
+            .array(z.string().min(1).max(channel.buttons.labelMax))
+            .max(channel.buttons.max)
+            .optional()
+            .describe(`Up to ${channel.buttons.max} reply buttons, ${channel.buttons.labelMax} characters each; a tap comes back as their message`);
+    }
+    if (channel.lists) {
+        shape.list = z
+            .object({
+            button: z.string().min(1).max(channel.lists.buttonMax).describe("The label that opens the list"),
+            rows: z
+                .array(z.object({
+                id: z.string().min(1).max(64),
+                title: z.string().min(1).max(channel.lists.titleMax),
+                description: z.string().max(72).optional(),
+            }))
+                .min(1)
+                .max(channel.lists.maxRows),
+        })
+            .optional()
+            .describe(`A list of up to ${channel.lists.maxRows} options the person picks one of; their pick comes back as their message`);
+    }
+    // Every channel takes a link: where there is no link button, Flow Framework puts its URL after the text.
+    shape.link = z
+        .object({ label: z.string().min(1).max(channel.linkButton?.labelMax ?? 20), url: https })
+        .optional()
+        .describe(channel.linkButton ? "A button that opens a page, by a URL you were given; not with buttons or a list" : "A page, by a URL you were given: it goes on a line after your text; not with buttons or a list");
+    if (channel.images) {
+        shape.image = z
+            .object({ url: https })
+            .optional()
+            .describe(`A photo, by a URL you were given; your text is its caption, up to ${channel.images.captionMax} characters${channel.lists ? "; not with a list" : ""}`);
+    }
+    for (const [name, schema] of Object.entries(params))
+        shape[name] = schema.optional();
+    return z.object(shape);
+}
+/** Why a send that fits its schema still cannot go out as written (WhatsApp's rules), or null. */
+export function sendRefusal(channel, input) {
+    if (input.link && (input.buttons?.length || input.list))
+        return "Not sent: a message with a link cannot also have buttons or a list. Send them in separate messages.";
+    if (input.image && input.list)
+        return "Not sent: a message with an image cannot also have a list. Send them in separate messages.";
+    if (input.image && channel.images && input.text.length > channel.images.captionMax) {
+        return `Not sent: with an image, your text is its caption, at most ${channel.images.captionMax} characters. Shorten it, or send the rest in another message.`;
+    }
+    const max = channel.maxLength ?? 4_000;
+    if (input.link && !channel.linkButton && input.text.length + 1 + input.link.url.length > max) {
+        return `Not sent: the link's URL goes after your text here, and together they are over ${max} characters. Shorten the text.`;
+    }
+    return null;
+}
+const reactTool = tool({
+    name: REACT,
+    description: "React to one of the person's messages with an emoji.",
+    input: reactInput,
+    run: () => "",
+});
+const updateTool = tool({
+    name: UPDATE,
+    description: "Show the person a short line of what you are doing, in their loading indicator. Each update replaces the last.",
+    input: updateInput,
+    run: () => "",
+});
+export function talkSpecs(channels, settings) {
+    const several = channels.length > 1;
+    const specs = channels.map((c) => toSpec(tool({
+        name: sendToolName(c.name),
+        description: `Send a message to the person on ${c.name}. Call it several times to send several messages; they go out in the order you call them.`,
+        input: sendInput(c.info, several, c.params),
+        run: () => "",
+    })));
+    if (channels.some((c) => c.info.reactions))
+        specs.push(toSpec(reactTool));
+    if (channels.some((c) => c.info.status) && settings.shareUpdates)
+        specs.push(toSpec(updateTool));
+    return specs;
+}
+const FORMATTING = {
+    plain: "Write plain text, not Markdown or other formatting: this channel does not support it.",
+    whatsapp: "Format with WhatsApp's marks if useful: *bold*, _italic_, ~strikethrough~; no Markdown headings or [links](url).",
+    markdown: "Markdown works here.",
+};
+export function talkInstructions(channels, settings) {
+    if (channels.length > 1)
+        return severalChannels(channels, settings);
+    const channel = channels[0].info;
+    const lines = [
+        "## Talking to the person",
+        `- IMPORTANT: They see only what you send with ${sendToolName(channels[0].name)}` +
+            (channel.reactions ? ", react" : "") +
+            (channel.status && settings.shareUpdates ? " or share_updates" : "") +
+            `. Anything else you write (your own text, a tool's result) never reaches them: to tell them anything, call ${sendToolName(channels[0].name)}.`,
+        "- Lines starting [Chinwag] are INTERNAL MESSAGES from the system running you, not from them: they never see them. Never mention them to the person, nor any text of yours that did not reach them.",
+        "- After they write, the first thing you do must reach them: your answer, or, if you need tools first, an acknowledgement in the same response as those tool calls" +
+            (channel.reactions ? " (react to their message, or a short line)." : ": a short line."),
+        "- Call every tool you can in one response; wait for a result only when another call needs it.",
+        "- IMPORTANT: A message you send with tool calls reaches them before those tools run. So say what you are about to do (\"I'm booking that now\"), never that it is done (\"I've booked it\", \"done\"): the outcome comes once, after the result arrives. Never send a placeholder.",
+        "- Their messages start with an id in brackets, like [m3].",
+        `- ${FORMATTING[channel.formatting ?? "plain"]}`,
+    ];
+    if (channel.buttons || channel.lists) {
+        lines.push("- When they choose between a few options, offer them as " + (channel.buttons ? "buttons" : "a list") + (channel.buttons && channel.lists ? " (or a list when there are more than " + channel.buttons.max + ")" : "") + " so they can tap.");
+    }
+    if (channel.status && settings.shareUpdates) {
+        lines.push(`- ${settings.shareUpdatesInstructions ?? "While several tools run one after another, keep them posted with share_updates: a few words on what you are doing now."}`);
+    }
+    if (channels[0].instructions)
+        lines.push(`- ${channels[0].instructions}`);
+    return lines.join("\n");
+}
+function severalChannels(channels, settings) {
+    const names = channels.map((c) => c.name);
+    const tools = channels.map((c) => sendToolName(c.name));
+    const reactions = channels.some((c) => c.info.reactions);
+    const lines = [
+        "## Talking to the person",
+        `- They write to you on more than one channel: ${names.join(", ")}. One conversation covers all of them. Their messages start with the channel and an id, like [${names[0]} · m3].`,
+        `- IMPORTANT: They see only what you send with ${tools.join(", ")}${reactions ? ", react" : ""}. Anything else you write (your own text, a tool's result) never reaches them: to tell them anything, call a send tool.`,
+        "- Lines starting [Chinwag] are INTERNAL MESSAGES from the system running you, not from them: they never see them. Never mention them to the person, nor any text of yours that did not reach them.",
+        "- Answer each message on the channel it came on, with that channel's send tool. Messages on different channels can be about different things: answer each one.",
+        "- After they write, the first thing you do must reach them on every channel they are waiting on: your answer, or, if you need tools first, an acknowledgement there in the same response as those tool calls.",
+        "- Call every tool you can in one response; wait for a result only when another call needs it.",
+        "- IMPORTANT: A message you send with tool calls reaches them before those tools run. So say what you are about to do (\"I'm booking that now\"), never that it is done (\"I've booked it\", \"done\"): the outcome comes once, after the result arrives. Never send a placeholder.",
+        ...channels.map((c) => `- On ${c.name}: ${FORMATTING[c.info.formatting ?? "plain"]}${c.info.buttons ? ` Up to ${c.info.buttons.max} buttons.` : ""}${c.instructions ? ` ${c.instructions}` : ""}`),
+    ];
+    if (channels.some((c) => c.info.status) && settings.shareUpdates) {
+        lines.push(`- ${settings.shareUpdatesInstructions ?? "While several tools run one after another, keep them posted with share_updates: a few words on what you are doing now."}`);
+    }
+    return lines.join("\n");
+}

package/dist/src/time.d.ts

@@ -0,0 +1,71 @@
+export type Rule = {
+    repeat: "once";
+    at: number;
+} | {
+    repeat: "daily";
+    time: string;
+}
+/** days: 0 is Sunday. */
+ | {
+    repeat: "weekly";
+    time: string;
+    days: number[];
+} | {
+    repeat: "monthly";
+    time: string;
+    day: number | "last";
+}
+/** Every `every` hours from `from` to `to` (local, inclusive), on `days` if given. */
+ | {
+    repeat: "hourly";
+    every: number;
+    from?: string;
+    to?: string;
+    days?: number[];
+};
+export interface LocalParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    /** 0 is Sunday. */
+    weekday: number;
+}
+export declare function validZone(zone: string): boolean;
+/** UTC given as a zone says nothing about where the person is, so it is never taken as theirs. */
+export declare function isBareUtc(zone: string): boolean;
+export declare function parts(zone: string, ms: number): LocalParts;
+/** The UTC instant of a local wall-clock time in `zone`. */
+export declare function localToUtc(zone: string, year: number, month: number, day: number, hour: number, minute: number): number;
+/** "HH:MM" as hours and minutes, or null when it is not a time. */
+export declare function clock(time: string): {
+    hour: number;
+    minute: number;
+} | null;
+/** "YYYY-MM-DD" as numbers, or null. */
+export declare function date(text: string): {
+    year: number;
+    month: number;
+    day: number;
+} | null;
+export declare function localDate(zone: string, ms: number): string;
+/** The first instant after the local day `text` ends. */
+export declare function endOfLocalDay(zone: string, text: string): number | null;
+/** The next time `rule` comes due strictly after `after`, or null when it never does again. */
+export declare function nextRun(rule: Rule, zone: string, after: number): number | null;
+/** "Kolkata time", "New York time"; "UTC" for UTC itself. */
+export declare function zoneLabel(zone: string): string;
+/** "Mon 12 Oct 2026 19:00 (New York time)". */
+export declare function formatLocal(zone: string, ms: number): string;
+/** What a rule does, in words, with its zone named. */
+export declare function describe(rule: Rule, zone: string): string;
+export declare const DAY_INDEX: Record<string, number>;
+/**
+ * When quiet hours `from`–`to` ("22:00"–"07:00", in `zone`, may wrap midnight) end, if `now` is
+ * inside them; null when it is not, or when from equals to.
+ */
+export declare function quietUntil(now: number, zone: string, hours: {
+    from: string;
+    to: string;
+}): number | null;

package/dist/src/time.js

@@ -0,0 +1,170 @@
+// Local time for scheduled messages, with the platform's own time zone data (Intl), no library.
+// A person is only ever told local time, with the zone named ("07:00 (Kolkata time)"), never UTC.
+// Times are wall-clock times in the zone, so 07:00 stays 07:00 across daylight saving; a time the
+// clocks skip runs the same distance after the jump (02:30 becomes 03:30), and a time that happens
+// twice runs the first time.
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const DAY_MS = 86_400_000;
+const formats = new Map();
+export function validZone(zone) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** UTC given as a zone says nothing about where the person is, so it is never taken as theirs. */
+export function isBareUtc(zone) {
+    return /^(etc\/)?(utc|gmt|uct|zulu|universal|greenwich)([+-]?0)?$/i.test(zone.trim());
+}
+export function parts(zone, ms) {
+    let format = formats.get(zone);
+    if (!format) {
+        format = new Intl.DateTimeFormat("en-US", { timeZone: zone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", weekday: "short" });
+        formats.set(zone, format);
+    }
+    const p = Object.fromEntries(format.formatToParts(ms).map((x) => [x.type, x.value]));
+    return { year: +p.year, month: +p.month, day: +p.day, hour: +p.hour % 24, minute: +p.minute, weekday: WEEKDAYS.indexOf(p.weekday) };
+}
+/** The UTC instant of a local wall-clock time in `zone`. */
+export function localToUtc(zone, year, month, day, hour, minute) {
+    const guess = Date.UTC(year, month - 1, day, hour, minute);
+    const offset = (ms) => {
+        const p = parts(zone, ms);
+        return Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute) - Math.floor(ms / 60_000) * 60_000;
+    };
+    const candidates = [...new Set([guess - offset(guess - DAY_MS), guess - offset(guess + DAY_MS)])];
+    const matching = candidates.filter((c) => {
+        const p = parts(zone, c);
+        return p.year === year && p.month === month && p.day === day && p.hour === hour && p.minute === minute;
+    });
+    return matching.length ? Math.min(...matching) : Math.max(...candidates);
+}
+/** "HH:MM" as hours and minutes, or null when it is not a time. */
+export function clock(time) {
+    const m = /^([01]?\d|2[0-3]):([0-5]\d)$/.exec(time.trim());
+    return m ? { hour: +m[1], minute: +m[2] } : null;
+}
+/** "YYYY-MM-DD" as numbers, or null. */
+export function date(text) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text.trim());
+    if (!m)
+        return null;
+    const d = new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]));
+    return d.getUTCMonth() === +m[2] - 1 ? { year: +m[1], month: +m[2], day: +m[3] } : null;
+}
+export function localDate(zone, ms) {
+    const p = parts(zone, ms);
+    return `${p.year}-${String(p.month).padStart(2, "0")}-${String(p.day).padStart(2, "0")}`;
+}
+/** The first instant after the local day `text` ends. */
+export function endOfLocalDay(zone, text) {
+    const d = date(text);
+    if (!d)
+        return null;
+    const next = new Date(Date.UTC(d.year, d.month - 1, d.day + 1));
+    return localToUtc(zone, next.getUTCFullYear(), next.getUTCMonth() + 1, next.getUTCDate(), 0, 0);
+}
+/** The next time `rule` comes due strictly after `after`, or null when it never does again. */
+export function nextRun(rule, zone, after) {
+    if (rule.repeat === "once")
+        return rule.at > after ? rule.at : null;
+    const start = parts(zone, after);
+    for (let k = 0; k <= 400; k++) {
+        const d = new Date(Date.UTC(start.year, start.month - 1, start.day + k));
+        const year = d.getUTCFullYear();
+        const month = d.getUTCMonth() + 1;
+        const day = d.getUTCDate();
+        const weekday = d.getUTCDay();
+        for (const t of timesOn(rule, year, month, day, weekday)) {
+            const at = localToUtc(zone, year, month, day, t.hour, t.minute);
+            if (at > after)
+                return at;
+        }
+    }
+    return null;
+}
+/** The local times `rule` runs at on one day, earliest first. */
+function timesOn(rule, year, month, day, weekday) {
+    if (rule.repeat === "hourly") {
+        if (rule.days?.length && !rule.days.includes(weekday))
+            return [];
+        const from = clock(rule.from ?? "00:00");
+        const to = clock(rule.to ?? "23:59");
+        const out = [];
+        for (let minutes = from.hour * 60 + from.minute; minutes <= to.hour * 60 + to.minute; minutes += rule.every * 60) {
+            out.push({ hour: Math.floor(minutes / 60), minute: minutes % 60 });
+        }
+        return out;
+    }
+    const t = clock(rule.time);
+    if (rule.repeat === "weekly" && !rule.days.includes(weekday))
+        return [];
+    if (rule.repeat === "monthly") {
+        const last = new Date(Date.UTC(year, month, 0)).getUTCDate();
+        const target = rule.day === "last" ? last : Math.min(rule.day, last);
+        if (day !== target)
+            return [];
+    }
+    return [t];
+}
+/** "Kolkata time", "New York time"; "UTC" for UTC itself. */
+export function zoneLabel(zone) {
+    if (isBareUtc(zone))
+        return "UTC";
+    const city = zone.split("/").at(-1).replaceAll("_", " ");
+    return `${city} time`;
+}
+/** "Mon 12 Oct 2026 19:00 (New York time)". */
+export function formatLocal(zone, ms) {
+    const p = parts(zone, ms);
+    const hhmm = `${String(p.hour).padStart(2, "0")}:${String(p.minute).padStart(2, "0")}`;
+    return `${WEEKDAYS[p.weekday]} ${p.day} ${MONTHS[p.month - 1]} ${p.year} ${hhmm} (${zoneLabel(zone)})`;
+}
+/** What a rule does, in words, with its zone named. */
+export function describe(rule, zone) {
+    const label = zoneLabel(zone);
+    if (rule.repeat === "once")
+        return `once, ${formatLocal(zone, rule.at)}`;
+    if (rule.repeat === "daily")
+        return `every day at ${rule.time} (${label})`;
+    if (rule.repeat === "weekly") {
+        const days = rule.days.length === 5 && [1, 2, 3, 4, 5].every((d) => rule.days.includes(d)) ? "weekday" : list(rule.days.map((d) => DAY_NAMES[d]));
+        return `every ${days} at ${rule.time} (${label})`;
+    }
+    if (rule.repeat === "monthly")
+        return `${rule.day === "last" ? "on the last day" : `on day ${rule.day}`} of every month at ${rule.time} (${label})`;
+    const window = rule.from || rule.to ? ` from ${rule.from ?? "00:00"} to ${rule.to ?? "23:59"}` : "";
+    const days = rule.days?.length ? ` on ${list(rule.days.map((d) => DAY_NAMES[d]))}` : "";
+    return `every ${rule.every === 1 ? "hour" : `${rule.every} hours`}${window}${days} (${label})`;
+}
+function list(items) {
+    return items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
+export const DAY_INDEX = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+/**
+ * When quiet hours `from`–`to` ("22:00"–"07:00", in `zone`, may wrap midnight) end, if `now` is
+ * inside them; null when it is not, or when from equals to.
+ */
+export function quietUntil(now, zone, hours) {
+    const from = clock(hours.from);
+    const to = clock(hours.to);
+    if (!from || !to)
+        return null;
+    const p = parts(zone, now);
+    const minute = p.hour * 60 + p.minute;
+    const start = from.hour * 60 + from.minute;
+    const end = to.hour * 60 + to.minute;
+    if (start === end)
+        return null;
+    const inside = start < end ? minute >= start && minute < end : minute >= start || minute < end;
+    if (!inside)
+        return null;
+    // The end is today, or tomorrow when it wraps past midnight and we are before it.
+    const day = new Date(Date.UTC(p.year, p.month - 1, p.day + (start > end && minute >= start ? 1 : 0)));
+    return localToUtc(zone, day.getUTCFullYear(), day.getUTCMonth() + 1, day.getUTCDate(), to.hour, to.minute);
+}

package/dist/src/tools.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { ToolSpec } from "./types.ts";
+export interface ToolContext {
+    conversationId: string;
+    /**
+     * Who the person is, as Flow Framework verified it, in one of three forms: `key:<resolve's value>` when
+     * the owner's `resolve` knew them, else `phone:<E.164>` (`phone:+15551234567`) for a number a
+     * phone channel verified, else `<channel>:<address>`. It is the stable id to key a person's data
+     * by, never an id the model passed. To look them up in your own backend, use `key`.
+     */
+    person: string;
+    /** Exactly what the owner's `resolve` returned for this person (no `key:`), or null when they are known only by phone or channel and address. */
+    key: string | null;
+    /** The channel of their latest message. */
+    channel: string;
+    /** The model's id for this call, as the history keeps it. */
+    callId: string;
+    /**
+     * The same for the same tool with the same input in the same turn, also when that turn runs
+     * again after a restart (a cut-off call is not rerun, but the agent may call it again): pass it
+     * to your backend so a booking or payment happens once.
+     */
+    idempotencyKey: string;
+    /** Aborted when the conversation closes (the person was forgotten): stop and drop the work. */
+    signal: AbortSignal;
+}
+export interface Tool<Input = any> {
+    name: string;
+    description: string;
+    input: z.ZodType<Input>;
+    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;
+}
+/**
+ * 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.
+ */
+export declare const STAND_IN: unique symbol;
+export declare function tool<Input>(definition: Tool<Input>): Tool<Input>;
+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

@@ -0,0 +1,26 @@
+// 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";
+/**
+ * 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.
+ */
+export const STAND_IN = Symbol("chinwag.standIn");
+export function tool(definition) {
+    return definition;
+}
+export function toSpec(t) {
+    const { $schema: _ignored, ...parameters } = z.toJSONSchema(t.input);
+    return { name: t.name, description: t.description, parameters };
+}
+/** A tool's output as the model reads it. */
+export function render(output) {
+    if (typeof output === "string")
+        return output;
+    try {
+        return JSON.stringify(output ?? null);
+    }
+    catch {
+        return String(output);
+    }
+}

package/dist/src/traces.d.ts

@@ -0,0 +1,31 @@
+import type { EventSink } from "./events.ts";
+import { setting } from "./names.ts";
+export interface TracesOptions {
+    /** The traces endpoint's base URL; traces go to `<url>/v1/traces`. */
+    url: string;
+    /** The agent's key for the traces endpoint. */
+    key: string;
+    /** Send what was written (messages, tool inputs and results). Default false: metadata only. */
+    content?: boolean;
+    /** This agent's version, sent as `service.version`. */
+    version?: string;
+}
+/** Where traces go when a key is set and no address is, and the test cloud `flow test` uses when none is named. */
+export declare const OBSERVE_URL = "https://flow.engineer/observe";
+/** A setting from the environment: FLOW_FRAMEWORK_<name>, else CHINWAG_<name> (src/names.ts). */
+export { setting };
+/**
+ * The traces options from the environment: on when FLOW_FRAMEWORK_TRACES_KEY is set, except under
+ * `node --test` (NODE_TEST_CONTEXT), so an agent's own tests never send their turns. The address
+ * is FLOW_FRAMEWORK_TRACES_URL, else {@link OBSERVE_URL}.
+ */
+export declare function tracesFromEnv(env?: NodeJS.ProcessEnv): TracesOptions | undefined;
+export interface Traces {
+    sink: EventSink;
+    /** Resolves once every finished turn queued so far has been sent (or dropped). */
+    flush(): Promise<void>;
+}
+export declare function traces(options: TracesOptions, agent: {
+    service: string;
+    kindOf(channel: string): string | undefined;
+}): Traces;