mindweave 0.0.1 → 2.1.2

package/dist/drivers/retryPolicy.js

@@ -0,0 +1,129 @@
+/**
+ * retryPolicy.ts — surviving a blip instead of losing the turn.
+ *
+ * Eleven of the thirteen providers reach their API through a raw `fetch` with no
+ * retries at all. A single 429, or one 503 from a load balancer, threw out of the
+ * transport, was rethrown by the engine, and ended the turn mid-task. The user had
+ * already paid for the request, the work was gone, and the only remedy was to type it
+ * again. Providers return those constantly and mean nothing by them.
+ *
+ * WHERE THIS IS SAFE TO APPLY, which is the whole reason it can exist at all: both
+ * request paths check `response.ok` on the HEADERS, before a single byte of the body is
+ * consumed and before any `onEvent` fires. So a failure at that point has emitted
+ * nothing, and re-sending is genuinely re-sending rather than duplicating. A failure
+ * DURING `consumeStream` is a different animal and is deliberately not retried here:
+ * content has already reached the screen and the transcript, and replaying it would
+ * double it.
+ *
+ * WHY THE BUDGET IS SMALL. A state-of-the-art client retries up to ten times and can
+ * wait minutes, which is right for an unattended agent and wrong for a person watching
+ * a prompt. Here the total wait is bounded so a retry always reads as "working" rather
+ * than as a hang, and a cooldown longer than the budget is reported instead of slept
+ * through: the provider's own sentence ("try again in 47 seconds") is more useful to
+ * someone sitting there than 47 seconds of silence.
+ */
+const env = (name, fallback) => {
+    const v = Number(process.env[name]);
+    return Number.isFinite(v) && v >= 0 ? v : fallback;
+};
+/** Attempts in total, so 3 means one try and two retries. */
+export const RETRY_MAX_ATTEMPTS = env("MINDWEAVE_RETRY_ATTEMPTS", 4);
+/** Total time this request may spend WAITING between attempts. */
+export const RETRY_TOTAL_BUDGET_MS = env("MINDWEAVE_RETRY_BUDGET_MS", 30_000);
+/** First backoff step; each retry doubles it. */
+const BASE_DELAY_MS = 500;
+/** No single wait longer than this, whatever the arithmetic says. */
+const MAX_DELAY_MS = 8_000;
+/**
+ * Statuses worth trying again.
+ *
+ * 429 is here even though `providerError.ts` classifies it as an ACCOUNT refusal, and
+ * the two are not in conflict: retrying comes first, and providerError renders whatever
+ * is still failing once the budget is spent. A rate limit that clears in two seconds
+ * should never have reached the user at all; one that does not clear still gets its
+ * proper explanation.
+ *
+ * 400/401/402/403/404/422 are absent on purpose. None of them changes by being asked
+ * again, and retrying a malformed request three times just makes a bug slower to see.
+ */
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504, 529]);
+/** Transport failures that are worth another go. */
+const RETRYABLE_NETWORK = [
+    "econnreset",
+    "econnrefused",
+    "etimedout",
+    "epipe",
+    "eai_again",
+    "enetunreach",
+    "socket hang up",
+    "fetch failed",
+    "network error",
+    "terminated",
+];
+/** Did the user cancel? Never retried, and never mistaken for a network fault. */
+export function isAbortLike(error) {
+    const e = error;
+    if (e?.name === "AbortError")
+        return true;
+    return typeof e?.message === "string" && /\babort/i.test(e.message);
+}
+/** Should this failure be tried again (pure)? */
+export function isRetryable(error, status) {
+    if (isAbortLike(error))
+        return false;
+    if (typeof status === "number")
+        return RETRYABLE_STATUSES.has(status);
+    const e = error;
+    const text = [
+        typeof e?.code === "string" ? e.code : "",
+        typeof e?.message === "string" ? e.message : "",
+        typeof e?.cause?.code === "string" ? (e.cause.code) : "",
+    ]
+        .join(" ")
+        .toLowerCase();
+    if (!text.trim())
+        return false;
+    return RETRYABLE_NETWORK.some((needle) => text.includes(needle));
+}
+/**
+ * How long the provider asked us to wait, in ms, or null if it did not say (pure).
+ *
+ * `Retry-After` comes as either a count of seconds or an HTTP date, and both are in the
+ * wild. A date in the past reads as zero rather than as a negative wait.
+ */
+export function retryAfterMs(header) {
+    const raw = (header ?? "").trim();
+    if (!raw)
+        return null;
+    if (/^\d+(\.\d+)?$/.test(raw))
+        return Math.round(Number(raw) * 1000);
+    const at = Date.parse(raw);
+    if (Number.isNaN(at))
+        return null;
+    return Math.max(0, at - Date.now());
+}
+/**
+ * How long to wait before attempt `attempt` (1-based for the first RETRY), or null to
+ * stop (pure).
+ *
+ * Returns null rather than a clamped delay when the provider's own cooldown exceeds
+ * what is left of the budget. Sleeping "as long as we can" would wake up and fail
+ * anyway, having spent the user's time to learn nothing.
+ *
+ * Jitter is full rather than partial: several drivers can be in flight at once (a turn
+ * plus a background session-memory refresh), and identical backoff would march them
+ * into the provider together on every step.
+ */
+export function nextDelayMs(attempt, spentMs, serverAskedMs, budgetMs = RETRY_TOTAL_BUDGET_MS, random = Math.random) {
+    const remaining = budgetMs - spentMs;
+    if (remaining <= 0)
+        return null;
+    if (serverAskedMs !== null) {
+        // The provider knows when it will serve us; obey it or admit we cannot wait.
+        return serverAskedMs <= remaining ? serverAskedMs : null;
+    }
+    const ceiling = Math.min(BASE_DELAY_MS * 2 ** Math.max(0, attempt - 1), MAX_DELAY_MS);
+    const delay = Math.round(ceiling * (0.5 + random() * 0.5));
+    return Math.min(delay, remaining);
+}
+//# sourceMappingURL=retryPolicy.js.map

