@cartanova/qgrid-cli 2.4.3 → 2.4.4

package/bundle/web-dist/server/assets/{routes-D9OiKoqa.js → routes-DhIpPgXz.js}

@@ -1,7 +1,8 @@
-import { X as __toESM, _ as require_react, f as require_react_dom, g as require_jsx_runtime, h as useQueryClient } from "./sd.generated-DRuQSIKo.js";
-import { i as TokenService, t as QgridService } from "./services.generated-Dp0uKgpV.js";
+import { X as __toESM, _ as require_react, f as require_react_dom, g as require_jsx_runtime, h as useQueryClient } from "./sd.generated-Cwg2f53z.js";
+import { i as TokenService, t as QgridService } from "./services.generated-CsotZP44.js";
 import { r as Q } from "../entry-server.generated.js";
 import { r as formatUsd } from "./cost-CSH_t17I.js";
+import { t as useUpdateTokenMutation } from "./use-update-token-mutation-BL96w-Pg.js";
 //#region ../../node_modules/.pnpm/@dnd-kit+utilities@3.2.2_react@19.2.4/node_modules/@dnd-kit/utilities/dist/utilities.esm.js
 var import_react_dom = /* @__PURE__ */ __toESM(require_react_dom());
 var import_react = /* @__PURE__ */ __toESM(require_react());
@@ -2318,6 +2319,22 @@ function validateThreshold(raw) {
 		value: n === 0 ? null : n
 	};
 }
+function validateWeight(raw) {
+	const trimmed = raw.trim();
+	if (!/^\d+$/.test(trimmed)) return {
+		ok: false,
+		error: "1–100 사이 정수를 입력하세요"
+	};
+	const value = Number(trimmed);
+	if (value < 1 || value > 100) return {
+		ok: false,
+		error: "1–100 사이 정수를 입력하세요"
+	};
+	return {
+		ok: true,
+		value
+	};
+}
 var PROVIDER_THEMES = {
 	openai: {
 		stripe: "bg-openai-400",
@@ -2439,7 +2456,7 @@ function ThresholdControl({ token }) {
 	const [value, setValue] = (0, import_react.useState)("");
 	const triggerRef = (0, import_react.useRef)(null);
 	const queryClient = useQueryClient();
-	const updateMutation = QgridService.useUpdateTokenMutation();
+	const updateMutation = useUpdateTokenMutation();
 	const supported = QUOTA_THRESHOLD_PROVIDERS.has(token.provider);
 	const open = pos !== null;
 	const validation = validateThreshold(value);
@@ -2474,7 +2491,6 @@ function ThresholdControl({ token }) {
 		if (!validation.ok) return;
 		await updateMutation.mutateAsync({
 			id: token.id,
-			name: token.name ?? "",
 			quotaThreshold: validation.value
 		});
 		await Promise.all([queryClient.invalidateQueries({ queryKey: ["Token"] }), queryClient.invalidateQueries({ queryKey: ["Qgrid"] })]);
@@ -2560,6 +2576,113 @@ function ThresholdControl({ token }) {
 		})] })]
 	});
 }
