osborn 0.9.252-swap.0 → 0.9.252

package/dist/bridge-llm.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bridge LLM Module - Creates LLM instances for pipelined voice sessions
+ *
+ * In pipelined mode, we use a separate LLM (Gemini or GPT-4o) as the
+ * "conversation manager" that handles voice I/O and routes to Claude Code.
+ */
+import * as google from '@livekit/agents-plugin-google';
+import * as openai from '@livekit/agents-plugin-openai';
+export interface BridgeLLMConfig {
+    provider: 'gemini-pro' | 'gemini-flash' | 'gpt-4o' | 'gpt-4o-mini';
+    model?: string;
+}
+/**
+ * Create Bridge LLM instance for pipelined voice sessions
+ *
+ * Options:
+ * - gemini-pro: Gemini 2.5 Pro (smart, good reasoning)
+ * - gemini-flash: Gemini 2.0 Flash (faster, cheaper)
+ * - gpt-4o: GPT-4o (alternative if OpenAI preferred)
+ * - gpt-4o-mini: GPT-4o Mini (faster, cheaper)
+ */
+export declare function createBridgeLLM(config: BridgeLLMConfig): google.LLM | openai.LLM;

package/dist/bridge-llm.js

@@ -0,0 +1,39 @@
+/**
+ * Bridge LLM Module - Creates LLM instances for pipelined voice sessions
+ *
+ * In pipelined mode, we use a separate LLM (Gemini or GPT-4o) as the
+ * "conversation manager" that handles voice I/O and routes to Claude Code.
+ */
+import * as google from '@livekit/agents-plugin-google';
+import * as openai from '@livekit/agents-plugin-openai';
+/**
+ * Create Bridge LLM instance for pipelined voice sessions
+ *
+ * Options:
+ * - gemini-pro: Gemini 2.5 Pro (smart, good reasoning)
+ * - gemini-flash: Gemini 2.0 Flash (faster, cheaper)
+ * - gpt-4o: GPT-4o (alternative if OpenAI preferred)
+ * - gpt-4o-mini: GPT-4o Mini (faster, cheaper)
+ */
+export function createBridgeLLM(config) {
+    switch (config.provider) {
+        case 'gemini-pro':
+            return new google.LLM({
+                model: config.model || 'gemini-2.5-pro',
+            });
+        case 'gemini-flash':
+            return new google.LLM({
+                model: config.model || 'gemini-2.0-flash',
+            });
+        case 'gpt-4o':
+            return new openai.LLM({
+                model: config.model || 'gpt-4o',
+            });
+        case 'gpt-4o-mini':
+            return new openai.LLM({
+                model: config.model || 'gpt-4o-mini',
+            });
+        default:
+            throw new Error(`Unknown Bridge LLM provider: ${config.provider}`);
+    }
+}

package/dist/codex-handler.d.ts

@@ -0,0 +1,38 @@
+import { EventEmitter } from 'events';
+type SandboxMode = 'workspace-write' | 'danger-full-access';
+type ApprovalPolicy = 'on-failure' | 'on-request' | 'never';
+interface CodexHandlerOptions {
+    workingDirectory?: string;
+    skipGitRepoCheck?: boolean;
+    sandboxMode?: SandboxMode;
+    approvalPolicy?: ApprovalPolicy;
+}
+/**
+ * Codex Handler using the official OpenAI Codex SDK
+ *
+ * Features:
+ * - Thread persistence (reuses same thread for context)
+ * - Built-in coding tools (file operations, terminal commands)
+ * - Hooks for observability
+ *
+ * Requirements:
+ * - Codex CLI must be installed (npm install -g @openai/codex or use npx)
+ * - Must be authenticated via: codex login (ChatGPT) or OPENAI_API_KEY env var
+ *
+ * Sandbox/Approval modes are configured via:
+ * - ~/.codex/config.yaml for global settings
+ * - CLI flags: --sandbox, --approval-policy
+ *
+ * Note: The SDK spawns the CLI binary, so authentication must be done beforehand.
+ */
+export declare class CodexHandler extends EventEmitter {
+    private codex;
+    private thread;
+    private options;
+    constructor(options?: CodexHandlerOptions);
+    run(prompt: string): Promise<string>;
+    getThreadId(): string | null;
+    clearThread(): void;
+}
+export declare function askCodex(prompt: string, cwd?: string): Promise<string>;
+export {};

