@flow-engineer/flow 0.0.1 → 0.2.1

package/dist/src/nudges.d.ts

@@ -0,0 +1,23 @@
+import type { NoContactRow, QuietHours, StoreApi } from "./store.ts";
+import { type Tool } from "./tools.ts";
+import type { Model, ModelResponse } from "./types.ts";
+export interface NoContactScope {
+    store: StoreApi;
+    conversationId: string;
+    now(): number;
+    /** Their zone, once known: an `until` date is read in it. */
+    zone(): string | null;
+    setQuietHours(hours: QuietHours | "off" | null): Promise<void>;
+}
+export declare function noContactTools(scope: NoContactScope): Tool[];
+/** The rules as the agent reads them each turn; empty when there are none. */
+export declare function rulesSection(rules: NoContactRow[], zone: string, quiet?: QuietHours | null): string;
+/**
+ * A fixed-text message the business starts, to a person with rules: one small model call says
+ * whether a rule covers it. Rejects when the model does; the caller sends nothing then.
+ */
+export declare function coveredBy(model: Model, rules: NoContactRow[], text: string): Promise<{
+    rule: NoContactRow | null;
+    usage?: ModelResponse["usage"];
+    model?: string;
+}>;

package/dist/src/nudges.js

@@ -0,0 +1,117 @@
+// Nudges are messages the business starts: sent as written (text), written by the agent (prompt),
+// or a template the owner already set up with the channel. What a person asked not to be messaged
+// about is the agent's judgement, kept as rules it adds and removes: a message the business starts
+// that the rules cover is not sent. The rules cover only what the business starts, never what the
+// person asks for themselves. A channel's STOP keyword is different: a hard rule, written without
+// the model, that stops everything the business starts until they text START (channels.ts).
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { clock, endOfLocalDay, formatLocal } from "./time.js";
+import { tool, toSpec } from "./tools.js";
+export function noContactTools(scope) {
+    return [
+        tool({
+            name: "add_no_contact",
+            description: "When they say they do not want to be messaged about something (or at all, or for a while), keep it as a rule, in their words: \"no promotions\", \"nothing before 9am\". Messages the business starts that the rule covers will not be sent. Also cancel their scheduled messages it covers. Not for things they ask for themselves.",
+            input: z.object({
+                rule: z.string().min(1).max(200),
+                until: z.string().optional().describe("YYYY-MM-DD, the last day it applies, when they gave one (\"not this week\")"),
+            }),
+            run: async ({ rule, until }) => {
+                // Their zone unknown, the day ends where it ends last (UTC-12): the rule never lifts early.
+                const ends = until ? endOfLocalDay(scope.zone() ?? "Etc/GMT+12", until) : null;
+                if (until && !ends)
+                    return { error: "until must be YYYY-MM-DD." };
+                const id = `nc_${randomUUID().slice(0, 6)}`;
+                await scope.store.addNoContact(scope.conversationId, id, rule, ends);
+                return { added: { id, rule, until: until ?? null } };
+            },
+        }),
+        tool({
+            name: "pause_messages",
+            description: "When they want nothing at all from the business for a while (\"no messages this week\", \"pause until Monday\"): nothing it starts goes until that day ends. Remove it with remove_no_contact.",
+            input: z.object({ until: z.string().describe("YYYY-MM-DD, the last day of the pause") }),
+            run: async ({ until }) => {
+                const ends = endOfLocalDay(scope.zone() ?? "Etc/GMT+12", until);
+                if (!ends)
+                    return { error: "until must be YYYY-MM-DD." };
+                if (ends <= scope.now())
+                    return { error: "That day is already over." };
+                const id = `nc_${randomUUID().slice(0, 6)}`;
+                await scope.store.addNoContact(scope.conversationId, id, `pause: nothing the business starts until ${until} is over`, ends, "pause");
+                return { paused: { id, until } };
+            },
+        }),
+        tool({
+            name: "set_quiet_hours",
+            description: "When they say when not to be messaged by the clock (\"not after 9pm\", \"nothing before 8\"): their quiet hours, in their own time, when what the business starts waits. off: none at all; default: back to the usual ones.",
+            input: z.object({
+                from: z.string().optional().describe("HH:MM their time, when quiet starts"),
+                to: z.string().optional().describe("HH:MM their time, when it ends"),
+                set: z.enum(["hours", "off", "default"]).describe("hours: from and to; off: no quiet hours; default: the usual ones"),
+            }),
+            run: async ({ from, to, set }) => {
+                if (set !== "hours") {
+                    await scope.setQuietHours(set === "off" ? "off" : null);
+                    return { quiet_hours: set };
+                }
+                if (!from || !to || !clock(from) || !clock(to))
+                    return { error: "from and to are HH:MM, such as 21:00 and 08:00." };
+                await scope.setQuietHours({ from, to });
+                return { quiet_hours: { from, to }, ...(scope.zone() ? {} : { note: "Their time zone is not known, so these apply once it is: ask where they are." }) };
+            },
+        }),
+        tool({
+            name: "remove_no_contact",
+            description: "Remove one of their no-contact rules, by id, when they want those messages again.",
+            input: z.object({ id: z.string() }),
+            run: async ({ id }) => {
+                const rule = (await scope.store.noContact(scope.conversationId, scope.now())).find((r) => r.id === id);
+                if (rule?.hard)
+                    return { error: "That is their STOP: it ends only when they text START." };
+                return { removed: await scope.store.removeNoContact(scope.conversationId, id) };
+            },
+        }),
+    ];
+}
+/** The rules as the agent reads them each turn; empty when there are none. */
+export function rulesSection(rules, zone, quiet = null) {
+    if (!rules.length && !quiet)
+        return "";
+    return [
+        "## When and what not to message them",
+        "Messages the business starts (nudges, its scheduled messages) that these cover are not sent. Things they ask for themselves are fine.",
+        ...(quiet ? [`- Quiet hours: ${quiet.from} to ${quiet.to}, their time: what the business starts waits until they end (set_quiet_hours changes them).`] : []),
+        ...rules.map((r) => `- [${r.id}] ${r.rule}${r.until ? ` (until ${formatLocal(zone, r.until - 1)})` : ""}`),
+    ].join("\n");
+}
+const decision = tool({
+    name: "decide",
+    description: "Say whether the message may be sent.",
+    input: z.object({ send: z.boolean(), rule: z.string().optional().describe("The id of the rule that covers it, when send is false") }),
+    run: () => "",
+});
+/**
+ * A fixed-text message the business starts, to a person with rules: one small model call says
+ * whether a rule covers it. Rejects when the model does; the caller sends nothing then.
+ */
+export async function coveredBy(model, rules, text) {
+    const response = await model.complete({
+        system: "A business wants to send this message to a person. The person asked not to be messaged about some things. Decide whether any of their rules covers this message; call decide once.",
+        messages: [{ role: "user", content: `Rules:\n${rules.map((r) => `- [${r.id}] ${r.rule}`).join("\n")}\n\nMessage:\n${text}` }],
+        tools: [toSpec(decision)],
+        signal: new AbortController().signal,
+    });
+    const call = response.toolCalls.find((c) => c.name === "decide");
+    let parsed = {};
+    try {
+        parsed = JSON.parse(call?.arguments ?? "{}");
+    }
+    catch {
+        // An unreadable answer sends nothing: a rule the person set is safer kept than broken.
+    }
+    const said = { usage: response.usage, model: response.model };
+    if (parsed.send === true)
+        return { rule: null, ...said };
+    return { rule: rules.find((r) => r.id === parsed.rule) ?? rules[0], ...said };
+}

