@avocadostudio-ai/orchestrator-core 0.29.0 → 0.30.0

package/dist/agents/assistant/next-steps.js

@@ -0,0 +1,34 @@
+const MAX_OPTIONS = 3;
+const MAX_CHARS = 80;
+const clean = (value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim().slice(0, MAX_CHARS) : "");
+export const nextStepsTool = {
+    name: "next_steps",
+    description: "Offer the person up to three next steps as buttons under your answer. Call it in the same message as your answer, never alone. Write each the way they would type it, specific to this answer (usually what you just offered to do). Add `routine` only when this question is worth asking again on a schedule, such as a check of how the site is doing: write it with its cadence, e.g. 'Check Google clicks every Monday'. Never offer a routine for a one-off change.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            options: { type: "array", items: { type: "string" }, description: "Up to three, each a short sentence in the person's language." },
+            routine: { type: "string", description: "Optional: the same question on a schedule, with its cadence." }
+        },
+        required: ["options"]
+    },
+    run: async (input) => {
+        const options = (Array.isArray(input.options) ? input.options : []).map(clean).filter(Boolean).slice(0, MAX_OPTIONS);
+        const routine = clean(input.routine);
+        return { result: "Shown to the person.", trace: JSON.stringify({ options, ...(routine ? { routine } : {}) }) };
+    }
+};
+/** The chips from a run's trace lines: the last next_steps call's, or none. */
+export function nextStepsFrom(calls) {
+    const call = [...calls].reverse().find((c) => c.name === "next_steps");
+    if (!call)
+        return null;
+    try {
+        const parsed = JSON.parse(call.result);
+        const options = Array.isArray(parsed.options) ? parsed.options.filter((o) => typeof o === "string") : [];
+        return { options, ...(typeof parsed.routine === "string" && parsed.routine ? { routine: parsed.routine } : {}) };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agents/assistant/permissions.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import type { RuntimeTool } from "../runtime/definition.ts";
+export type Permission = "allow" | "ask" | "never";
+export declare const sitePermissionsSchema: z.ZodObject<{
+    propose: z.ZodDefault<z.ZodEnum<{
+        never: "never";
+        ask: "ask";
+    }>>;
+    remember: z.ZodDefault<z.ZodEnum<{
+        never: "never";
+        allow: "allow";
+    }>>;
+    ask: z.ZodDefault<z.ZodEnum<{
+        never: "never";
+        allow: "allow";
+    }>>;
+    report: z.ZodDefault<z.ZodEnum<{
+        never: "never";
+        allow: "allow";
+    }>>;
+    outbound: z.ZodDefault<z.ZodEnum<{
+        never: "never";
+    }>>;
+    connectors: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        never: "never";
+        allow: "allow";
+    }>>>;
+}, z.core.$strip>;
+export type SitePermissions = z.infer<typeof sitePermissionsSchema>;
+export declare const DEFAULT_PERMISSIONS: SitePermissions;
+/** What a routine may narrow. Same keys; each value can only be the same or stricter. */
+export declare const routinePermissionsSchema: z.ZodObject<{
+    propose: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        never: "never";
+        ask: "ask";
+    }>>>;
+    remember: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        never: "never";
+        allow: "allow";
+    }>>>;
+    ask: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        never: "never";
+        allow: "allow";
+    }>>>;
+    report: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        never: "never";
+        allow: "allow";
+    }>>>;
+    outbound: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        never: "never";
+    }>>>;
+    connectors: z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        never: "never";
+        allow: "allow";
+    }>>>>;
+}, z.core.$strip>;
+export type RoutinePermissions = z.infer<typeof routinePermissionsSchema>;
+/** The site's settings, narrowed by a routine's. Never wider than the site's. */
+export declare function narrow(site: SitePermissions, routine?: RoutinePermissions): SitePermissions;
+/** The tools a run is offered: everything whose permission is not `never`. */
+export declare function permittedTools(tools: RuntimeTool[], permissions: SitePermissions): RuntimeTool[];
+export declare function connectorPermitted(id: string, permissions: SitePermissions): boolean;

