@steerable/agent-shell 0.6.15

package/dist/storage/pack-migrations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 包迁移注册表 —— ScenarioPack 的存储槽位（0.3b）。
+ *
+ * `storage/index.ts` 的 `LocalStore` 单例在模块求值时即构造并跑 `migrate()`，
+ * 所以包迁移必须在任何 `storage/index.js` import 之前注册。入口
+ * （main.ts / server/index.ts）把 `packs/active.ts` 作为第一个 import
+ * 来保证这个顺序。
+ *
+ * 本模块刻意不 import `storage/index.js`，避免反向依赖。
+ */
+import type { MigrationContribution } from '../scenario/pack.js';
+interface RegisteredMigration {
+    packId: string;
+    migration: MigrationContribution;
+}
+/**
+ * 注册一个包的迁移贡献。重复注册同一包会抛错（组装期笔误，fail fast）。
+ */
+export declare function registerPackMigrations(packId: string, migration: MigrationContribution): void;
+/** 已注册的全部迁移，按注册顺序返回。 */
+export declare function getPackMigrations(): readonly RegisteredMigration[];
+export {};

package/dist/storage/pack-migrations.js

@@ -0,0 +1,24 @@
+/**
+ * 包迁移注册表 —— ScenarioPack 的存储槽位（0.3b）。
+ *
+ * `storage/index.ts` 的 `LocalStore` 单例在模块求值时即构造并跑 `migrate()`，
+ * 所以包迁移必须在任何 `storage/index.js` import 之前注册。入口
+ * （main.ts / server/index.ts）把 `packs/active.ts` 作为第一个 import
+ * 来保证这个顺序。
+ *
+ * 本模块刻意不 import `storage/index.js`，避免反向依赖。
+ */
+const registered = [];
+/**
+ * 注册一个包的迁移贡献。重复注册同一包会抛错（组装期笔误，fail fast）。
+ */
+export function registerPackMigrations(packId, migration) {
+    if (registered.some((r) => r.packId === packId)) {
+        throw new Error(`[pack-migrations] duplicate registration for pack: ${packId}`);
+    }
+    registered.push({ packId, migration });
+}
+/** 已注册的全部迁移，按注册顺序返回。 */
+export function getPackMigrations() {
+    return registered;
+}

package/dist/storage/pack-seeds.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 包智能体种子注册表 —— ScenarioPack 的种子槽位（0.3d）。
+ *
+ * 与 pack-migrations 同一模式：`LocalStore` 单例在模块求值时构造并跑
+ * `seedDefaults()`，所以种子必须在任何 `storage/index.js` import 之前
+ * 由 `packs/active.ts` 注册。
+ *
+ * 与迁移不同的一点：**未激活的包也要注册**（active=false）——已有库
+ * 里「从未定制过」的包内置智能体需要在包缺席的产品里归档，shell 只有
+ * 拿到种子数据才能识别「未定制」。
+ *
+ * 本模块刻意不 import `storage/index.js`，避免反向依赖。判定函数是纯
+ * 函数，单测直接覆盖（tests/pack-seeds.test.ts）。
+ */
+import type { AgentSeed } from '../scenario/pack.js';
+export interface PackAgentSeedRegistration {
+    packId: string;
+    seeds: readonly AgentSeed[];
+    /** 包在当前产品是否激活；未激活包的种子只跑「未定制则归档」。 */
+    active: boolean;
+}
+/** 注册一个包的智能体种子。重复注册同一包抛错（组装期笔误，fail fast）。 */
+export declare function registerPackAgentSeeds(packId: string, seeds: readonly AgentSeed[], active: boolean): void;
+/** 已注册的全部种子，按注册顺序返回。 */
+export declare function getPackAgentSeeds(): readonly PackAgentSeedRegistration[];
+/** chat_agents 行中种子判定需要的最小列。 */
+export interface AgentSeedRow {
+    name: string;
+    description: string | null;
+    role_prompt: string;
+    is_archived: number;
+}
+/** 命中任一历史代文案（提示词前缀匹配，描述缺省按当前代）。 */
+export declare function matchesPreviousIdentity(seed: AgentSeed, row: AgentSeedRow): boolean;
+/** 当前代或任一历史代全中 = 用户从未定制过这行内置智能体。 */
+export declare function isUntouchedSeed(seed: AgentSeed, row: AgentSeedRow): boolean;

