@blockrun/franklin 3.15.43 → 3.15.45

package/dist/brain/extract.js

@@ -2,7 +2,7 @@
  * 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';
+import { loadEntities, saveEntities, upsertEntity, addObservation, upsertRelation, isJunkEntityName, } from './store.js';
 const EXTRACTION_MODELS = [
     'google/gemini-2.5-flash-lite',
     'google/gemini-2.5-flash',
@@ -25,8 +25,9 @@ Also extract relationships between entities:
 Rules:
 - Only extract entities with CLEAR evidence in the conversation.
 - Do NOT extract the AI agent itself or generic concepts ("TypeScript", "JavaScript").
+- Do NOT extract programmatic strings that happen to appear in the transcript: tool permission patterns like "Bash(git commit:*)", object URIs (gs://, s3://, file://), glob patterns (paths with **), task IDs (t_xxx_xxx), session IDs, or hashes/UUIDs.
 - DO extract specific people, specific projects, specific companies, specific products.
-- Observations should be concrete facts, not vague descriptions.
+- Observations must be concrete facts about the entity that would be useful in a future conversation. Do NOT include tautologies that restate the entity name ("This is a task ID for an ETL process") or generic statements that apply to any instance of the type.
 - If no entities are found, return empty arrays.
 
 Respond with ONLY a JSON object (no markdown fences):
@@ -69,7 +70,8 @@ function parseExtraction(raw) {
         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))
+            typeof e.type === 'string' && VALID_TYPES.has(e.type) &&
+            !isJunkEntityName(e.name))
             .map((e) => ({
             name: e.name.slice(0, 100),
             type: e.type,

package/dist/brain/store.d.ts

@@ -3,6 +3,21 @@
  * All in-memory with JSONL persistence. No database.
  */
 import type { Entity, EntityType, Observation, Relation } from './types.js';
+export declare function isJunkEntityName(name: string): boolean;
+/**
+ * Remove existing junk entities (and their observations + relations)
+ * from disk. Called once per session start by runDataHygiene to clear
+ * accumulated low-quality extractions from earlier brain runs that
+ * predate the post-extraction filter.
+ *
+ * Returns counts so the hygiene report can surface the cleanup —
+ * silent purges are hard to verify.
+ */
+export declare function pruneJunkBrainEntries(): {
+    entitiesRemoved: number;
+    observationsRemoved: number;
+    relationsRemoved: number;
+};
 export declare function loadEntities(): Entity[];
 export declare function saveEntities(entities: Entity[]): void;
 /**

package/dist/brain/store.js

@@ -25,6 +25,77 @@ function uid() { return crypto.randomBytes(8).toString('hex'); }
 function ensureDir() {
     fs.mkdirSync(BRAIN_DIR, { recursive: true });
 }
+// Names the extractor model emits but that aren't real entities — they're
+// programmatic strings that happened to be in the transcript. Verified
+// 2026-05-04 on a real machine: 7 of 44 entities (16%) were junk by these
+// patterns — `Bash(git commit:*)` (tool permission), `gs://bucket/path/**`
+// (object URI + glob), `t_morkaf83_f03a0b10` (Franklin task runId tagged
+// as "project"). The vacuous observations they then accumulated ("This is
+// a task ID for an ETL process") leaked back into context on every later
+// session. Keep the patterns conservative — anything that looks
+// programmatic rather than nameable.
+const JUNK_ENTITY_NAME_PATTERNS = [
+    /^[A-Z][a-zA-Z]*\(.*\)$/, // Tool-permission shape, e.g. Bash(...), Edit(...)
+    /^(?:gs|s3|file|https?):\/\//i, // URIs
+    /\*\*?(?:\/|$)/, // Glob patterns
+    /^t_[a-z0-9]+_[a-z0-9]{6,}$/i, // Franklin task runIds
+    /^run_[a-z0-9_-]+$/i, // Generic run/job ids
+    /^session-\d{4}-/, // Session ids
+    /^[0-9a-f]{16,}$/, // Hex hashes / commit shas / uuids without dashes
+];
+export function isJunkEntityName(name) {
+    const trimmed = name.trim();
+    if (trimmed.length < 2)
+        return true;
+    return JUNK_ENTITY_NAME_PATTERNS.some(rx => rx.test(trimmed));
+}
+/**
+ * Remove existing junk entities (and their observations + relations)
+ * from disk. Called once per session start by runDataHygiene to clear
+ * accumulated low-quality extractions from earlier brain runs that
+ * predate the post-extraction filter.
+ *
+ * Returns counts so the hygiene report can surface the cleanup —
+ * silent purges are hard to verify.
+ */
+export function pruneJunkBrainEntries() {
+    const result = { entitiesRemoved: 0, observationsRemoved: 0, relationsRemoved: 0 };
+    let entities;
+    try {
+        entities = loadEntities();
+    }
+    catch {
+        return result;
+    }
+    if (entities.length === 0)
+        return result;
+    const junkIds = new Set();
+    const surviving = [];
+    for (const e of entities) {
+        if (isJunkEntityName(e.name)) {
+            junkIds.add(e.id);
+            result.entitiesRemoved++;
+        }
+        else {
+            surviving.push(e);
+        }
+    }
+    if (junkIds.size === 0)
+        return result;
+    // Drop observations + relations referencing the junk entities.
+    const obs = loadJsonl(OBSERVATIONS_FILE);
+    const survivingObs = obs.filter(o => !junkIds.has(o.entity_id));
+    result.observationsRemoved = obs.length - survivingObs.length;
+    const rels = loadJsonl(RELATIONS_FILE);
+    const survivingRels = rels.filter(r => !junkIds.has(r.from_id) && !junkIds.has(r.to_id));
+    result.relationsRemoved = rels.length - survivingRels.length;
+    // Atomic rewrites — saveJsonl uses tmp + rename so a crash mid-purge
+    // leaves the prior state intact.
+    saveEntities(surviving);
+    saveJsonl(OBSERVATIONS_FILE, survivingObs);
+    saveJsonl(RELATIONS_FILE, survivingRels);
+    return result;
+}
 // ─── Generic JSONL helpers ────────────────────────────────────────────────
 function loadJsonl(file) {
     try {

package/dist/storage/hygiene.d.ts

@@ -32,6 +32,7 @@ export interface HygieneReport {
     dataFilesTrimmed: number;
     costLogRowsTrimmed: number;
     orphanToolResultsRemoved: number;
+    brainJunkEntitiesRemoved: number;
 }
 /**
  * Top-level entry. Call once at agent session start. Catches its own

package/dist/storage/hygiene.js

@@ -24,6 +24,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { BLOCKRUN_DIR } from '../config.js';
+import { pruneJunkBrainEntries } from '../brain/store.js';
 // Retention knobs. Tuned conservatively — a power user with 50+ calls/day
 // for 30 days still fits in DATA_DIR_MAX_FILES, and 5000 cost-log entries
 // covers months of normal use without truncating the running totals.
@@ -49,6 +50,7 @@ const ZERO_REPORT = {
     dataFilesTrimmed: 0,
     costLogRowsTrimmed: 0,
     orphanToolResultsRemoved: 0,
+    brainJunkEntitiesRemoved: 0,
 };
 /**
  * Top-level entry. Call once at agent session start. Catches its own
@@ -75,6 +77,10 @@ export function runDataHygiene() {
         report.orphanToolResultsRemoved = sweepOrphanToolResults();
     }
     catch { /* best effort */ }
+    try {
+        report.brainJunkEntitiesRemoved = pruneJunkBrainEntries().entitiesRemoved;
+    }
+    catch { /* best effort */ }
     return report;
 }
 function trimDataDir() {

package/dist/tools/imagegen.js

@@ -258,7 +258,29 @@ function buildExecute(deps) {
             const result = await response.json();
             const imageData = result.data?.[0];
             if (!imageData) {
-                return { output: 'No image data returned from API', isError: true };
+                // Some gateways return 200 with an `error` / `message` field for
+                // moderation, quota, or upstream-model failures instead of using
+                // HTTP error codes. Without surfacing those, the agent sees only
+                // "No image data returned from API" and starts guessing — verified
+                // 2026-05-04: agent guessed "gpt-image-2 is forced to 1024x1024
+                // per the tool docs" and burned a retry on a size param that
+                // wasn't the actual cause. Surface the diagnostic so the agent
+                // (or user) can react.
+                const bits = [];
+                if (result.error !== undefined) {
+                    bits.push(`error=${JSON.stringify(result.error).slice(0, 240)}`);
+                }
+                if (result.message !== undefined) {
+                    bits.push(`message=${String(result.message).slice(0, 240)}`);
+                }
+                if (Array.isArray(result.data) && result.data.length === 0) {
+                    bits.push('data=[] (empty array — likely content moderation)');
+                }
+                else if (result.data === undefined) {
+                    bits.push('data field missing');
+                }
+                const detail = bits.length > 0 ? ` — ${bits.join('; ')}` : '';
+                return { output: `No image data returned from API${detail}`, isError: true };
             }
             // Save image. The /v1/images/image2image endpoint returns Gemini results
             // as a data URI in `url`, so decode those locally instead of going through

package/dist/tools/videogen.js

@@ -192,7 +192,18 @@ function buildExecute(deps) {
             ctx.abortSignal.removeEventListener('abort', submitAbort);
         }
         if (!submitResult.poll_url || !paymentHeaders) {
-            return { output: 'API did not return a poll_url for the video job', isError: true };
+            // Surface any diagnostic the body contained — same rationale as
+            // imagegen.ts: "missing field" tells the agent nothing about
+            // whether it was moderation, quota, or upstream model failure.
+            const bits = [];
+            if (!paymentHeaders)
+                bits.push('payment headers missing');
+            if (submitResult?.error !== undefined)
+                bits.push(`error=${JSON.stringify(submitResult.error).slice(0, 240)}`);
+            if (submitResult?.message !== undefined)
+                bits.push(`message=${String(submitResult.message).slice(0, 240)}`);
+            const detail = bits.length > 0 ? ` — ${bits.join('; ')}` : '';
+            return { output: `API did not return a poll_url for the video job${detail}`, isError: true };
         }
         // Phase 2: poll GET /v1/videos/generations/{id} with the SAME signed
         // x-payment header until the job completes. Server settles on the first
@@ -218,7 +229,17 @@ function buildExecute(deps) {
         const videoData = outcome.data;
         const videoUrl = videoData.url;
         if (!videoUrl) {
-            return { output: 'No video URL returned from API', isError: true };
+            // Same diagnostic pattern as the submit-side path above.
+            const d = videoData;
+            const bits = [];
+            if (d.error !== undefined)
+                bits.push(`error=${JSON.stringify(d.error).slice(0, 240)}`);
+            if (d.message !== undefined)
+                bits.push(`message=${String(d.message).slice(0, 240)}`);
+            if (d.status !== undefined)
+                bits.push(`status=${String(d.status).slice(0, 80)}`);
+            const detail = bits.length > 0 ? ` — ${bits.join('; ')}` : '';
+            return { output: `No video URL returned from API${detail}`, isError: true };
         }
         try {
             // Download the MP4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.15.43",
+  "version": "3.15.45",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {