@konneal/engine 0.2.126 → 0.2.131

package/dist/{ask-RAQHKSPN.js → ask-5D2TYRXH.js}

@@ -1,10 +1,10 @@
 import {
   handleAsk
-} from "./chunk-ZHHORWM6.js";
+} from "./chunk-AIL7MJS3.js";
 import "./chunk-J6LBR6GI.js";
-import "./chunk-2JUWER2A.js";
+import "./chunk-7AXXR7GD.js";
 import "./chunk-TH5XGPD5.js";
-import "./chunk-DJ65EF5G.js";
+import "./chunk-W7J5SFXJ.js";
 import "./chunk-A4A26BCV.js";
 import "./chunk-4NXH5ZI6.js";
 import "./chunk-VT7DR6NQ.js";

package/dist/{chunk-2JUWER2A.js → chunk-7AXXR7GD.js}

@@ -9,7 +9,7 @@ import {
 import {
   bubbleConfirmPage,
   isAllowedBubbleOrigin
-} from "./chunk-DJ65EF5G.js";
+} from "./chunk-W7J5SFXJ.js";
 import {
   DATASETS,
   LIMITS,
@@ -24725,6 +24725,18 @@ function usageTotal(usage) {
   const total = p + c;
   return Number.isFinite(total) && total > 0 ? total : null;
 }
+var CREDIT_TOKEN_UNIT = 1e3;
+function creditLimit(env, bucketId) {
+  return Math.floor(tokenLimit(env, bucketId) / CREDIT_TOKEN_UNIT);
+}
+async function creditBudget(env, bucketId) {
+  const b = await tokenBudget(env, bucketId);
+  return { credits_used: Math.ceil(b.used / CREDIT_TOKEN_UNIT), credits_limit: creditLimit(env, bucketId) };
+}
+function creditEstimate(opts) {
+  const effortCredits = opts.effort === "low" ? 1 : opts.effort === "medium" ? 2 : 3;
+  return effortCredits + Math.max(0, opts.toolTurns) + (opts.image ? 1 : 0);
+}
 
 // workers/worker_public/src/graph.ts
 function docNumberOf(nodeId) {
@@ -24816,6 +24828,8 @@ export {
   tokenBudget,
   chargeTokens,
   usageTotal,
+  creditBudget,
+  creditEstimate,
   graphExpand,
   editionNote
 };

package/dist/{chunk-ZHHORWM6.js → chunk-AIL7MJS3.js}

@@ -34,6 +34,8 @@ import {
   citations,
   clientIp,
   contextNote,
+  creditBudget,
+  creditEstimate,
   editionNote,
   estimateTokens,
   experimentalSourceLabels,
@@ -63,7 +65,7 @@ import {
   tokenBudget,
   understandQuery,
   usageTotal
-} from "./chunk-2JUWER2A.js";
+} from "./chunk-7AXXR7GD.js";
 import {
   embed,
   generateOnce,
@@ -76,7 +78,7 @@ import {
   json,
   readJson,
   validateQuery
-} from "./chunk-DJ65EF5G.js";
+} from "./chunk-W7J5SFXJ.js";
 import {
   canonicalRefusal,
   exciseMisplacedPin,
@@ -1788,8 +1790,8 @@ function messageChars(messages) {
   }
   return n;
 }
-async function chargeAnswerTokens(env, bucketId, stats, promptChars, answerChars) {
-  const total = usageTotal(stats?.usage) ?? estimateTokens(promptChars + answerChars);
+async function chargeAnswerTokens(env, bucketId, stats, promptChars, answerChars, extraTokens = 0) {
+  const total = (usageTotal(stats?.usage) ?? estimateTokens(promptChars + answerChars)) + extraTokens;
   await chargeTokens(env, bucketId, total);
   const budget = await tokenBudget(env, bucketId);
   return { tokens_used: budget.used, token_limit: budget.limit };
@@ -1858,15 +1860,18 @@ async function handleAsk(env, ctx, req, tier, key) {
   const effort = requestEffort(env, member, body?.effort);
   const declaredEffort = body?.effort;
   const routeEffort = (route) => route === "fast" && !declaredEffort ? "low" : effort;
-  const limit = tier === "key" ? key.day_limit : tier === "member" || member ? num(env, "MEMBER_DAY_ASK", 300) : num(env, "ANON_DAY_ASK", 20);
-  const bucketId = tier === "key" ? `key:${key.id}` : member ? `sub:${member.sub}` : clientIp(req);
+  const memberKey = tier === "key" ? key?.owner_sub ?? null : null;
+  const limit = memberKey ? num(env, "MEMBER_DAY_ASK", 300) : tier === "key" ? key.day_limit : tier === "member" || member ? num(env, "MEMBER_DAY_ASK", 300) : num(env, "ANON_DAY_ASK", 20);
+  const bucketId = memberKey ? `sub:${memberKey}` : tier === "key" ? `key:${key.id}` : member ? `sub:${member.sub}` : clientIp(req);
   const quota = await checkQuota(env, "ask", bucketId, limit, effort === "low" ? 1 : 2);
+  const creditPreview = creditEstimate({ effort, toolTurns: body?.multi_turn !== false ? 3 : 0, image: false });
   if (!quota.ok) {
     return err(429, "quota_exceeded", `Daily question limit reached (${quota.limit}). Try again tomorrow.`);
   }
   const tokBudget = await tokenBudget(env, bucketId);
   if (tokBudget.used >= tokBudget.limit) {
-    return err(429, "quota_exceeded", `Daily token budget reached (${tokBudget.limit} tokens). Try again tomorrow.`);
+    const cb = await creditBudget(env, bucketId);
+    return err(429, "quota_exceeded", `Daily credits reached (${cb.credits_limit} credits, ${cb.credits_used} used). Try again tomorrow.`);
   }
   quota.tokens_used = tokBudget.used;
   quota.token_limit = tokBudget.limit;
@@ -1928,6 +1933,7 @@ async function handleAsk(env, ctx, req, tier, key) {
   const summary = overflow.length >= 2 ? await summarizeHistory(env, MODELS.understand, overflow) ?? void 0 : void 0;
   let retrieved;
   const fresh = freshRequested(body);
+  const multiTurn = body?.multi_turn !== false;
   const gen = await corpusGen(env.CACHE);
   const withImage = effectiveImage || storedImage;
   const cached = fresh || contextual || declaredCtx || draftAct || apiCallIntent || withImage || ablate ? null : await cacheGet(env, gen, ns, q.query, q.lang, salt);
@@ -2107,7 +2113,7 @@ Certificates are issued per recommendation family \u2014 the register carries no
           context_applied: NO_CONTEXT,
           read: readAs(),
           ...ablate ? { ablate } : {},
-          quota: { ...quota, ...tq2 }
+          quota: { ...quota, ...tq2, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview }
         });
       }
     }
@@ -2143,8 +2149,8 @@ ${summary}` }] : [],
               }
             } catch {
             }
-            const tq2 = await chargeAnswerTokens(env, bucketId, stats, messageChars(messages2), full.length);
-            send({ type: "quota", quota: { ...quota, ...tq2 } });
+            const tq2 = await chargeAnswerTokens(env, bucketId, stats, messageChars(messages2), full.length, probeTokensUsed);
+            send({ type: "quota", quota: { ...quota, ...tq2, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } });
             send({ type: "done", model, query_hash: queryHash2, context_applied: NO_CONTEXT, read: readAs() });
             telemetry(env, ctx, tier, "ask", model, true, full.length, queryHash2, q.lang, void 0, telemetryMeta());
             controller.close();
@@ -2201,7 +2207,7 @@ ${summary}` }] : [],
       );
     }
     const tq2 = await chargeAnswerTokens(env, bucketId, void 0, q.query.length, verdict.answer.length);
