qlogicagent 2.18.6 → 2.18.8

package/dist/types/skills/memory/host-memory-provider.d.ts

@@ -0,0 +1,148 @@
+/**
+ * HostMemoryProvider —— qlogicagent 大脑对 memories.db 的存取反转(Route B B3;X7 brain proxy)。
+ *
+ * 与 LocalMemoryProvider 同公开面的 **proxy 实现**:大脑逻辑(dream/distill/晋升/consolidation/召回 hook)
+ * 零改动,底下的存取经 `x/host.request`(HostRequestClient)打到 gateway 四权威 host 服务(memory 域),
+ * store(memories.db)只有 gateway 进程打开。
+ *
+ * 单一事实源:docs/agent-supervision-authority-migration-spec.md §3.1;契约 host-contract §13
+ * (HostRequestParams;wire 形态 = { service:"memory", method, params:<位置参数数组> })。
+ *
+ * 【PROXY 共享面(16 方法;两仓照此表,一字不差)】
+ *   search / addText / embedText / ingestExtracted / proposeExtracted / consumePendingProposals /
+ *   feedback / findRelatedEvents / synthesizeTimeline / getActivitySummary / getAllProfiles /
+ *   setProfile / getAtlas / setMemoryArchived / triggerDecay / resolveConflicts
+ *
+ * 面外方法 = fail-loud throw(护栏抓漏):gate 开时 UI RPC 面(atlas 富查询/update/attachments/
+ * proposals 消费等)由 gateway host-native 应答,**不该**再落到 qla 的 provider;到达此处 = 路由/
+ * wiring bug,绝不静默回落本地(静默回落 = 本进程再开 memories.db = 双权威,正是本工程消灭的形态)。
+ *
+ * 【单进程铁则】选型本 provider 后,本进程绝不打开 memories.db(零 better-sqlite3 memory 路径引用);
+ * userId 参数原样透传(多租户前缀语义归 gateway store-owner)。
+ * 纪律:fail-loud;单轨(创建时刻一次选型,非每调用分支);零 mock。
+ */
+import type { HostRequestParams } from "../../host-contract/index.js";
+import type { MemoryActivitySummary, MemoryAtlasResult, MemoryConsolidationWriteResult, MemoryDreamRuntimeProvider, MemoryExtractionItem, MemoryHandlerProvider, MemoryIngestOptions, MemoryLearningSink, MemoryRuntimeHookProvider, MemorySearchOptions, MemorySearchResult, MemoryToolProvider } from "../../runtime/ports/index.js";
+/**
+ * 最小转发口(结构化契约,由 coordinator-owned HostRequestClient 满足)。
+ * 只取 request 一个方法:provider 不持有判活/连接生命周期(那归协议 coordinator/client)。
+ */
+export interface HostRequestRequester {
+    request(params: HostRequestParams, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export interface HostMemoryProviderConfig {
+    /** x/host.request client; its service gate runs before send. */
+    client: HostRequestRequester;
+}
+export declare class HostMemoryProvider implements MemoryRuntimeHookProvider, MemoryLearningSink, MemoryToolProvider, MemoryHandlerProvider, MemoryDreamRuntimeProvider {
+    private readonly config;
+    readonly providerId = "qmemory-host";
+    constructor(config: HostMemoryProviderConfig);
+    /**
+     * 16 面统一转发:wire 形态 = { service:"memory", method, params:<位置参数数组> }(契约 §13)。
+     * 尾部 undefined 剔除:JSON 会把数组里的 undefined 序列化成 null,gateway 侧按位展开时
+     * null ≠ undefined 会击穿方法默认参(如 days=7)——省略实参才能让默认参生效。
+     */
+    private forward;
+    /** 面外方法护栏:fail-loud,绝不静默回落本地(见文件头)。 */
+    private unproxied;
+    search(query: string, userId: string, options?: MemorySearchOptions): Promise<MemorySearchResult[]>;
+    addText(text: string, userId: string, options?: MemoryIngestOptions & {
+        category?: string;
+        importance?: number;
+    }): Promise<{
+        memoriesAdded: number;
+    }>;
+    /** R3 蒸馏签名 embedding(gateway 调 llmrouter 现算);null = 不可用,调用方降级不炸。 */
+    embedText(text: string): Promise<number[] | null>;
+    ingestExtracted(items: MemoryExtractionItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationWriteResult>;
+    proposeExtracted(items: MemoryExtractionItem[], userId: string, options?: MemoryIngestOptions): Promise<MemoryConsolidationWriteResult>;
+    consumePendingProposals(userId: string, opts?: {
+        now?: number;
+        ttlMs?: number;
+        maxCommitsPerPass?: number;
+    }): Promise<{
+        committed: number;
+        merged: number;
+        expiredIds: string[];
+        pendingLeft: number;
+    }>;
+    feedback(memoryIds: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong"): Promise<{
+        affected: number;
+    }>;
+    findRelatedEvents(text: string, userId: string, options?: {
+        maxDaysBack?: number;
+        minSimilarity?: number;
+        maxSimilarity?: number;
+        limit?: number;
+    }): Promise<Array<{
+        id: string;
+        text: string;
+        score: number;
+        date: string;
+    }>>;
+    synthesizeTimeline(userId: string, startMs: number, endMs: number): Promise<string>;
+    getActivitySummary(userId: string, days?: number): Promise<MemoryActivitySummary>;
+    getAllProfiles(userId: string): Promise<Record<string, string>>;
+    setProfile(userId: string, key: string, value: string): Promise<void>;
+    getAtlas(userId: string, options?: {
+        pageSize?: number;
+        windowStartAt?: number;
+        windowEndAt?: number;
+        windowCenterAt?: number;
+        bucketCount?: number;
+        clusterLimit?: number;
+        activeOnly?: boolean;
+    }): Promise<MemoryAtlasResult>;
+    setMemoryArchived(memoryId: string, archived: boolean): Promise<boolean>;
+    triggerDecay(userId: string): Promise<{
+        decayed: number;
+    }>;
+    resolveConflicts(userId: string, opts?: {
+        minEvidenceToPromote?: number;
+    }): Promise<{
+        conflictsResolved: number;
+        claimsPromoted: number;
+    }>;
+    /** 本 provider 不持有 db 句柄/文件资源;close 为 no-op(shutdown 链 closeMemoryProviders 会调)。 */
+    close(): void;
+    remove(_memoryId: string): never;
+    update(_memoryId: string, _input: unknown): never;
+    observeExtracted(_items: MemoryExtractionItem[], _userId: string, _options?: MemoryIngestOptions): never;
+    listPendingProposals(_userId: string, _limit?: number, _status?: "pending" | "expired"): never;
+    resolveProposal(_userId: string, _proposalId: string, _action: "confirm" | "dismiss"): never;
+    listClaims(_userId: string): never;
+    listConflicts(_userId: string): never;
+    getProfile(_userId: string, _key: string): never;
+    deleteProfile(_userId: string, _key: string): never;
+    getTemporalSlice(_userId: string, _startMs: number, _endMs: number, _options?: {
+        category?: string;
+        limit?: number;
+    }): never;
+    list(_userId: string, _options?: {
+        page?: number;
+        pageSize?: number;
+        activeOnly?: boolean;
+    }): never;
+    listMemoriesByTag(_userId: string, _tag: string): never;
+    rerank(_results: unknown[], _options?: unknown): never;
+    health(): never;
+    count(_userId: string): never;
+    resetUser(_userId: string): never;
+    adoptAttachment(_input: {
+        data?: Buffer;
+        sourceUrl?: string;
+        filename: string;
+        mimeType: string;
+        userId: string;
+    }): never;
+    locateAttachment(_id: string): never;
+    purgeOrphanAttachments(): never;
+    readAttachmentBytes(_id: string): never;
+    setAttachmentText(_id: string, _text: string): never;
+}
+/** 工厂便捷函数(与 createLocalMemoryProvider 对称)。 */
+export declare function createHostMemoryProvider(config: HostMemoryProviderConfig): HostMemoryProvider;

package/dist/types/skills/memory/local-memory-provider.d.ts

@@ -72,8 +72,11 @@ export declare class LocalMemoryProvider implements MemoryProvider {
     private buildEmbedding;
     search(query: string, userId: string, options?: MemorySearchOptions): Promise<MemorySearchResult[]>;
     /** Public embedding access for task-distillation signatures (R3). Null when
-     * the embedding provider is unavailable — callers must degrade, not throw. */
-    embedText(text: string): Promise<Float32Array | null>;
+     * the embedding provider is unavailable — callers must degrade, not throw.
+     * B3(X7): returns number[] (not Float32Array) — this method is on the 16-method
+     * host-state proxy surface and its result crosses the x/host.request JSON wire
+     * in host mode; typed arrays do not survive JSON serialization. */
+    embedText(text: string): Promise<number[] | null>;
     addText(text: string, userId: string, options?: MemoryIngestOptions & {
         category?: string;
         importance?: number;
@@ -152,8 +155,9 @@ export declare class LocalMemoryProvider implements MemoryProvider {
      * Adjusts importance or archives/deletes based on signal.
      */
     /** V3 promote/demote: archive(技能接棒,记忆退役)与 unarchive(降格回归)成对。
-     * claims 状态随动,防 archived 记忆的 claim 继续参与冲突/召回。 */
-    setMemoryArchived(memoryId: string, archived: boolean): boolean;
+     * claims 状态随动,防 archived 记忆的 claim 继续参与冲突/召回。
+     * B3(X7)异步化:16 面 host-state proxy 方法,签名统一 Promise(实现体仍同步)。 */
+    setMemoryArchived(memoryId: string, archived: boolean): Promise<boolean>;
     feedback(memoryIds: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong"): Promise<{
         affected: number;
     }>;
@@ -163,12 +167,14 @@ export declare class LocalMemoryProvider implements MemoryProvider {
     getProfile(userId: string, key: string): string | null;
     /**
      * Set a user profile value (upsert).
+     * B3(X7)异步化:16 面 host-state proxy 方法。
      */
-    setProfile(userId: string, key: string, value: string): void;
+    setProfile(userId: string, key: string, value: string): Promise<void>;
     /**
      * Get all profile entries for a user.
+     * B3(X7)异步化:16 面 host-state proxy 方法。
      */
-    getAllProfiles(userId: string): Record<string, string>;
+    getAllProfiles(userId: string): Promise<Record<string, string>>;
     /**
      * Delete a profile entry.
      */
@@ -191,8 +197,9 @@ export declare class LocalMemoryProvider implements MemoryProvider {
     }[];
     /**
      * Get activity summary over recent N days (daily counts + highlights).
+     * B3(X7)异步化:16 面 host-state proxy 方法。
      */
-    getActivitySummary(userId: string, days?: number): {
+    getActivitySummary(userId: string, days?: number): Promise<{
         dailyCounts: Array<{
             date: string;
             count: number;
@@ -204,7 +211,7 @@ export declare class LocalMemoryProvider implements MemoryProvider {
             importance: number;
             date: string;
         }>;
-    };
+    }>;
     /**
      * List full memory records for a user (paginated). Used by the memory atlas
      * visualization, which needs the complete record shape (confidence, importance,
@@ -218,6 +225,7 @@ export declare class LocalMemoryProvider implements MemoryProvider {
     /**
      * Return the final atlas payload: a bounded interactive record window plus
      * whole-history buckets/clusters for large timelines.
+     * B3(X7)异步化:16 面 host-state proxy 方法。
      */
     getAtlas(userId: string, options?: {
         pageSize?: number;
@@ -227,7 +235,7 @@ export declare class LocalMemoryProvider implements MemoryProvider {
         bucketCount?: number;
         clusterLimit?: number;
         activeOnly?: boolean;
-    }): import("./local-store-records.js").MemoryAtlasResult;
+    }): Promise<import("./local-store-records.js").MemoryAtlasResult>;
     /** Complete tag-scoped listing (resident refresh / onboarding purge) — see store.listByTag. */
     listMemoriesByTag(userId: string, tag: string): import("./local-store-records.js").MemoryRecord[];
     /**
@@ -252,8 +260,9 @@ export declare class LocalMemoryProvider implements MemoryProvider {
     /**
      * Synthesize a temporal narrative from memories in a time range.
      * Returns a structured timeline suitable for prompt injection.
+     * B3(X7)异步化:16 面 host-state proxy 方法。
      */
-    synthesizeTimeline(userId: string, startMs: number, endMs: number): string;
+    synthesizeTimeline(userId: string, startMs: number, endMs: number): Promise<string>;
     /**
      * Rerank search results by applying recency boost, access frequency,
      * and importance weighting. No LLM needed - pure scoring heuristics.

package/dist/types/skills/memory/task-distillation.d.ts

@@ -7,6 +7,12 @@
  *   簇 ≥ 重复阈值才产 1 条 procedure 记忆 → 高复用晋升技能(见 coordinator)。
  * 成功闸不用 LLM 自评:正常终态 + 同 session 近窗内未被"重做"(在线否决)。
  * 与 feedback-distillation(反馈域)无关 —— 这里蒸馏的是任务执行模式。
+ *
+ * 【B3 登记·刻意不动】本文件的 profile 级 JSON store 直写(task-distill-candidates.json /
+ * promotion-proposals.json / procedure-usage.json,均 A 域)是 qla 写、gateway 读(gateway
+ * MemoryProfileService 已持 promotion-proposals.json)的**文件级共享过渡态**——B3.1 只反转
+ * memories.db 存取(LocalMemoryProvider→HostMemoryProvider),这批 JSON 随削藩批次归
+ * store-owner(spec §1 X7 裁决第 4 条)。单一事实源 docs/agent-supervision-authority-migration-spec.md。
  */
 /** 同模式判定的余弦下限。错聚有害(把不同任务蒸成一份配方),漏聚无害(下次再攒)。 */
 export declare const TASK_DISTILL_CLUSTER_SIM = 0.86;

package/dist/types/skills/plugins/plugin-marketplace.d.ts

@@ -1,77 +1,43 @@
 import { type ElectronNpm } from "../../runtime/infra/electron-node.js";
 export interface MarketplaceSource {
-    /** Source type */
     type: "npm" | "git" | "url";
-    /** Package name (npm), git URL, or zip URL */
     specifier: string;
-    /** Optional version constraint (npm only) */
     version?: string;
 }
 export interface MarketplaceConfig {
-    /** Enabled plugins from marketplace */
     enabledPlugins: MarketplaceSource[];
-    /**
-     * Enterprise policy: only allow plugins matching these names.
-     * If set, any plugin not in the allowlist is blocked.
-     */
     allowlist?: string[];
-    /**
-     * Enterprise policy: block these plugin names.
-     */
     blocklist?: string[];
 }
-export interface MarketplaceCatalogEntry {
-    /** Plugin name */
-    name: string;
-    /** Installed version */
-    version: string;
-    /** Source that provided this plugin */
-    source: MarketplaceSource;
-    /** Local install path */
-    installPath: string;
-    /** Install timestamp */
-    installedAt: string;
-}
-export interface InstalledPluginsManifest {
-    version: 1;
-    plugins: MarketplaceCatalogEntry[];
-}
 export interface MarketplaceLogger {
     info(msg: string): void;
     warn(msg: string): void;
 }
-/**
- * Resolve the executable + argv for an npm invocation. The packaged desktop app is usually the ONLY
- * Node/npm on a terminal user's machine, so `execFileAsync("npm", …)` fails there with "'npm' is not
- * recognized". When the desktop bridge is present we run the bundled npm as `AstraClaw.exe npm-cli.js …`
- * with ELECTRON_RUN_AS_NODE=1 (via electronNpmEnv); in dev / CI / server / tests the bridge is null and
- * we fall back to the system `npm` unchanged. Same routing as the agent-install runner.
- *
- * Note: electronNpmEnv pins npm_config_prefix to the GLOBAL prefix only — it does not affect the local
- * `npm install --production` this module runs inside each extracted plugin dir.
- */
+export interface StageMarketplaceNpmPluginRequest {
+    specifier: string;
+    version?: string;
+    /** Existing directory allocated and owned by the gateway. */
+    stageDir: string;
+}
+export interface StagedMarketplacePlugin {
+    name: string;
+    version: string;
+    contentDir: string;
+}
+type ExecResult = {
+    stdout: string;
+    stderr: string;
+};
+type ExecFile = (file: string, args: string[], options: Record<string, unknown>) => Promise<ExecResult>;
+export interface MarketplaceComputeDeps {
+    resolveNpm?: () => ElectronNpm | null;
+    execFile?: ExecFile;
+}
 export declare function resolveNpmExec(bridge: ElectronNpm | null, args: string[]): {
     file: string;
     argv: string[];
     env?: NodeJS.ProcessEnv;
 };
-/**
- * Load plugins from cache only (no network). Fast startup path.
- * CC parity: loadAllPluginsCacheOnly()
- */
-export declare function loadCachedPlugins(): string[];
-/**
- * Install/update marketplace plugins and return their local paths.
- * CC parity: loadAllPluginsWithDynamic()
- */
-export declare function installMarketplacePlugins(config: MarketplaceConfig, log: MarketplaceLogger): Promise<string[]>;
-/**
- * Get the marketplace config from user settings.
- * Reads ~/.qlogicagent/profiles/<owner>/marketplace.json
- */
-export declare function loadMarketplaceConfig(): MarketplaceConfig | null;
-/**
- * Combine local plugin dirs + marketplace plugin dirs for PluginLoader.
- * CC parity: loadAllPlugins() merges session + marketplace + builtin.
- */
-export declare function resolveAllPluginDirs(localDirs: string[], log: MarketplaceLogger): Promise<string[]>;
+/** Download and materialize one npm plugin strictly inside the supplied stage. */
+export declare function stageMarketplaceNpmPlugin(request: StageMarketplaceNpmPluginRequest, log: MarketplaceLogger, deps?: MarketplaceComputeDeps): Promise<StagedMarketplacePlugin>;
+export {};

package/dist/types/skills/tools/media-understand-tool.d.ts

@@ -0,0 +1,28 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const IMAGE_UNDERSTAND_TOOL_NAME: "image_understand";
+export declare const VIDEO_UNDERSTAND_TOOL_NAME: "video_understand";
+export interface MediaUnderstandToolParams {
+    query?: string;
+    /** The URL field name varies per tool (image_url / video_url), so it's read via the index. */
+    [key: string]: unknown;
+}
+/** What the injected backend returns for one understanding call. */
+export interface MediaUnderstandOutcome {
+    /** The model's answer/description (empty ⇔ nothing usable came back — see `failure`). */
+    text: string;
+    /** Why `text` is empty: "fetch_failed" (medium never reached the model) / "stream_error" /
+     * "empty_output" (model saw it, said nothing) / "no_model" (purpose unbound). undefined ⇔ success. */
+    failure?: string;
+    /** Input tokens billed, if known (diagnostic — a near-zero value on a media request corroborates fetch_failed). */
+    promptTokens?: number;
+    /** The resolved understanding model id, for the tool details. */
+    model?: string;
+}
+export interface MediaUnderstandToolDeps {
+    understand(params: {
+        url: string;
+        query?: string;
+    }): Promise<MediaUnderstandOutcome>;
+}
+export declare function createImageUnderstandTool(deps: MediaUnderstandToolDeps): PortableTool<MediaUnderstandToolParams>;
+export declare function createVideoUnderstandTool(deps: MediaUnderstandToolDeps): PortableTool<MediaUnderstandToolParams>;

package/dist/types/skills/tools/preview-browser-tool.d.ts

@@ -0,0 +1,136 @@
+import type { PortableTool } from "../portable-tool.js";
+import { type PreviewBrowserDriveResult, type PreviewBrowserToolParams } from "../../host-contract/index.js";
+export { PREVIEW_BROWSER_ACTIONS } from "../../host-contract/index.js";
+export type { PreviewBrowserAction, PreviewBrowserDriveResult, PreviewBrowserToolParams, } from "../../host-contract/index.js";
+export declare const PREVIEW_BROWSER_TOOL_NAME: "preview_browser";
+export interface PreviewBrowserToolDeps {
+    /**
+     * Drive the host-side preview view for one action. The host renders/executes it and
+     * returns text and/or a screenshot. If the host is not connected or the action fails,
+     * it returns `{ error }` (never silently empty). `signal` aborts an in-flight action.
+     */
+    drive(params: PreviewBrowserToolParams, signal?: AbortSignal): Promise<PreviewBrowserDriveResult>;
+}
+export declare const PREVIEW_BROWSER_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["navigate", "snapshot", "click", "type", "screenshot", "console", "network"];
+            readonly description: string;
+        };
+        readonly url: {
+            readonly type: "string";
+            readonly description: "URL to open. Required for action 'navigate'.";
+        };
+        readonly ref: {
+            readonly type: "string";
+            readonly description: "aria-ref of the target element, taken from a prior 'snapshot'. Required for 'click' and 'type'.";
+        };
+        readonly text: {
+            readonly type: "string";
+            readonly description: "Text to type into the element. Required for action 'type'.";
+        };
+        readonly submit: {
+            readonly type: "boolean";
+            readonly description: "For 'type': press Enter after typing to submit. Default false.";
+        };
+        readonly viewId: {
+            readonly type: "string";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["action"];
+    readonly oneOf: readonly [{
+        readonly type: "object";
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly const: "navigate";
+            };
+            readonly url: {
+                readonly type: "string";
+                readonly description: "URL to open.";
+            };
+            readonly viewId: {
+                type: "string";
+                description: string;
+            };
+        };
+        readonly required: readonly ["action", "url"];
+        readonly additionalProperties: false;
+    }, {
+        readonly type: "object";
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly const: "snapshot";
+            };
+            readonly viewId: {
+                type: "string";
+                description: string;
+            };
+        };
+        readonly required: readonly ["action"];
+        readonly additionalProperties: false;
+    }, {
+        readonly type: "object";
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly const: "click";
+            };
+            readonly ref: {
+                readonly type: "string";
+                readonly description: "aria-ref of the target element.";
+            };
+            readonly viewId: {
+                type: "string";
+                description: string;
+            };
+        };
+        readonly required: readonly ["action", "ref"];
+        readonly additionalProperties: false;
+    }, {
+        readonly type: "object";
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly const: "type";
+            };
+            readonly ref: {
+                readonly type: "string";
+                readonly description: "aria-ref of the target element.";
+            };
+            readonly text: {
+                readonly type: "string";
+                readonly description: "Text to type into the element.";
+            };
+            readonly submit: {
+                readonly type: "boolean";
+                readonly description: "Press Enter after typing. Default false.";
+            };
+            readonly viewId: {
+                type: "string";
+                description: string;
+            };
+        };
+        readonly required: readonly ["action", "ref", "text"];
+        readonly additionalProperties: false;
+    }, ...{
+        type: "object";
+        properties: {
+            action: {
+                type: "string";
+                const: "screenshot" | "console" | "network";
+            };
+            viewId: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: readonly ["action"];
+        additionalProperties: false;
+    }[]];
+};
+export declare function createPreviewBrowserTool(deps: PreviewBrowserToolDeps): PortableTool<PreviewBrowserToolParams>;

