@skillfm/local 2.6.3 → 2.7.0

package/dist/mcp/_vendored-contracts/beacon-mcp-tools-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon-mcp-tools-v1.d.ts","sourceRoot":"","sources":["../../../src/mcp/_vendored-contracts/beacon-mcp-tools-v1.ts"],"names":[],"mappings":"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"}

package/dist/mcp/_vendored-contracts/beacon-mcp-tools-v1.js

@@ -0,0 +1,128 @@
+// AUTO-GENERATED — do not edit. Source: shared/contracts/envelope-v2/beacon-mcp-tools-v1.ts
+//     Re-generate via `npx tsx sdk/skillfm-local/scripts/inline-mcp-contracts.ts`.
+//     Edit the source file in shared/contracts/envelope-v2/ instead.
+// @skillfm/contracts — Beacon MCP Skill Tools V1
+//
+// 本文件是 SkillFM Beacon Phase 1 MVP 的 MCP skill 工具集 CANONICAL 契约。
+// MCP skill (sdk/beacon-mcp) 和 Brain (platform/api/src/beacon/) 双方实现都从这里 import。
+//
+// 权威来源:
+//   docs/prd/PRD-SKILLFM-MCP-SKILL-V1.md §4
+//   docs/prd/PRD-SKILLFM-BEACON-CALL-SEQUENCE-V1.md §3
+//
+// 设计原则:
+//   - 30+ tools 完整名单见 §1 SKILLFM_TOOL_NAMES (常量,不能漂)
+//   - Phase 0 只详细定义"关键 5 个"代表 tool(§3-§7)
+//     其余 25+ tool 留 TODO,Week 5 实施时补完
+//   - Pro/Free 边界靠 Output 里的 isProLocked / proUpgradeHint 字段表达
+//     不是 input 直接拒(让 Free 用户能看到价值,而不是 403)
+//
+// BYOK 红线提醒:
+//   tool input/output 永远不出现 API key / cookie / session 等用户凭证
+//   涉及 LLM 路由时只交换 model 名 + cost 数字,实际 LLM 调用由 agent 用户机器自跑
+// ============================================================================
+// §1 工具命名清单(全 30+ tools 名字定下来,实现可分批)
+// ============================================================================
+/** 全部 beacon MCP tool 名(命名约定: skillfm_<verb>_<noun>) */
+export const SKILLFM_TOOL_NAMES = {
+    // 数据查询类(agent 主动查信息)
+    query: [
+        'skillfm_check_usage',
+        'skillfm_check_balance',
+        'skillfm_check_expiry',
+        'skillfm_list_assets',
+        'skillfm_get_savings_summary',
+    ],
+    // 路由建议类(任务前)
+    routing: [
+        'skillfm_suggest_route',
+        'skillfm_explain_routing',
+    ],
+    // 异常检测类(任务中)
+    anomaly: [
+        'skillfm_check_session_health',
+        'skillfm_check_burn_rate',
+    ],
+    // 优化建议类(任务后)
+    optimize: [
+        'skillfm_suggest_caching',
+        'skillfm_suggest_batching',
+        'skillfm_suggest_clear_context',
+    ],
+    // 时效预警类
+    expiry: [
+        'skillfm_check_domain_expiry',
+        'skillfm_check_ssl_expiry',
+        'skillfm_check_card_expiry',
+        'skillfm_check_balance_runway',
+    ],
+    // 跨工具发现类
+    discover: [
+        'skillfm_suggest_skill',
+        'skillfm_search_skill_market',
+    ],
+    // Avatar 推荐类
+    avatar: [
+        'skillfm_avatar_market',
+        'skillfm_explain_avatar',
+    ],
+    // Pro 升级类
+    upgrade: [
+        'skillfm_promote_pro',
+        'skillfm_show_savings_potential',
+    ],
+    // Memory / 凭证类
+    storage: [
+        'skillfm_save_credential',
+        'skillfm_get_credential',
+        'skillfm_memory_sync',
+        'skillfm_memory_recall',
+    ],
+    // 月度推送类(Pro)
+    push: [
+        'skillfm_get_monthly_picks',
+        'skillfm_install_recommended_skill',
+    ],
+    // 反馈类
+    feedback: [
+        'skillfm_record_acceptance',
+        'skillfm_record_rejection',
+        'skillfm_user_preferences',
+    ],
+};
+/** 把分组扁平化的所有 tool 名,Phase 0 用于 sanity check */
+export const ALL_SKILLFM_TOOL_NAMES = Object.values(SKILLFM_TOOL_NAMES).flat();
+// ============================================================================
+// §3 关键 tool 1: skillfm_check_usage(数据查询)
+// ============================================================================
+export const SkillFmPlatform = {
+    ALL: 'all',
+    ANTHROPIC: 'anthropic',
+    OPENAI: 'openai',
+    DEEPSEEK: 'deepseek',
+    QWEN: 'qwen',
+    DOUBAO: 'doubao',
+    KIMI: 'kimi',
+    CURSOR: 'cursor',
+    CLAUDE_CODE: 'claude_code',
+    OPENCLAW: 'openclaw',
+    CLINE: 'cline',
+};
+/** 提取分类 letter,client 决策树用来查 user_prefs.disabledCategories */
+export function getCategoryFromTriggerType(triggerType) {
+    const m = /^([A-H])\d+_/.exec(triggerType);
+    return m ? m[1] : null;
+}
+// ============================================================================
+// §13 Phase 1 → Phase 2 演进的 stable surface
+// ============================================================================
+/**
+ * 本契约 v1 → v2 演进规则:
+ * - 字段只允许加,不能删
+ * - enum 只允许加新值,不能改/删现值
+ * - tool 名字本身永不改(改 = 出新 tool 名 + 老 tool 标 deprecated)
+ *
+ * 任何破坏性变更必须出 beacon-mcp-tools-v2.ts 新文件,v1 保留至少 6 个月。
+ */
+export const BEACON_MCP_TOOLS_CONTRACT_VERSION = 'v1';
+//# sourceMappingURL=beacon-mcp-tools-v1.js.map

