@blockrun/franklin 3.28.3 → 3.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/agent/commands.js +37 -9
  2. package/dist/agent/compact.js +1 -1
  3. package/dist/agent/context.js +8 -14
  4. package/dist/agent/llm.js +3 -3
  5. package/dist/agent/loop.js +35 -7
  6. package/dist/agent/optimize.js +5 -5
  7. package/dist/agent/tokens.js +1 -0
  8. package/dist/agent/verification.js +1 -1
  9. package/dist/commands/skills.d.ts +1 -0
  10. package/dist/commands/skills.js +21 -5
  11. package/dist/commands/slack.js +1 -1
  12. package/dist/commands/social.js +1 -1
  13. package/dist/commands/telegram.js +1 -1
  14. package/dist/index.js +1 -0
  15. package/dist/learnings/extractor.js +2 -3
  16. package/dist/learnings/store.d.ts +25 -4
  17. package/dist/learnings/store.js +148 -39
  18. package/dist/mcp/client.d.ts +47 -29
  19. package/dist/mcp/client.js +288 -128
  20. package/dist/mcp/config.js +4 -0
  21. package/dist/mcp/oauth.d.ts +41 -0
  22. package/dist/mcp/oauth.js +205 -0
  23. package/dist/plugin-sdk/workflow.js +2 -2
  24. package/dist/pricing.js +4 -2
  25. package/dist/proxy/fallback.js +1 -1
  26. package/dist/proxy/server.js +15 -13
  27. package/dist/router/index.js +21 -22
  28. package/dist/router/vision.js +2 -1
  29. package/dist/skills/bootstrap.d.ts +35 -10
  30. package/dist/skills/bootstrap.js +87 -10
  31. package/dist/skills/loader.js +12 -0
  32. package/dist/skills/registry.d.ts +1 -1
  33. package/dist/skills/registry.js +4 -3
  34. package/dist/skills/triggers.d.ts +38 -0
  35. package/dist/skills/triggers.js +95 -0
  36. package/dist/skills/types.d.ts +14 -1
  37. package/dist/tools/moa.js +2 -3
  38. package/dist/tools/subagent.js +1 -1
  39. package/dist/ui/model-picker.js +25 -23
  40. package/package.json +1 -1
