@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/http/chat-stream-resumable.js

@@ -0,0 +1,290 @@
+// Resumable streaming chat: POST /chat/start → GET /chat/stream(?afterSeq) → POST /chat/cancel.
+//
+// Lives in core (transport-agnostic) so both the Fastify route and Web-handler
+// createOrchestrator() can use the same state machine. The Fastify route
+// (apps/orchestrator/src/routes/chat.ts) currently has its own copy of this
+// logic — it can be migrated to use this module when convenient; the existing
+// Fastify integration tests guard the contract.
+//
+// What lives here:
+//   - ResumableStreamStore: streamContexts map, sweep timer, allocate/cancel,
+//     buffered emit with seq numbers, subscriber set with broadcast
+//   - runResumableChatStream(): glues the store to runChatStream() plus the
+//     heartbeat + applying-idle timers that the Fastify route exercises
+//
+// What does NOT live here:
+//   - HTTP framing (SSE wire format, headers, status codes) — caller's job
+//   - The subscriber's transport. Callers pass a Subscriber interface; the
+//     Fastify route would back it with reply.raw, the Web handler with a
+//     ReadableStreamDefaultController.
+import { randomUUID } from "node:crypto";
+import { runChatStream } from "./chat-stream.js";
+const DEFAULTS = {
+    contextTtlMs: 60_000,
+    runTtlMs: 900_000,
+    maxEvents: 2000,
+    maxPendingPerSession: 3,
+    sweepIntervalMs: 60_000
+};
+export class ResumableStreamStore {
+    contexts = new Map();
+    opts;
+    sweepTimer = null;
+    constructor(options = {}) {
+        this.opts = { ...DEFAULTS, ...options };
+        if (this.opts.sweepIntervalMs > 0) {
+            this.sweepTimer = setInterval(() => this.sweepTerminal(), this.opts.sweepIntervalMs);
+            if (this.sweepTimer && typeof this.sweepTimer === "object" && "unref" in this.sweepTimer) {
+                this.sweepTimer.unref();
+            }
+        }
+    }
+    /** Stop the sweep timer. Call before process exit in tests. */
+    dispose() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+    }
+    get(streamId) {
+        return this.contexts.get(streamId);
+    }
+    countPendingForSession(session, siteId) {
+        let count = 0;
+        for (const entry of this.contexts.values()) {
+            if (entry.session === session && entry.siteId === siteId && (entry.state === "pending" || entry.state === "active")) {
+                count++;
+            }
+        }
+        return count;
+    }
+    findActiveForSession(session, siteId) {
+        for (const entry of this.contexts.values()) {
+            if (entry.session === session && entry.siteId === siteId && entry.state === "active")
+                return entry;
+        }
+        return null;
+    }
+    /** Allocate a new pending stream. Throws if session is over the pending cap. */
+    allocate(args) {
+        this.cleanExpiredPending();
+        if (this.countPendingForSession(args.session, args.siteId) >= this.opts.maxPendingPerSession) {
+            throw new TooManyPendingStreamsError(args.session, args.siteId);
+        }
+        const streamId = randomUUID();
+        const entry = {
+            streamId,
+            body: args.body,
+            session: args.session,
+            siteId: args.siteId,
+            origin: args.origin,
+            createdAt: Date.now(),
+            state: "pending",
+            abortController: new AbortController(),
+            events: [],
+            lastSeq: 0,
+            subscribers: new Set()
+        };
+        this.contexts.set(streamId, entry);
+        return entry;
+    }
+    markState(streamId, state) {
+        const entry = this.contexts.get(streamId);
+        if (entry)
+            entry.state = state;
+    }
+    /** Cancel by streamId, or by (session, siteId) for the active run on that session. */
+    cancel(by) {
+        let entry;
+        if (by.streamId)
+            entry = this.contexts.get(by.streamId);
+        else if (by.session !== undefined) {
+            const found = this.findActiveForSession(by.session, by.siteId ?? "");
+            if (found)
+                entry = found;
+        }
+        if (!entry)
+            return { status: "not_found" };
+        if (isTerminalState(entry.state))
+            return { status: "already_terminal", streamId: entry.streamId };
+        entry.state = "canceled";
+        entry.abortController.abort("user_canceled");
+        this.emit(entry.streamId, { type: "status", message: "Cancellation requested..." });
+        return { status: "canceled", streamId: entry.streamId };
+    }
+    /**
+     * Append an event to the buffer (with assigned seq number) and broadcast to
+     * all current subscribers. Returns the assigned seq, or -1 if streamId is
+     * unknown.
+     */
+    emit(streamId, event) {
+        const entry = this.contexts.get(streamId);
+        if (!entry)
+            return -1;
+        entry.lastSeq += 1;
+        const buffered = {
+            seq: entry.lastSeq,
+            event,
+            at: new Date().toISOString()
+        };
+        if (entry.events.length >= this.opts.maxEvents)
+            entry.events.shift();
+        entry.events.push(buffered);
+        const envelope = { ...event, _seq: entry.lastSeq };
+        for (const sub of entry.subscribers) {
+            try {
+                sub.emit(envelope);
+            }
+            catch { /* subscriber's transport may be closed */ }
+        }
+        return entry.lastSeq;
+    }
+    /** Subscribe and immediately replay any events with seq > afterSeq. Returns an unsubscribe fn. */
+    subscribe(streamId, sub, afterSeq = 0) {
+        const entry = this.contexts.get(streamId);
+        if (!entry)
+            return () => { };
+        for (const buffered of entry.events) {
+            if (buffered.seq > afterSeq) {
+                try {
+                    sub.emit({ ...buffered.event, _seq: buffered.seq });
+                }
+                catch { /* */ }
+            }
+        }
+        if (isTerminalState(entry.state)) {
+            try {
+                sub.close();
+            }
+            catch { /* */ }
+            return () => { };
+        }
+        entry.subscribers.add(sub);
+        return () => { entry.subscribers.delete(sub); };
+    }
+    /** Close all subscribers for a stream. Call when the run reaches a terminal state. */
+    closeAllSubscribers(streamId) {
+        const entry = this.contexts.get(streamId);
+        if (!entry)
+            return;
+        for (const sub of entry.subscribers) {
+            try {
+                sub.close();
+            }
+            catch { /* */ }
+        }
+        entry.subscribers.clear();
+    }
+    cleanExpiredPending() {
+        const now = Date.now();
+        for (const [id, entry] of this.contexts) {
+            if (entry.state === "pending" && now - entry.createdAt > this.opts.contextTtlMs) {
+                this.contexts.delete(id);
+            }
+        }
+    }
+    sweepTerminal() {
+        const now = Date.now();
+        for (const [id, entry] of this.contexts) {
+            if (now - entry.createdAt > this.opts.runTtlMs)
+                this.contexts.delete(id);
+        }
+    }
+}
+export function isTerminalState(state) {
+    return state === "done" || state === "error" || state === "canceled";
+}
+export class TooManyPendingStreamsError extends Error {
+    session;
+    siteId;
+    constructor(session, siteId) {
+        super(`too many pending streams for session=${session} siteId=${siteId}`);
+        this.session = session;
+        this.siteId = siteId;
+        this.name = "TooManyPendingStreamsError";
+    }
+}
+/**
+ * Drive `runChatStream` through a store entry. Transitions the entry's state
+ * (active → done/error/canceled), buffers events, manages heartbeat + idle
+ * timers, and closes subscribers on terminal. Returns the pipeline's HTTP code.
+ *
+ * Caller should have already called `store.markState(streamId, "active")` if
+ * the run was kicked off by a GET /chat/stream. (Done here as a safety net.)
+ */
+export async function runResumableChatStream(ctx, store, streamId, scopedBody, options = {}) {
+    const entry = store.get(streamId);
+    if (!entry)
+        return { code: 410 };
+    if (entry.state === "pending")
+        entry.state = "active";
+    const heartbeatMs = options.heartbeatIntervalMs ?? 1000;
+    const applyingIdleMs = options.applyingIdleMs ?? 1500;
+    const startedAt = Date.now();
+    let heartbeatStage = "planning";
+    let heartbeatLabel = "Planning";
+    let heartbeatTimer = null;
+    if (heartbeatMs > 0) {
+        heartbeatTimer = setInterval(() => {
+            store.emit(streamId, {
+                type: "heartbeat",
+                stage: heartbeatStage,
+                label: heartbeatLabel,
+                elapsedMs: Date.now() - startedAt
+            });
+        }, heartbeatMs);
+        if (heartbeatTimer && typeof heartbeatTimer === "object" && "unref" in heartbeatTimer) {
+            heartbeatTimer.unref();
+        }
+    }
+    let applyingIdleTimer = null;
+    const clearApplyingIdleTimer = () => {
+        if (applyingIdleTimer) {
+            clearTimeout(applyingIdleTimer);
+            applyingIdleTimer = null;
+        }
+    };
+    // Wrap the store's emit so we can observe specific events for label transitions.
+    const emit = (event) => {
+        if (event.type === "plan_meta") {
+            const n = event.estimatedOps ?? 0;
+            heartbeatLabel = n > 0 ? `Plan ready (${n} change${n === 1 ? "" : "s"})` : "Plan ready";
+        }
+        else if (event.type === "op_applied") {
+            heartbeatStage = "applying";
+            // Only show the (i/total) fraction for multi-op plans — "(1/1)" undersells a
+            // single op that rewrites many fields (e.g. a whole-section translate).
+            heartbeatLabel = event.total > 1
+                ? `Applying changes (${event.index}/${event.total})`
+                : "Applying changes";
+            clearApplyingIdleTimer();
+            if (applyingIdleMs > 0) {
+                applyingIdleTimer = setTimeout(() => {
+                    applyingIdleTimer = null;
+                    heartbeatLabel = "Wrapping up…";
+                    store.emit(streamId, { type: "status", message: heartbeatLabel });
+                }, applyingIdleMs);
+            }
+        }
+        else if (event.type === "status") {
+            heartbeatLabel = event.message;
+            clearApplyingIdleTimer();
+        }
+        store.emit(streamId, event);
+    };
+    try {
+        const result = await runChatStream(ctx, scopedBody, {
+            emit,
+            signal: entry.abortController.signal
+        });
+        const terminal = result.code >= 400 ? (result.code === 499 ? "canceled" : "error") : "done";
+        entry.state = terminal;
+        return { code: result.code };
+    }
+    finally {
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
+        clearApplyingIdleTimer();
+        store.closeAllSubscribers(streamId);
+    }
+}

