@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/demo-mode.js

@@ -0,0 +1,201 @@
+// ---------------------------------------------------------------------------
+// Demo mode — single-feature playground gated on a shared API key
+// ---------------------------------------------------------------------------
+//
+// When DEMO_MODE=1 is set, the orchestrator becomes a "try it before you
+// sign up" playground: the hosting team's OPENAI_API_KEY / ANTHROPIC_API_KEY
+// powers the planner, but everything is locked down so casual users can't
+// drain it. The only operation permitted is `update_props` on a Hero block.
+// Everything else (add/remove/move blocks, editing other blocks, agent
+// routes, image generation) returns a friendly rejection.
+//
+// Design choices:
+// - SERVER-ENFORCED: client-trusted `siteCapabilities` flags aren't enough;
+//   a curl request could bypass them. We enforce in `applyOpsAtomically`
+//   and via a Fastify preHandler hook.
+// - PER-IP ISOLATION: each demo visitor gets their own ephemeral session
+//   key `demo-<hash>` seeded from `demoPublishedPages()`. No persistence —
+//   state resets on server restart. Avoids visitors stomping on each other.
+// - RATE LIMITING: simple in-memory token bucket per IP. Default 20 req/hr.
+// - NO IMAGES: detectImageOps is short-circuited in demo mode so DALL-E /
+//   Unsplash calls can't be triggered. Text-only edits keep latency low
+//   and costs bounded.
+import { createHash } from "node:crypto";
+import { OperationError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Config — read once at module load, memoized
+// ---------------------------------------------------------------------------
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+function envFlag(name, fallback = false) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return fallback;
+    return TRUE_VALUES.has(raw.trim().toLowerCase());
+}
+function envList(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+    return parts.length > 0 ? parts : fallback;
+}
+function envNumber(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Is demo mode enabled for this orchestrator process? */
+export function isDemoModeEnabled() {
+    return envFlag("DEMO_MODE", false);
+}
+/** Operation types allowed in demo mode. Defaults to ["update_props"]. */
+export function getDemoAllowedOpTypes() {
+    return envList("DEMO_ALLOWED_OPS", ["update_props"]);
+}
+/** Block types on which update_props is allowed. Defaults to ["Hero"]. */
+export function getDemoAllowedBlockTypes() {
+    return envList("DEMO_ALLOWED_BLOCK_TYPES", ["Hero"]);
+}
+/** Max requests per IP per hour. Defaults to 20. */
+export function getDemoRateLimitPerHour() {
+    return envNumber("DEMO_RATE_LIMIT_PER_IP_PER_HOUR", 20);
+}
+/** Should image generation be disabled in demo mode? Defaults to true. */
+export function isDemoImageGenDisabled() {
+    return envFlag("DEMO_DISABLE_IMAGE_GEN", true);
+}
+// ---------------------------------------------------------------------------
+// Per-IP session key
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic ephemeral session key for a demo visitor.
+ *
+ * We hash the IP to avoid leaking it, and keep the key short enough to read
+ * in logs. The key does NOT contain "::" so it routes through the default
+ * `getSessionDraft` path which auto-seeds from `demoPublishedPages()`.
+ */
+export function demoSessionKeyForIp(ip) {
+    const normalized = (ip || "anon").trim() || "anon";
+    const hash = createHash("sha1").update(normalized).digest("hex").slice(0, 10);
+    return `demo-${hash}`;
+}
+/**
+ * Extract a client IP from a Fastify request. Render puts the real client IP
+ * in `x-forwarded-for` (first entry). Falls back to request.ip.
+ */
+export function extractClientIp(request) {
+    const xff = request.headers["x-forwarded-for"];
+    const header = Array.isArray(xff) ? xff[0] : xff;
+    if (typeof header === "string" && header.length > 0) {
+        const first = header.split(",")[0]?.trim();
+        if (first)
+            return first;
+    }
+    return request.ip ?? "anon";
+}
+/**
+ * Look up a block by id across all staged pages. Returns its `type` string,
+ * or undefined if the block wasn't found.
+ */
+function findBlockTypeInStaged(staged, blockId) {
+    for (const page of staged.values()) {
+        for (const block of page.blocks) {
+            if (block.id === blockId)
+                return block.type;
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate a list of operations against demo-mode rules. Returns the split
+ * between allowed and rejected ops; caller decides whether to proceed with
+ * the allowed subset or to throw.
+ */
+export function splitDemoOps(ops, staged) {
+    const allowedTypes = new Set(getDemoAllowedOpTypes());
+    const allowedBlockTypes = new Set(getDemoAllowedBlockTypes());
+    const allowed = [];
+    const rejected = [];
+    for (const op of ops) {
+        if (!allowedTypes.has(op.op)) {
+            rejected.push({
+                op,
+                reason: `Operation type "${op.op}" is not available in the demo. Allowed: ${[...allowedTypes].join(", ")}.`
+            });
+            continue;
+        }
+        // `update_props` is the only op type we currently allow, so we only need
+        // to special-case that. When the allow-list is widened, add branches here.
+        if (op.op === "update_props") {
+            const blockType = findBlockTypeInStaged(staged, op.blockId);
+            if (!blockType) {
+                rejected.push({
+                    op,
+                    reason: `Block "${op.blockId}" was not found in the current draft.`
+                });
+                continue;
+            }
+            if (!allowedBlockTypes.has(blockType)) {
+                rejected.push({
+                    op,
+                    reason: `Editing "${blockType}" blocks is disabled in the demo. Only ${[...allowedBlockTypes].join(" / ")} edits are available — try changing the hero headline.`
+                });
+                continue;
+            }
+            allowed.push(op);
+            continue;
+        }
+        // Belt-and-suspenders: if an op type slipped past allowedTypes but isn't
+        // update_props, refuse it explicitly.
+        rejected.push({
+            op,
+            reason: `Operation "${op.op}" is not permitted in the demo.`
+        });
+    }
+    return { allowed, rejected };
+}
+/**
+ * Throws an `OperationError` if any of the given ops violates demo-mode
+ * rules. Used as the final gate inside `applyOpsAtomically`, so both chat
+ * and direct `/ops` paths are covered.
+ */
+export function enforceDemoOps(ops, staged) {
+    const { rejected } = splitDemoOps(ops, staged);
+    if (rejected.length === 0)
+        return;
+    const firstReason = rejected[0]?.reason ?? "Operation not permitted in demo mode.";
+    throw new OperationError(`Demo mode: ${firstReason}`, {
+        category: "planner_refusal",
+        retryable: false,
+        userMessage: "This demo only supports editing the hero section. Try: \"change the hero headline to Welcome to my new site\"."
+    });
+}
+const WINDOW_MS = 60 * 60 * 1000; // 1 hour
+const rateBuckets = new Map();
+/**
+ * Consume one token for the given IP. Returns `{ ok: true }` if allowed,
+ * or `{ ok: false, retryAfterSeconds }` if the quota for the current
+ * hourly window is exhausted.
+ */
+export function consumeDemoRateToken(ip) {
+    const now = Date.now();
+    const limit = getDemoRateLimitPerHour();
+    const key = ip || "anon";
+    const bucket = rateBuckets.get(key);
+    if (!bucket || now - bucket.windowStart >= WINDOW_MS) {
+        rateBuckets.set(key, { count: 1, windowStart: now });
+        return { ok: true };
+    }
+    if (bucket.count >= limit) {
+        const retryAfterMs = WINDOW_MS - (now - bucket.windowStart);
+        return { ok: false, retryAfterSeconds: Math.max(1, Math.ceil(retryAfterMs / 1000)) };
+    }
+    bucket.count += 1;
+    return { ok: true };
+}
+/** Reset the rate limiter (test hook). */
+export function _resetDemoRateLimiterForTests() {
+    rateBuckets.clear();
+}

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Combined error category covering guardrails, planner failures, and
+ * operational validation. Superset of the former `GuardrailErrorCategory`
+ * and `PlannerFailureReasonCategory` types.
+ */
+export type ErrorCategory = "schema_violation" | "ambiguity" | "not_found" | "no_effective_change" | "planner_refusal" | "incomplete_output" | "malformed_output" | "internal_error" | "canceled" | "operation_failed";
+export type GuardrailErrorCategory = ErrorCategory;
+export type PlannerFailureReasonCategory = Extract<ErrorCategory, "schema_violation" | "planner_refusal" | "incomplete_output" | "malformed_output" | "internal_error">;
+/**
+ * Base error for all orchestrator-layer failures.
+ * Carries a machine-readable `category`, a flag indicating whether the
+ * caller may retry, and a human-friendly `userMessage`.
+ */
+export declare class OrchestrationError extends Error {
+    readonly category: ErrorCategory;
+    readonly retryable: boolean;
+    readonly userMessage: string;
+    constructor(message: string, options: {
+        category: ErrorCategory;
+        retryable?: boolean;
+        userMessage?: string;
+    });
+}
+/** Raised when the AI planner produces invalid / refused / incomplete output. */
+export declare class PlannerError extends OrchestrationError {
+    /** Alias kept for call-sites that read `.reasonCategory`. */
+    get reasonCategory(): PlannerFailureReasonCategory;
+    constructor(message: string, options: {
+        reasonCategory: PlannerFailureReasonCategory;
+        retryable?: boolean;
+        userMessage?: string;
+    });
+}
+/** Raised when input fails a guardrail check before reaching the planner. */
+export declare class GuardrailError extends OrchestrationError {
+    constructor(message: string, options: {
+        category: GuardrailErrorCategory;
+        retryable?: boolean;
+        userMessage?: string;
+    });
+}
+/** Raised when an operation (add_block, update_props, …) fails during apply. */
+export declare class OperationError extends OrchestrationError {
+    constructor(message: string, options?: {
+        category?: ErrorCategory;
+        retryable?: boolean;
+        userMessage?: string;
+    });
+}
+/** Raised when the user (or an abort signal) cancels an in-flight request. */
+export declare class CancelError extends OrchestrationError {
+    constructor(reason?: string);
+}
+export declare function isOrchestrationError(error: unknown): error is OrchestrationError;
+export declare function isPlannerError(error: unknown): error is PlannerError;
+/** @deprecated Use `isPlannerError` instead. Kept for backward compatibility. */
+export declare function isPlannerOutputError(error: unknown): error is PlannerError;
+export declare function isGuardrailError(error: unknown): error is GuardrailError;
+export declare function isOperationError(error: unknown): error is OperationError;
+export declare function isCancelError(error: unknown): error is CancelError;
+/**
+ * Extract a human-readable error string from any thrown value.
+ * Handles `Error`, Zod-like `{ issues }` objects, and plain strings.
+ */
+export declare function toErrorDetail(error: unknown): string;
+/** @deprecated Use `PlannerError` directly. */
+export declare const PlannerOutputError: typeof PlannerError;

package/dist/errors.js

@@ -0,0 +1,129 @@
+// ---------------------------------------------------------------------------
+// Unified error hierarchy for the orchestrator
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Base class
+// ---------------------------------------------------------------------------
+/**
+ * Base error for all orchestrator-layer failures.
+ * Carries a machine-readable `category`, a flag indicating whether the
+ * caller may retry, and a human-friendly `userMessage`.
+ */
+export class OrchestrationError extends Error {
+    category;
+    retryable;
+    userMessage;
+    constructor(message, options) {
+        super(message);
+        this.name = "OrchestrationError";
+        this.category = options.category;
+        this.retryable = options.retryable ?? false;
+        this.userMessage = options.userMessage ?? message;
+    }
+}
+// ---------------------------------------------------------------------------
+// Subclasses
+// ---------------------------------------------------------------------------
+/** Raised when the AI planner produces invalid / refused / incomplete output. */
+export class PlannerError extends OrchestrationError {
+    /** Alias kept for call-sites that read `.reasonCategory`. */
+    get reasonCategory() {
+        return this.category;
+    }
+    constructor(message, options) {
+        super(message, {
+            category: options.reasonCategory,
+            retryable: options.retryable,
+            userMessage: options.userMessage
+        });
+        this.name = "PlannerError";
+    }
+}
+/** Raised when input fails a guardrail check before reaching the planner. */
+export class GuardrailError extends OrchestrationError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "GuardrailError";
+    }
+}
+/** Raised when an operation (add_block, update_props, …) fails during apply. */
+export class OperationError extends OrchestrationError {
+    constructor(message, options) {
+        super(message, {
+            category: options?.category ?? "operation_failed",
+            retryable: options?.retryable ?? false,
+            userMessage: options?.userMessage
+        });
+        this.name = "OperationError";
+    }
+}
+/** Raised when the user (or an abort signal) cancels an in-flight request. */
+export class CancelError extends OrchestrationError {
+    constructor(reason) {
+        super(reason ?? "user_canceled", {
+            category: "canceled",
+            retryable: false,
+            userMessage: "Stopped this request."
+        });
+        this.name = "CancelError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+export function isOrchestrationError(error) {
+    return error instanceof OrchestrationError;
+}
+export function isPlannerError(error) {
+    return error instanceof PlannerError;
+}
+/** @deprecated Use `isPlannerError` instead. Kept for backward compatibility. */
+export function isPlannerOutputError(error) {
+    return isPlannerError(error);
+}
+export function isGuardrailError(error) {
+    return error instanceof GuardrailError;
+}
+export function isOperationError(error) {
+    return error instanceof OperationError;
+}
+export function isCancelError(error) {
+    return error instanceof CancelError;
+}
+// ---------------------------------------------------------------------------
+// Unified toErrorDetail — single source of truth
+// ---------------------------------------------------------------------------
+/**
+ * Extract a human-readable error string from any thrown value.
+ * Handles `Error`, Zod-like `{ issues }` objects, and plain strings.
+ */
+export function toErrorDetail(error) {
+    if (error instanceof OrchestrationError)
+        return error.userMessage;
+    if (error instanceof Error) {
+        // Try to extract a Zod-style message embedded in the error string
+        const issueMatch = /"message"\s*:\s*"([^"]+)"/.exec(error.message);
+        if (issueMatch?.[1])
+            return issueMatch[1];
+        return error.message;
+    }
+    if (error &&
+        typeof error === "object" &&
+        "issues" in error &&
+        Array.isArray(error.issues)) {
+        const first = error.issues[0];
+        if (first) {
+            const msg = typeof first.message === "string" ? first.message : "Invalid model output";
+            const path = Array.isArray(first.path) && first.path.length > 0 ? ` at ${first.path.join(".")}` : "";
+            return `${msg}${path}`;
+        }
+    }
+    if (typeof error === "string")
+        return error;
+    return "Unknown planner error";
+}
+// ---------------------------------------------------------------------------
+// Backward-compatible aliases
+// ---------------------------------------------------------------------------
+/** @deprecated Use `PlannerError` directly. */
+export const PlannerOutputError = PlannerError;

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

@@ -0,0 +1,108 @@
+import type { ChatPipelineContext } from "../chat/chat-pipeline.ts";
+import type { ChatRequestBody } from "../nlp/intent-detection.ts";
+import { type ChatStreamEvent } from "./chat-stream.ts";
+export type StreamState = "pending" | "active" | "done" | "error" | "canceled";
+export type SeqEnvelope = ChatStreamEvent & {
+    _seq: number;
+};
+export interface BufferedEvent {
+    seq: number;
+    event: ChatStreamEvent;
+    at: string;
+}
+export interface Subscriber {
+    emit(envelope: SeqEnvelope): void;
+    close(): void;
+}
+export interface StreamEntry {
+    streamId: string;
+    body: ChatRequestBody;
+    session: string;
+    siteId: string;
+    origin: string;
+    createdAt: number;
+    state: StreamState;
+    abortController: AbortController;
+    events: BufferedEvent[];
+    lastSeq: number;
+    subscribers: Set<Subscriber>;
+}
+export interface ResumableStreamStoreOptions {
+    /** TTL for pending streams that never got a /chat/stream connection (default 60s). */
+    contextTtlMs?: number;
+    /** TTL for terminal runs (kept around so a reconnect can still replay; default 15 min). */
+    runTtlMs?: number;
+    /** Ring-buffer cap for buffered events (default 2000). */
+    maxEvents?: number;
+    /** Max simultaneously pending+active streams per session (default 3). */
+    maxPendingPerSession?: number;
+    /** Sweep interval for the cleanup timer (default 60s). 0 disables the timer. */
+    sweepIntervalMs?: number;
+}
+export declare class ResumableStreamStore {
+    private readonly contexts;
+    private readonly opts;
+    private sweepTimer;
+    constructor(options?: ResumableStreamStoreOptions);
+    /** Stop the sweep timer. Call before process exit in tests. */
+    dispose(): void;
+    get(streamId: string): StreamEntry | undefined;
+    countPendingForSession(session: string, siteId: string): number;
+    findActiveForSession(session: string, siteId: string): StreamEntry | null;
+    /** Allocate a new pending stream. Throws if session is over the pending cap. */
+    allocate(args: {
+        body: ChatRequestBody;
+        session: string;
+        siteId: string;
+        origin: string;
+    }): StreamEntry;
+    markState(streamId: string, state: StreamState): void;
+    /** Cancel by streamId, or by (session, siteId) for the active run on that session. */
+    cancel(by: {
+        streamId?: string;
+        session?: string;
+        siteId?: string;
+    }): {
+        status: "canceled" | "already_terminal" | "not_found";
+        streamId?: string;
+    };
+    /**
+     * 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: string, event: ChatStreamEvent): number;
+    /** Subscribe and immediately replay any events with seq > afterSeq. Returns an unsubscribe fn. */
+    subscribe(streamId: string, sub: Subscriber, afterSeq?: number): () => void;
+    /** Close all subscribers for a stream. Call when the run reaches a terminal state. */
+    closeAllSubscribers(streamId: string): void;
+    private cleanExpiredPending;
+    private sweepTerminal;
+}
+export declare function isTerminalState(state: StreamState): boolean;
+export declare class TooManyPendingStreamsError extends Error {
+    readonly session: string;
+    readonly siteId: string;
+    constructor(session: string, siteId: string);
+}
+export interface RunResumableChatStreamOptions {
+    /** Heartbeat interval (default 1000 ms). 0 disables. */
+    heartbeatIntervalMs?: number;
+    /**
+     * When the last emitted event is "op_applied" and no new event arrives within
+     * this window, switch the heartbeat label to "Wrapping up…". Set 0 to disable.
+     * Default 1500 ms — matches the Fastify route.
+     */
+    applyingIdleMs?: number;
+}
+/**
+ * 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 declare function runResumableChatStream(ctx: ChatPipelineContext, store: ResumableStreamStore, streamId: string, scopedBody: ChatRequestBody, options?: RunResumableChatStreamOptions): Promise<{
+    code: number;
+}>;