package/dist/mcp/_vendored-contracts/beacon-mcp-tools-v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon-mcp-tools-v1.js","sourceRoot":"","sources":["../../../src/mcp/_vendored-contracts/beacon-mcp-tools-v1.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,mFAAmF;AACnF,qEAAqE;AAErE,iDAAiD;AACjD,EAAE;AACF,gEAAgE;AAChE,iFAAiF;AACjF,EAAE;AACF,QAAQ;AACR,4CAA4C;AAC5C,uDAAuD;AACvD,EAAE;AACF,QAAQ;AACR,qDAAqD;AACrD,0CAA0C;AAC1C,sCAAsC;AACtC,+DAA+D;AAC/D,2CAA2C;AAC3C,EAAE;AACF,aAAa;AACb,6DAA6D;AAC7D,4DAA4D;AAE5D,+EAA+E;AAC/E,qCAAqC;AACrC,+EAA+E;AAE/E,wDAAwD;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,qBAAqB;IACrB,KAAK,EAAE;QACL,qBAAqB;QACrB,uBAAuB;QACvB,sBAAsB;QACtB,qBAAqB;QACrB,6BAA6B;KAC9B;IACD,aAAa;IACb,OAAO,EAAE;QACP,uBAAuB;QACvB,yBAAyB;KAC1B;IACD,aAAa;IACb,OAAO,EAAE;QACP,8BAA8B;QAC9B,yBAAyB;KAC1B;IACD,aAAa;IACb,QAAQ,EAAE;QACR,yBAAyB;QACzB,0BAA0B;QAC1B,+BAA+B;KAChC;IACD,QAAQ;IACR,MAAM,EAAE;QACN,6BAA6B;QAC7B,0BAA0B;QAC1B,2BAA2B;QAC3B,8BAA8B;KAC/B;IACD,SAAS;IACT,QAAQ,EAAE;QACR,uBAAuB;QACvB,6BAA6B;KAC9B;IACD,aAAa;IACb,MAAM,EAAE;QACN,uBAAuB;QACvB,wBAAwB;KACzB;IACD,UAAU;IACV,OAAO,EAAE;QACP,qBAAqB;QACrB,gCAAgC;KACjC;IACD,eAAe;IACf,OAAO,EAAE;QACP,yBAAyB;QACzB,wBAAwB;QACxB,qBAAqB;QACrB,uBAAuB;KACxB;IACD,aAAa;IACb,IAAI,EAAE;QACJ,2BAA2B;QAC3B,mCAAmC;KACpC;IACD,MAAM;IACN,QAAQ,EAAE;QACR,2BAA2B;QAC3B,0BAA0B;QAC1B,0BAA0B;KAC3B;CACO,CAAC;AAEX,+CAA+C;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,IAAI,EAAE,CAAC;AA+ClG,+EAA+E;AAC/E,0CAA0C;AAC1C,+EAA+E;AAE/E,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,GAAG,EAAE,KAAK;IACV,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;CACN,CAAC;AAsVX,8DAA8D;AAC9D,MAAM,UAAU,0BAA0B,CAAC,WAAwB;IACjE,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3C,OAAO,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAwB,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED,+EAA+E;AAC/E,2CAA2C;AAC3C,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,IAAa,CAAC"}