package/dist/agents/assistant/permissions.js

@@ -0,0 +1,76 @@
+/*
+ * Permissions: one setting per kind of action (assistant concept §3).
+ *
+ *   allow — do it, and record it;
+ *   ask   — hold it for the owner in the Inbox;
+ *   never — the tool is not offered to the model at all.
+ *
+ * What exists today is narrower than the concept and says so in its types:
+ * a change can be asked for or refused, not applied unasked (earned autonomy
+ * comes later), and nothing outbound exists yet, so it is never. A routine can
+ * only narrow the site's settings, never widen them; and only the owner, in
+ * Settings, changes the site's.
+ */
+import { z } from "zod";
+export const sitePermissionsSchema = z.object({
+    /** Suggest changes, which wait in the Inbox. */
+    propose: z.enum(["ask", "never"]).default("ask"),
+    /** Record facts for later runs. */
+    remember: z.enum(["allow", "never"]).default("allow"),
+    /** Pause a background run to ask the owner a question. */
+    ask: z.enum(["allow", "never"]).default("allow"),
+    /** Leave a report in the Inbox. */
+    report: z.enum(["allow", "never"]).default("allow"),
+    /** Send anything off the site. Nothing does yet. */
+    outbound: z.enum(["never"]).default("never"),
+    /** Per connector id; absent means allow. */
+    connectors: z.record(z.string(), z.enum(["allow", "never"])).default({})
+});
+export const DEFAULT_PERMISSIONS = sitePermissionsSchema.parse({});
+/** What a routine may narrow. Same keys; each value can only be the same or stricter. */
+export const routinePermissionsSchema = sitePermissionsSchema.partial();
+const RANK = { never: 0, ask: 1, allow: 2 };
+const stricter = (a, b) => (b !== undefined && RANK[b] < RANK[a] ? b : a);
+/** The site's settings, narrowed by a routine's. Never wider than the site's. */
+export function narrow(site, routine) {
+    if (!routine)
+        return site;
+    const connectors = { ...site.connectors };
+    for (const [id, value] of Object.entries(routine.connectors ?? {})) {
+        connectors[id] = stricter(connectors[id] ?? "allow", value);
+    }
+    return {
+        propose: stricter(site.propose, routine.propose),
+        remember: stricter(site.remember, routine.remember),
+        ask: stricter(site.ask, routine.ask),
+        report: stricter(site.report, routine.report),
+        outbound: "never",
+        connectors
+    };
+}
+function permissionFor(effect, permissions) {
+    switch (effect) {
+        case "read":
+            return "allow";
+        case "propose":
+            return permissions.propose;
+        case "apply":
+            // Only the chat assistant is given an apply tool, and only while a person is asking.
+            return "allow";
+        case "remember":
+            return permissions.remember;
+        case "ask":
+            return permissions.ask;
+        case "report":
+            return permissions.report;
+        case "outbound":
+            return permissions.outbound;
+    }
+}
+/** The tools a run is offered: everything whose permission is not `never`. */
+export function permittedTools(tools, permissions) {
+    return tools.filter((tool) => permissionFor(tool.effect ?? "read", permissions) !== "never");
+}
+export function connectorPermitted(id, permissions) {
+    return (permissions.connectors[id] ?? "allow") !== "never";
+}

package/dist/agents/assistant/planner-tool.d.ts

@@ -0,0 +1,9 @@
+import type { ChatPipelineContext } from "../../chat/chat-pipeline.ts";
+import type { RuntimeTool } from "../runtime/definition.ts";
+/** Each host hands over its chat pipeline context once, at startup. */
+export declare function setAssistantPlanner(ctx: ChatPipelineContext | null): void;
+export declare function assistantPlannerAvailable(): boolean;
+/** What the editor sends a chat turn (manifest, capabilities, locale), kept for the assistant's edits. */
+export declare function rememberPlannerBody(scopeKey: string, body: Record<string, unknown>): void;
+export declare function plannerBodyFrom(raw: unknown): Record<string, unknown>;
+export declare const editPageTool: RuntimeTool;

package/dist/agents/assistant/planner-tool.js