@@ -0,0 +1,205 @@
1
+ /**
2
+ * OAuth client provider for remote MCP servers.
3
+ *
4
+ * Implements the MCP SDK's `OAuthClientProvider` interface against Franklin's
5
+ * own on-disk store at `~/.blockrun/mcp/oauth/<server>.json`. Each file holds
6
+ * the registered client information + the current token set (access +
7
+ * refresh + expiry). The SDK handles discovery, registration, PKCE, the
8
+ * exchange, and refresh; we only persist + supply the saved state.
9
+ *
10
+ * Authorization flow (interactive):
11
+ * 1. SDK calls `redirectToAuthorization(url)` — we spin up a localhost
12
+ * callback listener on the port encoded into `redirectUrl`, then
13
+ * open the user's browser to the authorization URL.
14
+ * 2. User authorizes in browser. The provider returns `?code=...&state=...`
15
+ * to our callback. We resolve the code through a one-shot promise.
16
+ * 3. SDK exchanges code → tokens, calls `saveTokens()` → we write to disk.
17
+ *
18
+ * Headless mode is not yet supported — if there is no TTY, the OAuth flow
19
+ * raises a clear error directing the user to configure manually instead.
20
+ */
21
+ import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
22
+ import { dirname, join } from 'node:path';
23
+ import { createServer } from 'node:http';
24
+ import { exec } from 'node:child_process';
25
+ import { promisify } from 'node:util';
26
+ import { BLOCKRUN_DIR } from '../config.js';
27
+ import { logger } from '../logger.js';
28
+ const execAsync = promisify(exec);
29
+ const OAUTH_DIR = join(BLOCKRUN_DIR, 'mcp', 'oauth');
30
+ function storePath(serverName) {
31
+ return join(OAUTH_DIR, `${serverName.replace(/[^A-Za-z0-9_.-]/g, '_')}.json`);
32
+ }
33
+ function loadState(serverName) {
34
+ const p = storePath(serverName);
35
+ if (!existsSync(p))
36
+ return {};
37
+ try {
38
+ return JSON.parse(readFileSync(p, 'utf8'));
39
+ }
40
+ catch (err) {
41
+ logger.warn(`[mcp:oauth:${serverName}] failed to read state — starting fresh: ${err.message}`);
42
+ return {};
43
+ }
44
+ }
45
+ function saveState(serverName, state) {
46
+ const p = storePath(serverName);
47
+ mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
48
+ writeFileSync(p, JSON.stringify(state, null, 2), { mode: 0o600 });
49
+ }
50
+ async function openBrowser(url) {
51
+ // Prefer the platform native opener so unusual environments (corporate
52
+ // wrappers, WSL, headless ssh-with-X-forward) still work when they have it.
53
+ const cmd = process.platform === 'darwin' ? `open "${url}"` :
54
+ process.platform === 'win32' ? `start "" "${url}"` :
55
+ `xdg-open "${url}"`;
56
+ try {
57
+ await execAsync(cmd);
58
+ }
59
+ catch (err) {
60
+ logger.warn(`[mcp:oauth] couldn't open browser automatically: ${err.message}`);
61
+ }
62
+ }
63
+ /**
64
+ * Bind a one-shot HTTP listener on the redirect URL's port and resolve when
65
+ * the authorization-code callback arrives. Returns the parsed `code`.
66
+ *
67
+ * `expectedState` is the `state` value the SDK embedded in the authorization
68
+ * URL. When present, the callback's `state` must match it — this is the OAuth
69
+ * 2.0 CSRF defense (RFC 6749 §10.12): a forged callback that doesn't echo our
70
+ * one-time state is rejected before the code is ever exchanged.
71
+ */
72
+ function waitForCallback(redirectUrl, expectedState, timeoutMs = 5 * 60_000) {
73
+ return new Promise((resolve, reject) => {
74
+ const port = redirectUrl.port ? Number(redirectUrl.port) : 80;
75
+ const expectedPath = redirectUrl.pathname || '/';
76
+ const server = createServer((req, res) => {
77
+ try {
78
+ const url = new URL(req.url || '/', `http://${req.headers.host}`);
79
+ if (url.pathname !== expectedPath) {
80
+ res.statusCode = 404;
81
+ res.end('Not Found');
82
+ return;
83
+ }
84
+ const code = url.searchParams.get('code');
85
+ const error = url.searchParams.get('error');
86
+ const state = url.searchParams.get('state') || undefined;
87
+ if (error) {
88
+ res.statusCode = 400;
89
+ res.end(`Authorization failed: ${error}`);
90
+ server.close();
91
+ reject(new Error(`OAuth callback returned error=${error}`));
92
+ return;
93
+ }
94
+ if (expectedState !== undefined && state !== expectedState) {
95
+ // CSRF guard: ignore (don't close) so the genuine callback can still
96
+ // arrive; only the real redirect carries our one-time state.
97
+ res.statusCode = 400;
98
+ res.end('State mismatch');
99
+ logger.warn('[mcp:oauth] rejected callback with mismatched state (possible CSRF)');
100
+ return;
101
+ }
102
+ if (!code) {
103
+ res.statusCode = 400;
104
+ res.end('Missing code');
105
+ return;
106
+ }
107
+ res.statusCode = 200;
108
+ res.setHeader('Content-Type', 'text/html; charset=utf-8');
109
+ res.end('<html><body><h2>Authorization complete — you can close this tab.</h2></body></html>');
110
+ server.close();
111
+ resolve({ code, state });
112
+ }
113
+ catch (err) {
114
+ res.statusCode = 500;
115
+ res.end('Internal error');
116
+ server.close();
117
+ reject(err);
118
+ }
119
+ });
120
+ server.on('error', reject);
121
+ server.listen(port, '127.0.0.1');
122
+ setTimeout(() => {
123
+ try {
124
+ server.close();
125
+ }
126
+ catch { /* ignore */ }
127
+ reject(new Error(`OAuth callback timeout after ${(timeoutMs / 1000).toFixed(0)}s`));
128
+ }, timeoutMs);
129
+ });
130
+ }
131
+ export async function createOAuthProvider(serverName, serverUrl, config) {
132
+ let state = loadState(serverName);
133
+ const callbackPort = 33761; // Fixed local port for Franklin's MCP OAuth callback.
134
+ const redirectUrl = `http://127.0.0.1:${callbackPort}/oauth/callback`;
135
+ const oauthOpts = typeof config.oauth === 'object' ? config.oauth : {};
136
+ const handle = {
137
+ isAuthorized: () => !!state.tokens?.access_token,
138
+ provider: {},
139
+ };
140
+ const provider = {
141
+ get redirectUrl() { return redirectUrl; },
142
+ get clientMetadata() {
143
+ return {
144
+ client_name: oauthOpts.clientName || `Franklin (${serverName})`,
145
+ redirect_uris: [redirectUrl],
146
+ grant_types: ['authorization_code', 'refresh_token'],
147
+ response_types: ['code'],
148
+ token_endpoint_auth_method: 'none',
149
+ scope: oauthOpts.scopes?.join(' '),
150
+ };
151
+ },
152
+ clientInformation() {
153
+ return state.clientInformation;
154
+ },
155
+ saveClientInformation(info) {
156
+ state = { ...state, clientInformation: info };
157
+ saveState(serverName, state);
158
+ },
159
+ tokens() {
160
+ return state.tokens;
161
+ },
162
+ saveTokens(tokens) {
163
+ const expiresAt = typeof tokens.expires_in === 'number' && tokens.expires_in > 0
164
+ ? Date.now() + tokens.expires_in * 1000
165
+ : undefined;
166
+ state = { ...state, tokens, expiresAt };
167
+ saveState(serverName, state);
168
+ logger.debug(`[mcp:oauth:${serverName}] tokens saved (expires in ${tokens.expires_in ?? 'n/a'}s)`);
169
+ },
170
+ saveCodeVerifier(codeVerifier) {
171
+ state = { ...state, codeVerifier };
172
+ saveState(serverName, state);
173
+ },
174
+ codeVerifier() {
175
+ if (!state.codeVerifier) {
176
+ throw new Error('OAuth code verifier missing — authorization not yet started');
177
+ }
178
+ return state.codeVerifier;
179
+ },
180
+ redirectToAuthorization(authorizationUrl) {
181
+ // Best-effort: start the callback listener, log + open browser. The SDK
182
+ // expects this to be fire-and-forget; the caller awaits `finishAuth`
183
+ // (which we expose via `handle.pendingCallback`) to actually finish.
184
+ logger.info(`[mcp:oauth:${serverName}] authorization required — opening browser to ${authorizationUrl.host}`);
185
+ console.error(`\n[Franklin MCP] '${serverName}' needs authorization. Opening browser to:\n ${authorizationUrl.toString()}\nIf the browser does not open, copy the URL manually.\n`);
186
+ const expectedState = authorizationUrl.searchParams.get('state') ?? undefined;
187
+ handle.pendingCallback = waitForCallback(new URL(redirectUrl), expectedState);
188
+ void openBrowser(authorizationUrl.toString());
189
+ },
190
+ };
191
+ handle.provider = provider;
192
+ void serverUrl; // silence unused (kept for future per-server policy)
193
+ return handle;
194
+ }
195
+ /**
196
+ * Standalone helper to drive an OAuth login outside the transport's normal
197
+ * flow — used by `franklin mcp login <name>` to refresh tokens before any
198
+ * connect attempt. Not wired by default; provided for the command layer.
199
+ */
200
+ export async function loginToMcpServer(_serverName, _config) {
201
+ // Implementation deferred to a follow-up — the transport's lazy OAuth flow
202
+ // already covers the first-time login path when the user runs `franklin
203
+ // start`. This stub exists so the CLI command surface is stable.
204
+ throw new Error('`franklin mcp login` not implemented — start a session and trigger the OAuth flow there for now.');
205
+ }
@@ -5,7 +5,7 @@
5
5
  * Plugins implement Workflow; core orchestrates execution and provides infrastructure.