package/dist/mcp/brain-client.d.ts

@@ -0,0 +1,96 @@
+/**
+ * src/brain-client.ts — Thin HTTPS wrapper for /v1/beacon/* endpoints.
+ *
+ * Phase 0 contract:
+ *   - Every method returns a `BrainResult<T>` envelope. Network/5xx/contract
+ *     drift never throws — callers always see ok=false and can fall back to
+ *     local cache without try/catch noise.
+ *   - 3-attempt exponential backoff (1s / 2s / 4s); 5s per-attempt timeout.
+ *   - All Phase 0 method bodies return mock fixtures matching
+ *     ACCEPTANCE-SCENARIO §1.1 numbers ($487 spend, $312 savings, etc.) so
+ *     the MCP server can demo the call sequence end-to-end without a live
+ *     brain.
+ *
+ * BYOK red line: this file MUST NOT read or transmit any LLM API key /
+ * cookie / vault secret. The only credential it sends is the
+ * `Authorization: Bearer <agentToken>` header (an opaque SkillFM-issued token).
+ *
+ * TODO Week 5:
+ *   - Real fetch() against api.skillfm.ai (endpoints listed below).
+ *   - HTTP-level error → SkillFmError code mapping (429 → BRAIN_RATE_LIMITED,
+ *     5xx → BRAIN_INTERNAL, network ECONN → NETWORK_UNREACHABLE).
+ *   - Idempotency-key on POSTs (record-acceptance / record-rejection) so retry
+ *     storms don't double-count feedback.
+ *   - ETag / If-None-Match on GET /rules to take advantage of brain side
+ *     stale-while-revalidate.
+ *   - structured tracing (correlation-id) so a brain log line can be linked
+ *     back to a specific MCP tool invocation.
+ *
+ * Endpoint inventory (canonical list lives in beacon-rule-protocol-v1.ts,
+ * which subagent A will write later — keep names in sync when that arrives):
+ *   GET    /v1/beacon/rules
+ *   POST   /v1/beacon/feedback
+ *   GET    /v1/beacon/preferences
+ *   PUT    /v1/beacon/preferences
+ *   GET    /v1/beacon/monthly-picks
+ *   GET    /v1/beacon/assets
+ *   POST   /v1/beacon/usage-snapshots
+ */
+import { type SkillFmCheckUsageOutput, type SkillFmCheckExpiryOutput, type SkillFmAvatarMarketOutput, type SkillFmGetMonthlyPicksOutput, type SkillFmRecordFeedbackOutput, type UserPreferences, type SkillFmRecordAcceptanceInput, type SkillFmRecordRejectionInput } from './_vendored-contracts/beacon-mcp-tools-v1.js';
+export interface BrainClientOpts {
+    agentToken: string | null;
+    baseUrl: string;
+    /** override default 5000ms */
+    timeoutMs?: number;
+}
+export type BrainResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    retryable: boolean;
+};
+export declare class BrainClient {
+    private readonly agentToken;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(opts: BrainClientOpts);
+    /** True if no token configured — caller should serve cache / mock fixtures. */
+    isDegraded(): boolean;
+    /** GET /v1/beacon/rules — Phase 0 mock; Week 5 real fetch. */
+    fetchRule(triggerType: string, _triggerContext: Record<string, unknown>, _userProfile: Record<string, unknown>): Promise<BrainResult<{
+        ruleId: string;
+        payload: Record<string, unknown>;
+    }>>;
+    /** POST /v1/beacon/feedback — record acceptance OR rejection. */
+    postFeedback(kind: 'acceptance' | 'rejection', _input: SkillFmRecordAcceptanceInput | SkillFmRecordRejectionInput): Promise<BrainResult<SkillFmRecordFeedbackOutput>>;
+    /** GET /v1/beacon/preferences */
+    getPreferences(): Promise<BrainResult<UserPreferences>>;
+    /** PUT /v1/beacon/preferences */
+    putPreferences(_prefs: UserPreferences): Promise<BrainResult<{
+        ok: true;
+    }>>;
+    /** GET /v1/beacon/monthly-picks?personalized=... */
+    getMonthlyPicks(_personalized: boolean): Promise<BrainResult<SkillFmGetMonthlyPicksOutput>>;
+    /** GET /v1/beacon/assets?withinDays=&category= */
+    getAssets(_withinDays?: number, _category?: string): Promise<BrainResult<SkillFmCheckExpiryOutput>>;
+    /** GET /v1/beacon/usage */
+    getUsage(): Promise<BrainResult<SkillFmCheckUsageOutput>>;
+    /** GET /v1/beacon/avatar-market */
+    getAvatarMarket(_intent: string): Promise<BrainResult<SkillFmAvatarMarketOutput>>;
+    /** POST /v1/beacon/usage-snapshots — agents push their own daily usage. */
+    postUsageSnapshot(_snapshots: Array<Record<string, unknown>>): Promise<BrainResult<{
+        accepted: number;
+    }>>;
+    /**
+     * For tests that need to assert headers / URL. Not exported via index.ts.
+     */
+    _describe(): {
+        baseUrl: string;
+        hasToken: boolean;
+        timeoutMs: number;
+    };
+}
+//# sourceMappingURL=brain-client.d.ts.map