package/dist/src/postgres.d.ts

@@ -0,0 +1,20 @@
+import type { Database, Row } from "./db.ts";
+interface Queryable {
+    query(text: string, params?: unknown[]): Promise<{
+        rows: Row[];
+        rowCount: number | null;
+    }>;
+}
+/** A connection pool: queries on any connection, and one connection checked out for a transaction. */
+export interface PostgresPool extends Queryable {
+    connect(): Promise<Queryable & {
+        release(error?: Error | boolean): void;
+    }>;
+}
+/**
+ * Postgres behind Flow Framework's Database. SQL written with `?` reaches Postgres as `$1`, `$2`, ...; a
+ * transaction runs BEGIN ... COMMIT on one connection taken from the pool for it, and a connection
+ * whose ROLLBACK failed is given back broken, so the pool closes it instead of reusing it.
+ */
+export declare function postgres(pool: PostgresPool): Database;
+export {};

package/dist/src/postgres.js

@@ -0,0 +1,62 @@
+// Flow Framework's state in Postgres, over a connection pool the app already has (node-postgres's Pool, or
+// anything shaped like it). Flow Framework takes no Postgres dependency: the app brings the client.
+//
+//   import pg from "pg";
+//   const database = postgres(new pg.Pool({ connectionString: process.env.DATABASE_URL }));
+/**
+ * Postgres behind Flow Framework's Database. SQL written with `?` reaches Postgres as `$1`, `$2`, ...; a
+ * transaction runs BEGIN ... COMMIT on one connection taken from the pool for it, and a connection
+ * whose ROLLBACK failed is given back broken, so the pool closes it instead of reusing it.
+ */
+export function postgres(pool) {
+    const on = (client) => ({
+        durable: true,
+        dialect: "postgres",
+        query: async (sql, params = []) => (await client.query(numbered(sql), params)).rows,
+        run: async (sql, params = []) => (await client.query(numbered(sql), params)).rowCount ?? 0,
+    });
+    return {
+        ...on(pool),
+        async transaction(work) {
+            const client = await pool.connect();
+            try {
+                await client.query("BEGIN");
+                const result = await work(on(client));
+                await client.query("COMMIT");
+                client.release();
+                return result;
+            }
+            catch (error) {
+                try {
+                    await client.query("ROLLBACK");
+                    client.release();
+                }
+                catch (rollback) {
+                    client.release(rollback);
+                }
+                throw error;
+            }
+        },
+    };
+}
+/** `?` placeholders as Postgres's `$n`, leaving any inside quoted strings or names alone. */
+function numbered(sql) {
+    let n = 0;
+    let quote = null;
+    let out = "";
+    for (const ch of sql) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+        }
+        else if (ch === "?") {
+            out += `$${++n}`;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}