package/dist/drivers/retryPolicy.js.map

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

package/dist/drivers/searchBlocks.js

@@ -0,0 +1,61 @@
+/** How many searches one call may run before the provider stops. */
+export const SEARCH_MAX_USES = 5;
+/**
+ * The thin system prompt for a search call.
+ *
+ * Model-work boundary: this is the whole of it. Search, answer from what is found,
+ * say so when it is not there. No analysis rules, no house style, nothing about how
+ * to judge a source — that judgment belongs to the model that asked for the search,
+ * not to a prompt buried inside a tool.
+ */
+export const SEARCH_SYSTEM = "Search the web to answer the request. Answer only from what you find, " +
+    "and say so plainly if the answer is not there. Include specifics — " +
+    "versions, names, dates, code — rather than describing the pages.";
+/**
+ * Pull an answer and its citations out of a finished search message.
+ *
+ * Two shapes have to be handled and only one of them is a list. A failed search comes
+ * back on a SUCCESSFUL response as a `web_search_tool_result` block whose `content` is
+ * an error OBJECT rather than an array of results, so indexing it blind yields nonsense
+ * instead of throwing. Hence the `Array.isArray` gate.
+ *
+ * Sources are de-duplicated by URL: the model commonly reads the same page across two
+ * searches in one turn, and listing it twice reads as two separate findings.
+ */
+export function extractSearch(message) {
+    let answer = "";
+    const sources = [];
+    const seen = new Set();
+    for (const block of message.content) {
+        if (block.type === "text") {
+            answer += block.text;
+            continue;
+        }
+        if (block.type !== "web_search_tool_result")
+            continue;
+        // The error branch. Nothing to list; the answer text explains it.
+        if (!Array.isArray(block.content))
+            continue;
+        for (const hit of block.content) {
+            // The declared type says both fields are strings. A real provider disagreed:
+            // a live DeepSeek search returned a result carrying neither, which rendered as
+            // "undefined — undefined" in the source list. The wire is not bound by the SDK's
+            // types, so a result without a usable URL is dropped rather than shown.
+            const url = typeof hit.url === "string" ? hit.url.trim() : "";
+            if (!url || seen.has(url))
+                continue;
+            seen.add(url);
+            const title = typeof hit.title === "string" ? hit.title.trim() : "";
+            sources.push({ title: title || url, url });
+        }
+    }
+    return {
+        answer: answer.trim(),
+        sources,
+        // The provider's own search loop has a ceiling; past it the turn comes back paused
+        // rather than finished. We keep what it found instead of resuming, and say so,
+        // because a partial answer with its sources is still useful.
+        partial: message.stop_reason === "pause_turn",
+    };
+}
+//# sourceMappingURL=searchBlocks.js.map

