@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/links/types.d.ts

@@ -0,0 +1,44 @@
+export type LinkActionRisk = "discovery" | "read" | "write";
+export interface LocalLinkIdentity {
+    externalAccountId: string;
+    label: string;
+    detail?: string;
+    /** Safe, non-secret resource labels that may be previewed in the Link card. */
+    resourceLabels?: string[];
+}
+export interface LocalLinkValidationResult {
+    providerId: string;
+    identity: LocalLinkIdentity;
+    capabilityIds: string[];
+    verifiedAt: string;
+}
+export interface LocalLinkActionSummary {
+    id: string;
+    title: string;
+    description: string;
+    risk: LinkActionRisk;
+}
+export interface LocalLinkProviderSummary {
+    id: string;
+    displayName: string;
+    tokenLabel: string;
+    tokenPlaceholder: string;
+    actions: LocalLinkActionSummary[];
+}
+export interface LocalLinkActionContext {
+    token: string;
+    params: Record<string, unknown>;
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}
+export interface LocalLinkActionSpec extends LocalLinkActionSummary {
+    execute(context: LocalLinkActionContext): Promise<unknown>;
+}
+export interface LocalLinkProviderSpec {
+    id: string;
+    displayName: string;
+    tokenLabel: string;
+    tokenPlaceholder: string;
+    validate(context: Omit<LocalLinkActionContext, "params">): Promise<LocalLinkIdentity>;
+    actions: LocalLinkActionSpec[];
+}

package/dist/llm/client-base.d.ts

@@ -31,6 +31,13 @@ export declare abstract class LLMClientBase {
     abstract createMessage(options: CreateMessageOptions): Promise<LLMResponse>;
     protected recordUsage(usage: TokenUsage, options?: CreateMessageOptions): void;
     getUsage(): LLMUsageTracker;
+    /**
+     * Cache-relevant request identity only. Credentials, retry/timeout policy,
+     * arbitrary catalog payloads, and endpoint text are deliberately excluded.
+     */
+    getPromptCacheConfigIdentity(): Readonly<Record<string, unknown>>;
+    /** Cache namespace identity with a normalized, credential-free endpoint. */
+    getPromptCacheScopeIdentity(): Readonly<Record<string, unknown>>;
     /** Zero all accumulated usage. Used when starting a fresh accounting window
      *  (e.g. after a model switch, where the prior model's cache stats no longer
      *  apply). */

package/dist/llm/client-base.js

@@ -54,20 +54,62 @@ export class LLMClientBase {
         this.initClient();
     }
     recordUsage(usage, options) {
-        if (options?.recordUsage === false)
-            return;
-        this.usage.records.push(usage);
-        this.usage.totalPromptTokens += usage.promptTokens;
-        this.usage.totalCompletionTokens += usage.completionTokens;
-        this.usage.totalTokens += usage.totalTokens;
-        this.usage.totalCacheReadTokens += usage.cacheReadTokens ?? 0;
-        this.usage.totalCacheCreationTokens += usage.cacheCreationTokens ?? 0;
-        this.usage.requestCount++;
-        LLMClientBase.onUsage?.(this.model, usage);
+        if (options?.requestVisible !== false) {
+            this.usage.records.push(usage);
+            this.usage.totalPromptTokens += usage.promptTokens;
+            this.usage.totalCompletionTokens += usage.completionTokens;
+            this.usage.totalTokens += usage.totalTokens;
+            this.usage.totalCacheReadTokens += usage.cacheReadTokens ?? 0;
+            this.usage.totalCacheCreationTokens += usage.cacheCreationTokens ?? 0;
+            this.usage.requestCount++;
+        }
+        if (options?.billingEnabled !== false) {
+            LLMClientBase.onUsage?.(this.model, usage);
+        }
     }
     getUsage() {
         return { ...this.usage };
     }
+    /**
+     * Cache-relevant request identity only. Credentials, retry/timeout policy,
+     * arbitrary catalog payloads, and endpoint text are deliberately excluded.
+     */
+    getPromptCacheConfigIdentity() {
+        const allowedExtraBodyKeys = new Set([
+            "temperature",
+            "top_p",
+            "thinking",
+            "reasoning",
+            "reasoning_effort",
+            "max_tokens",
+            "max_completion_tokens",
+            "service_tier",
+        ]);
+        const extraBody = Object.fromEntries(Object.entries(this.config.extraBody ?? {}).filter(([key]) => allowedExtraBodyKeys.has(key)));
+        return {
+            provider: this.provider,
+            providerKind: this.config.providerKind ?? this.provider,
+            model: this.model,
+            ...(this.maxTokens !== undefined ? { maxTokens: this.maxTokens } : {}),
+            ...(this.config.reasoning !== undefined ? { reasoning: this.config.reasoning } : {}),
+            ...(this.config.reasoningSummary !== undefined
+                ? { reasoningSummary: this.config.reasoningSummary }
+                : {}),
+            ...(this.config.serviceTier !== undefined ? { serviceTier: this.config.serviceTier } : {}),
+            temperature: this.temperature,
+            ...(this.imageDetail !== undefined ? { imageDetail: this.imageDetail } : {}),
+            ...(Object.keys(extraBody).length > 0 ? { extraBody } : {}),
+        };
+    }
+    /** Cache namespace identity with a normalized, credential-free endpoint. */
+    getPromptCacheScopeIdentity() {
+        return {
+            provider: this.provider,
+            providerKind: this.config.providerKind ?? this.provider,
+            model: this.model,
+            endpoint: normalizeCacheEndpoint(this.config.baseUrl),
+        };
+    }
     /** Zero all accumulated usage. Used when starting a fresh accounting window
      *  (e.g. after a model switch, where the prior model's cache stats no longer
      *  apply). */
@@ -226,6 +268,26 @@ export class LLMClientBase {
         throw lastError ?? new LLMError("Unknown LLM error");
     }
 }
