@terreno/ai 57.8.0 → 57.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,18 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.assertFileUploadsEnabled = void 0;
4
+ const api_1 = require("@terreno/api");
5
+ /**
6
+ * Reject the request when file uploads are turned off.
7
+ * Missing or `true` leaves uploads enabled.
8
+ */
9
+ const assertFileUploadsEnabled = async (req, fileUploadsEnabled) => {
10
+ if (fileUploadsEnabled === undefined || fileUploadsEnabled === true) {
11
+ return;
12
+ }
13
+ const allowed = typeof fileUploadsEnabled === "function" ? await fileUploadsEnabled(req) : fileUploadsEnabled;
14
+ if (!allowed) {
15
+ throw new api_1.APIError({ status: 403, title: "File uploads are disabled" });
16
+ }
17
+ };
18
+ exports.assertFileUploadsEnabled = assertFileUploadsEnabled;
@@ -2,7 +2,7 @@
2
2
  * Helper for listing models available to the Gemini Developer API (the API-key based
3
3
  * `generativelanguage.googleapis.com` service, distinct from Vertex / the Gemini Enterprise Agent
4
4
  * Platform). Used to drive model pickers from the live set of models Google actually exposes for a
5
- * given API key, so retired models (e.g. an old `gemini-2.0-flash`) never appear.
5
+ * given API key, so retired models (e.g. an old `gemini-2.5-flash`) never appear.
6
6
  */
7
7
  /** Default Gemini Developer API base URL. */
8
8
  export declare const GEMINI_API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
@@ -19,11 +19,11 @@ export interface ListGeminiApiModelsOptions {
19
19
  /** Injectable fetch implementation (defaults to the global `fetch`). */
20
20
  fetchImpl?: typeof fetch;
21
21
  }
22
- /** Strip the "models/" resource prefix from a Gemini model name (e.g. "models/gemini-2.5-flash"). */
22
+ /** Strip the "models/" resource prefix from a Gemini model name (e.g. "models/gemini-3.8-flash"). */
23
23
  export declare const normalizeGeminiModelId: (name: string) => string;
24
24
  /**
25
25
  * List the models available to a Gemini Developer API key via the `models` REST endpoint. Returns
26
- * normalized model ids (e.g. "gemini-2.5-flash"). By default only chat-capable models (those
26
+ * normalized model ids (e.g. "gemini-3.8-flash"). By default only chat-capable models (those
27
27
  * supporting `generateContent`) are returned. Returns `undefined` when the listing could not be
28
28
  * retrieved (missing key, network error, non-200 response, etc.).
29
29
  */
@@ -6,21 +6,21 @@ const api_1 = require("@terreno/api");
6
6
  * Helper for listing models available to the Gemini Developer API (the API-key based
7
7
  * `generativelanguage.googleapis.com` service, distinct from Vertex / the Gemini Enterprise Agent
8
8
  * Platform). Used to drive model pickers from the live set of models Google actually exposes for a
9
- * given API key, so retired models (e.g. an old `gemini-2.0-flash`) never appear.
9
+ * given API key, so retired models (e.g. an old `gemini-2.5-flash`) never appear.
10
10
  */
11
11
  /** Default Gemini Developer API base URL. */
12
12
  exports.GEMINI_API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
13
13
  const MAX_MODEL_LIST_PAGES = 10;
14
14
  const MODEL_LIST_PAGE_SIZE = "200";
15
15
  const GENERATE_CONTENT_METHOD = "generateContent";
