@avocadostudio-ai/orchestrator-core 0.29.0 → 0.30.0

package/dist/agents/assistant/connectors/drive.js

@@ -0,0 +1,203 @@
+import { fenceSiteData } from "../../runtime/toolkit.js";
+import { googleFor, googleUnavailable, serviceAccountEmail } from "./google-access.js";
+import { readSiteConnections } from "../site-connections.js";
+import { assistantMediaSink, imageExtension } from "../media-sink.js";
+const DRIVE = "https://www.googleapis.com/drive/v3";
+const SHEETS = "https://sheets.googleapis.com/v4/spreadsheets";
+const SCOPES = ["https://www.googleapis.com/auth/drive.readonly", "https://www.googleapis.com/auth/spreadsheets.readonly"];
+const MAX_CHARS = 30_000;
+const MAX_DEPTH = 4;
+/** A folder link (https://drive.google.com/drive/folders/<id>) or a bare id → the id. */
+export function driveFolderId(raw) {
+    if (!raw)
+        return null;
+    const text = raw.trim();
+    const fromLink = /\/folders\/([\w-]{10,})/.exec(text)?.[1];
+    if (fromLink)
+        return fromLink;
+    return /^[\w-]{10,}$/.test(text) ? text : null;
+}
+async function folderFor(ctx) {
+    return driveFolderId((await readSiteConnections(ctx.store, ctx.scopeKey))["google-drive"]?.folder);
+}
+const fileFields = "id,name,mimeType,modifiedTime,parents";
+/** Whether a file sits in the folder, directly or a few folders down. */
+export async function insideFolder(source, file, folderId) {
+    let parents = file.parents ?? [];
+    for (let depth = 0; depth < MAX_DEPTH && parents.length > 0; depth++) {
+        if (parents.includes(folderId))
+            return true;
+        const next = [];
+        for (const parent of parents) {
+            const meta = await source.json(`${DRIVE}/files/${encodeURIComponent(parent)}?fields=parents&supportsAllDrives=true`, SCOPES, {}, "Google Drive");
+            next.push(...(meta.parents ?? []));
+        }
+        parents = next;
+    }
+    return false;
+}
+const KIND = {
+    "application/vnd.google-apps.document": "Doc",
+    "application/vnd.google-apps.spreadsheet": "Sheet",
+    "application/vnd.google-apps.presentation": "Slides",
+    "application/vnd.google-apps.folder": "Folder",
+    "application/pdf": "PDF"
+};
+const listTool = {
+    name: "drive_list",
+    description: "List the owner's documents in the site's Google Drive folder: name, kind, when it last changed, and its id for drive_read. Pass `in` with a folder's id to look inside a subfolder.",
+    inputSchema: { type: "object", properties: { in: { type: "string", description: "A subfolder's id, from an earlier listing." } } },
+    run: async (input, ctx) => {
+        const root = await folderFor(ctx);
+        if (!root)
+            return { result: "No Drive folder is set for this site (Connections → Google Drive).", isError: true };
+        const source = await googleFor(ctx);
+        let folder = root;
+        if (typeof input.in === "string" && input.in && input.in !== root) {
+            const meta = await source.json(`${DRIVE}/files/${encodeURIComponent(input.in)}?fields=${fileFields}&supportsAllDrives=true`, SCOPES, {}, "Google Drive");
+            if (!(await insideFolder(source, meta, root)))
+                return { result: "That folder is not inside the site's Drive folder.", isError: true };
+            folder = meta.id;
+        }
+        const params = new URLSearchParams({
+            q: `'${folder}' in parents and trashed = false`,
+            fields: `files(${fileFields})`,
+            orderBy: "modifiedTime desc",
+            pageSize: "100",
+            supportsAllDrives: "true",
+            includeItemsFromAllDrives: "true"
+        });
+        const body = await source.json(`${DRIVE}/files?${params.toString()}`, SCOPES, {}, "Google Drive");
+        const files = body.files ?? [];
+        const lines = files.map((f) => `${f.id} | ${KIND[f.mimeType] ?? f.mimeType} | ${f.name} | changed ${f.modifiedTime?.slice(0, 10) ?? "?"}`);
+        return { result: fenceSiteData(lines.join("\n") || "(the folder is empty)"), trace: `listed ${files.length} documents` };
+    }
+};
+const readTool = {
+    name: "drive_read",
+    description: "Read one document from the site's Drive folder by its id: a Doc or Slides as text, a Sheet as rows (every tab), a text or CSV file as it is.",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+    run: async (input, ctx) => {
+        const root = await folderFor(ctx);
+        if (!root)
+            return { result: "No Drive folder is set for this site (Connections → Google Drive).", isError: true };
+        const id = typeof input.id === "string" ? input.id.trim() : "";
+        if (!/^[\w-]{10,}$/.test(id))
+            return { result: "Give a document id from drive_list.", isError: true };
+        const source = await googleFor(ctx);
+        const file = await source.json(`${DRIVE}/files/${encodeURIComponent(id)}?fields=${fileFields}&supportsAllDrives=true`, SCOPES, {}, "Google Drive");
+        if (!(await insideFolder(source, file, root)))
+            return { result: "That document is not inside the site's Drive folder.", isError: true };
+        let text;
+        if (file.mimeType === "application/vnd.google-apps.spreadsheet") {
+            const meta = await source.json(`${SHEETS}/${encodeURIComponent(id)}?fields=sheets.properties.title`, SCOPES, {}, "Google Sheets");
+            const tabs = (meta.sheets ?? []).map((s) => s.properties?.title ?? "").filter(Boolean).slice(0, 8);
+            const params = new URLSearchParams();
+            for (const tab of tabs)
+                params.append("ranges", `'${tab.replaceAll("'", "''")}'!A1:Z300`);
+            const values = await source.json(`${SHEETS}/${encodeURIComponent(id)}/values:batchGet?${params.toString()}`, SCOPES, {}, "Google Sheets");
+            text = (values.valueRanges ?? [])
+                .map((range, i) => [`## ${tabs[i] ?? range.range ?? "Sheet"}`, ...(range.values ?? []).map((row) => row.join(" | "))].join("\n"))
+                .join("\n\n");
+            if (text.length > MAX_CHARS)
+                text = `${text.slice(0, MAX_CHARS)}\n…(cut at ${MAX_CHARS} characters)`;
+        }
+        else if (file.mimeType === "application/vnd.google-apps.document" || file.mimeType === "application/vnd.google-apps.presentation") {
+            text = await source.text(`${DRIVE}/files/${encodeURIComponent(id)}/export?mimeType=text/plain`, SCOPES, MAX_CHARS, "Google Drive");
+        }
+        else if (file.mimeType.startsWith("text/") || file.mimeType === "application/json") {
+            text = await source.text(`${DRIVE}/files/${encodeURIComponent(id)}?alt=media&supportsAllDrives=true`, SCOPES, MAX_CHARS, "Google Drive");
+        }
+        else {
+            return { result: `${file.name} is a ${KIND[file.mimeType] ?? file.mimeType}, which cannot be read as text yet. Ask the owner for a Doc or Sheet version.`, isError: true };
+        }
+        return { result: fenceSiteData(`${file.name} (changed ${file.modifiedTime?.slice(0, 10) ?? "?"})\n\n${text}`), trace: `read ${file.name}` };
+    }
+};
+const MAX_IMAGES = 24;
+const MAX_IMAGE_BYTES = 10_000_000;
+/**
+ * The owner's images onto the site: each one read from the site's folder and
+ * stored where the host keeps the site's media (media-sink.ts). Only the chat
+ * assistant has it, because it adds files to the site; a routine only proposes.
+ */
+const importImagesTool = {
+    name: "drive_import_images",
+    effect: "apply",
+    description: "Bring images from the site's Google Drive folder onto the site, so pages can use them. Give the image ids from drive_list, or none for every image in the folder (up to 24). Returns each image's name and its address on the site; use those addresses in the page (edit_page), and write alt text from what the person said or the file name.",
+    inputSchema: { type: "object", properties: { ids: { type: "array", items: { type: "string" } } } },
+    run: async (input, ctx) => {
+        if (ctx.agentId !== "assistant")
+            return { result: "Only the chat assistant brings images onto the site.", isError: true };
+        const root = await folderFor(ctx);
+        if (!root)
+            return { result: "No Drive folder is set for this site (Connections → Google Drive).", isError: true };
+        const sink = assistantMediaSink();
+        if (!sink)
+            return { result: "This site has nowhere to store images yet.", isError: true };
+        const source = await googleFor(ctx);
+        const wanted = Array.isArray(input.ids) ? input.ids.filter((id) => typeof id === "string" && /^[\w-]{10,}$/.test(id)) : [];
+        let files;
+        if (wanted.length > 0) {
+            files = [];
+            for (const id of wanted.slice(0, MAX_IMAGES)) {
+                files.push(await source.json(`${DRIVE}/files/${encodeURIComponent(id)}?fields=${fileFields}&supportsAllDrives=true`, SCOPES, {}, "Google Drive"));
+            }
+        }
+        else {
+            const params = new URLSearchParams({
+                q: `'${root}' in parents and trashed = false and mimeType contains 'image/'`,
+                fields: `files(${fileFields})`,
+                orderBy: "name",
+                pageSize: String(MAX_IMAGES),
+                supportsAllDrives: "true",
+                includeItemsFromAllDrives: "true"
+            });
+            files = (await source.json(`${DRIVE}/files?${params.toString()}`, SCOPES, {}, "Google Drive")).files ?? [];
+        }
+        const lines = [];
+        let imported = 0;
+        for (const file of files) {
+            if (!(await insideFolder(source, file, root))) {
+                lines.push(`${file.name}: not inside the site's Drive folder, skipped`);
+                continue;
+            }
+            if (!imageExtension(file.mimeType)) {
+                lines.push(`${file.name}: not an image the site can show (${file.mimeType}), skipped`);
+                continue;
+            }
+            try {
+                const { data } = await source.bytes(`${DRIVE}/files/${encodeURIComponent(file.id)}?alt=media&supportsAllDrives=true`, SCOPES, MAX_IMAGE_BYTES, "Google Drive");
+                const filename = /\.[a-z0-9]+$/i.test(file.name) ? file.name : `${file.name}.${imageExtension(file.mimeType)}`;
+                const stored = await sink({ filename, contentType: file.mimeType, data });
+                lines.push(`${file.name} | ${stored.url}`);
+                imported += 1;
+            }
+            catch (error) {
+                lines.push(`${file.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (files.length === 0)
+            return { result: "There are no images in the site's Drive folder.", isError: true };
+        return {
+            result: fenceSiteData(`Imported ${imported} of ${files.length} images. name | address on the site:\n${lines.join("\n")}`),
+            trace: `imported ${imported} images`,
+            ...(imported === 0 ? { isError: true } : {})
+        };
+    }
+};
+export const driveConnector = {
+    id: "google-drive",
+    name: "Google Drive",
+    description: "The owner's documents and sheets in one shared folder: prices, event plans, brand rules. Read-only.",
+    fields: [{ key: "folder", label: "Drive folder (link or ID)", placeholder: "https://drive.google.com/drive/folders/…" }],
+    tools: [listTool, readTool, importImagesTool],
+    grantTo: serviceAccountEmail,
+    status: (settings, all) => {
+        const unavailable = googleUnavailable(all);
+        if (unavailable)
+            return { connected: false, reason: unavailable };
+        const folder = driveFolderId(settings.folder);
+        return folder ? { connected: true, detail: `folder ${folder}` } : { connected: false, reason: "Set the Drive folder to read." };
+    }
+};

package/dist/agents/assistant/connectors/google-access.d.ts

@@ -0,0 +1,11 @@
+import type { DurableStore } from "../../../durable/types.ts";
+import { type GoogleAccess } from "../../../connections/google-auth.ts";
+import { type SiteConnections } from "../site-connections.ts";
+/** Null when the site signed in, or there is no service account: there is then nobody to grant access to. */
+export declare function serviceAccountEmail(): string | null;
+/** Why a site cannot reach Google, or null when it can. */
+export declare function googleUnavailable(all: SiteConnections): string | null;
+export declare function googleFor(ctx: {
+    store: DurableStore;
+    scopeKey: string;
+}): Promise<GoogleAccess>;

package/dist/agents/assistant/connectors/google-access.js

@@ -0,0 +1,21 @@
+import { googleTokenSource } from "../../../connections/google-auth.js";
+import { googleAccessFor } from "../../../connections/google-oauth.js";
+import { googleSignedIn } from "../site-connections.js";
+/** Null when the site signed in, or there is no service account: there is then nobody to grant access to. */
+export function serviceAccountEmail() {
+    const source = googleTokenSource();
+    return "error" in source ? null : source.account.client_email;
+}
+/** Why a site cannot reach Google, or null when it can. */
+export function googleUnavailable(all) {
+    if (googleSignedIn(all))
+        return null;
+    const source = googleTokenSource();
+    return "error" in source ? "Connect Google for this site." : null;
+}
+export async function googleFor(ctx) {
+    const access = await googleAccessFor(ctx.store, ctx.scopeKey);
+    if ("error" in access)
+        throw new Error(access.error);
+    return access;
+}

package/dist/agents/assistant/connectors/pagespeed.d.ts

@@ -0,0 +1,39 @@
+import type { Connector } from "./types.ts";
+type Audit = {
+    title?: string;
+    displayValue?: string;
+    numericValue?: number;
+    details?: {
+        type?: string;
+        overallSavingsMs?: number;
+    };
+};
+type FieldMetric = {
+    percentile?: number;
+    category?: string;
+};
+export type PageSpeedResponse = {
+    lighthouseResult?: {
+        categories?: {
+            performance?: {
+                score?: number;
+            };
+        };
+        audits?: Record<string, Audit>;
+    };
+    loadingExperience?: {
+        overall_category?: string;
+        metrics?: Record<string, FieldMetric>;
+    };
+    error?: {
+        message?: string;
+    };
+};
+/** Tests answer PageSpeed with a stub. */
+export declare function setPageSpeedFetchForTests(fn: typeof fetch | null): void;
+/** The site's public origin: its own setting, else the Search Console property when that is a URL. */
+export declare function publicOrigin(settings: Record<string, string>, searchConsole?: Record<string, string>): string | null;
+/** The response, in lines a model and an owner can both read. */
+export declare function describePageSpeed(url: string, strategy: string, body: PageSpeedResponse): string;
+export declare const pageSpeedConnector: Connector;
+export {};

package/dist/agents/assistant/connectors/pagespeed.js

@@ -0,0 +1,103 @@
+import { fenceSiteData } from "../../runtime/toolkit.js";
+import { getSecret } from "../../../connections/secrets.js";
+import { connectorSecretName, readSiteConnections } from "../site-connections.js";
+const API = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed";
+let fetchOverride = null;
+/** Tests answer PageSpeed with a stub. */
+export function setPageSpeedFetchForTests(fn) {
+    fetchOverride = fn;
+}
+/** The site's public origin: its own setting, else the Search Console property when that is a URL. */
+export function publicOrigin(settings, searchConsole = {}) {
+    for (const candidate of [settings.siteUrl, searchConsole.property, process.env.GSC_PROPERTY]) {
+        if (!candidate || candidate.startsWith("sc-domain:"))
+            continue;
+        try {
+            return new URL(candidate.trim()).origin;
+        }
+        catch {
+            // Not a URL; try the next one.
+        }
+    }
+    return null;
+}
+const ms = (value) => (typeof value === "number" ? `${(value / 1000).toFixed(1)} s` : "n/a");
+/** The response, in lines a model and an owner can both read. */
+export function describePageSpeed(url, strategy, body) {
+    const lab = body.lighthouseResult;
+    const score = lab?.categories?.performance?.score;
+    const audits = lab?.audits ?? {};
+    const field = body.loadingExperience?.metrics ?? {};
+    const lines = [
+        `${url} (${strategy})`,
+        `performance score: ${typeof score === "number" ? Math.round(score * 100) : "n/a"}/100`,
+        `lab: largest content ${audits["largest-contentful-paint"]?.displayValue ?? "n/a"}, layout shift ${audits["cumulative-layout-shift"]?.displayValue ?? "n/a"}, blocking time ${audits["total-blocking-time"]?.displayValue ?? "n/a"}`
+    ];
+    if (field.LARGEST_CONTENTFUL_PAINT_MS || field.INTERACTION_TO_NEXT_PAINT) {
+        lines.push(`real visitors (28 days, ${body.loadingExperience?.overall_category ?? "?"}): largest content ${ms(field.LARGEST_CONTENTFUL_PAINT_MS?.percentile)}, ` +
+            `response to input ${field.INTERACTION_TO_NEXT_PAINT?.percentile ?? "n/a"} ms, layout shift ${((field.CUMULATIVE_LAYOUT_SHIFT_SCORE?.percentile ?? 0) / 100).toFixed(2)}`);
+    }
+    else {
+        lines.push("real visitors: not enough Chrome data for this page");
+    }
+    const opportunities = Object.values(audits)
+        .filter((audit) => audit.details?.type === "opportunity" && (audit.details.overallSavingsMs ?? 0) >= 100)
+        .sort((a, b) => (b.details?.overallSavingsMs ?? 0) - (a.details?.overallSavingsMs ?? 0))
+        .slice(0, 5)
+        .map((audit) => `- ${audit.title} (saves about ${ms(audit.details?.overallSavingsMs)})`);
+    lines.push(opportunities.length ? `biggest savings:\n${opportunities.join("\n")}` : "no large savings found");
+    return lines.join("\n");
+}
+const pageSpeedTool = {
+    name: "page_speed",
+    description: "Measure how fast one page loads, with Google PageSpeed Insights: a performance score, real-visitor numbers when Google has them, and the biggest things slowing it. Takes up to half a minute per page; measure a few important pages, not all.",
+    inputSchema: {
+        type: "object",
+        properties: { page: { type: "string", description: "A page slug, e.g. /events/." }, strategy: { type: "string", enum: ["mobile", "desktop"] } },
+        required: ["page"]
+    },
+    run: async (input, ctx) => {
+        const connections = await readSiteConnections(ctx.store, ctx.scopeKey);
+        const origin = publicOrigin(connections.pagespeed ?? {}, connections["search-console"] ?? {});
+        if (!origin)
+            return { result: "The site's public address is not set (Connections → PageSpeed).", isError: true };
+        const slug = typeof input.page === "string" && input.page.startsWith("/") ? input.page : "/";
+        const strategy = input.strategy === "desktop" ? "desktop" : "mobile";
+        const url = `${origin}${slug}`;
+        const params = new URLSearchParams({ url, strategy, category: "performance" });
+        const apiKey = (await getSecret(ctx.store, ctx.scopeKey, connectorSecretName("pagespeed", "apiKey"))) ?? process.env.PAGESPEED_API_KEY?.trim();
+        if (apiKey)
+            params.set("key", apiKey);
+        const res = await (fetchOverride ?? fetch)(`${API}?${params.toString()}`);
+        const body = (await res.json().catch(() => ({})));
+        if (res.status === 429) {
+            return {
+                result: apiKey
+                    ? "PageSpeed's daily quota for this key is used up; try again tomorrow."
+                    : "PageSpeed refused: without an API key, Google's shared daily quota is used up. Add a (free) key in Connections → PageSpeed.",
+                isError: true
+            };
+        }
+        if (!res.ok)
+            return { result: `PageSpeed answered ${res.status}: ${body.error?.message ?? "no reason given"}`, isError: true };
+        return { result: fenceSiteData(describePageSpeed(url, strategy, body)), trace: `measured ${slug} (${strategy})` };
+    }
+};
+export const pageSpeedConnector = {
+    id: "pagespeed",
+    name: "PageSpeed Insights",
+    description: "How fast pages load for real visitors, and what slows them down. Public data, nothing to grant.",
+    fields: [
+        { key: "siteUrl", label: "Public address of the site", placeholder: "https://example.com" },
+        { key: "apiKey", label: "API key", secret: true, helpUrl: "https://developers.google.com/speed/docs/insights/v5/get-started#APIKey" }
+    ],
+    tools: [pageSpeedTool],
+    status: (settings, all) => {
+        const origin = publicOrigin(settings, all["search-console"] ?? {});
+        if (!origin)
+            return { connected: false, reason: "Set the site's public address." };
+        if (!settings.apiKey && !process.env.PAGESPEED_API_KEY)
+            return { connected: false, reason: "Add an API key (free): without one, Google's shared daily quota is used up." };
+        return { connected: true, detail: origin };
+    }
+};

package/dist/agents/assistant/connectors/types.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeTool } from "../../runtime/definition.ts";
+import type { SiteConnections } from "../site-connections.ts";
+export type ConnectorStatus = {
+    connected: true;
+    detail?: string;
+} | {
+    connected: false;
+    reason: string;
+};
+/** A setting a site fills in, e.g. its Analytics property. Labels are the editor's to translate; these are defaults. */
+export type ConnectorField = {
+    key: string;
+    label: string;
+    placeholder?: string;
+    /** An API key and the like: kept encrypted (secrets.ts), shown back only as a hint. */
+    secret?: boolean;
+    /** Where the owner gets one, when it is not obvious. */
+    helpUrl?: string;
+};
+export type Connector = {
+    id: string;
+    name: string;
+    /** One line for people: what it gives the assistant. */
+    description: string;
+    fields: ConnectorField[];
+    tools: RuntimeTool[];
+    /** Connected for a site with these settings (and its other connections')? Synchronous: no network. */
+    status: (settings: Record<string, string>, all: SiteConnections) => ConnectorStatus;
+    /** Who to give access to, when access is granted by sharing (a service account's email). */
+    grantTo?: () => string | null;
+};

package/dist/agents/assistant/connectors/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,14 @@
+import type { Connector, ConnectorStatus } from "./connectors/types.ts";
+import type { SiteConnections } from "./site-connections.ts";
+export type { Connector, ConnectorField, ConnectorStatus } from "./connectors/types.ts";
+export declare const CONNECTORS: Connector[];
+/** Tests add a connector for their own duration. */
+export declare function registerConnectorForTests(connector: Connector): () => void;
+export declare function allConnectors(): Connector[];
+export declare function getConnector(id: string): Connector | undefined;
+/** A connector's state for a site. */
+export declare function connectorStatus(connector: Connector, connections?: SiteConnections): ConnectorStatus;
+/** Why a set of connectors cannot all be used for a site, or null when they can. */
+export declare function missingConnector(ids: string[], connections?: SiteConnections): string | null;
+/** The connectors connected for a site, in order. */
+export declare function connectedConnectors(connections?: SiteConnections): Connector[];

package/dist/agents/assistant/connectors.js

@@ -0,0 +1,66 @@
+/*
+ * Connectors: data from outside the site (assistant concept §2.4).
+ *
+ *   Google Search Console  what people search for, and what they click
+ *   Google Analytics       visits and key events (bookings, enquiries)
+ *   Google Drive           the owner's own documents and sheets
+ *   PageSpeed Insights     how fast pages load, and what slows them
+ *
+ * Each is connected per site: the site's settings (which property, which
+ * folder, which address) live with its assistant settings, and the Google ones
+ * share the deployment's service account (connections/google-auth.ts), which
+ * the site grants access to like a colleague. Everything a connector returns is
+ * untrusted content and is fenced like site text.
+ */
+import { SEARCH_TOOLS, searchConsoleStatus } from "../search/tools.js";
+import { serviceAccountEmail } from "./connectors/google-access.js";
+import { analyticsConnector } from "./connectors/analytics.js";
+import { driveConnector } from "./connectors/drive.js";
+import { pageSpeedConnector } from "./connectors/pagespeed.js";
+const searchConsoleConnector = {
+    id: "search-console",
+    name: "Google Search Console",
+    description: "What people search for on Google, and how often they see and click each page. Read-only.",
+    fields: [{ key: "property", label: "Search Console property", placeholder: "https://example.com/ or sc-domain:example.com" }],
+    tools: SEARCH_TOOLS,
+    grantTo: serviceAccountEmail,
+    status: (settings, all) => {
+        const status = searchConsoleStatus(settings, all);
+        return "error" in status ? { connected: false, reason: status.error } : { connected: true, detail: status.property };
+    }
+};
+export const CONNECTORS = [searchConsoleConnector, analyticsConnector, driveConnector, pageSpeedConnector];
+let extra = [];
+/** Tests add a connector for their own duration. */
+export function registerConnectorForTests(connector) {
+    extra = [...extra, connector];
+    return () => {
+        extra = extra.filter((c) => c !== connector);
+    };
+}
+export function allConnectors() {
+    return [...CONNECTORS, ...extra];
+}
+export function getConnector(id) {
+    return allConnectors().find((connector) => connector.id === id);
+}
+/** A connector's state for a site. */
+export function connectorStatus(connector, connections = {}) {
+    return connector.status(connections[connector.id] ?? {}, connections);
+}
+/** Why a set of connectors cannot all be used for a site, or null when they can. */
+export function missingConnector(ids, connections = {}) {
+    for (const id of ids) {
+        const connector = getConnector(id);
+        if (!connector)
+            return `Unknown connector ${id}.`;
+        const status = connectorStatus(connector, connections);
+        if (!status.connected)
+            return status.reason;
+    }
+    return null;
+}
+/** The connectors connected for a site, in order. */
+export function connectedConnectors(connections = {}) {
+    return allConnectors().filter((connector) => connectorStatus(connector, connections).connected);
+}

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

@@ -0,0 +1,14 @@
+import type { DurableStore } from "../../durable/types.ts";
+export declare const CONTEXT_SECTIONS: readonly ["business", "voice", "goals", "avoid"];
+export type ContextSection = (typeof CONTEXT_SECTIONS)[number];
+export declare const CONTEXT_SECTION_MAX_CHARS = 2000;
+export declare function isContextSection(value: unknown): value is ContextSection;
+export declare function readContextSections(store: DurableStore, scopeKey: string): Promise<Record<ContextSection, string>>;
+/** Set one section. An empty value clears it. */
+export declare function writeContextSection(store: DurableStore, scopeKey: string, section: ContextSection, value: string, by?: string): Promise<void>;
+/**
+ * The context block a run starts with, or "" when the site has none. Facts an
+ * agent recorded came from reading pages or connectors, so they are kept apart
+ * from what the owner stated, and labelled.
+ */
+export declare function siteContextBlock(store: DurableStore, scopeKey: string): Promise<string>;

package/dist/agents/assistant/context.js

@@ -0,0 +1,67 @@
+import { SITE_FACT_KINDS } from "../learning.js";
+export const CONTEXT_SECTIONS = ["business", "voice", "goals", "avoid"];
+export const CONTEXT_SECTION_MAX_CHARS = 2_000;
+const LABEL = {
+    business: "About the business",
+    voice: "Voice and tone",
+    goals: "What counts as a win",
+    avoid: "Do not touch"
+};
+export function isContextSection(value) {
+    return typeof value === "string" && CONTEXT_SECTIONS.includes(value);
+}
+const keyOf = (section) => `about.${section}`;
+export async function readContextSections(store, scopeKey) {
+    const rows = await store.listMemory({ scopeKey, scope: "site", kind: "decision", status: "active", limit: 50 });
+    const sections = Object.fromEntries(CONTEXT_SECTIONS.map((s) => [s, ""]));
+    for (const section of CONTEXT_SECTIONS) {
+        sections[section] = rows.find((row) => row.key === keyOf(section))?.value ?? "";
+    }
+    return sections;
+}
+/** Set one section. An empty value clears it. */
+export async function writeContextSection(store, scopeKey, section, value, by) {
+    const text = value.trim().slice(0, CONTEXT_SECTION_MAX_CHARS);
+    if (!text) {
+        const rows = await store.listMemory({ scopeKey, scope: "site", kind: "decision", status: "active", limit: 50 });
+        for (const row of rows.filter((r) => r.key === keyOf(section)))
+            await store.setMemoryStatus(row.id, "rejected");
+        return;
+    }
+    await store.putMemory({
+        scope: "site",
+        scopeKey,
+        kind: "decision",
+        key: keyOf(section),
+        value: text,
+        source: "user",
+        ...(by ? { sourceRef: `person:${by}` } : {}),
+        confidence: 1
+    });
+}
+const factLine = (fact) => (fact.key.startsWith("user:") ? `- ${fact.value}` : `- ${fact.key}: ${fact.value}`);
+/**
+ * The context block a run starts with, or "" when the site has none. Facts an
+ * agent recorded came from reading pages or connectors, so they are kept apart
+ * from what the owner stated, and labelled.
+ */
+export async function siteContextBlock(store, scopeKey) {
+    const [sections, facts] = await Promise.all([
+        readContextSections(store, scopeKey),
+        store.listMemory({ scopeKey, scope: "site", kind: [...SITE_FACT_KINDS], status: "active", limit: 100 })
+    ]);
+    const parts = [];
+    for (const section of CONTEXT_SECTIONS) {
+        if (sections[section])
+            parts.push(`${LABEL[section]}:\n${sections[section]}`);
+    }
+    const stated = facts.filter((fact) => fact.source === "user" || fact.source === "import");
+    const learned = facts.filter((fact) => fact.source !== "user" && fact.source !== "import");
+    if (stated.length)
+        parts.push(`Facts the owner gave:\n${stated.map(factLine).join("\n")}`);
+    if (learned.length)
+        parts.push(`Facts an agent recorded (not confirmed by the owner; check before relying on one):\n${learned.map(factLine).join("\n")}`);
+    if (parts.length === 0)
+        return "";
+    return `<site_context>\n${parts.join("\n\n").replaceAll("</site_context>", "</site_context_>")}\n</site_context>`;
+}

package/dist/agents/assistant/media-sink.d.ts

@@ -0,0 +1,12 @@
+export type MediaFile = {
+    filename: string;
+    contentType: string;
+    data: Uint8Array;
+};
+export type MediaSink = (file: MediaFile) => Promise<{
+    url: string;
+}>;
+export declare function setAssistantMediaSink(next: MediaSink | null): void;
+export declare function assistantMediaSink(): MediaSink | null;
+/** The file extension for an image type the site can serve, or null for anything else. */
+export declare function imageExtension(contentType: string): string | null;

package/dist/agents/assistant/media-sink.js

@@ -0,0 +1,19 @@
+let sink = null;
+export function setAssistantMediaSink(next) {
+    sink = next;
+}
+export function assistantMediaSink() {
+    return sink;
+}
+/** The file extension for an image type the site can serve, or null for anything else. */
+export function imageExtension(contentType) {
+    const map = {
+        "image/png": "png",
+        "image/jpeg": "jpg",
+        "image/webp": "webp",
+        "image/gif": "gif",
+        "image/avif": "avif"
+    };
+    // Not SVG: served from the orchestrator's own origin, an SVG can carry script.
+    return map[contentType.toLowerCase()] ?? null;
+}

package/dist/agents/assistant/next-steps.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeTool } from "../runtime/definition.ts";
+export declare const nextStepsTool: RuntimeTool;
+/** The chips from a run's trace lines: the last next_steps call's, or none. */
+export declare function nextStepsFrom(calls: Array<{
+    name: string;
+    result: string;
+}>): {
+    options: string[];
+    routine?: string;
+} | null;