+function normalizeCacheEndpoint(baseUrl) {
+    if (!baseUrl)
+        return "(provider-default)";
+    try {
+        const url = new URL(baseUrl);
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        const path = url.pathname.replace(/\/+$/u, "") || "/";
+        const port = (url.protocol === "https:" && url.port === "443") ||
+            (url.protocol === "http:" && url.port === "80")
+            ? ""
+            : url.port;
+        return `${url.protocol.toLocaleLowerCase()}//${url.hostname.toLocaleLowerCase()}${port ? `:${port}` : ""}${path}`;
+    }
+    catch {
+        return "(custom-endpoint)";
+    }
+}
 /**
  * Sleep `ms`, but wake immediately if `signal` aborts. Returns true when it
  * woke due to an abort (caller should bail), false on a normal timeout.

package/dist/llm/model-pool.d.ts

@@ -9,7 +9,7 @@
  *
  * Consumers:
  *   - Engine/TurnLoop: `pool.get()` for the active model
- *   - Arena: `pool.get("sonnet")` to resolve participants by key
+ *   - Product capabilities: `pool.get("sonnet")` to resolve a model by key
  *   - /model command: `pool.switch("haiku")` for hot-swap
  */
 import type { LLMConfig } from "../types.js";

package/dist/llm/model-pool.js

@@ -9,7 +9,7 @@
  *
  * Consumers:
  *   - Engine/TurnLoop: `pool.get()` for the active model
- *   - Arena: `pool.get("sonnet")` to resolve participants by key
+ *   - Product capabilities: `pool.get("sonnet")` to resolve a model by key
  *   - /model command: `pool.switch("haiku")` for hot-swap
  */
 import { readCache } from "./model-cache.js";

package/dist/llm/providers/anthropic.d.ts