-    return json({ answer: verdict.answer, citations: citations2, model, query_hash: queryHash2, follow_ups: [], context_applied: draftCtxApplied, read: readAs(), ...draftPayload ? { draft: draftPayload } : {}, ...ablate ? { ablate } : {}, quota: { ...quota, ...tq2 } });
+    return json({ answer: verdict.answer, citations: citations2, model, query_hash: queryHash2, follow_ups: [], context_applied: draftCtxApplied, read: readAs(), ...draftPayload ? { draft: draftPayload } : {}, ...ablate ? { ablate } : {}, quota: { ...quota, ...tq2, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } });
   }
   if (apiCallIntent) {
     const callCtxApplied = declaredCtx ? appliedContext(declaredCtx, null) : NO_CONTEXT;
@@ -2229,7 +2235,7 @@ ${summary}` }] : [],
       );
     }
     const tq2 = await chargeAnswerTokens(env, bucketId, void 0, q.query.length, verdict.answer.length);
-    return json({ answer: verdict.answer, citations: [], model, query_hash: queryHash2, follow_ups: [], context_applied: callCtxApplied, read: readAs(), ...draftPayload ? { draft: draftPayload } : {}, ...ablate ? { ablate } : {}, quota: { ...quota, ...tq2 } });
+    return json({ answer: verdict.answer, citations: [], model, query_hash: queryHash2, follow_ups: [], context_applied: callCtxApplied, read: readAs(), ...draftPayload ? { draft: draftPayload } : {}, ...ablate ? { ablate } : {}, quota: { ...quota, ...tq2, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } });
   }
   let liveRecords;
   let accountNote;
@@ -2513,7 +2519,8 @@ Answer account questions from these records ONLY: name the record when you use i
   );
   await attachFigureImages(env, messages, usedHits, q.query);
   const pendingTools = [];
-  if (/certificate|certified|certification/i.test(q.query) && env.DB) {
+  let probeTokensUsed = 0;
+  if (multiTurn && /certificate|certified|certification/i.test(q.query) && env.DB) {
     try {
       const imageTurn = typeof withImage === "string";
       if (imageTurn) mark("Reading the photograph to identify the instrument");
@@ -2529,6 +2536,7 @@ ${q.query}`.replace("\n\n\n\n", "\n\n") }];
         reasoning_effort: imageTurn ? "high" : "low"
       });
       const probeText = typeof probe?.response === "string" ? probe.response : probe?.choices?.[0]?.message?.content ?? "";
+      probeTokensUsed += usageTotal(probe?.usage) ?? 0;
       const call = parseToolCall(probeText);
       if (call) {
         mark(`Searching the certificate register for \u201C${String(call.args?.query ?? "")}\u201D`);
@@ -2590,8 +2598,8 @@ ${q.query}`.replace("\n\n\n\n", "\n\n") }];
             }
           } catch {
           }
-          const tq2 = await chargeAnswerTokens(env, bucketId, stats, messageChars(messages), full.length);
-          send({ type: "quota", quota: { ...quota, ...tq2 } });
+          const tq2 = await chargeAnswerTokens(env, bucketId, stats, messageChars(messages), full.length, probeTokensUsed);
+          send({ type: "quota", quota: { ...quota, ...tq2, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } });
           if (withImage && register?.rows?.length && full.includes(refusalAnswer())) {
             console.log("blind-answer(stream): regenerating once");
             mark("Re-answering from the register results");
@@ -2810,8 +2818,8 @@ ${q.query}`.replace("\n\n\n\n", "\n\n") }];
     text: h.text.slice(0, 1200),
     ...h.metadata.table_selection ? { sel: h.metadata.table_selection } : {}
   }));