package/dist/codex-handler.js

@@ -0,0 +1,83 @@
+import { Codex } from '@openai/codex-sdk';
+import { EventEmitter } from 'events';
+/**
+ * Codex Handler using the official OpenAI Codex SDK
+ *
+ * Features:
+ * - Thread persistence (reuses same thread for context)
+ * - Built-in coding tools (file operations, terminal commands)
+ * - Hooks for observability
+ *
+ * Requirements:
+ * - Codex CLI must be installed (npm install -g @openai/codex or use npx)
+ * - Must be authenticated via: codex login (ChatGPT) or OPENAI_API_KEY env var
+ *
+ * Sandbox/Approval modes are configured via:
+ * - ~/.codex/config.yaml for global settings
+ * - CLI flags: --sandbox, --approval-policy
+ *
+ * Note: The SDK spawns the CLI binary, so authentication must be done beforehand.
+ */
+export class CodexHandler extends EventEmitter {
+    codex;
+    thread = null;
+    options;
+    constructor(options = {}) {
+        super();
+        this.options = {
+            workingDirectory: options.workingDirectory || process.cwd(),
+            skipGitRepoCheck: options.skipGitRepoCheck ?? true,
+        };
+        // Initialize Codex (inherits process env by default)
+        this.codex = new Codex();
+    }
+    async run(prompt) {
+        try {
+            // Create or reuse thread
+            if (!this.thread) {
+                console.log('🆕 Starting new Codex thread');
+                this.thread = this.codex.startThread({
+                    workingDirectory: this.options.workingDirectory,
+                    skipGitRepoCheck: this.options.skipGitRepoCheck,
+                });
+            }
+            else {
+                console.log('🔄 Continuing Codex thread');
+            }
+            console.log(`📁 CWD: ${this.options.workingDirectory}`);
+            this.emit('thinking', prompt);
+            // Run the prompt and get the Turn result
+            const turn = await this.thread.run(prompt);
+            // Extract the final response text
+            const result = turn.finalResponse || '';
+            this.emit('result', result);
+            console.log(`✅ Codex done. Length: ${result.length}`);
+            // Log tool usage if any
+            if (turn.items && turn.items.length > 0) {
+                for (const item of turn.items) {
+                    this.emit('tool_use', item);
+                }
+            }
+            return result || 'Task completed.';
+        }
+        catch (error) {
+            console.error('❌ Codex SDK error:', error);
+            this.emit('error', error);
+            throw error;
+        }
+    }
+    getThreadId() {
+        // Codex threads have IDs but they may not be directly exposed
+        // Check the thread object for an id property
+        return this.thread?.id || null;
+    }
+    clearThread() {
+        this.thread = null;
+        console.log('🗑️ Codex thread cleared');
+    }
+}
+// Quick utility for one-off queries
+export async function askCodex(prompt, cwd) {
+    const handler = new CodexHandler({ workingDirectory: cwd });
+    return handler.run(prompt);
+}

package/dist/codex-llm.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Codex LLM Wrapper for LiveKit Agents
+ *
+ * Wraps the Codex Agent SDK (@openai/codex-sdk) to work
+ * with LiveKit's AgentSession as an LLM provider.
+ *
+ * Flow: User speaks → STT → CodexLLM (Agent SDK) → TTS → User hears
+ */
+import { llm, type APIConnectOptions } from '@livekit/agents';
+import { Codex } from '@openai/codex-sdk';
+import { EventEmitter } from 'events';
+export interface CodexLLMOptions {
+    workingDirectory?: string;
+    skipGitRepoCheck?: boolean;
+    /** Event emitter for tool_use, progress updates */
+    eventEmitter?: EventEmitter;
+}
+/**
+ * Codex LLM - Wraps Codex Agent SDK for LiveKit
+ */
+export declare class CodexLLM extends llm.LLM {
+    #private;
+    constructor(opts?: CodexLLMOptions);
+    label(): string;
+    get model(): string;
+    get events(): EventEmitter;
+    get thread(): ReturnType<Codex['startThread']> | null;
+    chat({ chatCtx, toolCtx, connOptions, }: {
+        chatCtx: llm.ChatContext;
+        toolCtx?: llm.ToolContext;
+        connOptions?: APIConnectOptions;
+        parallelToolCalls?: boolean;
+        toolChoice?: llm.ToolChoice;
+        extraKwargs?: Record<string, unknown>;
+    }): llm.LLMStream;
+}
+/**
+ * Create a CodexLLM instance
+ */
+export declare function createCodexLLM(opts?: CodexLLMOptions): CodexLLM;

