@steerable/agent-shell 0.6.21 → 0.6.22

package/README.md

@@ -0,0 +1,34 @@
+# @steerable/agent-shell
+
+Product-neutral Electron and headless HTTP host for Steerable Framework.
+
+## BS composition
+
+Products can register an `AuthProvider` from `@steerable/agent-shell/auth`
+before starting the host. A registered provider authenticates every
+`/api/v2/*` and `/host/*` request and supplies the request `Principal`.
+Without a provider, the host retains its loopback Host check and
+per-process Bearer token.
+
+Use `startBsHost` from `@steerable/agent-shell/server/start` to embed the BS
+host. Its options support host and port selection, a fixed Bearer token, and
+ordered middleware. Middleware returns `pass` to continue or `handled` to
+short-circuit. The returned handle owns shutdown of both HTTP and runtime
+services.
+
+## Storage drivers
+
+Storage drivers register during product composition and initialize after all
+scenario-pack migrations and seeds are registered. `initializeStorage()` must
+complete before `getScopedStore(scope)` or `getPackDbAccess(scope)` is used.
+The default `SqliteStorageDriver` preserves the local database path, migration
+sequence, seed behavior, and write lease.
+
+Host repositories use the async `ScopedStore` API. Scenario packs receive
+`PackDbAccess`, which carries `tenantId` and `userId` and does not expose the
+driver connection. Because arbitrary SQL cannot be rewritten safely,
+pack repositories must include both ownership columns in every statement;
+the SQLite and MySQL access objects reject missing or mismatched ownership,
+and pack boundary checks enforce the same requirement before runtime.
+
+License: Apache-2.0.

package/dist/auth/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Product-neutral authenticated identity attached to one local-backend request.
+ */
+export interface Principal {
+    id: string;
+    tenantId: string;
+    displayName: string;
+    email: string | null;
+    roles: readonly string[];
+    isAdmin: boolean;
+}
+export type AuthDecision = {
+    ok: true;
+    principal: Principal;
+} | {
+    ok: false;
+    status: 401 | 403;
+    body?: unknown;
+};
+/**
+ * Authentication extension point for BS deployments.
+ *
+ * Implementations own all interpretation and validation of request headers,
+ * including cookies and any identity assertions added by a trusted proxy.
+ */
+export interface AuthProvider {
+    readonly id: string;
+    authenticate(headers: Readonly<Record<string, string | string[] | undefined>>): Promise<AuthDecision>;
+    describeSelf(principal: Principal): Promise<unknown>;
+}
+/**
+ * Registers the process-wide provider before the BS host starts.
+ *
+ * @returns A disposer that removes this provider if it is still active.
+ */
+export declare function registerAuthProvider(provider: AuthProvider): () => void;
+/** Returns the provider registered by the product composition root, if any. */
+export declare function getAuthProvider(): AuthProvider | null;

package/dist/auth/index.js

@@ -0,0 +1,20 @@
+let activeProvider = null;
+/**
+ * Registers the process-wide provider before the BS host starts.
+ *
+ * @returns A disposer that removes this provider if it is still active.
+ */
+export function registerAuthProvider(provider) {
+    if (activeProvider) {
+        throw new Error(`[auth] provider already registered: ${activeProvider.id}`);
+    }
+    activeProvider = provider;
+    return () => {
+        if (activeProvider === provider)
+            activeProvider = null;
+    };
+}
+/** Returns the provider registered by the product composition root, if any. */
+export function getAuthProvider() {
+    return activeProvider;
+}

package/dist/host/pack-assembly.d.ts

@@ -14,12 +14,12 @@
  * 消费 handle.httpRoutes——包的入口面贡献由宿主循环驱动，宿主代码里
  * 不出现任何包名。
  */
-import type Database from 'better-sqlite3';
 import type { HttpRouteContribution, IpcContribution, ToolContribution } from '../scenario/pack.js';