package/dist/drivers/searchBlocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchBlocks.js","sourceRoot":"","sources":["../../src/drivers/searchBlocks.ts"],"names":[],"mappings":"AAiBA,oEAAoE;AACpE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,wEAAwE;IACxE,qEAAqE;IACrE,kEAAkE,CAAC;AAErE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,OAA0B;IACtD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC;YACrB,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,wBAAwB;YAAE,SAAS;QACtD,kEAAkE;QAClE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,SAAS;QAC5C,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAChC,6EAA6E;YAC7E,+EAA+E;YAC/E,iFAAiF;YACjF,wEAAwE;YACxE,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE;QACrB,OAAO;QACP,mFAAmF;QACnF,+EAA+E;QAC/E,6DAA6D;QAC7D,OAAO,EAAE,OAAO,CAAC,WAAW,KAAK,YAAY;KAC9C,CAAC;AACJ,CAAC"}

package/dist/drivers/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/drivers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/drivers/types.ts"],"names":[],"mappings":""}

package/dist/drivers/xai/client.js

@@ -0,0 +1,63 @@
+import { compatStreamTurn, compatToolTurn } from "../openaiCompat/wire.js";
+import { BUFFERED_OUTPUT_TOKENS, DEFAULT_MODEL, takesEffort } from "./manifest.js";
+const BASE_URL = process.env.MINDWEAVE_XAI_URL ?? "https://api.x.ai/v1";
+/** The model a request runs on, matching the shared layer's own fallback so the
+ *  reasoning fields can never be built for a different model than is being called. */
+function modelOf(config) {
+    return config?.model ?? process.env.MINDWEAVE_MODEL ?? DEFAULT_MODEL;
+}
+/**
+ * xAI's reasoning fields.
+ *
+ * `reasoning_effort` is served by ONE model here, so it is sent only for that one.
+ * On the others it is not a tolerated extra: they do not accept the parameter.
+ *
+ * Unlike Qwen, GLM and DeepSeek, there is nothing to send when reasoning is off on a
+ * model that has no dial — this provider does not default to thinking-on, so an
+ * absent field is genuinely absent rather than a hidden bill. Stated because the
+ * opposite is true of three other drivers here, and the reflex by now is to send it.
+ */
+export function reasoningFields(config) {
+    if (!takesEffort(modelOf(config)))
+        return {};
+    return { reasoning_effort: config?.thinking ? (config.effort ?? "low") : "none" };
+}
+/**
+ * `end_turn` is xAI's own spelling of a normal finish, alongside the standard
+ * `stop`. It already falls through to `"end"`, but it is mapped explicitly so the
+ * value is recorded as KNOWN — an unrecognised reason reaching the default is
+ * exactly how a real stop condition gets reported as a clean finish elsewhere.
+ */
+export function extraStop(reason) {
+    return reason === "end_turn" ? "end" : undefined;
+}
+/** xAI reports its cache hit as `prompt_tokens_details.cached_tokens`, where
+ *  `prompt_tokens` is the FULL prompt including the cached part. */
+export function cacheSplit(usage) {
+    const details = usage.prompt_tokens_details;
+    const hit = typeof details?.cached_tokens === "number" ? details.cached_tokens : 0;
+    if (hit === 0)
+        return undefined;
+    const prompt = typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : 0;
+    return { hit, miss: Math.max(0, prompt - hit) };
+}
+/** Everything the shared wire layer needs to talk to xAI. */
+export const xaiProvider = {
+    label: "xAI",
+    baseUrl: BASE_URL,
+    apiKeyEnv: "XAI_API_KEY",
+    defaultModel: process.env.MINDWEAVE_MODEL ?? DEFAULT_MODEL,
+    reasoningFields,
+    extraStop,
+    cacheSplit,
+    bufferedMaxTokens: BUFFERED_OUTPUT_TOKENS,
+};
+/** Ask the model for one turn. */
+export async function toolTurn(req, options = {}) {
+    return compatToolTurn(xaiProvider, req, options.signal);
+}
+/** Ask the model for one turn, streaming deltas to `options.onEvent`. */
+export async function streamTurn(req, options = {}) {
+    return compatStreamTurn(xaiProvider, req, options.onEvent, options.signal);
+}
+//# sourceMappingURL=client.js.map