16
- /** Strip the "models/" resource prefix from a Gemini model name (e.g. "models/gemini-2.5-flash"). */
16
+ /** Strip the "models/" resource prefix from a Gemini model name (e.g. "models/gemini-3.8-flash"). */
17
17
  const normalizeGeminiModelId = (name) => {
18
18
  return name.trim().replace(/^models\//, "");
19
19
  };
20
20
  exports.normalizeGeminiModelId = normalizeGeminiModelId;
21
21
  /**
22
22
  * List the models available to a Gemini Developer API key via the `models` REST endpoint. Returns
23
- * normalized model ids (e.g. "gemini-2.5-flash"). By default only chat-capable models (those
23
+ * normalized model ids (e.g. "gemini-3.8-flash"). By default only chat-capable models (those
24
24
  * supporting `generateContent`) are returned. Returns `undefined` when the listing could not be
25
25
  * retrieved (missing key, network error, non-200 response, etc.).
26
26
  */
@@ -12,8 +12,8 @@ import type { ImageModel, LanguageModel } from "ai";
12
12
  * - `verifyVertexModelsEnabled` / `assertVertexModelsEnabled` confirm that the requested models are
13
13
  * actually enabled/available for the project using the Google publisher-models listing API.
14
14
  */
15
- /** Default Vertex / Gemini Enterprise Agent Platform region. */
16
- export declare const DEFAULT_VERTEX_LOCATION = "us-central1";
15
+ /** Default Vertex / Gemini Enterprise Agent Platform region. Only global is supported for Gemini 3. */
16
+ export declare const DEFAULT_VERTEX_LOCATION = "global";
17
17
  /** Provider returned by `@ai-sdk/google-vertex` `createVertex`. */
18
18
  export interface VertexLanguageModelProvider {
19
19
  (modelId: string): LanguageModel;
@@ -31,7 +31,7 @@ export interface CreateVertexProviderOptions {
31
31
  * Vertex models are permitted. When provided, only listed models may be resolved.
32
32
  */
33
33
  allowedModels?: string[];
34
- /** Vertex location/region. Falls back to GOOGLE_VERTEX_LOCATION, then `us-central1`. */
34
+ /** Vertex location/region. Forced to global endpoint for Gemini 3 support. */
35
35
  location?: string;
36
36
  /** GCP project id. Falls back to the GOOGLE_VERTEX_PROJECT env var. */
37
37
  project?: string;
@@ -70,7 +70,7 @@ export interface ListEnabledVertexModelsOptions {
70
70
  fetchImpl?: typeof fetch;
71
71
  /** Injectable access-token getter (defaults to Application Default Credentials). */
72
72
  getAccessToken?: () => Promise<string | undefined>;
73
- /** Vertex location/region. Falls back to GOOGLE_VERTEX_LOCATION, then `us-central1`. */
73
+ /** Vertex location/region. Forced to global endpoint for Gemini 3 support. */
74
74
  location?: string;
75
75
  /** GCP project id. */
76
76
  project: string;
@@ -90,8 +90,8 @@ export interface VerifyVertexModelsOptions extends ListEnabledVertexModelsOption
90
90
  models: string[];
91
91
  }
92
92
  /**
93
- * Normalize a publisher model resource name (e.g. "publishers/google/models/gemini-2.5-flash" or
94
- * "gemini-2.5-flash@001") down to its bare model id (e.g. "gemini-2.5-flash").
93
+ * Normalize a publisher model resource name (e.g. "publishers/google/models/gemini-3.8-flash" or
94
+ * "gemini-3.8-flash@001") down to its bare model id (e.g. "gemini-3.8-flash").
95
95
  */
96
96
  export declare const normalizeVertexModelId: (modelName: string) => string;
97
97
  /**
@@ -15,14 +15,14 @@ const api_1 = require("@terreno/api");
15
15
  * - `verifyVertexModelsEnabled` / `assertVertexModelsEnabled` confirm that the requested models are
16
16
  * actually enabled/available for the project using the Google publisher-models listing API.
17
17
  */
18
- /** Default Vertex / Gemini Enterprise Agent Platform region. */
19
- exports.DEFAULT_VERTEX_LOCATION = "us-central1";
18
+ /** Default Vertex / Gemini Enterprise Agent Platform region. Only global is supported for Gemini 3. */
19
+ exports.DEFAULT_VERTEX_LOCATION = "global";
20
20
  const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
21
21
  const MAX_MODEL_LIST_PAGES = 10;
22
22
  const MODEL_LIST_PAGE_SIZE = "200";
23
23
  /**
24
- * Normalize a publisher model resource name (e.g. "publishers/google/models/gemini-2.5-flash" or
25
- * "gemini-2.5-flash@001") down to its bare model id (e.g. "gemini-2.5-flash").
24
+ * Normalize a publisher model resource name (e.g. "publishers/google/models/gemini-3.8-flash" or
25
+ * "gemini-3.8-flash@001") down to its bare model id (e.g. "gemini-3.8-flash").
26
26
  */
27
27
  const normalizeVertexModelId = (modelName) => {
28
28
  const lastSegment = modelName.trim().split("/").pop() ?? modelName.trim();
@@ -64,7 +64,7 @@ const getDefaultAccessToken = async () => {
64
64
  return undefined;
65
65
  }
66
66
  };
67
- const resolveLocation = (location) => location ?? process.env.GOOGLE_VERTEX_LOCATION ?? exports.DEFAULT_VERTEX_LOCATION;
67
+ const resolveLocation = (_location) => "global";
68
68
  const aiPlatformHost = (location) => location === "global" ? "aiplatform.googleapis.com" : `${location}-aiplatform.googleapis.com`;
69
69
  /**
70
70
  * Create a Vertex AI (Gemini Enterprise Agent Platform) provider that enforces an optional model
@@ -56,17 +56,27 @@ export interface ImageContentPart {
56
56
  type: "image";
57
57
  url: string;
58
58
  mimeType?: string;
59
+ /** Durable storage key when the attachment was uploaded through FileStorageService. */
60
+ gcsKey?: string;
59
61
  }
60
62
  export interface FileContentPart {
61
63
  type: "file";
62
64
  url: string;
63
65
  filename?: string;
64
66
  mimeType: string;
67
+ /** Durable storage key when the attachment was uploaded through FileStorageService. */
68
+ gcsKey?: string;
65
69
  }
66
70
  export type MessageContentPart = TextContentPart | ImageContentPart | FileContentPart;
71
+ /** Lifecycle of an assistant reply that is persisted while it streams. */
72
+ export type GptHistoryPromptStatus = "streaming" | "complete" | "error";
67
73
  export interface GptHistoryPrompt {
68
74
  model?: string;
69
75
  rating?: "up" | "down";
76
+ /** Set on assistant replies produced by /gpt/prompt. "streaming" while partial text is persisted. */
77
+ status?: GptHistoryPromptStatus;
78
+ /** Identifies one /gpt/prompt reply so resume clients can follow it. */
79
+ streamId?: string;
70
80
  text: string;
71
81
  type: "user" | "assistant" | "system" | "tool-call" | "tool-result";
72
82
  content?: MessageContentPart[];
@@ -205,11 +215,24 @@ export interface GptRouteOptions {
205
215
  tools?: Record<string, import("ai").Tool>;
206
216
  toolChoice?: "auto" | "none" | "required";
207
217
  maxSteps?: number;
208
- /** Cheap model ID used for generating conversation titles (e.g. "gemini-2.0-flash-lite"). Falls back to the main model if not set. */
218
+ /** Cheap model ID used for generating conversation titles (e.g. "gemini-3.5-flash-lite"). Falls back to the main model if not set. */
209
219
  titleModelId?: string;
210
220
  /** Langfuse prompt name to load and use as the system prompt. Compiled with no variables.
211
221
  * Falls back gracefully if Langfuse is not configured or the prompt is not found. */
212
222
  langfuseSystemPromptName?: string;
223
+ /** When set, `data:` attachments are uploaded to durable storage and history stores the reference. */
224
+ fileStorageService?: import("../service/fileStorage").FileStorageService;
225
+ /**
226
+ * When `false` or the function returns `false`, prompts that include attachments are rejected.
227
+ * Omit or pass `true` to leave uploads enabled.
228
+ */
229
+ fileUploadsEnabled?: import("../service/fileUploadsGate").FileUploadsEnabled;
230
+ /** How often partial assistant output is persisted while streaming. Defaults to 1000ms. */
231
+ streamPersistIntervalMs?: number;
232
+ /** How often the resume endpoint polls for new partial output. Defaults to 500ms. */
233
+ streamResumePollIntervalMs?: number;
234
+ /** A streaming reply with no persisted update for this long is treated as interrupted. Defaults to 60000ms. */
235
+ streamStaleAfterMs?: number;
213
236
  }
214
237
  export interface GptHistoryRouteOptions {
215
238
  openApiOptions?: Record<string, unknown>;
@@ -221,6 +244,11 @@ export interface FileRouteOptions {
221
244
  gcsBucket: string;
222
245
  maxFileSize?: number;
223
246
  openApiOptions?: Record<string, unknown>;
247
+ /**
248
+ * When `false` or the function returns `false`, `POST /files/upload` is rejected.
249
+ * Reads and deletes stay available. Omit or pass `true` to leave uploads enabled.
250
+ */
251
+ fileUploadsEnabled?: import("../service/fileUploadsGate").FileUploadsEnabled;
224
252
  }
225
253
  export interface McpRouteOptions {
226
254
  mcpService: import("../service/mcpService").MCPService;
package/package.json CHANGED
@@ -18,8 +18,8 @@
18
18
  "description": "Provider-agnostic AI service with streaming chat, request logging, and admin tools — part of Terreno, the batteries-included TypeScript framework for universal apps.",
19
19
  "devDependencies": {
20
20
  "@biomejs/biome": "^2.3.6",
21
- "@terreno/api": "57.8.0",
22
- "@terreno/test": "57.8.0",
21
+ "@terreno/api": "57.9.0",
22
+ "@terreno/test": "57.9.0",
23
23
  "@types/bun": "^1.4.0",
24
24
  "@types/express": "^5.0.6",
25
25
  "@types/luxon": "^3.7.1",
@@ -69,7 +69,7 @@
69
69
  "name": "@terreno/ai",
70
70
  "peerDependencies": {
71
71
  "@ai-sdk/google-vertex": "^4.0.142",
72
- "@terreno/api": "57.8.0",
72
+ "@terreno/api": "57.9.0",
73
73
  "mongoose": "^8.0.0 || ^9.0.0"
74
74
  },
75
75
  "peerDependenciesMeta": {
@@ -97,5 +97,5 @@
97
97
  "test:coverage": "bun run ../scripts/check-coverage.ts"
98
98
  },
99
99
  "types": "dist/index.d.ts",
100
- "version": "57.8.0"
100
+ "version": "57.9.0"
101
101
  }
package/src/aiApp.ts CHANGED
@@ -25,6 +25,11 @@ export interface AiAppOptions {
25
25
  fileStorageService?: FileStorageService;
26
26
  /** GCS bucket name for file uploads. Required alongside fileStorageService. */
27
27
  gcsBucket?: string;
28
+ /**
29
+ * When `false` or the function returns `false`, file uploads and chat attachments are rejected.
30
+ * Omit or pass `true` to leave uploads enabled whenever storage is configured.
31
+ */
32
+ fileUploadsEnabled?: import("./service/fileUploadsGate").FileUploadsEnabled;
28
33
  /** Maximum number of tool-calling steps per chat request. Defaults to 5 when tools are present. */
29
34
  maxSteps?: number;
30
35
  /** MCP service for connecting to external tool servers. */
@@ -33,7 +38,7 @@ export interface AiAppOptions {
33
38
  openApiOptions?: Record<string, unknown>;
34
39
  /** Tool choice strategy for chat requests. Defaults to "auto" when tools are present. */
35
40
  toolChoice?: "auto" | "none" | "required";
36
- /** Cheap model ID used for generating conversation titles (e.g. "gemini-2.0-flash-lite"). Falls back to the main model if not set. */
41
+ /** Cheap model ID used for generating conversation titles (e.g. "gemini-3.5-flash-lite"). Falls back to the main model if not set. */
37
42
  titleModelId?: string;
38
43
  /** Tool definitions available to the AI model during chat. */
39
44
  tools?: Record<string, Tool>;
@@ -52,7 +57,7 @@ export interface AiAppOptions {
52
57
  * import {AiApp, AIService} from "@terreno/ai";
53
58
  * import {google} from "@ai-sdk/google";
54
59
  *
55
- * const aiService = new AIService({model: google("gemini-2.5-flash")});
60
+ * const aiService = new AIService({model: google("gemini-3.8-flash")});
56
61
  * new AiApp({aiService, tools: myTools}).register(app);
57
62
  * ```
58
63
  *
@@ -60,7 +65,7 @@ export interface AiAppOptions {
60
65
  * ```typescript
61
66
  * // Demo mode with per-request key support (no server-side API key needed)
62
67
  * new AiApp({
63
- * createModelFn: (key) => google("gemini-2.5-flash", {apiKey: key}),
68
+ * createModelFn: (key) => google("gemini-3.8-flash", {apiKey: key}),
64
69
  * demoMode: true,
65
70
  * }).register(app);
66
71
  * ```
@@ -80,6 +85,7 @@ export class AiApp implements TerrenoPlugin {
80
85
  createServerModelFn,
81
86
  demoMode,
82
87
  fileStorageService,
88
+ fileUploadsEnabled,
83
89
  gcsBucket,
84
90
  maxSteps,
85
91
  mcpService,
@@ -95,6 +101,9 @@ export class AiApp implements TerrenoPlugin {
95
101
  createModelFn,
96
102
  createServerModelFn,
97
103
  demoMode,
104
+ // Attachments are only uploaded when the file routes are mounted too
105
+ fileStorageService: fileStorageService && gcsBucket ? fileStorageService : undefined,
106
+ fileUploadsEnabled,
98
107
  maxSteps,
99
108
  mcpService,
100
109
  openApiOptions,
@@ -108,6 +117,7 @@ export class AiApp implements TerrenoPlugin {
108
117
  if (fileStorageService && gcsBucket) {
109
118
  addFileRoutes(router, {
110
119
  fileStorageService,
120
+ fileUploadsEnabled,
111
121
  gcsBucket,
112
122
  openApiOptions,
113
123
  });
@@ -31,7 +31,7 @@ describe("AIRequest Model", () => {
31
31
  it("should create a request with all fields", async () => {
32
32
  const userId = new mongoose.Types.ObjectId();
33
33
  const request = await AIRequest.create({
34
- aiModel: "gemini-2.5-flash",
34
+ aiModel: "gemini-3.8-flash",
35
35
  error: undefined,
36
36
  metadata: {key: "value"},
37
37
  prompt: "Translate this",
@@ -42,7 +42,7 @@ describe("AIRequest Model", () => {
42
42
  userId,
43
43
  });
44
44
 
45
- expect(request.aiModel).toBe("gemini-2.5-flash");
45
+ expect(request.aiModel).toBe("gemini-3.8-flash");
46
46
  expect(request.requestType).toBe("translation");
47
47
  expect(request.response).toBe("Translated text");
48
48
  expect(request.responseTime).toBe(1500);
@@ -6,6 +6,10 @@ import type {GptHistoryDocument, GptHistoryModel} from "../types";
6
6
  const contentPartSchema = new mongoose.Schema(
7
7
  {
8
8
  filename: {description: "Original filename of the attached file", type: String},
9
+ gcsKey: {
10
+ description: "Durable storage key for an attachment uploaded through FileStorageService",
11
+ type: String,
12
+ },
9
13
  mimeType: {description: "MIME type of the content part", type: String},
10
14
  text: {description: "Text content of this part", type: String},
11
15
  type: {
@@ -30,12 +34,22 @@ const gptHistoryPromptSchema = new mongoose.Schema(
30
34
  type: String,
31
35
  },
32
36
  result: {description: "Result returned from a tool call", type: mongoose.Schema.Types.Mixed},
37
+ status: {
38
+ description:
39
+ "Lifecycle of an assistant reply: streaming while partial text is persisted, then complete or error",
40
+ enum: ["streaming", "complete", "error"],
41
+ type: String,
42
+ },
43
+ streamId: {
44
+ description: "Identifier of the /gpt/prompt reply, used to resume an in-flight stream",
45
+ type: String,
46
+ },
33
47
  text: {
34
48
  default: "",
35
49
  description: "Text content of the prompt or response",
36
- // Image-only responses carry their payload in content, not text
37
- required: function (this: {content?: unknown[]}): boolean {
38
- return !this.content?.length;
50
+ // Image-only responses carry their payload in content, and streaming replies start empty
51
+ required: function (this: {content?: unknown[]; status?: string}): boolean {
52
+ return !this.content?.length && !this.status;
39
53
  },
40
54
  type: String,
41
55
  },
@@ -69,6 +69,27 @@ describe("File Routes", () => {
69
69
  expect(res.status).toBe(400);
70
70
  });
71
71
 
72
+ it("rejects uploads when file uploads are disabled", async () => {
73
+ const gated = new TerrenoApp({
74
+ configureApp: (router, options) => {
75
+ addFileRoutes(router, {
76
+ fileStorageService: fileStorageService as FileStorageService,
77
+ fileUploadsEnabled: async () => false,
78
+ openApiOptions: options,
79
+ });
80
+ },
81
+ skipListen: true,
82
+ userModel: UserModel,
83
+ }).build();
84
+ const agent = await authAsUser(gated, "notAdmin");
85
+ const res = await agent
86
+ .post("/files/upload")
87
+ .attach("file", Buffer.from("hello"), {contentType: "text/plain", filename: "hi.txt"});
88
+ expect(res.status).toBe(403);
89
+ expect(res.body.title).toBe("File uploads are disabled");
90
+ expect(fileStorageService.upload as ReturnType<typeof mock>).not.toHaveBeenCalled();
91
+ });
92
+
72
93
  it("rejects unsupported mime types", async () => {
73
94
  const agent = await authAsUser(app, "notAdmin");
74
95
  const res = await agent.post("/files/upload").attach("file", Buffer.from("<html></html>"), {
@@ -5,6 +5,7 @@ import multer from "multer";
5
5
 
6
6
  import {FileAttachment} from "../models/fileAttachment";
7
7
  import type {FileStorageService} from "../service/fileStorage";
8
+ import {assertFileUploadsEnabled} from "../service/fileUploadsGate";
8
9
  import type {FileRouteOptions} from "../types";
9
10
 
10
11
  const ALLOWED_MIME_TYPES = new Set([
@@ -56,6 +57,7 @@ export const addFileRoutes = (
56
57
  .build(),
57
58
  ],
58
59
  asyncHandler(async (req: express.Request, res: express.Response) => {
60
+ await assertFileUploadsEnabled(req, options.fileUploadsEnabled);
59
61
  const file = (req as express.Request & {file?: Express.Multer.File}).file;
60
62
  const userId = (req.user as {_id?: mongoose.Types.ObjectId} | undefined)
61
63
  ?._id as mongoose.Types.ObjectId;