@trycua/cua 0.2.0

package/dist/spaces/presenceTypes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The presence records of the native binding (`../native`), restated
+ * structurally so the browser-safe presence model type-checks without the
+ * native module (whose runtime loader imports `node:*`). The native records
+ * are assignable to these; `presenceTypes.check.ts` keeps them in step.
+ */
+/** A participant (`PresenceParticipant`). */
+export type PresenceParticipant = {
+    participantId: string;
+    principalId: string;
+    displayName: string;
+    color: string;
+    kind: string;
+};
+/** A cursor (`PresenceCursor`). */
+export type PresenceCursor = {
+    displayId: string;
+    windowId?: string;
+    x: number;
+    y: number;
+    visible: boolean;
+    pressed: boolean;
+    shape: string;
+    shapeSource: string;
+    atMs: number;
+    receivedMs: number;
+};
+/** One presence event (`PresenceEvent`). */
+export type PresenceEvent = {
+    kind: string;
+    participant?: PresenceParticipant;
+    participantId?: string;
+    cursor?: PresenceCursor;
+    shape?: string;
+    shapeSource?: string;
+    reason?: string;
+    participantIds?: Array<string>;
+};
+/** A roster member at join (`PresenceMember`). */
+export type PresenceMember = {
+    participant: PresenceParticipant;
+    cursor?: PresenceCursor;
+};
+/** The part of a presence session `waitForPresence` reads. */
+export interface PresenceEventSource {
+    nextEvent(timeoutMs: bigint | undefined): Promise<PresenceEvent | undefined>;
+}

package/dist/spaces/presenceTypes.js

@@ -0,0 +1,7 @@
+/**
+ * The presence records of the native binding (`../native`), restated
+ * structurally so the browser-safe presence model type-checks without the
+ * native module (whose runtime loader imports `node:*`). The native records
+ * are assignable to these; `presenceTypes.check.ts` keeps them in step.
+ */
+export {};

package/dist/spaces/routines.d.ts