package/dist/drivers/xai/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/drivers/xai/client.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAuB,MAAM,yBAAyB,CAAC;AAChG,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEnF,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,qBAAqB,CAAC;AAExE;sFACsF;AACtF,SAAS,OAAO,CAAC,MAA+B;IAC9C,OAAO,MAAM,EAAE,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,aAAa,CAAC;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,MAA+B;IAC7D,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;AACpF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACnD,CAAC;AAED;oEACoE;AACpE,MAAM,UAAU,UAAU,CAAC,KAA8B;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,qBAA+D,CAAC;IACtF,MAAM,GAAG,GAAG,OAAO,OAAO,EAAE,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACnF,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,MAAM,GAAG,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,KAAK,EAAE,KAAK;IACZ,OAAO,EAAE,QAAQ;IACjB,SAAS,EAAE,aAAa;IACxB,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,aAAa;IAC1D,eAAe;IACf,SAAS;IACT,UAAU;IACV,iBAAiB,EAAE,sBAAsB;CAC1C,CAAC;AAEF,kCAAkC;AAClC,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAiB,EAAE,UAAuB,EAAE;IACzE,OAAO,cAAc,CAAC,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAiB,EAAE,UAAyB,EAAE;IAC7E,OAAO,gBAAgB,CAAC,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;AAC7E,CAAC"}

package/dist/drivers/xai/index.js

@@ -0,0 +1,5 @@
+import { streamTurn, toolTurn } from "./client.js";
+import { xaiManifest } from "./manifest.js";
+export const xaiDriver = { ...xaiManifest, toolTurn, streamTurn };
+export default xaiDriver;
+//# sourceMappingURL=index.js.map

package/dist/drivers/xai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/drivers/xai/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,CAAC,MAAM,SAAS,GAAW,EAAE,GAAG,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAE1E,eAAe,SAAS,CAAC"}

package/dist/drivers/xai/manifest.js