@@ -16,6 +16,7 @@ export declare class AnthropicClient extends LLMClientBase {
      */
     private _capability;
     private get capability();
+    getPromptCacheConfigIdentity(): Readonly<Record<string, unknown>>;
     /**
      * Translate the resolved ReasoningSetting into Anthropic's `thinking` field,
      * honoring the model's reasoning shape (rules.ts):

package/dist/llm/providers/anthropic.js

@@ -55,6 +55,15 @@ export class AnthropicClient extends LLMClientBase {
         }
         return this._capability;
     }
+    getPromptCacheConfigIdentity() {
+        return {
+            ...super.getPromptCacheConfigIdentity(),
+            cacheStrategy: "anthropic-explicit",
+            cacheLayoutVersion: "system-tools-history-v1",
+            breakpointCount: 3,
+            reasoningShape: this.capability.reasoning,
+        };
+    }
     /**
      * Translate the resolved ReasoningSetting into Anthropic's `thinking` field,
      * honoring the model's reasoning shape (rules.ts):

package/dist/llm/providers/openai.d.ts

@@ -77,6 +77,7 @@ export declare class OpenAIClient extends LLMClientBase {
      * "anthropic/".
      */
     private get isOpenRouterAnthropic();
+    getPromptCacheConfigIdentity(): Readonly<Record<string, unknown>>;
     createMessage(options: CreateMessageOptions): Promise<LLMResponse>;
     /**
      * Build the request body honoring the model's capability descriptor.

package/dist/llm/providers/openai.js

@@ -212,6 +212,23 @@ export class OpenAIClient extends LLMClientBase {
     get isOpenRouterAnthropic() {
         return this.config.providerKind === "openrouter" && /^~?anthropic\//.test(this.model);
     }
+    getPromptCacheConfigIdentity() {
+        const capability = this.capability;
+        return {
+            ...super.getPromptCacheConfigIdentity(),
+            cacheStrategy: this.isOpenRouterAnthropic
+                ? "openrouter-anthropic-explicit"
+                : "provider-automatic",
+            cacheLayoutVersion: this.isOpenRouterAnthropic ? "system-history-v1" : "automatic-v1",
+            tokenLimitField: this._forceMaxCompletionTokens
+                ? "max_completion_tokens"
+                : capability.tokenLimitField,
+            reasoningShape: capability.reasoning,
+            rejectedParams: [...capability.rejectedParams].sort(),
+            forceMaxCompletionTokens: this._forceMaxCompletionTokens,
+            dropReasoningEffort: this._dropReasoningEffort,
+        };
+    }
     async createMessage(options) {
         return this.withRetry(async (requestSignal) => {
             // requestSignal = caller's cancel signal composed with a per-request

package/dist/llm/types.d.ts

@@ -12,13 +12,20 @@ export interface CreateMessageOptions {
     onChunk?: (chunk: LLMStreamChunk) => void;
     signal?: AbortSignal;
     /**
-     * If false, this call's usage is excluded from the client's usage tracker
-     * and from the process-wide onUsage hook. Used for auxiliary sub-calls
-     * (tool-summary, future helper prompts) that should not appear in
-     * session_end.cost or skew turn/requestCount semantics.
+     * Whether this real provider request is billed through the process-wide
+     * usage hook. This is independent of request visibility: auxiliary calls
+     * are normally billed while remaining hidden from the foreground request
+     * tracker. Only explicit manual-audit paths should disable billing.
      * @default true
      */
-    recordUsage?: boolean;
+    billingEnabled?: boolean;
+    /**
+     * Whether this request appears in the client's foreground usage tracker.
+     * Hidden auxiliary calls must report their usage to their owning Engine's
+     * session/Goal recorder instead.
+     * @default true
+     */
+    requestVisible?: boolean;
     /**
      * Reasoning/thinking setting for this call. Overrides LLMConfig.reasoning.
      * Rich shape ({mode:"off"|"on"} | {mode:"effort",effort} |

package/dist/model-catalog/index.js

@@ -51,8 +51,21 @@ export function getMergedCatalog() {
     const byId = new Map();
     for (const e of BUILTIN_CATALOG)
         byId.set(e.id, e);
-    for (const e of loadUserCatalog())
-        byId.set(e.id, e); // user overrides built-in
+    for (const userEntry of loadUserCatalog()) {
+        const base = byId.get(userEntry.id);
+        if (!base || userEntry.modelPresetsMode !== "merge") {
+            byId.set(userEntry.id, userEntry); // legacy/full user override
+            continue;
+        }
+        const presets = new Map((base.modelPresets ?? []).map((preset) => [preset.value, preset]));
+        for (const preset of userEntry.modelPresets ?? [])
+            presets.set(preset.value, preset);
+        byId.set(userEntry.id, {
+            ...base,
+            ...userEntry,
+            modelPresets: [...presets.values()],
+        });
+    }
     return [...byId.values()];
 }
 /**

package/dist/model-catalog/resolve.d.ts

@@ -40,9 +40,21 @@ export interface ResolvedInstance {
     model: string;
     paramValues: Record<string, unknown>;
 }
+/**
+ * A credential may be shared by multiple catalog entries only when they refer
+ * to the same provider family AND endpoint origin. This preserves intentional
+ * sharing such as OpenAI text ↔ OpenAI Images/Transcribe while preventing an
+ * OpenAI account from being attached to an OpenRouter template merely because
+ * both speak the OpenAI-compatible protocol.
+ *
+ * An exact catalogId match remains authoritative: a credential can carry an
+ * explicit provider-specific baseUrl override for that catalog entry.
+ */
+export declare function isCredentialCompatible(entry: CatalogEntry, credential: Credential, catalog: CatalogEntry[], connectionBaseUrl?: string): boolean;
 /**
  * Resolve `inst` against the credential list (for its key) and `catalog`.
- * Returns null when the instance's catalogId resolves to no entry.
+ * Returns null when the instance's catalogId resolves to no entry or an
+ * explicitly referenced credential belongs to a different provider/endpoint.
  * baseUrl precedence: connection override → credential → catalog default.
  */
 export declare function resolveInstance(inst: ModelInstance, credentials: Credential[], catalog: CatalogEntry[]): ResolvedInstance | null;

package/dist/model-catalog/resolve.js

@@ -7,18 +7,53 @@
  * See docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md §6.
  */
 import { findCatalogEntry } from "./index.js";
+function endpointOrigin(baseUrl) {
+    if (!baseUrl)
+        return undefined;
+    try {
+        return new URL(baseUrl).origin.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A credential may be shared by multiple catalog entries only when they refer
+ * to the same provider family AND endpoint origin. This preserves intentional
+ * sharing such as OpenAI text ↔ OpenAI Images/Transcribe while preventing an
+ * OpenAI account from being attached to an OpenRouter template merely because
+ * both speak the OpenAI-compatible protocol.
+ *
+ * An exact catalogId match remains authoritative: a credential can carry an
+ * explicit provider-specific baseUrl override for that catalog entry.
+ */
+export function isCredentialCompatible(entry, credential, catalog, connectionBaseUrl) {
+    if (credential.catalogId === entry.id)
+        return true;
+    const credentialEntry = findCatalogEntry(catalog, credential.catalogId);
+    if (!credentialEntry || credentialEntry.adapterKind !== entry.adapterKind)
+        return false;
+    const connectionOrigin = endpointOrigin(connectionBaseUrl ?? entry.defaultBaseUrl);
+    const credentialOrigin = endpointOrigin(credential.baseUrl ?? credentialEntry.defaultBaseUrl);
+    return Boolean(connectionOrigin && credentialOrigin && connectionOrigin === credentialOrigin);
+}
 /**
  * Resolve `inst` against the credential list (for its key) and `catalog`.
- * Returns null when the instance's catalogId resolves to no entry.
+ * Returns null when the instance's catalogId resolves to no entry or an
+ * explicitly referenced credential belongs to a different provider/endpoint.
  * baseUrl precedence: connection override → credential → catalog default.
  */
 export function resolveInstance(inst, credentials, catalog) {
     const entry = findCatalogEntry(catalog, inst.catalogId);
     if (!entry)
         return null;
-    const cred = inst.credentialId
+    const candidate = inst.credentialId
         ? credentials.find((c) => c.id === inst.credentialId)
         : undefined;
+    if (candidate && !isCredentialCompatible(entry, candidate, catalog, inst.baseUrl)) {
+        return null;
+    }
+    const cred = candidate;
     const preset = entry.modelPresets?.find((p) => p.value === inst.model);
     return {
         entry,