@@ -0,0 +1,79 @@
+let pipelineCtx = null;
+const plannerBodies = new Map();
+const MAX_REMEMBERED = 200;
+/** Each host hands over its chat pipeline context once, at startup. */
+export function setAssistantPlanner(ctx) {
+    pipelineCtx = ctx;
+}
+export function assistantPlannerAvailable() {
+    return pipelineCtx !== null;
+}
+/** What the editor sends a chat turn (manifest, capabilities, locale), kept for the assistant's edits. */
+export function rememberPlannerBody(scopeKey, body) {
+    plannerBodies.delete(scopeKey);
+    plannerBodies.set(scopeKey, body);
+    if (plannerBodies.size > MAX_REMEMBERED)
+        plannerBodies.delete(plannerBodies.keys().next().value);
+}
+/** Fields of a chat body the planner may be given from the editor; nothing that steers execution. */
+const PLANNER_FIELDS = ["componentsManifest", "siteCapabilities", "sitePurpose", "siteHosting", "businessContext", "siteContext", "locale", "modelKey", "provider"];
+export function plannerBodyFrom(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const source = raw;
+    return Object.fromEntries(PLANNER_FIELDS.filter((key) => source[key] !== undefined).map((key) => [key, source[key]]));
+}
+export const editPageTool = {
+    name: "edit_page",
+    effect: "apply",
+    description: "Edit one page by instruction, through the editor's own page editor: add, remove, move or restyle blocks, change images, translate, or any edit that is more than replacing a field's text. Give the page slug and one plain instruction, as the person would say it. It applies at once, with undo. Something that deletes content comes back held for the person's confirmation: tell them, and call again with confirm_plan set to the id you were given once they agree.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            page: { type: "string", description: "The page slug, e.g. /events/." },
+            instruction: { type: "string", description: "One edit, in plain words, e.g. 'Add a FAQ section with three questions about parking'." },
+            confirm_plan: { type: "string", description: "Only to apply an edit that came back held: its plan id." }
+        },
+        required: ["page", "instruction"]
+    },
+    run: async (input, ctx) => {
+        if (!pipelineCtx)
+            return { result: "Page edits are not available here. Use apply_changes for text, or say what you would change.", isError: true };
+        const slug = typeof input.page === "string" ? input.page : "";
+        const instruction = typeof input.instruction === "string" ? input.instruction.trim() : "";
+        if (!slug.startsWith("/") || !instruction)
+            return { result: "Give a page slug and an instruction.", isError: true };
+        const confirm = typeof input.confirm_plan === "string" && input.confirm_plan ? input.confirm_plan : undefined;
+        const siteId = ctx.scopeKey.includes("::") ? ctx.scopeKey.split("::")[0] : undefined;
+        // Imported here: the chat pipeline reaches the agents through its own imports.
+        const { runChatPipeline } = await import("../../chat/chat-pipeline.js");
+        const result = await runChatPipeline(pipelineCtx, {
+            ...plannerBodies.get(ctx.scopeKey),
+            session: ctx.scopeKey,
+            ...(siteId ? { siteId } : {}),
+            slug,
+            message: instruction,
+            ...(confirm ? { executionMode: "apply_pending_plan", pendingPlanId: confirm } : {})
+        });
+        const payload = (result.payload ?? {});
+        const changes = (payload.changes ?? []).slice(0, 12);
+        const list = changes.length ? `\nChanges:\n${changes.map((c) => `- ${c}`).join("\n")}` : "";
+        switch (payload.status) {
+            case "applied":
+                return { result: `Done on ${payload.updatedSlug ?? slug}: ${payload.summary ?? ""}${list}`, trace: `edited ${payload.updatedSlug ?? slug}: ${changes.length} changes` };
+            case "plan_ready":
+                return {
+                    result: `Held for confirmation, because it ${payload.destructiveReasons?.join("; ") || "removes content"}: ${payload.summary ?? ""}${list}\nAsk the person. If they agree, call edit_page again with the same page and confirm_plan "${payload.pendingPlanId ?? ""}".`,
+                    trace: `held an edit on ${slug} for confirmation`
+                };
+            case "needs_clarification":
+                return { result: `The page editor needs to know more: ${payload.summary ?? ""}`, trace: `the page editor asked a question about ${slug}` };
+            default:
+                return {
+                    result: `The page editor did not make this edit (${payload.status ?? `HTTP ${result.code}`}): ${payload.summary ?? JSON.stringify(payload.validationErrors ?? "")}`,
+                    isError: true,
+                    trace: `the page editor refused an edit on ${slug}`
+                };
+        }
+    }
+};