@@ -0,0 +1,158 @@
+/**
+ * `@trycua/cua/spaces/routines`: recurring tasks a Bot runs on a schedule.
+ * No native library, no Node imports, so it runs in a browser or a webview too.
+ *
+ * A routine is a saved prompt plus a clock, owned by one Bot (one long-lived
+ * agent thread). When it comes due the store hands it to a
+ * {@link RoutineRunner}, which gives that Bot another turn in the shared
+ * Space. The store keeps three things apart:
+ *
+ * - **persistence**: every mutation is written through a {@link RoutineStorage}
+ *   (a JSON array, the same shape the Swift and Rust SDKs write);
+ * - **the clock**: {@link RoutineStore.tick} takes the instant to evaluate, so
+ *   the scheduler is testable without sleeping;
+ * - **the firing**: delegated to the runner, so the store never sees a Space.
+ *
+ * ```ts
+ * import { RoutineStore, memoryStorage } from "@trycua/cua/spaces/routines"
+ *
+ * const routines = new RoutineStore(memoryStorage(), {
+ *   fire: async (r) => ({ kind: "started", runId: await startTurn(r.botID, r.prompt) }),
+ * })
+ * routines.create({ botID: "inbox", title: "Morning sweep", prompt: "Triage the inbox",
+ *                   schedule: { kind: "dailyAt", hour: 8, minute: 0 } })
+ * routines.startScheduler(15_000)
+ * ```
+ *
+ * A scheduler that was asleep fires a due routine **once** on waking, never
+ * once per missed slot, and a refused firing still uses its slot.
+ */
+/** The three recurrence shapes. `weekday` is 1 = Sunday … 7 = Saturday. */
+export type RoutineSchedule = {
+    kind: "everyMinutes";
+    minutes: number;
+} | {
+    kind: "dailyAt";
+    hour: number;
+    minute: number;
+} | {
+    kind: "weeklyOn";
+    weekday: number;
+    hour: number;
+    minute: number;
+};
+/** One routine. Dates are ISO 8601 (UTC, whole seconds). */
+export interface Routine {
+    id: string;
+    /** The Bot that runs it. A routine never spans Bots; a group chat does. */
+    botID: string;
+    title: string;
+    /** The text handed to the Bot when it fires. */
+    prompt: string;
+    schedule: RoutineSchedule;
+    isEnabled: boolean;
+    createdAt: string;
+    /** When the scheduler last started a firing (persisted, so a restart does not re-fire the past). */
+    lastFiredAt?: string;
+    /** The agent run the last firing produced. */
+    lastRunID?: string;
+    /** The scheduler's words about the last firing: started, refused, failed. */
+    lastOutcome?: string;
+}
+/** What happened when a routine fired. A refusal is not a failure. */
+export type RoutineFiring = {
+    kind: "started";
+    runId: string;
+} | {
+    kind: "refused";
+    reason: string;
+} | {
+    kind: "failed";
+    reason: string;
+};
+/** Gives a Bot its routine turn. Never throws: a refusal is a result. */
+export interface RoutineRunner {
+    fire(routine: Routine): Promise<RoutineFiring>;
+}
+/** Where the routine list lives. `load` returns `undefined` when nothing was saved. */
+export interface RoutineStorage {
+    load(): string | undefined;
+    save(json: string): void;
+}
+/** One line of the scheduler's log, newest first. */
+export interface FiringRecord {
+    routineID: string;
+    title: string;
+    at: string;
+    firing: RoutineFiring;
+}
+/** Marks a routine-originated turn in a transcript. */
+export declare const ROUTINE_PREFIX = "[routine]";
+/** The text a runner hands the Bot: `[routine] <title>: <prompt>`. */
+export declare function routineTurnText(routine: Pick<Routine, "title" | "prompt">): string;
+/** A {@link RoutineStorage} in memory. */
+export declare function memoryStorage(initial?: string): RoutineStorage & {
+    value: string | undefined;
+};
+/** ISO 8601 in UTC with whole seconds, the portable form every SDK reads. */
+export declare function isoSeconds(d: Date): string;
+/** The first slot strictly after `reference`, in local time; `undefined` for an invalid schedule. */
+export declare function nextFireDate(schedule: RoutineSchedule, reference: Date): Date | undefined;
+/** When `routine` next fires after `reference`, or `undefined` when disabled. */
+export declare function routineNextFire(routine: Routine, reference: Date): Date | undefined;
+/**
+ * Whether the scheduler should fire `routine` at `now`. Measured from the
+ * last firing, not the tick, so a sleeping scheduler fires once on waking.
+ */
+export declare function isDue(routine: Routine, now: Date): boolean;
+/** `8:05 AM`. */
+export declare function clockLabel(hour: number, minute: number): string;
+/** The one-line description of a schedule: `Every day at 8:00 AM`. */
+export declare function scheduleLabel(schedule: RoutineSchedule): string;
+/** `started run <id>`, `refused: <why>`, `failed: <why>`. */
+export declare function firingSummary(f: RoutineFiring): string;
+/** Parses a saved routine list. Throws on anything malformed rather than guessing. */
+export declare function parseRoutines(json: string): Routine[];
+/** Routines: storage, editing, and the clock that fires them. */
+export declare class RoutineStore {
+    readonly storage: RoutineStorage;
+    private runner?;
+    routines: Routine[];
+    /** What the scheduler did, newest first (at most 50). */
+    log: FiringRecord[];
+    private timer;
+    private ticking;
+    private readonly listeners;
+    constructor(storage: RoutineStorage, runner?: RoutineRunner | undefined);
+    attach(runner: RoutineRunner): void;
+    /** Called after every change. Returns an unsubscribe. */
+    subscribe(fn: () => void): () => void;
+    private changed;
+    /** Reads the list back. A corrupt file starts empty, with a logged complaint. */
+    load(): void;
+    save(): boolean;
+    routinesFor(botID: string): Routine[];
+    routine(id: string): Routine | undefined;
+    create(input: {
+        botID: string;
+        title: string;
+        prompt: string;
+        schedule: RoutineSchedule;
+        enabled?: boolean;
+        now?: Date;
+    }): Routine;
+    update(routine: Routine): void;
+    delete(id: string): void;
+    /** Enable or disable without deleting; the firing history is kept. */
+    setEnabled(id: string, enabled: boolean): void;
+    due(now: Date): Routine[];
+    /** Evaluates the clock once and fires whatever is due; returns what it fired. */
+    tick(now?: Date): Promise<FiringRecord[]>;
+    /** Fires one routine now, whatever the clock says ("Run now", and the scheduler's step). */
+    fire(routine: Routine, now?: Date): Promise<FiringRecord>;
+    /** One loop for every routine. Ticks never overlap. */
+    startScheduler(intervalMs?: number, clock?: () => Date): void;
+    stopScheduler(): void;
+    get isSchedulerRunning(): boolean;
+    private note;
+}