package/dist/codex-llm.js

@@ -0,0 +1,144 @@
+/**
+ * Codex LLM Wrapper for LiveKit Agents
+ *
+ * Wraps the Codex Agent SDK (@openai/codex-sdk) to work
+ * with LiveKit's AgentSession as an LLM provider.
+ *
+ * Flow: User speaks → STT → CodexLLM (Agent SDK) → TTS → User hears
+ */
+import { llm, shortuuid, DEFAULT_API_CONNECT_OPTIONS } from '@livekit/agents';
+import { Codex } from '@openai/codex-sdk';
+import { EventEmitter } from 'events';
+/**
+ * Codex LLM - Wraps Codex Agent SDK for LiveKit
+ */
+export class CodexLLM extends llm.LLM {
+    #opts;
+    #codex;
+    #thread = null;
+    #eventEmitter;
+    constructor(opts = {}) {
+        super();
+        this.#opts = {
+            workingDirectory: opts.workingDirectory || process.cwd(),
+            skipGitRepoCheck: opts.skipGitRepoCheck ?? true,
+        };
+        this.#codex = new Codex();
+        this.#eventEmitter = opts.eventEmitter || new EventEmitter();
+        console.log('🟣 CodexLLM initialized (Codex Agent SDK)');
+        console.log(`   📁 Working dir: ${this.#opts.workingDirectory}`);
+    }
+    label() {
+        return 'codex.agent-sdk';
+    }
+    get model() {
+        return 'codex';
+    }
+    get events() {
+        return this.#eventEmitter;
+    }
+    get thread() {
+        return this.#thread;
+    }
+    chat({ chatCtx, toolCtx, connOptions = DEFAULT_API_CONNECT_OPTIONS, }) {
+        return new CodexLLMStream(this, {
+            chatCtx,
+            toolCtx,
+            connOptions,
+            opts: this.#opts,
+            codex: this.#codex,
+            thread: this.#thread,
+            onThread: (t) => { this.#thread = t; },
+            eventEmitter: this.#eventEmitter,
+        });
+    }
+}
+/**
+ * Codex LLM Stream - Runs Codex Agent SDK and streams results
+ */
+class CodexLLMStream extends llm.LLMStream {
+    #opts;
+    #codex;
+    #thread;
+    #onThread;
+    #eventEmitter;
+    constructor(llmInstance, { chatCtx, toolCtx, connOptions, opts, codex, thread, onThread, eventEmitter, }) {
+        super(llmInstance, { chatCtx, toolCtx, connOptions });
+        this.#opts = opts;
+        this.#codex = codex;
+        this.#thread = thread;
+        this.#onThread = onThread;
+        this.#eventEmitter = eventEmitter;
+    }
+    async run() {
+        const requestId = `codex_${shortuuid()}`;
+        try {
+            // Extract user's message from chat context
+            // ChatContext has .items which are ChatItem[] (ChatMessage | FunctionCall | FunctionCallOutput)
+            const items = this.chatCtx.items;
+            // Find the last user message
+            let userText = '';
+            for (let i = items.length - 1; i >= 0; i--) {
+                const item = items[i];
+                if (item.type === 'message' && item.role === 'user') {
+                    // Content is ChatContent[] = (ImageContent | AudioContent | string)[]
+                    if (Array.isArray(item.content)) {
+                        userText = item.content
+                            .filter((c) => typeof c === 'string')
+                            .join('\n');
+                    }
+                    break;
+                }
+            }
+            if (!userText.trim()) {
+                this.queue.put({
+                    id: requestId,
+                    delta: { role: 'assistant', content: "I didn't catch that. Could you repeat?" },
+                });
+                return;
+            }
+            console.log(`🎤 User (${userText.length} chars): "${userText}"`);
+            // Create or reuse thread
+            if (!this.#thread) {
+                console.log('🆕 Starting new Codex thread');
+                this.#thread = this.#codex.startThread({
+                    workingDirectory: this.#opts.workingDirectory,
+                    skipGitRepoCheck: this.#opts.skipGitRepoCheck,
+                });
+                this.#onThread(this.#thread);
+            }
+            else {
+                console.log('🔄 Continuing Codex thread');
+            }
+            // Run Codex and get result
+            const turn = await this.#thread.run(userText);
+            // Emit tool usage events
+            if (turn.items && turn.items.length > 0) {
+                for (const item of turn.items) {
+                    console.log(`🔧 Codex: ${item.type || 'action'}`);
+                    this.#eventEmitter.emit('tool_use', item);
+                }
+            }
+            // Send response to TTS
+            const result = turn.finalResponse || 'Done.';
+            this.queue.put({
+                id: requestId,
+                delta: { role: 'assistant', content: result },
+            });
+            console.log('✅ Codex response complete');
+        }
+        catch (error) {
+            console.error('❌ Codex Agent SDK error:', error);
+            this.queue.put({
+                id: requestId,
+                delta: { role: 'assistant', content: 'Sorry, I encountered an error.' },
+            });
+        }
+    }
+}
+/**
+ * Create a CodexLLM instance
+ */
+export function createCodexLLM(opts) {
+    return new CodexLLM(opts);
+}

