@cartanova/qgrid-cli 2.7.5 → 2.7.7

package/bundle/web-dist/server/assets/use-update-token-mutation-BNaRPVaX.js

@@ -0,0 +1,7 @@
+import { g as useMutation, n as QgridService } from "./services.generated-y7xVOTCo.js";
+//#region src/services/token/use-update-token-mutation.ts
+function useUpdateTokenMutation() {
+	return useMutation({ mutationFn: ({ id, name, quotaThreshold, weight, keepaliveEnabled }) => QgridService.updateToken(id, name, quotaThreshold, weight, keepaliveEnabled) });
+}
+//#endregion
+export { useUpdateTokenMutation as t };

package/bundle/web-dist/server/entry-server.generated.js

@@ -1,6 +1,6 @@
-import { A as matchMutation, B as __require, C as infiniteQueryBehavior, D as functionalUpdate, E as notifyManager, F as skipToken, I as focusManager, L as Subscribable, M as noop$1, N as partialMatchKey, O as hashKey, P as resolveStaleTime, R as __commonJSMin, S as Mutation, T as onlineManager, V as __toESM, _ as useQuery, b as require_jsx_runtime, c as SD, d as _enum, f as number$1, j as matchQuery, k as hashQueryKeyByOptions, l as SUPPORTED_LOCALES, m as string$2, n as QgridService, p as object, u as setLocale, v as QueryClientProvider, w as Query, x as require_react, z as __exportAll } from "./assets/services.generated-B5UkNmgc.js";
-import { A as decodePath, C as findRouteMatch, D as createLRUCache, E as processRouteTree, F as last, I as replaceEqualDeep, M as findLast, N as functionalUpdate$1, O as invariant, P as isPromise, S as findFlatMatch, T as processRouteMasks, _ as interpolatePath, a as Link$1, b as trimPath, c as usePrevious$1, d as useRouter, f as getRouterContext, g as cleanPath, h as isNotFound, i as createRootRouteWithContext, j as deepEqual$2, k as createControlledPromise, l as matchContext, m as rootRouteId, n as createFileRoute, p as warning, r as createLazyFileRoute, s as useLayoutEffect$3, t as lazyRouteComponent, u as useRouterState, v as joinPaths, w as findSingleMatch, x as trimPathRight, y as resolvePath } from "./assets/lazyRouteComponent-tS-rTksX.js";
-import { n as require_shim, t as require_react_dom } from "./assets/react-dom-7_SqhNWR.js";
+import { A as matchMutation, B as __require, C as infiniteQueryBehavior, D as functionalUpdate, E as notifyManager, F as skipToken, I as focusManager, L as Subscribable, M as noop$1, N as partialMatchKey, O as hashKey, P as resolveStaleTime, R as __commonJSMin, S as Mutation, T as onlineManager, V as __toESM, b as require_jsx_runtime, c as SD, d as _enum, f as number$1, j as matchQuery, k as hashQueryKeyByOptions, l as SUPPORTED_LOCALES, m as string$2, n as QgridService, o as TokenService, p as object, u as setLocale, v as QueryClientProvider, w as Query, x as require_react, z as __exportAll } from "./assets/services.generated-y7xVOTCo.js";
+import { A as decodePath, C as findRouteMatch, D as createLRUCache, E as processRouteTree, F as last, I as replaceEqualDeep, M as findLast, N as functionalUpdate$1, O as invariant, P as isPromise, S as findFlatMatch, T as processRouteMasks, _ as interpolatePath, a as Link$1, b as trimPath, c as usePrevious$1, d as useRouter, f as getRouterContext, g as cleanPath, h as isNotFound, i as createRootRouteWithContext, j as deepEqual$2, k as createControlledPromise, l as matchContext, m as rootRouteId, n as createFileRoute, p as warning, r as createLazyFileRoute, s as useLayoutEffect$3, t as lazyRouteComponent, u as useRouterState, v as joinPaths, w as findSingleMatch, x as trimPathRight, y as resolvePath } from "./assets/lazyRouteComponent-V1S8gqMS.js";
+import { n as require_shim, t as require_react_dom } from "./assets/react-dom-BFiG5Daf.js";
 import minpath from "node:path";
 import minproc from "node:process";
 import { fileURLToPath as urlToPath } from "node:url";
