@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/context/manager.js

@@ -5,7 +5,7 @@
  * Tier 2: LLM summary (async) — generate summary of older messages via model call
  * Tier 3: window compact (sync, emergency) — aggressive truncation fallback
  */
-import { estimateTokens, microcompact, dedupeFileReads, maskOldObservations, snipCompact, windowCompact, truncateToolResult, buildSummarizationPrompt, applySummaryCompaction, applyToolResultBudget, extractAnchoredSummary, } from "./compaction.js";
+import { estimateTokens, microcompact, dedupeFileReads, maskOldObservations, snipCompact, windowCompact, truncateToolResult, buildSummarizationPrompt, applySummaryCompaction, applyToolResultBudget, extractAnchoredSummary, buildAnchoredSummaryMessage, extractReferencedFilePaths, } from "./compaction.js";
 import { applyToolResultPersistence, createContentReplacementState, reconstructContentReplacementState, resolveToolResultsDir, } from "./tool-result-storage.js";
 import { logger } from "../logging/logger.js";
 const DEFAULT_CONFIG = {
@@ -162,7 +162,7 @@ export class ContextManager {
     setSummarizeFn(fn) {
         this.summarizeFn = fn;
     }
-    async trySummaryCompact(messages, before, logEvent) {
+    async trySummaryCompact(messages, before, logEvent, signal) {
         if (!this.summarizeFn || this.consecutiveSummaryFailures >= 3) {
             return { messages, tokens: before, compacted: false, noProgress: false };
         }
@@ -178,7 +178,7 @@ export class ContextManager {
             // re-summarizes from scratch.
             const priorSummary = extractAnchoredSummary(messages) ?? this.lastSummary;
             const prompt = buildSummarizationPrompt(messagesToSummarize, priorSummary);
-            const summary = await this.summarizeFn(prompt);
+            const summary = await this.summarizeFn(prompt, signal);
             if (!summary || summary.length <= 50) {
                 this.consecutiveSummaryFailures++;
                 logger.warn("context.summary_failed", {
@@ -358,7 +358,7 @@ export class ContextManager {
      * Async context management — attempts LLM summarization before falling back.
      * Call this when you have access to the LLM (between turns).
      */
-    async manageAsync(messages) {
+    async manageAsync(messages, signal) {
         let result = messages;
         // Tier 0a: Persist large tool_results to disk + replace with preview.
         result = this.persistLargeToolResults(result);
@@ -428,7 +428,7 @@ export class ContextManager {
         // Tier 2: LLM summary if approaching limit, or if micro was the only tier
         // available in the 0.70-0.85 band and it freed nothing.
         if (ratio >= this.config.compactAtRatio || shouldEscalateNoOpMicro) {
-            const summarized = await this.trySummaryCompact(result, tokens, "context.summary_compact");
+            const summarized = await this.trySummaryCompact(result, tokens, "context.summary_compact", signal);
             result = summarized.messages;
             tokens = summarized.tokens;
             if (summarized.compacted) {
@@ -488,7 +488,7 @@ export class ContextManager {
      * a long-but-under-threshold text-only conversation (the /compact bug) still
      * gets summarized here.
      */
-    async forceSummarize(messages) {
+    async forceSummarize(messages, signal) {
         let result = messages;
         // Tier 0: same waste-removal + micro as the automatic path.
         result = this.persistLargeToolResults(result);
@@ -505,7 +505,7 @@ export class ContextManager {
         let tokens = this.estimateTokensHybrid(result);
         // Unconditional LLM summary (no ratio gate).
         {
-            const summarized = await this.trySummaryCompact(result, tokens, "context.force_summary_compact");
+            const summarized = await this.trySummaryCompact(result, tokens, "context.force_summary_compact", signal);
             result = summarized.messages;
             tokens = summarized.tokens;
             if (summarized.compacted)
@@ -529,6 +529,41 @@ export class ContextManager {
         }
         return result;
     }
+    /**
+     * Generic range archival: summarize a caller-chosen contiguous index window
+     * `[range.start, range.end)` into a single anchored summary message, leaving
+     * everything outside the window untouched. Unlike manage()/forceSummarize,
+     * the window is caller-specified, not derived from a pressure heuristic — the
+     * caller decides which span to collapse. Returns the input unchanged when no
+     * summarizeFn is set, when the (clamped) window is empty, or when the summary
+     * is empty/too short. The emitted summary uses the same anchored marker the
+     * rolling-summary path reads, so a later compaction can merge-update it.
+     */
+    async summarizeRange(messages, range, opts = {}) {
+        const start = Math.max(0, Math.min(range.start, messages.length));
+        const end = Math.max(start, Math.min(range.end, messages.length));
+        if (!this.summarizeFn || end - start < 1)
+            return messages;
+        const window = messages.slice(start, end);
+        // Feed a prior anchored summary back so the LLM merge-updates rather than
+        // re-summarizes from scratch, matching the rolling-summary behavior of
+        // trySummaryCompact().
+        const priorSummary = extractAnchoredSummary(messages) ?? this.lastSummary;
+        const prompt = buildSummarizationPrompt(window, priorSummary);
+        const summary = await this.summarizeFn(prompt, opts.signal);
+        if (!summary || summary.length <= 50)
+            return messages;
+        this.lastSummary = summary;
+        const summaryMessage = buildAnchoredSummaryMessage(summary, {
+            ...(this.transcriptPath ? { transcriptPath: this.transcriptPath } : {}),
+            referencedFiles: extractReferencedFilePaths(window),
+        });
+        const before = this.estimateTokensHybrid(messages);
+        const out = [...messages.slice(0, start), summaryMessage, ...messages.slice(end)];
+        const after = this.estimateTokensHybrid(out);
+        this.onCompact?.({ strategy: "range", before, after });
+        return out;
+    }
     /**
      * Persist large tool_result blocks to disk and replace them with a
      * preview + filepath. No-op when transcript path hasn't been set

package/dist/context/token-counter.js

@@ -15,6 +15,9 @@ const RATIOS = {
     mixed: 3.6, // Mixed content (typical for tool results)
     cjk: 1.5, // CJK characters: ~1.5 chars per token
 };
+// Base64 is transport data, not text. A fixed vision estimate prevents large
+// images from spuriously exhausting the text context window.
+const IMAGE_TOKEN_ESTIMATE = 170;
 /**
  * Estimate token count for a string, detecting content type.
  */
@@ -80,12 +83,11 @@ function estimateBlockTokens(block) {
     if (block.name)
         tokens += estimateStringTokens(block.name);
     if (block.source?.data) {
-        tokens += estimateStringTokens(block.source.media_type);
-        tokens += estimateStringTokens(block.source.data);
+        tokens += IMAGE_TOKEN_ESTIMATE;
     }
     const maybeOpenAI = block;
     if (typeof maybeOpenAI.image_url?.url === "string") {
-        tokens += estimateStringTokens(maybeOpenAI.image_url.url);
+        tokens += IMAGE_TOKEN_ESTIMATE;
     }
     return tokens;
 }

package/dist/context/tool-result-storage.d.ts

@@ -55,6 +55,12 @@ export declare function reconstructContentReplacementState(messages: Message[]):
  * transcript path. Layout:  <transcriptDir>/tool-results/
  */
 export declare function resolveToolResultsDir(transcriptPath: string): string;
+/**
+ * Convert an externally supplied tool_use_id to a bounded internal filename.
+ * The original id remains the key in ContentReplacementState/onPersist; it is
+ * never used as a path component.
+ */
+export declare function safeToolResultFilename(toolUseId: string): string;
 interface PersistOptions {
     /** Per-result threshold; default DEFAULT_PERSIST_THRESHOLD. */
     perResultThreshold?: number;

package/dist/context/tool-result-storage.js

@@ -22,7 +22,8 @@
  *     parallel Read results), persist the largest ones first until under.
  */
 import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
 import { logger } from "../logging/logger.js";
 // ─── Tunables ───────────────────────────────────────────────────────
 /** Per-result threshold. Larger than this → persist + replace. */
@@ -77,12 +78,32 @@ function ensureDir(dir) {
     }
 }
 /**
- * Write content to <dir>/<toolUseId>.txt. Idempotent: skips if the file
- * already exists (tool_use_id is a UUID, content is deterministic per id).
+ * Convert an externally supplied tool_use_id to a bounded internal filename.
+ * The original id remains the key in ContentReplacementState/onPersist; it is
+ * never used as a path component.
  */
+export function safeToolResultFilename(toolUseId) {
+    if (toolUseId.length > 256) {
+        throw new RangeError("tool_use_id exceeds the 256 character limit");
+    }
+    if (isAbsolute(toolUseId) ||
+        win32.isAbsolute(toolUseId) ||
+        toolUseId.includes("/") ||
+        toolUseId.includes("\\")) {
+        throw new Error("tool_use_id must not contain a path");
+    }
+    return `${createHash("sha256").update(toolUseId, "utf8").digest("hex")}.txt`;
+}
+/** Write content to the contained hashed path. Idempotent by original id. */
 function persistToFile(dir, toolUseId, content) {
+    const root = resolve(dir);
+    const filename = safeToolResultFilename(toolUseId);
+    const filepath = resolve(root, filename);
+    const rel = relative(root, filepath);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error("tool_result path escaped its storage root");
+    }
     ensureDir(dir);
-    const filepath = join(dir, `${toolUseId}.txt`);
     try {
         // 'wx' = fail if exists. Skipping on collision is correct: same id =
         // same content. Avoids re-writing the same bytes every turn.

package/dist/credentials/access.d.ts

@@ -1,4 +1,4 @@
-import type { Credential, CredentialType } from "./types.js";
+import { type Credential, type CredentialType } from "./types.js";
 import type { SettingsScope } from "../settings/manager.js";
 import type { Transport } from "../protocol/transport.js";
 export type CredentialAccessScope = "full" | "project";
@@ -18,12 +18,23 @@ export interface CredentialAccess {
     listMasked(cwd: string | undefined, scope: CredentialAccessScope): CredentialMetadata[];
     resolveMeta(cwd: string | undefined, id: string, scope: CredentialAccessScope): CredentialMetadata | undefined;
     envExposures(cwd: string | undefined, scope: CredentialAccessScope): Record<string, string>;
+    /** Subscribe to host credential snapshot changes (desktop worker uses this to cancel in-flight Links). */
+    subscribe?(listener: () => void): () => void;
     resolveValue?(req: {
         cwd?: string;
         id: string;
         scope: CredentialAccessScope;
-        purpose: "use" | "mcp";
+        purpose: "use" | "mcp" | "link";
     }): Promise<string>;
+    /** Resolve only the bearer material needed by an MCP request. */
+    resolveOAuthAccess?(req: {
+        id: string;
+        scope: "full";
+        forceRefresh?: boolean;
+    }): Promise<{
+        accessToken: string;
+        expiresAt?: string;
+    }>;
     materializeCookie?(req: {
         cwd?: string;
         id: string;

package/dist/credentials/access.js

@@ -2,9 +2,11 @@ import { existsSync, readdirSync, rmSync, statSync, writeFileSync } from "node:f
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { credentialAllowsEnvExposure, credentialSecretHint, } from "./types.js";
 import { CredentialStore } from "./store.js";
 import { formatNetscapeCookies, parseCookieJar } from "./cookie-jar.js";
-import { summarizeOAuthCredentialSecret } from "./oauth.js";
+import { parseOAuthCredentialSecret, isBrowserOAuthLinkCredential, resolveLinkCredentialAccessToken, shouldRefreshOAuthCredential, summarizeOAuthCredentialSecret, } from "./oauth.js";
+import { refreshToken } from "../services/oauth.js";
 const COOKIE_FILE_PREFIX = "codeshell-cred-cookie-";
 const COOKIE_FILE_MAX_AGE_MS = 30 * 60 * 1000;
 let defaultCredentialAccess = null;
@@ -17,6 +19,7 @@ export function getCredentialAccess() {
 export function createIpcCredentialAccess(transport) {
     let snapshot = { revision: 0, entries: [] };
     let nextId = 1;
+    const subscribers = new Set();
     const pending = new Map();
     transport.onMessage((msg) => {
         if ("method" in msg && msg.method === "desktop/credentialSnapshot") {
@@ -26,6 +29,14 @@ export function createIpcCredentialAccess(transport) {
                     revision: params.revision,
                     entries: params.entries,
                 };
+                for (const listener of subscribers) {
+                    try {
+                        listener();
+                    }
+                    catch {
+                        // One consumer must not break the credential snapshot transport.
+                    }
+                }
             }
             return;
         }
@@ -79,12 +90,26 @@ export function createIpcCredentialAccess(transport) {
                 return {};
             return { ...(scope === "project" ? entry.envProject : entry.envFull) };
         },
+        subscribe(listener) {
+            subscribers.add(listener);
+            return () => subscribers.delete(listener);
+        },
         async resolveValue(req) {
             const result = (await request("desktop/credentialResolve", req));
             if (typeof result?.value !== "string")
                 throw new Error(`credential "${req.id}" is unavailable`);
             return result.value;
         },
+        async resolveOAuthAccess(req) {
+            const result = (await request("desktop/oauthAccessResolve", req));
+            if (typeof result?.accessToken !== "string") {
+                throw new Error(`oauth credential "${req.id}" requires login`);
+            }
+            return {
+                accessToken: result.accessToken,
+                expiresAt: typeof result.expiresAt === "string" ? result.expiresAt : undefined,
+            };
+        },
         async materializeCookie(req) {
             const result = (await request("desktop/credentialMaterializeCookie", req));
             if (typeof result?.cookiesFile !== "string" || typeof result.count !== "number") {
@@ -106,9 +131,12 @@ function toMetadata(cred) {
     const { secret: _secret, ...rest } = cred;
     return {
         ...rest,
+        ...(credentialAllowsEnvExposure(cred.type) ? {} : { exposeAsEnv: undefined }),
         hasSecret: available,
-        secretHint: available ? (secret.length > 4 ? `****${secret.slice(-4)}` : "****") : undefined,
-        ...(cred.type === "oauth" ? { oauthStatus: summarizeOAuthCredentialSecret(secret) } : {}),
+        secretHint: available ? credentialSecretHint(cred.type, secret) : undefined,
+        ...(cred.type === "oauth" || isBrowserOAuthLinkCredential(cred)
+            ? { oauthStatus: summarizeOAuthCredentialSecret(secret) }
+            : {}),
     };
 }
 function cloneMetadata(list) {
@@ -129,6 +157,8 @@ export const localCredentialAccess = {
         const out = {};
         const creds = storeFor(cwd).list(scope);
         for (const cred of creds) {
+            if (!credentialAllowsEnvExposure(cred.type))
+                continue;
             const name = cred.exposeAsEnv?.trim();
             if (name && isCredentialSecretAvailable(cred.secret))
                 out[name] = cred.secret;
@@ -140,7 +170,16 @@ export const localCredentialAccess = {
         if (!cred || !isCredentialSecretAvailable(cred.secret)) {
             throw new Error(`credential "${req.id}" is unavailable`);
         }
-        return cred.secret;
+        if (req.purpose === "link" &&
+            (cred.type !== "link" ||
+                cred.meta?.linkExecutionRuntime !== "local" ||
+                !cred.meta.linkProvider)) {
+            throw new Error(`credential "${req.id}" is not a local Link credential`);
+        }
+        return req.purpose === "link" ? resolveLinkCredentialAccessToken(cred) : cred.secret;
+    },
+    async resolveOAuthAccess(req) {
+        return resolveLocalOAuthAccess(req.id, Boolean(req.forceRefresh));
     },
     async materializeCookie(req) {
         const cred = storeFor(req.cwd).resolve(req.id, req.scope);
@@ -150,6 +189,62 @@ export const localCredentialAccess = {
         return materializeCookieSecret(cred.id, cred.secret);
     },
 };
+const localOAuthRefreshes = new Map();
+async function resolveLocalOAuthAccess(id, forceRefresh) {
+    const store = new CredentialStore(undefined);
+    const cred = store.resolve(id, "full");
+    if (!cred || cred.type !== "oauth" || !isCredentialSecretAvailable(cred.secret)) {
+        throw new Error(`oauth credential "${id}" requires login`);
+    }
+    const parsed = parseOAuthCredentialSecret(cred.secret);
+    const decision = shouldRefreshOAuthCredential(parsed);
+    if (!forceRefresh && decision === "no") {
+        return { accessToken: parsed.accessToken, expiresAt: parsed.expiresAt };
+    }
+    if (!parsed.refreshToken || !parsed.tokenEndpoint || !parsed.clientId) {
+        throw new Error(`oauth credential "${id}" requires login`);
+    }
+    const inflight = localOAuthRefreshes.get(id);
+    if (inflight)
+        return inflight;
+    const pending = (async () => {
+        const latestCred = store.resolve(id, "full");
+        if (!latestCred || latestCred.type !== "oauth" || !latestCred.secret) {
+            throw new Error(`oauth credential "${id}" requires login`);
+        }
+        const latest = parseOAuthCredentialSecret(latestCred.secret);
+        if (!forceRefresh && shouldRefreshOAuthCredential(latest) === "no") {
+            return { accessToken: latest.accessToken, expiresAt: latest.expiresAt };
+        }
+        if (!latest.refreshToken || !latest.tokenEndpoint || !latest.clientId) {
+            throw new Error(`oauth credential "${id}" requires login`);
+        }
+        const tokens = await refreshToken({
+            clientId: latest.clientId,
+            clientSecret: latest.clientSecret,
+            tokenEndpoint: latest.tokenEndpoint,
+            authorizationEndpoint: "",
+            scopes: latest.scopes,
+            resource: latest.resource,
+        }, latest.refreshToken);
+        const next = {
+            ...latest,
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken ?? latest.refreshToken,
+            expiresAt: tokens.expiresAt ? new Date(tokens.expiresAt).toISOString() : undefined,
+            tokenType: tokens.tokenType,
+            scope: tokens.scope ?? latest.scope,
+        };
+        store.save("user", {
+            ...latestCred,
+            secret: JSON.stringify(next),
+            meta: { ...latestCred.meta, lastRefreshAt: new Date().toISOString() },
+        });
+        return { accessToken: next.accessToken, expiresAt: next.expiresAt };
+    })().finally(() => localOAuthRefreshes.delete(id));
+    localOAuthRefreshes.set(id, pending);
+    return pending;
+}
 export function materializeCookieSecret(credentialId, secret) {
     const jar = parseCookieJar(secret);
     if (jar.length === 0)

package/dist/credentials/index.d.ts

@@ -2,8 +2,9 @@ export { CredentialStore } from "./store.js";
 export type { CredentialScope, MaskedCredential } from "./store.js";
 export { type EncryptionCipher, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./cipher.js";
 export { getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, isCredentialSecretAvailable, materializeCookieSecret, type CredentialAccess, type CredentialAccessScope, type CredentialMetadata, type CredentialSnapshot, type CredentialSnapshotEntry, } from "./access.js";
-export type { Credential, CredentialType, CredentialStoreFile, OAuthCredentialPublicStatus, OAuthCredentialSecret, } from "./types.js";
-export { buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, summarizeOAuthCredentialSecret, type OAuthClockOptions, type OAuthRefreshHandler, type OAuthRefreshRequest, } from "./oauth.js";
+export type { Credential, CredentialType, CredentialStoreFile, OAuthCredentialPublicStatus, OAuthCredentialSecret, OAuthTokenResponse, } from "./types.js";
+export { credentialAllowsEnvExposure, credentialSecretHint } from "./types.js";
+export { buildOAuthRefreshRequest, isBrowserOAuthLinkCredential, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, resolveLinkCredentialAccessToken, mergeOAuthTokenResponse, shouldRefreshOAuthCredential, summarizeOAuthCredentialSecret, type OAuthClockOptions, type OAuthRefreshHandler, type OAuthRefreshRequest, } from "./oauth.js";
 export { formatNetscapeCookies, parseCookieJar, type CookieLike } from "./cookie-jar.js";
 export { useCredentialToolDef, useCredentialToolDefFor, useCredentialTool, sweepStaleCredentialCookies, } from "./use-credential-tool.js";
 export { credentialUseGate } from "./use-gate.js";

package/dist/credentials/index.js

@@ -1,7 +1,8 @@
 export { CredentialStore } from "./store.js";
 export { PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./cipher.js";
 export { getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, isCredentialSecretAvailable, materializeCookieSecret, } from "./access.js";
-export { buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, summarizeOAuthCredentialSecret, } from "./oauth.js";
+export { credentialAllowsEnvExposure, credentialSecretHint } from "./types.js";
+export { buildOAuthRefreshRequest, isBrowserOAuthLinkCredential, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, resolveLinkCredentialAccessToken, mergeOAuthTokenResponse, shouldRefreshOAuthCredential, summarizeOAuthCredentialSecret, } from "./oauth.js";
 export { formatNetscapeCookies, parseCookieJar } from "./cookie-jar.js";
 export { useCredentialToolDef, useCredentialToolDefFor, useCredentialTool, sweepStaleCredentialCookies, } from "./use-credential-tool.js";
 export { credentialUseGate } from "./use-gate.js";

package/dist/credentials/oauth.d.ts

@@ -1,4 +1,4 @@
-import type { OAuthCredentialPublicStatus, OAuthCredentialSecret } from "./types.js";
+import type { Credential, OAuthCredentialPublicStatus, OAuthCredentialSecret, OAuthTokenResponse } from "./types.js";
 export interface OAuthClockOptions {
     now?: number | (() => number);
     skewMs?: number;
@@ -14,6 +14,14 @@ export interface OAuthRefreshRequest {
 }
 export type OAuthRefreshHandler = (req: OAuthRefreshRequest) => Promise<OAuthCredentialSecret>;
 export declare function parseOAuthCredentialSecret(secret: string): OAuthCredentialSecret;
+export declare function isBrowserOAuthLinkCredential(credential: Pick<Credential, "type" | "meta">): boolean;
+/** Return only the bearer token from a Link secret, never its refresh material. */
+export declare function resolveLinkCredentialAccessToken(credential: Pick<Credential, "type" | "secret" | "meta">): string | undefined;
+/** Merge and validate an OAuth token endpoint response without losing rotation state. */
+export declare function mergeOAuthTokenResponse(previous: OAuthCredentialSecret | undefined, response: OAuthTokenResponse, opts?: {
+    now?: number;
+}): OAuthCredentialSecret;
+export declare function shouldRefreshOAuthCredential(secret: OAuthCredentialSecret, opts?: OAuthClockOptions): "no" | "refresh" | "login_required";
 export declare function isOAuthAccessTokenExpired(secret: Pick<OAuthCredentialSecret, "accessToken" | "expiresAt">, opts?: OAuthClockOptions): boolean;
 export declare function oauthCredentialStatus(secret: Pick<OAuthCredentialSecret, "accessToken" | "expiresAt">, opts?: OAuthClockOptions): Pick<OAuthCredentialPublicStatus, "state" | "expiresAt" | "expiresInMs">;
 export declare function buildOAuthRefreshRequest(credentialId: string, secret: OAuthCredentialSecret): OAuthRefreshRequest | undefined;

package/dist/credentials/oauth.js

@@ -15,6 +15,17 @@ function optionalStringArray(value) {
     const out = value.filter((x) => typeof x === "string" && x.length > 0);
     return out.length > 0 ? out : undefined;
 }
+function optionalFiniteNumber(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error("OAuth token response expires_in must be a finite non-negative number");
+    }
+    if (value < 0) {
+        throw new Error("OAuth token response expires_in must be a finite non-negative number");
+    }
+    return value;
+}
 function parseExpiresAt(value) {
     if (!value)
         return undefined;
@@ -45,19 +56,87 @@ export function parseOAuthCredentialSecret(secret) {
     }
     const expiresAt = optionalString(raw.expiresAt);
     parseExpiresAt(expiresAt);
+    const refreshTokenExpiresAt = optionalString(raw.refreshTokenExpiresAt);
+    parseExpiresAt(refreshTokenExpiresAt);
+    const tokenType = optionalString(raw.tokenType);
+    if (tokenType && tokenType.toLowerCase() !== "bearer") {
+        throw new Error("OAuth credential tokenType must be Bearer");
+    }
     return {
         version: raw.version === 1 ? 1 : undefined,
         accessToken,
         refreshToken: optionalString(raw.refreshToken),
         expiresAt,
-        tokenType: optionalString(raw.tokenType),
+        refreshTokenExpiresAt,
+        tokenType,
         scope: optionalString(raw.scope),
         scopes: optionalStringArray(raw.scopes),
         tokenEndpoint: optionalString(raw.tokenEndpoint),
         clientId: optionalString(raw.clientId),
         clientSecret: optionalString(raw.clientSecret),
+        issuer: optionalString(raw.issuer),
+        resource: optionalString(raw.resource),
+        revocationEndpoint: optionalString(raw.revocationEndpoint),
+        clientRegistration: raw.clientRegistration &&
+            typeof raw.clientRegistration === "object" &&
+            !Array.isArray(raw.clientRegistration) &&
+            optionalString(raw.clientRegistration.clientId)
+            ? {
+                clientId: optionalString(raw.clientRegistration.clientId),
+                clientSecret: optionalString(raw.clientRegistration.clientSecret),
+                clientIdIssuedAt: typeof raw.clientRegistration.clientIdIssuedAt ===
+                    "number"
+                    ? raw.clientRegistration.clientIdIssuedAt
+                    : undefined,
+                clientSecretExpiresAt: typeof raw.clientRegistration.clientSecretExpiresAt ===
+                    "number"
+                    ? raw.clientRegistration
+                        .clientSecretExpiresAt
+                    : undefined,
+            }
+            : undefined,
+    };
+}
+export function isBrowserOAuthLinkCredential(credential) {
+    return credential.type === "link" && credential.meta?.linkAuthSource === "browser-oauth";
+}
+/** Return only the bearer token from a Link secret, never its refresh material. */
+export function resolveLinkCredentialAccessToken(credential) {
+    if (!credential.secret)
+        return undefined;
+    return isBrowserOAuthLinkCredential(credential)
+        ? parseOAuthCredentialSecret(credential.secret).accessToken
+        : credential.secret;
+}
+/** Merge and validate an OAuth token endpoint response without losing rotation state. */
+export function mergeOAuthTokenResponse(previous, response, opts = {}) {
+    const accessToken = optionalString(response.access_token);
+    if (!accessToken)
+        throw new Error("OAuth token response must include access_token");
+    const tokenType = optionalString(response.token_type) ?? "Bearer";
+    if (tokenType.toLowerCase() !== "bearer") {
+        throw new Error(`OAuth token response token_type must be Bearer`);
+    }
+    const expiresIn = optionalFiniteNumber(response.expires_in);
+    const now = opts.now ?? Date.now();
+    const responseScope = optionalString(response.scope);
+    const refreshToken = optionalString(response.refresh_token) ?? previous?.refreshToken;
+    return {
+        ...previous,
+        version: 1,
+        accessToken,
+        refreshToken,
+        expiresAt: expiresIn === undefined ? undefined : new Date(now + expiresIn * 1000).toISOString(),
+        tokenType: "Bearer",
+        scope: responseScope ?? previous?.scope,
+        scopes: responseScope ? responseScope.split(/\s+/).filter(Boolean) : previous?.scopes,
     };
 }
+export function shouldRefreshOAuthCredential(secret, opts = {}) {
+    if (!isOAuthAccessTokenExpired(secret, opts))
+        return "no";
+    return secret.refreshToken && secret.tokenEndpoint ? "refresh" : "login_required";
+}
 export function isOAuthAccessTokenExpired(secret, opts = {}) {
     const expiresAtMs = parseExpiresAt(secret.expiresAt);
     if (expiresAtMs === undefined)

package/dist/credentials/store.d.ts

@@ -1,4 +1,4 @@
-import type { Credential } from "./types.js";
+import { type Credential } from "./types.js";
 import { type EncryptionCipher } from "./cipher.js";
 export type CredentialScope = "user" | "project";
 export interface MaskedCredential extends Omit<Credential, "secret"> {
@@ -13,6 +13,13 @@ export interface MaskedCredential extends Omit<Credential, "secret"> {
  */
 export declare class CredentialStore {
     private readonly cwd?;
+    /**
+     * Override the user-scope store directory (the `~/.code-shell` layer;
+     * `credentials.json` lives directly inside it). Absent → today's
+     * behavior: `join(userHome(), ".code-shell")` resolved per call.
+     * Injection point for identity-scoped server deployments.
+     */
+    private readonly userDirOverride?;
     private readonly cipher;
     /**
      * @param cwd     project root for the project-scope store (undefined → user only).
@@ -22,7 +29,14 @@ export declare class CredentialStore {
      *                returns PLAINTEXT secrets; encryption is applied only at the
      *                disk boundary (read decrypts, write encrypts).
      */
-    constructor(cwd?: string | undefined, cipher?: EncryptionCipher);
+    constructor(cwd?: string | undefined, cipher?: EncryptionCipher, 
+    /**
+     * Override the user-scope store directory (the `~/.code-shell` layer;
+     * `credentials.json` lives directly inside it). Absent → today's
+     * behavior: `join(userHome(), ".code-shell")` resolved per call.
+     * Injection point for identity-scoped server deployments.
+     */
+    userDirOverride?: string | undefined);
     private pathFor;
     /**
      * Decrypt a stored secret to plaintext. A value this cipher can't decrypt