package/dist/http/chat-stream.d.ts

@@ -0,0 +1,99 @@
+import { type ChatPipelineContext } from "../chat/chat-pipeline.ts";
+import type { ChatRequestBody } from "../nlp/intent-detection.ts";
+export type ChatStreamEvent = {
+    type: "token";
+    text: string;
+} | {
+    type: "thinking_start";
+} | {
+    type: "thinking_token";
+    text: string;
+} | {
+    type: "thinking_end";
+    durationMs: number;
+} | {
+    type: "field_draft";
+    blockId: string;
+    editablePath: string;
+    value: string;
+    pageSlug?: string;
+} | {
+    type: "summary_token";
+    text: string;
+} | {
+    type: "changelog_entry";
+    entry: string;
+} | {
+    type: "op_candidate";
+    index: number;
+    op: unknown;
+} | {
+    type: "op_skipped";
+    index: number;
+    total: number;
+    op: unknown;
+    reason: string;
+} | {
+    type: "plan_meta";
+    intent: unknown;
+    summary: string;
+    estimatedOps: number;
+} | {
+    type: "op_applied";
+    index: number;
+    total: number;
+    op: unknown;
+    previewVersion: number;
+    focusBlockId: string | null;
+    updatedSlug?: string;
+} | {
+    type: "rollback_started";
+    appliedCount: number;
+    reason: string;
+} | {
+    type: "rollback_done";
+    restoredVersion: number;
+} | {
+    type: "status";
+    message: string;
+} | {
+    type: "image_progress";
+    percent: number;
+    stage: string;
+} | {
+    type: "heartbeat";
+    stage: "planning" | "applying";
+    label: string;
+    elapsedMs: number;
+} | {
+    type: "final";
+    result: unknown;
+} | {
+    type: "error";
+    result: unknown;
+    code: number;
+} | {
+    type: "canceled";
+    message: string;
+};
+export type ChatStreamEmit = (event: ChatStreamEvent) => void;
+export interface RunChatStreamOptions {
+    emit: ChatStreamEmit;
+    signal?: AbortSignal;
+}
+/**
+ * Runs the planner pipeline and emits events through `emit`. Returns when the
+ * pipeline has produced its terminal event (final / error / canceled).
+ *
+ * The caller is responsible for scoping the session key already; we don't
+ * re-scope to keep the contract symmetric with `runChatPipeline`.
+ */
+export declare function runChatStream(ctx: ChatPipelineContext, body: ChatRequestBody, options: RunChatStreamOptions): Promise<{
+    code: number;
+}>;
+/**
+ * Format an event as a single SSE `data: …\n\n` frame. Most callers will use
+ * this — both the Fastify route and the Web-handler version of /chat/stream
+ * want the same wire format.
+ */
+export declare function formatSseFrame(event: ChatStreamEvent): string;