package/dist/src/schedules.d.ts

@@ -0,0 +1,60 @@
+import type { NewSchedule, ScheduleRow, StoreApi } from "./store.ts";
+import { type Tool } from "./tools.ts";
+export declare const LIMITS: {
+    /** Active schedules one person may have. */
+    perPerson: number;
+    /** The same message to the same person at least this far apart. */
+    sameMessageGapMs: number;
+    /** A run found later than this after its time is missed, not sent late. */
+    lateMs: number;
+    maxAheadMs: number;
+};
+/** What the schedule tools need from the conversation they run in. */
+export interface ScheduleScope {
+    store: StoreApi;
+    conversationId: string;
+    /** The channel of the person's latest message, where a schedule's messages will go. */
+    channel(): string;
+    now(): number;
+    /** The person's zone, once known. */
+    personZone(): string | null;
+    setPersonZone(zone: string): Promise<void>;
+    /** The agent's own zone (the business's), if set: only for "in N minutes", which needs no one's clock. */
+    agentZone?: string;
+}
+export declare function scheduleTools(scope: ScheduleScope): Tool[];
+export declare function summary(s: ScheduleRow): {
+    id: string;
+    message: string;
+    mode: "check" | "message";
+    summary: string;
+    next_run: string | null;
+};
+/** A scheduled message from the business (a nudge with a time): fixed text, or an instruction. */
+export declare function businessSchedule(conversationId: string, channel: string, at: number, zone: string, body: {
+    text?: string;
+    prompt?: string;
+}, quiet?: boolean): NewSchedule;
+/** What one due run becomes in the conversation's inbox. */
+export interface DueRun {
+    run: string;
+    schedule: string;
+    channel: string;
+    mode: ScheduleRow["mode"];
+    fixed: boolean;
+    text: string;
+}
+/**
+ * Claims every due schedule once: a run found too late is missed (and the schedule moves past
+ * now, so nothing floods after downtime), one `blocked` names a reason is skipped, the rest are
+ * queued for their conversation. Returns the queued runs with their inbox ids.
+ */
+/**
+ * Claims the schedules due at `now`. One marked `quiet` that comes due in the person's quiet hours
+ * (`quietEnd` says when they end) waits: a once moves to their end, a repeat skips that run.
+ */
+export declare function claimDue(store: StoreApi, now: number, quietEnd: (s: ScheduleRow) => Promise<number | null>, blocked: (s: ScheduleRow) => Promise<string | null>): Promise<Array<{
+    conversationId: string;
+    inbox: number;
+    run: DueRun;
+}>>;

