@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.
- package/dist/agent/commands.js +37 -9
- package/dist/agent/compact.js +1 -1
- package/dist/agent/context.js +8 -14
- package/dist/agent/llm.js +3 -3
- package/dist/agent/loop.js +35 -7
- package/dist/agent/optimize.js +5 -5
- package/dist/agent/tokens.js +1 -0
- package/dist/agent/verification.js +1 -1
- package/dist/commands/skills.d.ts +1 -0
- package/dist/commands/skills.js +21 -5
- package/dist/commands/slack.js +1 -1
- package/dist/commands/social.js +1 -1
- package/dist/commands/telegram.js +1 -1
- package/dist/index.js +1 -0
- package/dist/learnings/extractor.js +2 -3
- package/dist/learnings/store.d.ts +25 -4
- package/dist/learnings/store.js +148 -39
- package/dist/mcp/client.d.ts +47 -29
- package/dist/mcp/client.js +288 -128
- package/dist/mcp/config.js +4 -0
- package/dist/mcp/oauth.d.ts +41 -0
- package/dist/mcp/oauth.js +205 -0
- package/dist/plugin-sdk/workflow.js +2 -2
- package/dist/pricing.js +4 -2
- package/dist/proxy/fallback.js +1 -1
- package/dist/proxy/server.js +15 -13
- package/dist/router/index.js +21 -22
- package/dist/router/vision.js +2 -1
- package/dist/skills/bootstrap.d.ts +35 -10
- package/dist/skills/bootstrap.js +87 -10
- package/dist/skills/loader.js +12 -0
- package/dist/skills/registry.d.ts +1 -1
- package/dist/skills/registry.js +4 -3
- package/dist/skills/triggers.d.ts +38 -0
- package/dist/skills/triggers.js +95 -0
- package/dist/skills/types.d.ts +14 -1
- package/dist/tools/moa.js +2 -3
- package/dist/tools/subagent.js +1 -1
- package/dist/ui/model-picker.js +25 -23
- package/package.json +1 -1
package/dist/learnings/store.js
CHANGED
|
@@ -158,25 +158,99 @@ export function formatForPrompt(learnings) {
|
|
|
158
158
|
return '# Personal Context\nLearned from previous sessions:\n\n' + sections.join('\n\n');
|
|
159
159
|
}
|
|
160
160
|
// ─── Skills (procedural memory) ──────────────────────────────────────────
|
|
161
|
-
//
|
|
162
|
-
//
|
|
161
|
+
//
|
|
162
|
+
// Auto-extracted "skills" from sessions are now stored under
|
|
163
|
+
// `~/.blockrun/skills/learned/<name>/SKILL.md` in the unified Anthropic
|
|
164
|
+
// SKILL.md format. The skills/ directory layout looks like:
|
|
165
|
+
//
|
|
166
|
+
// ~/.blockrun/skills/
|
|
167
|
+
// ├── my-handwritten/SKILL.md (user-authored)
|
|
168
|
+
// └── learned/
|
|
169
|
+
// ├── refactor-step-flow/SKILL.md (extracted by Franklin)
|
|
170
|
+
// └── pricing-quote-flow/SKILL.md
|
|
171
|
+
//
|
|
172
|
+
// The runtime registry (src/skills/bootstrap.loadAllSkills) discovers all
|
|
173
|
+
// three sources (bundled / learned / user / project) in one pass and
|
|
174
|
+
// trigger matching (src/skills/triggers.matchSkillTriggers) handles
|
|
175
|
+
// auto-invoke. The legacy `loadSkills`/`matchSkills`/`formatSkillsForPrompt`
|
|
176
|
+
// exports below are kept as compat shims (delegating to the new disk layout)
|
|
177
|
+
// so older callers don't break; new code should import from src/skills/.
|
|
163
178
|
const SKILLS_DIR = path.join(BLOCKRUN_DIR, 'skills');
|
|
164
|
-
const
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
fs.mkdirSync(SKILLS_DIR, { recursive: true });
|
|
179
|
+
const LEARNED_SKILLS_DIR = path.join(SKILLS_DIR, 'learned');
|
|
180
|
+
function ensureLearnedSkillsDir() {
|
|
181
|
+
if (!fs.existsSync(LEARNED_SKILLS_DIR)) {
|
|
182
|
+
fs.mkdirSync(LEARNED_SKILLS_DIR, { recursive: true });
|
|
169
183
|
}
|
|
170
184
|
}
|
|
171
|
-
/**
|
|
185
|
+
/**
|
|
186
|
+
* One-time migration of legacy auto-extracted skills.
|
|
187
|
+
*
|
|
188
|
+
* Before the unified registry, learned skills were flat markdown files at
|
|
189
|
+
* `~/.blockrun/skills/<name>.md`. The new layout expects
|
|
190
|
+
* `~/.blockrun/skills/learned/<name>/SKILL.md`, and the user-source loader
|
|
191
|
+
* only reads `<dir>/SKILL.md` — so the old flat files would be silently
|
|
192
|
+
* orphaned on upgrade. This moves each one into the new layout (normalizing
|
|
193
|
+
* it through `saveSkill`, which adds `hidden`/`auto-generated`) and deletes
|
|
194
|
+
* the old file. Idempotent and cheap: returns immediately when there are no
|
|
195
|
+
* flat `.md` files left to migrate.
|
|
196
|
+
*/
|
|
197
|
+
export function migrateLegacyLearnedSkills() {
|
|
198
|
+
let entries;
|
|
199
|
+
try {
|
|
200
|
+
entries = fs.readdirSync(SKILLS_DIR);
|
|
201
|
+
}
|
|
202
|
+
catch {
|
|
203
|
+
return 0; // no skills dir yet — nothing to migrate
|
|
204
|
+
}
|
|
205
|
+
const flatFiles = entries.filter((f) => f.endsWith('.md'));
|
|
206
|
+
if (flatFiles.length === 0)
|
|
207
|
+
return 0;
|
|
208
|
+
let migrated = 0;
|
|
209
|
+
for (const file of flatFiles) {
|
|
210
|
+
const oldPath = path.join(SKILLS_DIR, file);
|
|
211
|
+
try {
|
|
212
|
+
if (!fs.statSync(oldPath).isFile())
|
|
213
|
+
continue;
|
|
214
|
+
const raw = fs.readFileSync(oldPath, 'utf-8');
|
|
215
|
+
const skill = parseSkillFile(raw, file.replace(/\.md$/, ''));
|
|
216
|
+
if (!skill)
|
|
217
|
+
continue;
|
|
218
|
+
const destDir = path.join(LEARNED_SKILLS_DIR, safeDirName(skill.name));
|
|
219
|
+
// Don't clobber a skill already present in the new layout.
|
|
220
|
+
if (!fs.existsSync(path.join(destDir, 'SKILL.md'))) {
|
|
221
|
+
saveSkill(skill);
|
|
222
|
+
}
|
|
223
|
+
fs.rmSync(oldPath);
|
|
224
|
+
migrated++;
|
|
225
|
+
}
|
|
226
|
+
catch { /* skip unreadable/locked file */ }
|
|
227
|
+
}
|
|
228
|
+
return migrated;
|
|
229
|
+
}
|
|
230
|
+
function safeDirName(name) {
|
|
231
|
+
return name.replace(/[^a-z0-9-]/gi, '-').toLowerCase() || 'skill';
|
|
232
|
+
}
|
|
233
|
+
function escapeYamlValue(v) {
|
|
234
|
+
if (/[:#'"\n]/.test(v)) {
|
|
235
|
+
return JSON.stringify(v);
|
|
236
|
+
}
|
|
237
|
+
return v;
|
|
238
|
+
}
|
|
239
|
+
/** Load all learned skills from `~/.blockrun/skills/learned/`. */
|
|
172
240
|
export function loadSkills() {
|
|
173
|
-
|
|
241
|
+
ensureLearnedSkillsDir();
|
|
174
242
|
const skills = [];
|
|
175
243
|
try {
|
|
176
|
-
for (const
|
|
244
|
+
for (const entry of fs.readdirSync(LEARNED_SKILLS_DIR)) {
|
|
245
|
+
const dirPath = path.join(LEARNED_SKILLS_DIR, entry);
|
|
177
246
|
try {
|
|
178
|
-
|
|
179
|
-
|
|
247
|
+
if (!fs.statSync(dirPath).isDirectory())
|
|
248
|
+
continue;
|
|
249
|
+
const filePath = path.join(dirPath, 'SKILL.md');
|
|
250
|
+
if (!fs.existsSync(filePath))
|
|
251
|
+
continue;
|
|
252
|
+
const raw = fs.readFileSync(filePath, 'utf-8');
|
|
253
|
+
const skill = parseSkillFile(raw, entry);
|
|
180
254
|
if (skill)
|
|
181
255
|
skills.push(skill);
|
|
182
256
|
}
|
|
@@ -186,49 +260,79 @@ export function loadSkills() {
|
|
|
186
260
|
catch { /* dir doesn't exist yet */ }
|
|
187
261
|
return skills;
|
|
188
262
|
}
|
|
189
|
-
function parseSkillFile(raw) {
|
|
190
|
-
const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
|
|
263
|
+
function parseSkillFile(raw, fallbackName) {
|
|
264
|
+
const m = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
|
|
191
265
|
if (!m)
|
|
192
266
|
return null;
|
|
193
267
|
const fm = m[1];
|
|
194
|
-
const name = fm.match(/^name:\s*(.+)$/m)?.[1]?.trim() ||
|
|
268
|
+
const name = fm.match(/^name:\s*(.+)$/m)?.[1]?.trim() || fallbackName;
|
|
195
269
|
const description = fm.match(/^description:\s*(.+)$/m)?.[1]?.trim() || '';
|
|
196
|
-
|
|
197
|
-
|
|
270
|
+
// Triggers may be a YAML list (- "foo") OR a legacy inline form ([a, b]).
|
|
271
|
+
let triggers = [];
|
|
272
|
+
const inline = fm.match(/^triggers:\s*\[([^\]]*)\]/m)?.[1];
|
|
273
|
+
if (inline !== undefined) {
|
|
274
|
+
triggers = inline.split(',').map(t => t.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
|
|
275
|
+
}
|
|
276
|
+
else {
|
|
277
|
+
const lines = fm.split('\n');
|
|
278
|
+
const triggersIdx = lines.findIndex(l => /^triggers:\s*$/.test(l));
|
|
279
|
+
if (triggersIdx >= 0) {
|
|
280
|
+
for (let i = triggersIdx + 1; i < lines.length; i++) {
|
|
281
|
+
const m = lines[i].match(/^\s+-\s+(.+)$/);
|
|
282
|
+
if (!m)
|
|
283
|
+
break;
|
|
284
|
+
triggers.push(m[1].trim().replace(/^["']|["']$/g, ''));
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
}
|
|
198
288
|
const created = fm.match(/^created:\s*(.+)$/m)?.[1]?.trim() || '';
|
|
199
289
|
const uses = parseInt(fm.match(/^uses:\s*(\d+)$/m)?.[1] || '0');
|
|
200
|
-
const source = fm.match(/^
|
|
290
|
+
const source = fm.match(/^source(?:[-_]session):\s*(.+)$/m)?.[1]?.trim() || '';
|
|
201
291
|
if (!name)
|
|
202
292
|
return null;
|
|
203
293
|
return { name, description, triggers, steps: m[2].trim(), created, uses, source_session: source };
|
|
204
294
|
}
|
|
205
|
-
/** Save a new skill to disk. */
|
|
295
|
+
/** Save a new auto-extracted skill to disk in unified SKILL.md format. */
|
|
206
296
|
export function saveSkill(skill) {
|
|
207
|
-
|
|
208
|
-
const
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
`
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
297
|
+
ensureLearnedSkillsDir();
|
|
298
|
+
const dir = path.join(LEARNED_SKILLS_DIR, safeDirName(skill.name));
|
|
299
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
300
|
+
const fmLines = ['---'];
|
|
301
|
+
fmLines.push(`name: ${escapeYamlValue(skill.name)}`);
|
|
302
|
+
fmLines.push(`description: ${escapeYamlValue(skill.description)}`);
|
|
303
|
+
if (skill.triggers.length > 0) {
|
|
304
|
+
fmLines.push(`triggers:`);
|
|
305
|
+
for (const t of skill.triggers) {
|
|
306
|
+
fmLines.push(` - ${escapeYamlValue(t)}`);
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
fmLines.push(`hidden: true`);
|
|
310
|
+
fmLines.push(`auto-generated: true`);
|
|
311
|
+
if (skill.created)
|
|
312
|
+
fmLines.push(`created: ${skill.created}`);
|
|
313
|
+
fmLines.push(`uses: ${skill.uses}`);
|
|
314
|
+
if (skill.source_session) {
|
|
315
|
+
fmLines.push(`source-session: ${escapeYamlValue(skill.source_session)}`);
|
|
316
|
+
}
|
|
317
|
+
fmLines.push('---');
|
|
318
|
+
fmLines.push('');
|
|
319
|
+
fmLines.push(skill.steps);
|
|
320
|
+
fs.writeFileSync(path.join(dir, 'SKILL.md'), fmLines.join('\n') + '\n');
|
|
220
321
|
}
|
|
221
322
|
/** Bump use count for a skill. */
|
|
222
323
|
export function bumpSkillUse(skill) {
|
|
223
|
-
const
|
|
224
|
-
const fp = path.join(SKILLS_DIR, filename);
|
|
324
|
+
const filePath = path.join(LEARNED_SKILLS_DIR, safeDirName(skill.name), 'SKILL.md');
|
|
225
325
|
try {
|
|
226
|
-
const raw = fs.readFileSync(
|
|
227
|
-
fs.writeFileSync(
|
|
326
|
+
const raw = fs.readFileSync(filePath, 'utf-8');
|
|
327
|
+
fs.writeFileSync(filePath, raw.replace(/^uses:\s*\d+$/m, `uses: ${skill.uses + 1}`));
|
|
228
328
|
}
|
|
229
329
|
catch { /* non-critical */ }
|
|
230
330
|
}
|
|
231
|
-
/**
|
|
331
|
+
/**
|
|
332
|
+
* Compat shim retained so older callers keep working while the rest of the
|
|
333
|
+
* codebase migrates to `src/skills/triggers.ts`. New code should NOT depend
|
|
334
|
+
* on this — it ignores `hidden` and `disableModelInvocation` flags.
|
|
335
|
+
*/
|
|
232
336
|
export function matchSkills(input, skills) {
|
|
233
337
|
const lower = input.toLowerCase();
|
|
234
338
|
const scored = [];
|
|
@@ -244,12 +348,17 @@ export function matchSkills(input, skills) {
|
|
|
244
348
|
if (score > 0)
|
|
245
349
|
scored.push({ skill: s, score });
|
|
246
350
|
}
|
|
247
|
-
return scored.sort((a, b) => b.score - a.score).slice(0,
|
|
351
|
+
return scored.sort((a, b) => b.score - a.score).slice(0, 5).map(m => m.skill);
|
|
248
352
|
}
|
|
249
|
-
/**
|
|
353
|
+
/**
|
|
354
|
+
* Compat shim. The new code path injects skills per-turn via
|
|
355
|
+
* `formatSkillHints` rather than baking them into the boot-time system
|
|
356
|
+
* prompt, so callers should not need this any more.
|
|
357
|
+
*/
|
|
250
358
|
export function formatSkillsForPrompt(skills) {
|
|
251
359
|
if (skills.length === 0)
|
|
252
360
|
return '';
|
|
361
|
+
const MAX_SKILL_CHARS = 1500;
|
|
253
362
|
const parts = ['# Learned Skills\nProcedures from previous experience — use when relevant:\n'];
|
|
254
363
|
for (const s of skills) {
|
|
255
364
|
const body = s.steps.length > MAX_SKILL_CHARS ? s.steps.slice(0, MAX_SKILL_CHARS) + '\n…' : s.steps;
|
package/dist/mcp/client.d.ts
CHANGED
|
@@ -1,55 +1,73 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* MCP Client for Franklin.
|
|
3
|
+
*
|
|
3
4
|
* Connects to MCP servers, discovers tools, and wraps them as CapabilityHandlers.
|
|
4
|
-
* Supports
|
|
5
|
+
* Supports:
|
|
6
|
+
* - stdio transport (local subprocess)
|
|
7
|
+
* - StreamableHTTP transport (remote, with optional OAuth)
|
|
8
|
+
* - SSE transport (legacy remote)
|
|
9
|
+
*
|
|
10
|
+
* Per-server features:
|
|
11
|
+
* - `enabled_tools` / `disabled_tools` allowlist (mirrors Codex)
|
|
12
|
+
* - stderr piping into the franklin debug log so misconfigured servers can
|
|
13
|
+
* be diagnosed without dumping into the user's terminal
|
|
14
|
+
* - OAuth via the SDK's `OAuthClientProvider` contract; tokens persisted
|
|
15
|
+
* under `~/.blockrun/mcp/oauth/<server>.json`
|
|
16
|
+
* - connection status + last-error snapshot surfaced to `/mcp` command
|
|
5
17
|
*/
|
|
6
18
|
import type { CapabilityHandler } from '../agent/types.js';
|
|
7
19
|
export interface McpServerConfig {
|
|
8
|
-
/** Transport type
|
|
9
|
-
|
|
20
|
+
/** Transport type. `stdio` runs a local subprocess; `http` connects to a
|
|
21
|
+
* remote MCP server via StreamableHTTP (preferred) or SSE (legacy). */
|
|
22
|
+
transport: 'stdio' | 'http' | 'sse';
|
|
10
23
|
/** For stdio: command to run */
|
|
11
24
|
command?: string;
|
|
12
25
|
/** For stdio: arguments */
|
|
13
26
|
args?: string[];
|
|
14
|
-
/** For stdio: environment
|
|
27
|
+
/** For stdio / http: environment / extra headers passthrough */
|
|
15
28
|
env?: Record<string, string>;
|
|
16
|
-
/** For http: server URL */
|
|
29
|
+
/** For http / sse: server URL */
|
|
17
30
|
url?: string;
|
|
18
|
-
/** For http: headers */
|
|
31
|
+
/** For http / sse: static request headers (use OAuth for dynamic auth) */
|
|
19
32
|
headers?: Record<string, string>;
|
|
33
|
+
/** Allowlist: only expose these tool names to the model (post-discovery).
|
|
34
|
+
* Wildcards not supported — match by exact tool short name. */
|
|
35
|
+
enabled_tools?: string[];
|
|
36
|
+
/** Denylist: hide these tool names. Applied after `enabled_tools`. */
|
|
37
|
+
disabled_tools?: string[];
|
|
20
38
|
/** Human-readable label */
|
|
21
39
|
label?: string;
|
|
22
|
-
/** Disable this server */
|
|
40
|
+
/** Disable this server entirely */
|
|
23
41
|
disabled?: boolean;
|
|
42
|
+
/** Enable OAuth flow for http/sse transports. Set to a hint string
|
|
43
|
+
* (e.g. "interactive" or "device") or `true` for the default. */
|
|
44
|
+
oauth?: boolean | {
|
|
45
|
+
scopes?: string[];
|
|
46
|
+
clientName?: string;
|
|
47
|
+
};
|
|
24
48
|
}
|
|
25
49
|
export interface McpConfig {
|
|
26
50
|
mcpServers: Record<string, McpServerConfig>;
|
|
27
51
|
}
|
|
28
|
-
/**
|
|
29
|
-
* Connect to all configured MCP servers and return discovered tools.
|
|
30
|
-
* Each connection has a 5s timeout to avoid blocking startup.
|
|
31
|
-
*/
|
|
32
52
|
export declare function connectMcpServers(config: McpConfig, debug?: boolean): Promise<CapabilityHandler[]>;
|
|
33
|
-
/**
|
|
34
|
-
* Disconnect all MCP servers.
|
|
35
|
-
*/
|
|
36
53
|
export declare function disconnectMcpServers(): Promise<void>;
|
|
37
|
-
/**
|
|
38
|
-
* Aggregate server-level instructions from all connected MCP servers into a
|
|
39
|
-
* single system-prompt section, or '' if no server supplied any.
|
|
40
|
-
*
|
|
41
|
-
* These come from the `initialize` response of servers Franklin chose to
|
|
42
|
-
* connect (built-in, or user-configured + trusted), so they're treated as
|
|
43
|
-
* trusted guidance rather than untrusted data. The agent reads this once per
|
|
44
|
-
* session to learn each toolset's playbook (which tool for which question,
|
|
45
|
-
* common chains, anti-patterns) instead of rediscovering it by trial.
|
|
46
|
-
*/
|
|
47
54
|
export declare function getMcpServerInstructions(): string;
|
|
48
|
-
|
|
49
|
-
* List connected MCP servers and their tools.
|
|
50
|
-
*/
|
|
51
|
-
export declare function listMcpServers(): Array<{
|
|
55
|
+
export interface McpServerStatus {
|
|
52
56
|
name: string;
|
|
57
|
+
transport: 'stdio' | 'http' | 'sse';
|
|
53
58
|
toolCount: number;
|
|
54
59
|
tools: string[];
|
|
55
|
-
|
|
60
|
+
filtered: number;
|
|
61
|
+
hasOAuth: boolean;
|
|
62
|
+
oauthAuthorized: boolean;
|
|
63
|
+
}
|
|
64
|
+
export declare function listMcpServers(): McpServerStatus[];
|
|
65
|
+
export interface McpServerFailure {
|
|
66
|
+
name: string;
|
|
67
|
+
reason: string;
|
|
68
|
+
transport: 'stdio' | 'http' | 'sse';
|
|
69
|
+
stderrTail: string[];
|
|
70
|
+
}
|
|
71
|
+
export declare function listMcpFailures(): McpServerFailure[];
|
|
72
|
+
/** Most recent N stderr lines from a connected stdio MCP server (for `/mcp`). */
|
|
73
|
+
export declare function getMcpStderrTail(name: string): string[];
|