+import type { PackDbAccess } from '../storage/driver.js';
 /** 宿主注入包的装配能力面。包不 import 宿主装配模块，全部经回调注入。 */
 export interface PackAssemblyDeps {
-    /** 宿主借出的同一个 SQLite 连接（包只读写自己声明的包前缀表）。 */
-    readonly db: Database.Database;
+    /** Scope-bound database access; the underlying driver connection is hidden. */
+    readonly packDb: PackDbAccess;
     /** 模型可见工具面（与普通回合同源）。 */
     readonly listTools: () => {
         name: string;
@@ -27,10 +27,10 @@ export interface PackAssemblyDeps {
         inputSchema: unknown;
     }[];
     /** chatId → 绑定项目（无项目对话返回 null）。与 router.resolveChatProject 同源。 */
-    readonly resolveChatProject: (chatId: string) => {
+    readonly resolveChatProject: (chatId: string) => Promise<{
         name: string;
         folderPath: string;
-    } | null;
+    } | null>;
     /** 面向全部用户面的事件广播（CS=所有窗口 IPC，BS=SSE 总线）。 */
     readonly broadcast: (channel: string, payload: unknown) => void;
     /** 工具贡献注册口（toolRouter.registerToolContributions 的收窄面）。 */
@@ -46,7 +46,7 @@ export interface PackAssemblyDeps {
         totalTokens: number;
         cachedPromptTokens?: number;
         costUsd?: number | null;
-    }) => void;
+    }) => Promise<void>;
     /** 行为洞察（与主对话同款 turn 事件）。 */
     readonly recordInsight: (input: {
         chatId: string;
@@ -57,7 +57,7 @@ export interface PackAssemblyDeps {
         toolNames?: unknown;
         userText?: string;
         assistantText?: string;
-    }) => void;
+    }) => Promise<void>;
     /** 装配期日志行（进宿主日志）。 */
     readonly onLog: (line: string) => void;
 }

package/dist/host/runtime.d.ts

@@ -20,10 +20,13 @@ import { ProjectRegistry } from '../project-registry.js';
 import { LocalBackendRouter } from '../local-backend/router.js';
 import { WorktreeService } from '../local-backend/worktree-service.js';
 import { TaskService } from '../local-backend/task-service.js';
+import { type TenantScope } from '../storage/driver.js';
 import { createApprovalBridge } from '../sidecar/reverse-approval.js';
 import { createAskUserBridge } from '../sidecar/reverse-ask-user.js';
 import { type PackAssemblyHandle } from './pack-assembly.js';
 export interface HostRuntimeOptions {
+    /** Storage ownership for this host process. Defaults to local personal use. */
+    scope?: TenantScope;
     /** 面向全部用户面的事件广播（CS=所有窗口 IPC，BS=SSE 总线）。 */
     broadcast: (channel: string, payload: unknown) => void;
     /**
@@ -42,6 +45,7 @@ export interface HostRuntimeOptions {
     taskSweepReason: string;
 }
 export interface HostRuntime {
+    store: import('../storage/scoped-store.js').ScopedStore;
     localExecutor: LocalExecutor;
     localScriptRegistry: LocalScriptRegistry;
     terminalManager: TerminalManager;
@@ -62,8 +66,8 @@ export interface HostRuntime {
      * 不阻塞调用方的就绪路径（sidecar python import 慢，竞速的回合由
      * router 回退处理）。
      */
-    start(): void;
+    start(): Promise<void>;
     /** 关停：杀终端、停 mock、关 sidecar。 */
     shutdown(): Promise<void>;
 }
-export declare function createHostRuntime(options: HostRuntimeOptions): HostRuntime;
+export declare function createHostRuntime(options: HostRuntimeOptions): Promise<HostRuntime>;

package/dist/host/runtime.js

@@ -20,7 +20,7 @@ import { ProjectRegistry } from '../project-registry.js';
 import { LocalBackendRouter } from '../local-backend/router.js';
 import { WorktreeService } from '../local-backend/worktree-service.js';
 import { TaskService } from '../local-backend/task-service.js';