package/dist/src/schedules.js

@@ -0,0 +1,249 @@
+// Scheduled messages: an agent never runs timers. A
+// schedule is a row; when it comes due, a runner moves it on and writes an inbox event in one
+// transaction (so it runs once, even with several runners), and the conversation wakes like it
+// does for any message. The agent then writes the message with fresh data. Times are the
+// person's local time, never UTC (see time.ts).
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { DAY_INDEX, clock, date, describe, endOfLocalDay, formatLocal, isBareUtc, localDate, localToUtc, nextRun, parts, validZone } from "./time.js";
+import { tool } from "./tools.js";
+export const LIMITS = {
+    /** Active schedules one person may have. */
+    perPerson: 10,
+    /** The same message to the same person at least this far apart. */
+    sameMessageGapMs: 60 * 60_000,
+    /** A run found later than this after its time is missed, not sent late. */
+    lateMs: 30 * 60_000,
+    maxAheadMs: 366 * 86_400_000,
+};
+const scheduleInput = z.object({
+    message: z.string().min(1).max(500).describe("What to do at that time, written for yourself (\"send today's specials\"), not the finished text"),
+    repeat: z.enum(["once", "daily", "weekly", "monthly", "hourly"]),
+    time: z.string().optional().describe("HH:MM in their local time"),
+    date: z.string().optional().describe("once: YYYY-MM-DD; leave it out for the next time the clock shows `time`"),
+    in_minutes: z.number().int().min(1).max(525_600).optional().describe("once: this many minutes from now, instead of time and date"),
+    days: z.array(z.enum(["mon", "tue", "wed", "thu", "fri", "sat", "sun"])).optional().describe("weekly, or hourly on some days only"),
+    day_of_month: z.union([z.number().int().min(1).max(31), z.literal("last")]).optional().describe("monthly: 1 to 31 (a shorter month uses its last day), or \"last\""),
+    every_hours: z.number().int().min(1).max(23).optional().describe("hourly: every this many hours"),
+    from: z.string().optional().describe("hourly: HH:MM, the first run of the day"),
+    to: z.string().optional().describe("hourly: HH:MM, the last run of the day"),
+    until: z.string().optional().describe("Repeats: YYYY-MM-DD, the last day it may run"),
+    times: z.number().int().min(1).max(1000).optional().describe("Repeats: how many runs in all"),
+    timezone: z.string().optional().describe("An IANA zone, only when they named a place; leave it out otherwise"),
+    respect_quiet_hours: z.boolean().optional().describe("true for checks and updates that can wait for the morning (\"check for new listings and let me know\"); leave it out when they asked for that time, or for every hour"),
+    mode: z.enum(["message", "check"]).optional().describe("check: at that time, look, and message them only if there is something to tell"),
+});
+export function scheduleTools(scope) {
+    return [
+        tool({
+            name: "schedule_message",
+            description: "Message this person later, once or repeatedly, when they ask for a reminder or a regular message. Confirm vague times first (\"end of the month\" is the last day). Tell them plainly what you scheduled, with its time as the result gives it.",
+            input: scheduleInput,
+            run: (input) => create(scope, input),
+        }),
+        tool({
+            name: "list_scheduled",
+            description: "This person's scheduled messages that are still active.",
+            input: z.object({}),
+            run: async () => ({ scheduled: (await scope.store.schedules(scope.conversationId)).map(summary) }),
+        }),
+        tool({
+            name: "cancel_scheduled",
+            description: "Cancel one of this person's scheduled messages, by its id from list_scheduled.",
+            input: z.object({ id: z.string() }),
+            run: async ({ id }) => ({ cancelled: await scope.store.cancelSchedule(scope.conversationId, id) }),
+        }),
+    ];
+}
+export function summary(s) {
+    const ends = [s.endsOn ? `until ${s.endsOn}` : "", s.maxRuns ? `${s.maxRuns} times in all` : ""].filter(Boolean).join(", ");
+    return {
+        id: s.id,
+        message: s.instruction,
+        mode: s.mode,
+        summary: describe(s.rule, s.timeZone) + (ends ? `, ${ends}` : ""),
+        next_run: s.nextRunAt ? formatLocal(s.timeZone, s.nextRunAt) : null,
+    };
+}
+/**
+ * The zone a schedule uses: the one named (never a bare UTC), else the person's. Their zone is never
+ * guessed from the business's: only "in N minutes", which is the same in every zone, goes ahead
+ * without it (shown in the business's time).
+ */
+async function zoneFor(scope, named, relative = false) {
+    if (named && !isBareUtc(named)) {
+        if (!validZone(named))
+            return { error: `${named} is not a time zone. Use an IANA name such as America/New_York.` };
+        await scope.setPersonZone(named);
+        return named;
+    }
+    const known = scope.personZone() ?? (relative ? (scope.agentZone ?? "UTC") : null);
+    if (known)
+        return known;
+    return { error: "timezone_needed: you do not know their time zone. Ask which city they are in, then schedule again with timezone." };
+}
+async function create(scope, input) {
+    const zone = await zoneFor(scope, input.timezone, input.repeat === "once" && input.in_minutes !== undefined);
+    if (typeof zone !== "string")
+        return zone;
+    const now = scope.now();
+    const rule = ruleOf(input, zone, now);
+    if ("error" in rule)
+        return rule;
+    const repeats = rule.repeat !== "once";
+    if (!repeats && (input.until || input.times))
+        return { error: "until and times are only for repeats." };
+    const next = rule.repeat === "once" ? rule.at : nextRun(rule, zone, now);
+    if (!next)
+        return { error: "That never comes due. Check the time and days." };
+    if (next < now + 60_000)
+        return { error: "That time is less than a minute away or already past. Pick a later one." };
+    if (next > now + LIMITS.maxAheadMs)
+        return { error: "That is more than a year ahead." };
+    if (input.until) {
+        if (!date(input.until))
+            return { error: "until must be YYYY-MM-DD." };
+        if (input.until < localDate(zone, next))
+            return { error: "until is before the first run." };
+    }
+    const active = await scope.store.schedules(scope.conversationId);
+    if (active.length >= LIMITS.perPerson)
+        return { error: `They already have ${LIMITS.perPerson} scheduled messages. Cancel one first.` };
+    const same = active.find((s) => normalize(s.instruction) === normalize(input.message) && s.nextRunAt !== null && Math.abs(s.nextRunAt - next) < LIMITS.sameMessageGapMs);
+    if (same)
+        return { error: "already_scheduled: the same message is already scheduled at about that time.", scheduled: summary(same) };
+    const row = {
+        id: `s_${randomUUID().slice(0, 8)}`,
+        conversationId: scope.conversationId,
+        channel: scope.channel(),
+        instruction: input.message,
+        fixedText: false,
+        mode: input.mode ?? "message",
+        rule: input.respect_quiet_hours ? { ...rule, quiet: true } : rule,
+        timeZone: zone,
+        nextRunAt: next,
+        maxRuns: input.times ?? null,
+        endsOn: input.until ?? null,
+        origin: "person",
+    };
+    await scope.store.addSchedule(row);
+    const [saved] = (await scope.store.schedules(scope.conversationId)).filter((s) => s.id === row.id);
+    return { scheduled: summary(saved), now: formatLocal(zone, now) };
+}
+function ruleOf(input, zone, now) {
+    const time = input.time ? clock(input.time) : null;
+    if (input.time && !time)
+        return { error: "time must be HH:MM." };
+    if (input.day_of_month !== undefined && input.repeat !== "monthly")
+        return { error: "day_of_month is only for monthly." };
+    switch (input.repeat) {
+        case "once": {
+            if (input.in_minutes)
+                return { repeat: "once", at: Math.ceil((now + input.in_minutes * 60_000) / 60_000) * 60_000 };
+            if (!time)
+                return { error: "once needs time (and date), or in_minutes." };
+            if (input.date) {
+                const d = date(input.date);
+                if (!d)
+                    return { error: "date must be YYYY-MM-DD." };
+                return { repeat: "once", at: localToUtc(zone, d.year, d.month, d.day, time.hour, time.minute) };
+            }
+            const today = parts(zone, now);
+            let at = localToUtc(zone, today.year, today.month, today.day, time.hour, time.minute);
+            if (at <= now) {
+                const t = new Date(Date.UTC(today.year, today.month - 1, today.day + 1));
+                at = localToUtc(zone, t.getUTCFullYear(), t.getUTCMonth() + 1, t.getUTCDate(), time.hour, time.minute);
+            }
+            return { repeat: "once", at };
+        }
+        case "daily":
+            return time ? { repeat: "daily", time: input.time } : { error: "daily needs time." };
+        case "weekly":
+            if (!time || !input.days?.length)
+                return { error: "weekly needs time and days." };
+            return { repeat: "weekly", time: input.time, days: input.days.map((d) => DAY_INDEX[d]) };
+        case "monthly":
+            if (!time || input.day_of_month === undefined)
+                return { error: "monthly needs time and day_of_month." };
+            return { repeat: "monthly", time: input.time, day: input.day_of_month };
+        case "hourly": {
+            if ((input.from && !clock(input.from)) || (input.to && !clock(input.to)))
+                return { error: "from and to must be HH:MM." };
+            return { repeat: "hourly", every: input.every_hours ?? 1, from: input.from, to: input.to, days: input.days?.map((d) => DAY_INDEX[d]) };
+        }
+    }
+}
+/** A scheduled message from the business (a nudge with a time): fixed text, or an instruction. */
+export function businessSchedule(conversationId, channel, at, zone, body, quiet = true) {
+    return {
+        id: `s_${randomUUID().slice(0, 8)}`,
+        conversationId,
+        channel,
+        instruction: body.text ?? body.prompt ?? "",
+        fixedText: body.text !== undefined,
+        mode: "message",
+        rule: quiet ? { repeat: "once", at, quiet: true } : { repeat: "once", at },
+        timeZone: zone,
+        nextRunAt: at,
+        maxRuns: null,
+        endsOn: null,
+        origin: "api",
+    };
+}
+/**
+ * Claims every due schedule once: a run found too late is missed (and the schedule moves past
+ * now, so nothing floods after downtime), one `blocked` names a reason is skipped, the rest are
+ * queued for their conversation. Returns the queued runs with their inbox ids.
+ */
+/**
+ * Claims the schedules due at `now`. One marked `quiet` that comes due in the person's quiet hours
+ * (`quietEnd` says when they end) waits: a once moves to their end, a repeat skips that run.
+ */
+export async function claimDue(store, now, quietEnd, blocked) {
+    const queued = [];
+    for (const s of await store.dueSchedules(now)) {
+        const due = s.nextRunAt;
+        const late = now - due > LIMITS.lateMs;
+        const rule = s.rule;
+        let nextAt = nextRun(rule, s.timeZone, late ? now : due);
+        if (s.maxRuns && s.runCount + 1 >= s.maxRuns)
+            nextAt = null;
+        if (nextAt && s.endsOn && nextAt >= (endOfLocalDay(s.timeZone, s.endsOn) ?? Infinity))
+            nextAt = null;
+        const next = { nextRunAt: nextAt, status: (nextAt ? "active" : "done") };
+        const runId = `r_${randomUUID().slice(0, 8)}`;
+        if (late) {
+            const minutes = Math.round((now - due) / 60_000);
+            await store.claimRun(s, next, { id: runId, outcome: "missed", reason: `found ${minutes} minutes after its time; not sent late`, ranAt: now });
+            continue;
+        }
+        const ends = s.rule.quiet ? await quietEnd(s) : null;
+        if (ends !== null) {
+            const held = rule.repeat === "once";
+            await store.claimRun(s, held ? { nextRunAt: ends, status: "active" } : next, { id: runId, outcome: held ? "held" : "skipped", reason: held ? `their quiet hours: moved to ${formatLocal(s.timeZone, ends)}` : "their quiet hours", ranAt: now });
+            continue;
+        }
+        const reason = await blocked(s);
+        if (reason) {
+            await store.claimRun(s, next, { id: runId, outcome: "skipped", reason, ranAt: now });
+            continue;
+        }
+        const run = { run: runId, schedule: s.id, channel: s.channel, mode: s.mode, fixed: s.fixedText, text: s.fixedText ? s.instruction : noteFor(s) };
+        const inbox = await store.claimRun(s, next, { id: runId, outcome: "queued", ranAt: now }, { ...run });
+        if (inbox)
+            queued.push({ conversationId: s.conversationId, inbox, run });
+    }
+    return queued;
+}
+/** The note the agent's turn starts with when a schedule comes due. */
+function noteFor(s) {
+    const when = describe(s.rule, s.timeZone);
+    if (s.origin === "api")
+        return `[Nudge from the business, not from the person, scheduled earlier: ${s.instruction}] Write it to them now in your own words, or send nothing if it does not fit what they asked not to be messaged about.`;
+    if (s.mode === "check")
+        return `[Scheduled check, not from the person: they asked you to check ${when}: ${s.instruction}] Look now. Message them only if there is something to tell; otherwise send nothing.`;
+    return `[Scheduled message, not from the person: they asked you to message them ${when}. Do it now: ${s.instruction}] Write that message to them now.`;
+}
+function normalize(text) {
+    return text.toLowerCase().replace(/\s+/g, " ").trim();
+}