-  const tq = await chargeAnswerTokens(env, bucketId, void 0, messageChars(messages), answer.length);
-  return json({ ...out, context: contextOut, read: readAs(), quota: { ...quota, ...tq } }, 200, { ...corsHeaders(req), "server-timing": serverTiming() });
+  const tq = await chargeAnswerTokens(env, bucketId, void 0, messageChars(messages), answer.length, probeTokensUsed);
+  return json({ ...out, context: contextOut, read: readAs(), quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } }, 200, { ...corsHeaders(req), "server-timing": serverTiming() });
 }
 function sseResponse(events, cors) {
   const encoder = new TextEncoder();

package/dist/{chunk-P6IRYZLL.js → chunk-MWOY24B6.js}

@@ -6,7 +6,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "./chunk-2JUWER2A.js";
+} from "./chunk-7AXXR7GD.js";
 import {
   portModelRunner
 } from "./chunk-TH5XGPD5.js";
@@ -16,7 +16,7 @@ import {
   json,
   readJson,
   validateQuery
-} from "./chunk-DJ65EF5G.js";
+} from "./chunk-W7J5SFXJ.js";
 import {
   entitlementScope,
   standardKeysFrom

package/dist/{chunk-DJ65EF5G.js → chunk-W7J5SFXJ.js}

@@ -123,7 +123,7 @@ async function authenticate(env, req) {
   if (!m) return null;
   const keyHash = await sha256Hex(m[1].trim());
   const row = await env.DB.prepare(
-    "SELECT id, name, day_limit FROM api_keys WHERE key_hash = ?1 AND revoked = 0"
+    "SELECT id, name, day_limit, owner_sub FROM api_keys WHERE key_hash = ?1 AND revoked = 0"
   ).bind(keyHash).first();
   return row ?? null;
 }

package/dist/openapi-surface.gen.d.ts

@@ -3,7 +3,7 @@ export interface OpenApiRoute {
     pattern: string;
     operationId: string;
 }
-export type OpenApiOperationId = "askAnonymous" | "askKeyed" | "search" | "searchKeyed" | "verify" | "verifyKeyed" | "research" | "researchKeyed" | "mcp" | "datasets" | "keyUsage" | "health" | "listConversations" | "createConversation" | "getConversation" | "renameConversation" | "deleteConversation" | "appendMessage" | "shareConversation" | "getShared" | "uploadAttachment" | "listAttachments" | "getAttachment" | "deleteAttachment" | "listMemories" | "createMemory" | "deleteMemory" | "listProjects" | "createProject" | "deleteProject" | "listProjectFiles" | "attachProjectFile" | "detachProjectFile" | "laneQuery" | "laneKeyed" | "feedback" | "adminEnrich" | "adminEnrichAlias" | "adminSection" | "adminFamilySummary" | "adminSectionAlias" | "adminFamilySummaryAlias" | "adminVectors" | "adminCaption" | "adminJudge" | "adminJudgeAlias" | "adminRevokeKey" | "authMe" | "authLogin" | "authCallback" | "authLogout" | "authLogoutLink" | "adminStats" | "adminListKeys" | "adminCreateKey";
+export type OpenApiOperationId = "credits" | "creditsAlias" | "askAnonymous" | "askKeyed" | "search" | "searchKeyed" | "verify" | "verifyKeyed" | "research" | "researchKeyed" | "mcp" | "datasets" | "keyUsage" | "health" | "listConversations" | "createConversation" | "getConversation" | "renameConversation" | "deleteConversation" | "appendMessage" | "shareConversation" | "getShared" | "uploadAttachment" | "listAttachments" | "getAttachment" | "deleteAttachment" | "listMemories" | "createMemory" | "deleteMemory" | "listProjects" | "createProject" | "deleteProject" | "listProjectFiles" | "attachProjectFile" | "detachProjectFile" | "laneQuery" | "laneKeyed" | "feedback" | "adminEnrich" | "adminEnrichAlias" | "adminSection" | "adminFamilySummary" | "adminSectionAlias" | "adminFamilySummaryAlias" | "adminVectors" | "adminCaption" | "adminJudge" | "adminJudgeAlias" | "adminRevokeKey" | "authMe" | "authLogin" | "authCallback" | "authLogout" | "authLogoutLink" | "adminStats" | "adminListKeys" | "adminCreateKey";
 export declare const OPENAPI_SURFACE: readonly (Omit<OpenApiRoute, "operationId"> & {
     operationId: OpenApiOperationId;
 })[];

package/dist/openapi-types.d.ts

@@ -6,6 +6,46 @@
  */
 
 export interface paths {
+    "/api/credits": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The caller's daily credit balance
+         * @description Returns the credits the caller has left today — resolved by the same tiering as ask (anonymous by IP, member by session, key by its owner member's shared cap). 1 credit ≈ 1000 tokens of consumption; the UI's meter reads this.
+         */
+        get: operations["credits"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/credits": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The caller's daily credit balance (the authenticated path)
+         * @description The same balance, authenticated by session or key.
+         */
+        get: operations["creditsAlias"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/ask": {
         parameters: {
             query?: never;
@@ -998,6 +1038,42 @@ export interface components {
 }
 export type $defs = Record<string, never>;
 export interface operations {
+    credits: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The balance. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    creditsAlias: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The balance. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     askAnonymous: {
         parameters: {
             query?: never;

package/dist/quota.d.ts

@@ -23,3 +23,17 @@ export declare function tokenBudget(env: Env, bucketId: string): Promise<{
 }>;
 export declare function chargeTokens(env: Env, bucketId: string, tokens: number): Promise<void>;
 export declare function usageTotal(usage: unknown): number | null;
+export declare const CREDIT_TOKEN_UNIT = 1000;
+export declare function creditLimit(env: Env, bucketId: string): number;
+export declare function creditBudget(env: Env, bucketId: string): Promise<{
+    credits_used: number;
+    credits_limit: number;
+}>;
+/** The credit-price preview for an ask: effort, tool turns armed, and
+ *  multimodality each add real consumption — the estimate shown BEFORE
+ *  generation so users see what a mode costs. Honest, not exact. */
+export declare function creditEstimate(opts: {
+    effort: string;
+    toolTurns: number;
+    image: boolean;
+}): number;

package/dist/{search-OVUHVV35.js → search-6LP755Q7.js}

@@ -1,9 +1,9 @@
 import {
   handleSearch
-} from "./chunk-P6IRYZLL.js";
-import "./chunk-2JUWER2A.js";
+} from "./chunk-MWOY24B6.js";
+import "./chunk-7AXXR7GD.js";
 import "./chunk-TH5XGPD5.js";
-import "./chunk-DJ65EF5G.js";
+import "./chunk-W7J5SFXJ.js";
 import "./chunk-A4A26BCV.js";
 import "./chunk-4NXH5ZI6.js";
 import "./chunk-VT7DR6NQ.js";

package/dist/worker_mcp/src/index.js

@@ -1,6 +1,6 @@
 import {
   authenticate
-} from "../../chunk-DJ65EF5G.js";
+} from "../../chunk-W7J5SFXJ.js";
 import "../../chunk-VT7DR6NQ.js";
 import {
   P,

package/dist/worker_public/src/index.js

@@ -4,7 +4,7 @@ import {
   handleMemories,
   scoreFaithfulness,
   scoreJudge
-} from "../../chunk-ZHHORWM6.js";
+} from "../../chunk-AIL7MJS3.js";
 import {
   TOOLS_REGISTRY,
   bindModelNode,
@@ -12,10 +12,12 @@ import {
 } from "../../chunk-J6LBR6GI.js";
 import {
   handleSearch
-} from "../../chunk-P6IRYZLL.js";
+} from "../../chunk-MWOY24B6.js";
 import {
   buildMessages,
   citations,
+  clientIp,
+  creditBudget,
   editionNote,
   fill,
   ftsMatchQuery,
@@ -34,7 +36,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "../../chunk-2JUWER2A.js";
+} from "../../chunk-7AXXR7GD.js";
 import {
   cfBlobs,
   embed,
@@ -49,7 +51,7 @@ import {
   readJson,
   validateQuery,
   withCors
-} from "../../chunk-DJ65EF5G.js";
+} from "../../chunk-W7J5SFXJ.js";
 import {
   canonicalRefusal
 } from "../../chunk-A4A26BCV.js";
@@ -710,20 +712,21 @@ async function handleCreateKey(env, req) {
   const body = await readJson(req);
   if (!body?.name || typeof body.name !== "string") return err(400, "invalid_input", "name is required");
   const dayLimit = Number.isFinite(Number(body.day_limit)) && Number(body.day_limit) > 0 ? Number(body.day_limit) : num(env, "KEY_DAY_ASK_DEFAULT", 2e3);
+  const memberSub = typeof body?.member_sub === "string" && body.member_sub.trim() ? body.member_sub.trim().slice(0, 64) : null;
   const raw = `${P().publisher.id}_${[...crypto.getRandomValues(new Uint8Array(24))].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
   const id = crypto.randomUUID();
   const keyHash = await sha256Hex(raw);
   await env.DB.prepare(
-    "INSERT INTO api_keys (id, name, key_hash, day_limit, created_at, revoked) VALUES (?1,?2,?3,?4,?5,0)"
-  ).bind(id, body.name, keyHash, dayLimit, (/* @__PURE__ */ new Date()).toISOString()).run();
-  return json({ id, name: body.name, day_limit: dayLimit, key: raw, note: "Store this key now \u2014 it is not retrievable again." });
+    "INSERT INTO api_keys (id, name, key_hash, day_limit, owner_sub, created_at, revoked) VALUES (?1,?2,?3,?4,?5,?6,0)"
+  ).bind(id, body.name, keyHash, dayLimit, memberSub, (/* @__PURE__ */ new Date()).toISOString()).run();
+  return json({ id, name: body.name, day_limit: dayLimit, ...memberSub ? { member_sub: memberSub } : {}, key: raw, note: "Store this key now \u2014 it is not retrievable again." + (memberSub ? " This key draws from its member's shared daily credit cap." : "") });
 }
 async function handleListKeys(env, req) {
   if (!env.ADMIN_TOKEN) return err(501, "admin_disabled", "ADMIN_TOKEN secret is not configured");
   const auth = req.headers.get("authorization") ?? "";
   if (auth !== `Bearer ${env.ADMIN_TOKEN}`) return err(401, "unauthorized", "Invalid admin token");
   const rows = await env.DB.prepare(
-    "SELECT id, name, day_limit, created_at, revoked FROM api_keys ORDER BY created_at DESC"
+    "SELECT id, name, day_limit, owner_sub, created_at, revoked FROM api_keys ORDER BY created_at DESC"
   ).all();
   return json({ keys: rows.results, ...corsHeaders(req) });
 }
@@ -1049,7 +1052,7 @@ async function callToolOnce(env, ctx, _req, tier, key, name, args, t0) {
       const r = await runTool({ ...env, DB: env.DB }, { name, args }, "mcp");
       payload = r ? { tool: r.name, query: r.query, result: r.output } : { error: { message: `tool ${name} returned nothing for the given arguments` } };
     } else {
-      const res = name === "ask" ? await (await import("../../ask-RAQHKSPN.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-OVUHVV35.js")).handleSearch(env, ctx, inner, tier, key);
+      const res = name === "ask" ? await (await import("../../ask-5D2TYRXH.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-6LP755Q7.js")).handleSearch(env, ctx, inner, tier, key);
       payload = await res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
     }
     telemetry(env, ctx, tier, `mcp:${name}`, null, !payload?.error, JSON.stringify(payload).length, await sha256Hex(`${name}:${JSON.stringify(args ?? {})}`), void 0, void 0, { durationMs: Date.now() - t0 });
@@ -1086,6 +1089,16 @@ function matchRoute(routes, method, path) {
 
 // workers/worker_public/src/openapi-surface.gen.ts
 var OPENAPI_SURFACE = [
+  {
+    "method": "GET",
+    "pattern": "/api/credits",
+    "operationId": "credits"
+  },
+  {
+    "method": "GET",
+    "pattern": "/v1/credits",
+    "operationId": "creditsAlias"
+  },
   {
     "method": "POST",
     "pattern": "/api/ask",
@@ -1495,6 +1508,15 @@ async function mcpRoute(c) {
   if (t instanceof Response) return t;
   return withCors(await handleMcp(c.env, c.ctx, c.req, t.tier, t.key), corsHeaders(c.req));
 }
+async function creditsRoute(c) {
+  const t = await tierFor(c);
+  if (t instanceof Response) return t;
+  const key = t.key;
+  const memberKey = t.tier === "key" ? key?.owner_sub ?? null : null;
+  const bucketId = memberKey ? `sub:${memberKey}` : t.tier === "key" ? `key:${key.id}` : clientIp(c.req);
+  const cb = await creditBudget(c.env, bucketId);
+  return withCors(json({ credits: cb }), corsHeaders(c.req));
+}
 async function askRoute(c) {
   const t = await tierFor(c);
   if (t instanceof Response) return t;
@@ -1784,6 +1806,8 @@ var INFRA_ROUTES = [
 ];
 var OPENAPI_HANDLERS = {
   askAnonymous: askRoute,
+  credits: creditsRoute,
+  creditsAlias: creditsRoute,
   askKeyed: askRoute,
   search: searchRoute,
   searchKeyed: searchRoute,

package/package.json

@@ -27,7 +27,7 @@
     "playwright": "^1.62.1",
     "yaml": "^2.9.1"
   },
-  "version": "0.2.126",
+  "version": "0.2.131",
   "description": "The Konneal engine: the publisher-agnostic build pipeline and API plane for standards intelligence (retrieval, answer contract, verdicts, evaluation).",
   "license": "BSD-3-Clause",
   "type": "module",

package/workers/worker_public/migrations/0019_api_keys_owner.sql

@@ -0,0 +1,6 @@
+-- API keys draw from their OWNER MEMBER's credit cap (the owner's
+-- 2026-10-12 direction): a member-issued key is not a separate budget
+-- tier — key traffic and the member's web traffic share ONE daily
+-- allowance (sub:<owner> bucket). Keys without an owner (service
+-- keys) keep the per-key cap.
+ALTER TABLE api_keys ADD COLUMN owner_sub TEXT;

package/workers/worker_public/openapi.yaml

@@ -58,6 +58,29 @@ tags:
       the index-maintenance battery (enrichment, section units, vectors
       and figure captions).
 paths:
+  /api/credits:
+    get:
+      tags: [Service]
+      summary: The caller's daily credit balance
+      description: >-
+        Returns the credits the caller has left today — resolved by the
+        same tiering as ask (anonymous by IP, member by session, key by
+        its owner member's shared cap). 1 credit ≈ 1000 tokens of
+        consumption; the UI's meter reads this.
+      operationId: credits
+      responses:
+        '200':
+          description: The balance.
+  /v1/credits:
+    get:
+      tags: [Service]
+      summary: The caller's daily credit balance (the authenticated path)
+      description: The same balance, authenticated by session or key.
+      operationId: creditsAlias
+      security: [{ bearerAuth: [] }]
+      responses:
+        '200':
+          description: The balance.
   /api/ask:
     post:
       tags: [Ask]

package/workers/worker_public/schema.sql

@@ -3,6 +3,7 @@ CREATE TABLE IF NOT EXISTS api_keys (
   name       TEXT NOT NULL,
   key_hash   TEXT NOT NULL UNIQUE,
   day_limit  INTEGER NOT NULL DEFAULT 2000,
+  owner_sub  TEXT,
   created_at TEXT NOT NULL,
   revoked    INTEGER NOT NULL DEFAULT 0
 );

package/workers/worker_public/src/admin.ts

@@ -440,15 +440,18 @@ export async function handleCreateKey(env: Env, req: Request): Promise<Response>
   const body = await readJson(req);
   if (!body?.name || typeof body.name !== "string") return err(400, "invalid_input", "name is required");
   const dayLimit = Number.isFinite(Number(body.day_limit)) && Number(body.day_limit) > 0 ? Number(body.day_limit) : num(env as any, "KEY_DAY_ASK_DEFAULT", 2000);
+  // the owner member (2026-10-12): a key minted for a member draws from
+  // HER credit cap — one shared daily allowance across key and web
+  const memberSub = typeof body?.member_sub === "string" && body.member_sub.trim() ? body.member_sub.trim().slice(0, 64) : null;
   const raw = `${P().publisher.id}_${[...crypto.getRandomValues(new Uint8Array(24))].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
   const id = crypto.randomUUID();
   const keyHash = await sha256Hex(raw);
   await env.DB.prepare(
-    "INSERT INTO api_keys (id, name, key_hash, day_limit, created_at, revoked) VALUES (?1,?2,?3,?4,?5,0)",
+    "INSERT INTO api_keys (id, name, key_hash, day_limit, owner_sub, created_at, revoked) VALUES (?1,?2,?3,?4,?5,?6,0)",
   )
-    .bind(id, body.name, keyHash, dayLimit, new Date().toISOString())
+    .bind(id, body.name, keyHash, dayLimit, memberSub, new Date().toISOString())
     .run();
-  return json({ id, name: body.name, day_limit: dayLimit, key: raw, note: "Store this key now — it is not retrievable again." });
+  return json({ id, name: body.name, day_limit: dayLimit, ...(memberSub ? { member_sub: memberSub } : {}), key: raw, note: "Store this key now — it is not retrievable again." + (memberSub ? " This key draws from its member's shared daily credit cap." : "") });
 }
 
 export async function handleListKeys(env: Env, req: Request): Promise<Response> {
@@ -456,7 +459,7 @@ export async function handleListKeys(env: Env, req: Request): Promise<Response>
   const auth = req.headers.get("authorization") ?? "";
   if (auth !== `Bearer ${env.ADMIN_TOKEN}`) return err(401, "unauthorized", "Invalid admin token");
   const rows = await env.DB.prepare(
-    "SELECT id, name, day_limit, created_at, revoked FROM api_keys ORDER BY created_at DESC",
+    "SELECT id, name, day_limit, owner_sub, created_at, revoked FROM api_keys ORDER BY created_at DESC",
   ).all();
   return json({ keys: rows.results, ...corsHeaders(req) });
 }

package/workers/worker_public/src/ask.ts

@@ -42,7 +42,7 @@ import speculativeVerifyPrompt from "../prompts/speculative-verify.md";
 import type { Env } from "./env";
 export type { Env };
 import { json, err, corsHeaders, readJson, validateQuery, type ApiKey } from "./lib/http";
-import { chargeTokens, checkQuota, clientIp, estimateTokens, telemetry, tokenBudget, usageTotal } from "./quota";
+import { chargeTokens, checkQuota, clientIp, creditBudget, creditEstimate, estimateTokens, telemetry, tokenBudget, usageTotal } from "./quota";
 import { graphExpand, editionNote } from "./graph";
 import { registerNote, searchRegister, certificateLinks, registerAggregateIntent, registerAggregate, aggregateNote, aggregateBlock, queryFamily } from "./certificates";
 import { TOOL_DECLARATION, parseToolCall, runTool, toolNote } from "./tools";
@@ -276,8 +276,8 @@ function messageChars(messages: any[]): number {
 /** Post-generation true-up: the model's own usage when the stream
  *  reported it, the character estimate otherwise — charged, then the
  *  budget's fresh state returned for the quota payload. */
-async function chargeAnswerTokens(env: Env, bucketId: string, stats: { usage?: unknown } | undefined, promptChars: number, answerChars: number): Promise<{ tokens_used: number; token_limit: number }> {
-  const total = usageTotal(stats?.usage) ?? estimateTokens(promptChars + answerChars);
+async function chargeAnswerTokens(env: Env, bucketId: string, stats: { usage?: unknown } | undefined, promptChars: number, answerChars: number, extraTokens = 0): Promise<{ tokens_used: number; token_limit: number }> {
+  const total = (usageTotal(stats?.usage) ?? estimateTokens(promptChars + answerChars)) + extraTokens;
   await chargeTokens(env, bucketId, total);
   const budget = await tokenBudget(env, bucketId);
   return { tokens_used: budget.used, token_limit: budget.limit };
@@ -409,18 +409,31 @@ async function handleAsk(
   const routeEffort = (route: "fast" | "deep") =>
     route === "fast" && !declaredEffort ? ("low" as const) : effort;
 
+  // the owner-member law (2026-10-12): a member-owned API key draws
+  // from HER credit cap — key traffic and web traffic share ONE daily
+  // bucket (sub:<owner>), so a key can never multiply an allowance.
+  // Ownerless service keys keep the per-key bucket.
+  const memberKey = tier === "key" ? key?.owner_sub ?? null : null;
   const limit =
-    tier === "key" ? key!.day_limit : tier === "member" || member ? num(env as any, "MEMBER_DAY_ASK", 300) : num(env as any, "ANON_DAY_ASK", 20);
-  const bucketId = tier === "key" ? `key:${key!.id}` : member ? `sub:${member.sub}` : clientIp(req);
+    memberKey ? num(env as any, "MEMBER_DAY_ASK", 300)
+    : tier === "key" ? key!.day_limit
+    : tier === "member" || member ? num(env as any, "MEMBER_DAY_ASK", 300)
+    : num(env as any, "ANON_DAY_ASK", 20);
+  const bucketId = memberKey ? `sub:${memberKey}` : tier === "key" ? `key:${key!.id}` : member ? `sub:${member.sub}` : clientIp(req);
   const quota = await checkQuota(env, "ask", bucketId, limit, effort === "low" ? 1 : 2);
+  const creditPreview = creditEstimate({ effort, toolTurns: body?.multi_turn !== false ? 3 : 0, image: false });
   if (!quota.ok) {
     return err(429, "quota_exceeded", `Daily question limit reached (${quota.limit}). Try again tomorrow.`);
   }
   // the real allowance is the day's TOKENS (the 2026-09-29 shift): the
   // request cap above is the anti-abuse backstop, this is the budget
   const tokBudget = await tokenBudget(env, bucketId);
+  // the credit preview (2026-10-11): what this ask will cost, shown in
+  // the refusal when the day's credits are spent — effort + armed tool
+  // turns + multimodality, one honest number
   if (tokBudget.used >= tokBudget.limit) {
-    return err(429, "quota_exceeded", `Daily token budget reached (${tokBudget.limit} tokens). Try again tomorrow.`);
+    const cb = await creditBudget(env, bucketId);
+    return err(429, "quota_exceeded", `Daily credits reached (${cb.credits_limit} credits, ${cb.credits_used} used). Try again tomorrow.`);
   }
   (quota as any).tokens_used = tokBudget.used;
   (quota as any).token_limit = tokBudget.limit;
@@ -533,6 +546,10 @@ async function handleAsk(
   // / image, not the query text alone. The fresh parse is answercache's
   // single freshRequested, honored at every answer-cache read below.
   const fresh = freshRequested(body);
+  // multi-turn agent (2026-10-11): the tool loop is ON by default — the
+  // model may chain tools; a caller opts OUT for the cheap single-pass
+  // (and the credit estimate prices the difference)
+  const multiTurn = body?.multi_turn !== false;
   // the corpus-generation stamp (KV sys:corpus_gen) namespaces both
   // answer caches; corpus surgery bumps it (scripts/invalidate_answer_
   // cache.py) and old-generation entries miss (oimlsmart/rag#72)
@@ -800,7 +817,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
           context_applied: NO_CONTEXT,
           read: readAs(),
           ...(ablate ? { ablate } : {}),
-          quota: { ...quota, ...tq },
+          quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview },
         });
       }
     }
@@ -843,8 +860,8 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
             } catch {
               // stream ended prematurely — deliver what we have
             }
-            const tq = await chargeAnswerTokens(env, bucketId, stats, messageChars(messages), full.length);
-            send({ type: "quota", quota: { ...quota, ...tq } });
+            const tq = await chargeAnswerTokens(env, bucketId, stats, messageChars(messages), full.length, probeTokensUsed);
+            send({ type: "quota", quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } });
             send({ type: "done", model, query_hash: queryHash, context_applied: NO_CONTEXT, read: readAs() });
             telemetry(env, ctx, tier, "ask", model, true, full.length, queryHash, q.lang, undefined, telemetryMeta());
             controller.close();
@@ -917,7 +934,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
       );
     }
     const tq = await chargeAnswerTokens(env, bucketId, undefined, q.query.length, verdict.answer.length);
-    return json({ answer: verdict.answer, citations, model, query_hash: queryHash, follow_ups: [], context_applied: draftCtxApplied, read: readAs(), ...(draftPayload ? { draft: draftPayload } : {}), ...(ablate ? { ablate } : {}), quota: { ...quota, ...tq } });
+    return json({ answer: verdict.answer, citations, model, query_hash: queryHash, follow_ups: [], context_applied: draftCtxApplied, read: readAs(), ...(draftPayload ? { draft: draftPayload } : {}), ...(ablate ? { ablate } : {}), quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } });
   }
 
   // ── The api_call draft (TODO.ai-platform/09) — the operations
@@ -955,7 +972,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
       );
     }
     const tq = await chargeAnswerTokens(env, bucketId, undefined, q.query.length, verdict.answer.length);
