@push.rocks/smartai 2.2.0 → 4.0.0

package/readme.md

@@ -17,7 +17,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - **🔌 One function, eight providers** — `getModel()` returns a standard `LanguageModelV3`. Switch providers by changing a string.
 - **🧱 Built on Vercel AI SDK** — Uses `ai` v6 under the hood. Your model works with `generateText()`, `streamText()`, tool calling, structured output, and everything else in the AI SDK ecosystem.
 - **🏠 Custom Ollama provider** — A full `LanguageModelV3` implementation for Ollama with support for `think` mode, `num_ctx`, auto-tuned temperature for Qwen models, and native tool calling.
-- **💰 Anthropic prompt caching** — Automatic `cacheControl` middleware reduces cost and latency on repeated calls. Enabled by default, opt out with `promptCaching: false`.
+- **💰 Prompt caching** — Anthropic cache-control middleware is enabled by default; provider cache helpers are available for agent/session integrations.
 - **📦 Modular subpath exports** — Vision, audio, image, document, and research capabilities ship as separate imports. Only import what you need.
 - **⚡ Zero lock-in** — Your code uses standard AI SDK types. Swap providers without touching application logic.
 
@@ -107,6 +107,61 @@ console.log(result.text);
 
 OpenAI `reasoningEffort` supports `'none'`, `'minimal'`, `'low'`, `'medium'`, `'high'`, and `'xhigh'`. Model IDs are accepted as strings, so new IDs like `'gpt-5.5'` can be used before upstream model unions are updated.
 
+### OpenAI ChatGPT / Codex Auth
+
+SmartAI can request ChatGPT subscription-backed Codex credentials with OpenAI's device-code flow. The returned credentials are passed to `getModel()` through `openAiChatGptAuth`; SmartAI then routes OpenAI model calls through the ChatGPT Codex backend with the required account headers.
+
+```typescript
+import {
+  completeOpenAiChatGptDeviceCodeLogin,
+  getModel,
+  requestOpenAiChatGptDeviceCode,
+} from '@push.rocks/smartai';
+
+const deviceCode = await requestOpenAiChatGptDeviceCode();
+console.log(`Open ${deviceCode.verificationUrl} and enter ${deviceCode.userCode}`);
+
+const openAiChatGptAuth = await completeOpenAiChatGptDeviceCodeLogin(deviceCode);
+const model = getModel({
+  provider: 'openai',
+  model: 'gpt-5.5',
+  openAiChatGptAuth,
+});
+```
+
+Use `refreshOpenAiChatGptTokenData(openAiChatGptAuth)` before stored credentials expire, or after receiving an unauthorized response.
+
+Node.js consumers can inspect and resolve local ChatGPT auth files through the Node-only subpath. This supports SmartAI's canonical auth file, OpenCode's `~/.local/share/opencode/auth.json`, and Codex's `~/.codex/auth.json` without exposing token values in inspection results.
+
+```typescript
+import {
+  inspectOpenAiChatGptAuthSources,
+  resolveOpenAiChatGptAuth,
+} from '@push.rocks/smartai/openai-chatgpt-auth';
+
+const sources = await inspectOpenAiChatGptAuthSources({
+  sources: ['smartai', 'opencode', 'codex'],
+});
+
+const resolved = await resolveOpenAiChatGptAuth({
+  sources: ['smartai', 'opencode', 'codex'],
+  refresh: 'ifNeeded',
+  writeBack: {
+    smartai: true,
+    opencode: false,
+    codex: false,
+  },
+});
+
+if (resolved) {
+  const model = getModel({
+    provider: 'openai',
+    model: 'gpt-5.5',
+    openAiChatGptAuth: resolved.tokenData,
+  });
+}
+```
+
 ### Re-exported AI SDK Functions
 
 SmartAI re-exports the most commonly used functions from `ai` for convenience:
@@ -250,9 +305,9 @@ console.log(result.text);
 - **Streaming with reasoning** — `doStream()` emits proper `reasoning-start`, `reasoning-delta`, `reasoning-end` parts alongside text.
 - **All Ollama options** — `num_ctx`, `top_k`, `top_p`, `repeat_penalty`, `num_predict`, `stop`, `seed`.
 
-## 💰 Anthropic Prompt Caching
+## 💰 Prompt Caching
 