package/dist/content/compaction-lens-worker.d.ts

@@ -13,10 +13,15 @@
  *       copy to <path> instead of content-profile.md and leaves the HWM alone.
  *   node compaction-lens-worker.js --library <sessionId> [--cwd <dir>] [--dry] [--out-dir <dir>]
  *       LIBRARY step only (manual / dry run). Takes the per-project lock itself.
- * Per-compaction runs do TWO independent, fail-open steps under one lock:
+ *   node compaction-lens-worker.js --content <sessionId> [--cwd <dir>] [--dry] [--research-refresh]
+ *       CONTENT step (Stage A) only: manual / the per-project "Refresh research"
+ *       backend. --dry = no ingest (still spends, capped). Takes the per-project lock.
+ * Per-compaction runs do THREE independent, fail-open steps under one lock:
  *   1. the content lens (content-profile.md + HWM), unchanged;
  *   2. the library step (lens-library.ts): one period-map page for the period
- *      that just ended + INDEX.md. A failure in either never stops the other.
+ *      that just ended + INDEX.md;
+ *   3. the content step (content-run.ts, Stage A): research → briefs → scripts →
+ *      checks → draft ingest for that period. A failure in any never stops the others.
  * Fully self-contained: top-level try/catch, redacted log in the project dir,
  * refreshes + releases the per-project lock, always exits.
  */

package/dist/content/compaction-lens-worker.js

@@ -13,10 +13,15 @@
  *       copy to <path> instead of content-profile.md and leaves the HWM alone.
  *   node compaction-lens-worker.js --library <sessionId> [--cwd <dir>] [--dry] [--out-dir <dir>]
  *       LIBRARY step only (manual / dry run). Takes the per-project lock itself.
- * Per-compaction runs do TWO independent, fail-open steps under one lock:
+ *   node compaction-lens-worker.js --content <sessionId> [--cwd <dir>] [--dry] [--research-refresh]
+ *       CONTENT step (Stage A) only: manual / the per-project "Refresh research"
+ *       backend. --dry = no ingest (still spends, capped). Takes the per-project lock.
+ * Per-compaction runs do THREE independent, fail-open steps under one lock:
  *   1. the content lens (content-profile.md + HWM), unchanged;
  *   2. the library step (lens-library.ts): one period-map page for the period