-    return json({ answer: verdict.answer, citations: [], model, query_hash: queryHash, follow_ups: [], context_applied: callCtxApplied, read: readAs(), ...(draftPayload ? { draft: draftPayload } : {}), ...(ablate ? { ablate } : {}), quota: { ...quota, ...tq } });
+    return json({ answer: verdict.answer, citations: [], model, query_hash: queryHash, follow_ups: [], context_applied: callCtxApplied, read: readAs(), ...(draftPayload ? { draft: draftPayload } : {}), ...(ablate ? { ablate } : {}), quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } });
   }
 
   // (declared before the retrieval try: the account block, the refusal
@@ -1392,12 +1409,15 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   // invocations record into pendingTools; the stream emits them as its
   // first events (the UI shows what the agent consulted).
   const pendingTools: { name: string; query: string; output: string }[] = [];
+  // the agent's own consumption (2026-10-11): every tool probe is a real
+  // model call — its usage joins the charge so credits price the true cost
+  let probeTokensUsed = 0;
   // On an IMAGE turn the probe CARRIES THE IMAGE (2026-10-03, the owner's
   // architecture): the model that reads the plate is the model that issues
   // the tool call — one reader, one tool, no parallel extraction racing a
   // second vision pass that drifts hour to hour. The old probe dropped the
   // image-bearing message, which is why the private bridge had to exist.