-When using the Anthropic provider, SmartAI automatically wraps the model with caching middleware that adds `cacheControl: { type: 'ephemeral' }` to the last system message and last user message. This can significantly reduce cost and latency for repeated calls with the same system prompt.
+When using the Anthropic provider, SmartAI automatically wraps the model with caching middleware. The middleware follows the same breakpoint strategy used by opencode: cache the first two system messages and the two most recent non-system messages. This can significantly reduce cost and latency for repeated agent calls with stable system/tool context.
 
 ```typescript
 // Caching enabled by default
@@ -271,6 +326,17 @@ const modelNoCaching = getModel({
 });
 ```
 
+Longer Anthropic cache TTL is opt-in:
+
+```typescript
+const modelWithOneHourCache = getModel({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5-20250929',
+  apiKey: process.env.ANTHROPIC_TOKEN,
+  promptCaching: { retention: '1h' },
+});
+```
+
 You can also use the middleware directly:
 
 ```typescript
@@ -281,6 +347,23 @@ const middleware = createAnthropicCachingMiddleware();
 const cachedModel = wrapLanguageModel({ model: baseModel, middleware });
 ```
 
+For agent frameworks, SmartAI exports lower-level helpers:
+
+```typescript
+import {
+  applySmartAiCacheProviderOptions,
+  createSmartAiCachingMiddleware,
+} from '@push.rocks/smartai';
+
+const providerOptions = applySmartAiCacheProviderOptions({
+  provider: 'openai',
+  sessionId: 'stable-session-id',
+  cache: 'auto',
+});
+```
+
+OpenAI request-level cache affinity is only added when a stable `sessionId` or explicit cache `key` is provided. Extended OpenAI retention (`'24h'`) is opt-in.
+
 ## 📦 Subpath Exports
 
 SmartAI provides specialized capabilities as separate subpath imports. Each one is a focused utility that takes a model (or API key) and does one thing well.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartai',
-  version: '2.2.0',
+  version: '4.0.0',
   description: 'Provider registry and capability utilities for ai-sdk (Vercel AI SDK). Core export returns LanguageModel; subpath exports provide vision, audio, image, document and research capabilities.'
 }

package/ts/index.ts