@@ -46060,6 +46060,24 @@ var lucideX = (props) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("svg", {
 //#region src/assets/chat-icon.png
 var chat_icon_default = "/assets/chat-icon-JYfue7fB.png";
 //#endregion
+//#region src/components/qgrid/chat-token-selection.ts
+function chatTokenOptions(tokens, provider) {
+	return tokens.filter((token) => token.active && token.provider === provider).toSorted((a, b) => a.ord - b.ord || a.name.localeCompare(b.name));
+}
+function providerTokenMissing(tokens, provider) {
+	return provider !== void 0 && !tokens.some((token) => token.active && token.provider === provider);
+}
+function resolvedTokenName(tokenName, options, tokenListLoaded) {
+	if (!tokenName || !tokenListLoaded) return tokenName;
+	return options.some((token) => token.name === tokenName) ? tokenName : "";
+}
+function chatConfigChanged(previous, current) {
+	return previous.model !== current.model || previous.system !== current.system || previous.tokenName !== current.tokenName;
+}
+function tokenTargetPayload(tokenName) {
+	return tokenName ? { tokenName } : {};
+}
+//#endregion
 //#region src/components/qgrid/ChatWidget.tsx
 var CHAT_PROJECT_NAME = "qgrid_chat";
 var DEFAULT_MODEL = "openai/gpt-5.6-terra";
@@ -46104,9 +46122,9 @@ var PROVIDER_LABELS = {
 	openai: "OpenAI",
 	anthropic: "Anthropic"
 };
-function humanizeError(message, provider, stats) {
-	const providerTokenMissing = provider !== void 0 && stats !== void 0 && !stats.some((t) => t.provider === provider);
-	if (/NO_OPENAI_WORKERS|no ready openai workers|no anthropic tokens available/i.test(message) || providerTokenMissing && /기동 중입니다/.test(message)) return `사용 가능한 ${provider ? PROVIDER_LABELS[provider] ?? provider : ""} 토큰이 없습니다. Tokens 페이지에서 토큰을 추가해주세요.`;
+function humanizeError(message, provider, tokens) {
+	const missing = tokens !== void 0 && providerTokenMissing(tokens, provider);
+	if (/NO_OPENAI_WORKERS|no ready openai workers|no anthropic tokens available/i.test(message) || missing && /기동 중입니다/.test(message)) return `사용 가능한 ${provider ? PROVIDER_LABELS[provider] ?? provider : ""} 토큰이 없습니다. Tokens 페이지에서 토큰을 추가해주세요.`;
 	return message;
 }
 function formatCost(costUsd) {
@@ -46130,6 +46148,7 @@ function ChatWidget() {
 	const [messages, setMessages] = (0, import_react.useState)([]);
 	const [draft, setDraft] = (0, import_react.useState)("");
 	const [model, setModel] = (0, import_react.useState)(DEFAULT_MODEL);
+	const [tokenName, setTokenName] = (0, import_react.useState)("");
 	const [effort, setEffort] = (0, import_react.useState)("");
 	const [system, setSystem] = (0, import_react.useState)("");
 	const [settingsOpen, setSettingsOpen] = (0, import_react.useState)(false);
@@ -46143,19 +46162,20 @@ function ChatWidget() {
 	const fileInputRef = (0, import_react.useRef)(null);
 	const provider = model.split("/")[0];
 	const supportsImages = provider === "openai";
-	const { data: tokenStats } = useQuery({
-		...QgridService.statsQueryOptions(),
-		enabled: open,
-		staleTime: 15e3
-	});
-	const statsRef = (0, import_react.useRef)(void 0);
+	const { data: tokensData } = TokenService.useTokens("A", { orderBy: "ord-asc" }, { enabled: open });
+	const tokenOptions = (0, import_react.useMemo)(() => chatTokenOptions(tokensData?.rows ?? [], provider), [provider, tokensData?.rows]);
+	const tokenListLoaded = tokensData?.rows !== void 0;
+	const tokensRef = (0, import_react.useRef)(void 0);
 	(0, import_react.useEffect)(() => {
-		statsRef.current = tokenStats;
-	}, [tokenStats]);
-	const providerTokenMissing = tokenStats !== void 0 && !tokenStats.some((t) => t.provider === provider);
+		tokensRef.current = tokensData?.rows;
+	}, [tokensData?.rows]);
+	const selectedProviderMissing = tokensData?.rows !== void 0 && providerTokenMissing(tokensData.rows, provider);
 	(0, import_react.useEffect)(() => {
 		if (!supportsImages) setAttachments([]);
 	}, [supportsImages]);
+	(0, import_react.useEffect)(() => {
+		setTokenName((current) => resolvedTokenName(current, tokenOptions, tokenListLoaded));
+	}, [tokenListLoaded, tokenOptions]);
 	const addAttachments = async (files) => {
 		if (!files) return;
 		const slots = MAX_ATTACHMENTS - attachments.length;
@@ -46170,7 +46190,7 @@ function ChatWidget() {
 		});
 	};
 	const failStreaming = (message) => {
-		const friendly = humanizeError(message, lastConfigRef.current?.model.split("/")[0], statsRef.current);
+		const friendly = humanizeError(message, lastConfigRef.current?.model.split("/")[0], tokensRef.current);
 		patchLastAssistant((m) => m.status === "streaming" ? {
 			...m,
 			status: "error",
@@ -46234,11 +46254,14 @@ function ChatWidget() {
 		const prompt = draft.trim();
 		if (!prompt || busy) return;
 		const sys = system.trim();
-		if (lastConfigRef.current && (lastConfigRef.current.model !== model || lastConfigRef.current.system !== sys)) threadCoordRef.current = void 0;
-		lastConfigRef.current = {
+		const selectedTokenName = resolvedTokenName(tokenName, tokenOptions, tokenListLoaded);
+		const currentConfig = {
 			model,
-			system: sys
+			system: sys,
+			tokenName: selectedTokenName
 		};
+		if (lastConfigRef.current && chatConfigChanged(lastConfigRef.current, currentConfig)) threadCoordRef.current = void 0;
+		lastConfigRef.current = currentConfig;
 		const images = supportsImages ? attachments : [];
 		const history = buildHistory(messages);
 		setMessages((prev) => [
@@ -46262,6 +46285,7 @@ function ChatWidget() {
 				prompt,
 				model,
 				projectName: CHAT_PROJECT_NAME,
+				...tokenTargetPayload(selectedTokenName),
 				...sys ? { system: sys } : {},
 				...effort ? { effort } : {},
 				...images.length > 0 ? { input: images.map((url) => ({
@@ -46317,7 +46341,11 @@ function ChatWidget() {
 							children: "채팅"
 						}), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", {
 							className: "text-[11px] text-sand-400 truncate leading-tight",
-							children: [model, effort ? ` · ${effort}` : ""]
+							children: [
+								model,
+								effort ? ` · ${effort}` : "",
+								tokenName ? ` · ${tokenName}` : ""
+							]
 						})]
 					}), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 						className: "ml-auto flex items-center gap-0.5",
@@ -46325,7 +46353,7 @@ function ChatWidget() {
 							/* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
 								type: "button",
 								onClick: () => setSettingsOpen((v) => !v),
-								title: "모델·effort·system prompt 설정",
+								title: "모델·토큰·effort·system prompt 설정",
 								className: `size-8 grid place-items-center rounded-full transition-colors duration-150 ${settingsOpen ? "text-sienna-500 bg-sienna-50" : "text-sand-500 hover:text-sand-700 hover:bg-sand-100"}`,
 								children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(lucideSlidersHorizontal, { className: "size-4" })
 							}),
@@ -46349,38 +46377,55 @@ function ChatWidget() {
 				}),
 				settingsOpen && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 					className: "px-4 py-2.5 border-b border-sand-100 bg-sand-50/60 shrink-0 flex flex-col gap-1.5",
-					children: [/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
-						className: "flex items-center gap-1.5",
-						children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("select", {
-							value: model,
-							onChange: (e) => setModel(e.target.value),
-							disabled: busy,
-							className: "min-w-0 flex-1 rounded-xl border border-sand-200/80 bg-white px-2 py-1.5 text-[12px] text-sand-800 focus:outline-none focus:border-sienna-300 disabled:opacity-50",
-							children: MODEL_PRESETS.map((m) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
-								value: m,
-								children: m
-							}, m))
-						}), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("select", {
-							value: effort,
-							onChange: (e) => setEffort(e.target.value),
+					children: [
+						/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+							className: "flex items-center gap-1.5",
+							children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("select", {
+								value: model,
+								onChange: (e) => setModel(e.target.value),
+								disabled: busy,
+								className: "min-w-0 flex-1 rounded-xl border border-sand-200/80 bg-white px-2 py-1.5 text-[12px] text-sand-800 focus:outline-none focus:border-sienna-300 disabled:opacity-50",
+								children: MODEL_PRESETS.map((m) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
+									value: m,
+									children: m
+								}, m))
+							}), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("select", {
+								value: effort,
+								onChange: (e) => setEffort(e.target.value),
+								disabled: busy,
+								className: "rounded-xl border border-sand-200/80 bg-white px-2 py-1.5 text-[12px] text-sand-600 focus:outline-none focus:border-sienna-300 disabled:opacity-50",
+								children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
+									value: "",
+									children: "effort 기본"
+								}), EFFORT_PRESETS.map((v) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
+									value: v,
+									children: v
+								}, v))]
+							})]
+						}),
+						/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("select", {
+							value: tokenName,
+							onChange: (e) => setTokenName(e.target.value),
 							disabled: busy,
-							className: "rounded-xl border border-sand-200/80 bg-white px-2 py-1.5 text-[12px] text-sand-600 focus:outline-none focus:border-sienna-300 disabled:opacity-50",
+							"aria-label": "요청 토큰",
+							className: "w-full rounded-xl border border-sand-200/80 bg-white px-2 py-1.5 text-[12px] text-sand-700 focus:outline-none focus:border-sienna-300 disabled:opacity-50",
 							children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
 								value: "",
-								children: "effort 기본"
-							}), EFFORT_PRESETS.map((v) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
-								value: v,
-								children: v
-							}, v))]
-						})]
-					}), /* @__PURE__ */ (0, import_jsx_runtime.jsx)("textarea", {
-						value: system,
-						onChange: (e) => setSystem(e.target.value),
-						disabled: busy,
-						placeholder: "system prompt (선택)",
-						rows: 2,
-						className: "w-full resize-none rounded-xl border border-sand-200/80 bg-white px-2.5 py-1.5 text-[12px] text-sand-800 placeholder:text-sand-400 focus:outline-none focus:border-sienna-300 disabled:opacity-50"
-					})]
+								children: "토큰 자동 분배"
+							}), tokenOptions.map((token) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
+								value: token.name,
+								children: token.name
+							}, token.name))]
+						}),
+						/* @__PURE__ */ (0, import_jsx_runtime.jsx)("textarea", {
+							value: system,
+							onChange: (e) => setSystem(e.target.value),
+							disabled: busy,
+							placeholder: "system prompt (선택)",
+							rows: 2,
+							className: "w-full resize-none rounded-xl border border-sand-200/80 bg-white px-2.5 py-1.5 text-[12px] text-sand-800 placeholder:text-sand-400 focus:outline-none focus:border-sienna-300 disabled:opacity-50"
+						})
+					]
 				}),
 				/* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
 					ref: scrollRef,
@@ -46480,7 +46525,7 @@ function ChatWidget() {
 						}, i))
 					})
 				}),
-				providerTokenMissing && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+				selectedProviderMissing && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 					className: "px-4 py-1.5 border-t border-caution-400/30 bg-caution-400/10 text-[11px] text-caution-500 shrink-0",
 					children: [
 						PROVIDER_LABELS[provider] ?? provider,
@@ -46580,7 +46625,7 @@ function ChatWidget() {
 }
 //#endregion
 //#region src/components/Sidebar.tsx
-var qgridVersion = "2.7.5";
+var qgridVersion = "2.7.7";
 function Sidebar({ className }) {
 	const pathname = useRouterState({ select: (s) => s.location.pathname });
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("aside", {
@@ -68465,15 +68510,15 @@ function RootComponent() {
 }
 //#endregion
 //#region src/routes/tokens.tsx
-var $$splitComponentImporter$5 = () => import("./assets/tokens-BwlkZELV.js");
+var $$splitComponentImporter$5 = () => import("./assets/tokens-CyItE-L-.js");
 var Route$5 = createFileRoute("/tokens")({ component: lazyRouteComponent($$splitComponentImporter$5, "component") });
 //#endregion
 //#region src/routes/settings.tsx
-var $$splitComponentImporter$4 = () => import("./assets/settings-nCv71sax.js");
+var $$splitComponentImporter$4 = () => import("./assets/settings-JznSjwGQ.js");
 var Route$4 = createFileRoute("/settings")({ component: lazyRouteComponent($$splitComponentImporter$4, "component") });
 //#endregion
 //#region src/routes/monit.tsx
-var $$splitComponentImporter$3 = () => import("./assets/monit-CJBUH0l6.js");
+var $$splitComponentImporter$3 = () => import("./assets/monit-DrJ15xJL.js");
 var monitSearchSchema = object({ level: _enum([
 	"all",
 	"warn",
@@ -68485,7 +68530,7 @@ var Route$3 = createFileRoute("/monit")({
 });
 //#endregion
 //#region src/routes/logs.tsx
-var $$splitComponentImporter$2 = () => import("./assets/logs-ttf79emP.js");
+var $$splitComponentImporter$2 = () => import("./assets/logs-2Tkqcncq.js");
 var logsSearchSchema = object({
 	token: string$2().optional(),
 	project: string$2().optional(),
@@ -68499,11 +68544,11 @@ var Route$2 = createFileRoute("/logs")({
 });
 //#endregion
 //#region src/routes/index.tsx
-var $$splitComponentImporter$1 = () => import("./assets/routes-z79f1sOM.js");
+var $$splitComponentImporter$1 = () => import("./assets/routes-B9X0lvjQ.js");
 var Route$1 = createFileRoute("/")({ component: lazyRouteComponent($$splitComponentImporter$1, "component") });
 //#endregion
 //#region src/routes/requests/show.tsx
-var $$splitComponentImporter = () => import("./assets/show-CLrA4ZQ-.js");
+var $$splitComponentImporter = () => import("./assets/show-D8kuAFbc.js");
 var showSearchSchema = object({ id: number$1() });
 var Route = createFileRoute("/requests/show")({
 	validateSearch: showSearchSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-cli",
-  "version": "2.7.5",
+  "version": "2.7.7",
   "repository": {
     "type": "git",
     "url": "https://github.com/cartanova-ai/qgrid"

package/skills/qgrid/references/cli-env-and-server-boot.md

@@ -66,6 +66,7 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 |---|---:|---|
 | `QGRID_OPENAI_TRANSPORT` | `websocket` | OpenAI transport selector (`https` or `websocket`). Invalid values fail at dispatcher configuration time. This is the only OpenAI runtime knob; there is no concurrency cap. |
 | `QGRID_OPENAI_AUTOSCALE` / `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` / `QGRID_OPENAI_MAX_WORKERS_PER_TOKEN` / `QGRID_OPENAI_PERMITS_PER_TOKEN` | ignored | Removed. OpenAI requests run uncapped like Anthropic (stateless per-request execution); setting these has no effect. |
+| `QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED` (setting `qgrid.tokenWindowKeepaliveEnabled`) | on | Anthropic 5-hour window keepalive. Only the literal `false` disables it; anything else leaves it on. Changing the setting reschedules immediately. Disabling is the only switch — there is no per-token opt-in. |
 | `MAX_STRUCTURED_OUTPUT_RETRIES` | `1` for structured Anthropic streaming calls | Claude Code structured-output retry count for streaming only, clamped to at least 1 by qgrid. Non-streaming `generate` leaves the variable unset and uses Claude Code's default retry budget. |
 
 ## Server boot lifecycle

package/skills/qgrid/references/sonamu-api-web-flow.md

@@ -60,6 +60,8 @@ Structured output visibility: the list has an `Fmt` column (`json` badge from `i
 
 Tool contract visibility: the detail page renders a Tools panel between Response Type and Steps for requests whose `tools` is non-empty. It starts collapsed and its header shows the tool count plus a responsive, truncated name list built from the detail subset — collapsed views issue no extra query. Expanding fires `toolsView` once and caches it for that request id, since a stored tool contract never changes. Each card shows the name, the full description, the parameter count, and a compact display-only zod shape; enum values past the sixth collapse to `/* +N */`, with the full shape reachable through hover and keyboard focus. All JSON Schema conversion happens server-side — the web renders completed strings and holds no schema logic.
 
+Chat token targeting: the dashboard chat panel can pin a conversation to one account. It defaults to automatic distribution and lists only active tokens whose provider matches the selected model, sending the choice as `tokenName` so the request lands on exactly that account with no fallback. Changing either the model or the token resets the existing conversation coordinates, because a thread's prompt cache belongs to the account that built it. A selection that disappears — deactivated or deleted — is cleared automatically, but the selection is preserved while the token list is still loading so a slow fetch does not silently reset the user's choice.
+
 The monit tab's vitals strip shows per-provider in-flight counts, an in-flight sparkline, token chips with quota gauges (fed by the dispatcher's 60-second rate-limits cache; `resetsAt` arrives as ms epoch), and a 1-hour per-provider request/error/cache-hit stats line polled separately every 30 seconds.
 
 Reference input images for image generation render in the detail view under the user prompt from the first synthetic `image_generation` step's `tool_args.inputImages`. Keep the prompt itself text-only, redact large base64 in request JSON views, and avoid rendering duplicate input previews for multi-output image turns.

package/skills/qgrid/references/token-auth-quota-lifecycle.md

@@ -12,6 +12,8 @@ Use this reference before changing token storage, OAuth flows, token activation,
 - Token sync and reconcile
 - Provider runtime consequences
 - Quota threshold semantics
+- Explicit token targeting
+- Token window keepalive
 
 ## Source Files
 
@@ -222,4 +224,26 @@ When a refresh fails in a way that only re-login can fix, qgrid removes the toke
 - If all ready/eligible tokens are over threshold, qgrid throws `QuotaThresholdExceededError`.
 - Log messages use `quota_threshold gate` with reasons such as `over_threshold`, `lookup_fail_open`, and `all_exceeded`.
 
-OpenAI queue items keep an `excludedTokenIds` set so a token found over threshold for a request is not immediately reselected for that same queued request.
+## Explicit Token Targeting
+
+`tokenName` addresses one exact token instead of letting the router choose. It is resolved at the qgrid frame boundary into the dispatcher's existing `preferredTokenId`, so dispatchers stay provider-neutral and no second targeting contract exists.
+
+- Resolution requires an active token matching both provider and name. The provider is read from the name prefix (`anthropic/yds`), and `tokens` carries a `(provider, name)` unique index so the address is unambiguous.
+- A targeted request never falls back. Missing, inactive, or over-threshold targets fail rather than silently serving from another account — the whole point of addressing a token is that the answer comes from that account.
+- Targeted selection does not consume weighted round-robin state. Without that guarantee, background targeting such as keepalive would skew the token distribution of ordinary traffic.
+- Targeting is distinct from cache affinity. Affinity sets `preferredTokenId` as a preference and still falls back when the token is ineligible; explicit targeting adds `requirePreferredToken` so the same field becomes strict. The Anthropic path only ever receives explicit targeting — affinity coordinates are not forwarded there, so making it strict cannot break affinity behavior.
+- Exposure boundary: `tokenName` is not part of the AI SDK provider options. It is reachable on the qgrid frame wire and used by the dashboard chat token picker and internal callers; SDK consumers keep round-robin.
+
+## Token Window Keepalive
+
+Anthropic's 5-hour usage window anchors on the first request, so an unused token has no window at all — `five_hour.resets_at` is null until something is sent, and windows are per-account and independent. The practical cost is that starting work starts the clock: burn the quota in two hours and the remaining three are dead.
+
+Keepalive breaks that coupling by burning the window clock during idle time. Every active Anthropic token gets one cheap request as soon as its window expires, so windows always run and a workday lands mid-window rather than on a boundary. Across an eight-hour day this raises the number of windows the day can touch from a fixed 2 to an expected 2.6.
+
+- Scope is every active Anthropic token. There is no per-token opt-in; the only control is the global switch.
+- The next fire is scheduled from the token's real `resetsAt` rather than a fixed five-hour timer, so a provider-side change to the window length is followed automatically.
+- Per-token fire guards prevent repeats: 61 seconds after a successful fire (the usage API caches for a minute, so an immediate re-read would still show the old window) and five hours after a failure. Guards survive rescheduling — only timers are replaced — and the guard is recorded before the request is sent so a reschedule mid-flight cannot fire a second time.
+- Rescheduling happens only when target-set membership changes (active/provider). Credential rotation updates the token row and fires the change notification, but it does not change membership and must not trigger a sweep; otherwise every OAuth refresh would re-poll usage for every token.
+- Multiple instances each fire. A ping into an already-open window does nothing, so the duplicate is harmless and cheaper than a locking scheme — the same reasoning the expiry reminder uses.
+- Fires are logged under the `qgrid-token-window-keepalive` project name so they can be excluded from traffic statistics.
+- Known limits: the first sweep after boot has no concurrency cap, so N empty windows mean N simultaneous fires; and a failed fire costs that token five hours of window misalignment.