@trazum/core 1.8.0

package/dist/net.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Endpoint validation for the pluggable LLM layer.
+ *
+ * Trazum lets the caller choose the URL its optional LLM pass talks to. On a
+ * deployed server that is a server-side request forgery primitive: without
+ * this check, anyone who can reach the web app can make it fetch the cloud
+ * metadata service, an internal admin panel, or any host behind the firewall,
+ * and read the response through the error message.
+ *
+ * This lives in the core rather than in the web route on purpose. It is the
+ * most security-sensitive code in the project, so it belongs where it can be
+ * unit-tested and where every caller — the API route today, anything else
+ * later — gets the same answer.
+ */
+/** Whether a hostname points somewhere a public service must not fetch. */
+export declare function isPrivateHost(hostname: string): boolean;
+export type EndpointRejection = 'invalid-url' | 'insecure-scheme' | 'private-host' | 'credentials-in-url';
+export interface ValidateEndpointOptions {
+    /**
+     * Allow `http:` and private hosts. For local development only — it disables
+     * the entire protection, so it must never be derived from request input.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Validates an LLM endpoint URL. Returns `null` when it is safe to fetch, or a
+ * machine-readable reason when it is not.
+ *
+ * A reason code rather than a message so the caller renders it in the reader's
+ * locale, and so a test asserts on the decision rather than on wording.
+ */
+export declare function validateLlmEndpoint(raw: string, options?: ValidateEndpointOptions): EndpointRejection | null;
+/**
+ * Validates an endpoint and returns the value to fetch, with no trailing slash.
+ *
+ * Returning it rather than approving it is the point. The first version of this
+ * validated `baseUrl` and then fetched
+ * `` `${baseUrl.replace(/\/$/, '')}/chat/completions` `` — two different
+ * expressions, so the thing checked was never the thing used, and a later edit
+ * could have moved the check without anything noticing.
+ *
+ * Re-parsing normalises it too: `https://host/v1/../../admin` passes validation
+ * as a string and resolves somewhere else on the wire.
+ *
+ * Every caller in this package that sends a key to a caller-named host goes
+ * through here — both providers and the exact token counter.
+ */
+export declare function checkedEndpoint(baseUrl: string, { allowInsecure, name }: ValidateEndpointOptions & {
+    name: string;
+}): string;
+/**
+ * `fetch` options that every server-side call in this package must carry.
+ *
+ * `redirect: 'error'` is the one that matters, and it was missing. Everything
+ * above validates the URL the caller named — and then `fetch` followed
+ * redirects by default, so an endpoint that passed every check could answer
+ * `302 Location: http://169.254.169.254/latest/meta-data/` and the request went
+ * there anyway, carrying the `authorization` header. The entire host filter was
+ * one HTTP response away from being bypassed, for the CLI as much as for the
+ * deployed app.
+ *
+ * A refused redirect is a thrown `TypeError`, which is the right outcome: a
+ * legitimate LLM endpoint does not redirect its completions API, and one that
+ * suddenly does is exactly the case worth failing on.
+ */
+export declare const SAFE_FETCH_INIT: {
+    readonly redirect: 'error';
+    readonly credentials: 'omit';
+    readonly referrerPolicy: 'no-referrer';
+};
+/**
+ * The endpoints this server will call, from `TRAZUM_ALLOWED_LLM_ENDPOINTS`
+ * (comma-separated).
+ *
+ * An entry that would fail `validateLlmEndpoint` is dropped rather than
+ * honoured. The operator is trusted to choose, not to be immune from pasting
+ * `http://169.254.169.254` into a list that then serves every anonymous caller.
+ * `allowInsecure` is deliberately not offered: an endpoint only reachable with
+ * the protection off has no business being selectable over HTTP.
+ */
+export declare function allowedEndpoints(env: Record<string, string | undefined>): readonly string[];
+/**
+ * Resolves what a caller asked for to an entry on the list.
+ *
+ * Returns the **listed** value, not the requested one. That distinction is the
+ * entire function: the string from the request is compared and then discarded,
+ * so nothing derived from it reaches `fetch`.
+ */
+export declare function resolveEndpoint(requested: string, allowed: readonly string[]): string | null;
+//# sourceMappingURL=net.d.ts.map

package/dist/net.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../src/net.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiCH,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIvD;AAED,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,iBAAiB,GACjB,cAAc,GACd,oBAAoB,CAAC;AAEzB,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,iBAAiB,GAAG,IAAI,CAyB1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,EAAE,aAAqB,EAAE,IAAI,EAAE,EAAE,uBAAuB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1E,MAAM,CASR;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe;uBAChB,OAAO;0BAEJ,MAAM;6BACH,aAAa;CACC,CAAC;AA4CjC;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,MAAM,EAAE,CAY3F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAI5F"}

package/dist/net.js

@@ -0,0 +1,203 @@
+/**
+ * Endpoint validation for the pluggable LLM layer.
+ *
+ * Trazum lets the caller choose the URL its optional LLM pass talks to. On a
+ * deployed server that is a server-side request forgery primitive: without
+ * this check, anyone who can reach the web app can make it fetch the cloud
+ * metadata service, an internal admin panel, or any host behind the firewall,
+ * and read the response through the error message.
+ *
+ * This lives in the core rather than in the web route on purpose. It is the
+ * most security-sensitive code in the project, so it belongs where it can be
+ * unit-tested and where every caller — the API route today, anything else
+ * later — gets the same answer.
+ */
+/**
+ * Hostnames that must never be reachable from a server-side fetch.
+ *
+ * Written against the *hostname string* rather than a resolved address: DNS
+ * resolution would be more thorough but introduces a TOCTOU window (the name
+ * can resolve differently between the check and the request) and a network
+ * call in a validation path. This blocks the literal forms an attacker
+ * actually types; defence in depth against DNS rebinding belongs at the egress
+ * layer, and is called out in SECURITY.md rather than pretended to here.
+ */
+const PRIVATE_HOST_PATTERNS = [
+    /^localhost$/i,
+    /^127\./,
+    /^0\./,
+    /^10\./,
+    /^172\.(1[6-9]|2\d|3[01])\./,
+    /^192\.168\./,
+    /^169\.254\./, // cloud metadata (AWS/GCP/Azure) and link-local
+    /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./, // carrier-grade NAT
+    /^\[?::1\]?$/,
+    /^\[?::\]?$/,
+    /^\[?f[cd][0-9a-f]{2}:/i, // IPv6 unique local
+    /^\[?fe80:/i, // IPv6 link-local
+    /^\[?::ffff:/i, // IPv4-mapped IPv6, e.g. ::ffff:169.254.169.254
+    /\.internal$/i,
+    /\.local$/i,
+    /\.localhost$/i,
+    /^metadata\./i,
+    /^metadata$/i,
+];
+/** Whether a hostname points somewhere a public service must not fetch. */
+export function isPrivateHost(hostname) {
+    const host = hostname.trim().toLowerCase().replace(/\.$/, '');
+    if (!host)
+        return true;
+    return PRIVATE_HOST_PATTERNS.some((pattern) => pattern.test(host));
+}
+/**
+ * Validates an LLM endpoint URL. Returns `null` when it is safe to fetch, or a
+ * machine-readable reason when it is not.
+ *
+ * A reason code rather than a message so the caller renders it in the reader's
+ * locale, and so a test asserts on the decision rather than on wording.
+ */
+export function validateLlmEndpoint(raw, options = {}) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return 'invalid-url';
+    }
+    const { allowInsecure = false } = options;
+    if (url.protocol !== 'https:' && !(allowInsecure && url.protocol === 'http:')) {
+        return 'insecure-scheme';
+    }
+    // Credentials in the URL would be forwarded to whatever the host turns out
+    // to be, and would land in any log line that records the endpoint.
+    if (url.username || url.password) {
+        return 'credentials-in-url';
+    }
+    if (!allowInsecure && isPrivateHost(url.hostname)) {
+        return 'private-host';
+    }
+    return null;
+}
+/**
+ * Validates an endpoint and returns the value to fetch, with no trailing slash.
+ *
+ * Returning it rather than approving it is the point. The first version of this
+ * validated `baseUrl` and then fetched
+ * `` `${baseUrl.replace(/\/$/, '')}/chat/completions` `` — two different
+ * expressions, so the thing checked was never the thing used, and a later edit
+ * could have moved the check without anything noticing.
+ *
+ * Re-parsing normalises it too: `https://host/v1/../../admin` passes validation
+ * as a string and resolves somewhere else on the wire.
+ *
+ * Every caller in this package that sends a key to a caller-named host goes
+ * through here — both providers and the exact token counter.
+ */
+export function checkedEndpoint(baseUrl, { allowInsecure = false, name }) {
+    const rejection = validateLlmEndpoint(baseUrl, { allowInsecure });
+    if (rejection !== null) {
+        throw new Error(`Provider "${name}" cannot use ${baseUrl}: ${rejection}. ` +
+            'Pass allowInsecure only for an endpoint you configured yourself.');
+    }
+    return new URL(baseUrl).toString().replace(/\/$/, '');
+}
+/**
+ * `fetch` options that every server-side call in this package must carry.
+ *
+ * `redirect: 'error'` is the one that matters, and it was missing. Everything
+ * above validates the URL the caller named — and then `fetch` followed
+ * redirects by default, so an endpoint that passed every check could answer
+ * `302 Location: http://169.254.169.254/latest/meta-data/` and the request went
+ * there anyway, carrying the `authorization` header. The entire host filter was
+ * one HTTP response away from being bypassed, for the CLI as much as for the
+ * deployed app.
+ *
+ * A refused redirect is a thrown `TypeError`, which is the right outcome: a
+ * legitimate LLM endpoint does not redirect its completions API, and one that
+ * suddenly does is exactly the case worth failing on.
+ */
+export const SAFE_FETCH_INIT = {
+    redirect: 'error',
+    // No cookies or TLS client certs on a cross-origin call the caller named.
+    credentials: 'omit',
+    referrerPolicy: 'no-referrer',
+};
+// --------------------------------------------------------------------------
+// What a deployment is willing to be pointed at
+// --------------------------------------------------------------------------
+/**
+ * Which LLM endpoints a server-side caller is allowed to reach.
+ *
+ * The web route used to take `baseUrl` out of the request body, validate the
+ * string and hand it to a provider. That is server-side request forgery by
+ * construction, and validating harder does not fix it:
+ *
+ * - Every check above reads the *name*. `https://totally-fine.example.com` that
+ *   resolves to `169.254.169.254` passes all of them, and the fix for that is
+ *   pinning the resolved address at the socket, which `fetch` does not offer.
+ * - Even with the redirect hop closed, an anonymous caller could still aim the
+ *   server at any public host and read the reply through the error body.
+ *   "Public" is not the same as "fine to fetch on somebody else's behalf".
+ *
+ * So the request body no longer *names* an endpoint. It **selects** one the
+ * operator listed, and the value that reaches the provider is the entry from
+ * the list — never the string that arrived over HTTP. The default is an empty
+ * list, so a deployment that has not thought about this cannot be pointed
+ * anywhere at all.
+ *
+ * Nobody loses the capability: an operator running Trazum for themselves puts
+ * the endpoint in `TRAZUM_LLM_BASE_URL` and it is used directly, exactly as the
+ * CLI has always worked. This is only about who is allowed to choose.
+ *
+ * `env` is a parameter rather than a read of `process.env` because this module
+ * is on the browser-safe path.
+ */
+const ALLOWLIST_VAR = 'TRAZUM_ALLOWED_LLM_ENDPOINTS';
+/** Normalised, so a trailing slash or a capitalised host is not a mismatch. */
+function normaliseEndpoint(raw) {
+    try {
+        return new URL(raw.trim()).toString().replace(/\/$/, '');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The endpoints this server will call, from `TRAZUM_ALLOWED_LLM_ENDPOINTS`
+ * (comma-separated).
+ *
+ * An entry that would fail `validateLlmEndpoint` is dropped rather than
+ * honoured. The operator is trusted to choose, not to be immune from pasting
+ * `http://169.254.169.254` into a list that then serves every anonymous caller.
+ * `allowInsecure` is deliberately not offered: an endpoint only reachable with
+ * the protection off has no business being selectable over HTTP.
+ */
+export function allowedEndpoints(env) {
+    const raw = env[ALLOWLIST_VAR];
+    if (!raw)
+        return [];
+    const listed = new Set();
+    for (const part of raw.split(',')) {
+        const url = normaliseEndpoint(part);
+        if (url === null)
+            continue;
+        if (validateLlmEndpoint(url) !== null)
+            continue;
+        listed.add(url);
+    }
+    return [...listed];
+}
+/**
+ * Resolves what a caller asked for to an entry on the list.
+ *
+ * Returns the **listed** value, not the requested one. That distinction is the
+ * entire function: the string from the request is compared and then discarded,
+ * so nothing derived from it reaches `fetch`.
+ */
+export function resolveEndpoint(requested, allowed) {
+    const wanted = normaliseEndpoint(requested);
+    if (wanted === null)
+        return null;
+    return allowed.find((entry) => entry.toLowerCase() === wanted.toLowerCase()) ?? null;
+}
+//# sourceMappingURL=net.js.map

package/dist/net.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.js","sourceRoot":"","sources":["../src/net.ts"],"names":[],"mappings":"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"}

package/dist/node.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The parts of the core that read the filesystem.
+ *
+ * Kept off the main entry point on purpose, and the reason is a build failure
+ * rather than a preference: `apps/web` bundles `@trazum/core` for the browser,
+ * and a single `node:fs/promises` import anywhere in that graph fails the build
+ * outright — "the chunking context does not support external modules".
+ *
+ * That failure is the friendly version of the real risk. The web app hands
+ * `optimize()` a prompt straight from a request body; a file read reachable
+ * from that entry point is path traversal available to anyone who can reach the
+ * API. Two entry points make the split structural: the browser cannot import
+ * what is not in its graph, whatever a future refactor does.
+ *
+ * Only the CLI imports this.
+ */
+export { loadConfig } from './config.js';
+export type { LoadConfigOptions, LoadedConfig } from './config.js';
+export { CONFIG_FILENAME, CONFIG_KEYS, CONFIG_USAGE_KEYS, ConfigError, DEFAULT_EXTENSIONS, MAX_CONFIG_BYTES, MAX_CONFIG_SEARCH_DEPTH, budgetFor, parseConfig, validateConfigModel, } from './config-schema.js';
+export type { ResolvedBudget, TrazumConfig } from './config-schema.js';
+export { MAX_PRICING_BYTES, PricingOverlayError, applyPricingOverlay, catalogueFromOverlay, parsePricingOverlay, } from './pricing-overlay.js';
+export type { PricingOverlay } from './pricing-overlay.js';
+export { openrouterOverlay } from './openrouter.js';
+export type { OpenRouterResult } from './openrouter.js';
+export { SAFE_FETCH_INIT, checkedEndpoint } from './net.js';
+export { BUNDLED_CATALOGUE } from './pricing.js';
+export type { PricingCatalogue } from './pricing.js';
+export { detectHost } from './host.js';
+export type { HostEnvironment } from './host.js';
+export { MAX_WALK_DEPTH, MAX_WALK_FILES, walkPrompts } from './walk.js';
+export type { WalkOptions, WalkResult } from './walk.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAInE,OAAO,EACL,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,SAAS,EACT,WAAW,EACX,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvE,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/node.js

@@ -0,0 +1,33 @@
+/**
+ * The parts of the core that read the filesystem.
+ *
+ * Kept off the main entry point on purpose, and the reason is a build failure
+ * rather than a preference: `apps/web` bundles `@trazum/core` for the browser,
+ * and a single `node:fs/promises` import anywhere in that graph fails the build
+ * outright — "the chunking context does not support external modules".
+ *
+ * That failure is the friendly version of the real risk. The web app hands
+ * `optimize()` a prompt straight from a request body; a file read reachable
+ * from that entry point is path traversal available to anyone who can reach the
+ * API. Two entry points make the split structural: the browser cannot import
+ * what is not in its graph, whatever a future refactor does.
+ *
+ * Only the CLI imports this.
+ */
+export { loadConfig } from './config.js';
+// Re-exported for convenience, so the CLI has one import for everything
+// config-shaped. These halves are pure and also live on the main entry point.
+export { CONFIG_FILENAME, CONFIG_KEYS, CONFIG_USAGE_KEYS, ConfigError, DEFAULT_EXTENSIONS, MAX_CONFIG_BYTES, MAX_CONFIG_SEARCH_DEPTH, budgetFor, parseConfig, validateConfigModel, } from './config-schema.js';
+// Local price corrections. Pure, so also on the main entry point; re-exported
+// here so the CLI has one import for everything it needs to resolve a run.
+export { MAX_PRICING_BYTES, PricingOverlayError, applyPricingOverlay, catalogueFromOverlay, parsePricingOverlay, } from './pricing-overlay.js';
+// Turns a live price feed into an overlay. Pure — the fetch is the CLI's — and
+// re-exported here for the same reason as the overlay itself: one import.
+export { openrouterOverlay } from './openrouter.js';
+// The endpoint gate every outbound call in this project goes through.
+export { SAFE_FETCH_INIT, checkedEndpoint } from './net.js';
+export { BUNDLED_CATALOGUE } from './pricing.js';
+// Reads the process environment, so it cannot live on the browser-safe entry.
+export { detectHost } from './host.js';
+export { MAX_WALK_DEPTH, MAX_WALK_FILES, walkPrompts } from './walk.js';
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,wEAAwE;AACxE,8EAA8E;AAC9E,OAAO,EACL,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,SAAS,EACT,WAAW,EACX,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAG5B,8EAA8E;AAC9E,2EAA2E;AAC3E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAG9B,+EAA+E;AAC/E,0EAA0E;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGpD,sEAAsE;AACtE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD,8EAA8E;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/openrouter.d.ts

@@ -0,0 +1,25 @@
+import type { PricingOverlay } from './pricing-overlay.js';
+export interface OpenRouterResult {
+    overlay: PricingOverlay;
+    /** Ids that were skipped, and the reason, so nothing disappears silently. */
+    skipped: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+/**
+ * Turns OpenRouter's catalogue into an overlay.
+ *
+ * `knownIds` is the set the bundled catalogue already has. For those, only the
+ * three things OpenRouter actually knows are overridden — price in, price out,
+ * context window. `cacheMinTokens`, `caching`, `capability` and `tier` are left
+ * alone, because the bundled entry was written by somebody who looked them up
+ * and this feed has nothing to say about them. Overwriting a researched fact
+ * with a blank is not a refresh.
+ */
+export declare function openrouterOverlay(payload: unknown, options: {
+    knownIds: ReadonlySet<string>;
+    lastReviewed: string;
+    idFor?: (id: string) => string;
+}): OpenRouterResult;
+//# sourceMappingURL=openrouter.d.ts.map

package/dist/openrouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrouter.d.ts","sourceRoot":"","sources":["../src/openrouter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAsC3D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,cAAc,CAAC;IACxB,6EAA6E;IAC7E,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE;IAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,GAC/F,gBAAgB,CAqDlB"}

package/dist/openrouter.js

@@ -0,0 +1,72 @@
+/**
+ * OpenRouter quotes USD **per token**, as a decimal string.
+ *
+ * `"0.000003"` is three dollars per million. Parsed rather than multiplied
+ * blindly: a free model quotes `"0"`, and a model with no price for one half
+ * quotes `"-1"` on occasion. Neither is a price Trazum can put in a budget.
+ */
+function perMillion(raw) {
+    if (typeof raw !== 'string' && typeof raw !== 'number')
+        return null;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    return value * 1_000_000;
+}
+/**
+ * Turns OpenRouter's catalogue into an overlay.
+ *
+ * `knownIds` is the set the bundled catalogue already has. For those, only the
+ * three things OpenRouter actually knows are overridden — price in, price out,
+ * context window. `cacheMinTokens`, `caching`, `capability` and `tier` are left
+ * alone, because the bundled entry was written by somebody who looked them up
+ * and this feed has nothing to say about them. Overwriting a researched fact
+ * with a blank is not a refresh.
+ */
+export function openrouterOverlay(payload, options) {
+    const { knownIds, lastReviewed, idFor = (id) => id } = options;
+    const data = payload?.data;
+    if (!Array.isArray(data)) {
+        throw new Error('OpenRouter payload has no "data" array — is this the models endpoint?');
+    }
+    const models = {};
+    const skipped = [];
+    for (const entry of data) {
+        const rawId = typeof entry?.id === 'string' ? entry.id : '';
+        if (!rawId)
+            continue;
+        const id = idFor(rawId);
+        const input = perMillion(entry.pricing?.prompt);
+        const output = perMillion(entry.pricing?.completion);
+        if (input === null || output === null) {
+            // Free models and half-priced entries. Skipped rather than recorded at
+            // zero: a zero price makes every saving Trazum computes zero too, and a
+            // report full of $0.00 reads as "nothing to gain here" rather than as
+            // "this catalogue has no price for that".
+            skipped.push({ id: rawId, reason: 'no usable price' });
+            continue;
+        }
+        const context = Number(entry.context_length);
+        if (!Number.isInteger(context) || context <= 0) {
+            skipped.push({ id: rawId, reason: 'no context window' });
+            continue;
+        }
+        if (knownIds.has(id)) {
+            models[id] = { inputPerMTok: input, outputPerMTok: output, contextWindow: context };
+            continue;
+        }
+        models[id] = {
+            displayName: typeof entry.name === 'string' && entry.name ? entry.name : rawId,
+            inputPerMTok: input,
+            outputPerMTok: output,
+            contextWindow: context,
+            // The two the feed cannot answer. See the note at the top of this file.
+            cacheMinTokens: null,
+            caching: 'unknown',
+            capability: 'unknown',
+            tier: 'unknown',
+        };
+    }
+    return { overlay: { lastReviewed, models }, skipped };
+}
+//# sourceMappingURL=openrouter.js.map

package/dist/openrouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrouter.js","sourceRoot":"","sources":["../src/openrouter.ts"],"names":[],"mappings":"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"}

package/dist/optimize.d.ts

@@ -0,0 +1,38 @@
+import type { PricingCatalogue } from './pricing.js';
+import { join, segment } from './segment.js';
+import type { AsyncTokenCounter } from './tokenizer.js';
+import type { OptimizationResult, OptimizeOptions, Segment, UsageProfile } from './types.js';
+export declare const DEFAULT_USAGE: UsageProfile;
+interface Masked {
+    text: string;
+    /** Original text of each protected segment, indexed by its mask. */
+    vault: string[];
+}
+/**
+ * Replaces every protected segment with a 3-character marker from the Unicode
+ * private use area. The rules work on the masked text, so none of them can
+ * touch code, URLs or template placeholders.
+ */
+declare function mask(segments: Segment[]): Masked;
+/** Puts the protected content back. */
+declare function unmask(text: string, vault: string[]): string;
+/**
+ * Optimises a prompt by applying deterministic rules.
+ *
+ * The result is reproducible: the same input always yields the same output and
+ * running it costs nothing. The optional LLM pass lives separately, in
+ * `refineWithLlm`.
+ */
+export declare function optimize(prompt: string, options?: OptimizeOptions): OptimizationResult;
+/**
+ * Recomputes the report with an exact token counter (e.g. the official
+ * token-counting endpoint).
+ *
+ * Only the headline numbers and the saving are recomputed. Per-rule token
+ * attribution stays on the heuristic estimate: asking a remote counter once
+ * per rule would multiply the calls without changing any decision.
+ */
+export declare function withExactTokenCounts(result: OptimizationResult, counter: AsyncTokenCounter, pricing?: PricingCatalogue): Promise<OptimizationResult>;
+/** Re-exports of internals useful to anyone extending the library. */
+export { join, mask as maskProtected, segment, unmask as unmaskProtected };
+//# sourceMappingURL=optimize.d.ts.map

package/dist/optimize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimize.d.ts","sourceRoot":"","sources":["../src/optimize.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EAEf,OAAO,EAEP,YAAY,EACb,MAAM,YAAY,CAAC;AAQpB,eAAO,MAAM,aAAa,EAAE,YAM3B,CAAC;AAEF,UAAU,MAAM;IACd,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,iBAAS,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAqBzC;AAED,uCAAuC;AACvC,iBAAS,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CASrD;AAOD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,kBAAkB,CA2E1F;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,gBAAoC,GAC5C,OAAO,CAAC,kBAAkB,CAAC,CA2C7B;AAED,sEAAsE;AACtE,OAAO,EAAE,IAAI,EAAE,IAAI,IAAI,aAAa,EAAE,OAAO,EAAE,MAAM,IAAI,eAAe,EAAE,CAAC"}