package/dist/types/skills/tools/shell/task-output.d.ts

@@ -25,7 +25,16 @@ export declare class TaskOutput {
     writeStdout(data: string): void;
     /** Write stderr data (pipe mode). */
     writeStderr(data: string): void;
-    /** Get captured stdout. For file mode, reads from disk. */
+    /**
+     * Get captured stdout. For file mode, reads from disk.
+     *
+     * This is the single chokepoint every consumer of a finished command's output flows through —
+     * the foreground result (ShellCommand.result) and the background-completed result (the same
+     * ShellCommand handle read by BackgroundTaskManager). Sanitizing CLIXML here (a guarded no-op
+     * for bash/clean output) is what unifies foreground and background exec: neither surface sees raw
+     * `#< CLIXML <Objs>…` noise. `#outputFileSize` tracks the RAW on-disk bytes (drives file-redundancy
+     * cleanup), so it is measured before sanitizing.
+     */
     getStdout(): Promise<string>;
     /** Get captured stderr. In file mode stderr is interleaved with stdout. */
     getStderr(): string;

package/dist/types/skills/tools/skill-tool.d.ts

@@ -114,7 +114,7 @@ export interface SkillManageResult {
 }
 export interface SkillToolDeps {
     /** List all available skills (Layer 0 metadata). */
-    listSkills(): WorkspaceSkill[];
+    listSkills(): Promise<WorkspaceSkill[]>;
     /** List skills with full detail (for skills_list). */
     listSkillsFull(category?: string): Promise<SkillListOutput>;
     /** Read skill content (Layer 1 instructions). */

package/dist/types/skills/web-search/brave-source.d.ts

@@ -1,2 +1,3 @@
 import type { SourceProvider } from "../../runtime/ports/source-provider.js";
-export declare function createBraveSource(): SourceProvider;
+import { type WebTunableEnvironment, type WebTunableSnapshotResolver } from "./web-tunable-resolver.js";
+export declare function createBraveSource(resolveTunables: WebTunableSnapshotResolver, env?: WebTunableEnvironment): SourceProvider;

package/dist/types/skills/web-search/crawl4ai-extractor.d.ts

@@ -1,3 +1,4 @@
+import { type WebTunableEnvironment, type WebTunableSnapshotResolver } from "./web-tunable-resolver.js";
 export interface ExtractedContent {
     content: string;
     title?: string;
@@ -10,6 +11,6 @@ export interface Crawl4aiExtractor {
         signal?: AbortSignal;
     }): Promise<ExtractedContent | null>;
     /** 是否已配置 base url(诊断用)。 */
-    isConfigured(): boolean;
+    isConfigured(): Promise<boolean>;
 }
-export declare function createCrawl4aiExtractor(): Crawl4aiExtractor;
+export declare function createCrawl4aiExtractor(resolveTunables: WebTunableSnapshotResolver, env?: WebTunableEnvironment): Crawl4aiExtractor;

package/dist/types/skills/web-search/exa-source.d.ts

@@ -1,2 +1,3 @@
 import type { SourceProvider } from "../../runtime/ports/source-provider.js";
-export declare function createExaSource(): SourceProvider;
+import { type WebTunableEnvironment, type WebTunableSnapshotResolver } from "./web-tunable-resolver.js";
+export declare function createExaSource(resolveTunables: WebTunableSnapshotResolver, env?: WebTunableEnvironment): SourceProvider;

package/dist/types/skills/web-search/search-svc-source.d.ts

@@ -1,4 +1,5 @@
 import type { SourceProvider } from "../../runtime/ports/source-provider.js";
-/** 解析 search-svc base url:settings tunables → 环境变量。 */
-export declare function resolveSearchSvcBaseUrl(): Promise<string | undefined>;
-export declare function createSearchSvcSource(): SourceProvider;
+import { type WebTunableEnvironment, type WebTunableSnapshotResolver } from "./web-tunable-resolver.js";
+/** 解析 search-svc base url:host tunable 非空优先，空 override 才回退环境变量。 */
+export declare function resolveSearchSvcBaseUrl(resolveTunables: WebTunableSnapshotResolver, env?: WebTunableEnvironment): Promise<string | undefined>;
+export declare function createSearchSvcSource(resolveTunables: WebTunableSnapshotResolver, env?: WebTunableEnvironment): SourceProvider;

package/dist/types/skills/web-search/searxng-source.d.ts

@@ -1,2 +1,4 @@
 import type { SourceProvider } from "../../runtime/ports/source-provider.js";
-export declare function createSearxngSource(): SourceProvider;
+import { type WebTunableEnvironment, type WebTunableSnapshotResolver } from "./web-tunable-resolver.js";
+/** 解析 SearXNG base url:host tunable 非空优先，空 override 才回退环境变量。 */
+export declare function createSearxngSource(resolveTunables: WebTunableSnapshotResolver, env?: WebTunableEnvironment): SourceProvider;

package/dist/types/skills/web-search/serper-source.d.ts

@@ -1,2 +1,3 @@
 import type { SourceProvider } from "../../runtime/ports/source-provider.js";
-export declare function createSerperSource(): SourceProvider;
+import { type WebTunableEnvironment, type WebTunableSnapshotResolver } from "./web-tunable-resolver.js";
+export declare function createSerperSource(resolveTunables: WebTunableSnapshotResolver, env?: WebTunableEnvironment): SourceProvider;

package/dist/types/skills/web-search/source-factory.d.ts

@@ -1,5 +1,6 @@
 import type { SourceProvider } from "../../runtime/ports/source-provider.js";
+import type { WebTunableEnvironment, WebTunableSnapshotResolver } from "./web-tunable-resolver.js";
 /**
  * 组装 web_search 的 L0 数据源集合(运行期各源自行懒解析配置细节)。
  */
-export declare function buildWebSearchSources(): SourceProvider[];
+export declare function buildWebSearchSources(resolveTunables: WebTunableSnapshotResolver, env?: WebTunableEnvironment): SourceProvider[];

package/dist/types/skills/web-search/web-tunable-resolver.d.ts

@@ -0,0 +1,16 @@
+import { type TunableDefaults } from "../../tunables.js";
+export type WebTunableSnapshot = Readonly<TunableDefaults>;
+export type WebTunableSnapshotResolver = () => Promise<WebTunableSnapshot>;
+export type WebTunableEnvironment = Record<string, string | undefined>;
+/**
+ * Build one lazy snapshot for one web-tool invocation/search. The loader is not touched during
+ * synchronous registration; the first consumer starts it and all sibling consumers reuse the
+ * exact in-flight/settled Promise. Rejections are cached too so a host failure cannot degrade into
+ * a later env/local fallback inside the same invocation. Callers construct a fresh resolver for
+ * the next invoke so host updates are hot and a rejected request can retry.
+ */
+export declare function createWebTunableSnapshotResolver(loadOverrides: () => Promise<Record<string, unknown>>): WebTunableSnapshotResolver;
+/** Explicit standalone-server mode: shared defaults + source-specific env fallback, no local store. */
+export declare function createEnvOnlyWebTunableResolver(): WebTunableSnapshotResolver;
+/** Non-empty host override wins; an empty shared-default/override alone permits the legacy env fallback. */
+export declare function resolveWebTunableString(resolveSnapshot: WebTunableSnapshotResolver, key: keyof Pick<TunableDefaults, "exaApiKey" | "braveApiKey" | "serperApiKey" | "searxngBaseUrl" | "searchSvcBaseUrl" | "crawl4aiBaseUrl">, envName: string, env: WebTunableEnvironment): Promise<string | undefined>;

package/dist/types/test-support/global-home-setup.d.ts

@@ -0,0 +1,2 @@
+export declare function setupGlobalTestHome(): () => void;
+export default function globalSetup(): () => void;