@cjhyy/code-shell-core 0.9.2 → 0.9.4

package/dist/llm/providers/openai.js

@@ -16,7 +16,8 @@ import { capabilitiesFor } from "../capabilities/index.js";
 import { clampMaxTokens } from "../clamp-max-tokens.js";
 import { resolveApiKey, resolveHeaders } from "../provider-auth.js";
 import { stripVisionFromHistory } from "../strip-vision.js";
-import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError, } from "../stream-watchdog.js";
+import { resolvePromptCachePolicy, uniquePromptCacheBreakpointIndexes, } from "../prompt-cache.js";
+import { STREAM_WATCHDOG_CONFIG, StreamIdleTimeoutError } from "../stream-watchdog.js";
 /**
  * Extract prompt-cache counts from an OpenAI-compatible usage object.
  *
@@ -74,9 +75,7 @@ export async function runStreamWithWatchdog(stream, opts = {}) {
     // An explicit idleTimeoutMs always activates the watchdog. Otherwise follow
     // disableWatchdog (per-call override) if set, else the env default.
     const watchdogActive = opts.idleTimeoutMs !== undefined ||
-        (opts.disableWatchdog === undefined
-            ? STREAM_WATCHDOG_CONFIG.enabled
-            : !opts.disableWatchdog);
+        (opts.disableWatchdog === undefined ? STREAM_WATCHDOG_CONFIG.enabled : !opts.disableWatchdog);
     const idleTimeoutMs = opts.idleTimeoutMs ?? STREAM_WATCHDOG_CONFIG.idleTimeoutMs;
     let text = "";
     // Fast path: watchdog disabled AND caller did not override → no overhead.
@@ -224,6 +223,9 @@ export class OpenAIClient extends LLMClientBase {
     // succeed. Omitting the field just means "model default reasoning", which is
     // fine for our background/aux calls.
     _dropReasoningEffort = false;
+    /** Compatibility fallbacks for OpenAI-compatible gateways that lag the API. */
+    _disableExplicitPromptCache = false;
+    _disablePromptCacheKey = false;
     constructor(config, defaults, runtimeOptions = {}) {
         super(config, defaults);
         this.dangerouslyAllowBrowser = runtimeOptions.dangerouslyAllowBrowser === true;
@@ -264,30 +266,26 @@ export class OpenAIClient extends LLMClientBase {
         }
         return this._capability;
     }