@@ -0,0 +1,137 @@
+export const GROK_46 = "grok-4.6";
+export const GROK_45 = "grok-4.5";
+export const GROK_43 = "grok-4.3";
+/** The model used when nothing is saved and no env override is set. */
+export const DEFAULT_MODEL = GROK_46;
+/** The models offered by `/model`. First entry is this provider's default. */
+export const MODELS = [
+    { id: GROK_46, label: "Grok 4.6", description: "the current model, strong at code — the default" },
+    { id: GROK_45, label: "Grok 4.5", description: "the previous generation" },
+    { id: GROK_43, label: "Grok 4.3", description: "the reasoning tier, with a 1M window" },
+];
+/** Whether a model takes the `reasoning_effort` dial. Only Grok 4.3 does. */
+export function takesEffort(model) {
+    return model === GROK_43;
+}
+/**
+ * The reasoning levels offered by `/think`.
+ *
+ * xAI's ladder is `none`/`low`/`medium`/`high` — a shorter one than the shared type
+ * carries, and notably WITHOUT `xhigh` or `max`. `none` is the off switch rather
+ * than a separate flag, the same shape OpenAI uses.
+ *
+ * The models with no dial get a single level, and that is an honest statement
+ * rather than a stub: they reason as they reason, and there is no request to make
+ * about it. Offering a switch wired to nothing would be worse.
+ */
+export function thinkLevels(model) {
+    if (takesEffort(model)) {
+        return [
+            { label: "Standard", description: "answer directly — fastest", thinking: false, effort: "low" },
+            { label: "Thinking", description: "think first, then answer", thinking: true, effort: "low" },
+            { label: "Deep", description: "more reasoning, more tool work", thinking: true, effort: "medium" },
+            { label: "Maximum", description: "maximum reasoning budget", thinking: true, effort: "high" },
+        ];
+    }
+    return [{ label: "Standard", description: "this model has no reasoning dial", thinking: false, effort: "low" }];
+}
+/**
+ * List prices (USD / 1M tokens).
+ *
+ * Two caveats. xAI TIERS by prompt size: a request over 200K input tokens bills at
+ * DOUBLE these rates, across the whole request rather than the excess. The shared
+ * `ModelPrice` shape holds one rate, so these are the base tier — right for ordinary
+ * sessions, low for very long ones, which is also why `contextWindow` below sits
+ * where it does.
+ *
+ * Second: only Grok 4.6's figures are confirmed against xAI's own pricing table.
+ * The other two are estimates in its neighbourhood and are marked as such — a wrong
+ * price shows a wrong estimate, where a wrong model id would fail outright, so the
+ * ids were the part worth being certain about.
+ */
+const PRICES = {
+    [GROK_46]: { cacheHit: 0.5, cacheMiss: 2, output: 6 },
+    // Estimated.
+    [GROK_45]: { cacheHit: 0.5, cacheMiss: 2, output: 6 },
+    // Estimated.
+    [GROK_43]: { cacheHit: 0.75, cacheMiss: 3, output: 15 },
+};
+/** Cache-aware list price for a model, falling back to the default model's. */
+export function price(model) {
+    return PRICES[model] ?? PRICES[DEFAULT_MODEL];
+}
+/**
+ * The model's USABLE context window. These models store 500K (Grok 4.3, 1M), but
+ * this is deliberately far below that, and here the reason is billing as much as
+ * attention: crossing 200K input DOUBLES the rate on the entire request, so letting
+ * a transcript drift past that line silently doubles the cost of every later turn.
+ * 128K keeps ordinary sessions well clear of it.
+ */
+export function contextWindow(_model) {
+    return 128_000;
+}
+/**
+ * The ceiling this driver puts on a single BUFFERED (non-streaming) call. Core
+ * reserves exactly this much room below the window, and `client.ts` sends the same
+ * constant, so the request and the reservation cannot drift apart.
+ */
+export const BUFFERED_OUTPUT_TOKENS = 8_000;
+export function bufferedOutputTokens(_model) {
+    return BUFFERED_OUTPUT_TOKENS;
+}
+/**
+ * Vision is deliberately NOT declared. xAI serves image understanding, but through
+ * the separate `grok-imagine-*` line rather than any model offered here.
+ */
+/** The effort rungs this provider accepts, weakest first — note the absent top two. */
+const EFFORTS = ["low", "medium", "high"];
+/**
+ * Coerce a stored or unknown config onto a model this provider actually serves.
+ *
+ * The result is snapped onto a rung `/think` lists, which is what keeps the request
+ * legal: this provider's ladder stops at `high`, so a config carrying `xhigh` or
+ * `max` from another provider must not reach the wire.
+ */
+export function normalize(config) {
+    const model = PRICES[config.model] ? config.model : DEFAULT_MODEL;
+    const thinking = takesEffort(model) ? config.thinking === true : false;
+    const effort = EFFORTS.includes(config.effort) ? config.effort : "low";
+    return { model, thinking, effort: snapToOfferedRung(model, thinking, effort) };
+}
+/**
+ * Move an effort onto the nearest rung this model's `/think` ladder offers. Ties
+ * break DOWNWARD: an unlisted setting resolves to the cheaper neighbour, because
+ * silently spending more of the user's money is the worse way to be wrong.
+ */
+function snapToOfferedRung(model, thinking, effort) {
+    const ladder = ["low", "medium", "high", "xhigh", "max"];
+    const offered = thinkLevels(model).filter((l) => l.thinking === thinking);
+    if (offered.length === 0)
+        return thinkLevels(model)[0].effort;
+    if (offered.some((l) => l.effort === effort))
+        return effort;
+    const want = ladder.indexOf(effort);
+    let best = offered[0];
+    for (const level of offered) {
+        const d = Math.abs(ladder.indexOf(level.effort) - want);
+        const bestD = Math.abs(ladder.indexOf(best.effort) - want);
+        if (d < bestD || (d === bestD && ladder.indexOf(level.effort) < ladder.indexOf(best.effort))) {
+            best = level;
+        }
+    }
+    return best.effort;
+}
+/** The cheap metadata half of this driver — see `index.ts` for the wire half. */
+export const xaiManifest = {
+    id: "xai",
+    label: "xAI",
+    apiKeyEnv: "XAI_API_KEY",
+    keysUrl: "https://console.x.ai/",
+    models: MODELS,
+    thinkLevels,
+    price,
+    contextWindow,
+    bufferedOutputTokens,
+    normalize,
+};
+//# sourceMappingURL=manifest.js.map