+function WeightControl({ token }) {
+	const [pos, setPos] = (0, import_react.useState)(null);
+	const [value, setValue] = (0, import_react.useState)("");
+	const triggerRef = (0, import_react.useRef)(null);
+	const queryClient = useQueryClient();
+	const updateMutation = useUpdateTokenMutation();
+	const validation = validateWeight(value);
+	const openPopover = () => {
+		const rect = triggerRef.current?.getBoundingClientRect();
+		if (!rect) return;
+		const width = 240;
+		const height = 150;
+		const margin = 8;
+		const gap = 6;
+		const left = Math.min(Math.max(rect.right - width, margin), Math.max(window.innerWidth - width - margin, margin));
+		const above = rect.top - gap - height;
+		const top = Math.min(Math.max(above >= margin ? above : rect.bottom + gap, margin), Math.max(window.innerHeight - height - margin, margin));
+		setValue(String(token.weight));
+		setPos({
+			left,
+			top
+		});
+	};
+	const close = () => setPos(null);
+	const adjust = (delta) => {
+		const current = /^\d+$/.test(value.trim()) ? Number(value.trim()) : 1;
+		setValue(String(Math.min(Math.max(current + delta, 1), 100)));
+	};
+	const save = async () => {
+		if (!validation.ok) return;
+		await updateMutation.mutateAsync({
+			id: token.id,
+			weight: validation.value
+		});
+		await Promise.all([queryClient.invalidateQueries({ queryKey: ["Token"] }), queryClient.invalidateQueries({ queryKey: ["Qgrid"] })]);
+		close();
+	};
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+		className: "inline-flex",
+		onPointerDown: stopDragPropagation,
+		onClick: stopDragPropagation,
+		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("button", {
+			ref: triggerRef,
+			type: "button",
+			title: "라우팅 가중치 설정",
+			onClick: pos ? close : openPopover,
+			className: "flex items-center gap-1 px-1.5 py-0.5 rounded-md text-[10px] border border-sand-200/80 text-sand-400 hover:text-sand-600 hover:border-sand-300 transition-colors duration-150",
+			children: ["Weight ", token.weight]
+		}), pos && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
+			className: "fixed inset-0 z-40",
+			onPointerDown: close
+		}), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+			className: "fixed z-50 w-60 panel shadow-xl p-3",
+			style: pos,
+			children: [
+				/* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", {
+					htmlFor: `weight-${token.id}`,
+					className: "text-[10px] uppercase tracking-wider text-sand-500 font-medium",
+					children: "라우팅 가중치"
+				}),
+				/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+					className: "mt-1 flex items-center gap-2",
+					children: [
+						/* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
+							type: "button",
+							onClick: () => adjust(-1),
+							className: "size-9 shrink-0 rounded-md border border-sand-200 text-sand-600",
+							children: "−"
+						}),
+						/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Q, {
+							id: `weight-${token.id}`,
+							value,
+							onChange: (event) => setValue(event.target.value),
+							inputMode: "numeric",
+							className: `h-9 w-16 border rounded-md text-center text-sm tabular-nums ${validation.ok ? "border-sand-200" : "border-red-300"}`
+						}),
+						/* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
+							type: "button",
+							onClick: () => adjust(1),
+							className: "size-9 shrink-0 rounded-md border border-sand-200 text-sand-600",
+							children: "+"
+						})
+					]
+				}),
+				/* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", {
+					className: `mt-1.5 text-[11px] ${validation.ok ? "text-sand-500" : "text-red-500"}`,
+					children: validation.ok ? "새 요청의 상대 배정 비율입니다." : validation.error
+				}),
+				/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+					className: "mt-2 flex items-center justify-end gap-1.5",
+					children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
+						type: "button",
+						onClick: close,
+						className: "px-2 py-1 text-[11px]",
+						children: "Cancel"
+					}), /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
+						type: "button",
+						onClick: save,
+						disabled: updateMutation.isPending || !validation.ok,
+						className: "px-2 py-1 text-[11px] rounded-md bg-sienna-400 text-white disabled:opacity-50",
+						children: updateMutation.isPending ? "Saving..." : "Save"
+					})]
+				})
+			]
+		})] })]
+	});
+}
 function SortableTokenCard({ token }) {
 	const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
 		id: String(token.id),
@@ -2606,9 +2729,9 @@ function SortableTokenCard({ token }) {
 					token,
 					theme
 				}),
-				/* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
-					className: "mt-2 flex items-center justify-end",
-					children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ThresholdControl, { token })
+				/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+					className: "mt-2 flex items-center justify-end gap-1.5",
+					children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(WeightControl, { token }), /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ThresholdControl, { token })]
 				}),
 				/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 					className: "absolute top-2.5 right-3 flex items-center gap-1.5",

package/bundle/web-dist/server/assets/{sd.generated-DRuQSIKo.js → sd.generated-Cwg2f53z.js}

@@ -22600,6 +22600,7 @@ var entityLabels = {
 	"entity.Token.active": "활성 여부",
 	"entity.Token.ord": "정렬 순서",
 	"entity.Token.quota_threshold": "quota 사용률 임계치(%). null이면 미설정",
+	"entity.Token.weight": "가중 라운드로빈 라우팅 가중치 (1..100)",
 	"enum.TokenOrderBy.id-desc": "ID최신순",
 	"enum.TokenOrderBy.ord-asc": "순서순",
 	"enum.TokenSearchField.id": "ID",

package/bundle/web-dist/server/assets/{services.generated-Dp0uKgpV.js → services.generated-CsotZP44.js}

@@ -1,4 +1,4 @@
-import { A as hashKey, B as shallowEqualObjects, D as pendingThenable, E as notifyManager, F as noop, G as focusManager, K as Subscribable, L as replaceData, M as isValidTimeout, O as environmentManager, R as resolveEnabled, S as infiniteQueryBehavior, U as timeUntilStale, V as shouldThrowError, W as timeoutManager, X as __toESM, _ as require_react, a as fetch, b as hasNextPage, d as require_lib, g as require_jsx_runtime, h as useQueryClient, i as dedupeAndFlatten, o as useRefreshable, s as useSSEStream, w as fetchState, x as hasPreviousPage, y as getDefaultState, z as resolveStaleTime } from "./sd.generated-DRuQSIKo.js";
+import { A as hashKey, B as shallowEqualObjects, D as pendingThenable, E as notifyManager, F as noop, G as focusManager, K as Subscribable, L as replaceData, M as isValidTimeout, O as environmentManager, R as resolveEnabled, S as infiniteQueryBehavior, U as timeUntilStale, V as shouldThrowError, W as timeoutManager, X as __toESM, _ as require_react, a as fetch, b as hasNextPage, d as require_lib, g as require_jsx_runtime, h as useQueryClient, i as dedupeAndFlatten, o as useRefreshable, s as useSSEStream, w as fetchState, x as hasPreviousPage, y as getDefaultState, z as resolveStaleTime } from "./sd.generated-Cwg2f53z.js";
 //#region ../../node_modules/.pnpm/@tanstack+query-core@5.95.2/node_modules/@tanstack/query-core/build/modern/queryObserver.js
 var QueryObserver = class extends Subscribable {
 	constructor(client, options) {
@@ -1036,19 +1036,19 @@ var QgridService;
 	}
 	_QgridService.addToken = addToken;
 	_QgridService.useAddTokenMutation = () => useMutation({ mutationFn: (params) => addToken(params.provider, params.credentials, params.name) });
-	async function updateToken(id, name, quotaThreshold) {
+	async function updateToken(id, name, quotaThreshold, weight) {
 		return fetch({
 			method: "POST",
 			url: `/api/qgrid/updateToken`,
 			data: {
 				id,
 				name,
-				quotaThreshold
+				quotaThreshold,
+				weight
 			}
 		});
 	}
 	_QgridService.updateToken = updateToken;
-	_QgridService.useUpdateTokenMutation = () => useMutation({ mutationFn: (params) => updateToken(params.id, params.name, params.quotaThreshold) });
 	async function removeToken(id) {
 		return fetch({
 			method: "POST",
@@ -1124,4 +1124,4 @@ RequestLogService.useRequestLogs, RequestLogService.useRequestLogsInfinite;
 RequestLogStepService.useRequestLogSteps, RequestLogStepService.useRequestLogStepsInfinite;
 TokenService.useTokens, TokenService.useTokensInfinite;
 //#endregion
-export { TokenService as i, RequestLogService as n, RequestLogStepService as r, QgridService as t };
+export { useMutation as a, TokenService as i, RequestLogService as n, RequestLogStepService as r, QgridService as t };

package/bundle/web-dist/server/assets/{show-3GokIDEJ.js → show-CV2UFjaH.js}

@@ -1,6 +1,6 @@
-import { J as __exportAll, X as __toESM, _ as require_react, g as require_jsx_runtime, q as __commonJSMin } from "./sd.generated-DRuQSIKo.js";
-import { n as RequestLogService, r as RequestLogStepService } from "./services.generated-Dp0uKgpV.js";
-import { a as Link } from "./lazyRouteComponent-BswulcOx.js";
+import { J as __exportAll, X as __toESM, _ as require_react, g as require_jsx_runtime, q as __commonJSMin } from "./sd.generated-Cwg2f53z.js";
+import { n as RequestLogService, r as RequestLogStepService } from "./services.generated-CsotZP44.js";
+import { a as Link } from "./lazyRouteComponent-BrPAFtBA.js";
 import { t as Route } from "../entry-server.generated.js";
 import { n as formatMicroUsd, t as cacheHitRate } from "./cost-CSH_t17I.js";
 import minpath from "node:path";

package/bundle/web-dist/server/assets/{tokens-Cjw6cQxZ.js → tokens-DfGj1y2v.js}

@@ -1,6 +1,7 @@
-import { X as __toESM, _ as require_react, g as require_jsx_runtime, h as useQueryClient } from "./sd.generated-DRuQSIKo.js";
-import { i as TokenService, t as QgridService } from "./services.generated-Dp0uKgpV.js";
+import { X as __toESM, _ as require_react, g as require_jsx_runtime, h as useQueryClient } from "./sd.generated-Cwg2f53z.js";
+import { i as TokenService, t as QgridService } from "./services.generated-CsotZP44.js";
 import { i as lucideKeyRound, r as Q } from "../entry-server.generated.js";
+import { t as useUpdateTokenMutation } from "./use-update-token-mutation-BL96w-Pg.js";
 //#region ~icons/lucide/plus.jsx
 var import_react = /* @__PURE__ */ __toESM(require_react());
 var import_jsx_runtime = require_jsx_runtime();
@@ -216,7 +217,7 @@ function TokenTable({ data, isLoading }) {
 	const [editName, setEditName] = (0, import_react.useState)("");
 	const queryClient = useQueryClient();
 	const removeMutation = QgridService.useRemoveTokenMutation();
-	const updateMutation = QgridService.useUpdateTokenMutation();
+	const updateMutation = useUpdateTokenMutation();
 	const toggleMutation = QgridService.useToggleTokenMutation();
 	const invalidate = () => Promise.all([queryClient.invalidateQueries({ queryKey: ["Token"] }), queryClient.invalidateQueries({ queryKey: ["Qgrid"] })]);
 	const handleToggle = async (token) => {
@@ -237,8 +238,7 @@ function TokenTable({ data, isLoading }) {
 		if (!editTarget) return;
 		await updateMutation.mutateAsync({
 			id: editTarget.id,
-			name: editName.trim(),
-			quotaThreshold: editTarget.quota_threshold
+			name: editName.trim()
 		});
 		await invalidate();
 		setEditTarget(null);

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

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

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

@@ -1,5 +1,5 @@
-import { A as hashKey, C as Query, E as notifyManager, F as noop$1, G as focusManager, H as skipToken, I as partialMatchKey, K as Subscribable, N as matchMutation, P as matchQuery, S as infiniteQueryBehavior, T as onlineManager, X as __toESM, Y as __require, _ as require_react, c as number, f as require_react_dom, g as require_jsx_runtime, j as hashQueryKeyByOptions, k as functionalUpdate, l as object, m as QueryClientProvider, n as SUPPORTED_LOCALES, p as require_shim, q as __commonJSMin, r as setLocale, t as SD, u as string, v as Mutation, z as resolveStaleTime } from "./assets/sd.generated-DRuQSIKo.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-BswulcOx.js";
+import { A as hashKey, C as Query, E as notifyManager, F as noop$1, G as focusManager, H as skipToken, I as partialMatchKey, K as Subscribable, N as matchMutation, P as matchQuery, S as infiniteQueryBehavior, T as onlineManager, X as __toESM, Y as __require, _ as require_react, c as number, f as require_react_dom, g as require_jsx_runtime, j as hashQueryKeyByOptions, k as functionalUpdate, l as object, m as QueryClientProvider, n as SUPPORTED_LOCALES, p as require_shim, q as __commonJSMin, r as setLocale, t as SD, u as string, v as Mutation, z as resolveStaleTime } from "./assets/sd.generated-Cwg2f53z.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-BrPAFtBA.js";
 //#region ../../node_modules/.pnpm/@tanstack+query-core@5.95.2/node_modules/@tanstack/query-core/build/modern/hydration.js
 function defaultTransformerFn(data) {
 	return data;
@@ -22679,7 +22679,7 @@ var sections = [{
 		icon: lucideFileText
 	}]
 }];
-var qgridVersion = "2.4.3";
+var qgridVersion = "2.4.4";
 function Sidebar({ className }) {
 	const pathname = useRouterState({ select: (s) => s.location.pathname });
 	const isActive = (path) => {
@@ -44559,11 +44559,11 @@ function RootComponent() {
 }
 //#endregion
 //#region src/routes/tokens.tsx
-var $$splitComponentImporter$3 = () => import("./assets/tokens-Cjw6cQxZ.js");
+var $$splitComponentImporter$3 = () => import("./assets/tokens-DfGj1y2v.js");
 var Route$3 = createFileRoute("/tokens")({ component: lazyRouteComponent($$splitComponentImporter$3, "component") });
 //#endregion
 //#region src/routes/logs.tsx
-var $$splitComponentImporter$2 = () => import("./assets/logs-Bk9C0ELo.js");
+var $$splitComponentImporter$2 = () => import("./assets/logs-CKM6W3W6.js");
 var logsSearchSchema = object({
 	token: string().optional(),
 	project: string().optional(),
@@ -44575,11 +44575,11 @@ var Route$2 = createFileRoute("/logs")({
 });
 //#endregion
 //#region src/routes/index.tsx
-var $$splitComponentImporter$1 = () => import("./assets/routes-D9OiKoqa.js");
+var $$splitComponentImporter$1 = () => import("./assets/routes-DhIpPgXz.js");
 var Route$1 = createFileRoute("/")({ component: lazyRouteComponent($$splitComponentImporter$1, "component") });
 //#endregion
 //#region src/routes/requests/show.tsx
-var $$splitComponentImporter = () => import("./assets/show-3GokIDEJ.js");
+var $$splitComponentImporter = () => import("./assets/show-CV2UFjaH.js");
 var showSearchSchema = object({ id: number() });
 var Route = createFileRoute("/requests/show")({
 	validateSearch: showSearchSchema,

package/package.json

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

package/skills/qgrid/SKILL.md

@@ -15,7 +15,7 @@ Before changing code, identify the affected path:
 - CLI startup, env vars, server boot, OAuth callback URL: read `references/cli-env-and-server-boot.md`.
 - OpenAI models or Codex worker/thread/cache behavior: read `references/openai-codex-runtime.md`.
 - Anthropic models or Claude Code spawn/stream-json behavior: read `references/anthropic-claude-code-runtime.md`.
-- Token registration, OAuth, token sync, active/inactive behavior, or quota thresholds: read `references/token-auth-quota-lifecycle.md`.
+- Token registration, OAuth, token sync, active/inactive behavior, quota thresholds, or weighted token routing: read `references/token-auth-quota-lifecycle.md`.
 - Provider comparisons, routing, or cross-provider bugs: read `references/provider-runtime-differences.md`.
 - Tool calling, AI SDK multi-step loops, or tool-call request logs: read `references/tool-calling-and-multiturn.md`.
 - `sessionKey`, `threadCoord`, prompt cache metrics, usage accounting, or cost: read `references/prompt-cache-and-usage.md`.

package/skills/qgrid/references/anthropic-claude-code-runtime.md

@@ -37,8 +37,8 @@ Anthropic tokens live in an in-memory `Map<tokenId, PooledToken>`.
 - Startup loads active Anthropic tokens from DB.
 - Token subscriber events add/update/remove entries.
 - Periodic reconcile replaces pool contents from active DB rows.
-- Request selection is least-used plus round-robin tie-break.
-- Request count is incremented before awaiting execution so concurrent requests spread across tokens.
+- Request selection is smooth weighted round-robin over quota-eligible tokens, driven by per-token `tokens.weight` (shared selector in `providers/common/smooth-weighted-round-robin.ts`).
+- Selection and score mutation run synchronously before any await, so concurrent requests observe committed prior selections and spread across tokens.
 
 Quota threshold:
 

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

@@ -50,15 +50,15 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 
 ## Server boot lifecycle
 
-On server start, `packages/api/src/sonamu.config.ts`:
-
-1. Loads `.env` from `packages/api/.env` when running API directly.
-2. Configures Sonamu database connection from `QGRID_DB_*`.
-3. Runs latest migrations from `packages/api/src/migrations`.
-4. Ensures PostgreSQL `tokens_changed` triggers.
-5. Starts `TokenSubscriber` for LISTEN/NOTIFY plus periodic reconcile.
-6. Starts `OpenAIDispatcher` and `AnthropicDispatcher`.
-7. Logs server URL and provider readiness counts.
+`packages/api/src/index.ts` runs `bootstrapServer` (`server-bootstrap.ts`) with a strict init → migrate → listen order:
+
+1. `Sonamu.init()` loads `.env` from `packages/api/.env` when running API directly and configures the Sonamu database connection from `QGRID_DB_*`.
+2. `runRequiredMigrations` (`startup-migrations.ts`) applies latest migrations from `packages/api/src/migrations` before the server listens. Migration failure exits the process — qgrid must not boot against a schema missing required columns such as `tokens.weight`. This is a hard-fail; it used to be a soft-fail warn inside `onStart`.
+3. `Sonamu.createServer()` starts the server. Its `onStart` in `packages/api/src/sonamu.config.ts`:
+   1. Ensures PostgreSQL `tokens_changed` triggers.
+   2. Starts `TokenSubscriber` for LISTEN/NOTIFY plus periodic reconcile.
+   3. Starts `OpenAIDispatcher` and `AnthropicDispatcher`.
+   4. Logs server URL and provider readiness counts.
 
 On shutdown, it stops provider dispatchers and the token subscriber.
 

package/skills/qgrid/references/decision-rationale.md

@@ -11,6 +11,7 @@ Do not copy these notes blindly into implementation. Use them to find the releva
 - OpenAI/Codex runtime
 - Anthropic/Claude Code runtime
 - Token sync and quota thresholds
+- Weighted token routing
 - Request logs, metrics, and dashboard
 - CLI packaging and server boot
 - Image generation
@@ -119,6 +120,28 @@ Key decisions:
 - Lookup failure is fail-open with logs/metrics. Hard failure happens only when usage was read successfully and the token is over threshold.
 - OpenAI needs the gate in reuse, idle selection, and queue drain paths. A reusable but over-threshold worker must fall back cold to another eligible token when possible.
 
+## Weighted Token Routing
+
+Sources:
+
+- `docs/brainstorms/2026-07-10-weighted-token-routing-requirements.md`
+- `docs/plans/2026-07-10-weighted-token-routing-plan.md`
+
+Key decisions:
+
+- `tokens.weight` is a per-token integer from 1 to 100 defaulting to 1. It is a relative routing share for new requests, not an enable/disable switch. Weight 0 is invalid; disabling a token stays on `active`.
+- Both providers share one smooth weighted round-robin selector in the provider common layer. The selector knows only token ids, weights, and current scores. Dispatchers own quota, lifecycle, and worker availability, and pass in only the eligible token id set per selection. Do not teach the selector about credentials, workers, or queues.
+- The quota threshold gate runs before weighted selection. An over-threshold token receives no weighted assignment regardless of weight, and the schedule is computed from the remaining eligible tokens.
+- OpenAI thread reuse stays pinned to its original worker and neither reads nor mutates weighted-selector state. Cache affinity intentionally beats weight distribution; only cold requests are weighted.
+- OpenAI routing is work-conserving. A token whose workers are all busy is omitted from the current selection round instead of making requests wait for the heavy-weight token. Queue drain re-runs weighted selection for the head item; the previous released-worker shortcut was removed because it bypassed weighting.
+- Candidate collection, selector mutation, and worker acquisition must run without an intervening `await`. A weighted score is consumed only when the dispatcher can commit the assignment synchronously; this is what keeps concurrent Anthropic selections spread correctly.
+- Selector scores reset when token topology or configured weights change. Temporary ineligibility from quota or busy workers only excludes the token from that selection's candidate set and does not reset schedule state.
+- Weight-change notification is owned by the versioned migration trigger (`tokens_weight_changed_upd`); the boot-time trigger setup SQL intentionally excludes `weight` from its WHEN clause, and a test pins this so exactly one trigger fires per weight-only change.
+- The token subscriber serializes notification and reconcile handling through an operation chain because weight propagation made dispatcher updates awaited; out-of-order token events could otherwise apply stale weights.
+- Required migrations moved from a soft-fail `onStart` step to a hard-fail `bootstrapServer` order (init → migrate → listen). Dispatchers must never boot against a schema missing `tokens.weight`.
+- `updateToken` became a partial field update (`TokenModel.updateFields`) so the dashboard weight control cannot overwrite name or quota threshold edits happening elsewhere.
+- Explicit scope boundaries: no per-model, per-project, per-request, or time-varying weights, and no automatic weight adjustment from remaining quota, latency, cost, errors, or worker counts.
+
 ## Request Logs, Metrics, And Dashboard
 
 Sources:

package/skills/qgrid/references/openai-codex-runtime.md

@@ -100,9 +100,10 @@ There is no explicit close RPC for old ephemeral threads; qgrid removes them fro
 
 OpenAI worker selection:
 
-- Prefer reuse worker when a valid reuse coordinate exists.
-- Otherwise select an idle ready active worker round-robin across eligible workers.
-- If no worker is free, enqueue.
+- Prefer reuse worker when a valid reuse coordinate exists. Successful reuse bypasses weighted selection and does not read or mutate its state.
+- Otherwise cold selection is two-level: group quota-eligible ready active workers by token, keep only tokens with at least one idle worker, choose the token with the shared smooth weighted round-robin selector (`providers/common/smooth-weighted-round-robin.ts`, driven by `tokens.weight`), then rotate a per-token worker cursor inside the chosen token.
+- Selection is work-conserving: a token whose workers are all busy is omitted from that selection round, so an idle lower-weight token receives the request immediately instead of waiting for the heavy token.
+- If no eligible worker is idle, enqueue. Queue drain re-runs the same weighted cold selection; it must not hand the queue head to the worker that happened to finish first.
 - Queue timeout: 60 seconds.
 - Max queue size: 50.
 

package/skills/qgrid/references/prompt-cache-and-usage.md

@@ -45,6 +45,8 @@ Cache hit requires:
 
 When reuse succeeds, qgrid sends only delta input to `turn/start`. When reuse fails, qgrid falls back to cold execution with full prompt plus history injection.
 
+Reuse is decided before weighted token routing and stays pinned to its original worker: a successful reuse neither consumes nor advances the weighted schedule. Cache affinity intentionally beats weight distribution; only cold requests are weighted.
+
 Important cache breakers:
 
 - Different system prompt.

package/skills/qgrid/references/provider-runtime-differences.md

@@ -8,7 +8,8 @@ Use this reference when comparing OpenAI and Anthropic behavior, debugging provi
 | Worker pool | Token x `QGRID_WORKERS_PER_TOKEN`, default 3, max 5 | No workers; in-memory token pool only |
 | Worker id | `tokenId * 10 + workerIndex` | `tokenId` |
 | Epoch | Worker spawn counter; changes on restart | Always `0` |
-| Request concurrency | One turn per worker; queue when all eligible workers busy | Fresh process per request; token selection uses least-used RR |
+| Request concurrency | One turn per worker; queue when all eligible workers busy | Fresh process per request |
+| Token selection | Smooth weighted RR picks a quota-eligible token with an idle worker, then a per-token worker cursor; reuse bypasses weights | Smooth weighted RR over quota-eligible tokens per request |
 | Model routing | `openai/*`; qgrid strips provider prefix before provider call | `anthropic/*`; provider canonicalizes model and strips prefix/`[1m]` |
 | Prefix-less models | Fallback not implemented | Fallback not implemented |
 | Thread/session | Ephemeral Codex thread stored in worker memory | Fresh Claude `--session-id` per request |

package/skills/qgrid/references/repo-map.md

@@ -26,6 +26,8 @@ Use this map to orient qgrid work quickly.
 - OpenAI Codex runtime: `packages/api/src/utils/providers/openai/*`.
 - Anthropic Claude Code runtime: `packages/api/src/utils/providers/anthropic/*`.
 - Cost/usage accounting: `packages/api/src/utils/providers/common/model-cost.ts`.
+- Weighted token selection: `packages/api/src/utils/providers/common/smooth-weighted-round-robin.ts`.
+- Boot order and startup migrations: `packages/api/src/server-bootstrap.ts`, `packages/api/src/startup-migrations.ts`.
 - Tool-call emulation: `packages/api/src/application/qgrid/tool-emulation.ts`.
 
 ## Web/Sonamu hot spots

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

@@ -34,8 +34,9 @@ Use this reference before changing token storage, OAuth flows, token activation,
 - `active`: whether provider dispatchers may use it.
 - `ord`: dashboard ordering.
 - `quota_threshold`: nullable integer percentage, validated as 1..100 when present.
+- `weight`: non-null integer 1..100, database default 1. Relative share for weighted round-robin routing of new requests. Weight does not enable or disable a token; that stays on `active`.
 
-On creation, `TokenModel.save` applies default `quota_threshold = 80` unless `id` or `quota_threshold` is already provided.
+On creation, `TokenModel.save` applies defaults `quota_threshold = 80` and `weight = 1` independently for any field not provided (skipped entirely when `id` is present).
 
 OpenAI credentials:
 
@@ -72,7 +73,7 @@ Duplicate account replacement is account-identifier based:
 `QgridFrame` exposes token APIs:
 
 - `addToken(provider, credentials, name)`: saves a token directly.
-- `updateToken(id, name?, quotaThreshold?)`: updates name and/or quota threshold, preserving provider/credentials.
+- `updateToken(id, name?, quotaThreshold?, weight?)`: partial field update through `TokenModel.updateFields`; omitted fields preserve stored values, so one control cannot overwrite another control's setting. `weight` is validated as an integer 1..100. The web client uses a hand-written `useUpdateTokenMutation` hook instead of the generated tanstack-mutation client for this endpoint.
 - `removeToken(id)`: deletes token row.
 - `toggleToken(id)`: flips `active`.
 - `stats()`: reports dispatcher cache stats.
@@ -154,13 +155,16 @@ Triggers notify on:
 - INSERT
 - DELETE
 - UPDATE when `active`, `credentials`, `provider`, `name`, or `quota_threshold` changes.
+- UPDATE when `weight` changes, through a separate `tokens_weight_changed_upd` trigger owned by the versioned migration `20260710090000_alter_tokens_add_weight.ts`. The boot-time setup SQL intentionally leaves `weight` out of its WHEN clause (test-enforced in `token-trigger-setup.test.ts`) so exactly one trigger fires per weight-only change.
 
 `TokenSubscriber`:
 
 - connects to PostgreSQL and `LISTEN`s on `tokens_changed`;
 - reconnects with jittered exponential backoff up to 30 seconds;
 - runs periodic reconcile every 10 minutes because LISTEN/NOTIFY can miss changes while disconnected;
-- replaces dispatcher cache from `TokenModel.findActive("A")`.
+- replaces dispatcher cache from `TokenModel.findActive("A")`;
+- serializes notification handling and reconcile through an internal operation chain, so dispatcher updates (now awaited, including weight propagation) apply in arrival order;
+- passes `weight` through add, update, and reconcile calls for both provider dispatchers.
 
 On DELETE or missing row:
 
@@ -188,6 +192,7 @@ OpenAI token changes can create, update, deactivate, or kill persistent Codex wo
 
 - In-place OpenAI worker update is allowed only when account id and plan type match.
 - Otherwise workers are killed and respawned.
+- Weight-only changes never respawn workers; they update token metadata and reset the weighted selector's scores.
 - If no ready active OpenAI workers remain, queued OpenAI requests are rejected.
 
 Anthropic token changes only affect the in-memory token pool because every request fresh-spawns Claude Code.

package/skills/qgrid/references/verification-and-debugging.md

@@ -59,6 +59,9 @@ Choose by affected area:
 | qgrid frame API behavior | `packages/api/src/application/qgrid/qgrid.frame.test.ts` |
 | token subscriber and LISTEN/NOTIFY handling | `packages/api/src/application/qgrid/token-subscriber.test.ts` |
 | token defaults/validation | `packages/api/src/application/token/token.model.test.ts`, `token.types.test.ts` |
+| weighted routing selector | `packages/api/src/utils/providers/common/smooth-weighted-round-robin.test.ts` |
+| token weight migration/trigger split | `packages/api/src/application/qgrid/token-weight-migration.test.ts`, `token-trigger-setup.test.ts` |
+| boot order and startup migrations | `packages/api/src/server-bootstrap.test.ts`, `startup-migrations.test.ts` |
 | request log queries/legacy normalization | `packages/api/src/application/request-log/request-log.model.test.ts` |
 | OpenAI dispatcher routing/queue/quota/reuse | `packages/api/src/utils/providers/openai/openai-dispatcher.test.ts` |
 | OpenAI Codex worker RPC/turn behavior | `packages/api/src/utils/providers/openai/codex-worker.test.ts` |