@blockrun/franklin 3.7.9 → 3.8.0

package/dist/content/library.d.ts

@@ -0,0 +1,63 @@
+export type ContentType = 'x-thread' | 'blog' | 'podcast' | 'video' | 'ad-copy' | 'image';
+export type ContentStatus = 'outline' | 'drafting' | 'assets' | 'review' | 'published';
+export type AssetKind = 'image' | 'audio' | 'video' | 'text';
+export interface ContentAsset {
+    kind: AssetKind;
+    /** Producer of the asset: model ID like "openai/dall-e-3", or "manual". */
+    source: string;
+    /** USD actually spent producing this asset. 0 is valid (free models). */
+    costUsd: number;
+    /** Optional payload reference — URL, file path, or short inline text. */
+    data?: string;
+    createdAt: number;
+}
+export interface ContentDraft {
+    text: string;
+    createdAt: number;
+}
+export interface DistributionEntry {
+    channel: string;
+    url?: string;
+    at: number;
+}
+export interface Content {
+    id: string;
+    type: ContentType;
+    title: string;
+    status: ContentStatus;
+    outline?: string;
+    drafts: ContentDraft[];
+    assets: ContentAsset[];
+    spentUsd: number;
+    budgetUsd: number;
+    createdAt: number;
+    publishedAt?: number;
+    distribution: DistributionEntry[];
+}
+export interface CreateContentOptions {
+    type: ContentType;
+    title: string;
+    budgetUsd: number;
+}
+export declare class ContentLibrary {
+    private byId;
+    create(opts: CreateContentOptions): Content;
+    get(id: string): Content | undefined;
+    list(): Content[];
+    /** Replace a content record wholesale — used by the persistence layer. */
+    restore(content: Content): void;
+    /**
+     * Record a generated asset against a content, enforcing the budget cap.
+     * Returns `{ ok: false, reason }` on rejection so callers (including the
+     * agent-facing capability) can surface the reason instead of catching an
+     * exception. On the happy path mutates the Content in place and returns
+     * the updated spendUsd.
+     */
+    addAsset(id: string, asset: Omit<ContentAsset, 'createdAt'>): {
+        ok: true;
+        spentUsd: number;
+    } | {
+        ok: false;
+        reason: string;
+    };
+}

package/dist/content/library.js