package/dist/http/chat-stream.js

@@ -0,0 +1,92 @@
+// Transport-agnostic streaming wrapper around `runChatPipeline`.
+//
+// The Fastify route at apps/orchestrator/src/routes/chat.ts and the Web-handler
+// `createOrchestrator()` in packages/site-sdk/src/server both call this helper.
+// It accepts a single `emit(type, payload)` sink instead of 10 `on*` callbacks,
+// runs the planner pipeline, and translates terminal outcomes (success / error
+// / cancel) into a final event.
+//
+// What this helper does NOT cover:
+//   - SSE wire format (callers encode events themselves: `data: ${json}\n\n`)
+//   - The resumable replay layer (streamContexts map, /chat/start triplet)
+//   - Heartbeat / idle timers — caller's responsibility, since those need a
+//     timer that survives the caller's transport lifecycle
+//
+// Why those are out of scope: they're transport-coupled (Fastify reply.raw vs
+// Web ReadableStream controller) and would force this helper to know about
+// timers + writable streams. Keeping it pure makes both call sites trivial.
+import { isCancelError, cleanupImagePlaceholders } from "../chat/chat-pipeline-shared.js";
+import { runChatPipeline } from "../chat/chat-pipeline.js";
+/**
+ * Runs the planner pipeline and emits events through `emit`. Returns when the
+ * pipeline has produced its terminal event (final / error / canceled).
+ *
+ * The caller is responsible for scoping the session key already; we don't
+ * re-scope to keep the contract symmetric with `runChatPipeline`.
+ */
+export async function runChatStream(ctx, body, options) {
+    const { emit, signal } = options;
+    try {
+        const result = await runChatPipeline(ctx, body, {
+            signal,
+            onPlanningToken: (token) => emit({ type: "token", text: token }),
+            onThinking: (event) => {
+                if (event.type === "start")
+                    emit({ type: "thinking_start" });
+                else if (event.type === "token")
+                    emit({ type: "thinking_token", text: event.text });
+                else if (event.type === "end")
+                    emit({ type: "thinking_end", durationMs: event.durationMs });
+            },
+            onFieldDraft: (event) => emit({
+                type: "field_draft",
+                blockId: event.blockId,
+                editablePath: event.editablePath,
+                value: event.value,
+                ...(event.pageSlug ? { pageSlug: event.pageSlug } : {})
+            }),
+            onSummaryChunk: (text) => emit({ type: "summary_token", text }),
+            onChangeLogEntry: (entry) => emit({ type: "changelog_entry", entry }),
+            onPlannedOp: (event) => emit({ type: "op_candidate", index: event.index, op: event.op }),
+            onOpSkipped: (event) => emit({ type: "op_skipped", index: event.index, total: event.total, op: event.op, reason: event.reason }),
+            onPlanMeta: (event) => emit({ type: "plan_meta", intent: event.intent, summary: event.summary, estimatedOps: event.estimatedOps }),
+            onOpApplied: (event) => emit({
+                type: "op_applied",
+                index: event.index,
+                total: event.total,
+                op: event.op,
+                previewVersion: event.previewVersion,
+                focusBlockId: event.focusBlockId ?? null,
+                ...(event.updatedSlug ? { updatedSlug: event.updatedSlug } : {})
+            }),
+            onRollbackStarted: (event) => emit({ type: "rollback_started", appliedCount: event.appliedCount, reason: event.reason }),
+            onRollbackDone: (event) => emit({ type: "rollback_done", restoredVersion: event.restoredVersion }),
+            onStatusUpdate: (message) => emit({ type: "status", message }),
+            onImageProgress: (event) => emit({ type: "image_progress", percent: event.percent, stage: event.stage })
+        });
+        if (result.code >= 400) {
+            emit({ type: "error", result: result.payload, code: result.code });
+            return { code: result.code };
+        }
+        emit({ type: "final", result: result.payload });
+        return { code: result.code };
+    }
+    catch (err) {
+        if (isCancelError(err)) {
+            cleanupImagePlaceholders(body.session ?? "dev");
+            emit({ type: "canceled", message: "Stopped this request." });
+            return { code: 499 };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        emit({ type: "error", result: { error: message }, code: 500 });
+        return { code: 500 };
+    }
+}
+/**
+ * Format an event as a single SSE `data: …\n\n` frame. Most callers will use
+ * this — both the Fastify route and the Web-handler version of /chat/stream
+ * want the same wire format.
+ */
+export function formatSseFrame(event) {
+    return `data: ${JSON.stringify(event)}\n\n`;
+}

package/dist/image/gdrive-client.d.ts

@@ -0,0 +1,22 @@
+import type { ImageLogger } from "./image-helpers.ts";
+export type GDriveImageItem = {
+    id: string;
+    name: string;
+    mimeType: string;
+    thumbnailLink: string;
+    size: number;
+    width?: number;
+    height?: number;
+};
+/** Reset cached client (useful after env changes or in tests). */
+export declare function resetDriveClient(): void;
+/** Convert a file name like "hero_image-v2.jpg" to alt text "hero image v2". */
+export declare function fileNameToAlt(name: string): string;
+export declare function isGdriveConfigured(): boolean;
+/** Resolve folder ID from an override or fall back to env var. Returns undefined if neither is set. */
+export declare function resolveGdriveFolderId(override?: string): string | undefined;
+export declare function listImages(folderId: string, query?: string, log?: ImageLogger, maxResults?: number, skipCache?: boolean): Promise<GDriveImageItem[]>;
+export declare function downloadImage(fileId: string, log?: ImageLogger): Promise<{
+    filePath: string;
+    fileName: string;
+} | null>;