-  if (/certificate|certified|certification/i.test(q.query) && env.DB) {
+  if (multiTurn && /certificate|certified|certification/i.test(q.query) && env.DB) {
     try {
       const imageTurn = typeof withImage === "string";
       if (imageTurn) mark("Reading the photograph to identify the instrument");
@@ -1409,6 +1429,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
         reasoning_effort: imageTurn ? "high" : "low",
       });
       const probeText = typeof probe?.response === "string" ? probe.response : probe?.choices?.[0]?.message?.content ?? "";
+      probeTokensUsed += usageTotal((probe as any)?.usage) ?? 0;
       const call = parseToolCall(probeText);
       if (call) {
         mark(`Searching the certificate register for “${String(call.args?.query ?? "")}”`);
@@ -1486,8 +1507,8 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
           } catch {
             // stream ended prematurely — deliver what we have
           }
-          const tq = await chargeAnswerTokens(env, bucketId, stats, messageChars(messages), full.length);
-          send({ type: "quota", quota: { ...quota, ...tq } });
+          const tq = await chargeAnswerTokens(env, bucketId, stats, messageChars(messages), full.length, probeTokensUsed);
+          send({ type: "quota", quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } });
           // the blind-answer guard ON THE STREAM PATH (the JSON path has
           // had it since 0.2.80): an image rode the turn, the register
           // note carries rows, and the streamed text is the no-information