package/dist/storage/pack-seeds.js

@@ -0,0 +1,42 @@
+/**
+ * 包智能体种子注册表 —— ScenarioPack 的种子槽位（0.3d）。
+ *
+ * 与 pack-migrations 同一模式：`LocalStore` 单例在模块求值时构造并跑
+ * `seedDefaults()`，所以种子必须在任何 `storage/index.js` import 之前
+ * 由 `packs/active.ts` 注册。
+ *
+ * 与迁移不同的一点：**未激活的包也要注册**（active=false）——已有库
+ * 里「从未定制过」的包内置智能体需要在包缺席的产品里归档，shell 只有
+ * 拿到种子数据才能识别「未定制」。
+ *
+ * 本模块刻意不 import `storage/index.js`，避免反向依赖。判定函数是纯
+ * 函数，单测直接覆盖（tests/pack-seeds.test.ts）。
+ */
+const registrations = [];
+/** 注册一个包的智能体种子。重复注册同一包抛错（组装期笔误，fail fast）。 */
+export function registerPackAgentSeeds(packId, seeds, active) {
+    if (registrations.some((r) => r.packId === packId)) {
+        throw new Error(`[pack-seeds] duplicate registration for pack: ${packId}`);
+    }
+    registrations.push({ packId, seeds, active });
+}
+/** 已注册的全部种子，按注册顺序返回。 */
+export function getPackAgentSeeds() {
+    return registrations;
+}
+/** 命中当前代文案：名字 + 描述全等、提示词全等。 */
+function matchesCurrent(seed, row) {
+    return (row.name === seed.name &&
+        (row.description ?? '') === (seed.description ?? '') &&
+        row.role_prompt === seed.rolePrompt);
+}
+/** 命中任一历史代文案（提示词前缀匹配，描述缺省按当前代）。 */
+export function matchesPreviousIdentity(seed, row) {
+    return (seed.previousIdentities ?? []).some((prev) => row.name === prev.name &&
+        (row.description ?? '') === (prev.description ?? seed.description ?? '') &&
+        row.role_prompt.startsWith(prev.rolePromptHead));
+}
+/** 当前代或任一历史代全中 = 用户从未定制过这行内置智能体。 */
+export function isUntouchedSeed(seed, row) {
+    return matchesCurrent(seed, row) || matchesPreviousIdentity(seed, row);
+}

package/dist/storage/telemetry-settings.d.ts

@@ -0,0 +1,38 @@
+/**
+ * W6-6 遥测合规化:OTLP collector 连接 + 隐私模式的纯逻辑(默认值/校验/归一)。
+ *
+ * 与 `llm-settings.ts` 同样的拆分理由:不依赖 electron / better-sqlite3,
+ * 可在纯 Node/vitest 下直接单测。持久化在 `storage/index.ts` 的
+ * `settings_kv` 表(key = 'telemetry_settings')。
+ *
+ * 隐私模型(与 framework `otel.py` 的 PrivacyMode 对齐):
+ * - 未配置 endpoint = 关。一条 trace 都不出进程——这是默认,也是隐私安全默认。
+ * - 'metadata':只导出结构/时延/状态,事件 payload 正文与自由属性一律丢弃。
+ * - 'full':导出(已脱敏的)payload 与属性。仅当 collector 可信时选。
+ */
+export type TelemetryPrivacyMode = 'full' | 'metadata';
+export interface TelemetrySettings {
+    /**
+     * OTLP/HTTP collector 的 /v1/traces URL,例如
+     * `http://127.0.0.1:4318/v1/traces`。空/缺省 = 遥测关闭(默认)。
+     */
+    endpoint?: string;
+    /** 隐私档位;缺省 'metadata'(可观测但不外发内容)。 */
+    privacyMode: TelemetryPrivacyMode;
+    /** 资源属性 service.name;缺省 'steerable-agent-desktop'。 */
+    serviceName?: string;
+}
+export declare const DEFAULT_TELEMETRY_SETTINGS: TelemetrySettings;
+/** 遥测是否启用:有合法 endpoint 才启用(privacyMode 不影响开关)。 */
+export declare function telemetryEnabled(s: TelemetrySettings | null | undefined): boolean;
+/**
+ * 归一 endpoint:trim;空串视为未配置。只接受 http(s) URL——别的协议
+ * (file: 等)直接拒绝,避免把 trace POST 到非预期 scheme。返回 undefined
+ * 表示无效/未配置。
+ */
+export declare function normalizeTelemetryEndpoint(raw: unknown): string | undefined;
+/**
+ * 合并/校验一份(可能残缺的)incoming 设置,落到合法 TelemetrySettings。
+ * endpoint 非法一律归一为 undefined(=关),绝不让一个坏地址把遥测打开。
+ */
+export declare function mergeTelemetrySettings(settings?: Partial<TelemetrySettings> | null): TelemetrySettings;

