@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/state/session-state.d.ts

@@ -0,0 +1,310 @@
+import type { Logger } from "../logger.ts";
+import { type EditPlan, type Operation, type PageDoc, type SiteConfig } from "@avocadostudio-ai/shared";
+import { toErrorDetail as _unifiedToErrorDetail } from "../errors.ts";
+import type { PublishLogEntry } from "./sqlite-store.ts";
+export type { PublishLogEntry, PublishLogStatus } from "./sqlite-store.ts";
+export declare const HISTORY_DEPTH_MAX = 50;
+export declare const VERSION_LOG_MAX = 100;
+export declare const CHAT_HISTORY_MAX_TURNS = 6;
+export declare const PUBLISH_LOG_MAX = 200;
+export type ModelKey = "fast" | "balanced" | "reasoning" | "codex";
+export type AIProvider = "openai" | "anthropic" | "gemini";
+export declare const DEFAULT_SITE_ID = "avocado-stories";
+export declare const DEFAULT_SESSION = "dev";
+export declare function normalizeSiteId(value: unknown): string;
+export declare function normalizeSession(value: unknown): string;
+/** Returns true for the default JSON-file site (avocado-stories). */
+export declare function isLegacySiteId(siteId: string): siteId is "avocado-stories" | "default";
+export declare function scopedSessionKey(session: unknown, siteId: unknown): string;
+export type PendingImageGeneration = {
+    blockId: string;
+    pageSlug: string;
+    path?: string;
+    altPath?: string;
+    query: string;
+    provider: "openai" | "unsplash" | "gdrive" | "auto";
+};
+export type PendingApprovalPlan = {
+    id: string;
+    createdAt: string;
+    promptHash: string;
+    requestedSlug: string;
+    effectiveSlug: string;
+    summary: string;
+    source: "openai" | "anthropic" | "gemini" | "demo";
+    modelUsed: string;
+    modelKey: ModelKey;
+    plan: EditPlan;
+    pendingImageOps?: PendingImageGeneration[];
+    originalMessage?: string;
+    /**
+     * Human-readable reasons from the tier-1 destructive-action gate. Present
+     * when the approval gate was triggered by destructive ops (as opposed to,
+     * say, pending image generation). The editor renders these in the approval
+     * card so the user knows exactly what the plan will delete.
+     */
+    destructiveReasons?: string[];
+};
+export type ContinuationChain = {
+    id: string;
+    steps: string[];
+    stepLabels: string[];
+    currentStep: number;
+    totalSteps: number;
+    originalMessage: string;
+    effectiveSlug: string;
+    siteContextBlock: string | null;
+};
+export declare const continuationChainBySession: Map<string, ContinuationChain>;
+export type PublishTracker = {
+    session: string;
+    status: "triggered" | "failed";
+    startedAt: string;
+    updatedAt: string;
+    slugs: string[];
+    deployStatus?: number;
+    deployResponse?: string;
+    inspectUrl?: string;
+    deploymentId?: string;
+    deploymentUrl?: string;
+    vercelState?: string;
+    lastCheckError?: string;
+};
+export type IssueTouchedEntry = {
+    slugs: string[];
+    updatedAt: string;
+};
+export type PersistedState = {
+    publishedPages: PageDoc[];
+    draftPages: Record<string, Record<string, PageDoc>>;
+    historyUndo: Record<string, Record<string, (PageDoc | null)[]>>;
+    historyRedo: Record<string, Record<string, (PageDoc | null)[]>>;
+    versions: Record<string, number>;
+    recentEdits: Record<string, Array<{
+        slug: string;
+        summary: string;
+        ops: Operation[];
+        at: string;
+    }>>;
+    chatHistory: Record<string, Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>>;
+    siteConfigs?: Record<string, SiteConfig>;
+    versionLog?: Record<string, VersionEntry[]>;
+    issueTouchedSlugs?: Record<string, IssueTouchedEntry>;
+    /**
+     * Persisted publish-log rows. Absent in legacy JSON state files (publish log
+     * was introduced after the JSON-to-SQLite migration), so the hydrate path is
+     * the only real source — this field exists for symmetry / future round-trip.
+     */
+    publishLog?: Record<string, PublishLogEntry[]>;
+};
+export declare const publishedPages: Map<string, PageDoc>;
+export declare const draftPages: Map<string, Map<string, PageDoc>>;
+export declare const historyUndo: Map<string, Map<string, (PageDoc | null)[]>>;
+export declare const historyRedo: Map<string, Map<string, (PageDoc | null)[]>>;
+export declare const versions: Map<string, number>;
+export declare const recentEdits: Map<string, {
+    slug: string;
+    summary: string;
+    ops: Operation[];
+    at: string;
+}[]>;
+export type VersionEntry = {
+    version: number;
+    slug: string;
+    summary: string;
+    opTypes: string[];
+    opCount: number;
+    at: string;
+    source: "chat" | "direct" | "undo" | "redo" | "bootstrap" | "restore";
+    /**
+     * Full snapshot of the page state at this version. Enables the version
+     * history panel to jump back and forth between any two versions directly,
+     * independent of the undo/redo stacks. `null` means the page did not exist
+     * at this version (e.g. before it was created, or after it was removed).
+     * Omit the field when capturing a snapshot is impossible (legacy entries).
+     */
+    snapshot?: PageDoc | null;
+};
+export declare const versionLog: Map<string, VersionEntry[]>;
+/**
+ * Per-session publish-log entries — one row per `POST /publish` attempt.
+ * Mirrors the SQLite `publish_log` table. Unlike most other state maps, this
+ * one is NOT included in `writeAllStateToStore`'s drop-and-reinsert pass:
+ * publish entries support async UPDATE (deploy resolves seconds later) and
+ * the SQLite row is the source of truth. Writes go straight through via
+ * `pushPublishLogEntry` / `updatePublishLogStatus`; this Map is a read cache.
+ */
+export declare const publishLogBySession: Map<string, PublishLogEntry[]>;
+/**
+ * Per-ticket slugs touched by an agent run. Survives the execute→publish
+ * invocation gap so the publish-mode comment can list exactly what this
+ * ticket changed, rather than every page in the shared session. Capped at
+ * ISSUE_TOUCHED_MAX entries (oldest dropped by updatedAt).
+ */
+export declare const issueTouchedSlugsByKey: Map<string, IssueTouchedEntry>;
+export declare function setIssueTouchedSlugs(issueKey: string, slugs: string[]): void;
+export declare function getIssueTouchedSlugs(issueKey: string): string[];
+export declare const pendingClarificationBySession: Map<string, {
+    baseRequest: string;
+    updatedAt: string;
+}>;
+export declare const chatHistoryBySession: Map<string, {
+    role: "user" | "assistant";
+    content: string;
+}[]>;
+export declare const pendingApprovalPlanBySession: Map<string, PendingApprovalPlan>;
+/**
+ * Per-session image-source preference ("unsplash" | "genai" | "either"), set when
+ * the user resolves a source-ambiguity clarification. Stops repeated prompting
+ * within the same session. Ephemeral (in-memory) only.
+ */
+export type ImageSourcePreference = "unsplash" | "genai" | "either";
+export declare const imageSourcePreferenceBySession: Map<string, ImageSourcePreference>;
+export declare const publishStatusBySession: Map<string, PublishTracker>;
+export declare const siteConfigs: Map<string, {
+    name?: string | undefined;
+    logo?: string | undefined;
+    purpose?: string | undefined;
+    tone?: string | undefined;
+    constraints?: string[] | undefined;
+    navLabels?: Record<string, string> | undefined;
+    navGroups?: Record<string, string[]> | undefined;
+    themeOverrides?: Record<string, string> | undefined;
+}>;
+export declare let lastPublishedScopedSession: string | undefined;
+export declare function setLastPublishedScopedSession(key: string): void;
+export type SessionSummary = {
+    /** Full key as stored in the in-memory maps (`{siteId}::{session}` or just `{session}` for the legacy site). */
+    sessionKey: string;
+    /** Session segment after the "::" separator. */
+    session: string;
+    /** Site segment before the "::" separator. Falls back to DEFAULT_SITE_ID for legacy bare-session keys. */
+    siteId: string;
+    /** Monotonic preview version (post-mutation counter). 0 when nothing has been written. */
+    version: number;
+    /** Distinct page count in the draft map. Reads existing state without auto-seeding. */
+    draftPageCount: number;
+    /** ISO timestamp of the most recent versionLog entry, or null if none. */
+    lastMutatedAt: string | null;
+};
+export declare function getSessionSummary(sessionKey: string): SessionSummary;
+export declare function listSessionSummaries(): SessionSummary[];
+/** Total published pages across all sites (currently just the JSON-file legacy site). */
+export declare function publishedPageCountGlobal(): number;
+export declare function markRecentlyRestored(session: string): void;
+export declare function consumeRecentlyRestored(session: string): boolean;
+export declare const toErrorDetail: typeof _unifiedToErrorDetail;
+export declare function ensureHeroImageProps(page: PageDoc): void;
+export declare function orderSlugsHomeFirst(slugs: string[]): string[];
+/**
+ * Monorepo-only: backfill the in-memory siteConfig from the bundled
+ * apps/site/lib/published-content.json on first session touch.
+ *
+ * Why: the orch's draft siteConfig can drift narrower than what's actually
+ * published (e.g. SQLite outage loses a session's nav state, or a fresh boot
+ * of an already-published site has nothing in SQLite). Without this fill-in,
+ * the next publish silently wipes nav fields the live site still depends on.
+ *
+ * SDK consumers wire `getSiteConfig` into `createEditorApiHandler` and the
+ * orchestrator picks the live state up through `/publish/diff`'s
+ * loadPublishedForDiff path; this helper is only for the bundled apps/site.
+ *
+ * Exported for tests; production callers omit `publishedPathOverride`.
+ */
+export declare function hydrateSiteConfigFromPublished(session: string, publishedPathOverride?: string): void;
+export declare function getSessionDraft(session: string): Map<string, PageDoc>;
+export declare function getHistoryMap(store: Map<string, Map<string, (PageDoc | null)[]>>, session: string): Map<string, (PageDoc | null)[]>;
+export declare function getPage(session: string, slug: string): PageDoc | null;
+export declare function getSessionPages(session: string): PageDoc[];
+export declare function getContextCache(session: string): {
+    version: number;
+    pageDirectory?: string;
+} | undefined;
+export declare function setContextCache(session: string, entry: {
+    version: number;
+    pageDirectory?: string;
+}): void;
+export declare function setPage(session: string, page: PageDoc): void;
+export declare function removePage(session: string, slug: string): void;
+/**
+ * Append `snapshot` to an undo/redo stack, evicting the oldest entries
+ * once `HISTORY_DEPTH_MAX` is exceeded. Mutates `list` in place.
+ */
+export declare function pushCappedHistory(list: (PageDoc | null)[], snapshot: PageDoc | null): void;
+export declare function pushUndo(session: string, slug: string, snapshot: PageDoc | null): void;
+export declare function bumpVersion(session: string): number;
+export declare function pushRecentEdit(session: string, entry: {
+    slug: string;
+    summary: string;
+    ops: Operation[];
+}): void;
+export declare function pushVersionEntry(session: string, entry: Omit<VersionEntry, "at">): void;
+export declare function getVersionLog(session: string, slug?: string, limit?: number): VersionEntry[];
+/**
+ * Insert a publish-log row. Writes through to SQLite immediately so the row
+ * survives a process restart between the initial publish and the later async
+ * status update (deploy resolution can take seconds to minutes). Also mirrors
+ * into `publishLogBySession` for cheap reads.
+ *
+ * The `id` field is generated here (UUID) so callers don't need to import
+ * crypto. Returns the full materialised entry, including `id` / timestamps.
+ */
+export declare function pushPublishLogEntry(partial: Omit<PublishLogEntry, "id" | "at" | "updatedAt">): PublishLogEntry;
+/**
+ * Patch an existing publish-log row by `id`. Updates SQLite and the in-memory
+ * mirror. Used by `GET /publish/status` to transition `triggered` → `success`
+ * or `failed` when Vercel resolves. Returns the updated entry, or null if the
+ * id was not found.
+ */
+export declare function updatePublishLogStatusById(id: string, patch: Partial<Omit<PublishLogEntry, "id" | "session" | "at">>): PublishLogEntry | null;
+/**
+ * Resolve a publish-log row to update when an async deploy status arrives.
+ * Prefers an exact `deploymentId` match; falls back to the most recent
+ * `triggered` row for the session (covers deploy-hook targets that don't
+ * parse a deployment id out of their response).
+ */
+export declare function findPublishLogForStatusUpdate(session: string, deploymentId: string | undefined): PublishLogEntry | null;
+export declare function listPublishLog(session: string, limit?: number): PublishLogEntry[];
+export declare function pushChatHistory(session: string, userMessage: string, assistantSummary: string): void;
+export declare function getRecentEdits(session: string, slug: string): {
+    at: string;
+    summary: string;
+    ops: ("update_props" | "create_page" | "add_block" | "remove_block" | "move_block" | "duplicate_block" | "add_item" | "update_item" | "remove_item" | "move_item" | "reorder_items" | "reorder_blocks" | "rename_page" | "remove_page" | "move_page" | "duplicate_page" | "update_page_meta" | "update_site_config" | "update_theme")[];
+}[];
+export declare function getSiteConfig(session: string): SiteConfig;
+export declare function setSiteConfig(session: string, config: SiteConfig): void;
+/**
+ * Walk the in-memory `siteConfigs` map and return one entry per unique siteId,
+ * preferring entries that match `wantedSession` over legacy unscoped ones.
+ *
+ * The map keys come from `scopedSessionKey()`: either `{siteId}::{session}` or
+ * just `{session}` for legacy sites (avocado-stories convention). Owning that
+ * parsing here keeps route handlers from having to know about the key format.
+ */
+export declare function listSitesForSession(wantedSession: string): Array<SiteConfig & {
+    id: string;
+}>;
+export declare function nestedPageMapToObject(source: Map<string, Map<string, PageDoc>>): Record<string, Record<string, PageDoc>>;
+export declare function nestedHistoryMapToObject(source: Map<string, Map<string, (PageDoc | null)[]>>): Record<string, Record<string, (PageDoc | null)[]>>;
+export declare function objectToNestedPageMap(source: unknown): Map<string, Map<string, PageDoc>>;
+export declare function objectToNestedHistoryMap(source: unknown): Map<string, Map<string, (PageDoc | null)[]>>;
+export declare function applyPersistedState(parsed: Partial<PersistedState>): void;
+/**
+ * Persist the current in-memory state to SQLite. Always flushes any pending
+ * debounced write first, then runs synchronously (better-sqlite3 is sync).
+ * Async signature preserved for callers that want to `await` (publish flow
+ * does). Errors are logged and rethrown.
+ */
+export declare function persistStateNow(logger: Logger): Promise<void>;
+export declare function schedulePersistState(logger: Logger): void;
+/**
+ * Evict stale/excess entries from ephemeral in-memory maps.
+ * Called on a periodic timer (see index.ts). Safe to call at any time.
+ */
+export declare function evictStaleEphemeralMaps(): void;
+export declare function loadStateFromDisk(logger: Logger): Promise<void>;
+export type { ContentSource } from "./content-source.ts";
+export { InMemoryContentSource } from "./in-memory-content-source.ts";