@caelo-cms/shared 0.12.10 → 0.12.11

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 (55) hide show
  1. package/dist/ai-cost.d.ts +146 -0
  2. package/dist/ai-cost.d.ts.map +1 -0
  3. package/dist/ai-cost.js +182 -0
  4. package/dist/ai-cost.js.map +1 -0
  5. package/dist/ai-tools.d.ts +1 -1
  6. package/dist/build-page.d.ts +2 -2
  7. package/dist/cap-failures.d.ts.map +1 -1
  8. package/dist/cap-failures.js +7 -5
  9. package/dist/cap-failures.js.map +1 -1
  10. package/dist/change-journal.d.ts.map +1 -1
  11. package/dist/change-journal.js +13 -0
  12. package/dist/change-journal.js.map +1 -1
  13. package/dist/content.d.ts +3 -3
  14. package/dist/embedding-models.d.ts +95 -0
  15. package/dist/embedding-models.d.ts.map +1 -0
  16. package/dist/embedding-models.js +60 -0
  17. package/dist/embedding-models.js.map +1 -0
  18. package/dist/index.d.ts +4 -0
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +4 -0
  21. package/dist/index.js.map +1 -1
  22. package/dist/module-id-tag.d.ts +13 -0
  23. package/dist/module-id-tag.d.ts.map +1 -1
  24. package/dist/module-id-tag.js +24 -2
  25. package/dist/module-id-tag.js.map +1 -1
  26. package/dist/preview-compose.d.ts +6 -0
  27. package/dist/preview-compose.d.ts.map +1 -1
  28. package/dist/preview-compose.js +9 -3
  29. package/dist/preview-compose.js.map +1 -1
  30. package/dist/site-security-headers.d.ts +2 -2
  31. package/dist/stage-status.d.ts +10 -5
  32. package/dist/stage-status.d.ts.map +1 -1
  33. package/dist/stage-status.js +27 -1
  34. package/dist/stage-status.js.map +1 -1
  35. package/dist/version.d.ts +2 -2
  36. package/dist/version.js +1 -1
  37. package/dist/visitor-ai-origin.d.ts +41 -0
  38. package/dist/visitor-ai-origin.d.ts.map +1 -0
  39. package/dist/visitor-ai-origin.js +65 -0
  40. package/dist/visitor-ai-origin.js.map +1 -0
  41. package/package.json +8 -1
  42. package/src/ai-cost.test.ts +81 -0
  43. package/src/ai-cost.ts +288 -0
  44. package/src/cap-failures.ts +7 -5
  45. package/src/change-journal.ts +25 -0
  46. package/src/embedding-models.test.ts +37 -0
  47. package/src/embedding-models.ts +147 -0
  48. package/src/index.ts +8 -0
  49. package/src/module-id-tag.test.ts +27 -1
  50. package/src/module-id-tag.ts +29 -2
  51. package/src/preview-compose.test.ts +21 -0
  52. package/src/preview-compose.ts +20 -3
  53. package/src/stage-status.ts +29 -1
  54. package/src/version.ts +1 -1
  55. package/src/visitor-ai-origin.ts +86 -0
