@kenkaiiii/gg-core 5.91.2 → 5.93.0

package/NOTICE

@@ -1,5 +1,5 @@
 GG Coder
-Copyright (C) 2025-2026 KenKai
+Copyright (C) 2025-2026 Ken Kai
 
 This program is free software: you can redistribute it and/or modify it under
 the terms of the GNU Affero General Public License as published by the Free

package/README.md

@@ -1,68 +1,84 @@
-# @kenkaiiii/gg-core
+<h1 align="center">@kenkaiiii/gg-core</h1>
 
 <p align="center">
-  <strong>Model registry, auth storage and local-model discovery. No UI, no agent loop.</strong>
+  <strong>Model list, sign-in and local model discovery for apps built on gg-ai.</strong>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@kenkaiiii/gg-core"><img src="https://img.shields.io/npm/v/@kenkaiiii/gg-core?style=for-the-badge" alt="npm version"></a>
-  <a href="../../LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=for-the-badge" alt="AGPL-3.0 License"></a>
+  <a href="https://www.npmjs.com/package/@kenkaiiii/gg-core"><img src="https://img.shields.io/npm/v/@kenkaiiii/gg-core?style=for-the-badge&color=blue" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@kenkaiiii/gg-core"><img src="https://img.shields.io/npm/dm/@kenkaiiii/gg-core?style=for-the-badge&color=2ecc71" alt="npm downloads per month"></a>
+  <a href="https://github.com/KenKaiii/gg-framework/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=for-the-badge" alt="AGPL-3.0 License"></a>
 </p>
 