package/dist/drivers/xai/manifest.js.map

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

package/dist/dynamo/_probe.tmp.js

@@ -0,0 +1,20 @@
+import { staticSystemPrompt } from "./engine.js";
+import { toolSchemas } from "../tools/registry.js";
+import { basePrompt } from "./prompt.js";
+import { estimateTokens } from "../memory/compaction.js";
+import { readFileSync, existsSync } from "node:fs";
+const root = "D:\Kleopatra";
+const memIdx = "";
+const projMem = existsSync(root + "\GODEN.md") ? readFileSync(root + "\GODEN.md", "utf8") : "";
+const gov = { forbidden: "", skills: "", rules: [] };
+const sys = staticSystemPrompt("", projMem, root + "\memory", memIdx, gov, "", 3);
+const ctx = { cwd: root, governance: { rules: [], skills: [], forbidden: [] } };
+const tools = toolSchemas({ ctx });
+let toolTok = 0;
+for (const t of tools)
+    toolTok += estimateTokens(JSON.stringify(t));
+console.log("basePrompt        ", estimateTokens(basePrompt("PowerShell")));
+console.log("staticSystemPrompt", estimateTokens(sys), `(${sys.length} chars)`);
+console.log("tools             ", toolTok, `over ${tools.length}`);
+console.log("PREFIX TOTAL      ", estimateTokens(sys) + toolTok);
+//# sourceMappingURL=_probe.tmp.js.map

package/dist/dynamo/_probe.tmp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_probe.tmp.js","sourceRoot":"","sources":["../../src/dynamo/_probe.tmp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,IAAI,GAAG,cAAc,CAAC;AAC5B,MAAM,MAAM,GAAG,EAAE,CAAC;AAClB,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,GAAG,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/F,MAAM,GAAG,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,EAAc,EAAE,CAAC;AACjE,MAAM,GAAG,GAAG,kBAAkB,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,GAAY,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3F,MAAM,GAAG,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,EAA4B,CAAC;AAC1G,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;AACnC,IAAI,OAAO,GAAG,CAAC,CAAC;AAChB,KAAK,MAAM,CAAC,IAAI,KAAK;IAAE,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AACpE,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,cAAc,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAC5E,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,MAAM,SAAS,CAAC,CAAC;AAChF,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,OAAO,EAAE,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AACnE,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,cAAc,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC"}