6
6
  */
7
7
  export const DEFAULT_MODEL_TIERS = {
8
- free: 'nvidia/qwen3-coder-480b',
9
- cheap: 'nvidia/qwen3-coder-480b', // Free by default; opt-in to paid flat-rate via 'zai/glm-5.1'.
8
+ free: 'nvidia/llama-4-maverick',
9
+ cheap: 'nvidia/llama-4-maverick', // Free by default; opt-in to paid flat-rate via 'zai/glm-5.1'.
10
10
  premium: 'anthropic/claude-sonnet-4.6',
11
11
  };
package/dist/pricing.js CHANGED
@@ -81,10 +81,12 @@ export const MODEL_PRICING = {
81
81
  'minimax/minimax-m3': { input: 0.3, output: 1.2 },
82
82
  'minimax/minimax-m2.7': { input: 0.3, output: 1.2 },
83
83
  'minimax/minimax-m2.5': { input: 0.3, output: 1.2 },
84
- // Moonshot
84
+ // Moonshot — K2.7 is the gateway flagship (2026-06); K2.6 demoted but still
85
+ // routes, kept for the `k2.6` pin + legacy session-cost records.
86
+ 'moonshot/kimi-k2.7': { input: 0.95, output: 4.0 },
85
87
  'moonshot/kimi-k2.6': { input: 0.95, output: 4.0 },
86
88
  // Retired (kept for legacy session-cost records; the gateway no longer
87
- // serves these and the picker shortcuts now resolve to K2.6).
89
+ // serves these and the picker shortcuts now resolve to the current flagship).
88
90
  'moonshot/kimi-k2.5': { input: 0.6, output: 3.0 },
89
91
  'nvidia/kimi-k2.5': { input: 0.55, output: 2.5 },
90
92
  // PROMOTION (active ~2026-04): flat $0.001/call for all GLM models
@@ -7,7 +7,7 @@ export const DEFAULT_FALLBACK_CONFIG = {
7
7
  chain: [
8
8
  'deepseek/deepseek-chat', // Direct fallback — cheap & reliable
9
9
  'google/gemini-2.5-flash', // Fast & capable
10
- 'nvidia/qwen3-coder-480b', // Free model as ultimate fallback
10
+ 'nvidia/llama-4-maverick', // Free model as ultimate fallback
11
11
  ],
12
12
  retryOn: [429, 500, 502, 503, 504, 529],
13
13
  maxRetries: 5,
@@ -141,18 +141,18 @@ const MODEL_SHORTCUTS = {
141
141
  deepseek: 'deepseek/deepseek-chat',
142
142
  r1: 'deepseek/deepseek-reasoner',
143
143
  // Free models (agent-tested gateway free tier — refreshed 2026-04)
144
- free: 'nvidia/qwen3-coder-480b',
145
- glm4: 'nvidia/qwen3-coder-480b',
146
- 'deepseek-free': 'nvidia/qwen3-coder-480b',
147
- 'qwen-coder': 'nvidia/qwen3-coder-480b',
148
- 'qwen-think': 'nvidia/qwen3-coder-480b',
144
+ free: 'nvidia/llama-4-maverick',
145
+ glm4: 'nvidia/llama-4-maverick',
146
+ 'deepseek-free': 'nvidia/llama-4-maverick',
147
+ 'qwen-coder': 'nvidia/llama-4-maverick',
148
+ 'qwen-think': 'nvidia/llama-4-maverick',
149
149
  maverick: 'nvidia/llama-4-maverick',
150
- 'gpt-oss': 'nvidia/qwen3-coder-480b',
151
- 'gpt-oss-small': 'nvidia/qwen3-coder-480b',
150
+ 'gpt-oss': 'nvidia/llama-4-maverick',
151
+ 'gpt-oss-small': 'nvidia/llama-4-maverick',
152
152
  'mistral-small': 'nvidia/llama-4-maverick',
153
153
  // Retired/unreliable gateway-model aliases (map to closest agent-tested current).
154
- nemotron: 'nvidia/qwen3-coder-480b',
155
- devstral: 'nvidia/qwen3-coder-480b',
154
+ nemotron: 'nvidia/llama-4-maverick',
155
+ devstral: 'nvidia/llama-4-maverick',
156
156
  // Minimax
157
157
  minimax: 'minimax/minimax-m3',
158
158
  'm3': 'minimax/minimax-m3',
@@ -161,11 +161,13 @@ const MODEL_SHORTCUTS = {
161
161
  glm: 'zai/glm-5.1',
162
162
  'glm-turbo': 'zai/glm-5-turbo',
163
163
  'glm5': 'zai/glm-5.1',
164
- kimi: 'moonshot/kimi-k2.6',
164
+ kimi: 'moonshot/kimi-k2.7',
165
+ 'k2.7': 'moonshot/kimi-k2.7',
166
+ // K2.6 demoted 2026-06 (flagship is K2.7) but still routes — `k2.6` pins it.
165
167
  'k2.6': 'moonshot/kimi-k2.6',
166
- // K2.5 retired by the gateway — aliases resolve to K2.6 for muscle memory.
167
- 'kimi-k2.5': 'moonshot/kimi-k2.6',
168
- 'k2.5': 'moonshot/kimi-k2.6',
168
+ // K2.5 retired — aliases resolve to the current flagship for muscle memory.
169
+ 'kimi-k2.5': 'moonshot/kimi-k2.7',
170
+ 'k2.5': 'moonshot/kimi-k2.7',
169
171
  };
170
172
  // Model pricing now uses shared source from src/pricing.ts
171
173
  function detectModelSwitch(parsed) {
@@ -45,7 +45,7 @@ function loadLearnedWeights() {
45
45
  const AUTO_TIERS = {
46
46
  SIMPLE: {
47
47
  primary: 'deepseek/deepseek-v4-pro',
48
- fallback: ['google/gemini-2.5-flash', 'moonshot/kimi-k2.6', 'deepseek/deepseek-chat'],
48
+ fallback: ['google/gemini-2.5-flash', 'moonshot/kimi-k2.7', 'deepseek/deepseek-chat'],
49
49
  },
50
50
  MEDIUM: {
51
51
  primary: 'deepseek/deepseek-v4-pro',
@@ -440,14 +440,14 @@ export async function routeRequestAsync(prompt, profile = 'auto', classify = llm
440
440
  */
441
441
  export function resolveTierToModel(tier, profile = 'auto', needsVision = false) {
442
442
  // Free profile short-circuits — everything routes to a single free model.
443
- // qwen3-coder-480b is text-only; on a vision turn the free profile can't
443
+ // llama-4-maverick is text-only; on a vision turn the free profile can't
444
444
  // help us. Caller should detect this and warn the user that Free won't
445
445
  // handle images — for now we just return the free pick and let the model
446
- // fail gracefully. (Open question: should we hard-fall to nvidia/llama-4-
447
- // maverick here? Skipped until we see a real user hit this path.)
446
+ // fail gracefully. (The only vision-capable free model is the Nemotron Omni
447
+ // line; revisit hard-falling to it if a real user hits this path.)
448
448
  if (profile === 'free') {
449
449
  return {
450
- model: 'nvidia/qwen3-coder-480b',
450
+ model: 'nvidia/llama-4-maverick',
451
451
  tier: 'SIMPLE',
452
452
  confidence: 1.0,
453
453
  signals: needsVision ? ['free-profile', 'vision-unsupported'] : ['free-profile'],
@@ -479,7 +479,7 @@ export function routeRequest(prompt, profile = 'auto', needsVision = false) {
479
479
  // Free profile — always use free model
480
480
  if (profile === 'free') {
481
481
  return {
482
- model: 'nvidia/qwen3-coder-480b',
482
+ model: 'nvidia/llama-4-maverick',
483
483
  tier: 'SIMPLE',
484
484
  confidence: 1.0,
485
485
  signals: needsVision ? ['free-profile', 'vision-unsupported'] : ['free-profile'],
@@ -569,27 +569,26 @@ export function getFallbackChain(tier, profile = 'auto') {
569
569
  // to keep the user moving without waiting for funding.
570
570
  //
571
571
  // The lists are ordered: best-fit free model first, then degraded fallbacks.
572
- // Coding goes to qwen3-coder; everything else (chat / trading / research /
573
- // reasoning / creative) prefers general-purpose free models that aren't
574
- // coder-tuned. Without this split, a BTC question that exhausted paid
575
- // models was being handed to qwen3-coder-480b — a coder model trying to
576
- // do technical analysis. Reported 2026-05-03 with a markets question
577
- // routed to a coder model on Sonnet failure.
572
+ // llama-4-maverick leads every category — it's the only reliably-healthy free
573
+ // model and covers chat / coding / reasoning. deepseek-v4-flash (1M ctx) is the
574
+ // secondary; it occasionally times out on the NVIDIA NIM upstream, so it sits
575
+ // behind maverick rather than leading.
578
576
  // 2026-06-07: nvidia/glm-4.7 dropped from every chain — NVIDIA NIM hung, the
579
- // gateway redirects it to qwen3-coder-480b (already present here), so routing to
580
- // it just wasted a slot and mislabeled the model. qwen3-coder-480b + llama-4-
581
- // maverick are both healthy and cover all categories.
577
+ // gateway redirected it to a now-dead model, so routing to it just wasted a slot.
578
+ // 2026-06-11: nvidia/qwen3-coder-480b removed — its upstream
579
+ // (qwen/qwen3-coder-480b-a35b-instruct) reached end-of-life and the gateway now
580
+ // 410s on it. maverick + deepseek-v4-flash cover all categories.
582
581
  const FREE_MODELS_BY_CATEGORY = {
583
- coding: ['nvidia/qwen3-coder-480b', 'nvidia/llama-4-maverick'],
584
- trading: ['nvidia/llama-4-maverick', 'nvidia/qwen3-coder-480b'],
585
- research: ['nvidia/llama-4-maverick', 'nvidia/qwen3-coder-480b'],
586
- reasoning: ['nvidia/llama-4-maverick', 'nvidia/qwen3-coder-480b'],
587
- chat: ['nvidia/llama-4-maverick', 'nvidia/qwen3-coder-480b'],
588
- creative: ['nvidia/llama-4-maverick', 'nvidia/qwen3-coder-480b'],
582
+ coding: ['nvidia/llama-4-maverick', 'nvidia/deepseek-v4-flash'],
583
+ trading: ['nvidia/llama-4-maverick', 'nvidia/deepseek-v4-flash'],
584
+ research: ['nvidia/llama-4-maverick', 'nvidia/deepseek-v4-flash'],
585
+ reasoning: ['nvidia/llama-4-maverick', 'nvidia/deepseek-v4-flash'],
586
+ chat: ['nvidia/llama-4-maverick', 'nvidia/deepseek-v4-flash'],
587
+ creative: ['nvidia/llama-4-maverick', 'nvidia/deepseek-v4-flash'],
589
588
  };
590
589
  const DEFAULT_FREE_CHAIN = [
591
590
  'nvidia/llama-4-maverick',
592
- 'nvidia/qwen3-coder-480b',
591
+ 'nvidia/deepseek-v4-flash',
593
592
  ];
594
593
  /**
595
594
  * Pick the next free model to try given the question category and which
@@ -41,7 +41,8 @@ const VISION_MODELS = new Set([
41
41
  // xAI — only Grok 4 base supports vision; grok-4-1-fast-reasoning is text-only
42
42
  'xai/grok-4-0709',
43
43
  'xai/grok-3',
44
- // Moonshot — K2.6 added vision + reasoning when it replaced K2.5
44
+ // Moonshot — K2.7 (flagship) + K2.6 are multimodal (image + video input)
45
+ 'moonshot/kimi-k2.7',
45
46
  'moonshot/kimi-k2.6',
46
47
  // NVIDIA inference — Llama 4 Maverick is multimodal; deepseek/qwen-coder are not
47
48
  'nvidia/llama-4-maverick',
@@ -1,16 +1,25 @@
1
1
  /**
2
- * Boot-time helpers that wire the skills library into the running process:
2
+ * Boot-time helpers that wire the skills library into the running process.
3
3
  *
4
- * - `loadBundledSkills()` discovers `dist/skills-bundled/<name>/SKILL.md`
5
- * relative to this module's location and returns a populated Registry.
6
- * User-global and project-local discovery are deferred to Phase 2 of the
7
- * skills MVP plan; today we only ship the bundled set.
4
+ * Skills come from four sources, in order of precedence (project > user >
5
+ * learned > bundled). The same `SKILL.md` format is used for all four;
6
+ * the Registry resolves any name conflict and reports shadows for the
7
+ * `/skills` panel.
8
8
  *
9
- * - `getSkillVars()` returns the synchronously-known runtime variables
10
- * that `substituteVariables` injects into a skill body before
11
- * `$ARGUMENTS` expansion. Async values (wallet balance, on-chain reads)
12
- * are deferred to a later phase: those vars stay literal in the rendered
13
- * prompt and `substituteVariables` leaves unknown vars intact.
9
+ * bundled — `dist/skills-bundled/<name>/SKILL.md` (shipped with Franklin)
10
+ * learned — `~/.blockrun/skills/learned/<id>/SKILL.md` (auto-generated by
11
+ * the learnings/extractor when a session yields a reusable
12
+ * procedure). Same disk format as the others — `hidden: true`
13
+ * keeps them out of `/help` but they still participate in
14
+ * trigger matching.
15
+ * user — `~/.blockrun/skills/<name>/SKILL.md` (hand-authored per user)
16
+ * project — `<workDir>/.franklin/skills/<name>/SKILL.md`
17
+ * and `<workDir>/.skills/<name>/SKILL.md`
18
+ *
19
+ * `getSkillVars` returns the runtime variables that
20
+ * `substituteVariables` injects into a skill body before `$ARGUMENTS`
21
+ * expansion. Only sync values live here; async (wallet balance, on-chain
22
+ * reads) are deferred and the substituter leaves unknown vars literal.
14
23
  */
15
24
  import { Registry } from './registry.js';
16
25
  import type { LoadError } from './types.js';
@@ -18,7 +27,23 @@ export interface BundledLoad {
18
27
  registry: Registry;
19
28
  errors: LoadError[];
20
29
  }
30
+ export interface AllSkillsLoad extends BundledLoad {
31
+ /** Per-source counts for the `/mcp` and `/skills` status surfaces. */
32
+ counts: Record<string, number>;
33
+ }
34
+ /** Backwards-compatible alias: load only the bundled set. Callers should
35
+ * prefer `loadAllSkills(workDir)` to pick up user/project overrides. */
21
36
  export declare function loadBundledSkills(): BundledLoad;
37
+ /**
38
+ * Discover every skill the user can run in this directory. Sources are
39
+ * unioned; the Registry resolves name collisions by source precedence
40
+ * (project > user > learned > bundled).
41
+ */
42
+ export declare function loadAllSkills(workDir: string): AllSkillsLoad;
43
+ /** Ensure the user-global skills root exists so `~/.blockrun/skills/<name>/`
44
+ * edits don't fail with ENOENT. Idempotent. */
45
+ export declare function ensureUserSkillsDir(): string;
46
+ export declare function ensureLearnedSkillsDir(): string;
22
47
  export interface SkillVarSource {
23
48
  chain?: 'base' | 'solana';
24
49
  }
@@ -1,29 +1,106 @@
1
1
  /**
2
- * Boot-time helpers that wire the skills library into the running process:
2
+ * Boot-time helpers that wire the skills library into the running process.
3
3
  *
4
- * - `loadBundledSkills()` discovers `dist/skills-bundled/<name>/SKILL.md`
5
- * relative to this module's location and returns a populated Registry.
6
- * User-global and project-local discovery are deferred to Phase 2 of the
7
- * skills MVP plan; today we only ship the bundled set.
4
+ * Skills come from four sources, in order of precedence (project > user >
5
+ * learned > bundled). The same `SKILL.md` format is used for all four;
6
+ * the Registry resolves any name conflict and reports shadows for the
7
+ * `/skills` panel.
8
8
  *
9
- * - `getSkillVars()` returns the synchronously-known runtime variables
10
- * that `substituteVariables` injects into a skill body before
11
- * `$ARGUMENTS` expansion. Async values (wallet balance, on-chain reads)
12
- * are deferred to a later phase: those vars stay literal in the rendered
13
- * prompt and `substituteVariables` leaves unknown vars intact.
9
+ * bundled — `dist/skills-bundled/<name>/SKILL.md` (shipped with Franklin)
10
+ * learned — `~/.blockrun/skills/learned/<id>/SKILL.md` (auto-generated by
11
+ * the learnings/extractor when a session yields a reusable
12
+ * procedure). Same disk format as the others — `hidden: true`
13
+ * keeps them out of `/help` but they still participate in
14
+ * trigger matching.
15
+ * user — `~/.blockrun/skills/<name>/SKILL.md` (hand-authored per user)
16
+ * project — `<workDir>/.franklin/skills/<name>/SKILL.md`
17
+ * and `<workDir>/.skills/<name>/SKILL.md`
18
+ *
19
+ * `getSkillVars` returns the runtime variables that
20
+ * `substituteVariables` injects into a skill body before `$ARGUMENTS`
21
+ * expansion. Only sync values live here; async (wallet balance, on-chain
22
+ * reads) are deferred and the substituter leaves unknown vars literal.
14
23
  */
15
24
  import { fileURLToPath } from 'node:url';
16
25
  import { dirname, join } from 'node:path';
26
+ import { existsSync, mkdirSync } from 'node:fs';
17
27
  import { loadSkillsFromDir } from './loader.js';
18
28
  import { Registry } from './registry.js';
29
+ import { BLOCKRUN_DIR } from '../config.js';
30
+ import { migrateLegacyLearnedSkills } from '../learnings/store.js';
19
31
  const HERE = dirname(fileURLToPath(import.meta.url));
20
32
  // Built form lives at dist/skills/bootstrap.js, so dist/skills-bundled/
21
33
  // is one level up + sibling.
22
34
  const BUNDLED_DIR = join(HERE, '..', 'skills-bundled');
35
+ const USER_SKILLS_DIR = join(BLOCKRUN_DIR, 'skills');
36
+ const LEARNED_SKILLS_DIR = join(USER_SKILLS_DIR, 'learned');
37
+ function projectSkillDirs(workDir) {
38
+ return [
39
+ join(workDir, '.franklin', 'skills'),
40
+ join(workDir, '.skills'),
41
+ ];
42
+ }
43
+ /** Backwards-compatible alias: load only the bundled set. Callers should
44
+ * prefer `loadAllSkills(workDir)` to pick up user/project overrides. */
23
45
  export function loadBundledSkills() {
24
46
  const result = loadSkillsFromDir(BUNDLED_DIR, 'bundled');
25
47
  return { registry: Registry.fromLoaded(result.skills), errors: result.errors };
26
48
  }
49
+ /**
50
+ * Discover every skill the user can run in this directory. Sources are
51
+ * unioned; the Registry resolves name collisions by source precedence
52
+ * (project > user > learned > bundled).
53
+ */
54
+ export function loadAllSkills(workDir) {
55
+ const errors = [];
56
+ const all = [];
57
+ const counts = {};
58
+ // Fold any pre-unified-registry flat learned-skill files
59
+ // (`~/.blockrun/skills/<name>.md`) into the new `learned/<name>/SKILL.md`
60
+ // layout so upgrading users don't lose accumulated skills. No-op once done.
61
+ try {
62
+ migrateLegacyLearnedSkills();
63
+ }
64
+ catch { /* migration is best-effort */ }
65
+ const sources = [
66
+ { dir: BUNDLED_DIR, source: 'bundled' },
67
+ { dir: LEARNED_SKILLS_DIR, source: 'learned' },
68
+ { dir: USER_SKILLS_DIR, source: 'user' },
69
+ ...projectSkillDirs(workDir).map((dir) => ({ dir, source: 'project' })),
70
+ ];
71
+ for (const { dir, source } of sources) {
72
+ // user-global dir contains the `learned/` subdirectory — when loading
73
+ // user-source, skip the learned subdirectory so it isn't loaded twice
74
+ // with the wrong source label.
75
+ if (source === 'user' && dir === USER_SKILLS_DIR) {
76
+ const result = loadSkillsFromDir(dir, source);
77
+ const filtered = result.skills.filter((l) => !l.path.startsWith(LEARNED_SKILLS_DIR));
78
+ all.push(...filtered);
79
+ errors.push(...result.errors);
80
+ counts[source] = (counts[source] ?? 0) + filtered.length;
81
+ continue;
82
+ }
83
+ const result = loadSkillsFromDir(dir, source);
84
+ all.push(...result.skills);
85
+ errors.push(...result.errors);
86
+ counts[source] = (counts[source] ?? 0) + result.skills.length;
87
+ }
88
+ return { registry: Registry.fromLoaded(all), errors, counts };
89
+ }
90
+ /** Ensure the user-global skills root exists so `~/.blockrun/skills/<name>/`
91
+ * edits don't fail with ENOENT. Idempotent. */
92
+ export function ensureUserSkillsDir() {
93
+ if (!existsSync(USER_SKILLS_DIR)) {
94
+ mkdirSync(USER_SKILLS_DIR, { recursive: true });
95
+ }
96
+ return USER_SKILLS_DIR;
97
+ }
98
+ export function ensureLearnedSkillsDir() {
99
+ if (!existsSync(LEARNED_SKILLS_DIR)) {
100
+ mkdirSync(LEARNED_SKILLS_DIR, { recursive: true });
101
+ }
102
+ return LEARNED_SKILLS_DIR;
103
+ }
27
104
  export function getSkillVars(src) {
28
105
  const out = {};
29
106
  if (src.chain)
@@ -46,6 +46,18 @@ export function parseSkill(content) {
46
46
  if (Array.isArray(fields.triggers)) {
47
47
  skill.triggers = fields.triggers.filter((t) => typeof t === 'string');
48
48
  }
49
+ if (typeof fields.hidden === 'boolean') {
50
+ skill.hidden = fields.hidden;
51
+ }
52
+ if (typeof fields['auto-generated'] === 'boolean') {
53
+ skill.autoGenerated = fields['auto-generated'];
54
+ }
55
+ if (typeof fields['source-session'] === 'string') {
56
+ skill.sourceSession = fields['source-session'];
57
+ }
58
+ if (typeof fields.uses === 'number') {
59
+ skill.uses = fields.uses;
60
+ }
49
61
  return { skill, warnings };
50
62
  }
51
63
  function extractFrontmatter(content) {
@@ -3,7 +3,7 @@
3
3
  * lookup, list, and shadow-set queries for `/help` and
4
4
  * `franklin skills list`.
5
5
  *
6
- * Precedence: project > user > bundled. Within the same source, the first
6
+ * Precedence: project > user > learned > bundled. Within the same source, the first
7
7
  * loaded skill wins so that the order returned by the loader (which is
8
8
  * filesystem-ordered) is the deterministic tiebreaker the user can rely on.
9
9
  *
@@ -3,7 +3,7 @@
3
3
  * lookup, list, and shadow-set queries for `/help` and
4
4
  * `franklin skills list`.
5
5
  *
6
- * Precedence: project > user > bundled. Within the same source, the first
6
+ * Precedence: project > user > learned > bundled. Within the same source, the first
7
7
  * loaded skill wins so that the order returned by the loader (which is
8
8
  * filesystem-ordered) is the deterministic tiebreaker the user can rely on.
9
9
  *
@@ -12,8 +12,9 @@
12
12
  * `src/agent/commands.ts`. The registry never sees the built-in list.
13
13
  */
14
14
  const SOURCE_PRIORITY = {
15
- project: 3,
16
- user: 2,
15
+ project: 4,
16
+ user: 3,
17
+ learned: 2,
17
18
  bundled: 1,
18
19
  };
19
20
  export class Registry {