@terreno/ai 57.20.0 → 58.0.0-beta.1

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.
Files changed (97) hide show
  1. package/AGENTS.md +20 -18
  2. package/CHANGELOG.md +93 -0
  3. package/biome.jsonc +3 -2
  4. package/dist/aiApp.d.ts +5 -2
  5. package/dist/aiApp.js +3 -2
  6. package/dist/harness/agentLoop.js +1 -0
  7. package/dist/index.d.ts +2 -1
  8. package/dist/index.js +6 -2
  9. package/dist/migrations/gptHistoryStringIds.d.ts +41 -0
  10. package/dist/migrations/gptHistoryStringIds.js +94 -0
  11. package/dist/models/aiDataset.js +2 -2
  12. package/dist/models/gptHistory.js +11 -0
  13. package/dist/observability/local/experimentRunner.d.ts +2 -5
  14. package/dist/routes/files.d.ts +7 -1
  15. package/dist/routes/files.js +62 -13
  16. package/dist/routes/gptActions.js +0 -7
  17. package/dist/routes/gptHistories.js +8 -2
  18. package/dist/service/aiDatasets.js +2 -1
  19. package/dist/service/chatTurn.js +4 -0
  20. package/dist/service/vertex.d.ts +5 -2
  21. package/dist/types/harness.d.ts +5 -2
  22. package/dist/types/index.d.ts +5 -2
  23. package/e2e/smoke.ts +227 -0
  24. package/package.json +19 -16
  25. package/src/aiApp.test.ts +43 -18
  26. package/src/aiApp.ts +6 -3
  27. package/src/harness/agentLoop.test.ts +1 -1
  28. package/src/harness/agentLoop.ts +2 -1
  29. package/src/harness/agentRecovery.test.ts +31 -28
  30. package/src/harness/approvals.test.ts +11 -9
  31. package/src/harness/events.test.ts +10 -6
  32. package/src/harness/extensions.test.ts +7 -6
  33. package/src/harness/ownership.test.ts +20 -9
  34. package/src/harness/retries.test.ts +6 -3
  35. package/src/harness/routes/conversations.test.ts +2 -2
  36. package/src/harness/routes/tasks.test.ts +2 -2
  37. package/src/harness/runners/jobsRunner.test.ts +1 -1
  38. package/src/harness/subagent.test.ts +3 -2
  39. package/src/harness/waits.test.ts +6 -4
  40. package/src/index.test.ts +3 -3
  41. package/src/index.ts +7 -1
  42. package/src/isolated/gptStream.isolated.ts +35 -30
  43. package/src/isolated/langfuseClient.isolated.ts +9 -3
  44. package/src/isolated/lazyProjectModel.isolated.ts +2 -2
  45. package/src/langfuseApp.test.ts +4 -20
  46. package/src/langfuseRoutes.test.ts +20 -15
  47. package/src/langfuseTracing.test.ts +6 -2
  48. package/src/langfuseVercelAi.test.ts +12 -9
  49. package/src/migrations/gptHistoryStringIds.test.ts +231 -0
  50. package/src/migrations/gptHistoryStringIds.ts +150 -0
  51. package/src/models/aiDataset.test.ts +1 -1
  52. package/src/models/aiDataset.ts +2 -2
  53. package/src/models/gptHistory.test.ts +22 -11
  54. package/src/models/gptHistory.ts +19 -1
  55. package/src/observability/evaluate.test.ts +12 -10
  56. package/src/observability/local/experimentRunner.test.ts +9 -12
  57. package/src/observability/local/experimentRunner.ts +2 -2
  58. package/src/observability/local/promptStore.test.ts +4 -3
  59. package/src/observability/routes/datasets.test.ts +2 -2
  60. package/src/observability/routes/evaluators.test.ts +2 -2
  61. package/src/observability/routes/experiments.test.ts +2 -2
  62. package/src/observability/routes/prompts.test.ts +3 -3
  63. package/src/observability/routes/review.test.ts +2 -2
  64. package/src/observability/routes/status.test.ts +4 -4
  65. package/src/observability/routes/testMultiStage.test.ts +6 -6
  66. package/src/observability/routes/traces.test.ts +2 -2
  67. package/src/routes/files.test.ts +126 -3
  68. package/src/routes/files.ts +90 -15
  69. package/src/routes/gpt.test.ts +23 -16
  70. package/src/routes/gptActions.test.ts +15 -15
  71. package/src/routes/gptActions.ts +1 -4
  72. package/src/routes/gptApprovals.test.ts +1 -1
  73. package/src/routes/gptDatasets.test.ts +1 -1
  74. package/src/routes/gptFiles.test.ts +2 -2
  75. package/src/routes/gptHistories.test.ts +17 -11
  76. package/src/routes/gptHistories.ts +59 -55
  77. package/src/routes/gptHistoriesSync.test.ts +141 -0
  78. package/src/routes/mcp.test.ts +3 -3
  79. package/src/routes/projects.test.ts +5 -3
  80. package/src/routes/routes.test.ts +64 -47
  81. package/src/service/aiDatasets.ts +2 -1
  82. package/src/service/aiService.test.ts +1 -1
  83. package/src/service/asks.test.ts +14 -6
  84. package/src/service/chatTurn.ts +4 -0
  85. package/src/service/fileStorage.test.ts +5 -2
  86. package/src/service/getMCPTools.test.ts +9 -5
  87. package/src/service/mcpService.test.ts +6 -3
  88. package/src/service/vertex.test.ts +1 -1
  89. package/src/service/vertex.ts +7 -4
  90. package/src/tests/bunSetup.ts +1 -1
  91. package/src/tests/chatHarness.ts +4 -4
  92. package/src/tests/fakeJudge.ts +8 -0
  93. package/src/tests/fakeLangfusePrompt.ts +10 -0
  94. package/src/tests/helpers.ts +26 -4
  95. package/src/types/harness.ts +6 -2
  96. package/src/types/index.ts +5 -2
  97. package/tsconfig.typecheck.json +18 -0
package/AGENTS.md CHANGED
@@ -21,7 +21,7 @@ deploy.
21
21
 
