@cartanova/qgrid-cli 2.3.8 → 2.3.9

package/postinstall.mjs

@@ -0,0 +1,119 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, rm, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.dirname(fileURLToPath(import.meta.url));
+const sourceSkillsDir = path.join(packageDir, "skills", "qgrid");
+
+function hasArg(name) {
+  return process.argv.slice(2).includes(name);
+}
+
+function findProjectRoot(startDir) {
+  let current = path.resolve(startDir);
+  let packageJsonRoot = null;
+
+  while (true) {
+    if (
+      existsSync(path.join(current, "pnpm-workspace.yaml")) ||
+      existsSync(path.join(current, ".git"))
+    ) {
+      return current;
+    }
+
+    if (!packageJsonRoot && existsSync(path.join(current, "package.json"))) {
+      packageJsonRoot = current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return packageJsonRoot ?? path.resolve(startDir);
+    current = parent;
+  }
+}
+
+function defaultProjectRoot() {
+  if (process.env.QGRID_SKILLS_CWD) return findProjectRoot(process.env.QGRID_SKILLS_CWD);
+  if (process.env.INIT_CWD) return findProjectRoot(process.env.INIT_CWD);
+
+  const cwd = process.cwd();
+  if (cwd.includes(`${path.sep}node_modules${path.sep}`)) return null;
+  return findProjectRoot(cwd);
+}
+
+function defaultTargets() {
+  const isGlobalInstall =
+    process.env.npm_config_global === "true" || process.env.npm_config_location === "global";
+
+  if (hasArg("--global") || isGlobalInstall) {
+    const codexHome = process.env.CODEX_HOME
+      ? path.resolve(process.env.CODEX_HOME)
+      : path.join(os.homedir(), ".codex");
+    const claudeHome = process.env.CLAUDE_HOME
+      ? path.resolve(process.env.CLAUDE_HOME)
+      : path.join(os.homedir(), ".claude");
+    return [
+      { label: "Codex", target: path.join(codexHome, "skills", "qgrid"), useSymlink: false },
+      { label: "Claude Code", target: path.join(claudeHome, "skills", "qgrid"), useSymlink: false },
+    ];
+  }
+
+  const projectRoot = defaultProjectRoot();
+  if (!projectRoot) return null;
+
+  return [
+    {
+      label: "Codex",
+      target: path.join(projectRoot, ".agents", "skills", "qgrid"),
+      useSymlink: true,
+    },
+    {
+      label: "Claude Code",
+      target: path.join(projectRoot, ".claude", "skills", "qgrid"),
+      useSymlink: true,
+    },
+  ];
+}
+
+async function syncSkill({ label, target, useSymlink }) {
+  if (!existsSync(path.join(sourceSkillsDir, "SKILL.md"))) {
+    console.log("qgrid skill source not found in qgrid CLI package.");
+    return;
+  }
+
+  await rm(target, { recursive: true, force: true });
+  await mkdir(path.dirname(target), { recursive: true });
+
+  if (useSymlink) {
+    try {
+      await symlink(sourceSkillsDir, target, "dir");
+      console.log(`qgrid skill linked for ${label}: ${target}`);
+      return;
+    } catch (error) {
+      console.log(
+        `qgrid skill symlink failed for ${label}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      console.log("falling back to copy");
+    }
+  }
+
+  await cp(sourceSkillsDir, target, { recursive: true });
+  console.log(`qgrid skill copied for ${label}: ${target}`);
+}
+
+const targetConfigs = defaultTargets();
+
+if (!targetConfigs) {
+  console.log("qgrid skill sync skipped: project root not found.");
+  process.exit(0);
+}
+
+try {
+  for (const targetConfig of targetConfigs) {
+    await syncSkill(targetConfig);
+  }
+} catch (error) {
+  console.error(`qgrid skill sync failed: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}

package/skills/qgrid/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: qgrid
+description: Work on the qgrid repository, an LLM subscription-token proxy with OpenAI Codex app-server workers, Anthropic Claude Code fresh-spawn runtime, AI SDK provider compatibility, Sonamu API/web generation, token routing, prompt-cache behavior, request logging, quota thresholds, and dashboard flows. Use when implementing, debugging, reviewing, or planning qgrid code, docs, migrations, provider integrations, CLI/runtime behavior, request logs, or SDK behavior.
+---
+
+# Qgrid
+
+## Start Here
+
+Use this skill for qgrid repository work. Treat qgrid as a runtime-contract-heavy system: model input travels through the active AI SDK provider, Sonamu API, provider dispatcher, provider-specific runtime, response mapping, request logging, and dashboard display.
+
+Before changing code, identify the affected path:
+
+- Public AI SDK provider: read `references/ai-sdk-provider-contract.md`.
+- 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`.
+- 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`.
+- Design rationale, prior decisions, or "why is this feature shaped this way?": read `references/decision-rationale.md`.
+- Dashboard changes: read `references/sonamu-api-web-flow.md`.
+- Request log lifecycle, tool-call steps, telemetry/logger behavior: read `references/request-log-run-lifecycle.md`.
+- Choosing tests, smoke scripts, or debugging common runtime errors: read `references/verification-and-debugging.md`.
+- Project planning/review/documentation workflow: read `references/docs-workflow.md`.
+- Repository orientation: read `references/repo-map.md`.
+
+## Setup Guardrails
+
+When helping a user set up local `@cartanova/qgrid-ai-sdk`, `createQgridLogger`, or qgrid CLI-backed workflows, ensure request-log project naming is configured. Check for `QGRID_PROJECT_NAME` in the calling app/runtime environment or `projectName` in qgrid provider/logger config. If neither is present, ask the user for a stable project/workflow name or add the obvious repository/app name when the surrounding setup convention makes that appropriate.
+
+Prefer `QGRID_PROJECT_NAME` as the project-wide default. Use config `projectName` only for a deliberate per-call/per-provider override. Do not add `projectName` or `project_name` under `providerOptions.qgrid`; current code does not read it there.
+
+## Non-Negotiable Boundaries
+
+- Use `packages/ai-sdk` as the active public SDK surface.
+- Treat `packages/sdk` as deprecated. Read it only for legacy context or migration clues. Do not add new examples or features on top of it unless explicitly asked for legacy work.
+- Route provider models by prefix: `openai/*` goes to the OpenAI Codex runtime, `anthropic/*` goes to the Anthropic Claude Code runtime. Prefix-less model fallback is not implemented.
+- Treat dashboard work as Sonamu API/model/generated-client/web work, not isolated frontend work.
+- Keep OpenAI Codex built-in tools, apps, plugins, skills, web search, shell, and environment instruction blocks disabled unless the user explicitly asks for agentic Codex behavior.
+- Treat OpenAI image generation as an opt-in Codex `image_generation` tool path. Inspect current code before modifying it; it is not a direct Images API call and its image cost is an estimate.
+
+## Verification
+
+Choose verification by blast radius:
+
+- Type/lint/format: `pnpm check`.
+- Package tests: use the relevant package test command or targeted Vitest files.
+- Provider runtime changes: run targeted tests for `packages/api/src/utils/providers/**` and, when practical, the relevant smoke script in `scripts/` or `packages/api/scripts/`.
+- AI SDK changes: run `packages/ai-sdk` tests and inspect generated request payload behavior.
+- Sonamu API/model changes: check generated files and both API and web consumers.
+
+Do not rely on one provider's behavior to infer the other provider's behavior. OpenAI/Codex and Anthropic/Claude Code have different process lifetimes, cache behavior, usage accounting, and structured-output paths.

package/skills/qgrid/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qgrid"
+  short_description: "Develop and debug qgrid runtime contracts"
+  default_prompt: "Use $qgrid to implement or debug qgrid provider runtime behavior."

package/skills/qgrid/references/ai-sdk-provider-contract.md

@@ -0,0 +1,100 @@
+# AI SDK Provider Contract
+
+Use this reference before changing `packages/ai-sdk`.
+
+## Active public surface
+
+`packages/ai-sdk` is the active public SDK package. `packages/sdk` is deprecated and context-only.
+
+qgrid's custom provider implements the AI SDK `LanguageModelV3` contract. General usage should follow the AI SDK docs and normal AI SDK APIs such as `generateText`, `streamText`, tools, structured output, and telemetry. Do not re-document generic AI SDK usage in qgrid-specific docs unless the behavior differs. qgrid docs and this skill should focus on qgrid-specific config, `providerOptions.qgrid`, request logging, runtime routing, cache/session behavior, and provider limitations.
+
+For tool calling, qgrid intentionally follows the AI SDK interface while implementing provider calls through qgrid structured-output emulation. Read `tool-calling-and-multiturn.md` before changing tool behavior, `stopWhen`/multi-step behavior, or tool-call request logs.
+
+Main files:
+
+- `packages/ai-sdk/src/index.ts`: `qgrid()` provider implementation.
+- `packages/ai-sdk/src/index.types.ts`: public config/options/types.
+- `packages/ai-sdk/src/utils.ts`: prompt/history/tool conversion.
+- `packages/ai-sdk/src/logger.ts`: telemetry logger integration.
+- `packages/ai-sdk/src/qgrid.constant.ts`: defaults and warnings.
+
+## Provider config
+
+`qgrid(modelId, config)` supports:
+
+- `serverUrl`: default `process.env.QGRID_URL`, then `http://localhost:44900`.
+- `defaultEffort`: default `low`.
+- `projectName`: default `process.env.QGRID_PROJECT_NAME`.
+
+Strongly recommend setting `QGRID_PROJECT_NAME` in the environment for real workloads. The config-level `projectName` override is valid, but the env var is the preferred project-wide default. It is stored as `request_logs.project_name` and makes high-volume request logs usable: operators can filter by project/workflow, identify which task produced which request, compare token/cache/cost/TTFT metrics by workload, and debug noisy callers without scanning prompts manually.
+
+Use camelCase `projectName` in TypeScript and qgrid API payloads. `project_name` is the database/Sonamu request-log field name, not an AI SDK provider option.
+
+Setup agents should treat a missing project label as an actionable configuration gap. When installing or wiring qgrid for a local app, inspect the target app's env/config. If neither `QGRID_PROJECT_NAME` nor qgrid provider/logger config `projectName` is present, ask the user for a stable project or workflow name, then add it using the project's normal env/config pattern. A repo or package name is an acceptable default only when it is clearly the user's intended workload label.
+
+## Provider options
+
+qgrid-specific behavior is controlled through `providerOptions.qgrid`. Explain these options precisely because they are qgrid's extension point beyond normal AI SDK usage.
+
+`providerOptions.qgrid` supports:
+
+- `sessionKey`: OpenAI thread reuse key. Disabled for Anthropic models.
+- `effort`
+- `verbosity`: OpenAI/Codex route only.
+- `reasoningSummary`: OpenAI/Codex route only.
+- `serviceTier`: OpenAI/Codex route only.
+- `fallbackModels`: reserved for future fallback routing.
+- `imageGeneration`: OpenAI/Codex non-stream only. Enables Codex's built-in `image_generation` tool for that request.
+- `imageGenerationOptions`: optional image quality/size hints and cost-estimation basis. Current supported values are `quality: "low" | "medium" | "high"` and `size: "1024x1024" | "1024x1536" | "1536x1024"`.
+
+`providerOptions.qgrid` does not currently support `projectName` or `project_name`. Prefer `QGRID_PROJECT_NAME` for the default project label; use config `projectName` only when a caller needs to override that default.
+
+## Request construction
+
+The provider sends `POST /api/qgrid/query` for generate and `prepareStream` plus SSE for stream.
+
+Payload responsibilities:
+
+- Extract current prompt, system prompt, and history from AI SDK prompt messages.
+- Convert AI SDK function tools to qgrid tools.
+- Send `jsonSchema` only when no tools are present and response format top-level schema is `object`.
+- Send `history` as JSON string when prior messages exist.
+- Send `projectName` when configured.
+- Use `logMode: "run"` for tool-call loops.
+- Preserve and resend `runContext` for tool-call follow-ups.
+- Store/resend OpenAI `threadCoord` by `sessionKey`.
+- Send `imageGeneration` and `imageGenerationOptions` when configured.
+
+Tools and `jsonSchema` cannot be used together at qgrid dispatcher level.
+
+When tools are present, qgrid sends tool definitions to the server as `tools`; it does not send them to OpenAI or Anthropic as native provider tools. The server converts them into a strict structured-output schema and maps the model's structured result back into AI SDK `tool-call` content.
+
+Image generation is different from AI SDK client tools: it is an opt-in Codex-hosted tool exposed by qgrid through `providerOptions.qgrid.imageGeneration`. Use `generateText`; `streamText` rejects image generation before opening the stream.
+
+## Response mapping
+
+qgrid response content maps to AI SDK content:
+
+- qgrid `text` -> AI SDK text content.
+- qgrid `tool-call` -> AI SDK tool-call content.
+- qgrid `image` -> AI SDK file content with `mediaType: "image/png"`.
+
+`finishReason` maps `tool-calls` when qgrid returns tool calls.
+
+When `imageGeneration` was requested and the server returns no image part, the AI SDK provider throws a version-skew/error guard instead of silently accepting text-only output.
+
+Usage maps qgrid standard usage into AI SDK V3 usage:
+
+- `inputTokens.total = input_tokens`
+- `inputTokens.cacheRead = cache_read_input_tokens`
+- `inputTokens.cacheWrite = cache_creation_input_tokens`
+- `inputTokens.noCache = max(input - cacheRead - cacheWrite, 0)`
+- `outputTokens.total = output_tokens`
+
+## Anthropic sessionKey guard
+
+Do not store or replay `sessionKey` thread coordinates for `anthropic/*` models. Tests cover this because Anthropic fresh-spawn runtime cannot safely use Codex-style thread reuse.
+
+## Logger integration
+
+`createQgridLogger` records external provider calls into qgrid request logs. It skips qgrid provider calls to avoid double-logging. When changing logger behavior, preserve stale-run fallback because AI SDK telemetry lacks a reliable error hook for all failure modes.

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

@@ -0,0 +1,170 @@
+# Anthropic Claude Code Runtime
+
+Use this reference before changing Anthropic provider behavior, Claude Code spawn args/env, stream-json adaptation, structured output, 1M context behavior, token routing, OAuth refresh, or quota handling.
+
+## Contents
+
+- Process model
+- Token routing
+- OAuth refresh
+- Spawn args
+- Spawn env
+- Config isolation
+- Input adaptation
+- Output adaptation
+- Structured output
+- 1M context
+
+## Process model
+
+Anthropic uses fresh Claude Code process spawn per request. It does not use a persistent worker pool.
+
+- Dispatcher: `packages/api/src/utils/providers/anthropic/anthropic-dispatcher.ts`.
+- Session runner: `packages/api/src/utils/providers/anthropic/claude-session.ts`.
+- Stream adapter: `packages/api/src/utils/providers/anthropic/stream-json-adapter.ts`.
+- Constants/model normalization: `packages/api/src/utils/providers/anthropic/anthropic-constants.ts`.
+- Process command: `claude -p ...`.
+- Each request gets a fresh UUID `--session-id`.
+- `workerId` is `tokenId`.
+- `epoch` is always `0`.
+
+The emitted `threadCoord` lets qgrid keep a shared response shape, but AI SDK disables `sessionKey` storage/replay for `anthropic/*` models. Do not implement Anthropic cache by pretending Claude sessions are reused unless the runtime design changes.
+
+## Token routing
+
+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.
+
+Quota threshold:
+
+- `quota_threshold` is checked through Anthropic quota usage.
+- Lookup failure is fail-open.
+- If all eligible tokens exceed threshold, throw `QuotaThresholdExceededError`.
+
+## OAuth refresh
+
+Before spawning Claude, qgrid refreshes access tokens when expiration is within 60 seconds and a refresh token exists.
+
+Refresh is attempted through `QgridFrame.refreshToken` with provider set to `anthropic`. Refresh failure is logged and the current access token is still tried.
+
+## Spawn args
+
+`buildClaudeArgs` constructs Claude Code flags:
+
+```text
+claude -p
+  --tools ""
+  --allowed-tools StructuredOutput        # only when jsonSchema exists
+  --disallowedTools Monitor PushNotification RemoteTrigger
+  --input-format stream-json
+  --output-format stream-json
+  --verbose
+  --include-partial-messages              # streaming path only
+  --permission-mode bypassPermissions
+  --setting-sources project
+  --model <canonical-model-or-1m-suffix>
+  --system-prompt <text>                  # small system prompt
+  --system-prompt-file <path>             # large system prompt
+  --thinking disabled
+  --effort <effort-or-low>
+  --disable-slash-commands
+  --session-id <uuid>
+  --json-schema <schema>                  # only when jsonSchema exists
+```
+
+Important details:
+
+- `--tools ""` blocks normal tools. With structured output, only `StructuredOutput` is allowed.
+- `--setting-sources project` plus seeded settings isolates user configuration.
+- `--system-prompt` or `--system-prompt-file` is always supplied. Omitting it would allow Claude Code default system prompt injection.
+- Large system prompts over 64 KiB are written to a temporary file to avoid argv `E2BIG`.
+- `--thinking disabled`, `MAX_THINKING_TOKENS=0`, and adaptive thinking env suppression keep thinking off.
+
+## Spawn env
+
+qgrid builds a fresh env whitelist. Do not spread `process.env` into Claude child env.
+
+Included env:
+
+- `PATH`
+- `TMPDIR`
+- `CLAUDE_CODE_OAUTH_TOKEN`
+- `CLAUDE_CONFIG_DIR`
+- `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
+- `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`
+- `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1`
+- `CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1`
+- `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1`
+- `CLAUDE_CODE_DISABLE_WORKFLOWS=1`
+- `CLAUDE_CODE_ATTRIBUTION_HEADER=0`
+- `MAX_THINKING_TOKENS=0`
+- `CLAUDE_CODE_DISABLE_1M_CONTEXT=1` when model does not support qgrid's 1M path
+- `MAX_STRUCTURED_OUTPUT_RETRIES` for structured output only
+
+Never pass `ANTHROPIC_API_KEY` or inherited auth env vars to child processes. OAuth must flow through `CLAUDE_CODE_OAUTH_TOKEN`.
+
+## Config isolation
+
+- Shared cwd: `/tmp/qgrid-anthropic`.
+- Project settings file: `/tmp/qgrid-anthropic/.claude/settings.json`, written as `{}`.
+- Per-token config dir: `/tmp/qgrid-anthropic-config/${tokenId}`.
+- qgrid writes `{}` to both `.claude.json` and `settings.json` inside the per-token config dir before each run.
+
+This blocks user-scope Claude settings, hooks, memory, and token cross-contamination as much as the current Claude Code interface allows.
+
+## Input adaptation
+
+qgrid sends Claude stdin as JSONL with `--input-format stream-json`.
+
+- Current input is the only executable user line.
+- Prior conversation history is flattened into a single assistant context line prefixed with `Prior conversation context:`.
+- Function calls and function outputs from AI SDK history are flattened into text.
+- Each JSONL line is decorated with `session_id`, `uuid`, and `parent_tool_use_id: null`.
+
+This is not equivalent to persistent Claude session reuse. It is full-history replay through a fresh process.
+
+## Output adaptation
+
+Claude stdout JSONL is parsed by `stream-json-adapter.ts`.
+
+- Text mode streams `text_delta`.
+- Structured mode streams `input_json_delta` and preserves `StructuredOutput` tool input as final text.
+- `result` lines provide final text, usage, duration, cost, subtype, and terminal reason.
+- Non-success subtype, `is_error`, or `terminal_reason: model_error` is treated as an error.
+- Quota exhaustion is detected when text starts with `You've hit`.
+
+Anthropic native usage categories are mutually exclusive. qgrid normalizes them into its provider-standard shape by setting:
+
+```text
+inputTokens = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
+cachedInputTokens = cache_read_input_tokens
+cacheCreationInputTokens = cache_creation_input_tokens
+```
+
+## Structured output
+
+qgrid strictifies schemas before provider dispatch. Claude Code `--json-schema` is not grammar-constrained decoding; it is a `StructuredOutput` tool plus post-validation behavior. Keep schemas strict and preserve error signaling for failed structured-output attempts.
+
+`MAX_STRUCTURED_OUTPUT_RETRIES` defaults to `1` for structured Anthropic calls and is clamped to at least 1. Avoid setting it to 0; Claude Code can fail before emitting a useful attempt.
+
+## 1M context
+
+Model normalization strips provider prefix and `[1m]` for canonical model/cost keys.
+
+qgrid's measured 1M support set currently includes:
+
+- `claude-sonnet-4-6`
+- `claude-opus-4-6`
+- `claude-opus-4-8`
+
+Models requiring CLI `[1m]` suffix:
+
+- `claude-sonnet-4-6`
+- `claude-opus-4-6`
+
+Unsupported `[1m]` suffixes throw early.

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

@@ -0,0 +1,66 @@
+# CLI, Env, And Server Boot
+
+Use this reference for qgrid startup, configuration, and runtime-facing environment variables.
+
+## CLI options
+
+- `--db <url>`: PostgreSQL URL in `postgres://user:password@host:port/dbname` or `postgresql://...` form. Parsed by `packages/cli/src/cli.ts` and copied into `QGRID_DB_*` env vars before server boot.
+- `-p, --port <port>`: server port. Default `44900`. The CLI validates the port and refuses to start if it is already in use.
+- `--skip-update`: skip qgrid CLI self-update check.
+
+The CLI also ensures runtime CLIs are installed/current enough:
+
+- `codex` from `@openai/codex`, required for OpenAI tokens.
+- `claude` from `@anthropic-ai/claude-code`, required for Anthropic tokens.
+
+## Server env vars agents should know
+
+| Env | Default | Meaning |
+|---|---:|---|
+| `QGRID_DB_HOST` | `localhost` | PostgreSQL host. |
+| `QGRID_DB_PORT` | `5432` | PostgreSQL port. |
+| `QGRID_DB_USER` | `postgres` | PostgreSQL user. |
+| `QGRID_DB_PASSWORD` | `postgres` | PostgreSQL password. |
+| `QGRID_DB_NAME` | `qgrid` | PostgreSQL database. |
+| `HOST` | `localhost` | Sonamu server listen host when running API directly. |
+| `PORT` | `44900` | Sonamu server listen port. In CLI mode this is derived from `--port`, not read as user input. |
+| `QGRID_PUBLIC_BASE_URL` | empty | Public base URL used to construct Anthropic OAuth callback URL. If unset, callback defaults to `http://localhost:${PORT}/callback`. |
+| `PROJECT_NAME` | `Qgrid` | Sonamu project name. Not the same as request log `projectName`. |
+
+Do not treat CLI bundle bootstrapping internals as user-facing qgrid configuration.
+
+## SDK/client env vars
+
+| Env | Default | Meaning |
+|---|---:|---|
+| `QGRID_URL` | `http://localhost:44900` | Server URL used by `@cartanova/qgrid-ai-sdk` and logger integration. |
+| `QGRID_PROJECT_NAME` | empty | Request log project name sent by the AI SDK provider/logger unless overridden in config. Configure this in the calling app or agent runtime environment, not only in the qgrid server process. |
+
+When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or config `projectName`. If absent, ask for a stable project/workflow label or add the obvious app/repo name when the setup context makes it unambiguous. This keeps request logs, metrics, and dashboard filters usable once traffic volume grows.
+
+## Provider runtime knobs
+
+| Env | Default | Meaning |
+|---|---:|---|
+| `QGRID_WORKERS_PER_TOKEN` | `3` | OpenAI Codex workers per token. Capped at 5 in code. |
+| `QGRID_OPENAI_THREAD_REUSE` | enabled | Set to `"false"` to disable OpenAI thread reuse and force cold thread behavior. |
+| `MAX_STRUCTURED_OUTPUT_RETRIES` | `1` for structured Anthropic calls | Claude Code structured-output retry count, clamped to at least 1 by qgrid. |
+
+## 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.
+
+On shutdown, it stops provider dispatchers and the token subscriber.
+
+## OAuth callbacks
+
+- Anthropic OAuth uses `/callback` on the qgrid server. The callback URL is based on `QGRID_PUBLIC_BASE_URL` when set, otherwise localhost and `PORT`.
+- OpenAI OAuth is handled by Codex app-server's own callback flow and completed through qgrid's OpenAI OAuth APIs.