-    /**
-     * True when this client routes an Anthropic-family model through OpenRouter's
-     * OpenAI-compatible endpoint. Anthropic caching is EXPLICIT — nothing is
-     * cached unless the request carries `cache_control` breakpoints (verified live
-     * 2026-07-02: plain requests to anthropic/claude-opus-4.7-fast via OpenRouter
-     * report cached_tokens 0 on every repeat; a single system-block breakpoint
-     * turns the whole stable prefix — tools + system — into a cache hit, ~89%
-     * cheaper on the follow-up). OpenAI and other OpenRouter models cache
-     * automatically, so they must NOT get breakpoints. The slug arrives resolved
-     * (e.g. "anthropic/claude-opus-4.7-fast") or as the router alias
-     * ("~anthropic/claude-opus-latest") — both start with an optional "~" then
-     * "anthropic/".
-     */
-    get isOpenRouterAnthropic() {
-        return this.config.providerKind === "openrouter" && /^~?anthropic\//.test(this.model);
+    promptCachePolicy(request) {
+        const policy = resolvePromptCachePolicy({
+            provider: this.provider,
+            providerKind: this.config.providerKind,
+            model: this.model,
+            request,
+            explicitDisabled: this._disableExplicitPromptCache,
+        });
+        return this._disablePromptCacheKey && policy.cacheKey
+            ? { ...policy, cacheKey: undefined }
+            : policy;
     }
     getPromptCacheConfigIdentity() {
         const capability = this.capability;
+        const cachePolicy = this.promptCachePolicy();
         return {
             ...super.getPromptCacheConfigIdentity(),
-            cacheStrategy: this.isOpenRouterAnthropic
-                ? "openrouter-anthropic-explicit"
-                : "provider-automatic",
-            cacheLayoutVersion: this.isOpenRouterAnthropic ? "system-history-v1" : "automatic-v1",
+            cacheStrategy: cachePolicy.strategy,
+            cacheLayoutVersion: cachePolicy.layoutVersion,
+            cacheBreakpoints: cachePolicy.breakpoints,
             tokenLimitField: this._forceMaxCompletionTokens
                 ? "max_completion_tokens"
                 : capability.tokenLimitField,
@@ -295,6 +293,8 @@ export class OpenAIClient extends LLMClientBase {
             rejectedParams: [...capability.rejectedParams].sort(),
             forceMaxCompletionTokens: this._forceMaxCompletionTokens,
             dropReasoningEffort: this._dropReasoningEffort,
+            disableExplicitPromptCache: this._disableExplicitPromptCache,
+            disablePromptCacheKey: this._disablePromptCacheKey,
         };
     }
     async createMessage(options) {
@@ -305,7 +305,7 @@ export class OpenAIClient extends LLMClientBase {
             // Per-call reasoning wins; otherwise fall back to provider default
             // (settings.providers[].reasoning, threaded through LLMConfig).
             const reasoning = options.reasoning ?? this.config.reasoning;
-            const messages = this.buildMessages(options.systemPrompt, options.messages, reasoning);
+            const messages = this.buildMessages(options.systemPrompt, options.messages, reasoning, options.promptCache);
             const tools = options.tools?.length ? this.convertTools(options.tools) : undefined;
             const span = logger.span("llm.request", {
                 cat: "llm",
@@ -314,6 +314,7 @@ export class OpenAIClient extends LLMClientBase {
                 stream: !!(options.stream && options.onChunk),
                 messageCount: messages.length,
                 toolCount: tools?.length ?? 0,
+                cacheStrategy: this.promptCachePolicy(options.promptCache).strategy,
             });
             try {
                 const response = options.stream && options.onChunk
@@ -341,6 +342,7 @@ export class OpenAIClient extends LLMClientBase {
      */
     buildRequestBody(options, messages, tools, reasoning, stream) {
         const cap = this.capability;
+        const cachePolicy = this.promptCachePolicy(options.promptCache);
         // Clamp to the model's known output ceiling so a stale catalog value
         // (e.g. 384000 inherited after a hot model switch) can't 400 a
         // smaller-cap model. No known cap → send the value as-is.
@@ -449,10 +451,10 @@ export class OpenAIClient extends LLMClientBase {
         // requested summary level to that object. For the bare `reasoning_effort`
         // shape there's no summary field on chat-completions, so we skip it rather
         // than send an unknown top-level param.
-        if (this.config.reasoningSummary && reasoningBody.reasoning &&
+        if (this.config.reasoningSummary &&
+            reasoningBody.reasoning &&
             typeof reasoningBody.reasoning === "object") {
-            reasoningBody.reasoning.summary =
-                this.config.reasoningSummary;
+            reasoningBody.reasoning.summary = this.config.reasoningSummary;
         }
         // Catalog-driven passthrough params (temperature/top_p/thinking etc, already
         // wire-mapped from the connection's paramValues by applyParams). Filter each
@@ -489,6 +491,12 @@ export class OpenAIClient extends LLMClientBase {
             ...paramBody,
             // service_tier (TODO 7.2): passed through verbatim when configured.
             ...(this.config.serviceTier ? { service_tier: this.config.serviceTier } : {}),
+            ...(options.promptCache && cachePolicy.cacheKey
+                ? { prompt_cache_key: cachePolicy.cacheKey }
+                : {}),
+            ...(options.promptCache && cachePolicy.promptCacheOptions
+                ? { prompt_cache_options: cachePolicy.promptCacheOptions }
+                : {}),
             ...(tools ? { tools } : {}),
             ...(stream ? { stream: true, stream_options: { include_usage: true } } : {}),
         };
@@ -740,7 +748,7 @@ export class OpenAIClient extends LLMClientBase {
             ...(reasoningContent ? { reasoningContent } : {}),
         };
     }
-    buildMessages(systemPrompt, messages, reasoning) {
+    buildMessages(systemPrompt, messages, reasoning, promptCache) {
         const result = [{ role: "system", content: systemPrompt }];
         // Drop historical image blocks when the active model can't accept vision.
         // Engine.run only gates *new* attachments; an image left in history from
@@ -748,6 +756,8 @@ export class OpenAIClient extends LLMClientBase {
         // below and 400s ("unknown variant `image_url`") after a model switch.
         // Identity-preserving on the common path (vision models / no images).
         messages = stripVisionFromHistory(messages, this.capability.supportsVision);
+        const stablePrefixMessageCount = Math.max(0, Math.min(messages.length, promptCache?.stablePrefixMessageCount ?? messages.length));
+        let stablePrefixEndMessage = stablePrefixMessageCount === 0 ? result[0] : undefined;
         // Reasoning-content echo-back contract — driven by capability:
         //   "when-tools"  : backfill an empty placeholder if the prior assistant
         //                   turn doesn't carry one (DeepSeek V4 + tools 400s
@@ -760,11 +770,13 @@ export class OpenAIClient extends LLMClientBase {
         const cap = this.capability;
         const hasTools = messages.some((m) => Array.isArray(m.content) &&
             m.content.some((b) => b.type === "tool_use" || b.type === "tool_result"));
-        const needsReasoningBackfill = reasoning?.mode !== "off" &&
-            cap.echoReasoning === "when-tools" &&
-            hasTools;
+        const needsReasoningBackfill = reasoning?.mode !== "off" && cap.echoReasoning === "when-tools" && hasTools;
         const stripReasoning = cap.echoReasoning === "never";
-        for (const msg of messages) {
+        for (let sourceIndex = 0; sourceIndex < messages.length; sourceIndex++) {
+            if (sourceIndex === stablePrefixMessageCount) {
+                stablePrefixEndMessage = result[result.length - 1];
+            }
+            const msg = messages[sourceIndex];
             if (msg.role === "system")
                 continue;
             if (msg.role === "assistant") {
@@ -948,55 +960,64 @@ export class OpenAIClient extends LLMClientBase {
                 }
             }
         }
+        stablePrefixEndMessage ??= result[result.length - 1];
         const normalized = normalizeOpenAIToolMessagePairs(result);
-        if (this.isOpenRouterAnthropic) {
-            this.applyAnthropicCacheBreakpoints(normalized);
+        const stablePrefixEndIndex = stablePrefixEndMessage
+            ? normalized.indexOf(stablePrefixEndMessage)
+            : undefined;
+        const cachePolicy = this.promptCachePolicy(promptCache);
+        if (promptCache || cachePolicy.strategy === "anthropic-explicit") {
+            this.applyPromptCacheBreakpoints(normalized, cachePolicy, stablePrefixEndIndex !== undefined && stablePrefixEndIndex >= 0
+                ? stablePrefixEndIndex
+                : undefined);
         }
         return normalized;
     }
     /**
-     * In-place: add prompt-cache breakpoints for Anthropic-over-OpenRouter.
-     * Mirrors the native anthropic provider (≤4 breakpoints):
-     *   1. System block  — the stable prefix. Anthropic sees tools BEFORE the
-     *      system prompt, so one marker on the system block caches tools too
-     *      (verified live: system-only marker cached 3511/3952 prompt tokens
-     *      including tool defs).
-     *   2. Last message  — one rolling breakpoint so the growing conversation
-     *      history becomes a cached prefix. Not scrolled: as history grows the
-     *      "last message" naturally advances and its tail is the next write.
-     * A string `content` is lifted to a single-element `[{type:"text",...}]`
-     * array so it can carry `cache_control`; OpenRouter accepts this OpenAI
-     * multimodal wire form for text.
+     * Translate semantic prefix boundaries to the active wire format. Both
+     * formats annotate content blocks without reordering messages.
      */
-    applyAnthropicCacheBreakpoints(messages) {
-        const mark = (m) => {
-            if (!m)
+    applyPromptCacheBreakpoints(messages, policy, stablePrefixEndIndex) {
+        if (policy.strategy !== "anthropic-explicit" && policy.strategy !== "openai-explicit") {
+            return;
+        }
+        const markedMessages = new Set();
+        const mark = (index) => {
+            let cursor = Math.min(index, messages.length - 1);
+            let m;
+            while (cursor >= 0) {
+                const candidate = messages[cursor];
+                if ((typeof candidate.content === "string" && candidate.content.length > 0) ||
+                    (Array.isArray(candidate.content) && candidate.content.length > 0)) {
+                    m = candidate;
+                    break;
+                }
+                cursor--;
+            }
+            if (!m || markedMessages.has(m))
                 return;
+            markedMessages.add(m);
+            const marker = policy.strategy === "anthropic-explicit"
+                ? { cache_control: { type: "ephemeral" } }
+                : { prompt_cache_breakpoint: { mode: "explicit" } };
             // Lift a plain-string content to a text-block array so it can carry the
-            // marker. Non-text content (tool messages, image arrays) already uses an
-            // array of parts — mark the last part instead.
+            // marker. Non-text content already uses an array of parts.
             if (typeof m.content === "string") {
-                m.content = [
-                    { type: "text", text: m.content, cache_control: { type: "ephemeral" } },
-                ];
+                m.content = [{ type: "text", text: m.content, ...marker }];
                 return;
             }
             if (Array.isArray(m.content) && m.content.length > 0) {
-                // cache_control is an Anthropic-via-OpenRouter extension field, not in
-                // the OpenAI content-part union — attach through `unknown`.
                 const last = m.content[m.content.length - 1];
-                last.cache_control = { type: "ephemeral" };
+                Object.assign(last, marker);
             }
         };
-        // 1. System block (always index 0 — buildMessages seeds it first).
-        const sys = messages[0];
-        if (sys && sys.role === "system")
-            mark(sys);
-        // 2. Rolling history breakpoint on the very last message. Skip if it IS the
-        //    system message (no conversation yet) — one breakpoint already covers it.
-        const last = messages[messages.length - 1];
-        if (last && last !== sys)
-            mark(last);
+        const requested = uniquePromptCacheBreakpointIndexes([
+            policy.breakpoints.includes("system") ? 0 : undefined,
+            policy.breakpoints.includes("stable-history") ? stablePrefixEndIndex : undefined,
+            policy.breakpoints.includes("rolling-history") ? messages.length - 1 : undefined,
+        ]);
+        for (const index of requested)
+            mark(index);
     }
     convertTools(tools) {
         return tools.map((t) => ({
@@ -1031,6 +1052,33 @@ export class OpenAIClient extends LLMClientBase {
             // the corrected body — fixing the call that triggered it, not just the
             // next one.
             let selfCorrected = false;
+            // New GPT-5.6 cache fields may reach an OpenAI-compatible gateway before
+            // that gateway supports them. Downgrade sticky-per-client and retry once:
+            // first explicit -> implicit, then omit the affinity key only if that is
+            // also rejected. Native OpenAI keeps the optimized path.
+            if (err.status === 400 && msg.includes("prompt_cache")) {
+                if ((msg.includes("prompt_cache_options") || msg.includes("prompt_cache_breakpoint")) &&
+                    !this._disableExplicitPromptCache) {
+                    this._disableExplicitPromptCache = true;
+                    selfCorrected = true;
+                    logger.warn("llm.prompt_cache_explicit_unsupported", {
+                        cat: "llm",
+                        provider: this.provider,
+                        providerKind: this.config.providerKind,
+                        model: this.model,
+                    });
+                }
+                if (msg.includes("prompt_cache_key") && !this._disablePromptCacheKey) {
+                    this._disablePromptCacheKey = true;
+                    selfCorrected = true;
+                    logger.warn("llm.prompt_cache_key_unsupported", {
+                        cat: "llm",
+                        provider: this.provider,
+                        providerKind: this.config.providerKind,
+                        model: this.model,
+                    });
+                }
+            }
             // o-series / gpt-5+ reject `max_tokens` and demand
             // `max_completion_tokens`. The id-based regex catches the common
             // cases; this is the belt-and-suspenders path for ids that ship
@@ -1095,8 +1143,12 @@ export class OpenAIClient extends LLMClientBase {
 function deepMergeInto(dst, src) {
     for (const [k, v] of Object.entries(src)) {
         const cur = dst[k];
-        if (v && typeof v === "object" && !Array.isArray(v) &&
-            cur && typeof cur === "object" && !Array.isArray(cur)) {
+        if (v &&
+            typeof v === "object" &&
+            !Array.isArray(v) &&
+            cur &&
+            typeof cur === "object" &&
+            !Array.isArray(cur)) {
             deepMergeInto(cur, v);
         }
         else {

package/dist/llm/types.d.ts

@@ -2,6 +2,7 @@
  * LLM-specific internal types.
  */
 import type { Message, ToolDefinition, LLMStreamChunk, TokenUsage } from "../types.js";
+import type { PromptCacheRequestContext } from "./prompt-cache.js";
 export interface CreateMessageOptions {
     systemPrompt: string;
     messages: Message[];
@@ -33,6 +34,8 @@ export interface CreateMessageOptions {
      * the client's capability layer.
      */
     reasoning?: import("./reasoning-setting.js").ReasoningSetting;
+    /** Provider-neutral prompt-cache context supplied by the model facade. */
+    promptCache?: PromptCacheRequestContext;
 }
 export interface LLMUsageTracker {
     records: TokenUsage[];

package/dist/onboarding.js

@@ -4,7 +4,7 @@
  * (see src/ui/components/OnboardingPrompt.tsx); this module only exposes
  * pure(-ish) helpers it consumes, so there's a single input stack.
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { userHome } from "./settings/manager.js";
 import { getOpenRouterModels } from "./data/openrouter-models.js";
@@ -14,6 +14,7 @@ import { KNOWN_MAX_OUTPUT, KNOWN_CONTEXT_WINDOWS, OPENROUTER_VENDORS, PROVIDERS,
 export { PROVIDERS };
 import { sanitizeApiKey } from "./llm/api-key-sanitize.js";
 import { getMergedCatalog } from "./model-catalog/index.js";
+import { mutateJsonFile } from "./utils/file-mutex.js";
 // ProviderDef 类型 + PROVIDERS 目录已外移到 data/model-metadata.json
 // (loader: data/model-metadata.ts),并在文件顶部 re-export。core 只读目录数据。
 // ─── Dynamic model list (OpenRouter snapshot) ────────────────────
@@ -115,7 +116,7 @@ export async function validateApiKey(baseUrl, apiKey) {
                 headers: { Authorization: `Bearer ${apiKey}` },
                 signal: AbortSignal.timeout(10_000),
             });
-            const data = await res.json();
+            const data = (await res.json());
             return !data.error;
         }
         const url = baseUrl.replace(/\/$/, "") + "/models";
@@ -162,6 +163,8 @@ export function hasApiKey() {
     // Reads ~/.code-shell/ only — ~/.claude/ compat was dropped because Claude
     // Code's settings schema diverges and merging broke boot.
     const p = join(userHome(), ".code-shell", "settings.json");
+    // This is only a boot-time hint. A slightly stale read can show onboarding
+    // once; all mutations below still re-read under the shared file lock.
     if (existsSync(p)) {
         try {
             const data = JSON.parse(readFileSync(p, "utf-8"));
@@ -170,7 +173,9 @@ export function hasApiKey() {
             if (Array.isArray(data?.modelConnections) && data.modelConnections.length > 0)
                 return true;
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
     }
     return false;
 }
@@ -297,50 +302,68 @@ export function appendOnboardingResult(opts) {
     const tag = opts.tag ?? "text";
     const dir = join(userHome(), ".code-shell");
     const file = join(dir, "settings.json");
-    mkdirSync(dir, { recursive: true });
-    let existing = {};
-    if (existsSync(file)) {
-        try {
-            existing = JSON.parse(readFileSync(file, "utf-8"));
-        }
-        catch { /* corrupt → replace */ }
-    }
-    const creds = Array.isArray(existing.credentials)
-        ? [...existing.credentials] : [];
-    const conns = Array.isArray(existing.modelConnections)
-        ? [...existing.modelConnections] : [];
-    for (const m of opts.models) {
-        const catalogId = catalogIdForKind(m.kind);
-        const credId = `${m.instanceId}-key`;
-        if (!creds.some((c) => c?.id === credId)) {
-            creds.push({ id: credId, catalogId, apiKey: m.apiKey, baseUrl: m.baseUrl });
-        }
-        if (!conns.some((c) => c?.id === m.instanceId)) {
-            conns.push({
-                id: m.instanceId, catalogId, tag, model: m.model, credentialId: credId,
-                ...(m.baseUrl ? { baseUrl: m.baseUrl } : {}),
-            });
-        }
-    }
-    const existingDefaults = (typeof existing.defaults === "object" && existing.defaults)
-        ? existing.defaults : {};
-    const updated = {
-        ...existing,
-        credentials: creds,
-        modelConnections: conns,
-        defaults: { ...existingDefaults, [tag]: opts.activeId },
-    };
-    // Atomic write: tmp file in the same dir, then rename (atomic on POSIX).
-    // mode 0o600 — settings.json holds plaintext API keys, must be owner-only.
-    const tmp = `${file}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(updated, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
-    try {
-        renameSync(tmp, file);
-    }
-    catch {
-        // Fallback: best-effort direct write if rename fails (e.g. cross-device),
-        // then remove the orphaned temp file the failed rename left behind.
-        writeFileSync(file, JSON.stringify(updated, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
-        rmSync(tmp, { force: true });
-    }
+    mutateJsonFile(file, {
+        parse: (raw) => {
+            if (raw === undefined)
+                return {};
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (error) {
+                throw new Error("settings.json is unreadable; onboarding did not overwrite it", {
+                    cause: error,
+                });
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error("settings.json must contain a JSON object");
+            }
+            return parsed;
+        },
+        serialize: (value) => `${JSON.stringify(value, null, 2)}\n`,
+        mutation: (existing) => {
+            const creds = Array.isArray(existing.credentials)
+                ? [...existing.credentials]
+                : [];
+            const conns = Array.isArray(existing.modelConnections)
+                ? [...existing.modelConnections]
+                : [];
+            for (const model of opts.models) {
+                const catalogId = catalogIdForKind(model.kind);
+                const credentialId = `${model.instanceId}-key`;
+                if (!creds.some((credential) => credential?.id === credentialId)) {
+                    creds.push({
+                        id: credentialId,
+                        catalogId,
+                        apiKey: model.apiKey,
+                        baseUrl: model.baseUrl,
+                    });
+                }
+                if (!conns.some((connection) => connection?.id === model.instanceId)) {
+                    conns.push({
+                        id: model.instanceId,
+                        catalogId,
+                        tag,
+                        model: model.model,
+                        credentialId,
+                        ...(model.baseUrl ? { baseUrl: model.baseUrl } : {}),
+                    });
+                }
+            }
+            const existingDefaults = existing.defaults &&
+                typeof existing.defaults === "object" &&
+                !Array.isArray(existing.defaults)
+                ? existing.defaults
+                : {};
+            return {
+                value: {
+                    ...existing,
+                    credentials: creds,
+                    modelConnections: conns,
+                    defaults: { ...existingDefaults, [tag]: opts.activeId },
+                },
+            };
+        },
+        mode: 0o600,
+    });
 }

package/dist/panel-apps/manifest.d.ts

@@ -57,37 +57,37 @@ export declare const PanelAppAgentContribution: z.ZodEffects<z.ZodObject<{
     }>, "many">>;
     skills: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
 }, "strict", z.ZodTypeAny, {
-    skills: string[];
     tools: {
         name: string;
         description: string;
         inputSchema: Record<string, unknown>;
         readOnly: boolean;
     }[];
+    skills: string[];
 }, {
-    skills?: string[] | undefined;
     tools?: {
         name: string;
         description: string;
         inputSchema: Record<string, unknown>;
         readOnly?: boolean | undefined;
     }[] | undefined;
+    skills?: string[] | undefined;
 }>, {
-    skills: string[];
     tools: {
         name: string;
         description: string;
         inputSchema: Record<string, unknown>;
         readOnly: boolean;
     }[];
+    skills: string[];
 }, {
-    skills?: string[] | undefined;
     tools?: {
         name: string;
         description: string;
         inputSchema: Record<string, unknown>;
         readOnly?: boolean | undefined;
     }[] | undefined;
+    skills?: string[] | undefined;
 }>;
 /**
  * Schema v2 keeps one installable Panel App identity while allowing it to
@@ -178,37 +178,37 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
         }>, "many">>;
         skills: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, "strict", z.ZodTypeAny, {
-        skills: string[];
         tools: {
             name: string;
             description: string;
             inputSchema: Record<string, unknown>;
             readOnly: boolean;
         }[];
+        skills: string[];
     }, {
-        skills?: string[] | undefined;
         tools?: {
             name: string;
             description: string;
             inputSchema: Record<string, unknown>;
             readOnly?: boolean | undefined;
         }[] | undefined;
+        skills?: string[] | undefined;
     }>, {
-        skills: string[];
         tools: {
             name: string;
             description: string;
             inputSchema: Record<string, unknown>;
             readOnly: boolean;
         }[];
+        skills: string[];
     }, {
-        skills?: string[] | undefined;
         tools?: {
             name: string;
             description: string;
             inputSchema: Record<string, unknown>;
             readOnly?: boolean | undefined;
         }[] | undefined;
+        skills?: string[] | undefined;
     }>>;
     id: z.ZodString;
     version: z.ZodString;
@@ -247,13 +247,13 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
     placement: "right-dock";
     singleton: boolean;
     agent?: {
-        skills: string[];
         tools: {
             name: string;
             description: string;
             inputSchema: Record<string, unknown>;
             readOnly: boolean;
         }[];
+        skills: string[];
     } | undefined;
     description?: string | undefined;
 }, {
@@ -267,13 +267,13 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
     };
     schemaVersion: 2;
     agent?: {
-        skills?: string[] | undefined;
         tools?: {
             name: string;
             description: string;
             inputSchema: Record<string, unknown>;
             readOnly?: boolean | undefined;
         }[] | undefined;
+        skills?: string[] | undefined;
     } | undefined;
     description?: string | undefined;
     permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "agent.task" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage" | "process")[] | undefined;
@@ -310,13 +310,13 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
     placement: "right-dock";
     singleton: boolean;
     agent?: {
-        skills: string[];
         tools: {
             name: string;
             description: string;
             inputSchema: Record<string, unknown>;
             readOnly: boolean;
         }[];
+        skills: string[];
     } | undefined;
     description?: string | undefined;
 }, {
@@ -345,13 +345,13 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
     };
     schemaVersion: 2;
     agent?: {
-        skills?: string[] | undefined;
         tools?: {
             name: string;
             description: string;
             inputSchema: Record<string, unknown>;
             readOnly?: boolean | undefined;
         }[] | undefined;
+        skills?: string[] | undefined;
     } | undefined;
     description?: string | undefined;
     permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "agent.task" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage" | "process")[] | undefined;