package/dist/dynamo/cacheBreak.js

@@ -0,0 +1,88 @@
+/**
+ * FNV-1a, 32-bit. A non-cryptographic hash is exactly right here: the question is
+ * "are these the same bytes", collisions cost a missed report rather than a wrong
+ * action, and this runs on every request over the whole system prompt.
+ */
+export function hashString(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/** Fingerprint what is about to be sent. */
+export function prefixPrint(model, system, tools, messages = []) {
+    const byName = {};
+    for (const tool of tools) {
+        byName[tool.function.name] = hashString(JSON.stringify(tool));
+    }
+    return {
+        model,
+        system: hashString(system),
+        tools: byName,
+        systemChars: system.length,
+        messages: messages.map((m) => hashString(JSON.stringify(m))),
+    };
+}
+/**
+ * Compare two fingerprints and report the FIRST thing that broke the prefix, in the
+ * order the provider would hit it.
+ *
+ * One finding, not a list, and the order is the point: the parts are nested, so a model
+ * change makes every downstream difference meaningless to report. Naming the outermost
+ * cause is what tells someone where to look.
+ */
+export function diffPrefix(prev, next) {
+    if (prev.model !== next.model) {
+        return { kind: "model", detail: `model changed (${prev.model} → ${next.model})` };
+    }
+    const before = Object.keys(prev.tools);
+    const after = Object.keys(next.tools);
+    const added = after.filter((n) => !(n in prev.tools));
+    const removed = before.filter((n) => !(n in next.tools));
+    if (added.length > 0 || removed.length > 0) {
+        const parts = [
+            added.length > 0 ? `+${added.join(", +")}` : "",
+            removed.length > 0 ? `-${removed.join(", -")}` : "",
+        ].filter(Boolean);
+        return { kind: "tools", detail: `the tool list changed (${parts.join(" ")})` };
+    }
+    // Same names, same count, different bytes: a description or schema built from live
+    // state. Invisible to any check that counts tools, and it breaks the cache every call.
+    const changed = after.filter((n) => prev.tools[n] !== next.tools[n]);
+    if (changed.length > 0) {
+        return {
+            kind: "tool-schema",
+            detail: `${changed.join(", ")} changed shape without changing name — its schema is built from live state`,
+        };
+    }
+    // The conversation, compared only over the length they SHARE. Growth is the normal
+    // case and costs nothing; what breaks the cache is an earlier message changing, and
+    // the first one that did is where the damage starts — everything after it is a
+    // consequence, not a second finding.
+    const shared = Math.min(prev.messages.length, next.messages.length);
+    for (let i = 0; i < shared; i++) {
+        if (prev.messages[i] !== next.messages[i]) {
+            return {
+                kind: "history",
+                detail: `message ${i + 1} of ${shared} was rewritten — everything after it is re-billed`,
+            };
+        }
+    }
+    // Shrinking is a rewrite too, even when every surviving message matches: a dropped
+    // turn moves everything that followed it.
+    if (next.messages.length < prev.messages.length) {
+        return {
+            kind: "history",
+            detail: `the conversation shrank (${prev.messages.length} → ${next.messages.length} messages)`,
+        };
+    }
+    if (prev.system !== next.system) {
+        const delta = next.systemChars - prev.systemChars;
+        const size = delta === 0 ? "same length" : `${delta > 0 ? "+" : ""}${delta} chars`;
+        return { kind: "system", detail: `the system prompt changed (${size})` };
+    }
+    return null;
+}
+//# sourceMappingURL=cacheBreak.js.map

package/dist/dynamo/cacheBreak.js.map

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