@@ -0,0 +1,65 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+ /**
3
+ * Where a visitor's browser streams an AI conversation from (#1654).
4
+ *
5
+ * On `gcp` (load balancer) and self-hosted (Caddy) the site's own origin
6
+ * streams: `/api/*` reaches the gateway unbuffered. On `gcp-firebase` the
7
+ * Firebase Hosting rewrite of `/api/**` buffers a response until it ends,
8
+ * so the widget streams from the gateway's own run.app origin instead
9
+ * (with CORS for the site's origins), the one Cloud Run gives every
10
+ * service: `https://<service>-<project number>.<region>.run.app`.
11
+ *
12
+ * Nothing about it is configured: the service name and region are the
13
+ * env the install already sets (`CAELO_GATEWAY_SERVICE`,
14
+ * `CAELO_GATEWAY_REGION` on the admin; Cloud Run's own `K_SERVICE` on a
15
+ * gateway), the project number and region come from the metadata server
16
+ * of the Cloud Run instance. `CAELO_VISITOR_AI_STREAM_ORIGIN` overrides
17
+ * everything (tests, an install behind its own streaming proxy); an empty
18
+ * value means the site's own origin.
19
+ */
20
+ /** The override; empty: the site's own origin. */
21
+ export const VISITOR_AI_STREAM_ORIGIN_ENV = "CAELO_VISITOR_AI_STREAM_ORIGIN";
22
+ /** The deterministic URL Cloud Run gives a service. */
23
+ export function cloudRunServiceOrigin(service, projectNumber, region) {
24
+ if (!/^[a-z][a-z0-9-]{0,62}$/.test(service) ||
25
+ !/^\d{1,20}$/.test(projectNumber) ||
26
+ !/^[a-z]+-[a-z]+\d+$/.test(region))
27
+ throw new Error(`not a Cloud Run service address: ${service} / ${projectNumber} / ${region}`);
28
+ return `https://${service}-${projectNumber}.${region}.run.app`;
29
+ }
30
+ /** The project number and region of this Cloud Run instance, from the metadata server. */
31
+ export async function cloudRunInstanceLocation(fetchFn = fetch) {
32
+ const res = await fetchFn("http://metadata.google.internal/computeMetadata/v1/instance/region", {
33
+ headers: { "Metadata-Flavor": "Google" },
34
+ signal: AbortSignal.timeout(3000),
35
+ });
36
+ if (!res.ok)
37
+ throw new Error(`metadata server: instance/region returned HTTP ${res.status}`);
38
+ // projects/<number>/regions/<region>
39
+ const m = /^projects\/(\d+)\/regions\/([a-z]+-[a-z]+\d+)$/.exec((await res.text()).trim());
40
+ if (!m)
41
+ throw new Error("metadata server: instance/region has an unknown shape");
42
+ return { projectNumber: m[1], region: m[2] };
43
+ }
44
+ /**
45
+ * The origin to stream from, or null for the site's own. `service` and
46
+ * `region` name the gateway (the admin's env); without `region` the
47
+ * instance's own (a gateway asking about itself). The staging gateway
48
+ * always streams on its own origin: it serves the staged site itself, with
49
+ * no Firebase rewrite in front to buffer, and its gate admits only requests
50
+ * carrying the operator's staging cookie, which a run.app request would not.
51
+ */
52
+ export async function visitorAiStreamOrigin(env, gateway, fetchFn = fetch) {
53
+ const override = env[VISITOR_AI_STREAM_ORIGIN_ENV];
54
+ if (override !== undefined)
55
+ return override.trim() === "" ? null : new URL(override).origin;
56
+ if (gateway.environment === "staging")
57
+ return null;
58
+ if (env.CAELO_PROVIDER !== "gcp-firebase")
59
+ return null;
60
+ if (!gateway.service)
61
+ throw new Error("gcp-firebase: the gateway's Cloud Run service is not named (CAELO_GATEWAY_SERVICE on the admin, K_SERVICE on the gateway); run `cms-provision upgrade`");
62
+ const where = await cloudRunInstanceLocation(fetchFn);
63
+ return cloudRunServiceOrigin(gateway.service, where.projectNumber, gateway.region ?? where.region);
64
+ }
65
+ //# sourceMappingURL=visitor-ai-origin.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"visitor-ai-origin.js","sourceRoot":"","sources":["../src/visitor-ai-origin.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;;;;;GAiBG;AAEH,kDAAkD;AAClD,MAAM,CAAC,MAAM,4BAA4B,GAAG,gCAAgC,CAAC;AAE7E,uDAAuD;AACvD,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,aAAqB,EACrB,MAAc;IAEd,IACE,CAAC,wBAAwB,CAAC,IAAI,CAAC,OAAO,CAAC;QACvC,CAAC,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC;QACjC,CAAC,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC;QAElC,MAAM,IAAI,KAAK,CAAC,oCAAoC,OAAO,MAAM,aAAa,MAAM,MAAM,EAAE,CAAC,CAAC;IAChG,OAAO,WAAW,OAAO,IAAI,aAAa,IAAI,MAAM,UAAU,CAAC;AACjE,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,UAAwB,KAAK;IAE7B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,oEAAoE,EAAE;QAC9F,OAAO,EAAE,EAAE,iBAAiB,EAAE,QAAQ,EAAE;QACxC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;KAClC,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7F,qCAAqC;IACrC,MAAM,CAAC,GAAG,gDAAgD,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3F,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IACjF,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,CAAW,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAW,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,GAAiD,EACjD,OAIC,EACD,UAAwB,KAAK;IAE7B,MAAM,QAAQ,GAAG,GAAG,CAAC,4BAA4B,CAAC,CAAC;IACnD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;IAC5F,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,GAAG,CAAC,cAAc,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,CAAC,OAAO,CAAC,OAAO;QAClB,MAAM,IAAI,KAAK,CACb,wJAAwJ,CACzJ,CAAC;IACJ,MAAM,KAAK,GAAG,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC;IACtD,OAAO,qBAAqB,CAC1B,OAAO,CAAC,OAAO,EACf,KAAK,CAAC,aAAa,EACnB,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,CAC/B,CAAC;AACJ,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@caelo-cms/shared",
3
- "version": "0.12.10",
3
+ "version": "0.12.11",
4
4
  "private": false,