package/dist/agents/assistant/router.d.ts

@@ -0,0 +1,20 @@
+import type { ScheduleTrigger } from "../schedule.ts";
+export type Route = {
+    route: "planner";
+} | {
+    route: "assistant";
+    message: string;
+} | {
+    route: "routine";
+    schedule: ScheduleTrigger;
+    request: string;
+};
+export type RouteOptions = {
+    /**
+     * The chat's last reply was the assistant's. An edit that points back at it
+     * ("rewrite them", "change both") continues that conversation instead of
+     * taking the planner's shortcut.
+     */
+    followUp?: boolean;
+};
+export declare function routeMessage(message: string, options?: RouteOptions): Route;

package/dist/agents/assistant/router.js

@@ -0,0 +1,69 @@
+const DAYS = [
+    [/\b(sunday|sonntags?)\b/i, 0],
+    [/\b(monday|montags?)\b/i, 1],
+    [/\b(tuesday|dienstags?)\b/i, 2],
+    [/\b(wednesday|mittwochs?)\b/i, 3],
+    [/\b(thursday|donnerstags?)\b/i, 4],
+    [/\b(friday|freitags?)\b/i, 5],
+    [/\b(saturday|samstags?)\b/i, 6]
+];
+const DAY_NAMES = "monday|tuesday|wednesday|thursday|friday|saturday|sunday";
+const TAG_NAMEN = "montag|dienstag|mittwoch|donnerstag|freitag|samstag|sonntag";
+const CADENCE = new RegExp([
+    `\\b(every|each)\\s+(day|morning|week|${DAY_NAMES})\\b`,
+    "\\b(daily|weekly)\\b",
+    `\\bjeden\\s+(tag|morgen|${TAG_NAMEN})\\b`,
+    "\\bjede\\s+woche\\b",
+    `\\b(${TAG_NAMEN})s\\b`,
+    "\\b(täglich|wöchentlich)\\b"
+].join("|"), "i");
+/** A message that starts like a direct edit of the page: the planner's fast path. */
+const EDIT_START = /^\s*(please\s+|bitte\s+|can you\s+|could you\s+|kannst du\s+|könntest du\s+)?(change|make|set|replace|add|insert|append|remove|delete|rewrite|write|translate|update|move|swap|shorten|lengthen|fix|rename|create|generate|put|turn|duplicate|clone|copy|reorder|sort|align|center|centre|resize|crop|restyle|style|colou?r|increase|decrease|expand|simplify|improve|show|hide|use|link|undo|redo|ändere|änder|mach|setze|ersetze|füge|entferne|lösche|übersetze|schreib|schreibe|erstelle|verschiebe|kürze|verlängere|tausche|dupliziere|kopiere|verbessere|zeige|verstecke|blende)\b/i;
+/** An edit across the whole site needs finding every mention first: the assistant's. */
+const WHOLE_SITE = /\b(everywhere|on (all|every) pages?|across the (whole )?site|sitewide|site-wide)\b|(?:^|\s)(überall|auf allen seiten|auf der ganzen website)(?=$|\s|[.,!?])/i;
+const MENTION = /^\s*@(assistant|assistent)\b[:,]?\s*/i;
+/** Words that say "the thing we just did", with nothing of their own to repeat. */
+const FILLER = /\b(please|bitte|do|this|that|it|again|run|repeat|the same|same|mach|das|dies|es|wieder|nochmal|wiederholen|so|also|and|und|at|um|\d{1,2}(:00)?( ?uhr| ?h)?)\b/gi;
+function scheduleOf(message) {
+    if (!CADENCE.test(message))
+        return null;
+    const hourMatch = /\b(?:at|um)\s+(\d{1,2})(?::00)?\s*(?:uhr|h|am|pm)?\b/i.exec(message);
+    let hour = hourMatch ? Number(hourMatch[1]) : 6;
+    if (hourMatch && /pm/i.test(hourMatch[0]) && hour < 12)
+        hour += 12;
+    if (hour > 23)
+        hour = 6;
+    if (/\b(every|each)\s+(day|morning)\b|\bdaily\b|\bjeden\s+(tag|morgen)\b|\btäglich\b/i.test(message)) {
+        return { kind: "schedule", every: "day", hour, weekday: 1 };
+    }
+    const weekday = DAYS.find(([pattern]) => pattern.test(message))?.[1] ?? 1;
+    return { kind: "schedule", every: "week", hour, weekday };
+}
+/** What the routine should do: the message minus its cadence, when that leaves a request of its own. */
+function requestOf(message) {
+    const rest = message
+        .replace(CADENCE, " ")
+        .replace(/\b(?:at|um)\s+\d{1,2}(?::00)?\s*(?:uhr|h|am|pm)?\b/gi, " ")
+        .replace(/^[\s,.:;-]+|[\s,.:;-]+$/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    const meaningful = rest.replace(FILLER, " ").replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+    return meaningful.split(" ").filter(Boolean).length >= 3 ? rest : "";
+}
+/** "them", "those", "die": an edit that points back at what the assistant just said. */
+const BACK_REFERENCE = /\b(them|those|these|that|both|all of them|the ones?|die|diese|das|dies|beide|alle)\b/i;
+export function routeMessage(message, options = {}) {
+    const text = message.trim();
+    if (!text)
+        return { route: "planner" };
+    const mention = MENTION.exec(text);
+    const body = mention ? text.slice(mention[0].length).trim() : text;
+    const schedule = scheduleOf(body);
+    if (schedule)
+        return { route: "routine", schedule, request: requestOf(body) };
+    if (mention)
+        return { route: "assistant", message: body || text };
+    if (EDIT_START.test(body) && !WHOLE_SITE.test(body) && !(options.followUp && BACK_REFERENCE.test(body)))
+        return { route: "planner" };
+    return { route: "assistant", message: body };
+}

package/dist/agents/assistant/routines.d.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import type { DurableStore } from "../../durable/types.ts";
+export declare const ROUTINE_PREFIX = "routine:";
+export declare const routineSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    job: z.ZodDefault<z.ZodString>;
+    request: z.ZodString;
+    skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    connectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    schedule: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"schedule">;
+        every: z.ZodEnum<{
+            day: "day";
+            week: "week";
+        }>;
+        hour: z.ZodDefault<z.ZodNumber>;
+        weekday: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    events: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        publish: "publish";
+    }>>>;
+    may: z.ZodOptional<z.ZodObject<{
+        propose: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            never: "never";
+            ask: "ask";
+        }>>>;
+        remember: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            never: "never";
+            allow: "allow";
+        }>>>;
+        ask: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            never: "never";
+            allow: "allow";
+        }>>>;
+        report: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            never: "never";
+            allow: "allow";
+        }>>>;
+        outbound: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            never: "never";
+        }>>>;
+        connectors: z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            never: "never";
+            allow: "allow";
+        }>>>>;
+    }, z.core.$strip>>;
+    budget: z.ZodDefault<z.ZodObject<{
+        usdPerRun: z.ZodNumber;
+        usdPerMonth: z.ZodNumber;
+    }, z.core.$strip>>;
+    tier: z.ZodDefault<z.ZodEnum<{
+        fast: "fast";
+        balanced: "balanced";
+        reasoning: "reasoning";
+    }>>;
+    maxSteps: z.ZodDefault<z.ZodNumber>;
+    fromRunId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Routine = z.infer<typeof routineSchema>;
+export type RoutineInput = z.input<typeof routineSchema>;
+export type SiteRoutine = Routine & {
+    origin: "template" | "site";
+    enabled: boolean;
+    since: number;
+};
+/** The templates. Off until a site switches one on. */
+export declare const ROUTINE_TEMPLATES: Routine[];
+export declare function getRoutineTemplate(id: string): Routine | undefined;
+export declare function isSiteRoutineId(id: string): boolean;
+/** A new id for a site routine, readable in logs: `routine:monday-search-check-3f9a`. */
+export declare function newRoutineId(name: string): string;
+/** Every routine for a site: the templates with the site's switch, then its own, by name. */
+export declare function listSiteRoutines(store: DurableStore, scopeKey: string): Promise<SiteRoutine[]>;
+export declare function getSiteRoutine(store: DurableStore, scopeKey: string, id: string): Promise<SiteRoutine | undefined>;
+/** Create or replace a site routine. Templates are code and cannot be saved over. */
+export declare function saveSiteRoutine(store: DurableStore, scopeKey: string, input: RoutineInput, options?: {
+    enabled?: boolean;
+    by?: string;
+}): Promise<SiteRoutine | {
+    error: string;
+}>;
+export declare function removeSiteRoutine(store: DurableStore, scopeKey: string, id: string): Promise<boolean>;
+/** "every Monday at 06:00 UTC", for a routine's line on the Agents page and in chat. */
+export declare function describeSchedule(routine: Pick<Routine, "schedule" | "events">): string;

