@kubuild/ai 0.6.0 → 0.8.0

package/dist/server/handler.d.ts

@@ -2,6 +2,8 @@ import type { KubuildAiEngine } from './engine';
 import type { KubuildAiAgent } from './agent';
 import type { PageDocument } from '@kubuild/schema';
 import type { AiGeneratePageRequest, AiRefactorNodeRequest, AiChatMessage, AiGenerateResponse, AiGenerationMode, PagePlan } from '../types';
+/** Default cap for client-supplied `instructions` (characters). */
+export declare const DEFAULT_MAX_CLIENT_INSTRUCTIONS_LENGTH = 4000;
 export interface AiApiRequestBody {
     mode?: AiGenerationMode;
     prompt?: string;
@@ -27,15 +29,42 @@ export interface AiApiRequestBody {
     /** Agent mode (STORA-530) — the snapshot the agent reads and patches. */
     document?: PageDocument;
     maxSteps?: number;
+    /**
+     * Client-supplied extra instructions. Appended AFTER the engine's built-in system prompt
+     * (never replacing it), length-capped, and ignored entirely when the handler was created
+     * with `allowClientInstructions: false`.
+     */
+    instructions?: string;
+    /** @deprecated Alias of `instructions`, accepted for older clients. Same rules apply. */
+    systemPrompt?: string;
 }
-export declare function processAiRequest(engine: KubuildAiEngine, body: unknown, signal?: AbortSignal, agent?: KubuildAiAgent): Promise<{
+/** Controls how client-supplied `instructions` are accepted by the handler. */
+export interface ClientInstructionsOptions {
+    /**
+     * Whether to honour `instructions` (and its deprecated alias `systemPrompt`) from the
+     * request body. Default: `true`. Set `false` on endpoints where end users — not your own
+     * editor build — can call the handler and you don't want them steering the model.
+     */
+    allowClientInstructions?: boolean;
+    /**
+     * Maximum accepted length (characters) of client instructions; longer text is truncated.
+     * Default: 4000.
+     */
+    maxClientInstructionsLength?: number;
+}
+/**
+ * Extracts the client instructions from a request body, applying the handler's
+ * allow/cap options. Returns `undefined` when there is nothing (allowed) to append.
+ */
+export declare function resolveClientInstructions(payload: AiApiRequestBody, options?: ClientInstructionsOptions): string | undefined;
+export declare function processAiRequest(engine: KubuildAiEngine, body: unknown, signal?: AbortSignal, agent?: KubuildAiAgent, instructionsOptions?: ClientInstructionsOptions): Promise<{
     status: number;
     response: AiGenerateResponse<unknown>;
 }>;
 /**
  * Options for {@link createAiHandler} (STORA-519).
  */
-export interface CreateAiHandlerOptions {
+export interface CreateAiHandlerOptions extends ClientInstructionsOptions {
     /**
      * Enables agent mode (STORA-530) on this endpoint. Without it, `mode: 'agent'` requests
      * are answered with a 501 rather than silently falling back to chat.

package/dist/server/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/server/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EACV,qBAAqB,EAErB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAEhB,QAAQ,EACT,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,eAAe,CAAC,EAAE,YAAY,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,aAAa,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,cAAc,GACrB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAkMpE;AAsDD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC;CAClF;AA8CD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,sBAAsB,IACzE,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CA+JnD"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/server/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EACV,qBAAqB,EAErB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAEhB,QAAQ,EACT,MAAM,UAAU,CAAC;AAGlB,mEAAmE;AACnE,eAAO,MAAM,sCAAsC,OAAO,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,eAAe,CAAC,EAAE,YAAY,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,aAAa,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,yBAAyB,GAClC,MAAM,GAAG,SAAS,CAcpB;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,cAAc,EACtB,mBAAmB,CAAC,EAAE,yBAAyB,GAC9C,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAyMpE;AAsDD;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,yBAAyB;IACvE;;;OAGG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC;CAClF;AA8CD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,sBAAsB,IACzE,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CA6KnD"}