5
5
  "license": "MPL-2.0",
6
6
  "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",
@@ -28,6 +28,13 @@
28
28
  "development": "./src/lists/model.ts",
29
29
  "import": "./dist/lists/model.js",
30
30
  "default": "./dist/lists/model.js"
31
+ },
32
+ "./embedding-models": {
33
+ "types": "./dist/embedding-models.d.ts",
34
+ "bun": "./src/embedding-models.ts",
35
+ "development": "./src/embedding-models.ts",
36
+ "import": "./dist/embedding-models.js",
37
+ "default": "./dist/embedding-models.js"
31
38
  }
32
39
  },
33
40
  "files": [
@@ -0,0 +1,81 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ import { describe, expect, it } from "bun:test";
4
+ import {
5
+ computeAiCallCostMicrocents,
6
+ IMAGE_TOKEN_BOUND,
7
+ PROVIDER_REQUEST_OVERHEAD_TOKENS,
8
+ promptTokenBound,
9
+ tokenBoundOf,
10
+ worstCaseTextMicrocents,
11
+ } from "./ai-cost.js";
12
+
13
+ describe("worstCaseTextMicrocents (#1653)", () => {
14
+ const pricing = {
15
+ inputMicrocents: 300,
16
+ outputMicrocents: 1500,
17
+ cachedMicrocents: 30,
18
+ cacheCreationMicrocents: 375,
19
+ longPromptThresholdTokens: null,
20
+ longPromptMultiplier: null,
21
+ };
22
+
23
+ it("bills every prompt token at the dearest input lane and the whole output ceiling", () => {
24
+ // 10,000 × 375/1K + 2,000 × 1,500/1K = 3,750 + 3,000.
25
+ expect(worstCaseTextMicrocents(pricing, { promptTokens: 10_000, maxOutputTokens: 2_000 })).toBe(
26
+ 6_750,
27
+ );
28
+ });
29
+
30
+ it("is never below the real cost of a call inside its bounds", () => {
31
+ const real = computeAiCallCostMicrocents(pricing, {
32
+ operationType: "text",
33
+ inputTokens: 10_000,
34
+ outputTokens: 2_000,
35
+ cachedTokens: 4_000,
36
+ cacheCreationTokens: 6_000,
37
+ imageCount: 0,
38
+ }).costMicrocents;
39
+ expect(
40
+ worstCaseTextMicrocents(pricing, { promptTokens: 10_000, maxOutputTokens: 2_000 }),
41
+ ).toBeGreaterThanOrEqual(real);
42
+ });
43
+
44
+ it("takes the prompt-length card when the bound crosses its threshold, and null without pricing", () => {
45
+ const long = { ...pricing, longPromptThresholdTokens: 5_000, longPromptMultiplier: 2 };
46
+ expect(worstCaseTextMicrocents(long, { promptTokens: 10_000, maxOutputTokens: 0 })).toBe(7_500);
47
+ expect(worstCaseTextMicrocents(null, { promptTokens: 1, maxOutputTokens: 1 })).toBeNull();
48
+ });
49
+ });
50
+
51
+ describe("token bounds for reservations (#1653)", () => {
52
+ it("counts every UTF-8 byte of text as at most one token", () => {
53
+ // The JSON text's bytes: quotes included.
54
+ expect(tokenBoundOf("abc")).toBe(5);
55
+ // Each umlaut is two bytes, so two tokens at most.
56
+ expect(tokenBoundOf("äö")).toBe(6);
57
+ expect(tokenBoundOf("你好")).toBe(8);
58
+ });
59
+
60
+ it("counts an image part at a fixed bound instead of its base64 bytes", () => {
61
+ const image = { type: "image", base64: "A".repeat(2_000_000), mediaType: "image/png" };
62
+ const bound = tokenBoundOf([{ role: "user", content: "see", additionalContent: [image] }]);
63
+ expect(bound).toBeGreaterThanOrEqual(IMAGE_TOKEN_BOUND);
64
+ expect(bound).toBeLessThan(IMAGE_TOKEN_BOUND + 200);
65
+ // The SDK's file/media part shapes count the same way.
66
+ expect(
67
+ tokenBoundOf({ type: "file", data: "B".repeat(500_000), mediaType: "application/pdf" }),
68
+ ).toBeLessThan(IMAGE_TOKEN_BOUND + 100);
69
+ });
70
+
71
+ it("never counts a function (tool handlers) and adds the provider's wrapping once", () => {
72
+ // The key travels in a schema dump at most; the function's source never does.
73
+ expect(tokenBoundOf({ name: "t", handler: () => "x".repeat(10_000) })).toBeLessThan(40);
74
+ expect(promptTokenBound("s", "m")).toBe(PROVIDER_REQUEST_OVERHEAD_TOKENS + 6);
75
+ });
76
+
77
+ it("bounds a JSON value at no less than its serialized bytes", () => {
78
+ const value = { a: [1, 2, { b: "text", d: "Grüße\n" }], c: null, e: true };
79
+ expect(tokenBoundOf(value)).toBeGreaterThanOrEqual(Buffer.byteLength(JSON.stringify(value)));
80
+ });
81
+ });
package/src/ai-cost.ts ADDED
@@ -0,0 +1,288 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * What an AI call costs, and the most it can cost before it runs: the pure
5
+ * pricing every spend ledger shares (#297, #1477, #1653, #1654). The admin's
6
+ * `ai_calls` ledger and the gateway's visitor-AI ledger (cms_public) price
7
+ * the same way from the same code, so a cap means the same on both sides.
8
+ *
9
+ * Money unit: microcents (1e-8 USD); pricing rows are per 1K tokens for
10
+ * text and per image for image ops (see migration 0048).
11
+ *
12
+ * Prices that depend on prompt length (#1477): Claude Haiku 5.5 bills a
13
+ * request whose prompt is over 100,000 tokens at five times its normal
14
+ * rates, on every lane. The prompt length counts cache reads and writes
15
+ * too, and each request is priced on its own.
16
+ */
17
+
18
+ /** The prompt-length fields of an `ai_pricing` row; absent or null = one flat card. */
19
+ export interface LongPromptPricing {
20
+ readonly longPromptThresholdTokens?: number | null;
21
+ readonly longPromptMultiplier?: number | null;
22
+ }
23
+
24
+ /**
25
+ * The factor on every rate for a request with `promptTokens` of input.
26
+ *
27
+ * @param promptTokens all input tokens of the request (fresh + cache read +
28
+ * cache write). At exactly the threshold the normal rates still apply.
29
+ * @returns 1 for a row without prompt-length pricing or a prompt at or under
30
+ * the threshold, else the row's multiplier.
31
+ */
32
+ export function longPromptRateMultiplier(
33
+ pricing: LongPromptPricing | null | undefined,
34
+ promptTokens: number,
35
+ ): number {
36
+ const threshold = pricing?.longPromptThresholdTokens;
37
+ const multiplier = pricing?.longPromptMultiplier;
38
+ if (threshold == null || multiplier == null) return 1;
39
+ return promptTokens > threshold ? multiplier : 1;
40
+ }
41
+
42
+ /** The rates of one `ai_pricing` row (per 1K tokens; per image for image rows). */
43
+ export interface PricingRow extends LongPromptPricing {
44
+ inputMicrocents: number;
45
+ outputMicrocents: number | null;
46
+ /** Cache-READ (`cache_read_input_tokens`) rate per 1K tokens. */
47
+ cachedMicrocents: number | null;
48
+ /** Cache-WRITE (`cache_creation_input_tokens`) rate per 1K tokens; NULL
49
+ * lets the cost mapper default to 1.25x the input rate. */
50
+ cacheCreationMicrocents: number | null;
51
+ }
52
+
53
+ /**
54
+ * A candidate ai_pricing row for one (provider, operationType), carrying the
55
+ * fields `pickPricingRow` needs to choose the row in force at a given time:
56
+ * the rates plus the model (for exact-vs-wildcard specificity) and the
57
+ * validity/effective timestamps as epoch ms (null bound = open-ended).
58
+ */
59
+ export interface PricingCandidate extends PricingRow {
60
+ model: string;
61
+ effectiveFromMs: number;
62
+ validFromMs: number | null;
63
+ validToMs: number | null;
64
+ }
65
+
66
+ /**
67
+ * Pick the ai_pricing row in force at `nowMs` from candidates already scoped
68
+ * to one (provider, operationType). Eligibility: `effective_from` has passed
69
+ * AND the `[valid_from, valid_to]` window (either bound open) contains
70
+ * `nowMs`. Precedence among the eligible: exact-model beats the wildcard `*`,
71
+ * then a DATED window beats the undated back-compat row, then the
72
+ * latest-starting window wins, then the latest `effective_from`. Returns the
73
+ * `PricingRow` rate subset, or null when nothing is eligible.
74
+ *
75
+ * Pure + exported so validity-window selection is unit-testable without a DB.
76
+ */
77
+ export function pickPricingRow(
78
+ candidates: readonly PricingCandidate[],
79
+ requestedModel: string,
80
+ nowMs: number,
81
+ ): PricingRow | null {
82
+ const eligible = candidates.filter(
83
+ (c) =>
84
+ c.effectiveFromMs <= nowMs &&
85
+ (c.validFromMs === null || c.validFromMs <= nowMs) &&
86
+ (c.validToMs === null || c.validToMs >= nowMs),
87
+ );
88
+ if (eligible.length === 0) return null;
89
+ const exact = (c: PricingCandidate) => (c.model === requestedModel ? 1 : 0);
90
+ const dated = (c: PricingCandidate) => (c.validFromMs !== null || c.validToMs !== null ? 1 : 0);
91
+ // Later in each ranked dimension wins; `beats(b, a)` = "b outranks a".
92
+ const beats = (b: PricingCandidate, a: PricingCandidate): boolean => {
93
+ if (exact(b) !== exact(a)) return exact(b) > exact(a);
94
+ if (dated(b) !== dated(a)) return dated(b) > dated(a);
95
+ const bf = b.validFromMs ?? Number.NEGATIVE_INFINITY;
96
+ const af = a.validFromMs ?? Number.NEGATIVE_INFINITY;
97
+ if (bf !== af) return bf > af;
98
+ return b.effectiveFromMs > a.effectiveFromMs;
99
+ };
100
+ const best = eligible.reduce((a, b) => (beats(b, a) ? b : a));
101
+ return {
102
+ inputMicrocents: best.inputMicrocents,
103
+ outputMicrocents: best.outputMicrocents,
104
+ cachedMicrocents: best.cachedMicrocents,
105
+ cacheCreationMicrocents: best.cacheCreationMicrocents,
106
+ longPromptThresholdTokens: best.longPromptThresholdTokens ?? null,
107
+ longPromptMultiplier: best.longPromptMultiplier ?? null,
108
+ };
109
+ }
110
+
111
+ // ---------------------------------------------------------------------------
112
+ // The cost of a finished call (issue #297).
113
+ // ---------------------------------------------------------------------------
114
+ export interface AiCallCostInput {
115
+ operationType: "text" | "image";
116
+ inputTokens: number;
117
+ outputTokens: number;
118
+ /** Cache-READ tokens (`cache_read_input_tokens`), billed at the cheap
119
+ * `cachedMicrocents` rate. */
120
+ cachedTokens: number;
121
+ /** Cache-WRITE tokens (`cache_creation_input_tokens`), billed at
122
+ * `cacheCreationMicrocents` (~1.25x the input rate). */
123
+ cacheCreationTokens: number;
124
+ /** The longest single prompt among the requests this row sums up. Omitted =
125
+ * `inputTokens`, which is exact for a one-request call and on the high side
126
+ * for an aggregate, so a caller that sums requests can only overcount by
127
+ * leaving it out. */
128
+ largestPromptTokens?: number;
129
+ imageCount: number;
130
+ }
131
+
132
+ export interface AiCallCost {
133
+ /** Microcents to store on the ai_calls row. */
134
+ costMicrocents: number;
135
+ /** True when the call did real work but no pricing row exists — the row
136
+ * will store 0 and every spend roll-up reading it is UNDERSTATED. */
137
+ unpriced: boolean;
138
+ }
139
+
140
+ /**
141
+ * Map a pricing row (or a lookup miss, `null`) onto a call's token/image
142
+ * counts. Three input lanes bill at three rates: fresh input at
143
+ * `inputMicrocents`, cache-READ at `cachedMicrocents` (else input rate), and
144
+ * cache-WRITE at `cacheCreationMicrocents` (else 1.25x the input rate, the
145
+ * Anthropic cache-write premium).
146
+ *
147
+ * Double-count decision: the Vercel AI SDK's flat `usage.inputTokens` is the
148
+ * GRAND total of all three input lanes — see `asLanguageModelUsage`
149
+ * (`ai/dist/index.js`: `inputTokens = usage.inputTokens.total`) fed by the
150
+ * Anthropic adapter (`@ai-sdk/anthropic`: `total = input(fresh) +
151
+ * cacheCreation + cacheRead`). So the fresh remainder billed at the full
152
+ * input rate is `inputTokens - cachedTokens - cacheCreationTokens`; failing
153
+ * to subtract cacheCreationTokens would bill cache writes twice (once at the
154
+ * input rate inside `billedInput`, once at the cache-write rate).
155
+ *
156
+ * Prompt-length pricing (#1477): a row with `longPromptThresholdTokens` bills
157
+ * every lane at its multiplier once the prompt is over the threshold. An
158
+ * `ai_calls` row of a chat turn sums all of the turn's requests, so the whole
159
+ * turn takes the higher card when ANY of its requests crossed the threshold.
160
+ * That can overcount a turn that started below it, by at most the multiplier.
161
+ * Pricing each request would need per-step rows; an overcount is the safe side
162
+ * of this trade because budget caps read this number.
163
+ */
164
+ export function computeAiCallCostMicrocents(
165
+ pricing: PricingRow | null,
166
+ call: AiCallCostInput,
167
+ ): AiCallCost {
168
+ const didWork =
169
+ call.operationType === "image" ? call.imageCount > 0 : call.inputTokens + call.outputTokens > 0;
170
+ if (pricing === null) {
171
+ return { costMicrocents: 0, unpriced: didWork };
172
+ }
173
+ if (call.operationType === "image") {
174
+ return { costMicrocents: pricing.inputMicrocents * call.imageCount, unpriced: false };
175
+ }
176
+ const tier = longPromptRateMultiplier(pricing, call.largestPromptTokens ?? call.inputTokens);
177
+ const inRate = pricing.inputMicrocents * tier;
178
+ const outRate = (pricing.outputMicrocents ?? 0) * tier;
179
+ const cacheReadRate = (pricing.cachedMicrocents ?? pricing.inputMicrocents) * tier;
180
+ const cacheCreationRate =
181
+ (pricing.cacheCreationMicrocents ?? pricing.inputMicrocents * 1.25) * tier;
182
+ const billedInput = Math.max(0, call.inputTokens - call.cachedTokens - call.cacheCreationTokens);
183
+ const costMicrocents = Math.round(
184
+ (billedInput * inRate) / 1000 +
185
+ (call.cachedTokens * cacheReadRate) / 1000 +
186
+ (call.cacheCreationTokens * cacheCreationRate) / 1000 +
187
+ (call.outputTokens * outRate) / 1000,
188
+ );
189
+ return { costMicrocents, unpriced: false };
190
+ }
191
+
192
+ /** What a text request can cost at most, before it runs (#1653). */
193
+ export interface WorstCaseTextInput {
194
+ /** An upper bound of the request's prompt tokens (every input lane). */
195
+ promptTokens: number;
196
+ /** The request's output ceiling (`maxOutputTokens`), thinking included. */
197
+ maxOutputTokens: number;
198
+ }
199
+
200
+ /**
201
+ * The most a text request can cost: every prompt token at the dearest
202
+ * input lane (a cache WRITE, ~1.25x the input rate — a cold prompt may be
203
+ * written to the cache in full), every output token the ceiling allows,
204
+ * and the prompt-length card when the prompt bound is over its threshold.
205
+ * A reservation at this amount cannot be overrun by the call it covers.
206
+ * Null pricing → null: the caller decides whether an unpriced call may run.
207
+ */
208
+ export function worstCaseTextMicrocents(
209
+ pricing: PricingRow | null,
210
+ req: WorstCaseTextInput,
211
+ ): number | null {
212
+ if (pricing === null) return null;
213
+ const tier = longPromptRateMultiplier(pricing, req.promptTokens);
214
+ const inRate = Math.max(
215
+ pricing.inputMicrocents,
216
+ pricing.cacheCreationMicrocents ?? pricing.inputMicrocents * 1.25,
217
+ );
218
+ const outRate = pricing.outputMicrocents ?? 0;
219
+ return Math.ceil(
220
+ ((req.promptTokens * inRate) / 1000 + (req.maxOutputTokens * outRate) / 1000) * tier,
221
+ );
222
+ }
223
+
224
+ // ---------------------------------------------------------------------------
225
+ // The prompt bound of a request before it runs (#1653).
226
+ // ---------------------------------------------------------------------------
227
+
228
+ /** Tokens a provider adds to every request around the caller's content. */
229
+ export const PROVIDER_REQUEST_OVERHEAD_TOKENS = 2_000;
230
+
231
+ /**
232
+ * Tokens one image counts at most, whatever its size: providers scale an
233
+ * image down before they count it (about 1,600 tokens at most for Claude,
234
+ * fewer for the others), so its base64 bytes say nothing about its cost.
235
+ */
236
+ export const IMAGE_TOKEN_BOUND = 5_000;
237
+
238
+ /** Media parts in any of the message shapes the AI SDK and Caelo use. */
239
+ function isMediaPart(o: Record<string, unknown>): boolean {
240
+ return (
241
+ o.type === "image" ||
242
+ o.type === "file" ||
243
+ o.type === "media" ||
244
+ o.type === "image-data" ||
245
+ typeof o.mediaType === "string" ||
246
+ typeof o.mimeType === "string"
247
+ );
248
+ }
249
+
250
+ /**
251
+ * An upper bound of the tokens a value sends: one token per UTF-8 byte of
252
+ * its text (a byte-level BPE token is at least one byte), {@link
253
+ * IMAGE_TOKEN_BOUND} per image or file part instead of its encoded bytes.
254
+ * Several times the real count for prose — the safe side for a
255
+ * reservation, which is settled to the real count after the call.
256
+ */
257
+ export function tokenBoundOf(value: unknown): number {
258
+ // The UTF-8 length of the value's JSON text, with each media part
259
+ // counted at its token bound instead: what the provider receives is at
260
+ // most this many bytes of text plus the images.
261
+ if (typeof value === "function" || value === undefined) return 0;
262
+ if (typeof value === "string") return Buffer.byteLength(JSON.stringify(value), "utf8");
263
+ if (value === null || typeof value !== "object") return String(value).length;
264
+ if (Array.isArray(value)) {
265
+ let n = 2;
266
+ for (const v of value) n += tokenBoundOf(v) + 1;
267
+ return n;
268
+ }
269
+ const o = value as Record<string, unknown>;
270
+ if (isMediaPart(o)) {
271
+ // The part's own short fields (type, name) still travel; its data does not count as text.
272
+ let n = IMAGE_TOKEN_BOUND;
273
+ for (const [k, v] of Object.entries(o))
274
+ if (typeof v === "string" && v.length < 1_000) n += Buffer.byteLength(k + v, "utf8") + 6;
275
+ return n;
276
+ }
277
+ let n = 2;
278
+ for (const [k, v] of Object.entries(o))
279
+ n += Buffer.byteLength(JSON.stringify(k), "utf8") + tokenBoundOf(v) + 2;
280
+ return n;
281
+ }
282
+
283
+ /** An upper bound of a request's prompt tokens: its parts plus the provider's wrapping. */
284
+ export function promptTokenBound(...parts: readonly unknown[]): number {
285
+ let n = PROVIDER_REQUEST_OVERHEAD_TOKENS;
286
+ for (const p of parts) n += tokenBoundOf(p);
287
+ return n;
288
+ }
@@ -4,11 +4,13 @@
4
4
  * P16 hardening — track consecutive cap-lookup failures so a flaky DB
5
5
  * query doesn't silently disable AI cost enforcement.
6
6
  *
7
- * The plugin-host's `ctx.ai.complete` and chat-runner's daily-budget
8
- * pre-flight both consult `ai_calls.aggregate_per_plugin` /
9
- * `ai_budgets.status` before dispatching to the provider. Today a thrown
10
- * error there is swallowed (so a working plugin doesn't break on a DB
11
- * hiccup). That's the right default — but unbounded silent retries =
7
+ * #1653 — every paid AI call reserves its worst-case cost in the AI spend
8
+ * ledger before it reaches the provider (`ai_ledger.reserve`, plugin-host
9
+ * ai-ledger.ts): the chat-runner per request of a turn, a plugin's
10
+ * `ctx.ai`, the core helpers (moduleize, query_page_html, the completeness
11
+ * judge), images. A ledger that cannot be reached lets the call through
12
+ * (it is recorded after it ran, so a working chat or plugin does not break
13
+ * on a DB hiccup). That's the right default — but unbounded silent passes =
12
14
  * "no enforcement at all under sustained DB pressure".
13
15
  *
14
16
  * The counter trips a per-key fail-closed mode after `LOOKUP_FAIL_THRESHOLD`
@@ -277,6 +277,8 @@ export const JOURNAL_EXEMPT_TABLES: Readonly<Record<string, string>> = {
277
277
  email_config: "Owner email configuration; read per send",
278
278
  mail_delivery_caps:
279
279
  "#1337: the Owner's delivery caps of the public mail outboxes; read per drain",
280
+ visitor_ai_settings:
281
+ "#1654: the Owner's visitor-AI settings; read per call, and published to the gateways by its projection trigger",
280
282
  public_mail_deliveries:
281
283
  "#1337: the ledger of mails the admin sent from the public mail outboxes; only counted for the delivery caps",
282
284
  telemetry_settings: "the install's telemetry consent",
@@ -298,6 +300,28 @@ export const JOURNAL_EXEMPT_TABLES: Readonly<Record<string, string>> = {
298
300
  redirect_changes:
299
301
  "which transactions changed redirects, folded by the redirect sync; the journaled redirects table is the source",
300
302
  static_bakes: "derived build output of plugin-baked regions",
303
+ collection_changes:
304
+ "plugin collection writes waiting for an index (#1648): the indexing job consumes them, nothing reads them as state",
305
+ stage_output_commits:
306
+ "build state of a Stage (#1647): which Stages' page output counts, in build order",
307
+ collection_release_changes:
308
+ "build state of a Stage (#1648): which changes each collection release is built from",
309
+ collection_releases:
310
+ "build state of a Stage like deploy_runs (#1648): which collection release each run produced; the projection publishes the pointed run's",
311
+ plugin_page_observations:
312
+ "derived from Stage output (#1647): the hashes an observer last received; losing it only re-sends pages at the next Stage",
313
+ plugin_page_observation_pending:
314
+ "a running Stage's observer deliveries (#1647), committed or dropped with the run",
315
+ plugin_module_counts:
316
+ "derived from Stage output (#1647): the placement counts an observer last received",
317
+ plugin_module_count_pending:
318
+ "a running Stage's placement counts (#1647), committed or dropped with the run",
319
+ plugin_page_observers:
320
+ "derived from Stage output (#1647): the digest an observer last saw every page under; losing it only re-sends every page at the next Stage",
321
+ plugin_page_observer_pending:
322
+ "a running Stage's observer digests (#1647), committed or dropped with the run",
323
+ plugin_batch_runs:
324
+ "the run log of plugin batch operations (#1646): queued, running and how each ended; read by its list op, nothing is derived from it",
301
325
  content_instance_refs:
302
326
  "derived (synchronous, #1287): the ids and media slugs each content instance's values reference, maintained by triggers on the journaled content_instances; rebuilt by content_instances.rebuild_refs",
303
327
  content_instance_snapshot_refs:
@@ -360,6 +384,7 @@ export const JOURNAL_EXEMPT_TABLES: Readonly<Record<string, string>> = {
360
384
  deploy_pending_actions: QUEUE,
361
385
  domain_pending_actions: QUEUE,
362
386
  static_file_pending_actions: QUEUE,
387
+ plugin_config_pending_actions: QUEUE,
363
388
  redirect_pending_actions: QUEUE,
364
389
  email_config_pending_actions: QUEUE,
365
390
  layout_pending_actions: QUEUE,
@@ -0,0 +1,37 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /** #1650 — the embedding-model catalog holds only what may ship. */
4
+
5
+ import { describe, expect, it } from "bun:test";
6
+ import {
7
+ DEFAULT_EMBEDDING_MODEL_ID,
8
+ EMBEDDING_MODEL_IDS,
9
+ EMBEDDING_MODELS,
10
+ embeddingModel,
11
+ embeddingModelFingerprint,
12
+ } from "./embedding-models.js";
13
+
14
+ describe("embedding-model catalog", () => {
15
+ it("has unique ids and a default from the catalog", () => {
16
+ expect(new Set(EMBEDDING_MODEL_IDS).size).toBe(EMBEDDING_MODELS.length);
17
+ expect(embeddingModel(DEFAULT_EMBEDDING_MODEL_ID)).toBeDefined();
18
+ expect(embeddingModel("jina-embeddings-v3")).toBeUndefined();
19
+ });
20
+
21
+ for (const m of EMBEDDING_MODELS) {
22
+ it(`${m.id}: licence, pins and shape`, () => {
23
+ // CLAUDE.md §3: MIT or Apache-2.0 only.
24
+ expect(["MIT", "Apache-2.0"]).toContain(m.licence);
25
+ expect(m.id).toMatch(/^[a-z0-9][a-z0-9.-]{0,79}$/);
26
+ expect(m.source.revision).toMatch(/^[0-9a-f]{40}$/);
27
+ for (const f of [m.files.model, m.files.tokenizer]) {
28
+ expect(f.sha256).toMatch(/^[0-9a-f]{64}$/);
29
+ expect(f.bytes).toBeGreaterThan(0);
30
+ expect(f.name).toMatch(/^[a-z_]+\.(onnx|json)$/);
31
+ }
32
+ expect(m.dims % 32).toBe(0);
33
+ expect(m.maxTokens).toBeGreaterThan(16);
34
+ expect(embeddingModelFingerprint(m)).toBe(`${m.id}@${m.files.model.sha256.slice(0, 12)}`);
35
+ });
36
+ }
37
+ });