@@ -1801,8 +1822,8 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
     text: h.text.slice(0, 1200),
     ...((h.metadata as any).table_selection ? { sel: (h.metadata as any).table_selection } : {}),
   }));
-  const tq = await chargeAnswerTokens(env, bucketId, undefined, messageChars(messages), answer.length);
-  return json({ ...out, context: contextOut, read: readAs(), quota: { ...quota, ...tq } }, 200, { ...corsHeaders(req), "server-timing": serverTiming() });
+  const tq = await chargeAnswerTokens(env, bucketId, undefined, messageChars(messages), answer.length, probeTokensUsed);
+  return json({ ...out, context: contextOut, read: readAs(), quota: { ...quota, ...tq, credits: await creditBudget(env, bucketId), credit_estimate: creditPreview } }, 200, { ...corsHeaders(req), "server-timing": serverTiming() });
 }
 
 function sseResponse(events: unknown[], cors: Record<string, string>): Response {

package/workers/worker_public/src/index.ts

@@ -20,6 +20,7 @@ import type { Env } from "./env";
 import { portModelRunner } from "./env.ts";
 export type { Env };
 import { json, err, corsHeaders, withCors, readJson, authenticate, type ApiKey } from "./lib/http";
+import { creditBudget, clientIp } from "./quota";
 
 import { handleSearch } from "./search";
 import { handleEnrich, handleSectionUnit, handleCaption, handleVectors, handleJudge, handleCreateKey, handleListKeys, handleRevokeKey, handleKeyUsage, handleFamilySummary } from "./admin";
@@ -215,6 +216,19 @@ async function mcpRoute(c: RouteContext): Promise<Response> {
   return withCors(await handleMcp(c.env, c.ctx, c.req, t.tier, t.key), corsHeaders(c.req));
 }
 
+/** The caller's daily credit balance (2026-10-11): the meter the UI
+ *  shows — resolved by the same tiering as ask (anon by IP, member by
+ *  session, key by its owner member's shared cap). */
+async function creditsRoute(c: RouteContext): Promise<Response> {
+  const t = await tierFor(c);
+  if (t instanceof Response) return t;
+  const key = t.key;
+  const memberKey = t.tier === "key" ? key?.owner_sub ?? null : null;
+  const bucketId = memberKey ? `sub:${memberKey}` : t.tier === "key" ? `key:${key!.id}` : clientIp(c.req);
+  const cb = await creditBudget(c.env, bucketId);
+  return withCors(json({ credits: cb }), corsHeaders(c.req));
+}
+
 async function askRoute(c: RouteContext): Promise<Response> {
   const t = await tierFor(c);
   if (t instanceof Response) return t;
@@ -571,6 +585,8 @@ const INFRA_ROUTES: Route[] = [
 
 const OPENAPI_HANDLERS: Record<OpenApiOperationId, RouteHandler> = {
   askAnonymous: askRoute,
+  credits: creditsRoute,
+  creditsAlias: creditsRoute,
   askKeyed: askRoute,
   search: searchRoute,
   searchKeyed: searchRoute,

package/workers/worker_public/src/lib/http.ts

@@ -46,6 +46,11 @@ export interface ApiKey {
   id: string;
   name: string;
   day_limit: number;
+  /** the member whose credit cap this key draws from (the owner's
+   *  2026-10-12 law): a member-owned key shares the member's daily
+   *  allowance — key and web traffic are ONE budget. Null = a service
+   *  key with its own per-key cap. */
+  owner_sub?: string | null;
 }
 
 export async function authenticate(env: Pick<Env, "DB">, req: Request): Promise<ApiKey | null> {
@@ -54,7 +59,7 @@ export async function authenticate(env: Pick<Env, "DB">, req: Request): Promise<
   if (!m) return null;
   const keyHash = await sha256Hex(m[1].trim());
   const row = await env.DB.prepare(
-    "SELECT id, name, day_limit FROM api_keys WHERE key_hash = ?1 AND revoked = 0",
+    "SELECT id, name, day_limit, owner_sub FROM api_keys WHERE key_hash = ?1 AND revoked = 0",
   )
     .bind(keyHash)
     .first<ApiKey>();

package/workers/worker_public/src/openapi-surface.gen.ts

@@ -7,6 +7,8 @@ export interface OpenApiRoute {
 }
 
 export type OpenApiOperationId =
+  | "credits"
+  | "creditsAlias"
   | "askAnonymous"
   | "askKeyed"
   | "search"
@@ -64,6 +66,16 @@ export type OpenApiOperationId =
   | "adminCreateKey"
 
 export const OPENAPI_SURFACE: readonly (Omit<OpenApiRoute, "operationId"> & { operationId: OpenApiOperationId })[] = [
+  {
+    "method": "GET",
+    "pattern": "/api/credits",
+    "operationId": "credits"
+  },
+  {
+    "method": "GET",
+    "pattern": "/v1/credits",
+    "operationId": "creditsAlias"
+  },
   {
     "method": "POST",
     "pattern": "/api/ask",

package/workers/worker_public/src/quota.ts

@@ -95,3 +95,29 @@ export function usageTotal(usage: unknown): number | null {
   const total = p + c;
   return Number.isFinite(total) && total > 0 ? total : null;
 }
+
+// ── credits (2026-10-11, the owner's direction): the user-facing quota
+// unit. 1 credit = CREDIT_TOKEN_UNIT tokens of actual consumption
+// (default 1000 — a simple ask is ~1 credit, an elevated-effort answer
+// a few, a multi-turn agent ask with tool probes what it truly cost).
+// The KV token counters stay the source of truth; credits are their
+// honest denomination. Every quota payload carries them so the UI shows
+// one number users can reason about.
+export const CREDIT_TOKEN_UNIT = 1000;
+
+export function creditLimit(env: Env, bucketId: string): number {
+  return Math.floor(tokenLimit(env, bucketId) / CREDIT_TOKEN_UNIT);
+}
+
+export async function creditBudget(env: Env, bucketId: string): Promise<{ credits_used: number; credits_limit: number }> {
+  const b = await tokenBudget(env, bucketId);
+  return { credits_used: Math.ceil(b.used / CREDIT_TOKEN_UNIT), credits_limit: creditLimit(env, bucketId) };
+}
+
+/** The credit-price preview for an ask: effort, tool turns armed, and
+ *  multimodality each add real consumption — the estimate shown BEFORE
+ *  generation so users see what a mode costs. Honest, not exact. */
+export function creditEstimate(opts: { effort: string; toolTurns: number; image: boolean }): number {
+  const effortCredits = opts.effort === "low" ? 1 : opts.effort === "medium" ? 2 : 3;
+  return effortCredits + Math.max(0, opts.toolTurns) + (opts.image ? 1 : 0);
+}