22
22
  - **api/** - REST API framework built on Express/Mongoose (`@terreno/api`)
23
23
  - **ui/** - React Native UI component library (`@terreno/ui`)
24
- - **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
24
+ - **syncdb/** - Frontend data layer: local-first collections, request client + generated API hooks, auth session, flags (`@terreno/syncdb`)
25
25
  - **admin-backend/** - Admin panel backend plugin for @terreno/api (`@terreno/admin-backend`)
26
26
  - **admin-frontend/** - Admin panel frontend screens for @terreno/api backends (`@terreno/admin-frontend`)
27
27
  - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp`, bins `terreno-mcp` / `terreno-mcp-local`)
@@ -68,13 +68,13 @@ The three core packages form a complete full-stack framework:
68
68
  |
69
69
  /openapi.json
70
70
  |
71
- RTK Query SDK Codegen
71
+ terreno-syncdb-codegen
72
72
  |
73
73
  FRONTEND
74
- @terreno/rtk
75
- - Generated hooks from OpenAPI spec
76
- - Auth slice with JWT token management
77
- - Automatic token refresh
74
+ @terreno/syncdb
75
+ - Generated request hooks + local-first collection hooks
76
+ - SessionProvider / useSession (Better Auth or JWT)
77
+ - Shared auth provider with refresh on 401
78
78
  +
79
79
  @terreno/ui
80
80
  - React Native components (Box, Button, TextField, etc.)
@@ -85,12 +85,12 @@ The three core packages form a complete full-stack framework:
85
85
 
86
86
  1. **Backend (api)**: Define Mongoose models, use `modelRouter` to create CRUD endpoints with permissions
87
87
  2. **OpenAPI Generation**: `setupServer` automatically generates `/openapi.json`
88
- 3. **SDK Codegen**: Frontend runs `bun run sdk` to generate RTK Query hooks from OpenAPI spec
89
- 4. **Frontend (rtk + ui)**: Use generated hooks with UI components for type-safe API calls
88
+ 3. **SDK Codegen**: Frontend runs `bun run sdk` (`terreno-syncdb-codegen --api-out` → `store/apiSdk.ts`) and `bun run sync-sdk` (→ `store/syncDbSdk.ts`)
89
+ 4. **Frontend (syncdb + ui)**: Use `useQuery` / `useMutate` for synced collections and generated hooks for other routes. `@terreno/rtk` and Redux were removed in Terreno 58.
90
90
 
91
91
  ## Example Apps (Keep These Updated!)
92
92
 
93
- The `example-frontend/` and `example-backend/` directories serve as both documentation and integration tests. When adding features to api, ui, or rtk:
93
+ The `example-frontend/` and `example-backend/` directories serve as both documentation and integration tests. When adding features to api, ui, or syncdb:
94
94
 
95
95
  1. **Add examples** demonstrating new features
96
96
  2. **Update SDK** after backend changes: `cd example-frontend && bun run sdk`
@@ -290,26 +290,28 @@ Modals:
290
290
  - Don't use raw `View`/`Text` when `Box`/@terreno/ui `Text` are available
291
291
  - Don't forget loading and error states
292
292
  - Don't use `style` prop when equivalent props exist (`padding`, `margin`)
293
- - Never modify `openApiSdk.ts` manually
293
+ - Never modify generated `store/apiSdk.ts` or `store/syncDbSdk.ts` manually
294
294
 
295
- ### @terreno/rtk
295
+ ### @terreno/syncdb
296
296
 
297
- Redux Toolkit Query integration:
297
+ Frontend data, request, and session layer:
298
298
 
299
- - **generateAuthSlice**: Creates auth reducer and middleware with JWT handling
300
- - **emptyApi**: Base RTK Query API for code generation
301
- - **Platform utilities**: Secure token storage (expo-secure-store for native, AsyncStorage for web)
299
+ - **createSyncDb** + `useQuery` / `useMutate`: Local-first collection CRUD
300
+ - **createApiClient** + generated `store/apiSdk.ts` hooks: Every non-synced route
301
+ - **SessionProvider** / **useSession**: Better Auth (or `jwtAuthAdapter`) session state
302
302
 
303
303
  Key imports:
304
304
  ```typescript
305
- import {generateAuthSlice} from "@terreno/rtk";
305
+ import {createApiClient} from "@terreno/syncdb/api";
306
+ import {SessionProvider, useSession} from "@terreno/syncdb/auth";
307
+ import {useMutate, useQuery} from "@terreno/syncdb/react";
306
308
  ```
307
309
 
308
- Always use generated SDK hooks - never use `axios` or `request` directly:
310
+ Always use generated SDK hooks or syncdb hooks - never use `axios` or `fetch` directly:
309
311
 
310
312
  ```typescript
311
313
  // Correct
312
- import {useGetYourRouteQuery} from "@/store/openApiSdk";
314
+ import {useGetYourRouteQuery} from "@/store/apiSdk";
313
315
  const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
314
316
 
315
317
  // Wrong - don't use axios directly
package/CHANGELOG.md CHANGED
@@ -20,6 +20,99 @@ Upgrade notes for consumer action live in [`mcp-server/src/docs/upgrades/`](mcp-
20
20
 
21
21
  Unreleased changes live in [`changelog/unreleased/`](changelog/unreleased/). Add one Markdown file per feature (see that directory's README) instead of editing this section.
22
22
 
23
+ ## [58.0.0-beta.1] - 2026-11-02
24
+
25
+ Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.1.md`](mcp-server/src/docs/upgrades/58.0.0-beta.1.md).
26
+
27
+ ### Breaking
28
+
29
+ - Terreno 58 targets Expo SDK 58 (`~58.0.14`), React Native `0.88.0`, and React `19.3.0`. `@terreno/ui` peers `react-native` `0.88.0`. Native catalog moves with the SDK: `react-native-gesture-handler` `~3.3.0`, `react-native-reanimated` `4.7.1` + `react-native-worklets` `0.13.0`, `react-native-screens` `~4.30.0`, `react-native-webview` `14.0.1`, `@sentry/react-native` `~8.28.0`, `@shopify/flash-list` `2.3.2`, `@shopify/react-native-skia` `2.14.0`. Rebuild dev clients and store binaries.
30
+ - Expo Router 58: set `export const unstable_settings = {initialRouteName}` on the layout instead of passing `initialRouteName` to `<Slot>` / navigators. `SidebarNavigation` ignores the prop.
31
+ - Expo Router 58 static rendering: a custom `app/+html.tsx` must render `headNodes` and `bodyNodes` from `useServerDocumentContext()` (`expo-router/html`), or exported pages ship without their JavaScript. `example-frontend` is updated.
32
+ - React Native 0.88 generated types: type refs as `ViewInstance`, `TextInstance`, `ScrollViewInstance`, and `TextInputInstance` (`Box.scrollRef`, `TextField.inputRef`, `Text` `ref`).
33
+ - `create-terreno-app` scaffolds Expo `~58.0.14`, React Native `0.88.0`, and React `19.3.0`.
34
+ - The Terreno 58 native module baseline lands in `example-frontend` and `demo`: `@stripe/stripe-react-native` 0.81.0, `react-native-purchases` and `react-native-purchases-ui` 10.12.2, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, and `expo-build-properties` (Android Kotlin 2.2.21 and `compileSdkVersion` 37 pins). Rebuild every dev client and store binary. `react-native-otp-verify` is left out because it does not support the New Architecture. The demo has a hidden **Native Modules** page that shows each module's version and whether the running binary links it. See the 58.0.0 upgrade note.
35
+ - `TerrenoApp` turns HTTP rate limiting on by default. Omitting `rateLimit` now mounts the limiter with the memory store (auth 20 / 15 min, api 600 / 15 min). Pass `rateLimit: false` to turn it off. On Cloud Run pass `rateLimit: {trustProxy: 1}` so unauthenticated traffic keys by client IP. See the 58.0.0 upgrade note.
36
+ - `@terreno/admin-frontend` no longer takes an RTK `api`. The `api` prop is removed from every admin component (`AdminProvider`, `AdminShellLayout`, `AdminHome`, `AdminModelList`, `AdminModelTable`, `AdminModelForm`, `AdminScreenRouter`, `ConfigurationScreen`, `DocumentStorageBrowser`, `ConsentHistory`, comms, jobs, org, consent, and announcement screens, and widget props), and admin hooks drop their `api` argument (`useAdminConfig(apiBase)`, `useAdminScripts(apiBase)`, `useAdminRoles(apiBase)`, `useConfigurationApi({basePath})`, `useDocumentStorageApi(basePath)`, `useConsentHistory(baseUrl)`, `useOrganizationsApi(basePath)`, `useCommsDashboardApi()`, `useJobsDashboardApi()`, and the `useAiObservability*Api()` hooks).
37
+ - `useAdminApi(api, routePath, modelName)` is removed. Use `useAdminModelApi(routePath, modelName)`, which keeps the same hook names and calls the same `/admin/{routePath}` URLs through the admin fetch client. `AdminApi`, `EndpointBuilder`, and admin `injectEndpoints` are gone; `@reduxjs/toolkit` and `react-redux` are no longer peers of admin-frontend.
38
+ - `AdminProvider` is now the required auth binding for every admin request, including ObjectId and API-only model CRUD. Cookie SPAs pass `credentials="same-origin"`; embedded apps pass `apiOrigin` and `getAuthHeaders`. Product screens that reuse admin components wrap them in `AdminProvider`. See the 58.0.0 upgrade guide.
39
+ - Removed the legacy RTK realtime path. Use `sync` on `modelRouter` with `@terreno/syncdb` for live collection updates. `RealtimeApp`, `SyncApp`, socket auth, `sync:delta`, and admin `admin:model.changed` events are unchanged. See the 58.0.0 upgrade note.
40
+ - `@terreno/api`: `modelRouter` no longer accepts `realtime` (now a TypeScript error), and the change stream no longer emits the `sync` websocket event. Removed `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, `registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`, the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. Sockets no longer handle `subscribe:model`, `subscribe:document`, or `subscribe:query`.
41
+ - `@terreno/rtk`: removed `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `useSyncConnection`, and the `RealtimeEvent` type. The rest of `@terreno/rtk` (including `useSocketConnection` and `useRealtimeDebug`) is removed in the same release; see `remove-rtk.md`.
42
+ - Removed `@terreno/rtk` and every Redux dependency (`@reduxjs/toolkit`, `react-redux`, `redux-persist`, `@rtk-query/codegen-openapi`). `@terreno/rtk` is not published for 58. `@terreno/syncdb` is the only frontend data, request, and session layer. Follow `docs/how-to/migrate-rtk-to-syncdb.md`, which maps every removed export to its replacement, and the 58.0.0 upgrade note.
43
+ - `@terreno/syncdb` adds `@terreno/syncdb/api` (`createApiClient`, `ApiError`), request hooks in `@terreno/syncdb/react` (`ApiClientProvider`, `useApiQuery`, `useLazyApiQuery`, `useApiMutation`, `useSocketEvent`), `@terreno/syncdb/config` (`baseUrl`, `baseWebsocketsUrl`, `appHeaders`), `@terreno/syncdb/auth` (`createBetterAuthClient`, `SessionProvider`, `useSession`, `jwtAuthAdapter`, `useJwtAuth`, token-expiry helpers), `@terreno/syncdb/flags` (`useFeatureFlags`, `useTerrenoFeatureFlags` on the sync socket), `@terreno/syncdb/app` (`useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools`), and `@terreno/syncdb/buildNumber`.
44
+ - `terreno-syncdb-codegen --api-out` generates typed hooks for every non-synced OpenAPI operation (same names as the RTK codegen), replacing `@rtk-query/codegen-openapi`. `bun run sdk` writes `store/apiSdk.ts`.
45
+ - `@terreno/ui` `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, and `useAcknowledgeAnnouncement` take a request `client` instead of an RTK `api`.
46
+ - `GptHistory` (`gpt/histories`) and `McpServiceToken` (`mcp/service-tokens`, read-only) are synced collections with String ids. Run the `gptHistoryStringIdsMigration` (`@terreno/ai`) and `mcpServiceTokenStringIdsMigration` (`@terreno/api`) before deploying 58 frontends.
47
+ - `create-terreno-app`, the `terreno_bootstrap` prompt, and the `terreno_generate_screen` tool scaffold apps without Redux or `@terreno/rtk`. The terreno-mcp-local `get_rtk_state` tool, the MCP resource `terreno://docs/rtk`, and `terreno state --slice rtk` are removed; use `get_syncdb_state` and `terreno state`.
48
+
49
+ ### Added
50
+
51
+ - `DataTable` columns size themselves when `width` is omitted. Each auto column starts at the wider of its header and its content (sampled from at most 50 rows, measured with a canvas on web and estimated on native), clamped to 80–360px, and auto columns grow to fill the table's container. Columns that set `width` keep it. `DataTableColumn.width` is now optional.
52
+
53
+ ### Changed
54
+
55
+ - The repository's agent rules now generate with rulesync 17 (up from 9). The root rule `.rulesync/rules/00-root.md` now generates `AGENTS.md`, which Devin and other AGENTS.md readers load, in place of `.devin/rules/00-root.md`. Never edit `AGENTS.md` by hand: edit the root rule and run `bun run rules`. The examples that existed only in the old hand-edited `AGENTS.md` (syncdb and RTK SDK usage) moved into the root rule, so `CLAUDE.md`, the Cursor root rule, and Copilot instructions get them too. Links in the root rule now resolve from the repository root. Generated Copilot hooks use the portable `command` field. Generated Copilot subagents no longer list `agent/runSubagent` as their only tool, so they get every default tool. Generated skills carry their `license`, `disable-model-invocation`, and Devin `triggers` frontmatter.
56
+ - `@terreno/syncdb/auth` `SessionProvider`: `logout()` no longer clears the session before the server answers. The session stays in the state until `authClient.signOut()` finishes (`signOutTimeoutMs`, default 10 seconds), and then it is cleared. Meanwhile the new `isSigningOut` state (`useSession().isSigningOut`) is true; `isLoading` is left alone, so a navigator gated on it keeps its screen. Before, a login screen that opened at once could find the still-live session and sign the user straight back in. A sign-out that fails or times out checks the session first. A session that is still live, or a cookie or native session the server cannot be asked about, stays signed in, and `error` is set to `SIGN_OUT_FAILED_MESSAGE` ("Couldn't sign out. Check your connection and try again."). A web bearer client, which drops its token before the request leaves, ends signed out. The global `auth/logout` action (a refused session) now ends signed out even when the sign-out request fails. With `apisToReset` (57.17.0), `logout()` purges the cache when the session clears, not when it is dispatched: a purge at dispatch refetched every mounted screen mid-sign-out, and a refetch that could not reach the server answered 401 and signed the user out even though the sign-out failed. A failed sign-out keeps both the session and the cache. The global `auth/logout` action still purges at once (only the first of several in flight) and again when the session clears. A sign-in for another user that lands while a sign-out is in flight is kept; a sign-out that started signed out asks `getSession` first, so a restore of the session it revoked is cleared. Show `selectBetterAuthIsSigningOut` on the sign-out control and `selectBetterAuthError` after a failed sign-out.
57
+
58
+ ### Removed
59
+
60
+ - `@terreno/ui` no longer exports the `Filter` and `FilterProps` aliases deprecated in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps` instead. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names.
61
+
62
+ ### Fixed
63
+
64
+ - `@terreno/syncdb`: logging out while `syncDb.start()` is still running no longer loses local writes or logs errors. `start()` now resolves the web encryption key from `GET /sync/key` before it loads the store, so the flush in `stop()` never needs the network after the session has ended. A `stop()` or `signOut()` call now cancels a `start()` that is running or queued ahead of it, so the transport never connects without a session. A failed key fetch is now retried on the next save instead of failing every save for the rest of the session.
65
+
66
+ ## [57.21.0] - 2026-11-01
67
+
68
+ Upgrade note: [`mcp-server/src/docs/upgrades/57.21.0.md`](mcp-server/src/docs/upgrades/57.21.0.md).
69
+
70
+ ### Breaking
71
+
72
+ - The `terreno-scan` plugin is now `terreno-loop`, and its skills are renamed from `terreno-scan-*` to `terreno-loop-*`. The resident loop `terreno-scan-loop` is now `terreno-loop-run`: `/terreno-loop:run` in Claude Code, `/terreno-loop-run` in Cursor, `$terreno-loop-run` in Codex. Claude Code moves existing installs over through the marketplace `renames` entry. In Cursor and Codex, uninstall `terreno-scan` and install `terreno-loop`. Campaign state stays at `.terreno/scan/<goal>.json`, so campaigns already in progress resume.
73
+
74
+ ### Added
75
+
76
+ - `@terreno/admin-spa` serves an MCP OAuth consent screen at `/console/oauth/consent`, so a backend with no product frontend can set `mcpOAuth.consentUrl` to `${issuer}/console/oauth/consent`. Any signed-in user can approve or deny a request with their Better Auth session; signed-out users sign in and return through the login screen's new `returnTo` parameter, which accepts only in-app paths.
77
+ - Claude Code plugins now publish to npm with every release, as `@terreno/agent-plugin` and `@terreno/agent-plugin-loop`. A new `terreno-releases` marketplace installs them at the latest stable release. To pin one release, add `TerrenoLabs/terreno#<version>` instead. See [Install agent skills](docs/how-to/install-agent-skills.md#pick-a-channel).
78
+ - The generated Claude plugin manifest no longer pins `version`. Before this change, plugins installed from the `TerrenoLabs/terreno` marketplace stayed on the `2.12.0` copy, because their version never changed. They now update on every commit. Run `/plugin update terreno@terreno-plugins` once to leave `2.12.0`.
79
+ - The `terreno-planning` lifecycle plugin (2.13.0) plans e2e tests and manual regression cases in every IP:
80
+
81
+ - Grow requires `## E2E tests` and `## Regression cases` sections (either may be `None — <reason>`), read from the e2e guide at `docs/testing/e2e.md` or a `## Testing conventions` override in AGENTS.md or CLAUDE.md.
82
+ - Regression cases stay minimal: most features add none. A case is only for what a developer or QA must check by hand, such as push notifications, and Roast fails one that repeats an existing case.
83
+ - Pick writes each planned spec in the task that delivers it, and Roast runs it; a missing or failing row is `FAIL`.
84
+ - Brew gates on every planned spec and merges regression cases into `docs/regression/<area>.md` with the next free ID.
85
+ - Taste re-checks both sections after behaviour-changing fixes and renumbers regression ID collisions with `master`.
86
+ - `bun run check:lifecycle-skills` enforces these phrases in every stage.
87
+ - New `backfill-regression` skill proposes manual regression cases one area at a time and writes only the sets the human approves.
88
+ - A consumer opts out of manual regression suites with `Regression suites | none` in its `## Testing conventions` table.
89
+ - The `terreno-planning` lifecycle plugin (2.14.0) grows an end-user guide with every feature:
90
+
91
+ - Every IP has a `## User guide` section listing the guide pages it adds, updates, or retires, or `None — <reason>`. Pages live in `docs/user-guide/<area>/<feature>.md`, one feature per page, with `title`, `audience`, `platforms`, and `questions` frontmatter that chat agents use to answer "how do I…" questions.
92
+ - Pick writes each page in the task that ships the feature, Roast checks it against the shipped screens, Brew gates on it and the index, and Taste keeps it current after fixes.
93
+ - A repo opts out with `| User guide | none — <reason> |` in a `## User guide conventions` table in AGENTS.md or CLAUDE.md.
94
+ - New `backfill-user-guide` skill drafts pages for features that shipped without one, one area at a time, and writes only the pages the human approves.
95
+ - `bun run check:user-guide` validates the pages and index (CI `repo-policies`); `--uncovered <app dir>` lists screens no page names.
96
+ - Terreno's own guide covers the example app's main features.
97
+ - `@terreno/api`: opt-in `mcpRequestLog` on `TerrenoApp` records one metadata-only `McpRequestLog` row per MCP tool call (tool, user, credential, service token or OAuth client, duration, outcome, error class; never arguments, results, or error text), expiring after `retentionDays` (default 30).
98
+ - `@terreno/api`: opt-in `mcpToolSettings` on `TerrenoApp` registers every MCP tool in `McpToolSetting` at startup; tools an admin switches off are hidden from `tools/list` and rejected by `tools/call`.
99
+ - `@terreno/api`: deleting an `McpOAuthToken` row revokes its whole connection (token family) and keeps the rows. New `McpOAuthToken.revokeAllForUser` and `McpServiceToken.revokeAllForUser`.
100
+ - `@terreno/admin-backend`: `mcpAdminModels()` adds MCP admin screens (service tokens, OAuth clients, OAuth connections, request log, tool switches), `mcpAdminStatements` for RBAC, and `mcpAdminScripts()` adds `mcp-sign-out-everywhere`. See [Manage MCP from the admin panel](docs/how-to/manage-mcp-in-admin.md).
101
+ - Docs: [Expose an MCP server safely](docs/how-to/expose-mcp-server-safely.md) (OAuth, service tokens, Cloudflare Tunnel, Access) and the `bootstrap-mcp-server` skill for a single-binary MCP server with the admin console embedded.
102
+ - Every workspace package has a real-process smoke test and an e2e page:
103
+
104
+ - Each package's `e2e/smoke.ts` (or `smoke.spec.ts` for browser packages) runs its built output through its public entry: a server on a real port, the compiled binary, or a page in Chromium. `bun run --cwd <package> smoke` runs one; `bun run smoke` runs them all and prints each package's time. The CircleCI `smoke` job runs them on every package change.
105
+ - `@terreno/test` adds the smoke helpers `smokeMongoUri()`, `spawnUntilReady()`, `spawnExampleBackend()`, `runBin()`, and `freePort()`.
106
+ - The [E2E testing guide](docs/testing/e2e.md) explains the test tiers and links one page per package under `docs/testing/e2e/`.
107
+ - Manual regression cases live in `docs/regression/<area>.md`, one file per area, and `bun run check:regression-suites` validates them.
108
+ - example-frontend's smoke serves a web export that `bun run --cwd example-frontend export:smoke` builds once with a placeholder API URL; the smoke swaps in a `freePort()` API URL as it serves the bundle, so the 30 s smoke no longer rebuilds the export. `spawnUntilReady()` takes `stopGraceMs`, and `spawnExampleBackend()` stops example-backend after 0.5 s instead of 5 s.
109
+ - Every workspace package has a `typecheck` script that runs `tsc` over source and test files through a new `tsconfig.typecheck.json`. Root `bun run lint` ends with `bun run typecheck`, and CircleCI runs it in a new `typecheck` job. Test files that had type errors were fixed.
110
+
111
+ ### Changed
112
+
113
+ - `@terreno/api`: deleting an `McpOAuthToken` row with document or query `deleteOne` now revokes that row's whole token family (the connection) and keeps the rows instead of removing one pair. `deleteMany` is unchanged.
114
+ - `@terreno/ui`: new `theme.field` tokens (`background`, `backgroundDisabled`, `border`, `borderFocus`, `borderError`, `borderDisabled`) style form inputs. `TextField`, `SelectField`, `DateTimeField`, `HeightField`, and `OtpField` read them instead of `surface.base` and `border.dark`. Defaults equal the old colors, but overriding `surface` or `border` no longer recolors those fields; use `setTheme({field: ...})`.
115
+
23
116
  ## [57.20.0] - 2026-10-30
24
117
 
25
118
  Upgrade note: [`mcp-server/src/docs/upgrades/57.20.0.md`](mcp-server/src/docs/upgrades/57.20.0.md).
package/biome.jsonc CHANGED
@@ -1,5 +1,4 @@
1
1
  {
2
- "root": true,
3
2
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
4
3
  "extends": ["../biome.jsonc"],
5
4
  "files": {
@@ -7,6 +6,7 @@
7
6
  "package.json",
8
7
  "src/**/*.ts",
