@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/nlp/intent-detection.d.ts

@@ -0,0 +1,309 @@
+import { z } from "zod";
+import { type BlockType, type EditPlan, type PageDoc, type PublishDiff, type Operation } from "@avocadostudio-ai/shared";
+import { type ModelKey } from "../state/session-state.ts";
+import { type GuardrailErrorCategory } from "../errors.ts";
+export type { GuardrailErrorCategory };
+export declare const siteCapabilitiesSchema: z.ZodObject<{
+    allowStructuralEdits: z.ZodBoolean;
+    manifestStatus: z.ZodEnum<{
+        loading: "loading";
+        ready: "ready";
+        degraded: "degraded";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+    manifestVersion: z.ZodOptional<z.ZodNumber>;
+    blockCount: z.ZodOptional<z.ZodNumber>;
+    checkedAt: z.ZodString;
+}, z.core.$strip>;
+export type SiteCapabilities = z.infer<typeof siteCapabilitiesSchema>;
+export declare const chatAttachmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        image: "image";
+        pdf: "pdf";
+    }>;
+    url: z.ZodString;
+    mimeType: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    bytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ChatAttachment = z.infer<typeof chatAttachmentSchema>;
+export declare const chatRequestBodySchema: z.ZodObject<{
+    session: z.ZodOptional<z.ZodString>;
+    siteId: z.ZodOptional<z.ZodString>;
+    componentsManifest: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    siteCapabilities: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        allowStructuralEdits: z.ZodBoolean;
+        manifestStatus: z.ZodEnum<{
+            loading: "loading";
+            ready: "ready";
+            degraded: "degraded";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+        manifestVersion: z.ZodOptional<z.ZodNumber>;
+        blockCount: z.ZodOptional<z.ZodNumber>;
+        checkedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodString]>>;
+    sitePurpose: z.ZodOptional<z.ZodString>;
+    siteHosting: z.ZodOptional<z.ZodString>;
+    businessContext: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        purpose: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodString>;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodString]>>;
+    siteContext: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        siteId: z.ZodOptional<z.ZodString>;
+        siteName: z.ZodOptional<z.ZodString>;
+        purpose: z.ZodOptional<z.ZodString>;
+        hosting: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodString>;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        gdriveFolderId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodString]>>;
+    locale: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    modelKey: z.ZodOptional<z.ZodEnum<{
+        fast: "fast";
+        balanced: "balanced";
+        reasoning: "reasoning";
+        codex: "codex";
+    }>>;
+    provider: z.ZodOptional<z.ZodEnum<{
+        openai: "openai";
+        anthropic: "anthropic";
+        gemini: "gemini";
+    }>>;
+    activeBlockId: z.ZodOptional<z.ZodString>;
+    activeBlockType: z.ZodOptional<z.ZodString>;
+    activeEditablePath: z.ZodOptional<z.ZodString>;
+    executionMode: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        plan_only: "plan_only";
+        apply_pending_plan: "apply_pending_plan";
+        discard_pending_plan: "discard_pending_plan";
+        continue_chain: "continue_chain";
+    }>>;
+    pendingPlanId: z.ZodOptional<z.ZodString>;
+    continuationChainId: z.ZodOptional<z.ZodString>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            image: "image";
+            pdf: "pdf";
+        }>;
+        url: z.ZodString;
+        mimeType: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        bytes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ChatRequestBody = z.infer<typeof chatRequestBodySchema>;
+/** Per-op outcome surfaced to the editor for the plan-preview card. Mirrors the engine's OpResult. */
+export type PlanOpResult = {
+    index: number;
+    op: Operation["op"];
+    status: "applied" | "skipped" | "failed";
+    reason?: string;
+    category?: string;
+};
+export type ChatResult = {
+    status: string;
+    summary: string;
+    changes: string[];
+    mentionedSlugs?: string[];
+    suggestions?: string[];
+    validationErrors?: unknown;
+    previewVersion: number;
+    focusBlockId?: string;
+    updatedSlug?: string;
+    undoSlug?: string;
+    plannerSource: "openai" | "anthropic" | "gemini" | "demo";
+    modelUsed: string;
+    modelKey: ModelKey;
+    pendingPlanId?: string;
+    /**
+     * True when a "make a plan first" request was applied to the draft as a
+     * revertible soft draft (status "applied"). The editor renders an inline
+     * Keep / Revert affordance instead of the held Apply / Discard card; Revert is
+     * a one-step undo on `undoSlug`. Nothing is published — it stays a draft.
+     */
+    planApplied?: boolean;
+    /**
+     * Structured before→after preview of a held plan (plan_ready), computed by a
+     * dry-run of the plan's ops. Powers the diff rendered in the approval card so
+     * the user sees exactly what will change before confirming — not just the
+     * change_log text. `planPreview.opResults` says which ops will apply / skip /
+     * fail; `planPreview.diff` is the same PublishDiff shape used by publish review.
+     */
+    planPreview?: {
+        opResults: PlanOpResult[];
+        diff: PublishDiff;
+        appliedCount: number;
+        skippedCount: number;
+        failedCount: number;
+    };
+    /**
+     * Tier-1 destructive-action reasons, surfaced when the approval gate was
+     * triggered because the plan contains destructive ops (remove_page with
+     * content, multi-page scope, bulk deletes). Rendered as a warning in the
+     * approval card so the user sees what will be deleted before confirming.
+     */
+    destructiveReasons?: string[];
+    continuation?: {
+        chainId: string;
+        currentStep: number;
+        totalSteps: number;
+        nextStepLabel: string;
+    };
+    debug?: {
+        traceId: string;
+        promptHash: string;
+        promptExcerpt: string;
+        outcome?: string;
+        reasonCategory?: GuardrailErrorCategory;
+        reason?: string;
+        intent?: EditPlan["intent"];
+        opTypes?: string[];
+        opCount?: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+        estimatedUsd?: number | null;
+        plannerTier?: "forced_deterministic" | "deterministic" | "llm_intent_router" | "full_llm" | "demo";
+        modelUsed?: string;
+        plannerSource?: "openai" | "anthropic" | "gemini" | "demo";
+        planningAttempts?: number;
+        executionMode?: string;
+        skippedOpCount?: number;
+        skippedOps?: Array<{
+            index: number;
+            op: string;
+            reason: "empty_patch" | "unchanged_value";
+            pageSlug?: string;
+            blockId?: string;
+        }>;
+        timeline?: Array<{
+            stage: "request_received" | "first_token" | "first_structured_progress" | "plan_ready" | "first_op_applied" | "done";
+            atMs: number;
+        }>;
+        currentPage?: string;
+        siteId?: string;
+        activeBlockId?: string;
+        activeEditablePath?: string;
+        /**
+         * Auto-routing decision. Populated when the chat pipeline considered an
+         * automatic model-tier change (up- or downgrade). `reason: "shadow"` means
+         * the upgrade was logged but not applied — used while validating the
+         * router's complexity signal before flipping `CHAT_AUTO_UPGRADE_COMPLEX`.
+         */
+        routingDecision?: {
+            from: "fast" | "balanced" | "reasoning" | "codex";
+            to: "fast" | "balanced" | "reasoning" | "codex";
+            reason: "simple_downgrade" | "complex_upgrade" | "shadow" | "user_override";
+            complexity?: "simple" | "standard" | "complex";
+        };
+    };
+};
+export declare function normalizeForIntent(message: string): string;
+export { BLOCK_CATALOG_PATTERNS } from "./intent-patterns.ts";
+export declare function isBlockCatalogQuery(message: string): boolean;
+export declare function stripPositionalAnchorPhrase(message: string): string;
+/** Return the ordered list of BlockType values mentioned in the message. */
+export declare function extractMentionedBlockTypes(message: string): BlockType[];
+/**
+ * Returns true when the message is "add X in/to [the Y] heading/subheading/copy/..."
+ * — a field-content update phrased with "add", NOT a batch block add.
+ * Guards the loose fallback below from false positives when field-targeting
+ * prepositions are combined with block-type keyword aliases like "numbers"
+ * (Stats) or "copy" (RichText).
+ */
+export declare function isFieldContentUpdateRequest(message: string): boolean;
+export declare function isBatchAddRequest(message: string): boolean;
+/**
+ * Detects batch remove requests — any remove/delete/clear that implies
+ * multiple blocks should be affected. Broadly matches so the LLM can
+ * handle the nuance (typos, "this one", etc.) without strict single-op limits.
+ */
+export declare function isPageWideRewriteRequest(message: string): boolean;
+export declare function isBatchReorderRequest(message: string): boolean;
+export declare function isBatchRemoveRequest(message: string): boolean;
+/**
+ * Detects duplicate/copy/clone requests targeting a block on the current
+ * page. The fast LLM intent router's schema has no "duplicate" action
+ * (only add|move|update|remove|info|clarify), so these requests must
+ * bypass the router and go straight to the full planner, which supports
+ * the `duplicate_block` op.
+ */
+export declare function isDuplicateBlockRequest(message: string): boolean;
+/**
+ * Detects "duplicate this page and modify the content" patterns — duplicate /
+ * clone / copy a page combined with a modification verb (populate, fill,
+ * suggest, update, modify, change, adjust, replace, rewrite). Used to bypass
+ * `chatStrictPrimaryOpMode` so the planner can emit `duplicate_page` plus
+ * follow-on `update_props` / `add_block` / `remove_block` ops in one plan.
+ *
+ * Without this, strict mode truncates duplicate-and-modify plans to just the
+ * `duplicate_page` op, leaving the user with an unmodified clone.
+ */
+export declare function isDuplicateAndModifyRequest(message: string): boolean;
+/**
+ * Detects "show me a plan first" / "plan it before doing" phrasing — the user
+ * wants the planner to assemble ops but hold them behind the approval gate
+ * instead of auto-applying. Used by the chat pipeline to override
+ * `executionMode` to `plan_only` when the message asks for review-before-apply.
+ */
+export declare function requestsPlanFirst(message: string): boolean;
+export declare function isPageBlockListQuery(message: string): boolean;
+export declare function isInfoQuery(message: string): boolean;
+export declare function isPageListQuery(message: string): boolean;
+/**
+ * True when the message asks for a mutation that spans the whole site rather
+ * than the current page ("update the CTA on all pages", "make the footer
+ * site-wide", "change X everywhere"). The single-page deterministic path can't
+ * honor this — it would silently narrow the edit to the current page — so the
+ * gate defers these to the LLM, whose ops carry pageSlug and can fan out across
+ * pages or clarify. See planner-quality issue #29.
+ */
+export declare function hasCrossPageScope(message: string): boolean;
+export declare function isContentQuery(message: string): boolean;
+export declare function isAdviceQuery(message: string): boolean;
+export declare function adviceResponse(args: {
+    body: ChatRequestBody;
+    current: PageDoc;
+    plannerSource: "openai" | "anthropic" | "gemini" | "demo";
+    modelUsed: string;
+    modelKey: ModelKey;
+}): {
+    code: number;
+    payload: ChatResult;
+};
+export declare function plannerMessageWithPendingContext(session: string, message: string): string;
+/** Build the site context lines without wrapping in a message. Returns null if empty. */
+export declare function buildSiteContextBlock(args?: {
+    sitePurpose?: string;
+    siteHosting?: string;
+    businessContext?: ChatRequestBody["businessContext"];
+    siteContext?: ChatRequestBody["siteContext"];
+    pageDirectory?: string;
+}): string | null;
+export declare function withSiteContext(message: string, args?: {
+    sitePurpose?: string;
+    siteHosting?: string;
+    businessContext?: ChatRequestBody["businessContext"];
+    siteContext?: ChatRequestBody["siteContext"];
+}): string;
+export declare function stripSiteContextEnvelope(message: string): string;
+export declare function extractSiteContextLineValue(message: string, label: string): string | undefined;
+export declare function infoResponse(args: {
+    body: ChatRequestBody;
+    current: PageDoc;
+    plannerSource: "openai" | "anthropic" | "gemini" | "demo";
+    modelUsed: string;
+    modelKey: ModelKey;
+}): {
+    code: number;
+    payload: ChatResult;
+};