- *      that just ended + INDEX.md. A failure in either never stops the other.
+ *      that just ended + INDEX.md;
+ *   3. the content step (content-run.ts, Stage A): research → briefs → scripts →
+ *      checks → draft ingest for that period. A failure in any never stops the others.
  * Fully self-contained: top-level try/catch, redacted log in the project dir,
  * refreshes + releases the per-project lock, always exits.
  */
@@ -27,15 +32,36 @@ import { resolveSessionDb } from './lens-db.js';
 import { acquireLock, refuseOutPath, releaseLock, resolveProjectDir, touchLock } from './lens-paths.js';
 import { logLine } from './lens-profile.js';
 import { runLibraryStep } from './lens-library.js';
-// ≤2 big windows + reduce at ≤6 min/call, then the library step (1 call ≤6 min + model meta).
-const INCREMENTAL_TIMEOUT_MS = 35 * 60_000;
+import { runContentStep } from './content-run.js';
+// ≤2 big windows + reduce at ≤6 min/call, then the library step (1 call ≤6 min + model meta),
+// then the content step (Stage A: ~10-18 small calls, ≤4 min each, capped in $).
+const INCREMENTAL_TIMEOUT_MS = 45 * 60_000;
 const BACKFILL_TIMEOUT_MS = 3 * 60 * 60_000;
 const LIBRARY_TIMEOUT_MS = 15 * 60_000;