package/dist/spaces/routines.js

@@ -0,0 +1,339 @@
+/**
+ * `@trycua/cua/spaces/routines`: recurring tasks a Bot runs on a schedule.
+ * No native library, no Node imports, so it runs in a browser or a webview too.
+ *
+ * A routine is a saved prompt plus a clock, owned by one Bot (one long-lived
+ * agent thread). When it comes due the store hands it to a
+ * {@link RoutineRunner}, which gives that Bot another turn in the shared
+ * Space. The store keeps three things apart:
+ *
+ * - **persistence**: every mutation is written through a {@link RoutineStorage}
+ *   (a JSON array, the same shape the Swift and Rust SDKs write);
+ * - **the clock**: {@link RoutineStore.tick} takes the instant to evaluate, so
+ *   the scheduler is testable without sleeping;
+ * - **the firing**: delegated to the runner, so the store never sees a Space.
+ *
+ * ```ts
+ * import { RoutineStore, memoryStorage } from "@trycua/cua/spaces/routines"
+ *
+ * const routines = new RoutineStore(memoryStorage(), {
+ *   fire: async (r) => ({ kind: "started", runId: await startTurn(r.botID, r.prompt) }),
+ * })
+ * routines.create({ botID: "inbox", title: "Morning sweep", prompt: "Triage the inbox",
+ *                   schedule: { kind: "dailyAt", hour: 8, minute: 0 } })
+ * routines.startScheduler(15_000)
+ * ```
+ *
+ * A scheduler that was asleep fires a due routine **once** on waking, never
+ * once per missed slot, and a refused firing still uses its slot.
+ */
+/** Marks a routine-originated turn in a transcript. */
+export const ROUTINE_PREFIX = "[routine]";
+/** The text a runner hands the Bot: `[routine] <title>: <prompt>`. */
+export function routineTurnText(routine) {
+    return `${ROUTINE_PREFIX} ${routine.title}: ${routine.prompt}`;
+}
+/** A {@link RoutineStorage} in memory. */
+export function memoryStorage(initial) {
+    const s = {
+        value: initial,
+        load: () => s.value,
+        save: (json) => {
+            s.value = json;
+        },
+    };
+    return s;
+}
+/** ISO 8601 in UTC with whole seconds, the portable form every SDK reads. */
+export function isoSeconds(d) {
+    return new Date(Math.floor(d.getTime() / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function at(d, hour, minute) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate(), hour, minute, 0, 0);
+}
+function addDays(d, n) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate() + n, d.getHours(), d.getMinutes(), 0, 0);
+}
+/** The first slot strictly after `reference`, in local time; `undefined` for an invalid schedule. */
+export function nextFireDate(schedule, reference) {
+    switch (schedule.kind) {
+        case "everyMinutes":
+            if (!(schedule.minutes > 0))
+                return undefined;
+            return new Date(reference.getTime() + schedule.minutes * 60_000);
+        case "dailyAt": {
+            let c = at(reference, schedule.hour, schedule.minute);
+            if (c.getTime() <= reference.getTime())
+                c = at(addDays(c, 1), schedule.hour, schedule.minute);
+            return c;
+        }
+        case "weeklyOn": {
+            const want = (((schedule.weekday - 1) % 7) + 7) % 7;
+            const ahead = (want - reference.getDay() + 7) % 7;
+            let c = at(addDays(reference, ahead), schedule.hour, schedule.minute);
+            if (c.getTime() <= reference.getTime())
+                c = at(addDays(c, 7), schedule.hour, schedule.minute);
+            return c;
+        }
+    }
+}
+/** When `routine` next fires after `reference`, or `undefined` when disabled. */
+export function routineNextFire(routine, reference) {
+    if (!routine.isEnabled)
+        return undefined;
+    const last = routine.lastFiredAt ? new Date(routine.lastFiredAt) : undefined;
+    const from = last && last.getTime() > reference.getTime() ? last : reference;
+    return nextFireDate(routine.schedule, from);
+}
+/**
+ * Whether the scheduler should fire `routine` at `now`. Measured from the
+ * last firing, not the tick, so a sleeping scheduler fires once on waking.
+ */
+export function isDue(routine, now) {
+    if (!routine.isEnabled)
+        return false;
+    const from = new Date(routine.lastFiredAt ?? routine.createdAt);
+    const next = nextFireDate(routine.schedule, from);
+    return next !== undefined && next.getTime() <= now.getTime();
+}
+const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** `8:05 AM`. */
+export function clockLabel(hour, minute) {
+    const h = hour % 12 === 0 ? 12 : hour % 12;
+    return `${h}:${String(minute).padStart(2, "0")} ${hour < 12 ? "AM" : "PM"}`;
+}
+/** The one-line description of a schedule: `Every day at 8:00 AM`. */
+export function scheduleLabel(schedule) {
+    switch (schedule.kind) {
+        case "everyMinutes": {
+            const m = schedule.minutes;
+            if (m === 1)
+                return "Every minute";
+            if (m % 60 === 0)
+                return m === 60 ? "Every hour" : `Every ${m / 60} hours`;
+            return `Every ${m} minutes`;
+        }
+        case "dailyAt":
+            return `Every day at ${clockLabel(schedule.hour, schedule.minute)}`;
+        case "weeklyOn":
+            return `Every ${WEEKDAYS[(((schedule.weekday - 1) % 7) + 7) % 7]} at ${clockLabel(schedule.hour, schedule.minute)}`;
+    }
+}
+/** `started run <id>`, `refused: <why>`, `failed: <why>`. */
+export function firingSummary(f) {
+    return f.kind === "started" ? `started run ${f.runId}` : `${f.kind}: ${f.reason}`;
+}
+function validSchedule(s) {
+    if (!s || typeof s !== "object")
+        return false;
+    const o = s;
+    const int = (k) => Number.isInteger(o[k]);
+    switch (o.kind) {
+        case "everyMinutes":
+            return int("minutes");
+        case "dailyAt":
+            return int("hour") && int("minute");
+        case "weeklyOn":
+            return int("weekday") && int("hour") && int("minute");
+        default:
+            return false;
+    }
+}
+/** Parses a saved routine list. Throws on anything malformed rather than guessing. */
+export function parseRoutines(json) {
+    const v = JSON.parse(json);
+    if (!Array.isArray(v))
+        throw new Error("routines: expected a JSON array");
+    return v.map((r, i) => {
+        const o = r;
+        for (const k of ["id", "botID", "title", "prompt", "createdAt"]) {
+            if (typeof o[k] !== "string")
+                throw new Error(`routines[${i}].${k} is missing`);
+        }
+        if (!validSchedule(o.schedule))
+            throw new Error(`routines[${i}].schedule is not a schedule`);
+        const out = {
+            id: o.id,
+            botID: o.botID,
+            title: o.title,
+            prompt: o.prompt,
+            schedule: o.schedule,
+            isEnabled: o.isEnabled !== false,
+            createdAt: o.createdAt,
+        };
+        if (typeof o.lastFiredAt === "string")
+            out.lastFiredAt = o.lastFiredAt;
+        if (typeof o.lastRunID === "string")
+            out.lastRunID = o.lastRunID;
+        if (typeof o.lastOutcome === "string")
+            out.lastOutcome = o.lastOutcome;
+        return out;
+    });
+}
+function newId() {
+    return globalThis.crypto.randomUUID().toUpperCase();
+}
+/** Routines: storage, editing, and the clock that fires them. */
+export class RoutineStore {
+    storage;
+    runner;
+    routines = [];
+    /** What the scheduler did, newest first (at most 50). */
+    log = [];
+    timer;
+    ticking = false;
+    listeners = new Set();
+    constructor(storage, runner) {
+        this.storage = storage;
+        this.runner = runner;
+        this.load();
+    }
+    attach(runner) {
+        this.runner = runner;
+    }
+    /** Called after every change. Returns an unsubscribe. */
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    changed() {
+        for (const l of this.listeners)
+            l();
+    }
+    /** Reads the list back. A corrupt file starts empty, with a logged complaint. */
+    load() {
+        const raw = this.storage.load();
+        if (raw === undefined || raw.trim() === "") {
+            this.routines = [];
+            return;
+        }
+        try {
+            this.routines = parseRoutines(raw);
+        }
+        catch (e) {
+            this.routines = [];
+            this.note(`routines file could not be read (${e instanceof Error ? e.message : String(e)}); starting empty`);
+        }
+    }
+    save() {
+        try {
+            this.storage.save(JSON.stringify(this.routines, null, 2));
+            return true;
+        }
+        catch (e) {
+            this.note(`could not save routines: ${e instanceof Error ? e.message : String(e)}`);
+            return false;
+        }
+    }
+    routinesFor(botID) {
+        return this.routines.filter((r) => r.botID === botID).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    routine(id) {
+        return this.routines.find((r) => r.id === id);
+    }
+    create(input) {
+        const r = {
+            id: newId(),
+            botID: input.botID,
+            title: input.title,
+            prompt: input.prompt,
+            schedule: input.schedule,
+            isEnabled: input.enabled ?? true,
+            createdAt: isoSeconds(input.now ?? new Date()),
+        };
+        this.routines.push(r);
+        this.save();
+        this.changed();
+        return r;
+    }
+    update(routine) {
+        const i = this.routines.findIndex((r) => r.id === routine.id);
+        if (i < 0)
+            return;
+        this.routines[i] = routine;
+        this.save();
+        this.changed();
+    }
+    delete(id) {
+        this.routines = this.routines.filter((r) => r.id !== id);
+        this.save();
+        this.changed();
+    }
+    /** Enable or disable without deleting; the firing history is kept. */
+    setEnabled(id, enabled) {
+        const r = this.routine(id);
+        if (!r)
+            return;
+        r.isEnabled = enabled;
+        this.save();
+        this.changed();
+    }
+    due(now) {
+        return this.routines.filter((r) => isDue(r, now));
+    }
+    /** Evaluates the clock once and fires whatever is due; returns what it fired. */
+    async tick(now = new Date()) {
+        const fired = [];
+        for (const r of this.due(now))
+            fired.push(await this.fire(r, now));
+        return fired;
+    }
+    /** Fires one routine now, whatever the clock says ("Run now", and the scheduler's step). */
+    async fire(routine, now = new Date()) {
+        let firing;
+        if (!this.runner)
+            firing = { kind: "failed", reason: "no runner attached: not connected to a Space" };
+        else {
+            try {
+                firing = await this.runner.fire(routine);
+            }
+            catch (e) {
+                firing = { kind: "failed", reason: e instanceof Error ? e.message : String(e) };
+            }
+        }
+        // The slot is used even on a refusal; otherwise a busy Bot is hammered every tick.
+        const r = this.routine(routine.id);
+        if (r) {
+            r.lastFiredAt = isoSeconds(now);
+            if (firing.kind === "started")
+                r.lastRunID = firing.runId;
+            r.lastOutcome = firingSummary(firing);
+            this.save();
+        }
+        const record = { routineID: routine.id, title: routine.title, at: isoSeconds(now), firing };
+        this.log.unshift(record);
+        if (this.log.length > 50)
+            this.log.length = 50;
+        this.changed();
+        return record;
+    }
+    /** One loop for every routine. Ticks never overlap. */
+    startScheduler(intervalMs = 15_000, clock = () => new Date()) {
+        this.stopScheduler();
+        const loop = async () => {
+            if (!this.ticking) {
+                this.ticking = true;
+                try {
+                    await this.tick(clock());
+                }
+                finally {
+                    this.ticking = false;
+                }
+            }
+            if (this.timer !== undefined)
+                this.timer = setTimeout(loop, intervalMs);
+        };
+        this.timer = setTimeout(loop, 0);
+    }
+    stopScheduler() {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    get isSchedulerRunning() {
+        return this.timer !== undefined;
+    }
+    note(text) {
+        this.log.unshift({ routineID: "", title: "Routines", at: isoSeconds(new Date()), firing: { kind: "failed", reason: text } });
+    }
+}