package/dist/storage/telemetry-settings.js

@@ -0,0 +1,59 @@
+/**
+ * W6-6 遥测合规化:OTLP collector 连接 + 隐私模式的纯逻辑(默认值/校验/归一)。
+ *
+ * 与 `llm-settings.ts` 同样的拆分理由:不依赖 electron / better-sqlite3,
+ * 可在纯 Node/vitest 下直接单测。持久化在 `storage/index.ts` 的
+ * `settings_kv` 表(key = 'telemetry_settings')。
+ *
+ * 隐私模型(与 framework `otel.py` 的 PrivacyMode 对齐):
+ * - 未配置 endpoint = 关。一条 trace 都不出进程——这是默认,也是隐私安全默认。
+ * - 'metadata':只导出结构/时延/状态,事件 payload 正文与自由属性一律丢弃。
+ * - 'full':导出(已脱敏的)payload 与属性。仅当 collector 可信时选。
+ */
+export const DEFAULT_TELEMETRY_SETTINGS = {
+    endpoint: undefined, // 默认关闭:没有 collector 地址就一条都不发
+    privacyMode: 'metadata',
+    serviceName: 'steerable-agent-desktop',
+};
+/** 遥测是否启用:有合法 endpoint 才启用(privacyMode 不影响开关)。 */
+export function telemetryEnabled(s) {
+    return !!normalizeTelemetryEndpoint(s?.endpoint);
+}
+/**
+ * 归一 endpoint:trim;空串视为未配置。只接受 http(s) URL——别的协议
+ * (file: 等)直接拒绝,避免把 trace POST 到非预期 scheme。返回 undefined
+ * 表示无效/未配置。
+ */
+export function normalizeTelemetryEndpoint(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return undefined;
+        return trimmed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizePrivacyMode(raw) {
+    return raw === 'full' ? 'full' : 'metadata';
+}
+/**
+ * 合并/校验一份(可能残缺的)incoming 设置,落到合法 TelemetrySettings。
+ * endpoint 非法一律归一为 undefined(=关),绝不让一个坏地址把遥测打开。
+ */
+export function mergeTelemetrySettings(settings) {
+    const incoming = settings ?? {};
+    return {
+        endpoint: normalizeTelemetryEndpoint(incoming.endpoint),
+        privacyMode: normalizePrivacyMode(incoming.privacyMode),
+        serviceName: typeof incoming.serviceName === 'string' && incoming.serviceName.trim()
+            ? incoming.serviceName.trim()
+            : DEFAULT_TELEMETRY_SETTINGS.serviceName,
+    };
+}

package/dist/storage/usage-summary.d.ts

@@ -0,0 +1,55 @@
+/**
+ * W6-9 用量与成本归因 —— 用量聚合的纯逻辑部分。
+ *
+ * `LocalStore.getUsageSummary` 负责 SQL(按 model/provider 分桶 GROUP BY),
+ * 本模块负责把 SQL 行映射成 `UsageSummary`(逐桶 null-cost 处理 + 总计 reduce)。
+ * 拆成纯函数是为了可测:`LocalStore` 顶层加载的 better-sqlite3 native module
+ * 与 vitest 的 node 运行时二进制不兼容,无法直接实例化测试。
+ *
+ * 成本口径:只统计有单价的模型(framework `MODEL_PRICES`);无单价模型的
+ * `cost_usd` 存 NULL,SQL `SUM` 全 NULL 得 NULL → 该桶 `costUsd = null`
+ * (面板渲染 "—"),且不计入总成本。
+ */
+/** 一个 model(+provider) 分桶的用量聚合。 */
+export interface UsageModelBucket {
+    model: string;
+    provider: string;
+    turns: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cachedPromptTokens: number;
+    /** 该桶成本合计(USD);桶内无一条有单价时为 null(渲染为 "—")。 */
+    costUsd: number | null;
+}
+/** 用量面板数据 —— 按 model 分桶 + 总计。 */
+export interface UsageSummary {
+    sinceDays: number;
+    byModel: UsageModelBucket[];
+    totals: {
+        turns: number;
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedPromptTokens: number;
+        /** 所有有单价模型的成本合计(无单价模型不计入)。 */
+        costUsd: number;
+    };
+}
+/** `getUsageSummary` SQL 查询返回的原始行(snake_case 列)。 */
+export interface UsageSummaryRow {
+    model: string;
+    provider: string;
+    turns: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cached_prompt_tokens: number;
+    cost_usd: number | null;
+}
+/**
+ * 把 SQL 分桶行聚合成 `UsageSummary`。
+ * 逐桶:`cost_usd` 为 NULL/undefined → `costUsd = null`;否则转 number。
+ * 总计:token/轮次直接相加;成本只累加非 null 桶(无单价模型不摊入)。
+ */
+export declare function buildUsageSummary(rows: UsageSummaryRow[], sinceDays: number): UsageSummary;

package/dist/storage/usage-summary.js

@@ -0,0 +1,38 @@
+/**
+ * W6-9 用量与成本归因 —— 用量聚合的纯逻辑部分。
+ *
+ * `LocalStore.getUsageSummary` 负责 SQL(按 model/provider 分桶 GROUP BY),
+ * 本模块负责把 SQL 行映射成 `UsageSummary`(逐桶 null-cost 处理 + 总计 reduce)。
+ * 拆成纯函数是为了可测:`LocalStore` 顶层加载的 better-sqlite3 native module
+ * 与 vitest 的 node 运行时二进制不兼容,无法直接实例化测试。
+ *
+ * 成本口径:只统计有单价的模型(framework `MODEL_PRICES`);无单价模型的
+ * `cost_usd` 存 NULL,SQL `SUM` 全 NULL 得 NULL → 该桶 `costUsd = null`
+ * (面板渲染 "—"),且不计入总成本。
+ */
+/**
+ * 把 SQL 分桶行聚合成 `UsageSummary`。
+ * 逐桶:`cost_usd` 为 NULL/undefined → `costUsd = null`;否则转 number。
+ * 总计:token/轮次直接相加;成本只累加非 null 桶(无单价模型不摊入)。
+ */
+export function buildUsageSummary(rows, sinceDays) {
+    const byModel = rows.map((row) => ({
+        model: String(row.model),
+        provider: String(row.provider),
+        turns: Number(row.turns),
+        promptTokens: Number(row.prompt_tokens),
+        completionTokens: Number(row.completion_tokens),
+        totalTokens: Number(row.total_tokens),
+        cachedPromptTokens: Number(row.cached_prompt_tokens),
+        costUsd: row.cost_usd === null || row.cost_usd === undefined ? null : Number(row.cost_usd),
+    }));
+    const totals = byModel.reduce((acc, b) => ({
+        turns: acc.turns + b.turns,
+        promptTokens: acc.promptTokens + b.promptTokens,
+        completionTokens: acc.completionTokens + b.completionTokens,
+        totalTokens: acc.totalTokens + b.totalTokens,
+        cachedPromptTokens: acc.cachedPromptTokens + b.cachedPromptTokens,
+        costUsd: acc.costUsd + (b.costUsd ?? 0),
+    }), { turns: 0, promptTokens: 0, completionTokens: 0, totalTokens: 0, cachedPromptTokens: 0, costUsd: 0 });
+    return { sinceDays, byModel, totals };
+}

package/dist/storage/web-search-settings.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Web search settings: Tavily key and/or an explicit free backend.
+ *
+ * Empty Tavily key → sidecar does not register `web_search` unless:
+ * - stored provider is `ddg` (DuckDuckGo lite, no key), or
+ * - the current LLM has hosted search (OpenAI) and the host injects
+ *   `STEERABLE_WEB_SEARCH_PROVIDER=host`.
+ * DuckDuckGo is never a silent fallback for an empty Tavily key.
+ */
+export type WebSearchProviderId = 'tavily' | 'ddg';
+export interface WebSearchSettings {
+    /** Search backend. Default `tavily` keeps the previous empty-key = off behavior. */
+    provider: WebSearchProviderId;
+    /** Search backend key (Tavily). Empty/undefined = not configured. */
+    apiKey?: string;
+}
+export declare const DEFAULT_WEB_SEARCH_SETTINGS: WebSearchSettings;
+export declare function normalizeWebSearchProvider(raw: unknown): WebSearchProviderId;
+export declare function mergeWebSearchSettings(settings?: Partial<WebSearchSettings> | null): WebSearchSettings;
+/** Hostnames whose chat credential can run hosted web search (OpenAI). */
+export declare function hostedSearchAvailable(baseUrl?: string): boolean;
+/**
+ * Origin for the in-process search backend. Mirrors
+ * `WebToolsConfig` / `_default_search_base_url` in the sidecar.
+ */
+export declare function defaultSearchBaseUrl(provider: string): string;
+/**
+ * Sidecar env the desktop injects at spawn. Process env wins over stored
+ * settings. `ddg` is an explicit stored (or operator) choice. `host` is
+ * only set when there is no search key, the stored provider is not `ddg`,
+ * and the LLM base URL is OpenAI.
+ */
+export declare function sidecarWebSearchEnv(opts: {
+    processEnv: NodeJS.ProcessEnv;
+    storedApiKey?: string;
+    storedProvider?: WebSearchProviderId;
+    llmBaseUrl?: string;
+}): Record<string, string>;

package/dist/storage/web-search-settings.js

@@ -0,0 +1,74 @@
+/**
+ * Web search settings: Tavily key and/or an explicit free backend.
+ *
+ * Empty Tavily key → sidecar does not register `web_search` unless:
+ * - stored provider is `ddg` (DuckDuckGo lite, no key), or
+ * - the current LLM has hosted search (OpenAI) and the host injects
+ *   `STEERABLE_WEB_SEARCH_PROVIDER=host`.
+ * DuckDuckGo is never a silent fallback for an empty Tavily key.
+ */
+export const DEFAULT_WEB_SEARCH_SETTINGS = {
+    provider: 'tavily',
+    apiKey: undefined,
+};
+export function normalizeWebSearchProvider(raw) {
+    return raw === 'ddg' ? 'ddg' : 'tavily';
+}
+export function mergeWebSearchSettings(settings) {
+    const incoming = settings ?? {};
+    const key = typeof incoming.apiKey === 'string' ? incoming.apiKey.trim() : '';
+    return {
+        provider: normalizeWebSearchProvider(incoming.provider),
+        apiKey: key || undefined,
+    };
+}
+/** Hostnames whose chat credential can run hosted web search (OpenAI). */
+export function hostedSearchAvailable(baseUrl) {
+    if (!baseUrl || !baseUrl.trim())
+        return false;
+    try {
+        const host = new URL(baseUrl.includes('://') ? baseUrl : `https://${baseUrl}`).hostname;
+        return host === 'api.openai.com' || host.endsWith('.openai.com');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Origin for the in-process search backend. Mirrors
+ * `WebToolsConfig` / `_default_search_base_url` in the sidecar.
+ */
+export function defaultSearchBaseUrl(provider) {
+    if (provider === 'brave')
+        return 'https://api.search.brave.com';
+    if (provider === 'ddg')
+        return 'https://html.duckduckgo.com';
+    return 'https://api.tavily.com';
+}
+/**
+ * Sidecar env the desktop injects at spawn. Process env wins over stored
+ * settings. `ddg` is an explicit stored (or operator) choice. `host` is
+ * only set when there is no search key, the stored provider is not `ddg`,
+ * and the LLM base URL is OpenAI.
+ */
+export function sidecarWebSearchEnv(opts) {
+    const fromEnv = ((opts.processEnv.STEERABLE_WEB_SEARCH_API_KEY || '').trim()
+        || (opts.processEnv.TAVILY_API_KEY || '').trim());
+    if (fromEnv) {
+        return { STEERABLE_WEB_SEARCH_API_KEY: fromEnv };
+    }
+    if ((opts.processEnv.STEERABLE_WEB_SEARCH_PROVIDER || '').trim()) {
+        return {};
+    }
+    if (opts.storedProvider === 'ddg') {
+        return { STEERABLE_WEB_SEARCH_PROVIDER: 'ddg' };
+    }
+    const stored = (opts.storedApiKey || '').trim();
+    if (stored) {
+        return { STEERABLE_WEB_SEARCH_API_KEY: stored };
+    }
+    if (hostedSearchAvailable(opts.llmBaseUrl)) {
+        return { STEERABLE_WEB_SEARCH_PROVIDER: 'host' };
+    }
+    return {};
+}

package/dist/storage/write-lease.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cross-process write lease for one sqlite database.
+ *
+ * Sibling lock file: `<dbFileName>` → 同路径换 `.lock` 后缀。
+ *
+ * The lease is an open `BEGIN EXCLUSIVE` transaction on the lock file,
+ * which is a kernel lock in SQLite's VFS (fcntl on POSIX, LockFileEx on
+ * Windows). That gives the three properties the desktop needs: a second
+ * process fails loud (`StoreAlreadyOwnedError`) instead of corrupting a
+ * shared WAL, process death releases the lock without a TTL, and no
+ * caller can steal a live lease.
+ *
+ * Node exposes no portable `flock`, and `fs.constants.O_EXLOCK` does not
+ * exist on any platform, so SQLite's own locking is the only kernel lock
+ * reachable from here — and it is already a shipped dependency because
+ * the database it guards is sqlite.
+ */
+export declare class StoreAlreadyOwnedError extends Error {
+    readonly lockPath: string;
+    constructor(lockPath: string);
+}
+export interface HeldWriteLease {
+    release(): void;
+}
+export declare function lockPathForDb(dbPath: string): string;
+export declare function acquireWriteLease(lockPath: string): HeldWriteLease;

package/dist/storage/write-lease.js

@@ -0,0 +1,74 @@
+/**
+ * Cross-process write lease for one sqlite database.
+ *
+ * Sibling lock file: `<dbFileName>` → 同路径换 `.lock` 后缀。
+ *
+ * The lease is an open `BEGIN EXCLUSIVE` transaction on the lock file,
+ * which is a kernel lock in SQLite's VFS (fcntl on POSIX, LockFileEx on
+ * Windows). That gives the three properties the desktop needs: a second
+ * process fails loud (`StoreAlreadyOwnedError`) instead of corrupting a
+ * shared WAL, process death releases the lock without a TTL, and no
+ * caller can steal a live lease.
+ *
+ * Node exposes no portable `flock`, and `fs.constants.O_EXLOCK` does not
+ * exist on any platform, so SQLite's own locking is the only kernel lock
+ * reachable from here — and it is already a shipped dependency because
+ * the database it guards is sqlite.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export class StoreAlreadyOwnedError extends Error {
+    lockPath;
+    constructor(lockPath) {
+        super(`store already owned: ${lockPath} (another process has this database open for write)`);
+        this.name = 'StoreAlreadyOwnedError';
+        this.lockPath = lockPath;
+    }
+}
+/** SQLite reports a live incumbent as SQLITE_BUSY / SQLITE_BUSY_SNAPSHOT. */
+function isSqliteBusy(err) {
+    const code = err?.code;
+    return typeof code === 'string' && code.startsWith('SQLITE_BUSY');
+}
+export function lockPathForDb(dbPath) {
+    const parsed = path.parse(path.resolve(dbPath));
+    return path.join(parsed.dir, `${parsed.name}.lock`);
+}
+export function acquireWriteLease(lockPath) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    // Loaded lazily so tests that only exercise lockPathForDb do not need
+    // better-sqlite3's Electron ABI.
+    const Database = require('better-sqlite3');
+    const db = new Database(lockPath, { timeout: 0 });
+    try {
+        // Every statement here can hit the incumbent's lock, including the
+        // journal_mode pragma — it rewrites the header and so needs the same
+        // write lock. busy_timeout 0 makes that immediate instead of a stall.
+        db.pragma('busy_timeout = 0');
+        db.pragma('journal_mode = DELETE');
+        db.exec('CREATE TABLE IF NOT EXISTS lease (id INTEGER PRIMARY KEY)');
+        db.exec('BEGIN EXCLUSIVE');
+    }
+    catch (err) {
+        db.close();
+        // Only contention becomes StoreAlreadyOwnedError; a corrupt or
+        // unreadable lock file must not masquerade as a second instance.
+        if (isSqliteBusy(err)) {
+            throw new StoreAlreadyOwnedError(lockPath);
+        }
+        throw err;
+    }
+    let released = false;
+    return {
+        release() {
+            if (released)
+                return;
+            released = true;
+            // Closing rolls the transaction back and drops the kernel lock. The
+            // lock file itself is never deleted.
+            db.close();
+        },
+    };
+}

package/dist/terminal-manager.d.ts

@@ -0,0 +1,83 @@
+import { EventEmitter } from 'events';
+export type TerminalShell = 'zsh' | 'bash' | 'sh' | 'powershell.exe' | 'cmd.exe';
+export interface TerminalSpawnOptions {
+    shell?: TerminalShell;
+    cwd?: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+}
+export interface TerminalSession {
+    id: string;
+    shell: string;
+    pid: number;
+    cwd: string;
+    cols: number;
+    rows: number;
+}
+export interface TerminalExecResult {
+    success: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+    durationMs: number;
+}
+export interface TerminalManagerEvents {
+    data: (sessionId: string, chunk: string) => void;
+    exit: (sessionId: string, code: number, signal: string | null) => void;
+    spawned: (session: TerminalSession) => void;
+}
+/**
+ * Owns interactive PTY sessions and provides two complementary APIs:
+ *
+ *  1. **Streaming**: spawn a PTY, push raw bytes to subscribers (xterm UI),
+ *     accept user input via `write()`. Standard interactive terminal model.
+ *
+ *  2. **Programmatic exec**: `exec(id, command)` writes a command to the PTY
+ *     wrapped with a unique end-of-command sentinel, captures the output
+ *     between write and sentinel, and resolves with stdout + exit code.
+ *     This is what the agent uses when it wants to "drive" the user's
+ *     visible terminal — the user sees the command being typed and the
+ *     output streaming live, while the agent gets a structured result back.
+ *
+ * Concurrency note: only one `exec()` may be in flight per session. Callers
+ * must serialize their requests; this class throws if exec is invoked while
+ * another exec is still pending on the same session.
+ */
+export declare class TerminalManager extends EventEmitter {
+    private sessions;
+    spawn(options?: TerminalSpawnOptions): TerminalSession;
+    list(): TerminalSession[];
+    primarySession(): TerminalSession | null;
+    ensurePrimary(options?: TerminalSpawnOptions): TerminalSession;
+    /**
+     * Snapshot of recent PTY output, used to "catch up" a renderer that
+     * subscribed after the session started producing output.
+     */
+    getReplayBuffer(id: string): string;
+    write(id: string, data: string): boolean;
+    resize(id: string, cols: number, rows: number): boolean;
+    kill(id: string): boolean;
+    killAll(): void;
+    /**
+     * Execute a single command in the visible PTY and wait for it to finish.
+     * The user sees the command typed and output streaming live. The returned
+     * result is parsed from the captured stream by stripping the sentinel.
+     *
+     * Caller must ensure no other exec() is pending on the same session.
+     *
+     * `killOnTimeout`: on timeout, send SIGINT (Ctrl-C) to the PTY instead of
+     * just giving up on the capture. A timed-out command otherwise keeps
+     * running in the shared visible terminal — every subsequent exec jams
+     * behind it (typed into the busy terminal, never reaching a shell prompt)
+     * and times out in cascade. The wrapper's `; printf <sentinel>` survives
+     * the interrupt (SIGINT kills the foreground pipeline, not the shell's
+     * command list), so after Ctrl-C we keep waiting briefly for the sentinel
+     * and resolve with the interrupted exit code (130) instead of rejecting.
+     * GUI-launch commands pass false: their timeout means "launched, still
+     * running", and killing would terminate the app the user asked for.
+     */
+    exec(id: string, command: string, timeoutMs?: number, killOnTimeout?: boolean): Promise<TerminalExecResult>;
+    private defaultShell;
+}