package/dist/agents/assistant/routines.js

@@ -0,0 +1,142 @@
+/*
+ * Routines: the assistant working without being asked (assistant concept §2.5).
+ *
+ * A routine is a saved request with a trigger, the skills its job always
+ * needs, the connectors it may use, permissions that can only narrow the
+ * site's, and a budget. What used to be a coded agent is a routine template:
+ * the Search analyst is "weekly search review" with two skills and Search
+ * Console, nothing more.
+ *
+ * Templates are code and keep their old agent ids (`findings-review`,
+ * `search-analyst`), so runs, settings and Inbox items recorded before the
+ * split still resolve. A site's own routines — most often made from a chat
+ * answer with "do this every Monday" — are stored as agent settings rows with
+ * an id starting `routine:` and the routine as the row's spec, which both
+ * durable stores already keep.
+ */
+import { randomBytes } from "node:crypto";
+import { z } from "zod";
+import { scheduleTriggerSchema } from "../schedule.js";
+import { DEFAULT_AGENT_BUDGET } from "../runtime/definition.js";
+import { routinePermissionsSchema } from "./permissions.js";
+export const ROUTINE_PREFIX = "routine:";
+export const routineSchema = z.object({
+    id: z.string().min(1).max(80),
+    name: z.string().trim().min(1).max(80),
+    /** What it is for, in one line. Shown on the Agents page. */
+    job: z.string().trim().max(240).default(""),
+    /** The request each run starts from, as the owner would say it. */
+    request: z.string().trim().min(1).max(2000),
+    /** Skills loaded up front. Others can still be loaded with use_skill. */
+    skills: z.array(z.string()).max(8).default([]),
+    /**
+     * Connectors it may use. Absent: every connected one the site permits.
+     * Listed: only these, and the routine cannot run until they are connected.
+     */
+    connectors: z.array(z.string()).max(8).optional(),
+    schedule: scheduleTriggerSchema.optional(),
+    events: z.array(z.enum(["publish"])).default([]),
+    may: routinePermissionsSchema.optional(),
+    budget: z
+        .object({ usdPerRun: z.number().positive().max(5), usdPerMonth: z.number().positive().max(200) })
+        .default(DEFAULT_AGENT_BUDGET),
+    tier: z.enum(["fast", "balanced", "reasoning"]).default("balanced"),
+    maxSteps: z.number().int().min(1).max(40).default(20),
+    /** The chat run it was made from, when it was. */
+    fromRunId: z.string().optional()
+});
+const template = (input) => routineSchema.parse(input);
+/** The templates. Off until a site switches one on. */
+export const ROUTINE_TEMPLATES = [
+    template({
+        id: "findings-review",
+        name: "Findings review",
+        job: "Each week, reviews the open findings, proposes the fixes it is sure of, and asks when it is not.",
+        request: "Review this site's open findings. Summarise what matters this week, propose fixes for the ones you are sure of, and ask the owner if one decision blocks you.",
+        skills: ["findings-triage"],
+        connectors: [],
+        schedule: { kind: "schedule", every: "week", weekday: 1, hour: 7 }
+    }),
+    template({
+        id: "search-analyst",
+        name: "Weekly search review",
+        job: "Each week, reads Google Search Console and proposes the few title, description and content changes that should bring the most clicks.",
+        request: "Weekly search review. Find the few changes that should bring this site the most clicks from Google, and propose them.",
+        skills: ["search-analysis", "search-snippets"],
+        connectors: ["search-console"],
+        schedule: { kind: "schedule", every: "week", weekday: 1, hour: 6 }
+    })
+];
+export function getRoutineTemplate(id) {
+    return ROUTINE_TEMPLATES.find((routine) => routine.id === id);
+}
+export function isSiteRoutineId(id) {
+    return id.startsWith(ROUTINE_PREFIX);
+}
+/** A new id for a site routine, readable in logs: `routine:monday-search-check-3f9a`. */
+export function newRoutineId(name) {
+    const slug = name
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    return `${ROUTINE_PREFIX}${slug || "routine"}-${randomBytes(2).toString("hex")}`;
+}
+/** Every routine for a site: the templates with the site's switch, then its own, by name. */
+export async function listSiteRoutines(store, scopeKey) {
+    const rows = await store.listAgentSettings(scopeKey);
+    const byId = new Map(rows.map((row) => [row.agentId, row]));
+    const templates = ROUTINE_TEMPLATES.map((routine) => {
+        const row = byId.get(routine.id);
+        return { ...routine, origin: "template", enabled: row?.enabled ?? false, since: row?.updatedAt ?? 0 };
+    });
+    const own = [];
+    for (const row of rows) {
+        if (!isSiteRoutineId(row.agentId) || !row.spec)
+            continue;
+        // A stored routine this build cannot read is left out, not run half-understood.
+        const parsed = routineSchema.safeParse({ ...row.spec, id: row.agentId });
+        if (!parsed.success)
+            continue;
+        own.push({ ...parsed.data, origin: "site", enabled: row.enabled, since: row.updatedAt });
+    }
+    own.sort((a, b) => a.name.localeCompare(b.name));
+    return [...templates, ...own];
+}
+export async function getSiteRoutine(store, scopeKey, id) {
+    return (await listSiteRoutines(store, scopeKey)).find((routine) => routine.id === id);
+}
+/** Create or replace a site routine. Templates are code and cannot be saved over. */
+export async function saveSiteRoutine(store, scopeKey, input, options = {}) {
+    if (!isSiteRoutineId(input.id))
+        return { error: `a site routine's id starts with "${ROUTINE_PREFIX}"` };
+    const parsed = routineSchema.safeParse(input);
+    if (!parsed.success)
+        return { error: parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ") };
+    const row = await store.putAgentSetting({
+        scopeKey,
+        agentId: parsed.data.id,
+        enabled: options.enabled ?? true,
+        ...(options.by ? { owner: options.by } : {}),
+        spec: parsed.data
+    });
+    return { ...parsed.data, origin: "site", enabled: row.enabled, since: row.updatedAt };
+}
+export async function removeSiteRoutine(store, scopeKey, id) {
+    if (!isSiteRoutineId(id))
+        return false;
+    return store.deleteAgentSetting(scopeKey, id);
+}
+/** "every Monday at 06:00 UTC", for a routine's line on the Agents page and in chat. */
+export function describeSchedule(routine) {
+    const parts = [];
+    if (routine.schedule) {
+        const hour = `${String(routine.schedule.hour).padStart(2, "0")}:00 UTC`;
+        const days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+        parts.push(routine.schedule.every === "day" ? `every day at ${hour}` : `every ${days[routine.schedule.weekday]} at ${hour}`);
+    }
+    if (routine.events.includes("publish"))
+        parts.push("after every publish");
+    return parts.join(", ") || "only when started by hand";
+}

package/dist/agents/assistant/site-connections.d.ts

@@ -0,0 +1,17 @@
+import type { DurableStore } from "../../durable/types.ts";
+export declare const ASSISTANT_ROW = "assistant";
+/** The value a set secret field reads as in a site's connections. */
+export declare const SECRET_SET = "(set)";
+/** The secrets.ts name a connector's secret field is kept under. */
+export declare const connectorSecretName: (connectorId: string, key: string) => string;
+export type SiteConnections = Record<string, Record<string, string>>;
+/**
+ * The site's connection settings, plus `google.signedIn` when the site has
+ * connected a Google account (the token itself stays in secrets.ts; only its
+ * presence is read here, so a status can be answered without decrypting).
+ */
+export declare function readSiteConnections(store: DurableStore, scopeKey: string): Promise<SiteConnections>;
+/** Replace one connection's settings for a site. Empty values are dropped. */
+export declare function writeSiteConnection(store: DurableStore, scopeKey: string, id: string, values: Record<string, unknown>, by?: string): Promise<void>;
+/** Whether a site can reach Google: its own sign-in, or the deployment's service account. */
+export declare function googleSignedIn(all: SiteConnections): boolean;

package/dist/agents/assistant/site-connections.js

@@ -0,0 +1,51 @@
+export const ASSISTANT_ROW = "assistant";
+/** The value a set secret field reads as in a site's connections. */
+export const SECRET_SET = "(set)";
+/** The secrets.ts name a connector's secret field is kept under. */
+export const connectorSecretName = (connectorId, key) => `connector:${connectorId}:${key}`;
+const MAX_VALUE = 500;
+/**
+ * The site's connection settings, plus `google.signedIn` when the site has
+ * connected a Google account (the token itself stays in secrets.ts; only its
+ * presence is read here, so a status can be answered without decrypting).
+ */
+export async function readSiteConnections(store, scopeKey) {
+    const rows = await store.listAgentSettings(scopeKey).catch(() => []);
+    const signedIn = rows.some((row) => row.agentId === "secret:google-refresh-token");
+    const raw = rows.find((row) => row.agentId === ASSISTANT_ROW)?.spec?.connections;
+    const out = signedIn ? { google: { signedIn: "1" } } : {};
+    // A secret field that is set reads as SECRET_SET: enough for a status, nothing to leak.
+    for (const row of rows) {
+        const match = /^secret:connector:([\w-]+):([\w-]+)$/.exec(row.agentId);
+        if (match)
+            out[match[1]] = { ...out[match[1]], [match[2]]: SECRET_SET };
+    }
+    if (!raw || typeof raw !== "object")
+        return out;
+    for (const [id, values] of Object.entries(raw)) {
+        if (!values || typeof values !== "object")
+            continue;
+        out[id] = { ...out[id], ...Object.fromEntries(Object.entries(values).filter((entry) => typeof entry[1] === "string")) };
+    }
+    return out;
+}
+/** Replace one connection's settings for a site. Empty values are dropped. */
+export async function writeSiteConnection(store, scopeKey, id, values, by) {
+    const rows = await store.listAgentSettings(scopeKey);
+    const row = rows.find((r) => r.agentId === ASSISTANT_ROW);
+    const clean = Object.fromEntries(Object.entries(values)
+        .filter((entry) => typeof entry[1] === "string" && entry[1].trim().length > 0)
+        .map(([key, value]) => [key, value.trim().slice(0, MAX_VALUE)]));
+    const connections = { ...(row?.spec?.connections ?? {}), [id]: clean };
+    await store.putAgentSetting({
+        scopeKey,
+        agentId: ASSISTANT_ROW,
+        enabled: true,
+        ...(by ? { owner: by } : {}),
+        spec: { ...(row?.spec ?? {}), connections }
+    });
+}
+/** Whether a site can reach Google: its own sign-in, or the deployment's service account. */
+export function googleSignedIn(all) {
+    return all.google?.signedIn === "1";
+}