+const CONTENT_TIMEOUT_MS = 20 * 60_000;
 function argVal(argv, flag) {
     const i = argv.indexOf(flag);
     return i >= 0 ? argv[i + 1] : undefined;
 }
 function parseJob(argv) {
+    if (argv[0] === '--content') {
+        const sessionId = argv[1];
+        if (!sessionId || sessionId.startsWith('--'))
+            throw new Error('usage: --content <sessionId> [--cwd <dir>] [--dry] [--research-refresh]');
+        const cwd = argVal(argv, '--cwd');
+        const db = resolveSessionDb(sessionId, null, cwd);
+        const projectDir = db ? dirname(dirname(dirname(db))) : null;
+        if (!projectDir || !acquireLock(projectDir))
+            throw new Error(`content: project dir ${projectDir ?? '(none)'} missing or locked`);
+        return {
+            opts: { sessionId, cwd, mode: 'incremental' },
+            kind: 'content',
+            content: { dry: argv.includes('--dry'), researchRefresh: argv.includes('--research-refresh') },
+            lockDir: projectDir,
+            logDir: projectDir,
+            timeoutMs: CONTENT_TIMEOUT_MS,
+        };
+    }
     if (argv[0] === '--library') {
         const sessionId = argv[1];
         if (!sessionId || sessionId.startsWith('--'))
@@ -135,7 +161,7 @@ async function main() {
         const t0 = Date.now();
         let lensErr = null;
         // Step 1 — content lens (skipped by the --library entry).
-        if (job.kind !== 'library') {
+        if (job.kind !== 'library' && job.kind !== 'content') {
             try {
                 const r = await runCompactionLens({
                     ...job.opts,
@@ -155,7 +181,8 @@ async function main() {
         }
         // Step 2 — library page for the period that just ended (per-compaction + --library only; never backfill).
         // runLibraryStep never throws; any failure is logged and the worker still exits cleanly.
-        if (job.opts.mode === 'incremental') {
+        let libPeriod = null;
+        if (job.opts.mode === 'incremental' && job.kind !== 'content') {
             if (lockDir)
                 touchLock(lockDir);
             const lib = await runLibraryStep({
@@ -169,12 +196,38 @@ async function main() {
             logLine(logDir, `session ${sid}: library status=${lib.status} cost=$${lib.costUsd.toFixed(4)}${lib.page ? ` page=${lib.page}` : ''}`);
             if (job.kind === 'library')
                 process.stdout.write(`${JSON.stringify({ status: lib.status, page: lib.page, index: lib.index, period: lib.period, cost: lib.costUsd, errors: lib.errors })}\n`);
+            if (lib.status === 'written')
+                libPeriod = lib.period;
+        }
+        // Step 3 — content plan (Stage A) for the period (per-compaction + --content; never backfill / --library).
+        // runContentStep never throws; the try is belt and braces so nothing here can fail the worker.
+        if (job.opts.mode === 'incremental' && job.kind !== 'library') {
+            try {
+                if (lockDir)
+                    touchLock(lockDir);
+                const c = await runContentStep({
+                    sessionId: job.opts.sessionId,
+                    projectDir: lockDir,
+                    cwd: job.opts.cwd,
+                    period: libPeriod,
+                    dry: job.content?.dry,
+                    researchRefresh: job.content?.researchRefresh,
+                    keepAlive: () => lockDir && touchLock(lockDir),
+                    log: m => logLine(logDir, `session ${sid} [content]: ${m}`),
+                });
+                logLine(logDir, `session ${sid}: content status=${c.status} pieces=${c.pieces.length} cost=$${c.costUsd.toFixed(4)}${c.capHit ? ` cap=${c.capHit}` : ''}`);
+                if (job.kind === 'content')
+                    process.stdout.write(`${JSON.stringify(c)}\n`);
+            }
+            catch (err) {
+                logLine(logDir, `content step error (ignored): ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
         return lensErr ? 1 : 0;
     }
     catch (err) {
         logLine(logDir, `worker error: ${err instanceof Error ? err.stack || err.message : String(err)}`);
-        if (err instanceof Error && /^(backfill|library):/.test(err.message))
+        if (err instanceof Error && /^(backfill|library|content):/.test(err.message))
             process.stderr.write(`${err.message}\n`);
         return 1;
     }

package/dist/content/compaction-lens.js

@@ -14,12 +14,14 @@
  *  7. HN gap check (fail-open), optional recording, client-redact the entry,
  *     APPEND to <project>/content-profile.md (or a scratch file); advance HWM
  */
-import { dirname } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { loadConversationRows, packWindows, resolveSessionDb } from './lens-db.js';
 import { buildRecordIndex, explainQuote, parseJsonObject, readAngles, readCapabilities, splitByEvidence, verifyItems, } from './lens-quotes.js';
 import { Budget, chat, getModelInfo, mapPrompt, reducePrompt, windowTokensFor } from './lens-model.js';
 import { DENYLIST_FILE, hasBillingQuote, isBillingAngle, isBillingCapability, loadClientRedactor } from './lens-redact.js';
 import { gapCheck } from './lens-hn.js';
+import { makeScrubber } from './content-redact.js';
+import { gateQueries, privateSegments } from './content-query-gate.js';
 import { alignRecording, findSessionRecording } from './lens-audio.js';
 import { appendProfile, formatEntry, writeScratch } from './lens-profile.js';
 import { findTranscriptBySessionId, isProjectDir, readHwm, refuseOutPath, resolveProjectDir, writeHwm } from './lens-paths.js';
@@ -197,8 +199,17 @@ export async function runCompactionLens(opts) {
         bumpHwm(covered);
         return { ...r, status: 'nothing-survived' };
     }
+    // Outbound HN queries are model output built from session text: scrub, then the same
+    // deterministic gate research uses (project basename / cwd segments never leave the machine).
+    // gapCheck([]) makes no fetch and returns its neutral "no queries" result.
+    const sc = makeScrubber(projectDir);
+    const privateTerms = privateSegments([opts.cwd, process.env.OSBORN_CWD, basename(projectDir)]);
     for (const a of fin.c.angles) {
-        r.angles.push({ title: a.title, why: a.why, quotes: a.quotes, gap: await gapCheck(a.queries) });
+        const scrubbed = (a.queries ?? []).map(q => sc.scrub(String(q ?? '')).replace(/\[[^\]]*\]/g, ' ').replace(/\s+/g, ' ').trim()).filter(q => q.length >= 3);
+        const queries = gateQueries(scrubbed, privateTerms);
+        if ((a.queries ?? []).length > queries.length)
+            log(`gap check "${a.title.slice(0, 60)}": ${(a.queries ?? []).length - queries.length} query(ies) held back by the outbound gate`);
+        r.angles.push({ title: a.title, why: a.why, quotes: a.quotes, gap: await gapCheck(queries) });
     }
     r.capabilities = fin.c.capabilities.map(c => ({
         name: c.name, did: c.did, evidence: c.evidence, proof: c.proof, quotes: c.quotes,

package/dist/content/content-brief.d.ts

@@ -0,0 +1,90 @@
+/**
+ * content-brief.ts — Stage A planning: which pieces a period yields, and the
+ * brief for each (rules §2-§4, §8a).
+ *
+ *   planPieces()  one OpenRouter call over the period's library page →
+ *                 ≤1 highlight + ≤3 how-to candidates, each with a subtopic,
+ *                 1-2 search queries and the row range it is built from.
+ *   buildBriefs() one call over the candidates + their research digests →
+ *                 per piece: VIEWER (from research), situation, tier, format
+ *                 (from the catalog), the research problems it speaks to.
+ * Deterministic validation after each call: unknown tiers/formats, rows outside
+ * the period, or a missing viewer fall back to safe defaults rather than failing.
+ * Throws CapError (cap) or Error (model) — content-run records either.
+ */
+import { type ContentLlmOptions } from './content-llm.js';
+import { type Tier } from './content-script-rules.js';
+import type { TopicResearch } from './content-research.js';
+export declare const OWNER_FILE = "content-owner.json";
+export interface PieceCandidate {
+    id: string;
+    kind: Tier;
+    subtopic: string;
+    story: string;
+    queries: string[];
+    fromRow: number;
+    toRow: number;
+    why: string;
+}
+export interface Owner {
+    name: string;
+    handle?: string;
+}
+export interface Stake {
+    /** What is measured, e.g. "facts recalled after compaction". */
+    quantity: string;
+    before: string;
+    after: string;
+}
+export interface Brief {
+    id: string;
+    tier: Tier;
+    subtopic: string;
+    story: string;
+    fromRow: number;
+    toRow: number;
+    /** WHO is consuming it (rules §4), picked from the research. */
+    viewer: string;
+    /** What that viewer is living through. */
+    situation: string;
+    /** Format id from FORMAT_CATALOG. */
+    format: string;
+    angle: string;
+    /** Research problems (§8a) the piece speaks to. */
+    problems: string[];
+    /** WHAT-WORKS rule 1: the before -> after quantity or verdict the piece shows. Null = no provable stake (not scripted). */
+    stake: Stake | null;
+    researchKey: string;
+    owner: Owner | null;
+    autoGenerated: true;
+}
+/** Developer who owns the pieces (rules §6): env first, then <project>/content-owner.json. Null when unknown. */
+export declare function loadOwner(projectDir: string | null): Owner | null;
+export declare const PLAN_SYSTEM: string;
+export declare function planPrompt(page: string, maxHighlights: number, maxHowtos: number, range: {
+    from: number;
+    to: number;
+}): string;
+export declare function validateCandidates(raw: unknown, range: {
+    from: number;
+    to: number;
+}, maxPieces: number): PieceCandidate[];
+/** Plan this period's pieces. One model call. */
+export declare function planPieces(page: string, range: {
+    from: number;
+    to: number;
+}, maxPieces: number, llm: ContentLlmOptions): Promise<{
+    candidates: PieceCandidate[];
+    costUsd: number;
+}>;
+export declare const BRIEF_SYSTEM: string;
+export declare function catalogText(tier: Tier): string;
+export declare function briefPrompt(cands: PieceCandidate[], research: Map<string, TopicResearch>): string;
+/** A stake needs all three parts, and before must differ from after. */
+export declare function validStake(v: unknown): Stake | null;
+export declare function validateBriefs(raw: unknown, cands: PieceCandidate[], research: Map<string, TopicResearch>, owner: Owner | null): Brief[];
+/** Build all briefs for a period in one model call. */
+export declare function buildBriefs(cands: PieceCandidate[], research: Map<string, TopicResearch>, owner: Owner | null, llm: ContentLlmOptions): Promise<{
+    briefs: Brief[];
+    costUsd: number;
+}>;