package/dist/mcp/brain-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-client.d.ts","sourceRoot":"","sources":["../../src/mcp/brain-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EACjC,MAAM,8CAA8C,CAAC;AAItD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACrB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC;AAsFrE,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,EAAE,eAAe;IAMjC,+EAA+E;IAC/E,UAAU,IAAI,OAAO;IAIrB,8DAA8D;IACxD,SAAS,CACb,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAAC,WAAW,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAa7E,iEAAiE;IAC3D,YAAY,CAChB,IAAI,EAAE,YAAY,GAAG,WAAW,EAChC,MAAM,EAAE,4BAA4B,GAAG,2BAA2B,GACjE,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAAC;IAYpD,iCAAiC;IAC3B,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;IAW7D,iCAAiC;IAC3B,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IASjF,oDAAoD;IAC9C,eAAe,CACnB,aAAa,EAAE,OAAO,GACrB,OAAO,CAAC,WAAW,CAAC,4BAA4B,CAAC,CAAC;IAMrD,kDAAkD;IAC5C,SAAS,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,wBAAwB,CAAC,CAAC;IAMzG,2BAA2B;IACrB,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC;IAM/D,mCAAmC;IAC7B,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAC;IAMvF,2EAA2E;IACrE,iBAAiB,CACrB,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzC,OAAO,CAAC,WAAW,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAM7C;;OAEG;IACH,SAAS,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CAOvE"}

package/dist/mcp/brain-client.js