-import { localStore } from '../storage/index.js';
+import { LOCAL_SCOPE, closeStorage, getPackDbAccess, getScopedStore, initializeStorage, } from '../storage/driver.js';
 import { createApprovalBridge } from '../sidecar/reverse-approval.js';
 import { createAskUserBridge } from '../sidecar/reverse-ask-user.js';
 import { startHostSidecar, shutdownHostSidecar } from '../sidecar/boot.js';
@@ -29,18 +29,52 @@ import { createJsonStore } from '../json-store.js';
 import { bindWorkspaceSkillRoots } from '../local-backend/skill-loader.js';
 import { getChatAttachmentsDir } from '../attachments.js';
 import { recordInsightTurn } from '../insights/record.js';
+import { llmService } from '../llm/index.js';
 import { getPackAssemblies, } from './pack-assembly.js';
-export function createHostRuntime(options) {
+export async function createHostRuntime(options) {
     const { broadcast, hasWindow, onLog } = options;
     const broadcastMain = options.broadcastMain ?? broadcast;
+    await initializeStorage();
+    const scope = options.scope ?? LOCAL_SCOPE;
+    const defaultStore = getScopedStore(scope);
+    let localBackendRouter;
+    const activeScope = () => localBackendRouter?.activeStore.scope ?? scope;
+    const packDb = {
+        get scope() {
+            return activeScope();
+        },
+        get(sql, params) {
+            return getPackDbAccess(activeScope()).get(sql, params);
+        },
+        all(sql, params) {
+            return getPackDbAccess(activeScope()).all(sql, params);
+        },
+        run(sql, params) {
+            return getPackDbAccess(activeScope()).run(sql, params);
+        },
+        exec(sql) {
+            return getPackDbAccess(activeScope()).exec(sql);
+        },
+        transaction(operation) {
+            return getPackDbAccess(activeScope()).transaction(() => operation(packDb));
+        },
+    };
     const localExecutor = new LocalExecutor();
     // 恢复设置界面里配置的"命令默认超时"（保存时由 local-backend router 即时
     // 生效，这里负责进程重启后的恢复）。
     {
-        const persistedLlmSettings = localStore.getLlmSettings();
+        const persistedLlmSettings = await defaultStore.getLlmSettings();
         setDefaultExecTimeoutMs(persistedLlmSettings?.execTimeoutSeconds
             ? persistedLlmSettings.execTimeoutSeconds * 1000
             : null);
+        llmService.initialize(persistedLlmSettings ?? {
+            provider: 'ollama',
+            model: 'llama3.1:8b',
+            baseUrl: 'http://127.0.0.1:11434',
+            temperature: 0.3,
+        }, {
+            setLlmSettings: (settings) => defaultStore.setLlmSettings(settings),
+        });
     }
     const localScriptRegistry = new LocalScriptRegistry();
     const terminalManager = new TerminalManager();
@@ -78,8 +112,8 @@ export function createHostRuntime(options) {
     // 4.6a/4.6b：跨 turn 后台任务 + git worktree 隔离。任务流由宿主独立驱动
     // （不绑父 turn 生命周期，见 task-service.ts 模块头）；终态经广播推到
     // 用户面任务面板。
-    const resolveChatProjectRoot = (chatId) => {
-        const projectId = localStore.getChat(chatId)?.projectId;
+    const resolveChatProjectRoot = async (chatId) => {
+        const projectId = (await defaultStore.getChat(chatId))?.projectId;
         if (!projectId)
             return null;
         const project = projectRegistry.get(projectId);
@@ -91,20 +125,19 @@ export function createHostRuntime(options) {
     const packHandles = new Map();
     {
         const packDeps = {
-            db: localStore.getPackDb(),
+            packDb,
             listTools: () => toolRouter.listModelSchemas(),
             resolveChatProject: resolveChatProjectRoot,
             broadcast,
             registerTools: (tools) => toolRouter.registerToolContributions(tools),
-            recordUsage: (input) => localStore.recordUsageEvent(input),
-            recordInsight: (input) => recordInsightTurn(input),
+            recordUsage: (input) => (localBackendRouter?.activeStore ?? defaultStore).recordUsageEvent(input),
+            recordInsight: (input) => recordInsightTurn(localBackendRouter?.activeStore ?? defaultStore, input),
             onLog,
         };
         // 包迁移容错应用（3.2）：包的 import 链可能经 llm/index 等模块提前
         // 触发 storage 单例构造（ESM 深度优先，active.ts 的注册体后于链上
         // 单例求值）——构造时注册表尚空，此处（装配前）补上已注册包迁移。
         // 幂等（按包 id 去重），注册表为空时零开销。
-        localStore.applyPackMigrations();
         for (const [packId, assemble] of getPackAssemblies()) {
             const handle = assemble(packDeps);
             if (handle)
@@ -113,14 +146,18 @@ export function createHostRuntime(options) {
     }
     const worktreeService = new WorktreeService({ resolveProject: resolveChatProjectRoot });
     const taskService = new TaskService({
-        store: localStore,
+        store: () => localBackendRouter?.activeStore ?? defaultStore,
         toolRouter,
         worktreeService,
         resolveChatProject: resolveChatProjectRoot,
         broadcast,
     });
     toolRouter.setTaskServices({ taskService, worktreeService });
-    const localBackendRouter = new LocalBackendRouter(toolRouter, {
+    localBackendRouter = new LocalBackendRouter(toolRouter, {
+        store: defaultStore,
+        resolveStore: (principal) => principal
+            ? getScopedStore({ tenantId: principal.tenantId, userId: principal.id })
+            : defaultStore,
         taskService,
         broadcast: broadcastMain,
     });
@@ -137,6 +174,7 @@ export function createHostRuntime(options) {
     });
     let started = false;
     return {
+        store: defaultStore,
         localExecutor,
         localScriptRegistry,
         terminalManager,
@@ -150,13 +188,13 @@ export function createHostRuntime(options) {
         approvalBridge,
         askUserBridge,
         maybeExecInTerminal,
-        start() {
+        async start() {
             if (started)
                 return;
             started = true;
             // 4.6a：上次进程崩溃/强杀留下的 running 任务不是真相——任务流随进程
             // 一起死了，启动时落成 failed，任务面板据此显示"重启中断"。
-            const sweptTasks = localStore.failRunningTasks(options.taskSweepReason);
+            const sweptTasks = await defaultStore.failRunningTasks(options.taskSweepReason);
             if (sweptTasks > 0) {
                 onLog(`[task] swept ${sweptTasks} stale running task(s)`);
             }
@@ -164,8 +202,9 @@ export function createHostRuntime(options) {
             // Not awaited: sidecar boot (python import) must not delay readiness.
             // A turn that races the boot falls back for that turn only.
             void startHostSidecar({
+                store: defaultStore,
                 toolRouter,
-                resolveProjectRoot: (chatId) => localBackendRouter.resolveChatProject(chatId)?.folderPath ?? null,
+                resolveProjectRoot: async (chatId) => (await localBackendRouter.resolveChatProject(chatId))?.folderPath ?? null,
                 // 项目模式下文件读写被围栏在项目目录内；会话附件目录是额外放行的
                 // 只读根，保证用户上传的文件即使在项目会话里也能被 agent 读回。
                 resolveAdditionalReadRoots: (chatId) => [getChatAttachmentsDir(chatId)],
@@ -201,6 +240,7 @@ export function createHostRuntime(options) {
                 await handle.dispose?.();
             }
             await shutdownHostSidecar();
+            await closeStorage();
         },
     };
 }

package/dist/insights/flush.d.ts

@@ -1,10 +1,11 @@
+import type { ScopedStore } from '../storage/scoped-store.js';
 export declare function insightsNetworkDisabled(): boolean;
-export declare function buildInsightsExportPayload(): Record<string, unknown>;
+export declare function buildInsightsExportPayload(store: ScopedStore): Promise<Record<string, unknown>>;
 export declare function postInsightsJson(url: string, body: unknown): Promise<boolean>;
-export declare function flushInsightsOutbox(): Promise<{
+export declare function flushInsightsOutbox(store: ScopedStore): Promise<{
     uploaded: number;
     skipped: number;
     failed: number;
 }>;
-export declare function uploadInsightsBundle(): Promise<boolean>;
-export declare function scheduleInsightsFlush(): void;
+export declare function uploadInsightsBundle(store: ScopedStore): Promise<boolean>;
+export declare function scheduleInsightsFlush(store: ScopedStore): void;

package/dist/insights/flush.js

@@ -3,7 +3,6 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getBrand } from '../brand.js';
 import { resolveInsightsApiBase, rowsEligibleForAutoUpload, } from '../storage/insights-settings.js';
-import { localStore } from '../storage/index.js';
 const FLUSH_TIMEOUT_MS = 8_000;
 const MAX_BATCH = 20;
 export function insightsNetworkDisabled() {
@@ -41,10 +40,10 @@ function clientMeta(settings) {
         appVersion: detectAppVersion(),
     };
 }
-export function buildInsightsExportPayload() {
-    const settings = localStore.ensureInsightsSettings();
+export async function buildInsightsExportPayload(store) {
+    const settings = await store.ensureInsightsSettings();
     return {
-        ...localStore.exportInsightsBundle(),
+        ...await store.exportInsightsBundle(),
         ...clientMeta(settings),
     };
 }
@@ -84,12 +83,12 @@ function pathForKind(kind) {
         return '/api/v2/agent-insights/turns';
     return '/api/v2/agent-insights/profile';
 }
-export async function flushInsightsOutbox() {
+export async function flushInsightsOutbox(store) {
     if (insightsNetworkDisabled()) {
         return { uploaded: 0, skipped: 0, failed: 0 };
     }
-    const settings = localStore.ensureInsightsSettings();
-    const pending = localStore.listInsightOutbox({ uploaded: false, limit: MAX_BATCH });
+    const settings = await store.ensureInsightsSettings();
+    const pending = await store.listInsightOutbox({ uploaded: false, limit: MAX_BATCH });
     const { upload, skipped } = rowsEligibleForAutoUpload(settings, pending);
     let uploaded = 0;
     let failed = 0;
@@ -105,22 +104,22 @@ export async function flushInsightsOutbox() {
             clientEventId: row.id,
         });
         if (ok) {
-            localStore.markInsightUploaded(row.id);
+            await store.markInsightUploaded(row.id);
             uploaded += 1;
         }
         else {
-            localStore.markInsightUploadError(row.id, 'upload_failed');
+            await store.markInsightUploadError(row.id, 'upload_failed');
             failed += 1;
         }
     }
     return { uploaded, skipped, failed };
 }
-export async function uploadInsightsBundle() {
+export async function uploadInsightsBundle(store) {
     if (insightsNetworkDisabled()) {
         return false;
     }
-    const settings = localStore.ensureInsightsSettings();
-    const bundle = buildInsightsExportPayload();
+    const settings = await store.ensureInsightsSettings();
+    const bundle = await buildInsightsExportPayload(store);
     const base = resolveInsightsApiBase(settings, process.env.DEEPPATH_INSIGHTS_API_BASE);
     if (!base)
         return false;
@@ -128,12 +127,12 @@ export async function uploadInsightsBundle() {
     if (ok) {
         const records = Array.isArray(bundle.records) ? bundle.records : [];
         for (const row of records)
-            localStore.markInsightUploaded(row.id);
+            await store.markInsightUploaded(row.id);
     }
     return ok;
 }
-export function scheduleInsightsFlush() {
-    void flushInsightsOutbox().catch((err) => {
+export function scheduleInsightsFlush(store) {
+    void flushInsightsOutbox(store).catch((err) => {
         console.warn('[insights] flush crashed', err);
     });
 }

package/dist/insights/record.d.ts

@@ -1,5 +1,6 @@
-export declare function recordInsightEvent(eventName: string, properties?: Record<string, unknown>): void;
-export declare function recordInsightTurn(input: {
+import type { ScopedStore } from '../storage/scoped-store.js';
+export declare function recordInsightEvent(store: ScopedStore, eventName: string, properties?: Record<string, unknown>): Promise<void>;
+export declare function recordInsightTurn(store: ScopedStore, input: {
     chatId: string;
     mode?: string;
     modelId?: string | null;
@@ -8,10 +9,10 @@ export declare function recordInsightTurn(input: {
     toolNames?: unknown;
     userText?: string;
     assistantText?: string;
-}): void;
-export declare function recordInsightProfile(profile: {
+}): Promise<void>;
+export declare function recordInsightProfile(store: ScopedStore, profile: {
     displayName?: string;
     email?: string;
     company?: string;
     note?: string;
-}): void;
+}): Promise<void>;

package/dist/insights/record.js

@@ -1,18 +1,17 @@
 import { redactInsightText, toolNamesOnly } from '../storage/insights-redact.js';
-import { localStore } from '../storage/index.js';
 import { scheduleInsightsFlush } from './flush.js';
-export function recordInsightEvent(eventName, properties = {}) {
+export async function recordInsightEvent(store, eventName, properties = {}) {
     try {
-        localStore.enqueueInsight('event', { eventName, properties });
-        scheduleInsightsFlush();
+        await store.enqueueInsight('event', { eventName, properties });
+        scheduleInsightsFlush(store);
     }
     catch (err) {
         console.warn('[insights] event enqueue failed', err);
     }
 }
-export function recordInsightTurn(input) {
+export async function recordInsightTurn(store, input) {
     try {
-        localStore.enqueueInsight('turn', {
+        await store.enqueueInsight('turn', {
             chatId: input.chatId,
             mode: input.mode === 'plan' ? 'plan' : 'agent',
             modelId: typeof input.modelId === 'string' ? input.modelId.slice(0, 128) : undefined,
@@ -22,21 +21,21 @@ export function recordInsightTurn(input) {
             userText: redactInsightText(input.userText, 4000),
             assistantText: redactInsightText(input.assistantText, 8000),
         });
-        scheduleInsightsFlush();
+        scheduleInsightsFlush(store);
     }
     catch (err) {
         console.warn('[insights] turn enqueue failed', err);
     }
 }
-export function recordInsightProfile(profile) {
+export async function recordInsightProfile(store, profile) {
     try {
-        localStore.enqueueInsight('profile', {
+        await store.enqueueInsight('profile', {
             displayName: redactInsightText(profile.displayName, 128),
             email: redactInsightText(profile.email, 191),
             company: redactInsightText(profile.company, 191),
             note: redactInsightText(profile.note, 500),
         });
-        scheduleInsightsFlush();
+        scheduleInsightsFlush(store);
     }
     catch (err) {
         console.warn('[insights] profile enqueue failed', err);

package/dist/llm/index.d.ts

@@ -1,10 +1,14 @@
-import { type LlmSettings } from '../storage/index.js';
+import type { LlmSettings, ScopedStore } from '../storage/index.js';
 import { getSidecarSupervisor, setSidecarSupervisor, setSidecarSupervisorPending, whenSidecarSupervisor } from '../sidecar/handle.js';
 export { getSidecarSupervisor, setSidecarSupervisor, setSidecarSupervisorPending, whenSidecarSupervisor };
 import type { LlmGenerateRequest, LlmGenerateResult, LlmGenerateStreamRequest } from './types.js';
 export declare class LlmService {
     private provider;
     private cachedConfigSignature;
+    private settings;
+    private store;
+    /** Initializes the synchronous runtime cache after storage has loaded. */
+    initialize(settings: LlmSettings, store: Pick<ScopedStore, 'setLlmSettings'>): void;
     listModels(): Promise<string[]>;
     generate(request: Omit<LlmGenerateRequest, 'model'> & {
         model?: string;
@@ -16,7 +20,7 @@ export declare class LlmService {
         model?: string;
     }): Promise<LlmGenerateResult>;
     getSettings(): LlmSettings;
-    setSettings(next: LlmSettings): LlmSettings;
+    setSettings(next: LlmSettings, store?: Pick<ScopedStore, "setLlmSettings"> | null): Promise<LlmSettings>;
     private getProvider;
 }
 export declare const llmService: LlmService;

package/dist/llm/index.js

@@ -1,4 +1,3 @@
-import { localStore } from '../storage/index.js';
 import { sidecarWireProvider } from '../storage/llm-settings.js';
 import { OllamaProvider } from './ollama.js';
 import { OpenAICompatProvider } from './openai-compat.js';
@@ -11,6 +10,15 @@ export { getSidecarSupervisor, setSidecarSupervisor, setSidecarSupervisorPending
 export class LlmService {
     provider = null;
     cachedConfigSignature = '';
+    settings = null;
+    store = null;
+    /** Initializes the synchronous runtime cache after storage has loaded. */
+    initialize(settings, store) {
+        this.settings = settings;
+        this.store = store;
+        this.provider = null;
+        this.cachedConfigSignature = '';
+    }
     async listModels() {
         const provider = this.getProvider();
         return provider.listModels();
@@ -51,15 +59,17 @@ export class LlmService {
         return result;
     }
     getSettings() {
-        return localStore.getLlmSettings() || {
-            provider: 'ollama',
-            model: 'llama3.1:8b',
-            baseUrl: 'http://127.0.0.1:11434',
-            temperature: 0.3,
-        };
+        if (!this.settings) {
+            throw new Error('LlmService must be initialized after storage');
+        }
+        return this.settings;
     }
-    setSettings(next) {
-        const saved = localStore.setLlmSettings(next);
+    async setSettings(next, store = this.store) {
+        if (!store) {
+            throw new Error('LlmService must be initialized after storage');
+        }
+        const saved = await store.setLlmSettings(next);
+        this.settings = saved;
         this.provider = null;
         this.cachedConfigSignature = '';
         return saved;

package/dist/local-backend/prompt-builder.d.ts

@@ -48,6 +48,11 @@ export interface BuildPromptOptions {
      * 仍然优先——模式级排除（plan 模式的执行类技能）不因勾选而失效。
      */
     pinnedSkillNames?: Iterable<string>;
+    /**
+     * 本轮自称。有绑定智能体时用智能体显示名，渲染技能正文 `{agentName}`；
+     * 未传则回落产品品牌 `brand.agentName`。
+     */
+    identityName?: string | null;
 }
 export interface BuiltPrompt {
     prompt: string;
@@ -84,11 +89,12 @@ export declare function conditionsFromTools(toolNames: Iterable<string>, autoHas
  */
 export declare function buildSystemPrompt(options?: BuildPromptOptions): Promise<BuiltPrompt>;
 /**
- * 品牌占位符变量：技能正文里的 `{agentName}` / `{brandDisplayName}` /
- * `{brandTagline}` 渲染为当前产品注入的品牌（brand.ts；未注入 = shell
- * 中性默认）。eager 系统提示词路径统一注入；包技能同理可用。
+ * 品牌/身份占位符：`{brandDisplayName}` / `{brandTagline}` 始终是产品品牌；
+ * `{agentName}` 有本轮智能体时用智能体显示名，否则回落 `brand.agentName`。
  */
-export declare function brandSkillVars(): Record<string, string>;
+export declare function brandSkillVars(options?: {
+    identityName?: string | null;
+}): Record<string, string>;
 /** 技能正文渲染:把 `{scripts}` 及额外占位符解析为绝对路径。 */
 export declare function renderSkillContent(m: SkillModule, vars?: Record<string, string>): string;
 /** 用户显式指定技能的优先级指令头，渲染在该技能内容之前。 */