package/dist/src/skills.d.ts

@@ -0,0 +1,12 @@
+import { type Tool } from "./tools.ts";
+export interface Skill {
+    name: string;
+    description: string;
+    body: string;
+}
+/** An agent's folder as text: AGENTS.md and skills/<name>/SKILL.md, by their paths in it. */
+export type AgentFiles = Record<string, string>;
+export declare function readAgentFolder(dir: string): AgentFiles;
+export declare function loadSkills(files: AgentFiles): Skill[];
+export declare function loadInstructions(files: AgentFiles, skills: Skill[], inline?: boolean): string;
+export declare function skillTool(skills: Skill[], onLoad: (conversationId: string, name: string) => void): Tool;

package/dist/src/skills.js

@@ -0,0 +1,69 @@
+// An agent starts from its AGENTS.md and the one-line description of each skill; a skill's full
+// file is read only when the agent asks for it, so every prompt stays small.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { tool } from "./tools.js";
+function frontmatter(text) {
+    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+    if (!match)
+        return { fields: {}, body: text };
+    const fields = {};
+    for (const line of match[1].split("\n")) {
+        const at = line.indexOf(":");
+        if (at > 0)
+            fields[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+    }
+    return { fields, body: match[2] };
+}
+export function readAgentFolder(dir) {
+    const files = {};
+    const agents = join(dir, "AGENTS.md");
+    if (existsSync(agents))
+        files["AGENTS.md"] = readFileSync(agents, "utf8");
+    const root = join(dir, "skills");
+    if (!existsSync(root))
+        return files;
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const file = join(root, entry.name, "SKILL.md");
+        if (entry.isDirectory() && existsSync(file))
+            files[`skills/${entry.name}/SKILL.md`] = readFileSync(file, "utf8");
+    }
+    return files;
+}
+export function loadSkills(files) {
+    const skills = [];
+    for (const [path, text] of Object.entries(files)) {
+        const folder = /^skills\/([^/]+)\/SKILL\.md$/.exec(path)?.[1];
+        if (!folder)
+            continue;
+        const { fields, body } = frontmatter(text);
+        skills.push({ name: fields.name || folder, description: fields.description || "", body: body.trim() });
+    }
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function loadInstructions(files, skills, inline = false) {
+    const base = (files["AGENTS.md"] ?? "").trim();
+    if (!skills.length)
+        return base;
+    if (inline)
+        return `${base}\n\n${skills.map((s) => `## Skill: ${s.name}\n${s.body}`).join("\n\n")}`;
+    const list = skills.map((s) => `- ${s.name}: ${s.description}`).join("\n");
+    return `${base}\n\n## Skills\nLoad a skill with load_skill before doing what it covers; call it together with the first other tool you need, not on its own.\n${list}`;
+}
+export function skillTool(skills, onLoad) {
+    const names = skills.map((s) => s.name);
+    return tool({
+        name: "load_skill",
+        description: "Read a skill's full instructions. Use it before doing what the skill covers.",
+        input: z.object({ name: z.enum(names) }),
+        deadlineMs: 60_000,
+        run({ name }, context) {
+            const skill = skills.find((s) => s.name === name);
+            if (!skill)
+                return `No skill named ${name}.`;
+            onLoad(context.conversationId, name);
+            return skill.body;
+        },
+    });
+}