@@ -1,6 +1,13 @@
 export { getModel, getModelSetup } from './smartai.classes.smartai.js';
 export type {
   IOpenAiProviderOptions,
+  IOpenAiChatGptAuthCredentials,
+  IOpenAiChatGptAuthOptions,
+  IOpenAiChatGptCompleteDeviceCodeOptions,
+  IOpenAiChatGptDeviceCode,
+  IOpenAiChatGptDeviceCodePollOptions,
+  IOpenAiChatGptTokenData,
+  IOpenAiChatGptTokenInfo,
   ISmartAiModelSetup,
   ISmartAiOptions,
   TOpenAiReasoningEffort,
@@ -9,9 +16,41 @@ export type {
   TSmartAiProviderOptions,
   IOllamaModelOptions,
   LanguageModelV3,
+  LanguageModelV3Prompt,
 } from './smartai.interfaces.js';
 export { createAnthropicCachingMiddleware } from './smartai.middleware.anthropic.js';
+export {
+  applySmartAiCacheProviderOptions,
+  applySmartAiPromptCaching,
+  createSmartAiCachingMiddleware,
+  getSmartAiCacheProviderOptions,
+  getSmartAiMessageCacheProviderOptions,
+  mergeSmartAiProviderOptions,
+  resolveSmartAiCacheProvider,
+} from './smartai.cache.js';
+export type {
+  ISmartAiCacheOptions,
+  TSmartAiCacheRetention,
+  TSmartAiCacheSetting,
+  TSmartAiMessageCacheProvider,
+} from './smartai.cache.js';
 export { createOllamaModel } from './smartai.provider.ollama.js';
+export {
+  OPENAI_CHATGPT_AUTH_ISSUER,
+  OPENAI_CHATGPT_CLIENT_ID,
+  OPENAI_CHATGPT_CODEX_BASE_URL,
+  OPENAI_CHATGPT_DEFAULT_ORIGINATOR,
+  OpenAiChatGptAuthError,
+  completeOpenAiChatGptDeviceCodeLogin,
+  createOpenAiChatGptProviderSettings,
+  ensureOpenAiChatGptWorkspaceAllowed,
+  exchangeOpenAiChatGptAuthorizationCode,
+  parseOpenAiChatGptTokenInfo,
+  pollOpenAiChatGptDeviceCode,
+  refreshOpenAiChatGptTokenData,
+  requestOpenAiChatGptDeviceCode,
+} from './smartai.auth.openai.js';
+export type { IOpenAiChatGptAuthorizationCode } from './smartai.auth.openai.js';
 
 // Re-export commonly used ai-sdk functions for consumer convenience
 export { generateText, streamText, tool, jsonSchema } from 'ai';

package/ts/smartai.auth.openai.ts

@@ -0,0 +1,312 @@
+import type {
+  IOpenAiChatGptAuthCredentials,
+  IOpenAiChatGptAuthOptions,
+  IOpenAiChatGptCompleteDeviceCodeOptions,
+  IOpenAiChatGptDeviceCode,
+  IOpenAiChatGptDeviceCodePollOptions,
+  IOpenAiChatGptTokenData,
+  IOpenAiChatGptTokenInfo,
+} from './smartai.interfaces.js';
+
+export const OPENAI_CHATGPT_AUTH_ISSUER = 'https://auth.openai.com';
+export const OPENAI_CHATGPT_CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann';
+export const OPENAI_CHATGPT_CODEX_BASE_URL = 'https://chatgpt.com/backend-api/codex';
+export const OPENAI_CHATGPT_DEFAULT_ORIGINATOR = 'smartai';
+
+const DEVICE_CODE_TIMEOUT_MS = 15 * 60 * 1000;
+
+export class OpenAiChatGptAuthError extends Error {
+  public status?: number;
+  public body?: string;
+
+  constructor(message: string, options: { status?: number; body?: string } = {}) {
+    super(message);
+    this.name = 'OpenAiChatGptAuthError';
+    this.status = options.status;
+    this.body = options.body;
+  }
+}
+
+export interface IOpenAiChatGptAuthorizationCode {
+  authorizationCode: string;
+  codeChallenge: string;
+  codeVerifier: string;
+}
+
+interface IOpenAiChatGptTokenResponse {
+  id_token?: unknown;
+  access_token?: unknown;
+  refresh_token?: unknown;
+}
+
+function getFetch(options: IOpenAiChatGptAuthOptions): typeof fetch {
+  const fetchFunction = options.fetch ?? globalThis.fetch;
+  if (!fetchFunction) {
+    throw new OpenAiChatGptAuthError('fetch is not available for OpenAI ChatGPT authentication.');
+  }
+  return fetchFunction;
+}
+
+function getIssuer(options: IOpenAiChatGptAuthOptions): string {
+  return (options.issuer ?? OPENAI_CHATGPT_AUTH_ISSUER).replace(/\/+$/, '');
+}
+
+function getClientId(options: IOpenAiChatGptAuthOptions): string {
+  return options.clientId ?? OPENAI_CHATGPT_CLIENT_ID;
+}
+
+function asString(value: unknown, name: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new OpenAiChatGptAuthError(`OpenAI ChatGPT auth response is missing ${name}.`);
+  }
+  return value;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function asIntervalSeconds(value: unknown): number {
+  const interval = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isFinite(interval) || interval <= 0) {
+    throw new OpenAiChatGptAuthError('OpenAI ChatGPT device-code response has an invalid interval.');
+  }
+  return interval;
+}
+
+async function readJson(response: Response, context: string): Promise<unknown> {
+  const body = await response.text();
+  if (!response.ok) {
+    throw new OpenAiChatGptAuthError(`${context} failed with status ${response.status}.`, {
+      status: response.status,
+      body,
+    });
+  }
+
+  try {
+    return body ? JSON.parse(body) : {};
+  } catch (error) {
+    throw new OpenAiChatGptAuthError(`${context} returned invalid JSON: ${(error as Error).message}`, {
+      status: response.status,
+      body,
+    });
+  }
+}
+
+async function postJson(url: string, body: unknown, options: IOpenAiChatGptAuthOptions): Promise<unknown> {
+  const response = await getFetch(options)(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return readJson(response, `POST ${url}`);
+}
+
+async function postForm(url: string, body: URLSearchParams, options: IOpenAiChatGptAuthOptions): Promise<unknown> {
+  const response = await getFetch(options)(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+  return readJson(response, `POST ${url}`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseJwtPayload(jwt: string): Record<string, unknown> {
+  const parts = jwt.split('.');
+  if (parts.length !== 3 || !parts[1]) {
+    throw new OpenAiChatGptAuthError('OpenAI ChatGPT auth returned an invalid token.');
+  }
+
+  try {
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')) as Record<string, unknown>;
+  } catch (error) {
+    throw new OpenAiChatGptAuthError(`OpenAI ChatGPT token could not be parsed: ${(error as Error).message}`);
+  }
+}
+
+export function parseOpenAiChatGptTokenInfo(token: string): IOpenAiChatGptTokenInfo {
+  const claims = parseJwtPayload(token);
+  const profile = claims['https://api.openai.com/profile'] as Record<string, unknown> | undefined;
+  const auth = claims['https://api.openai.com/auth'] as Record<string, unknown> | undefined;
+  const expiresAtSeconds = typeof claims.exp === 'number' ? claims.exp : undefined;
+
+  return {
+    email: asOptionalString(claims.email) ?? asOptionalString(profile?.email),
+    chatgptPlanType: asOptionalString(auth?.chatgpt_plan_type),
+    chatgptUserId: asOptionalString(auth?.chatgpt_user_id) ?? asOptionalString(auth?.user_id),
+    chatgptAccountId: asOptionalString(auth?.chatgpt_account_id),
+    chatgptAccountIsFedramp: auth?.chatgpt_account_is_fedramp === true,
+    expiresAt: expiresAtSeconds ? new Date(expiresAtSeconds * 1000).toISOString() : undefined,
+    rawJwt: token,
+  };
+}
+
+function createTokenData(
+  response: IOpenAiChatGptTokenResponse,
+  existingTokenData?: IOpenAiChatGptTokenData,
+): IOpenAiChatGptTokenData {
+  const accessToken = asOptionalString(response.access_token) ?? existingTokenData?.accessToken;
+  const refreshToken = asOptionalString(response.refresh_token) ?? existingTokenData?.refreshToken;
+  const idToken = asOptionalString(response.id_token) ?? existingTokenData?.idToken;
+  if (!accessToken) {
+    throw new OpenAiChatGptAuthError('OpenAI ChatGPT auth response is missing access_token.');
+  }
+  if (!refreshToken) {
+    throw new OpenAiChatGptAuthError('OpenAI ChatGPT auth response is missing refresh_token.');
+  }
+  const tokenInfo = parseOpenAiChatGptTokenInfo(idToken ?? accessToken);
+
+  return {
+    accessToken,
+    refreshToken,
+    idToken,
+    accountId: tokenInfo.chatgptAccountId,
+    tokenInfo,
+  };
+}
+
+export async function requestOpenAiChatGptDeviceCode(
+  options: IOpenAiChatGptAuthOptions = {},
+): Promise<IOpenAiChatGptDeviceCode> {
+  const issuer = getIssuer(options);
+  const response = await postJson(`${issuer}/api/accounts/deviceauth/usercode`, {
+    client_id: getClientId(options),
+  }, options) as Record<string, unknown>;
+
+  return {
+    verificationUrl: `${issuer}/codex/device`,
+    userCode: asString(response.user_code ?? response.usercode, 'user_code'),
+    deviceAuthId: asString(response.device_auth_id, 'device_auth_id'),
+    intervalSeconds: asIntervalSeconds(response.interval),
+  };
+}
+
+export async function pollOpenAiChatGptDeviceCode(
+  deviceCode: IOpenAiChatGptDeviceCode,
+  options: IOpenAiChatGptDeviceCodePollOptions = {},
+): Promise<IOpenAiChatGptAuthorizationCode> {
+  const issuer = getIssuer(options);
+  const pollUrl = `${issuer}/api/accounts/deviceauth/token`;
+  const timeoutMs = options.timeoutMs ?? DEVICE_CODE_TIMEOUT_MS;
+  const sleepFunction = options.sleep ?? sleep;
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < timeoutMs) {
+    const response = await getFetch(options)(pollUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        device_auth_id: deviceCode.deviceAuthId,
+        user_code: deviceCode.userCode,
+      }),
+    });
+
+    if (response.ok) {
+      const body = await readJson(response, `POST ${pollUrl}`) as Record<string, unknown>;
+      return {
+        authorizationCode: asString(body.authorization_code, 'authorization_code'),
+        codeChallenge: asString(body.code_challenge, 'code_challenge'),
+        codeVerifier: asString(body.code_verifier, 'code_verifier'),
+      };
+    }
+
+    if (response.status !== 403 && response.status !== 404) {
+      const body = await response.text();
+      throw new OpenAiChatGptAuthError(`OpenAI ChatGPT device-code polling failed with status ${response.status}.`, {
+        status: response.status,
+        body,
+      });
+    }
+
+    await response.arrayBuffer().catch(() => undefined);
+    const remaining = timeoutMs - (Date.now() - startedAt);
+    await sleepFunction(Math.min(deviceCode.intervalSeconds * 1000, Math.max(remaining, 0)));
+  }
+
+  throw new OpenAiChatGptAuthError('OpenAI ChatGPT device-code login timed out.');
+}
+
+export async function exchangeOpenAiChatGptAuthorizationCode(
+  authorizationCode: IOpenAiChatGptAuthorizationCode,
+  options: IOpenAiChatGptAuthOptions = {},
+): Promise<IOpenAiChatGptTokenData> {
+  const issuer = getIssuer(options);
+  const response = await postForm(`${issuer}/oauth/token`, new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: authorizationCode.authorizationCode,
+    redirect_uri: `${issuer}/deviceauth/callback`,
+    client_id: getClientId(options),
+    code_verifier: authorizationCode.codeVerifier,
+  }), options) as IOpenAiChatGptTokenResponse;
+
+  return createTokenData(response);
+}
+
+export function ensureOpenAiChatGptWorkspaceAllowed(
+  tokenData: IOpenAiChatGptTokenData,
+  forcedChatGptWorkspaceId?: string,
+): void {
+  if (!forcedChatGptWorkspaceId) {
+    return;
+  }
+  if (tokenData.tokenInfo.chatgptAccountId !== forcedChatGptWorkspaceId) {
+    throw new OpenAiChatGptAuthError(`OpenAI ChatGPT login is restricted to workspace ${forcedChatGptWorkspaceId}.`);
+  }
+}
+
+export async function completeOpenAiChatGptDeviceCodeLogin(
+  deviceCode: IOpenAiChatGptDeviceCode,
+  options: IOpenAiChatGptCompleteDeviceCodeOptions = {},
+): Promise<IOpenAiChatGptTokenData> {
+  const authorizationCode = await pollOpenAiChatGptDeviceCode(deviceCode, options);
+  const tokenData = await exchangeOpenAiChatGptAuthorizationCode(authorizationCode, options);
+  ensureOpenAiChatGptWorkspaceAllowed(tokenData, options.forcedChatGptWorkspaceId);
+  return tokenData;
+}
+
+export async function refreshOpenAiChatGptTokenData(
+  tokenData: IOpenAiChatGptTokenData,
+  options: IOpenAiChatGptAuthOptions = {},
+): Promise<IOpenAiChatGptTokenData> {
+  const issuer = getIssuer(options);
+  const response = await postJson(`${issuer}/oauth/token`, {
+    client_id: getClientId(options),
+    grant_type: 'refresh_token',
+    refresh_token: tokenData.refreshToken,
+  }, options) as IOpenAiChatGptTokenResponse;
+
+  return createTokenData({
+    id_token: response.id_token ?? tokenData.idToken,
+    access_token: response.access_token ?? tokenData.accessToken,
+    refresh_token: response.refresh_token ?? tokenData.refreshToken,
+  }, tokenData);
+}
+
+export function createOpenAiChatGptProviderSettings(credentials: IOpenAiChatGptAuthCredentials): {
+  apiKey: string;
+  baseURL: string;
+  headers: Record<string, string>;
+} {
+  const accountId = credentials.accountId ?? credentials.tokenInfo?.chatgptAccountId;
+  const isFedrampAccount = credentials.tokenInfo?.chatgptAccountIsFedramp === true;
+  const headers: Record<string, string> = {
+    originator: credentials.originator ?? OPENAI_CHATGPT_DEFAULT_ORIGINATOR,
+  };
+
+  if (accountId) {
+    headers['ChatGPT-Account-ID'] = accountId;
+  }
+  if (isFedrampAccount) {
+    headers['X-OpenAI-Fedramp'] = 'true';
+  }
+
+  return {
+    apiKey: credentials.accessToken,
+    baseURL: credentials.baseUrl ?? OPENAI_CHATGPT_CODEX_BASE_URL,
+    headers,
+  };
+}