@@ -0,0 +1,214 @@
+/**
+ * src/brain-client.ts — Thin HTTPS wrapper for /v1/beacon/* endpoints.
+ *
+ * Phase 0 contract:
+ *   - Every method returns a `BrainResult<T>` envelope. Network/5xx/contract
+ *     drift never throws — callers always see ok=false and can fall back to
+ *     local cache without try/catch noise.
+ *   - 3-attempt exponential backoff (1s / 2s / 4s); 5s per-attempt timeout.
+ *   - All Phase 0 method bodies return mock fixtures matching
+ *     ACCEPTANCE-SCENARIO §1.1 numbers ($487 spend, $312 savings, etc.) so
+ *     the MCP server can demo the call sequence end-to-end without a live
+ *     brain.
+ *
+ * BYOK red line: this file MUST NOT read or transmit any LLM API key /
+ * cookie / vault secret. The only credential it sends is the
+ * `Authorization: Bearer <agentToken>` header (an opaque SkillFM-issued token).
+ *
+ * TODO Week 5:
+ *   - Real fetch() against api.skillfm.ai (endpoints listed below).
+ *   - HTTP-level error → SkillFmError code mapping (429 → BRAIN_RATE_LIMITED,
+ *     5xx → BRAIN_INTERNAL, network ECONN → NETWORK_UNREACHABLE).
+ *   - Idempotency-key on POSTs (record-acceptance / record-rejection) so retry
+ *     storms don't double-count feedback.
+ *   - ETag / If-None-Match on GET /rules to take advantage of brain side
+ *     stale-while-revalidate.
+ *   - structured tracing (correlation-id) so a brain log line can be linked
+ *     back to a specific MCP tool invocation.
+ *
+ * Endpoint inventory (canonical list lives in beacon-rule-protocol-v1.ts,
+ * which subagent A will write later — keep names in sync when that arrives):
+ *   GET    /v1/beacon/rules
+ *   POST   /v1/beacon/feedback
+ *   GET    /v1/beacon/preferences
+ *   PUT    /v1/beacon/preferences
+ *   GET    /v1/beacon/monthly-picks
+ *   GET    /v1/beacon/assets
+ *   POST   /v1/beacon/usage-snapshots
+ */
+import { SKILLFM_ERROR_CODES } from './errors.js';
+/**
+ * Mock fixture matching ACCEPTANCE-SCENARIO §1.1 A2 — $487 monthly spend,
+ * 67% Anthropic, $312 already saved. Used until brain endpoints land.
+ */
+const MOCK_USAGE_FIXTURE = {
+    totalSpent: { amount: 487, currency: 'USD' },
+    byPlatform: {
+        anthropic: { amount: 326, tokens: 12_400_000, calls: 8_240 },
+        openai: { amount: 102, tokens: 3_900_000, calls: 1_810 },
+        deepseek: { amount: 59, tokens: 18_000_000, calls: 4_300 },
+    },
+    savingsThisPeriod: {
+        amount: 312,
+        mechanisms: ['model_routing', 'prompt_cache', 'context_compression'],
+    },
+    trend: { direction: 'down', percentChange: -8 },
+    warnings: [],
+};
+const MOCK_EXPIRY_FIXTURE = {
+    items: [],
+    proUpgradeHint: {
+        en: 'Upgrade to Pro to see all 30-day expiry alerts (domains, SSL, cards).',
+        zh: '升级 Pro 查看 30 天内全部到期提醒(域名 / SSL / 卡片)。',
+    },
+};
+const MOCK_AVATAR_FIXTURE = {
+    matches: [],
+    reasoningWhy: {
+        en: 'Phase 0 mock — no avatars matched this intent yet.',
+        zh: 'Phase 0 占位 — 暂无匹配 avatar。',
+    },
+};
+const MOCK_MONTHLY_PICKS_FIXTURE = {
+    monthLabel: '2026-05',
+    curationTheme: {
+        en: 'Cost-aware coding skills',
+        zh: '省钱编程技能精选',
+    },
+    picks: [],
+};
+// ============================================================================
+// Backoff helper
+// ============================================================================
+const DEFAULT_TIMEOUT_MS = 5000;
+const RETRY_DELAYS_MS = [1_000, 2_000, 4_000];
+async function _sleep(ms) {
+    await new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Phase 0 — wrap every method. Currently always resolves to mock data,
+ * but the structure is what Week 5 implementations will plug into.
+ */
+async function _attemptWithBackoff(fn) {
+    let lastErr = {
+        ok: false,
+        code: SKILLFM_ERROR_CODES.NETWORK_UNREACHABLE,
+        message: 'no attempt made',
+        retryable: true,
+    };
+    for (let i = 0; i < RETRY_DELAYS_MS.length; i += 1) {
+        const result = await fn();
+        if (result.ok)
+            return result;
+        lastErr = result;
+        if (!result.retryable)
+            return result;
+        if (i < RETRY_DELAYS_MS.length - 1) {
+            await _sleep(RETRY_DELAYS_MS[i]);
+        }
+    }
+    return lastErr;
+}
+// ============================================================================
+// Client
+// ============================================================================
+export class BrainClient {
+    agentToken;
+    baseUrl;
+    timeoutMs;
+    constructor(opts) {
+        this.agentToken = opts.agentToken;
+        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /** True if no token configured — caller should serve cache / mock fixtures. */
+    isDegraded() {
+        return this.agentToken === null;
+    }
+    /** GET /v1/beacon/rules — Phase 0 mock; Week 5 real fetch. */
+    async fetchRule(triggerType, _triggerContext, _userProfile) {
+        return _attemptWithBackoff(async () => {
+            // TODO Week 5: real fetch with abortcontroller(this.timeoutMs)
+            return {
+                ok: true,
+                data: {
+                    ruleId: `mock_rule_${triggerType}`,
+                    payload: {},
+                },
+            };
+        });
+    }
+    /** POST /v1/beacon/feedback — record acceptance OR rejection. */
+    async postFeedback(kind, _input) {
+        return _attemptWithBackoff(async () => {
+            return {
+                ok: true,
+                data: {
+                    recorded: true,
+                    acceptanceRateForCategory: kind === 'acceptance' ? 0.42 : 0.31,
+                },
+            };
+        });
+    }
+    /** GET /v1/beacon/preferences */
+    async getPreferences() {
+        return _attemptWithBackoff(async () => {
+            return {
+                ok: false,
+                code: SKILLFM_ERROR_CODES.TOOL_NOT_IMPLEMENTED,
+                message: 'preferences are local-only in Phase 0',
+                retryable: false,
+            };
+        });
+    }
+    /** PUT /v1/beacon/preferences */
+    async putPreferences(_prefs) {
+        return _attemptWithBackoff(async () => {
+            return {
+                ok: true,
+                data: { ok: true },
+            };
+        });
+    }
+    /** GET /v1/beacon/monthly-picks?personalized=... */
+    async getMonthlyPicks(_personalized) {
+        return _attemptWithBackoff(async () => {
+            return { ok: true, data: MOCK_MONTHLY_PICKS_FIXTURE };
+        });
+    }
+    /** GET /v1/beacon/assets?withinDays=&category= */
+    async getAssets(_withinDays, _category) {
+        return _attemptWithBackoff(async () => {
+            return { ok: true, data: MOCK_EXPIRY_FIXTURE };
+        });
+    }
+    /** GET /v1/beacon/usage */
+    async getUsage() {
+        return _attemptWithBackoff(async () => {
+            return { ok: true, data: MOCK_USAGE_FIXTURE };
+        });
+    }
+    /** GET /v1/beacon/avatar-market */
+    async getAvatarMarket(_intent) {
+        return _attemptWithBackoff(async () => {
+            return { ok: true, data: MOCK_AVATAR_FIXTURE };
+        });
+    }
+    /** POST /v1/beacon/usage-snapshots — agents push their own daily usage. */
+    async postUsageSnapshot(_snapshots) {
+        return _attemptWithBackoff(async () => {
+            return { ok: true, data: { accepted: 0 } };
+        });
+    }
+    /**
+     * For tests that need to assert headers / URL. Not exported via index.ts.
+     */
+    _describe() {
+        return {
+            baseUrl: this.baseUrl,
+            hasToken: this.agentToken !== null,
+            timeoutMs: this.timeoutMs,
+        };
+    }
+}
+//# sourceMappingURL=brain-client.js.map

package/dist/mcp/brain-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-client.js","sourceRoot":"","sources":["../../src/mcp/brain-client.ts"],"names":[],"mappings":"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"}

package/dist/mcp/cache.d.ts

@@ -0,0 +1,55 @@
+/**
+ * src/cache.ts — Local filesystem cache paths + tiny JSON helpers.
+ *
+ * Ownership layout (everything under `~/.skillfm/beacon-mcp/`):
+ *   - rules-v{N}.json    cached brain rule snapshot (stale-while-revalidate)
+ *   - user-prefs.json    UserPreferences from contract §9
+ *   - session-cache.db   suggestion dedupe + frequency-limit ledger (sqlite stub)
+ *   - config.json        agent token + apiBaseUrl (read by config.ts)
+ *
+ * Phase 0 keeps everything as JSON files — no real sqlite dependency to keep
+ * the npm tarball minimal. Session dedupe lives in-memory for now.
+ *
+ * TODO Week 5:
+ *   - Open session-cache.db with `better-sqlite3` (lazy import to avoid
+ *     making it a hard dep on agents that never use frequency limits).
+ *   - Add atomic write helper (write to .tmp, rename) so MCP server kill
+ *     mid-flush never corrupts user-prefs.json.
+ *   - Add file-lock so two parallel MCP servers (Cursor + Claude Code on same
+ *     mac) don't race on user-prefs.json — `proper-lockfile` candidate.
+ *   - Add migration: rules-v1.json → rules-v2.json when contract version bumps.
+ */
+import { type UserPreferences } from './_vendored-contracts/beacon-mcp-tools-v1.js';
+export declare const BEACON_HOME: string;
+export declare const RULES_FILE: string;
+export declare const USER_PREFS_FILE: string;
+export declare const SESSION_CACHE_DB: string;
+export declare const SAVINGS_LEDGER_FILE: string;
+export declare const DEFAULT_USER_PREFERENCES: UserPreferences;
+export interface CachedRulesEnvelope {
+    /** ISO 8601 timestamp at which rules were fetched from brain */
+    fetchedAt: string;
+    /** Brain-issued rule revision */
+    revision: number;
+    /** Opaque rule blob — schema owned by beacon-rule-protocol-v1 (Week 5) */
+    rules: Record<string, unknown>;
+}
+export declare function loadRules(): CachedRulesEnvelope | null;
+export declare function saveRules(envelope: CachedRulesEnvelope): void;
+export declare function loadPrefs(): UserPreferences;
+export declare function savePrefs(prefs: UserPreferences): void;
+/**
+ * Phase 0 stub — returns a hand-rolled in-memory map. Week 5 will swap to
+ * better-sqlite3. The shape is intentionally minimal so callers can be
+ * rewritten without changing call sites.
+ */
+export interface SessionCacheHandle {
+    /** Returns true if the same suggestion fired within the dedupe window. */
+    hasRecentSuggestion(key: string, withinMs: number): boolean;
+    recordSuggestion(key: string): void;
+    /** Number of suggestions emitted in the current session (for maxPerSession). */
+    sessionCount(): number;
+    reset(): void;
+}
+export declare function openSessionCache(): SessionCacheHandle;
+//# sourceMappingURL=cache.d.ts.map

package/dist/mcp/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/mcp/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,8CAA8C,CAAC;AAMtD,eAAO,MAAM,WAAW,QAA4C,CAAC;AAErE,eAAO,MAAM,UAAU,QAGtB,CAAC;AACF,eAAO,MAAM,eAAe,QAAuC,CAAC;AACpE,eAAO,MAAM,gBAAgB,QAAwC,CAAC;AACtE,eAAO,MAAM,mBAAmB,QAA2C,CAAC;AAM5E,eAAO,MAAM,wBAAwB,EAAE,eAUtC,CAAC;AAgCF,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,wBAAgB,SAAS,IAAI,mBAAmB,GAAG,IAAI,CAGtD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAE7D;AAED,wBAAgB,SAAS,IAAI,eAAe,CAE3C;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAEtD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5D,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,gFAAgF;IAChF,YAAY,IAAI,MAAM,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,gBAAgB,IAAI,kBAAkB,CAqBrD"}

package/dist/mcp/cache.js

@@ -0,0 +1,109 @@
+/**
+ * src/cache.ts — Local filesystem cache paths + tiny JSON helpers.
+ *
+ * Ownership layout (everything under `~/.skillfm/beacon-mcp/`):
+ *   - rules-v{N}.json    cached brain rule snapshot (stale-while-revalidate)
+ *   - user-prefs.json    UserPreferences from contract §9
+ *   - session-cache.db   suggestion dedupe + frequency-limit ledger (sqlite stub)
+ *   - config.json        agent token + apiBaseUrl (read by config.ts)
+ *
+ * Phase 0 keeps everything as JSON files — no real sqlite dependency to keep
+ * the npm tarball minimal. Session dedupe lives in-memory for now.
+ *
+ * TODO Week 5:
+ *   - Open session-cache.db with `better-sqlite3` (lazy import to avoid
+ *     making it a hard dep on agents that never use frequency limits).
+ *   - Add atomic write helper (write to .tmp, rename) so MCP server kill
+ *     mid-flush never corrupts user-prefs.json.
+ *   - Add file-lock so two parallel MCP servers (Cursor + Claude Code on same
+ *     mac) don't race on user-prefs.json — `proper-lockfile` candidate.
+ *   - Add migration: rules-v1.json → rules-v2.json when contract version bumps.
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { BEACON_MCP_TOOLS_CONTRACT_VERSION, } from './_vendored-contracts/beacon-mcp-tools-v1.js';
+// ============================================================================
+// Path constants
+// ============================================================================
+export const BEACON_HOME = join(homedir(), '.skillfm', 'beacon-mcp');
+export const RULES_FILE = join(BEACON_HOME, `rules-${BEACON_MCP_TOOLS_CONTRACT_VERSION}.json`);
+export const USER_PREFS_FILE = join(BEACON_HOME, 'user-prefs.json');
+export const SESSION_CACHE_DB = join(BEACON_HOME, 'session-cache.db');
+export const SAVINGS_LEDGER_FILE = join(BEACON_HOME, 'savings-ledger.json');
+// ============================================================================
+// Defaults
+// ============================================================================
+export const DEFAULT_USER_PREFERENCES = {
+    disabledCategories: [],
+    maxPerSession: 3,
+    maxPerDay: 10,
+    quietHours: {
+        enabled: false,
+        start: '22:00',
+        end: '08:00',
+        timezone: 'UTC',
+    },
+};
+// ============================================================================
+// Helpers
+// ============================================================================
+function ensureHome() {
+    if (!existsSync(BEACON_HOME)) {
+        mkdirSync(BEACON_HOME, { recursive: true });
+    }
+}
+function readJson(path, fallback) {
+    if (!existsSync(path))
+        return fallback;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        console.error(`[skillfm-beacon-mcp] cache read failed (${path}):`, err.message);
+        return fallback;
+    }
+}
+function writeJson(path, value) {
+    ensureHome();
+    writeFileSync(path, JSON.stringify(value, null, 2), 'utf8');
+}
+export function loadRules() {
+    if (!existsSync(RULES_FILE))
+        return null;
+    return readJson(RULES_FILE, null);
+}
+export function saveRules(envelope) {
+    writeJson(RULES_FILE, envelope);
+}
+export function loadPrefs() {
+    return readJson(USER_PREFS_FILE, DEFAULT_USER_PREFERENCES);
+}
+export function savePrefs(prefs) {
+    writeJson(USER_PREFS_FILE, prefs);
+}
+export function openSessionCache() {
+    const seen = new Map();
+    let count = 0;
+    return {
+        hasRecentSuggestion(key, withinMs) {
+            const t = seen.get(key);
+            if (t === undefined)
+                return false;
+            return Date.now() - t < withinMs;
+        },
+        recordSuggestion(key) {
+            seen.set(key, Date.now());
+            count += 1;
+        },
+        sessionCount() {
+            return count;
+        },
+        reset() {
+            seen.clear();
+            count = 0;
+        },
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/mcp/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/mcp/cache.ts"],"names":[],"mappings":"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"}