-The shared foundation under GG Coder's app and CLI. It depends only on [`@kenkaiiii/gg-ai`](../gg-ai/README.md), never on React, Ink or the agent loop.
+gg-core is the shared base under [GG Coder](https://github.com/KenKaiii/gg-framework)'s desktop app and CLI. It knows every supported model (context window, image and video support, thinking levels), signs users in to their AI subscriptions, keeps those credentials fresh, and finds models running on the user's machine.
 
-Part of the [GG Framework](../../README.md) monorepo.
-
----
+It has no UI and no agent loop. Its only framework dependency is [`@kenkaiiii/gg-ai`](https://www.npmjs.com/package/@kenkaiiii/gg-ai).
 
 ## Install
 
 ```bash
-npm i @kenkaiiii/gg-core
+npm install @kenkaiiii/gg-core
 ```
 
----
-
-## What's inside
-
-| Area            | Main exports                                                                              |
-| --------------- | ----------------------------------------------------------------------------------------- |
-| Model registry  | `getModel`, `getAllModels`, `getModelsForProvider`, `getDefaultModel`, `getContextWindow` |
-| Thinking levels | `getSupportedThinkingLevels`, `getMaxThinkingLevel`, `getDefaultThinkingLevel`            |
-| Auth storage    | `AuthStorage` (reads and writes `~/.gg/auth.json`, refreshes OAuth tokens)                |
-| OAuth           | Anthropic, OpenAI, Gemini, Kimi and xAI login flows                                       |
-| Local models    | `discoverLocalModels` (Ollama, LM Studio, llama.cpp, vLLM, custom endpoints)              |
-| Paths           | `getAppPaths` (every file under `~/.gg/`)                                                 |
-| Other           | Logger, file lock, usage limits, Telegram, voice transcription, auto-update               |
+Needs Node.js 22 or newer. Ships ESM and CommonJS builds with TypeScript types.
 
-Two lighter subpath entries skip the rest of the package:
-
-```ts
-import { getModel } from "@kenkaiiii/gg-core/models";
-import { getAppPaths } from "@kenkaiiii/gg-core/paths";
-```
-
----
-
-## Example
+## Quick start
 
 ```ts
 import { AuthStorage, discoverLocalModels, getModel } from "@kenkaiiii/gg-core";
 
 const model = getModel("claude-sonnet-5-5");
-console.log(model?.contextWindow);
+console.log(model?.contextWindow, model?.supportsImages); // 1000000 true
 
+// Credentials saved by `ggcoder login` or the GG Coder app, refreshed when they expire.
 const auth = new AuthStorage();
 const token = await auth.resolveToken("anthropic");
 
+// Models on a running Ollama server.
 const { models } = await discoverLocalModels();
 console.log(models.map((m) => m.id));
 ```
 
-`AuthStorage` throws `NotLoggedInError` when a provider has no stored credentials.
+`resolveToken()` throws `NotLoggedInError` when the provider has no saved credentials.
+
+## What's inside
+
+| Area            | Main exports                                                                                                   |
+| --------------- | -------------------------------------------------------------------------------------------------------------- |
+| Models          | `getModel`, `getAllModels`, `getModelsForProvider`, `getDefaultModel`, `getContextWindow`, `MODELS`            |
+| Thinking levels | `getSupportedThinkingLevels`, `getMaxThinkingLevel`, `getDefaultThinkingLevel`, `getNextThinkingLevel`         |
+| Credentials     | `AuthStorage`: reads and writes `~/.gg/auth.json`, refreshes sign-in tokens, safe across processes             |
+| Sign-in         | `loginAnthropic`, `loginOpenAI`, `loginKimi`, `loginXai`, `loginGemini` and matching `refresh…Token` functions |
+| Provider list   | `AUTH_PROVIDERS`: each provider's name, models and sign-in methods, ready for a login screen                   |
+| Local models    | `discoverLocalModels`, `probeEndpoint`: Ollama by default, plus LM Studio, llama.cpp, vLLM or any custom URL   |
+| Plan usage      | `fetchSubscriptionUsage`: remaining Claude, ChatGPT and Kimi plan usage                                        |
+| Paths           | `getAppPaths`: every file GG Coder keeps under `~/.gg/`                                                        |
+| Other           | Logger, file lock, Telegram bot, voice transcription, auto-update                                              |
+
+`AuthStorage` shares `~/.gg/auth.json` with GG Coder, so a user who has signed in there is already signed in to your tool. Pass a different file path to the constructor to keep your own.
+
+## Lighter imports
+
+Two subpaths load only what they need, which keeps startup fast:
+
+```ts
+import { getModel } from "@kenkaiiii/gg-core/models";
+import { getAppPaths } from "@kenkaiiii/gg-core/paths";
+```
+
+Voice transcription uses two optional dependencies (`@huggingface/transformers`, `ogg-opus-decoder`). Everything else works without them.
+
+## The GG Framework
+
+| Package                                                                  | What it does                                                                     |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| [@kenkaiiii/gg-ai](https://www.npmjs.com/package/@kenkaiiii/gg-ai)       | One streaming API for every provider                                             |
+| [@kenkaiiii/gg-agent](https://www.npmjs.com/package/@kenkaiiii/gg-agent) | The agent loop: runs tools and feeds results back to the model                   |
+| **@kenkaiiii/gg-core**                                                   | Model list, sign-in and stored credentials, local model discovery (this package) |
+| [@kenkaiiii/ggcoder](https://www.npmjs.com/package/@kenkaiiii/ggcoder)   | The GG Coder coding agent: CLI, tools and sessions                               |
 
----
+Source, issues and the desktop app: [github.com/KenKaiii/gg-framework](https://github.com/KenKaiii/gg-framework).
 
 ## License
 
-AGPL-3.0-only. See [LICENSE](../../LICENSE).
+[AGPL-3.0-only](https://github.com/KenKaiii/gg-framework/blob/main/LICENSE). You can build on it; if you distribute your changes or run them as a network service, share their source under the same license.

package/dist/{chunk-YXPGQIOD.js → chunk-SDUIKPGO.js}

@@ -1148,6 +1148,7 @@ import { setTimeout as setTimeout2 } from "timers/promises";
 var STALE_TIMEOUT_MS = 1e4;
 var RETRY_INTERVAL_MS = 50;
 var MAX_WAIT_MS = 5e3;
+var PENDING_DELETE_CODES = /* @__PURE__ */ new Set(["EACCES", "EBUSY", "EPERM"]);
 async function withFileLock(filePath, fn) {
   const lockPath = filePath + ".lock";
   await acquireLock(lockPath);
@@ -1159,13 +1160,22 @@ async function withFileLock(filePath, fn) {
 }
 async function acquireLock(lockPath) {
   const startTime = Date.now();
+  let refusedWithoutLock = 0;
   while (true) {
     try {
       const info = { pid: process.pid, timestamp: Date.now() };
       await fs.writeFile(lockPath, JSON.stringify(info), { flag: "wx" });
       return;
     } catch (err) {
-      if (err.code !== "EEXIST") throw err;
+      const code = err.code;
+      if (code !== "EEXIST") {
+        if (process.platform !== "win32" || !code || !PENDING_DELETE_CODES.has(code)) throw err;
+        const lockPresent = await lockFileExists(lockPath);
+        if (!lockPresent && ++refusedWithoutLock > 3) throw err;
+        if (Date.now() - startTime > MAX_WAIT_MS) throw err;
+        await setTimeout2(RETRY_INTERVAL_MS);
+        continue;
+      }
       try {
         const content = await fs.readFile(lockPath, "utf-8");
         const info = JSON.parse(content);
@@ -1194,6 +1204,14 @@ async function acquireLock(lockPath) {
     }
   }
 }
+async function lockFileExists(lockPath) {
+  try {
+    await fs.stat(lockPath);
+    return true;
+  } catch (err) {
+    return err.code !== "ENOENT";
+  }
+}
 async function releaseLock(lockPath) {
   await fs.unlink(lockPath).catch(() => {
   });
@@ -3021,4 +3039,4 @@ export {
   getDefaultThinkingLevel,
   getSummaryModel
 };
-//# sourceMappingURL=chunk-YXPGQIOD.js.map
+//# sourceMappingURL=chunk-SDUIKPGO.js.map