@blockrun/franklin 3.3.3 → 3.5.1

package/dist/agent/tool-guard.js

@@ -0,0 +1,324 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_WEBSEARCHES_PER_TURN = 8;
+const MAX_SIMILAR_SEARCHES_PER_TURN = 4;
+const MAX_NO_SIGNAL_SEARCHES_PER_FAMILY = 2;
+const SEARCH_FAMILY_SIMILARITY = 0.58;
+const DUPLICATE_READ_TURN_WINDOW = 1;
+const DUPLICATE_FETCH_TURN_WINDOW = 1;
+const MAX_PREVIEW_CHARS = 320;
+const SEARCH_STOPWORDS = new Set([
+    'a', 'an', 'and', 'april', 'at', 'builder', 'builders', 'com', 'developer',
+    'developers', 'for', 'from', 'in', 'latest', 'live', 'may', 'of', 'on', 'or',
+    'post', 'posts', 'recent', 'reply', 'replies', 'site', 'status', 'the', 'to',
+    'tweet', 'tweets', 'via', 'x',
+]);
+function stemToken(token) {
+    let result = token.toLowerCase();
+    if (/^\d{4}$/.test(result))
+        return '';
+    if (result.endsWith('ing') && result.length > 6)
+        result = result.slice(0, -3);
+    else if (result.endsWith('ers') && result.length > 5)
+        result = result.slice(0, -3);
+    else if (result.endsWith('er') && result.length > 4)
+        result = result.slice(0, -2);
+    else if (result.endsWith('ed') && result.length > 4)
+        result = result.slice(0, -2);
+    else if (result.endsWith('es') && result.length > 4)
+        result = result.slice(0, -2);
+    else if (result.endsWith('s') && result.length > 4)
+        result = result.slice(0, -1);
+    return result;
+}
+export function normalizeSearchQuery(query) {
+    const tokens = query
+        .toLowerCase()
+        .replace(/https?:\/\/\S+/g, ' ')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(/\s+/)
+        .map(stemToken)
+        .filter((token) => token.length >= 2 && !SEARCH_STOPWORDS.has(token));
+    const normalized = [...new Set(tokens)].sort().join(' ');
+    return { normalized, tokens: [...new Set(tokens)] };
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const token of a) {
+        if (b.has(token))
+            intersection++;
+    }
+    const union = new Set([...a, ...b]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+function summarizeOutput(output) {
+    const compact = output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(0, 4)
+        .join('\n');
+    return compact.length > MAX_PREVIEW_CHARS
+        ? compact.slice(0, MAX_PREVIEW_CHARS - 3) + '...'
+        : compact;
+}
+function isNoSignalSearchResult(output, isError) {
+    const lower = output.toLowerCase();
+    return Boolean(isError ||
+        lower.startsWith('no results found for:') ||
+        lower.startsWith('no candidate posts found') ||
+        lower.startsWith('search timed out') ||
+        lower.startsWith('search error:') ||
+        lower.startsWith('searchx error:'));
+}
+function readKey(resolved, offset, limit) {
+    return `${resolved}::${offset ?? 1}::${limit ?? 2000}`;
+}
+function fetchKey(url, maxLength) {
+    return `${url}::${maxLength ?? 12288}`;
+}
+export class SessionToolGuard {
+    turn = 0;
+    webSearchesThisTurn = 0;
+    searchFamilies = [];
+    searchCache = new Map();
+    pendingSearches = new Map();
+    recentReads = new Map();
+    pendingReads = new Map();
+    recentFetches = new Map();
+    pendingFetches = new Map();
+    toolErrorCounts = new Map();
+    startTurn() {
+        this.turn++;
+        this.webSearchesThisTurn = 0;
+        for (const family of this.searchFamilies) {
+            family.turnSearches = 0;
+        }
+    }
+    async beforeExecute(invocation, scope) {
+        // Hard-block tools that have failed too many times this session
+        const errorCount = this.toolErrorCounts.get(invocation.name) ?? 0;
+        if (errorCount >= 3) {
+            return {
+                output: `${invocation.name} has failed ${errorCount} times this session and is now disabled. ` +
+                    'Tell the user what went wrong and suggest alternatives.',
+                isError: true,
+            };
+        }
+        switch (invocation.name) {
+            case 'WebSearch':
+            case 'SearchX':
+                return this.beforeWebSearch(invocation);
+            case 'Read':
+                return this.beforeRead(invocation, scope);
+            case 'WebFetch':
+                return this.beforeWebFetch(invocation);
+            default:
+                return null;
+        }
+    }
+    afterExecute(invocation, result) {
+        // Track per-tool error counts across the session
+        if (result.isError) {
+            this.toolErrorCounts.set(invocation.name, (this.toolErrorCounts.get(invocation.name) ?? 0) + 1);
+        }
+        switch (invocation.name) {
+            case 'WebSearch':
+            case 'SearchX':
+                this.afterWebSearch(invocation, result);
+                break;
+            case 'Read':
+                this.afterRead(invocation, result);
+                break;
+            case 'WebFetch':
+                this.afterWebFetch(invocation, result);
+                break;
+            default:
+                break;
+        }
+    }
+    cancelInvocation(invocationId) {
+        this.pendingSearches.delete(invocationId);
+        this.pendingReads.delete(invocationId);
+        this.pendingFetches.delete(invocationId);
+    }
+    beforeWebSearch(invocation) {
+        const query = String(invocation.input.query ?? '').trim();
+        const fingerprint = normalizeSearchQuery(query);
+        const normalized = fingerprint.normalized || query.toLowerCase().trim();
+        const cached = this.searchCache.get(normalized);
+        if (cached) {
+            const reason = cached.noSignal
+                ? 'That same WebSearch already returned no useful signal earlier in this session.'
+                : 'That same WebSearch already ran earlier in this session.';
+            return {
+                output: `${reason} Reuse the prior result already in context instead of searching again.\n\n` +
+                    `Previous search: ${cached.query}\n` +
+                    `Summary:\n${cached.preview}`,
+            };
+        }
+        if (this.webSearchesThisTurn >= MAX_WEBSEARCHES_PER_TURN) {
+            return {
+                output: `WebSearch budget reached for this turn (${MAX_WEBSEARCHES_PER_TURN} searches). ` +
+                    'Stop searching and synthesize the results already collected.',
+            };
+        }
+        let bestFamily = null;
+        let bestSimilarity = 0;
+        const tokenSet = new Set(fingerprint.tokens);
+        for (const family of this.searchFamilies) {
+            const similarity = jaccardSimilarity(tokenSet, family.tokens);
+            if (similarity > bestSimilarity) {
+                bestSimilarity = similarity;
+                bestFamily = family;
+            }
+        }
+        if (bestFamily && bestSimilarity >= SEARCH_FAMILY_SIMILARITY) {
+            if (bestFamily.noSignalSearches >= MAX_NO_SIGNAL_SEARCHES_PER_FAMILY) {
+                return {
+                    output: `Search stopped: ${bestFamily.noSignalSearches} similar WebSearch queries for this topic ` +
+                        `already returned empty or low-signal results.\n\n` +
+                        `Topic exemplar: ${bestFamily.exemplarQuery}\n` +
+                        'Present what you have instead of rephrasing the same search.',
+                };
+            }
+            if (bestFamily.turnSearches >= MAX_SIMILAR_SEARCHES_PER_TURN) {
+                return {
+                    output: `Search stopped: you already ran ${bestFamily.turnSearches} similar WebSearch queries ` +
+                        `for this topic in the current turn.\n\n` +
+                        `Topic exemplar: ${bestFamily.exemplarQuery}\n` +
+                        'Synthesize or switch to a materially different angle.',
+                };
+            }
+        }
+        const family = bestFamily && bestSimilarity >= SEARCH_FAMILY_SIMILARITY
+            ? bestFamily
+            : {
+                exemplarQuery: query,
+                tokens: tokenSet,
+                totalSearches: 0,
+                turnSearches: 0,
+                noSignalSearches: 0,
+            };
+        if (family === bestFamily) {
+            family.tokens = new Set([...family.tokens, ...tokenSet]);
+        }
+        else {
+            this.searchFamilies.push(family);
+        }
+        family.totalSearches++;
+        family.turnSearches++;
+        this.webSearchesThisTurn++;
+        this.pendingSearches.set(invocation.id, { normalized, family });
+        return null;
+    }
+    beforeRead(invocation, scope) {
+        const filePath = String(invocation.input.file_path ?? '');
+        if (!filePath)
+            return null;
+        const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(scope.workingDir, filePath);
+        let stat;
+        try {
+            stat = fs.statSync(resolved);
+        }
+        catch {
+            return null;
+        }
+        if (stat.isDirectory())
+            return null;
+        const offset = Number(invocation.input.offset ?? 1);
+        const limit = Number(invocation.input.limit ?? 2000);
+        const key = readKey(resolved, offset, limit);
+        const pending = [...this.pendingReads.values()].find((snapshot) => snapshot.key === key);
+        if (pending && pending.mtimeMs === stat.mtimeMs && pending.size === stat.size) {
+            return {
+                output: `Skipped duplicate Read of ${resolved}. The same file and line range is already being read ` +
+                    'in this turn, so reuse that content instead of reading it again.',
+            };
+        }
+        const previous = this.recentReads.get(key);
+        if (previous &&
+            this.turn - previous.turn <= DUPLICATE_READ_TURN_WINDOW &&
+            previous.mtimeMs === stat.mtimeMs &&
+            previous.size === stat.size) {
+            return {
+                output: `Skipped duplicate Read of ${resolved}. Same file and line range were already read ` +
+                    `${previous.turn === this.turn ? 'this turn' : 'in the previous turn'}, and the file has not changed.`,
+            };
+        }
+        this.pendingReads.set(invocation.id, {
+            key,
+            resolved,
+            offset,
+            limit,
+            turn: this.turn,
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+        });
+        return null;
+    }
+    beforeWebFetch(invocation) {
+        const url = String(invocation.input.url ?? '').trim();
+        if (!url)
+            return null;
+        const maxLength = Number(invocation.input.max_length ?? 12288);
+        const key = fetchKey(url, maxLength);
+        const pending = [...this.pendingFetches.values()].find((snapshot) => snapshot.key === key);
+        if (pending) {
+            return {
+                output: `Skipped duplicate WebFetch of ${url}. The same URL is already being fetched in this turn, ` +
+                    'so reuse that result instead of fetching it again.',
+            };
+        }
+        const previous = this.recentFetches.get(key);
+        if (previous && this.turn - previous.turn <= DUPLICATE_FETCH_TURN_WINDOW) {
+            return {
+                output: `Skipped duplicate WebFetch of ${url}. The same URL was already fetched recently in this session; ` +
+                    'reuse that content already in context instead of fetching it again.',
+            };
+        }
+        this.pendingFetches.set(invocation.id, {
+            key,
+            url,
+            maxLength,
+            turn: this.turn,
+        });
+        return null;
+    }
+    afterWebSearch(invocation, result) {
+        const pending = this.pendingSearches.get(invocation.id);
+        if (!pending)
+            return;
+        this.pendingSearches.delete(invocation.id);
+        const query = String(invocation.input.query ?? '').trim();
+        const noSignal = isNoSignalSearchResult(result.output, result.isError);
+        if (noSignal) {
+            pending.family.noSignalSearches++;
+        }
+        this.searchCache.set(pending.normalized, {
+            query,
+            preview: summarizeOutput(result.output),
+            noSignal,
+        });
+    }
+    afterRead(invocation, result) {
+        const pending = this.pendingReads.get(invocation.id);
+        if (!pending)
+            return;
+        this.pendingReads.delete(invocation.id);
+        if (result.isError)
+            return;
+        this.recentReads.set(pending.key, pending);
+    }
+    afterWebFetch(invocation, result) {
+        const pending = this.pendingFetches.get(invocation.id);
+        if (!pending)
+            return;
+        this.pendingFetches.delete(invocation.id);
+        if (result.isError)
+            return;
+        this.recentFetches.set(pending.key, pending);
+    }
+}

package/dist/agent/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Core types for the runcode agent system.
+ * Core types for the Franklin agent system.
  * All type names and structures are original designs.
  */
 export type Role = 'user' | 'assistant';
@@ -45,6 +45,8 @@ export interface CapabilityHandler {
     spec: CapabilityDefinition;
     execute(input: Record<string, unknown>, ctx: ExecutionScope): Promise<CapabilityResult>;
     concurrent?: boolean;
+    /** Dynamic concurrency check — called per-invocation. Overrides `concurrent` when provided. */
+    isConcurrentSafe?: (input: Record<string, unknown>) => boolean;
 }
 export interface CapabilityResult {
     output: string;
@@ -97,6 +99,10 @@ export interface StreamUsageInfo {
     outputTokens: number;
     model: string;
     calls: number;
+    tier?: 'SIMPLE' | 'MEDIUM' | 'COMPLEX' | 'REASONING';
+    confidence?: number;
+    savings?: number;
+    contextPct?: number;
 }
 export type StreamEvent = StreamTextDelta | StreamThinkingDelta | StreamCapabilityStart | StreamCapabilityInputDelta | StreamCapabilityProgress | StreamCapabilityDone | StreamTurnDone | StreamUsageInfo;
 export interface AgentConfig {

package/dist/agent/types.js

@@ -1,5 +1,5 @@
 /**
- * Core types for the runcode agent system.
+ * Core types for the Franklin agent system.
  * All type names and structures are original designs.
  */
 export {};

package/dist/brain/extract.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Franklin Brain — entity extraction from session traces.
+ * Uses cheap model to detect people, projects, companies from conversation.
+ */
+import { ModelClient } from '../agent/llm.js';
+import type { Dialogue } from '../agent/types.js';
+/**
+ * Extract entities from a session and store in the brain.
+ * Fire-and-forget — caller should not await.
+ */
+export declare function extractBrainEntities(history: Dialogue[], sessionId: string, client: ModelClient): Promise<number>;

package/dist/brain/extract.js

@@ -0,0 +1,154 @@
+/**
+ * Franklin Brain — entity extraction from session traces.
+ * Uses cheap model to detect people, projects, companies from conversation.
+ */
+import { loadEntities, saveEntities, upsertEntity, addObservation, upsertRelation, } from './store.js';
+const EXTRACTION_MODELS = [
+    'google/gemini-2.5-flash-lite',
+    'google/gemini-2.5-flash',
+    'nvidia/nemotron-super-49b',
+];
+const VALID_TYPES = new Set(['person', 'project', 'company', 'product', 'concept']);
+const BRAIN_PROMPT = `You are analyzing a conversation between a user and an AI agent. Extract entities (people, projects, companies, products, concepts) mentioned in the conversation.
+
+For each entity, provide:
+- name: canonical name (e.g. "Garry Tan" not "garry" or "Garry")
+- type: person | project | company | product | concept
+- aliases: other names used for the same entity (handles, abbreviations)
+- observations: 1-3 facts learned about this entity from the conversation
+
+Also extract relationships between entities:
+- from: entity name
+- to: entity name
+- type: founded | works_on | partnered_with | uses | mentioned | replied_to | depends_on
+
+Rules:
+- Only extract entities with CLEAR evidence in the conversation.
+- Do NOT extract the AI agent itself or generic concepts ("TypeScript", "JavaScript").
+- DO extract specific people, specific projects, specific companies, specific products.
+- Observations should be concrete facts, not vague descriptions.
+- If no entities are found, return empty arrays.
+
+Respond with ONLY a JSON object (no markdown fences):
+{"entities":[{"name":"...","type":"person","aliases":["@handle"],"observations":["Founded X in 2025"]}],"relations":[{"from":"Person","to":"Project","type":"founded"}]}`;
+function condenseForBrain(history) {
+    const parts = [];
+    let chars = 0;
+    for (const msg of history) {
+        if (chars >= 3000)
+            break;
+        let text = '';
+        if (typeof msg.content === 'string') {
+            text = msg.content;
+        }
+        else if (Array.isArray(msg.content)) {
+            text = msg.content
+                .filter(p => p.type === 'text')
+                .map(p => p.text ?? '')
+                .join('\n');
+        }
+        if (!text.trim())
+            continue;
+        if (text.length > 400)
+            text = text.slice(0, 400) + '…';
+        const role = msg.role === 'user' ? 'User' : 'Assistant';
+        const line = `${role}: ${text}`;
+        parts.push(line);
+        chars += line.length;
+    }
+    return parts.join('\n\n');
+}
+function parseExtraction(raw) {
+    let cleaned = raw.replace(/```json\s*/gi, '').replace(/```\s*/g, '').trim();
+    const start = cleaned.indexOf('{');
+    const end = cleaned.lastIndexOf('}');
+    if (start === -1 || end === -1)
+        return { entities: [], relations: [] };
+    cleaned = cleaned.slice(start, end + 1);
+    try {
+        const parsed = JSON.parse(cleaned);
+        const entities = (parsed.entities || [])
+            .filter((e) => typeof e.name === 'string' && e.name.length > 1 &&
+            typeof e.type === 'string' && VALID_TYPES.has(e.type))
+            .map((e) => ({
+            name: e.name.slice(0, 100),
+            type: e.type,
+            aliases: Array.isArray(e.aliases) ? e.aliases.slice(0, 5) : [],
+            observations: Array.isArray(e.observations)
+                ? e.observations.filter(o => typeof o === 'string' && o.length > 5).slice(0, 5)
+                : [],
+        }));
+        const relations = (parsed.relations || [])
+            .filter((r) => typeof r.from === 'string' && typeof r.to === 'string' && typeof r.type === 'string')
+            .map((r) => ({
+            from: r.from,
+            to: r.to,
+            type: r.type.slice(0, 30),
+        }));
+        return { entities, relations };
+    }
+    catch {
+        return { entities: [], relations: [] };
+    }
+}
+/**
+ * Extract entities from a session and store in the brain.
+ * Fire-and-forget — caller should not await.
+ */
+export async function extractBrainEntities(history, sessionId, client) {
+    if (history.length < 4)
+        return 0;
+    const condensed = condenseForBrain(history);
+    if (condensed.length < 80)
+        return 0;
+    let result = null;
+    for (const model of EXTRACTION_MODELS) {
+        try {
+            const response = await client.complete({
+                model,
+                messages: [{ role: 'user', content: condensed }],
+                system: BRAIN_PROMPT,
+                max_tokens: 1500,
+                temperature: 0.2,
+            });
+            const text = response.content
+                .filter(p => p.type === 'text')
+                .map(p => p.text ?? '')
+                .join('');
+            result = parseExtraction(text);
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!result || (result.entities.length === 0 && result.relations.length === 0))
+        return 0;
+    // Store entities + observations
+    const entities = loadEntities();
+    const nameToId = new Map();
+    for (const extracted of result.entities) {
+        const entityId = upsertEntity(entities, extracted.name, extracted.type, extracted.aliases);
+        nameToId.set(extracted.name.toLowerCase(), entityId);
+        for (const obs of extracted.observations) {
+            addObservation(entityId, obs, sessionId);
+        }
+    }
+    saveEntities(entities);
+    // Store relations
+    for (const rel of result.relations) {
+        const fromId = nameToId.get(rel.from.toLowerCase()) ||
+            findEntityIdByName(entities, rel.from);
+        const toId = nameToId.get(rel.to.toLowerCase()) ||
+            findEntityIdByName(entities, rel.to);
+        if (fromId && toId) {
+            upsertRelation(fromId, toId, rel.type);
+        }
+    }
+    return result.entities.length;
+}
+function findEntityIdByName(entities, name) {
+    const lower = name.toLowerCase();
+    return entities.find(e => e.name.toLowerCase() === lower ||
+        e.aliases.some(a => a.toLowerCase() === lower))?.id;
+}

package/dist/brain/index.d.ts

@@ -0,0 +1,3 @@
+export type { Entity, EntityType, Observation, Relation, BrainExtraction } from './types.js';
+export { loadEntities, saveEntities, findEntity, upsertEntity, loadObservations, getEntityObservations, addObservation, loadRelations, getEntityRelations, upsertRelation, searchEntities, buildEntityContext, getBrainStats, } from './store.js';
+export { extractBrainEntities } from './extract.js';

package/dist/brain/index.js

@@ -0,0 +1,2 @@
+export { loadEntities, saveEntities, findEntity, upsertEntity, loadObservations, getEntityObservations, addObservation, loadRelations, getEntityRelations, upsertRelation, searchEntities, buildEntityContext, getBrainStats, } from './store.js';
+export { extractBrainEntities } from './extract.js';

package/dist/brain/store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Franklin Brain — JSONL storage for entities, observations, relations.
+ * All in-memory with JSONL persistence. No database.
+ */
+import type { Entity, EntityType, Observation, Relation } from './types.js';
+export declare function loadEntities(): Entity[];
+export declare function saveEntities(entities: Entity[]): void;
+/**
+ * Find entity by name or alias (case-insensitive).
+ */
+export declare function findEntity(entities: Entity[], nameOrAlias: string): Entity | undefined;
+/**
+ * Create or update an entity. Returns the entity ID.
+ * If an entity with a matching name/alias exists, merges aliases and bumps reference_count.
+ */
+export declare function upsertEntity(entities: Entity[], name: string, type: EntityType, aliases?: string[]): string;
+export declare function loadObservations(): Observation[];
+export declare function getEntityObservations(entityId: string): Observation[];
+/**
+ * Add an observation. Deduplicates by content similarity (exact match).
+ */
+export declare function addObservation(entityId: string, content: string, source: string, confidence?: number, tags?: string[]): void;
+export declare function loadRelations(): Relation[];
+export declare function getEntityRelations(entityId: string): Relation[];
+/**
+ * Add or update a relation. If same from+to+type exists, bumps count.
+ */
+export declare function upsertRelation(fromId: string, toId: string, type: string, confidence?: number): void;
+/**
+ * Search entities by name/alias substring match.
+ */
+export declare function searchEntities(query: string, limit?: number): Entity[];
+/**
+ * Build context string for entities mentioned in the conversation.
+ * Returns empty string if no relevant entities found.
+ */
+export declare function buildEntityContext(mentionedNames: string[]): string;
+export declare function getBrainStats(): {
+    entities: number;
+    observations: number;
+    relations: number;
+};