@@ -0,0 +1,75 @@
+/**
+ * ContentLibrary — persistent, cross-session state for content generation work.
+ *
+ * Mirrors the Trading vertical: Library is the state object, Budget is the
+ * risk engine, store.ts is the persistence adapter, and tools/content-execute.ts
+ * wires everything into agent-facing capabilities.
+ *
+ * Why this exists: Claude Code / Cursor cannot carry a content project across
+ * sessions. If you start drafting a podcast episode Monday and come back
+ * Wednesday, there's no concept of *the same* piece of work. Franklin tracks
+ * outline → drafts → assets → distribution as one durable object and lets
+ * the agent spend USDC (image generation, audio, stock footage) against a
+ * budget that survives session boundaries.
+ */
+import { randomUUID } from 'node:crypto';
+export class ContentLibrary {
+    byId = new Map();
+    create(opts) {
+        if (opts.budgetUsd < 0) {
+            throw new Error('budgetUsd must be non-negative');
+        }
+        const now = Date.now();
+        const content = {
+            id: randomUUID(),
+            type: opts.type,
+            title: opts.title,
+            status: 'outline',
+            drafts: [],
+            assets: [],
+            spentUsd: 0,
+            budgetUsd: opts.budgetUsd,
+            createdAt: now,
+            distribution: [],
+        };
+        this.byId.set(content.id, content);
+        return content;
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    list() {
+        return [...this.byId.values()].sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /** Replace a content record wholesale — used by the persistence layer. */
+    restore(content) {
+        this.byId.set(content.id, content);
+    }
+    /**
+     * Record a generated asset against a content, enforcing the budget cap.
+     * Returns `{ ok: false, reason }` on rejection so callers (including the
+     * agent-facing capability) can surface the reason instead of catching an
+     * exception. On the happy path mutates the Content in place and returns
+     * the updated spendUsd.
+     */
+    addAsset(id, asset) {
+        const content = this.byId.get(id);
+        if (!content) {
+            return { ok: false, reason: `Content ${id} not found` };
+        }
+        if (asset.costUsd < 0) {
+            return { ok: false, reason: 'costUsd must be non-negative' };
+        }
+        const projected = content.spentUsd + asset.costUsd;
+        if (projected > content.budgetUsd + 1e-9) {
+            return {
+                ok: false,
+                reason: `Exceeds budget: spent $${content.spentUsd.toFixed(2)} + proposed ` +
+                    `$${asset.costUsd.toFixed(2)} > cap $${content.budgetUsd.toFixed(2)}`,
+            };
+        }
+        content.assets.push({ ...asset, createdAt: Date.now() });
+        content.spentUsd = projected;
+        return { ok: true, spentUsd: projected };
+    }
+}

package/dist/content/record-image.d.ts

@@ -0,0 +1,43 @@
+/**
+ * recordImageAsset — wire an ImageGen result into a Content piece's budget.
+ *
+ * The ImageGen tool closes the loop between spending USDC and tracking it
+ * against a content project. When the agent generates a hero image for a
+ * piece of content, this helper:
+ *   1. Estimates the USD cost from model + size (see image-pricing.ts).
+ *   2. Calls ContentLibrary.addAsset, which enforces the per-piece budget.
+ *   3. Returns a structured decision so the caller (imagegen.ts) can format
+ *      a human-readable summary without swallowing budget refusals.
+ *
+ * This lives in `content/` on purpose — it's content-bookkeeping logic that
+ * happens to be triggered from the ImageGen tool, not an ImageGen detail.
+ */
+import type { ContentLibrary } from './library.js';
+export interface RecordImageAssetInput {
+    contentId: string;
+    imagePath: string;
+    model: string;
+    size: string;
+}
+export type RecordImageDecision = {
+    ok: true;
+    costUsd: number;
+    spentUsd: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Pre-flight budget check. Run this BEFORE hitting the image-generation
+ * endpoint so the agent doesn't spend real USDC on a fill it then can't
+ * book against the content's budget. Returns `{ ok: true }` when the
+ * estimated cost fits; `{ ok: false, reason }` when it doesn't or the
+ * content doesn't exist. Non-mutating.
+ */
+export declare function checkImageBudget(library: ContentLibrary, contentId: string, model: string, size: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function recordImageAsset(library: ContentLibrary, input: RecordImageAssetInput): RecordImageDecision;

package/dist/content/record-image.js

@@ -0,0 +1,50 @@
+/**
+ * recordImageAsset — wire an ImageGen result into a Content piece's budget.
+ *
+ * The ImageGen tool closes the loop between spending USDC and tracking it
+ * against a content project. When the agent generates a hero image for a
+ * piece of content, this helper:
+ *   1. Estimates the USD cost from model + size (see image-pricing.ts).
+ *   2. Calls ContentLibrary.addAsset, which enforces the per-piece budget.
+ *   3. Returns a structured decision so the caller (imagegen.ts) can format
+ *      a human-readable summary without swallowing budget refusals.
+ *
+ * This lives in `content/` on purpose — it's content-bookkeeping logic that
+ * happens to be triggered from the ImageGen tool, not an ImageGen detail.
+ */
+import { estimateImageCostUsd } from './image-pricing.js';
+/**
+ * Pre-flight budget check. Run this BEFORE hitting the image-generation
+ * endpoint so the agent doesn't spend real USDC on a fill it then can't
+ * book against the content's budget. Returns `{ ok: true }` when the
+ * estimated cost fits; `{ ok: false, reason }` when it doesn't or the
+ * content doesn't exist. Non-mutating.
+ */
+export function checkImageBudget(library, contentId, model, size) {
+    const content = library.get(contentId);
+    if (!content) {
+        return { ok: false, reason: `Content ${contentId} not found` };
+    }
+    const cost = estimateImageCostUsd(model, size);
+    if (content.spentUsd + cost > content.budgetUsd + 1e-9) {
+        return {
+            ok: false,
+            reason: `Would exceed budget: spent $${content.spentUsd.toFixed(2)} + estimated ` +
+                `$${cost.toFixed(2)} > cap $${content.budgetUsd.toFixed(2)}`,
+        };
+    }
+    return { ok: true };
+}
+export function recordImageAsset(library, input) {
+    const costUsd = estimateImageCostUsd(input.model, input.size);
+    const result = library.addAsset(input.contentId, {
+        kind: 'image',
+        source: input.model,
+        costUsd,
+        data: input.imagePath,
+    });
+    if (!result.ok) {
+        return { ok: false, reason: result.reason };
+    }
+    return { ok: true, costUsd, spentUsd: result.spentUsd };
+}

package/dist/content/store.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Persistence for ContentLibrary. Whole-library JSON snapshot (vs the
+ * trade log's append-only JSONL) because content records are mutable
+ * throughout their life — new drafts, new assets, status transitions —
+ * so append-only would require replaying every edit on load. A single
+ * re-written JSON file is simpler and content volume is orders of
+ * magnitude smaller than a trade log.
+ *
+ * Disk failures and corruption are always survivable: save is
+ * best-effort, load returns `null` on any error so the agent falls back
+ * to a fresh in-memory library rather than refusing to start.
+ */
+import { ContentLibrary } from './library.js';
+export declare function saveLibrary(lib: ContentLibrary, filePath: string): void;
+export declare function loadLibrary(filePath: string): ContentLibrary | null;

package/dist/content/store.js

@@ -0,0 +1,55 @@
+/**
+ * Persistence for ContentLibrary. Whole-library JSON snapshot (vs the
+ * trade log's append-only JSONL) because content records are mutable
+ * throughout their life — new drafts, new assets, status transitions —
+ * so append-only would require replaying every edit on load. A single
+ * re-written JSON file is simpler and content volume is orders of
+ * magnitude smaller than a trade log.
+ *
+ * Disk failures and corruption are always survivable: save is
+ * best-effort, load returns `null` on any error so the agent falls back
+ * to a fresh in-memory library rather than refusing to start.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { ContentLibrary } from './library.js';
+export function saveLibrary(lib, filePath) {
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        const payload = { version: 1, contents: lib.list() };
+        writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf-8');
+    }
+    catch {
+        // Persistence is best-effort; never block a capability call on disk
+        // failure. The in-memory library stays authoritative until the next
+        // successful save.
+    }
+}
+export function loadLibrary(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+        if (raw?.version !== 1 || !Array.isArray(raw.contents))
+            return null;
+        const lib = new ContentLibrary();
+        for (const c of raw.contents) {
+            // Defensive — skip records missing the load-bearing fields rather than
+            // importing partially-shaped data.
+            if (typeof c?.id !== 'string' ||
+                typeof c?.title !== 'string' ||
+                typeof c?.budgetUsd !== 'number' ||
+                typeof c?.spentUsd !== 'number' ||
+                !Array.isArray(c?.assets) ||
+                !Array.isArray(c?.drafts) ||
+                !Array.isArray(c?.distribution)) {
+                continue;
+            }
+            lib.restore(c);
+        }
+        return lib;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/pricing.d.ts

@@ -7,7 +7,7 @@ export declare const MODEL_PRICING: Record<string, {
     output: number;
     perCall?: number;
 }>;
-/** Opus pricing for savings calculations */
+/** Opus pricing for savings calculations — tracks the current flagship. */
 export declare const OPUS_PRICING: {
     input: number;
     output: number;

package/dist/pricing.js

@@ -22,8 +22,8 @@ export const MODEL_PRICING = {
     'nvidia/llama-4-maverick': { input: 0, output: 0 },
     // Anthropic
     'anthropic/claude-sonnet-4.6': { input: 3.0, output: 15.0 },
-    'anthropic/claude-opus-4.6': { input: 5.0, output: 25.0 },
     'anthropic/claude-opus-4.7': { input: 5.0, output: 25.0 },
+    'anthropic/claude-opus-4.6': { input: 5.0, output: 25.0 },
     'anthropic/claude-haiku-4.5': { input: 1.0, output: 5.0 },
     'anthropic/claude-haiku-4.5-20251001': { input: 1.0, output: 5.0 },
     // OpenAI
@@ -76,7 +76,7 @@ export const MODEL_PRICING = {
     'zai/glm-5-turbo': { input: 0, output: 0, perCall: 0.001 },
     'zai/glm-5.1-turbo': { input: 0, output: 0, perCall: 0.001 }, // client alias for zai/glm-5-turbo
 };
-/** Opus pricing for savings calculations */
+/** Opus pricing for savings calculations — tracks the current flagship. */
 export const OPUS_PRICING = MODEL_PRICING['anthropic/claude-opus-4.7'];
 /**
  * Estimate cost in USD for a request.

package/dist/router/index.js

@@ -35,6 +35,8 @@ function loadLearnedWeights() {
 // ─── Tier Model Configs ───
 // Agent-first defaults. Claude Sonnet 4.6 is the industry standard for multi-step
 // tool-use agent work; cheap models keep derailing on simple agent loops.
+// Each tier's fallback ends with a cheaper option so payment/quota failures
+// don't strand users on equally expensive alternatives.
 const AUTO_TIERS = {
     SIMPLE: {
         primary: 'google/gemini-2.5-flash',
@@ -42,15 +44,24 @@ const AUTO_TIERS = {
     },
     MEDIUM: {
         primary: 'anthropic/claude-sonnet-4.6',
-        fallback: ['openai/gpt-5.4', 'google/gemini-3.1-pro'],
+        fallback: ['openai/gpt-5.4', 'google/gemini-3.1-pro', 'moonshot/kimi-k2.5'],
     },
     COMPLEX: {
         primary: 'anthropic/claude-sonnet-4.6',
-        fallback: ['openai/gpt-5.4', 'anthropic/claude-opus-4.7'],
+        fallback: ['openai/gpt-5.4', 'anthropic/claude-opus-4.7', 'moonshot/kimi-k2.5'],
     },
     REASONING: {
+        // Opus 4.7: step-change improvement in agentic coding over 4.6 per
+        // Anthropic. Same price, same 200k ctx in Franklin's baseline, so
+        // swap is cost-neutral. 4.6 stays in the fallback chain in case of
+        // rollout delays on the gateway side.
         primary: 'anthropic/claude-opus-4.7',
-        fallback: ['openai/o3', 'xai/grok-4-1-fast-reasoning'],
+        fallback: [
+            'anthropic/claude-opus-4.6',
+            'openai/o3',
+            'xai/grok-4-1-fast-reasoning',
+            'deepseek/deepseek-reasoner',
+        ],
     },
 };
 const ECO_TIERS = {
@@ -82,11 +93,11 @@ const PREMIUM_TIERS = {
     },
     COMPLEX: {
         primary: 'anthropic/claude-opus-4.7',
-        fallback: ['openai/gpt-5.4', 'anthropic/claude-sonnet-4.6'],
+        fallback: ['anthropic/claude-opus-4.6', 'openai/gpt-5.4', 'anthropic/claude-sonnet-4.6'],
     },
     REASONING: {
-        primary: 'anthropic/claude-sonnet-4.6',
-        fallback: ['anthropic/claude-opus-4.7', 'openai/o3'],
+        primary: 'anthropic/claude-opus-4.7',
+        fallback: ['anthropic/claude-opus-4.6', 'anthropic/claude-sonnet-4.6', 'openai/o3'],
     },
 };
 // ─── Keywords for Classification ───

package/dist/tools/bash.d.ts

@@ -14,5 +14,13 @@ interface BackgroundTask {
 export declare function getBackgroundTask(id: string): BackgroundTask | undefined;
 /** List all background tasks. */
 export declare function listBackgroundTasks(): BackgroundTask[];
+/**
+ * Drop completed/failed task records. Running tasks are left in place —
+ * we have no safe way to terminate a spawned process from here, and killing
+ * one out from under a caller that may still be polling it would silently
+ * lose output. Callers starting a fresh session can still query prior
+ * running tasks by id if they need to; anything finished is gone.
+ */
+export declare function clearSessionState(): void;
 export declare const bashCapability: CapabilityHandler;
 export {};

package/dist/tools/bash.js

@@ -226,6 +226,19 @@ export function getBackgroundTask(id) {
 export function listBackgroundTasks() {
     return [...backgroundTasks.values()];
 }
+/**
+ * Drop completed/failed task records. Running tasks are left in place —
+ * we have no safe way to terminate a spawned process from here, and killing
+ * one out from under a caller that may still be polling it would silently
+ * lose output. Callers starting a fresh session can still query prior
+ * running tasks by id if they need to; anything finished is gone.
+ */
+export function clearSessionState() {
+    for (const [id, task] of backgroundTasks) {
+        if (task.status !== 'running')
+            backgroundTasks.delete(id);
+    }
+}
 const MAX_OUTPUT_BYTES = 512 * 1024; // 512KB capture buffer (prevents OOM)
 const MAX_RETURN_CHARS = 32_000; // 32KB return cap (~8,000 tokens) — prevents context bloat
 const DEFAULT_TIMEOUT_MS = 120_000; // 2 minutes

package/dist/tools/content-execute.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent-facing Content capabilities. Four tools, deliberately mirroring the
+ * Trading vertical's shape:
+ *
+ *   ContentCreate     — start a new piece with type/title/budgetUsd
+ *   ContentAddAsset   — record a generated asset (image/audio/etc.) with its
+ *                       cost; rejected (as normal text, not an error) if it
+ *                       would breach the per-piece budget
+ *   ContentShow       — dump a single piece's state as actionable markdown
+ *   ContentList       — summary of every piece, newest first
+ *
+ * This is the surface Claude Code and Cursor cannot cover: durable content
+ * state with autonomous spending gating. An agent can spin up "Franklin
+ * launch thread" with a $3 budget, hit DALL-E twice for hero images, blow
+ * the budget, read the refusal, pick a cheaper model, and continue — all
+ * without human intervention and with the project surviving to the next
+ * session.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+import type { ContentLibrary } from '../content/library.js';
+export interface ContentCapabilitiesDeps {
+    library: ContentLibrary;
+    /** Invoked after mutating calls so callers can persist to disk. */
+    onStateChange?: () => void | Promise<void>;
+}
+export declare function createContentCapabilities(deps: ContentCapabilitiesDeps): CapabilityHandler[];

package/dist/tools/content-execute.js

@@ -0,0 +1,212 @@
+/**
+ * Agent-facing Content capabilities. Four tools, deliberately mirroring the
+ * Trading vertical's shape:
+ *
+ *   ContentCreate     — start a new piece with type/title/budgetUsd
+ *   ContentAddAsset   — record a generated asset (image/audio/etc.) with its
+ *                       cost; rejected (as normal text, not an error) if it
+ *                       would breach the per-piece budget
+ *   ContentShow       — dump a single piece's state as actionable markdown
+ *   ContentList       — summary of every piece, newest first
+ *
+ * This is the surface Claude Code and Cursor cannot cover: durable content
+ * state with autonomous spending gating. An agent can spin up "Franklin
+ * launch thread" with a $3 budget, hit DALL-E twice for hero images, blow
+ * the budget, read the refusal, pick a cheaper model, and continue — all
+ * without human intervention and with the project surviving to the next
+ * session.
+ */
+const VALID_TYPES = [
+    'x-thread', 'blog', 'podcast', 'video', 'ad-copy', 'image',
+];
+const VALID_ASSET_KINDS = ['image', 'audio', 'video', 'text'];
+function formatUsd(n) {
+    const sign = n < 0 ? '-' : '';
+    return `${sign}$${Math.abs(n).toFixed(2)}`;
+}
+function formatAssetLine(a) {
+    const when = new Date(a.createdAt).toISOString().replace('T', ' ').slice(0, 16);
+    const data = a.data ? ` · ${a.data}` : '';
+    return `- ${when}  ${a.kind} via ${a.source} (${formatUsd(a.costUsd)})${data}`;
+}
+function formatContent(c) {
+    const lines = [];
+    lines.push(`## ${c.title}`);
+    lines.push(`- id: \`${c.id}\``);
+    lines.push(`- type: ${c.type}   status: ${c.status}`);
+    lines.push(`- budget: ${formatUsd(c.spentUsd)} spent / ${formatUsd(c.budgetUsd)} cap`);
+    lines.push(`- drafts: ${c.drafts.length}   assets: ${c.assets.length}`);
+    if (c.publishedAt) {
+        lines.push(`- published: ${new Date(c.publishedAt).toISOString()}`);
+    }
+    if (c.assets.length > 0) {
+        lines.push('');
+        lines.push('### Assets');
+        for (const a of c.assets)
+            lines.push(formatAssetLine(a));
+    }
+    return lines.join('\n');
+}
+export function createContentCapabilities(deps) {
+    const { library, onStateChange } = deps;
+    const contentCreate = {
+        spec: {
+            name: 'ContentCreate',
+            description: 'Start a new content piece with a budget. The piece is durable across ' +
+                'sessions. Use types: x-thread, blog, podcast, video, ad-copy, image. ' +
+                'Budget is a hard USD cap on asset spending for this piece.',
+            input_schema: {
+                type: 'object',
+                required: ['type', 'title', 'budgetUsd'],
+                properties: {
+                    type: { type: 'string', description: 'Content kind (x-thread, blog, podcast, video, ad-copy, image)' },
+                    title: { type: 'string', description: 'Human-readable title' },
+                    budgetUsd: { type: 'number', description: 'Hard USD spending cap for asset generation' },
+                },
+                additionalProperties: false,
+            },
+        },
+        concurrent: false,
+        async execute(input, _ctx) {
+            const rawType = String(input.type ?? '');
+            const title = String(input.title ?? '').trim();
+            const budgetUsd = Number(input.budgetUsd);
+            if (!VALID_TYPES.includes(rawType)) {
+                return {
+                    output: `Error: type must be one of ${VALID_TYPES.join(', ')}. Got "${rawType}".`,
+                    isError: true,
+                };
+            }
+            if (!title) {
+                return { output: 'Error: title is required.', isError: true };
+            }
+            if (!Number.isFinite(budgetUsd) || budgetUsd < 0) {
+                return { output: 'Error: budgetUsd must be a non-negative number.', isError: true };
+            }
+            const c = library.create({ type: rawType, title, budgetUsd });
+            if (onStateChange)
+                await onStateChange();
+            return {
+                output: `## Content created\n` +
+                    `- id: \`${c.id}\`\n` +
+                    `- title: ${c.title}\n` +
+                    `- type: ${c.type}\n` +
+                    `- budget: ${formatUsd(c.budgetUsd)} (spent ${formatUsd(c.spentUsd)})\n` +
+                    `- status: ${c.status}\n\n` +
+                    `Use this id with ContentAddAsset / ContentShow.`,
+            };
+        },
+    };
+    const contentAddAsset = {
+        spec: {
+            name: 'ContentAddAsset',
+            description: 'Record a generated asset (image, audio, video, or text) against a ' +
+                'content piece, debiting its budget. If the asset would exceed the ' +
+                'budget cap the call is refused and returned as a normal text result ' +
+                '— not an error — so the agent can read the refusal and try a cheaper ' +
+                'model. Cost must reflect what was actually spent (zero for free ' +
+                'models, positive for paid).',
+            input_schema: {
+                type: 'object',
+                required: ['id', 'kind', 'source', 'costUsd'],
+                properties: {
+                    id: { type: 'string', description: 'Content id returned by ContentCreate' },
+                    kind: { type: 'string', description: 'image, audio, video, or text' },
+                    source: { type: 'string', description: 'Generator model or "manual" (e.g. "openai/dall-e-3")' },
+                    costUsd: { type: 'number', description: 'Actual USD spent producing this asset' },
+                    data: { type: 'string', description: 'Optional URL or inline text reference to the asset' },
+                },
+                additionalProperties: false,
+            },
+        },
+        concurrent: false,
+        async execute(input, _ctx) {
+            const id = String(input.id ?? '').trim();
+            const kind = String(input.kind ?? '');
+            const source = String(input.source ?? '').trim();
+            const costUsd = Number(input.costUsd);
+            const data = input.data == null ? undefined : String(input.data);
+            if (!id)
+                return { output: 'Error: id is required.', isError: true };
+            if (!VALID_ASSET_KINDS.includes(kind)) {
+                return {
+                    output: `Error: kind must be one of ${VALID_ASSET_KINDS.join(', ')}. Got "${kind}".`,
+                    isError: true,
+                };
+            }
+            if (!source)
+                return { output: 'Error: source is required.', isError: true };
+            if (!Number.isFinite(costUsd) || costUsd < 0) {
+                return { output: 'Error: costUsd must be a non-negative number.', isError: true };
+            }
+            const decision = library.addAsset(id, { kind, source, costUsd, data });
+            if (!decision.ok) {
+                // Normal text: the agent should read this and adapt, not retry.
+                return { output: `## Asset rejected\n- ${decision.reason}` };
+            }
+            if (onStateChange)
+                await onStateChange();
+            const c = library.get(id);
+            return {
+                output: `## Asset recorded\n` +
+                    `- ${kind} via ${source}: ${formatUsd(costUsd)}\n` +
+                    `- Spent so far: ${formatUsd(c.spentUsd)} / ${formatUsd(c.budgetUsd)} cap\n` +
+                    `- Remaining: ${formatUsd(c.budgetUsd - c.spentUsd)}`,
+            };
+        },
+    };
+    const contentShow = {
+        spec: {
+            name: 'ContentShow',
+            description: 'Dump a single content piece\'s full state as markdown: title, budget, ' +
+                'assets, drafts, distribution, status. Use before deciding the next step ' +
+                'on a piece (another asset, draft revision, publish).',
+            input_schema: {
+                type: 'object',
+                required: ['id'],
+                properties: {
+                    id: { type: 'string', description: 'Content id' },
+                },
+                additionalProperties: false,
+            },
+        },
+        concurrent: true,
+        async execute(input, _ctx) {
+            const id = String(input.id ?? '').trim();
+            if (!id)
+                return { output: 'Error: id is required.', isError: true };
+            const c = library.get(id);
+            if (!c)
+                return { output: `No content with id ${id}.` };
+            return { output: formatContent(c) };
+        },
+    };
+    const contentList = {
+        spec: {
+            name: 'ContentList',
+            description: 'List every content piece in the library (newest first) with its title, ' +
+                'status, and budget utilization. No inputs.',
+            input_schema: {
+                type: 'object',
+                properties: {},
+                additionalProperties: false,
+            },
+        },
+        concurrent: true,
+        async execute(_input, _ctx) {
+            const contents = library.list();
+            if (contents.length === 0) {
+                return { output: '_No content pieces yet. Use ContentCreate to start one._' };
+            }
+            const lines = ['## Content library', ''];
+            for (const c of contents) {
+                const pct = c.budgetUsd > 0 ? (c.spentUsd / c.budgetUsd) * 100 : 0;
+                lines.push(`- \`${c.id}\` · **${c.title}** · ${c.type}/${c.status} · ` +
+                    `${formatUsd(c.spentUsd)} / ${formatUsd(c.budgetUsd)} (${pct.toFixed(0)}%) ` +
+                    `· ${c.assets.length} assets`);
+            }
+            return { output: lines.join('\n') };
+        },
+    };
+    return [contentCreate, contentAddAsset, contentShow, contentList];
+}