@agent-native/core 0.46.0 → 0.48.1

package/dist/server/complete-text.d.ts

@@ -0,0 +1,56 @@
+import { type AgentEngine, type EngineContentPart, type EngineStreamOptions } from "../agent/engine/index.js";
+import type { ReasoningEffort } from "../shared/reasoning-effort.js";
+export interface CompleteTextMessage {
+    role: "user" | "assistant";
+    content: string | EngineContentPart[];
+}
+export interface CompleteTextUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+}
+export interface CompleteTextOptions {
+    /** Optional system prompt for the single model call. */
+    systemPrompt?: string;
+    /** Convenience final user message. Appended after `messages` when both are set. */
+    input?: string;
+    /** Optional prior messages for narrow multi-turn transforms. */
+    messages?: CompleteTextMessage[];
+    /** Explicit engine name or instance. Omit to use the normal request/default engine. */
+    engine?: string | AgentEngine | {
+        name: string;
+        config: Record<string, unknown>;
+    };
+    /** Explicit model. Omit to honor app/user default, then engine default. */
+    model?: string;
+    /** App/template id used for org-scoped model defaults. */
+    appId?: string;
+    /** Optional direct API key. Prefer request secrets/env resolution when possible. */
+    apiKey?: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    reasoningEffort?: ReasoningEffort;
+    providerOptions?: EngineStreamOptions["providerOptions"];
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface CompleteTextResult {
+    text: string;
+    content: EngineContentPart[];
+    engine: string;
+    model: string;
+    stopReason?: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use";
+    usage?: CompleteTextUsage;
+}
+/**
+ * Run a single server-side model completion through the framework engine layer.
+ *
+ * Prefer `sendToAgentChat()` or actions for product workflows where the user
+ * should see, steer, or audit the agent. Use this helper only for narrow text
+ * transforms that intentionally do not need tools, chat history, or run state.
+ */
+export declare function completeText(options: CompleteTextOptions): Promise<CompleteTextResult>;
+//# sourceMappingURL=complete-text.d.ts.map

package/dist/server/complete-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete-text.d.ts","sourceRoot":"","sources":["../../src/server/complete-text.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EAEtB,KAAK,mBAAmB,EACzB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGrE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,uFAAuF;IACvF,MAAM,CAAC,EACH,MAAM,GACN,WAAW,GACX;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IACtD,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,eAAe,CAAC,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;IACzD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,UAAU,CAAC;IACtE,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAoFD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CA0E7B"}

package/dist/server/complete-text.js

@@ -0,0 +1,147 @@
+import { getStoredModelForEngine, registerBuiltinEngines, resolveEngine, } from "../agent/engine/index.js";
+import { getOwnerActiveApiKey } from "../agent/production-agent.js";
+import { EngineError } from "../agent/engine/types.js";
+import { getRequestUserEmail } from "./request-context.js";
+function normalizeCompleteTextMessages(messages, input) {
+    const normalized = [];
+    for (const message of messages ?? []) {
+        const content = typeof message.content === "string"
+            ? [{ type: "text", text: message.content }]
+            : [...message.content];
+        normalized.push({ role: message.role, content });
+    }
+    if (input !== undefined) {
+        normalized.push({
+            role: "user",
+            content: [{ type: "text", text: input }],
+        });
+    }
+    if (normalized.length === 0) {
+        throw new Error("completeText requires `input` or at least one message.");
+    }
+    return normalized;
+}
+function contentText(parts) {
+    return parts
+        .filter((part) => {
+        return part.type === "text";
+    })
+        .map((part) => part.text)
+        .join("");
+}
+function createCompletionAbortSignal(signal, timeoutMs) {
+    const controller = new AbortController();
+    const cleanupFns = [];
+    if (signal) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+        }
+        else {
+            const onAbort = () => controller.abort(signal.reason);
+            signal.addEventListener("abort", onAbort, { once: true });
+            cleanupFns.push(() => signal.removeEventListener("abort", onAbort));
+        }
+    }
+    if (timeoutMs !== undefined) {
+        const timeout = setTimeout(() => {
+            controller.abort(new Error(`completeText timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        cleanupFns.push(() => clearTimeout(timeout));
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            for (const cleanup of cleanupFns)
+                cleanup();
+        },
+    };
+}
+async function resolveCompletionApiKey(explicitApiKey) {
+    if (explicitApiKey)
+        return explicitApiKey;
+    try {
+        return await getOwnerActiveApiKey(getRequestUserEmail());
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run a single server-side model completion through the framework engine layer.
+ *
+ * Prefer `sendToAgentChat()` or actions for product workflows where the user
+ * should see, steer, or audit the agent. Use this helper only for narrow text
+ * transforms that intentionally do not need tools, chat history, or run state.
+ */
+export async function completeText(options) {
+    registerBuiltinEngines();
+    const apiKey = await resolveCompletionApiKey(options.apiKey);
+    const engine = await resolveEngine({
+        engineOption: options.engine,
+        apiKey,
+        model: options.model,
+        appId: options.appId,
+    });
+    const model = options.model ??
+        (await getStoredModelForEngine(engine, { appId: options.appId })) ??
+        engine.defaultModel;
+    const { signal, cleanup } = createCompletionAbortSignal(options.signal, options.timeoutMs);
+    let streamedText = "";
+    let finalContent;
+    let usage;
+    let stopReason;
+    try {
+        for await (const event of engine.stream({
+            model,
+            systemPrompt: options.systemPrompt ?? "",
+            messages: normalizeCompleteTextMessages(options.messages, options.input),
+            tools: [],
+            abortSignal: signal,
+            maxOutputTokens: options.maxOutputTokens,
+            temperature: options.temperature,
+            reasoningEffort: options.reasoningEffort,
+            providerOptions: options.providerOptions,
+        })) {
+            if (event.type === "text-delta") {
+                streamedText += event.text;
+            }
+            else if (event.type === "assistant-content") {
+                finalContent = event.parts;
+            }
+            else if (event.type === "usage") {
+                usage = {
+                    inputTokens: event.inputTokens,
+                    outputTokens: event.outputTokens,
+                    cacheReadTokens: event.cacheReadTokens,
+                    cacheWriteTokens: event.cacheWriteTokens,
+                    totalTokens: event.totalTokens,
+                    reasoningTokens: event.reasoningTokens,
+                };
+            }
+            else if (event.type === "stop") {
+                if (event.reason === "error") {
+                    throw new EngineError(event.error ?? "Model completion failed.", {
+                        errorCode: event.errorCode,
+                        upgradeUrl: event.upgradeUrl,
+                        statusCode: event.statusCode,
+                        providerRetryable: event.providerRetryable,
+                    });
+                }
+                stopReason = event.reason;
+            }
+        }
+    }
+    finally {
+        cleanup();
+    }
+    const content = finalContent ?? [{ type: "text", text: streamedText }];
+    return {
+        text: contentText(content) || streamedText,
+        content,
+        engine: engine.name,
+        model,
+        stopReason,
+        usage,
+    };
+}
+//# sourceMappingURL=complete-text.js.map

package/dist/server/complete-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete-text.js","sourceRoot":"","sources":["../../src/server/complete-text.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,aAAa,GAKd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAmD3D,SAAS,6BAA6B,CACpC,QAAoD,EACpD,KAAyB;IAEzB,MAAM,UAAU,GAAoB,EAAE,CAAC;IAEvC,KAAK,MAAM,OAAO,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;QACrC,MAAM,OAAO,GACX,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;YACjC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YACpD,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3B,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,WAAW,CAAC,KAAmC;IACtD,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAwD,EAAE;QACrE,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC;IAC9B,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;SACxB,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,SAAS,2BAA2B,CAClC,MAA+B,EAC/B,SAA6B;IAE7B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,UAAU,GAAsB,EAAE,CAAC;IAEzC,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,UAAU,CAAC,KAAK,CACd,IAAI,KAAK,CAAC,gCAAgC,SAAS,IAAI,CAAC,CACzD,CAAC;QACJ,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,GAAG,EAAE;YACZ,KAAK,MAAM,OAAO,IAAI,UAAU;gBAAE,OAAO,EAAE,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,uBAAuB,CACpC,cAAkC;IAElC,IAAI,cAAc;QAAE,OAAO,cAAc,CAAC;IAC1C,IAAI,CAAC;QACH,OAAO,MAAM,oBAAoB,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAA4B;IAE5B,sBAAsB,EAAE,CAAC;IAEzB,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC;QACjC,YAAY,EAAE,OAAO,CAAC,MAAM;QAC5B,MAAM;QACN,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,CAAC;IACH,MAAM,KAAK,GACT,OAAO,CAAC,KAAK;QACb,CAAC,MAAM,uBAAuB,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACjE,MAAM,CAAC,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,2BAA2B,CACrD,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,SAAS,CAClB,CAAC;IAEF,IAAI,YAAY,GAAG,EAAE,CAAC;IACtB,IAAI,YAA6C,CAAC;IAClD,IAAI,KAAoC,CAAC;IACzC,IAAI,UAAwD,CAAC;IAE7D,IAAI,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC;YACtC,KAAK;YACL,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;YACxC,QAAQ,EAAE,6BAA6B,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC;YACxE,KAAK,EAAE,EAAE;YACT,WAAW,EAAE,MAAM;YACnB,eAAe,EAAE,OAAO,CAAC,eAAe;YACxC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,eAAe,EAAE,OAAO,CAAC,eAAe;YACxC,eAAe,EAAE,OAAO,CAAC,eAAe;SACzC,CAAC,EAAE,CAAC;YACH,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAChC,YAAY,IAAI,KAAK,CAAC,IAAI,CAAC;YAC7B,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;gBAC9C,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC;YAC7B,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBAClC,KAAK,GAAG;oBACN,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;oBAChC,eAAe,EAAE,KAAK,CAAC,eAAe;oBACtC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;oBACxC,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,eAAe,EAAE,KAAK,CAAC,eAAe;iBACvC,CAAC;YACJ,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACjC,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;oBAC7B,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,IAAI,0BAA0B,EAAE;wBAC/D,SAAS,EAAE,KAAK,CAAC,SAAS;wBAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;wBAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;wBAC5B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;qBAC3C,CAAC,CAAC;gBACL,CAAC;gBACD,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;IACvE,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,YAAY;QAC1C,OAAO;QACP,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,KAAK;QACL,UAAU;QACV,KAAK;KACN,CAAC;AACJ,CAAC","sourcesContent":["import {\n  getStoredModelForEngine,\n  registerBuiltinEngines,\n  resolveEngine,\n  type AgentEngine,\n  type EngineContentPart,\n  type EngineMessage,\n  type EngineStreamOptions,\n} from \"../agent/engine/index.js\";\nimport { getOwnerActiveApiKey } from \"../agent/production-agent.js\";\nimport { EngineError } from \"../agent/engine/types.js\";\nimport type { ReasoningEffort } from \"../shared/reasoning-effort.js\";\nimport { getRequestUserEmail } from \"./request-context.js\";\n\nexport interface CompleteTextMessage {\n  role: \"user\" | \"assistant\";\n  content: string | EngineContentPart[];\n}\n\nexport interface CompleteTextUsage {\n  inputTokens?: number;\n  outputTokens?: number;\n  cacheReadTokens?: number;\n  cacheWriteTokens?: number;\n  totalTokens?: number;\n  reasoningTokens?: number;\n}\n\nexport interface CompleteTextOptions {\n  /** Optional system prompt for the single model call. */\n  systemPrompt?: string;\n  /** Convenience final user message. Appended after `messages` when both are set. */\n  input?: string;\n  /** Optional prior messages for narrow multi-turn transforms. */\n  messages?: CompleteTextMessage[];\n  /** Explicit engine name or instance. Omit to use the normal request/default engine. */\n  engine?:\n    | string\n    | AgentEngine\n    | { name: string; config: Record<string, unknown> };\n  /** Explicit model. Omit to honor app/user default, then engine default. */\n  model?: string;\n  /** App/template id used for org-scoped model defaults. */\n  appId?: string;\n  /** Optional direct API key. Prefer request secrets/env resolution when possible. */\n  apiKey?: string;\n  maxOutputTokens?: number;\n  temperature?: number;\n  reasoningEffort?: ReasoningEffort;\n  providerOptions?: EngineStreamOptions[\"providerOptions\"];\n  signal?: AbortSignal;\n  timeoutMs?: number;\n}\n\nexport interface CompleteTextResult {\n  text: string;\n  content: EngineContentPart[];\n  engine: string;\n  model: string;\n  stopReason?: \"end_turn\" | \"max_tokens\" | \"stop_sequence\" | \"tool_use\";\n  usage?: CompleteTextUsage;\n}\n\nfunction normalizeCompleteTextMessages(\n  messages: readonly CompleteTextMessage[] | undefined,\n  input: string | undefined,\n): EngineMessage[] {\n  const normalized: EngineMessage[] = [];\n\n  for (const message of messages ?? []) {\n    const content =\n      typeof message.content === \"string\"\n        ? [{ type: \"text\" as const, text: message.content }]\n        : [...message.content];\n    normalized.push({ role: message.role, content });\n  }\n\n  if (input !== undefined) {\n    normalized.push({\n      role: \"user\",\n      content: [{ type: \"text\", text: input }],\n    });\n  }\n\n  if (normalized.length === 0) {\n    throw new Error(\"completeText requires `input` or at least one message.\");\n  }\n\n  return normalized;\n}\n\nfunction contentText(parts: readonly EngineContentPart[]): string {\n  return parts\n    .filter((part): part is Extract<EngineContentPart, { type: \"text\" }> => {\n      return part.type === \"text\";\n    })\n    .map((part) => part.text)\n    .join(\"\");\n}\n\nfunction createCompletionAbortSignal(\n  signal: AbortSignal | undefined,\n  timeoutMs: number | undefined,\n): { signal: AbortSignal; cleanup: () => void } {\n  const controller = new AbortController();\n  const cleanupFns: Array<() => void> = [];\n\n  if (signal) {\n    if (signal.aborted) {\n      controller.abort(signal.reason);\n    } else {\n      const onAbort = () => controller.abort(signal.reason);\n      signal.addEventListener(\"abort\", onAbort, { once: true });\n      cleanupFns.push(() => signal.removeEventListener(\"abort\", onAbort));\n    }\n  }\n\n  if (timeoutMs !== undefined) {\n    const timeout = setTimeout(() => {\n      controller.abort(\n        new Error(`completeText timed out after ${timeoutMs}ms`),\n      );\n    }, timeoutMs);\n    cleanupFns.push(() => clearTimeout(timeout));\n  }\n\n  return {\n    signal: controller.signal,\n    cleanup: () => {\n      for (const cleanup of cleanupFns) cleanup();\n    },\n  };\n}\n\nasync function resolveCompletionApiKey(\n  explicitApiKey: string | undefined,\n): Promise<string | undefined> {\n  if (explicitApiKey) return explicitApiKey;\n  try {\n    return await getOwnerActiveApiKey(getRequestUserEmail());\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Run a single server-side model completion through the framework engine layer.\n *\n * Prefer `sendToAgentChat()` or actions for product workflows where the user\n * should see, steer, or audit the agent. Use this helper only for narrow text\n * transforms that intentionally do not need tools, chat history, or run state.\n */\nexport async function completeText(\n  options: CompleteTextOptions,\n): Promise<CompleteTextResult> {\n  registerBuiltinEngines();\n\n  const apiKey = await resolveCompletionApiKey(options.apiKey);\n  const engine = await resolveEngine({\n    engineOption: options.engine,\n    apiKey,\n    model: options.model,\n    appId: options.appId,\n  });\n  const model =\n    options.model ??\n    (await getStoredModelForEngine(engine, { appId: options.appId })) ??\n    engine.defaultModel;\n  const { signal, cleanup } = createCompletionAbortSignal(\n    options.signal,\n    options.timeoutMs,\n  );\n\n  let streamedText = \"\";\n  let finalContent: EngineContentPart[] | undefined;\n  let usage: CompleteTextUsage | undefined;\n  let stopReason: CompleteTextResult[\"stopReason\"] | undefined;\n\n  try {\n    for await (const event of engine.stream({\n      model,\n      systemPrompt: options.systemPrompt ?? \"\",\n      messages: normalizeCompleteTextMessages(options.messages, options.input),\n      tools: [],\n      abortSignal: signal,\n      maxOutputTokens: options.maxOutputTokens,\n      temperature: options.temperature,\n      reasoningEffort: options.reasoningEffort,\n      providerOptions: options.providerOptions,\n    })) {\n      if (event.type === \"text-delta\") {\n        streamedText += event.text;\n      } else if (event.type === \"assistant-content\") {\n        finalContent = event.parts;\n      } else if (event.type === \"usage\") {\n        usage = {\n          inputTokens: event.inputTokens,\n          outputTokens: event.outputTokens,\n          cacheReadTokens: event.cacheReadTokens,\n          cacheWriteTokens: event.cacheWriteTokens,\n          totalTokens: event.totalTokens,\n          reasoningTokens: event.reasoningTokens,\n        };\n      } else if (event.type === \"stop\") {\n        if (event.reason === \"error\") {\n          throw new EngineError(event.error ?? \"Model completion failed.\", {\n            errorCode: event.errorCode,\n            upgradeUrl: event.upgradeUrl,\n            statusCode: event.statusCode,\n            providerRetryable: event.providerRetryable,\n          });\n        }\n        stopReason = event.reason;\n      }\n    }\n  } finally {\n    cleanup();\n  }\n\n  const content = finalContent ?? [{ type: \"text\", text: streamedText }];\n  return {\n    text: contentText(content) || streamedText,\n    content,\n    engine: engine.name,\n    model,\n    stopReason,\n    usage,\n  };\n}\n"]}

package/dist/server/core-routes-plugin.d.ts

@@ -7,6 +7,7 @@ import { type AuthSession } from "./auth.js";
  * collisions with template-specific `/api/*` routes.
  */
 export declare const FRAMEWORK_ROUTE_PREFIX = "/_agent-native";
+export declare const AVATAR_RASTER_MIME: RegExp;
 type BuilderAnonymousOwnerResolver = (event: H3Event) => string | null | Promise<string | null>;
 export type BuilderOwnerContext = {
     email: string | undefined;

package/dist/server/core-routes-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-routes-plugin.d.ts","sourceRoot":"","sources":["../../src/server/core-routes-plugin.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAuBlC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA2CvD,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAwDzD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAsJvD,KAAK,6BAA6B,GAAG,CACnC,KAAK,EAAE,OAAO,KACX,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE5C,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,wBAAsB,oCAAoC,CACxD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,6BAA6B,CAAC;IAC/C,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACjE,EACN,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAsD9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAWf;AAUD,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;wCACoC;IACpC,eAAe,CAAC,EAAE,OAAO,iBAAiB,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IAChF,qEAAqE;IACrE,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,6BAA6B,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC,cAAc,CAy/EhB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAAyC,CAAC"}
+{"version":3,"file":"core-routes-plugin.d.ts","sourceRoot":"","sources":["../../src/server/core-routes-plugin.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAuBlC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA+CvD,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAyDzD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAmBvD,eAAO,MAAM,kBAAkB,QAAwC,CAAC;AAsHxE,KAAK,6BAA6B,GAAG,CACnC,KAAK,EAAE,OAAO,KACX,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE5C,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,wBAAsB,oCAAoC,CACxD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,6BAA6B,CAAC;IAC/C,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACjE,EACN,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAsD9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CASf;AAUD,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;wCACoC;IACpC,eAAe,CAAC,EAAE,OAAO,iBAAiB,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IAChF,qEAAqE;IACrE,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,6BAA6B,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC,cAAc,CA0hFhB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAAyC,CAAC"}

package/dist/server/core-routes-plugin.js

@@ -14,13 +14,14 @@ import { handleIdentitySso } from "./identity-sso.js";
 import { isIdentitySsoEnabled } from "./identity-sso-store.js";
 import { getAppName } from "./app-name.js";
 import { upsertEnvFile } from "./create-server.js";
-import { readBody } from "./h3-helpers.js";
+import { readBody, DEFAULT_UPLOAD_MAX_FILE_BYTES, isAllowedUploadMimeType, } from "./h3-helpers.js";
 import { BUILDER_CONNECT_PARAM, BUILDER_CONNECT_OWNER_COOKIE, BUILDER_ENV_KEYS, BUILDER_OPENER_PARAM, BUILDER_STATE_PARAM, appendBuilderConnectToken, builderConnectTrackingProperties, buildBuilderCliAuthUrl, createBuilderBrowserCallbackErrorPage, createBuilderBrowserCallbackPage, getBuilderConnectTrackingParams, getBuilderCliAuthCallbackOriginForEvent, getBuilderBrowserOriginForEvent, resolveBuilderCallbackReturnUrl, getBuilderBrowserStatusForEvent, resolveBuilderBranchProjectId, resolveSafePreviewUrl, runBuilderAgent, signBuilderCallbackState, verifyBuilderConnectTokenAndGetOwner, verifyBuilderCallbackStateAndGetOwner, signBuilderConnectToken, } from "./builder-browser.js";
 import { getState, putState, deleteState, listComposeDrafts, getComposeDraft, putComposeDraft, deleteComposeDraft, deleteAllComposeDrafts, } from "../application-state/handlers.js";
 import { getSetting, putSetting, deleteSetting } from "../settings/store.js";
 import { getUserSetting, putUserSetting, deleteUserSetting, } from "../settings/user-settings.js";
 import { getSession } from "./auth.js";
 import { getAppBasePath, getOrigin } from "./google-oauth.js";
+import { getConfiguredAppBasePath, stripAppBasePath } from "./app-base-path.js";
 import { findWorkspaceRoot } from "../scripts/utils.js";
 import { listOnboardingSteps } from "../onboarding/registry.js";
 import { uploadFile, getActiveFileUploadProvider, listFileUploadProviders, } from "../file-upload/index.js";
@@ -62,6 +63,11 @@ function parseBuilderCallbackBoolean(value) {
     return /^(1|true)$/i.test(value);
 }
 const PROVIDER_ENV_VAR_KEYS = new Set(Object.values(PROVIDER_ENV_META).map(({ envVar }) => envVar));
+// Raster-only data-URI allowlist for avatar writes. SVG is deliberately absent:
+// data:image/svg+xml payloads can carry inline <script> and event-handler
+// attributes that execute when the browser renders them as an <img> src or
+// inlines them in the DOM. Mirrors SAFE_DATA_IMAGE in sanitize-html.ts.
+export const AVATAR_RASTER_MIME = /^data:image\/(png|jpe?g|gif|webp);/i;
 async function detectUsageEngineName(event, userEmail) {
     try {
         const stored = (await getSetting("agent-engine"));
@@ -116,25 +122,6 @@ async function trackBuilderLifecycle(event, name, userEmail, properties = {}) {
         ...properties,
     }, { userId: userEmail });
 }
-function normalizeAppBasePath(value) {
-    if (!value || value === "/")
-        return "";
-    const trimmed = value.trim();
-    if (!trimmed || trimmed === "/")
-        return "";
-    return `/${trimmed.replace(/^\/+/, "").replace(/\/+$/, "")}`;
-}
-function stripAppBasePath(pathname) {
-    const basePath = normalizeAppBasePath(process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH);
-    if (!basePath)
-        return pathname;
-    if (pathname === basePath)
-        return "/";
-    if (pathname.startsWith(`${basePath}/`)) {
-        return pathname.slice(basePath.length) || "/";
-    }
-    return pathname;
-}
 function getBuilderConnectOwnerCookiePath() {
     return getAppBasePath() || "/";
 }
@@ -221,7 +208,7 @@ export function resolveLegacyToolsRedirect(rawPath, search) {
     if (pathname !== "/tools" && !pathname.startsWith("/tools/"))
         return null;
     const suffix = pathname === "/tools" ? "" : pathname.slice("/tools".length);
-    const basePath = normalizeAppBasePath(process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH);
+    const basePath = getConfiguredAppBasePath();
     return `${basePath}/extensions${suffix}${search}`;
 }
 function redactValues(text, values) {
@@ -562,7 +549,7 @@ export function createCoreRoutesPlugin(options = {}) {
                         /* org module not present in this template — keep userEmail-only */
                     }
                 }
-                return runWithRequestContext({ userEmail, orgId }, async () => {
+                return runWithRequestContext({ userEmail, orgId: orgId ?? undefined }, async () => {
                     const projectId = await resolveBuilderBranchProjectId();
                     const requestStatus = {
                         ...envStatus,
@@ -659,7 +646,9 @@ export function createCoreRoutesPlugin(options = {}) {
                                     envStatus.subscriptionName ||
                                     undefined,
                                 isEnterprise: creds.isEnterprise ?? envStatus.isEnterprise ?? undefined,
-                                isFreeAccount: creds.isFreeAccount ?? envStatus.isFreeAccount ?? undefined,
+                                isFreeAccount: creds.isFreeAccount ??
+                                    envStatus.isFreeAccount ??
+                                    undefined,
                                 credentialSource: credentialSource ?? undefined,
                             });
                         }
@@ -910,7 +899,7 @@ export function createCoreRoutesPlugin(options = {}) {
                 // uses. Without this, per-user Builder keys stored in app_secrets are
                 // invisible to the run path and the call throws "Builder keys are not
                 // configured" even though the status endpoint correctly reports configured=true.
-                return runWithRequestContext({ userEmail, orgId }, async () => {
+                return runWithRequestContext({ userEmail, orgId: orgId ?? undefined }, async () => {
                     const projectId = await resolveBuilderBranchProjectId();
                     if (!projectId) {
                         setResponseStatus(event, 403);
@@ -1529,7 +1518,7 @@ export function createCoreRoutesPlugin(options = {}) {
                         return {
                             configured: true,
                             engine,
-                            model: stored.model ?? entry?.defaultModel ?? DEFAULT_MODEL,
+                            model: stored?.model ?? entry?.defaultModel ?? DEFAULT_MODEL,
                             source: "settings",
                         };
                     }
@@ -1838,6 +1827,20 @@ export function createCoreRoutesPlugin(options = {}) {
                     setResponseStatus(event, 400);
                     return { error: "No file uploaded" };
                 }
+                // Reject files that exceed the upload size ceiling.
+                if (filePart.data.length > DEFAULT_UPLOAD_MAX_FILE_BYTES) {
+                    setResponseStatus(event, 413);
+                    return {
+                        error: `File too large (max ${Math.round(DEFAULT_UPLOAD_MAX_FILE_BYTES / 1024 / 1024)} MB)`,
+                    };
+                }
+                // Reject executable/script MIME types.
+                if (filePart.type && !isAllowedUploadMimeType(filePart.type)) {
+                    setResponseStatus(event, 415);
+                    return {
+                        error: `Unsupported file type: ${filePart.type}`,
+                    };
+                }
                 const session = await getSession(event);
                 if (!session?.email) {
                     setResponseStatus(event, 401);
@@ -2107,6 +2110,11 @@ export function createCoreRoutesPlugin(options = {}) {
             // ─── Avatar routes ──────────────────────────────────────────────────
             // GET /_agent-native/avatar/:email — fetch any user's avatar (public)
             // PUT /_agent-native/avatar       — update current user's avatar (auth required)
+            //
+            // Only raster MIME types are accepted on write; SVG carries scripting risk
+            // (data:image/svg+xml payloads can execute JS when rendered by browsers),
+            // so it is explicitly excluded. Mirrors the SAFE_DATA_IMAGE allowlist in
+            // packages/core/src/client/blocks/library/sanitize-html.ts.
             getH3App(nitroApp).use(`${P}/avatar`, defineEventHandler(async (event) => {
                 const method = getMethod(event);
                 const emailParam = (event.url?.pathname || "")
@@ -2128,9 +2136,11 @@ export function createCoreRoutesPlugin(options = {}) {
                     }
                     const body = await readBody(event);
                     const { image } = body;
-                    if (!image || !image.startsWith("data:image/")) {
+                    if (!image || !AVATAR_RASTER_MIME.test(image)) {
                         setResponseStatus(event, 400);
-                        return { error: "image (data URL) required" };
+                        return {
+                            error: "image must be a data URI with a raster MIME type (png, jpeg, gif, or webp)",
+                        };
                     }
                     await putSetting(`avatar:${session.email}`, { image });
                     return { ok: true };