9
8
  "src/**/*.tsx",
9
+ "e2e/**/*.ts",
10
10
  "!!**/node_modules",
11
11
  "!!node_modules",
12
12
  "!!**/dist",
@@ -16,5 +16,6 @@
16
16
  "!!**/coverage",
17
17
  "!!coverage"
18
18
  ]
19
- }
19
+ },
20
+ "root": true
20
21
  }
package/dist/aiApp.d.ts CHANGED
@@ -32,7 +32,10 @@ export interface AiAppOptions {
32
32
  maxSteps?: number;
33
33
  /** MCP service for connecting to external tool servers. */
34
34
  mcpService?: MCPService;
35
- /** OpenAPI options passed through to route builders for spec generation. */
35
+ /**
36
+ * OpenAPI options passed through to route builders for spec generation. Defaults to the
37
+ * OpenAPI instance TerrenoApp passes to `register`.
38
+ */
36
39
  openApiOptions?: Record<string, unknown>;
37
40
  /**
38
41
  * Mount the `/gpt/projects` routes, which register the `Project` model. Defaults to `true`;
@@ -75,5 +78,5 @@ export interface AiAppOptions {
75
78
  export declare class AiApp implements TerrenoPlugin {
76
79
  private options;
77
80
  constructor(options: AiAppOptions);
78
- register(app: express.Application): void;
81
+ register(app: express.Application, openApi?: unknown): void;
79
82
  }
package/dist/aiApp.js CHANGED
@@ -38,9 +38,10 @@ class AiApp {
38
38
  constructor(options) {
39
39
  this.options = options;
40
40
  }
41
- register(app) {
41
+ register(app, openApi) {
42
42
  const router = app;
43
- const { aiService, asks, createModelFn, createServerModelFn, demoMode, fileStorageService, fileUploadsEnabled, gcsBucket, maxSteps, mcpService, openApiOptions, projects, titleModelId, toolChoice, tools, } = this.options;
43
+ const { aiService, asks, createModelFn, createServerModelFn, demoMode, fileStorageService, fileUploadsEnabled, gcsBucket, maxSteps, mcpService, projects, titleModelId, toolChoice, tools, } = this.options;
44
+ const openApiOptions = this.options.openApiOptions ?? (openApi ? { openApi } : undefined);
44
45
  const hasFileRoutes = Boolean(fileStorageService && gcsBucket);
45
46
  const chat = {
46
47
  aiService,
@@ -403,6 +403,7 @@ const createAgentTasks = (context) => {
403
403
  }
404
404
  let returned;
405
405
  try {
406
+ // `args.data` was parsed by this tool's own `parameters`, which match its `execute` args.
406
407
  returned = await tool.execute(args.data, {
407
408
  conversationId,
408
409
  env: rt.env,
package/dist/index.d.ts CHANGED
@@ -12,6 +12,7 @@ export { compilePrompt, createPrompt, getPrompt, invalidatePromptCache } from ".
12
12
  export { initTracing, shutdownTracing } from "./langfuseTracing";
13
13
  export type { ChatMessage, GetPromptOptions, LangfuseAppOptions, LangfuseCachedPrompt, PaginatedResult, PreparePromptResult, PromptListItem, ScoreSubmission, ScoringFunction, TelemetrySettings, TraceListItem, } from "./langfuseTypes";
14
14
  export { createTelemetryConfig, preparePromptForAI } from "./langfuseVercelAi";
15
+ export { GPT_HISTORY_STRING_IDS_MIGRATION, type GptHistoryStringIdsResult, gptHistoryStringIdsMigration, migrateGptHistoryStringIds, } from "./migrations/gptHistoryStringIds";
15
16
  export { AIDataset } from "./models/aiDataset";
16
17
  export { AIRequest } from "./models/aiRequest";
17
18
  export { FileAttachment } from "./models/fileAttachment";
@@ -31,7 +32,7 @@ export { buildObservabilityStatus, buildPlaygroundAiStatus, isLocalObservability
31
32
  export type { ControlPrimary, ObservabilityAiServiceFactory, ObservabilityAppOptions, ObservabilityCapability, ObservabilityControlConfig, ObservabilityGenerateClient, ObservabilityPlugin, ObservabilityRequestAiServiceFactory, PromptRegistry, ReviewQueue, ScoreRecord, ScoreSink, SpanRecord, TraceExportResult, TraceRecord, TraceSink, } from "./observability/types";
32
33
  export { DEFAULT_OBSERVABILITY_CONTROL, resolveObservabilityControl, validateObservabilityConfig, } from "./observability/types";
33
34
  export { addAiRequestsExplorerRoutes } from "./routes/aiRequestsExplorer";
34
- export { addFileRoutes } from "./routes/files";
35
+ export { addFileRoutes, type FileStorageServiceSource } from "./routes/files";
35
36
  export { addGptRoutes } from "./routes/gpt";
36
37
  export { addGptHistoryRoutes } from "./routes/gptHistories";
37
38
  export { addMcpRoutes } from "./routes/mcp";
package/dist/index.js CHANGED
@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
14
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
- exports.validateObservabilityConfig = exports.resolveObservabilityControl = exports.DEFAULT_OBSERVABILITY_CONTROL = exports.isLocalObservabilityPluginOn = exports.buildPlaygroundAiStatus = exports.buildObservabilityStatus = exports.resetObservabilityApp = exports.ObservabilityApp = exports.getObservabilityApp = exports.MemoryTraceSink = exports.MemoryScoreSink = exports.LocalTraceStore = exports.LocalTraceSink = exports.LocalScoreSink = exports.LocalReviewStore = exports.LocalPromptStore = exports.createLocalObservabilityPlugin = exports.createLocalObservabilityBundle = exports.LocalExperimentRunner = exports.LocalEvaluatorStore = exports.LocalDatasetStore = exports.observabilityAdminScreens = exports.AI_OBSERVABILITY_GROUP = exports.Project = exports.getProjectModel = exports.GptHistory = exports.FileAttachment = exports.AIRequest = exports.AIDataset = exports.preparePromptForAI = exports.createTelemetryConfig = exports.shutdownTracing = exports.initTracing = exports.invalidatePromptCache = exports.getPrompt = exports.createPrompt = exports.compilePrompt = exports.shutdownLangfuseClient = exports.isLangfuseInitialized = exports.initLangfuseClient = exports.getLangfuseClient = exports.setCached = exports.LangfuseCache = exports.invalidateCache = exports.getCached = exports.LangfuseApp = exports.AiApp = exports.AIAdminApp = exports.Output = exports.jsonSchema = void 0;
18
- exports.verifyVertexModelsEnabled = exports.normalizeVertexModelId = exports.listEnabledVertexModels = exports.isVertexModelAllowed = exports.DEFAULT_VERTEX_LOCATION = exports.createVertexProvider = exports.assertVertexModelsEnabled = exports.toggleChecklistHostAction = exports.scaleStepperHostAction = exports.TRANSLATION_PROMPT = exports.TITLE_GENERATION_PROMPT = exports.TERRENO_ASKS_SYSTEM_PROMPT = exports.REMIX_PROMPT = exports.JSON_VALUE_SYSTEM_PROMPT = exports.DEFAULT_GPT_MEMORY = exports.CONTENT_SUMMARY_PROMPT = exports.COMPACT_SURFACE_SYSTEM_PROMPT = exports.parseAiJson = exports.normalizeLlmJsonTextForStructuredOutput = exports.MCPService = exports.getMCPTools = exports.normalizeGeminiModelId = exports.listGeminiApiModels = exports.GEMINI_API_BASE_URL = exports.FileStorageService = exports.runBufferedChatTurn = exports.createAskTools = exports.TemperaturePresets = exports.AIService = exports.registerAiDataset = exports.configureAiDatasets = exports.findAgentBlock = exports.addProjectRoutes = exports.addMcpRoutes = exports.addGptHistoryRoutes = exports.addGptRoutes = exports.addFileRoutes = exports.addAiRequestsExplorerRoutes = void 0;
17
+ exports.isLocalObservabilityPluginOn = exports.buildPlaygroundAiStatus = exports.buildObservabilityStatus = exports.resetObservabilityApp = exports.ObservabilityApp = exports.getObservabilityApp = exports.MemoryTraceSink = exports.MemoryScoreSink = exports.LocalTraceStore = exports.LocalTraceSink = exports.LocalScoreSink = exports.LocalReviewStore = exports.LocalPromptStore = exports.createLocalObservabilityPlugin = exports.createLocalObservabilityBundle = exports.LocalExperimentRunner = exports.LocalEvaluatorStore = exports.LocalDatasetStore = exports.observabilityAdminScreens = exports.AI_OBSERVABILITY_GROUP = exports.Project = exports.getProjectModel = exports.GptHistory = exports.FileAttachment = exports.AIRequest = exports.AIDataset = exports.migrateGptHistoryStringIds = exports.gptHistoryStringIdsMigration = exports.GPT_HISTORY_STRING_IDS_MIGRATION = exports.preparePromptForAI = exports.createTelemetryConfig = exports.shutdownTracing = exports.initTracing = exports.invalidatePromptCache = exports.getPrompt = exports.createPrompt = exports.compilePrompt = exports.shutdownLangfuseClient = exports.isLangfuseInitialized = exports.initLangfuseClient = exports.getLangfuseClient = exports.setCached = exports.LangfuseCache = exports.invalidateCache = exports.getCached = exports.LangfuseApp = exports.AiApp = exports.AIAdminApp = exports.Output = exports.jsonSchema = void 0;
18
+ exports.verifyVertexModelsEnabled = exports.normalizeVertexModelId = exports.listEnabledVertexModels = exports.isVertexModelAllowed = exports.DEFAULT_VERTEX_LOCATION = exports.createVertexProvider = exports.assertVertexModelsEnabled = exports.toggleChecklistHostAction = exports.scaleStepperHostAction = exports.TRANSLATION_PROMPT = exports.TITLE_GENERATION_PROMPT = exports.TERRENO_ASKS_SYSTEM_PROMPT = exports.REMIX_PROMPT = exports.JSON_VALUE_SYSTEM_PROMPT = exports.DEFAULT_GPT_MEMORY = exports.CONTENT_SUMMARY_PROMPT = exports.COMPACT_SURFACE_SYSTEM_PROMPT = exports.parseAiJson = exports.normalizeLlmJsonTextForStructuredOutput = exports.MCPService = exports.getMCPTools = exports.normalizeGeminiModelId = exports.listGeminiApiModels = exports.GEMINI_API_BASE_URL = exports.FileStorageService = exports.runBufferedChatTurn = exports.createAskTools = exports.TemperaturePresets = exports.AIService = exports.registerAiDataset = exports.configureAiDatasets = exports.findAgentBlock = exports.addProjectRoutes = exports.addMcpRoutes = exports.addGptHistoryRoutes = exports.addGptRoutes = exports.addFileRoutes = exports.addAiRequestsExplorerRoutes = exports.validateObservabilityConfig = exports.resolveObservabilityControl = exports.DEFAULT_OBSERVABILITY_CONTROL = void 0;
19
19
  var ai_1 = require("ai");
20
20
  Object.defineProperty(exports, "jsonSchema", { enumerable: true, get: function () { return ai_1.jsonSchema; } });
21
21
  Object.defineProperty(exports, "Output", { enumerable: true, get: function () { return ai_1.Output; } });
@@ -46,6 +46,10 @@ Object.defineProperty(exports, "shutdownTracing", { enumerable: true, get: funct
46
46
  var langfuseVercelAi_1 = require("./langfuseVercelAi");
47
47
  Object.defineProperty(exports, "createTelemetryConfig", { enumerable: true, get: function () { return langfuseVercelAi_1.createTelemetryConfig; } });
48
48
  Object.defineProperty(exports, "preparePromptForAI", { enumerable: true, get: function () { return langfuseVercelAi_1.preparePromptForAI; } });
49
+ var gptHistoryStringIds_1 = require("./migrations/gptHistoryStringIds");
50
+ Object.defineProperty(exports, "GPT_HISTORY_STRING_IDS_MIGRATION", { enumerable: true, get: function () { return gptHistoryStringIds_1.GPT_HISTORY_STRING_IDS_MIGRATION; } });
51
+ Object.defineProperty(exports, "gptHistoryStringIdsMigration", { enumerable: true, get: function () { return gptHistoryStringIds_1.gptHistoryStringIdsMigration; } });
52
+ Object.defineProperty(exports, "migrateGptHistoryStringIds", { enumerable: true, get: function () { return gptHistoryStringIds_1.migrateGptHistoryStringIds; } });
49
53
  var aiDataset_1 = require("./models/aiDataset");
50
54
  Object.defineProperty(exports, "AIDataset", { enumerable: true, get: function () { return aiDataset_1.AIDataset; } });
51
55
  var aiRequest_1 = require("./models/aiRequest");
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Data migration for Terreno 58: GptHistory became a synced collection with String `_id`s.
3
+ * Histories saved before 58 have ObjectId `_id`s, which sync clients and the String-typed
4
+ * schema cannot address. This migration re-inserts each one with `_id` set to the same id's
5
+ * hex string, so URLs and client caches that hold the hex id keep working, rewrites
6
+ * `AIDataset.historyId` refs to that hex string, and then deletes the ObjectId originals.
7
+ *
8
+ * It writes through the native driver: `syncPlugin` forbids the hard deletes and
9
+ * multi-document writes a move needs, and the copies keep every stored field as-is.
10
+ * Running it again is a no-op.
11
+ */
12
+ import type { MigrationContext, MigrationLogger } from "@terreno/api";
13
+ import type mongoose from "mongoose";
14
+ /** Slug for the timestamped file an app adds to its `migrations/` directory. */
15
+ export declare const GPT_HISTORY_STRING_IDS_MIGRATION = "gpt-history-string-ids";
16
+ export interface GptHistoryStringIdsResult {
17
+ /** AIDataset rows whose ObjectId `historyId` was rewritten (or would be, in a dry run). */
18
+ datasetsUpdated: number;
19
+ /** Histories moved to a String `_id` (or that would move, in a dry run). */
20
+ historiesMigrated: number;
21
+ }
22
+ /**
23
+ * Moves every ObjectId-id GptHistory to its hex-string id in batches and rewrites the
24
+ * AIDataset refs. In a dry run it only counts what it would change.
25
+ */
26
+ export declare const migrateGptHistoryStringIds: ({ batchSize, checkCancellation, connection, dryRun, logger, }: {
27
+ batchSize?: number;
28
+ checkCancellation?: () => Promise<void>;
29
+ connection: mongoose.Connection;
30
+ dryRun: boolean;
31
+ logger?: MigrationLogger;
32
+ }) => Promise<GptHistoryStringIdsResult>;
33
+ /**
34
+ * Ready-made `up` for an app's `migrations/<YYYYMMDDHHmmss>-gpt-history-string-ids.ts` file.
35
+ * Run it before deploying Terreno 58 frontends, which address histories by String id. It has
36
+ * no `down`: new histories get UUIDs, which have no ObjectId to go back to.
37
+ */
38
+ export declare const gptHistoryStringIdsMigration: {
39
+ slug: string;
40
+ up: (ctx: MigrationContext) => Promise<void>;
41
+ };
@@ -0,0 +1,94 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.gptHistoryStringIdsMigration = exports.migrateGptHistoryStringIds = exports.GPT_HISTORY_STRING_IDS_MIGRATION = void 0;
4
+ const aiDataset_1 = require("../models/aiDataset");
5
+ const gptHistory_1 = require("../models/gptHistory");
6
+ /** Slug for the timestamped file an app adds to its `migrations/` directory. */
7
+ exports.GPT_HISTORY_STRING_IDS_MIGRATION = "gpt-history-string-ids";
8
+ const DEFAULT_BATCH_SIZE = 500;
9
+ const DUPLICATE_KEY_CODE = 11000;
10
+ /** Only ObjectId `_id`s still need a move; String ids are already migrated or new. */
11
+ const OBJECT_ID_FILTER = { _id: { $type: "objectId" } };
12
+ /** Server-side ObjectId → hex string, so refs move without reading each dataset. */
13
+ const HISTORY_ID_TO_STRING = [{ $set: { historyId: { $toString: "$historyId" } } }];
14
+ /** An insert that failed only because the hex-id copy exists from an interrupted earlier run. */
15
+ const isOnlyDuplicateKeyError = (error) => {
16
+ const writeError = error;
17
+ if (writeError.writeErrors?.length) {
18
+ return writeError.writeErrors.every((item) => item.code === DUPLICATE_KEY_CODE);
19
+ }
20
+ return writeError.code === DUPLICATE_KEY_CODE;
21
+ };
22
+ const insertCopies = async ({ collection, copies, }) => {
23
+ try {
24
+ await collection.insertMany(copies, { ordered: false });
25
+ }
26
+ catch (error) {
27
+ if (!isOnlyDuplicateKeyError(error)) {
28
+ throw error;
29
+ }
30
+ }
31
+ };
32
+ /**
33
+ * Moves every ObjectId-id GptHistory to its hex-string id in batches and rewrites the
34
+ * AIDataset refs. In a dry run it only counts what it would change.
35
+ */
36
+ const migrateGptHistoryStringIds = async ({ batchSize = DEFAULT_BATCH_SIZE, checkCancellation, connection, dryRun, logger, }) => {
37
+ const histories = connection.collection(gptHistory_1.GptHistory.collection.collectionName);
38
+ const datasets = connection.collection(aiDataset_1.AIDataset.collection.collectionName);
39
+ const datasetFilter = { historyId: { $type: "objectId" } };
40
+ if (dryRun) {
41
+ const result = {
42
+ datasetsUpdated: await datasets.countDocuments(datasetFilter),
43
+ historiesMigrated: await histories.countDocuments(OBJECT_ID_FILTER),
44
+ };
45
+ logger?.info(`[${exports.GPT_HISTORY_STRING_IDS_MIGRATION}] dry run`, result);
46
+ return result;
47
+ }
48
+ let historiesMigrated = 0;
49
+ let datasetsUpdated = 0;
50
+ while (true) {
51
+ await checkCancellation?.();
52
+ const batch = await histories.find(OBJECT_ID_FILTER).limit(batchSize).toArray();
53
+ if (batch.length === 0) {
54
+ break;
55
+ }
56
+ const originalIds = batch.map((doc) => doc._id);
57
+ // Copy first and delete second, so an interrupted run never loses a history: the next
58
+ // run finds the original again and the copy's duplicate key is ignored.
59
+ await insertCopies({
60
+ collection: histories,
61
+ copies: batch.map((doc) => ({ ...doc, _id: String(doc._id) })),
62
+ });
63
+ const moved = await datasets.updateMany({ historyId: { $in: originalIds } }, HISTORY_ID_TO_STRING);
64
+ datasetsUpdated += moved.modifiedCount;
65
+ await histories.deleteMany({ _id: { $in: originalIds } });
66
+ historiesMigrated += batch.length;
67
+ logger?.info(`[${exports.GPT_HISTORY_STRING_IDS_MIGRATION}] moved ${historiesMigrated} histories to String ids`);
68
+ }
69
+ // Refs whose history was moved by an interrupted run, or never existed, still hold ObjectIds.
70
+ const remaining = await datasets.updateMany(datasetFilter, HISTORY_ID_TO_STRING);
71
+ datasetsUpdated += remaining.modifiedCount;
72
+ const result = { datasetsUpdated, historiesMigrated };
73
+ logger?.info(`[${exports.GPT_HISTORY_STRING_IDS_MIGRATION}] done`, result);
74
+ return result;
75
+ };
76
+ exports.migrateGptHistoryStringIds = migrateGptHistoryStringIds;
77
+ /**
78
+ * Ready-made `up` for an app's `migrations/<YYYYMMDDHHmmss>-gpt-history-string-ids.ts` file.
79
+ * Run it before deploying Terreno 58 frontends, which address histories by String id. It has
80
+ * no `down`: new histories get UUIDs, which have no ObjectId to go back to.
81
+ */
82
+ exports.gptHistoryStringIdsMigration = {
83
+ slug: exports.GPT_HISTORY_STRING_IDS_MIGRATION,
84
+ up: async (ctx) => {
85
+ const result = await (0, exports.migrateGptHistoryStringIds)({
86
+ checkCancellation: ctx.checkCancellation,
87
+ connection: ctx.mongoose.connection,
88
+ dryRun: ctx.dryRun,
89
+ logger: ctx.logger,
90
+ });
91
+ await ctx.addLog?.("info", `[${exports.GPT_HISTORY_STRING_IDS_MIGRATION}] ${ctx.dryRun ? "would move" : "moved"} ` +
92
+ `${result.historiesMigrated} histories and ${result.datasetsUpdated} dataset refs`);
93
+ },
94
+ };
@@ -30,11 +30,11 @@ const aiDatasetSchema = new mongoose_1.default.Schema({
30
30
  type: Date,
31
31
  },
32
32
  historyId: {
33
- description: "The conversation whose tool stored these rows",
33
+ description: "The conversation whose tool stored these rows (a GptHistory String id)",
34
34
  index: true,
35
35
  ref: "GptHistory",
36
36
  required: true,
37
- type: mongoose_1.default.Schema.Types.ObjectId,
37
+ type: String,
38
38
  },
39
39
  rowCount: {
40
40
  description: "How many rows were stored",
@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.GptHistory = void 0;
7
+ const node_crypto_1 = require("node:crypto");
7
8
  const api_1 = require("@terreno/api");
8
9
  const blocks_1 = require("@terreno/blocks");
9
10
  const mongoose_1 = __importDefault(require("mongoose"));
@@ -132,6 +133,14 @@ const gptHistoryPromptSchema = new mongoose_1.default.Schema({
132
133
  },
133
134
  }, { _id: false, strict: "throw" });
134
135
  const gptHistorySchema = new mongoose_1.default.Schema({
136
+ _id: {
137
+ // Synced through @terreno/syncdb: offline clients mint entity ids locally and the sync
138
+ // mutation channel writes them through as _id. Histories created before Terreno 58 keep
139
+ // their ObjectId hex string after the gpt-history-string-ids migration.
140
+ default: () => (0, node_crypto_1.randomUUID)(),
141
+ description: "The conversation id (a String so offline sync clients can mint ids)",
142
+ type: String,
143
+ },
135
144
  pendingAsk: {
136
145
  description: "The ask this conversation is waiting on; cleared when the user answers or the ask is cancelled",
137
146
  type: pendingAskSchema,
@@ -160,6 +169,8 @@ gptHistorySchema.plugin(api_1.createdUpdatedPlugin);
160
169
  gptHistorySchema.plugin(api_1.isDeletedPlugin);
161
170
  gptHistorySchema.plugin(api_1.findOneOrNone);
162
171
  gptHistorySchema.plugin(api_1.findExactlyOne);
172
+ // Stamps a per-stream _syncSeq on every write; required by the /gpt/histories sync config.
173
+ gptHistorySchema.plugin(api_1.syncPlugin);
163
174
  // Virtual ownerId alias so Permissions.IsOwner works with userId field
164
175
  gptHistorySchema.virtual("ownerId").get(function () {
165
176
  return this.userId;
@@ -2,7 +2,7 @@ import type { ExperimentAggregates, ExperimentEstimate, ExperimentVersionResult,
2
2
  import type { ModelPrice, ObservabilityAiServiceFactory, ObservabilityGenerateClient } from "../types";
3
3
  import type { LocalDatasetStore } from "./datasetStore";
4
4
  import type { LocalEvaluatorStore } from "./evaluatorStore";
5
- import type { LocalPromptStore } from "./promptStore";
5
+ import type { LocalPromptStore, MoveLabelResult } from "./promptStore";
6
6
  export interface ExperimentCreateInput {
7
7
  datasetId: string;
8
8
  evaluatorIds: string[];
@@ -87,10 +87,7 @@ export declare class LocalExperimentRunner {
87
87
  }): Promise<ExperimentListResult>;
88
88
  get(id: string): Promise<ExperimentView>;
89
89
  private toSummaryView;
90
- promote(id: string, version: number): Promise<{
91
- label: string;
92
- outgoingVersion?: number;
93
- }>;
90
+ promote(id: string, version: number): Promise<MoveLabelResult>;
94
91
  executeExperiment(id: string): Promise<void>;
95
92
  private computeGates;
96
93
  }
@@ -1,6 +1,12 @@
1
1
  import type express from "express";
2
2
  import type { FileStorageService } from "../service/fileStorage";
3
3
  import type { FileRouteOptions } from "../types";
4
+ /**
5
+ * A storage service, or a function that returns the current one. Pass a function when storage
6
+ * can be configured or cleared at runtime: the routes stay mounted (and documented in OpenAPI)
7
+ * and answer 503 while it returns `undefined`.
8
+ */
9
+ export type FileStorageServiceSource = FileStorageService | (() => FileStorageService | undefined);
4
10
  export declare const addFileRoutes: (router: express.Router, options: FileRouteOptions & {
5
- fileStorageService: FileStorageService;
11
+ fileStorageService: FileStorageServiceSource;
6
12
  }) => void;