clementine-agent 1.18.188 → 1.18.190

package/dist/agent/background-tasks.d.ts

@@ -26,12 +26,21 @@ export interface BackgroundTaskOptions {
 /**
  * Create a new pending task on disk and return it. Caller (the MCP tool)
  * doesn't await execution — the daemon picks the task up asynchronously.
+ *
+ * 1.18.190 — accepts the new chain fields (kind / chainId / planId /
+ * stepIndex / parentTaskId) for planner-orchestrator chained tasks. All
+ * are optional; callers that pass none get the legacy monolithic shape.
  */
 export declare function createBackgroundTask(input: {
     fromAgent: string;
     prompt: string;
     maxMinutes: number;
     sessionKey?: string;
+    kind?: BackgroundTask['kind'];
+    chainId?: string;
+    planId?: string;
+    stepIndex?: number;
+    parentTaskId?: string;
 }, opts?: BackgroundTaskOptions): BackgroundTask;
 /** Load a task by id, or null if not found / malformed. */
 export declare function loadBackgroundTask(id: string, opts?: BackgroundTaskOptions): BackgroundTask | null;

package/dist/agent/background-tasks.js

@@ -45,6 +45,10 @@ function safeWrite(file, task) {
 /**
  * Create a new pending task on disk and return it. Caller (the MCP tool)
  * doesn't await execution — the daemon picks the task up asynchronously.
+ *
+ * 1.18.190 — accepts the new chain fields (kind / chainId / planId /
+ * stepIndex / parentTaskId) for planner-orchestrator chained tasks. All
+ * are optional; callers that pass none get the legacy monolithic shape.
  */
 export function createBackgroundTask(input, opts) {
     const now = new Date();
@@ -58,6 +62,16 @@ export function createBackgroundTask(input, opts) {
     };
     if (input.sessionKey)
         task.sessionKey = input.sessionKey;
+    if (input.kind)
+        task.kind = input.kind;
+    if (input.chainId)
+        task.chainId = input.chainId;
+    if (input.planId)
+        task.planId = input.planId;
+    if (typeof input.stepIndex === 'number')
+        task.stepIndex = input.stepIndex;
+    if (input.parentTaskId)
+        task.parentTaskId = input.parentTaskId;
     safeWrite(pathFor(task.id, opts), task);
     return task;
 }

package/dist/agent/bg-orchestrator.d.ts

@@ -0,0 +1,103 @@
+/**
+ * bg-orchestrator — drive a Plan from start to finish by queuing one
+ * bg-task per PlanStep, advancing the chain as each step completes.
+ *
+ * Why this exists (1.18.190)
+ * ──────────────────────────
+ * The bg-planner produces a Plan with 3-7 PlanSteps. This module is
+ * the runtime that executes that Plan, one step at a time, with each
+ * step getting its own fresh bg-task + worker context. The chain only
+ * advances when the previous step completed successfully — failures
+ * pause the chain and notify the owner.
+ *
+ * Architectural role:
+ *   bg-planner.ts → Plan (data)
+ *   bg-orchestrator.ts → drives the Plan (this module)
+ *   background-tasks.ts → bg-task persistence (filesystem)
+ *   run-agent-cron.ts → runs the actual SDK call for each step
+ *
+ * The orchestrator is NEVER the thing reading files or calling APIs.
+ * It's a state machine: read plan → queue next step → wait for step
+ * to finish → repeat. The state machine lives across daemon restarts
+ * because both Plans and BackgroundTasks are filesystem-persisted.
+ *
+ * Why this prevents the autocompact thrash that motivated 1.18.190:
+ *   - each step gets a FRESH bg-task with a FRESH 200K worker window
+ *   - state flows between steps via the project's STATUS.md and the
+ *     plan's `deliverable` fields, NOT via accumulated SDK context
+ *   - no single worker has to do more than ~2-6 tool calls before
+ *     completing its scoped deliverable
+ *   - the model's compaction pressure resets between steps
+ */
+import { createBackgroundTask } from './background-tasks.js';
+import { loadPlan, savePlan } from './bg-planner.js';
+import type { Plan, PlanStep } from './bg-planner.js';
+import type { BackgroundTask } from '../types.js';
+/**
+ * Queue the first step of a freshly-planned chain. Returns the
+ * BackgroundTask created for step 0.
+ *
+ * Caller responsibility: the Plan must already be persisted to disk
+ * (via savePlan) before calling this — the dispatched step task
+ * carries a planId that will be loaded back at execution time.
+ */
+export declare function dispatchChain(plan: Plan): BackgroundTask;
+/**
+ * Called by the bg-task framework when a chained step completes.
+ * Updates the plan's step status, then either:
+ *   - queues the next step (chain continues),
+ *   - marks the plan completed (no more steps), or
+ *   - pauses the chain (step failed; owner notification surfaces elsewhere).
+ *
+ * Returns the next BackgroundTask if one was queued, or null otherwise.
+ *
+ * Safe to call multiple times for the same completed task (idempotent
+ * via the step's status check).
+ */
+export declare function advanceChain(opts: {
+    completedTask: BackgroundTask;
+    /** Optional override for tests; defaults to filesystem. */
+    loadPlanFn?: typeof loadPlan;
+    savePlanFn?: typeof savePlan;
+    createTaskFn?: typeof createBackgroundTask;
+}): BackgroundTask | null;
+/**
+ * Pause a chain explicitly (e.g., owner intervention). The current
+ * running step is left alone — caller can mark it however the
+ * downstream cancellation flow does.
+ */
+export declare function pauseChain(planId: string, projectPath?: string | null, reason?: string): void;
+/**
+ * Resume a paused chain by dispatching its next pending step. If
+ * all steps are terminal, marks the plan completed. Returns the
+ * dispatched task, or null when nothing to dispatch.
+ */
+export declare function resumeChain(planId: string, projectPath?: string | null): BackgroundTask | null;
+/**
+ * Build the focused prompt for one chained worker. Designed to be SMALL
+ * (~1-2KB) and ANCHORED to the step's deliverable so the worker has a
+ * clear stopping condition. Key elements:
+ *   - The original user request (for context, not for re-doing it)
+ *   - The plan summary (what's been done, what's next)
+ *   - THIS step's scope + expected tools + deliverable
+ *   - Posture: "do ONLY this step. Don't overshoot. State your deliverable
+ *     in your final response."
+ *
+ * State that the next step might need is read by that step from the
+ * project STATUS.md or the prior step's deliverable file — NOT from
+ * this step's response text. Result text is for the orchestrator's
+ * advancement decision; deliverables are for the work itself.
+ */
+export declare function buildStepPrompt(plan: Plan, step: PlanStep): string;
+/**
+ * Given a chain step's taskId, derive the directory where the plan
+ * lives. Used by run-agent-cron to set the SDK's `cwd` and
+ * `additionalDirectories` to the project root for the step.
+ */
+export declare function projectDirForChainTask(task: BackgroundTask): string | undefined;
+/**
+ * Format a status line for posting to the originating chat after each
+ * step completes — gives the owner a real-time view of chain progress.
+ */
+export declare function formatChainStatusUpdate(plan: Plan, justCompletedStep: PlanStep): string;
+//# sourceMappingURL=bg-orchestrator.d.ts.map

package/dist/agent/bg-orchestrator.js

@@ -0,0 +1,323 @@
+/**
+ * bg-orchestrator — drive a Plan from start to finish by queuing one
+ * bg-task per PlanStep, advancing the chain as each step completes.
+ *
+ * Why this exists (1.18.190)
+ * ──────────────────────────
+ * The bg-planner produces a Plan with 3-7 PlanSteps. This module is
+ * the runtime that executes that Plan, one step at a time, with each
+ * step getting its own fresh bg-task + worker context. The chain only
+ * advances when the previous step completed successfully — failures
+ * pause the chain and notify the owner.
+ *
+ * Architectural role:
+ *   bg-planner.ts → Plan (data)
+ *   bg-orchestrator.ts → drives the Plan (this module)
+ *   background-tasks.ts → bg-task persistence (filesystem)
+ *   run-agent-cron.ts → runs the actual SDK call for each step
+ *
+ * The orchestrator is NEVER the thing reading files or calling APIs.
+ * It's a state machine: read plan → queue next step → wait for step
+ * to finish → repeat. The state machine lives across daemon restarts
+ * because both Plans and BackgroundTasks are filesystem-persisted.
+ *
+ * Why this prevents the autocompact thrash that motivated 1.18.190:
+ *   - each step gets a FRESH bg-task with a FRESH 200K worker window
+ *   - state flows between steps via the project's STATUS.md and the
+ *     plan's `deliverable` fields, NOT via accumulated SDK context
+ *   - no single worker has to do more than ~2-6 tool calls before
+ *     completing its scoped deliverable
+ *   - the model's compaction pressure resets between steps
+ */
+import path from 'node:path';
+import pino from 'pino';
+import { createBackgroundTask } from './background-tasks.js';
+import { loadPlan, savePlan } from './bg-planner.js';
+const logger = pino({ name: 'clementine.bg-orchestrator' });
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Queue the first step of a freshly-planned chain. Returns the
+ * BackgroundTask created for step 0.
+ *
+ * Caller responsibility: the Plan must already be persisted to disk
+ * (via savePlan) before calling this — the dispatched step task
+ * carries a planId that will be loaded back at execution time.
+ */
+export function dispatchChain(plan) {
+    if (!plan.steps.length) {
+        throw new Error(`Cannot dispatch chain: plan ${plan.id} has zero steps`);
+    }
+    const firstStep = plan.steps[0];
+    const task = createBackgroundTask({
+        fromAgent: 'clementine',
+        prompt: buildStepPrompt(plan, firstStep),
+        maxMinutes: 30, // generous per-step; the step itself decides how long it needs
+        ...(plan.originatingSessionKey ? { sessionKey: plan.originatingSessionKey } : {}),
+        kind: 'step',
+        chainId: plan.chainId,
+        planId: plan.id,
+        stepIndex: 0,
+    });
+    // Stamp the step with its taskId + mark plan as in_progress so future
+    // resumes don't try to re-dispatch the same step.
+    firstStep.taskId = task.id;
+    firstStep.status = 'running';
+    plan.status = 'in_progress';
+    savePlan(plan, plan.projectPath);
+    logger.info({
+        planId: plan.id,
+        chainId: plan.chainId,
+        stepIndex: 0,
+        stepTitle: firstStep.title,
+        taskId: task.id,
+    }, 'dispatchChain: queued step 0');
+    return task;
+}
+/**
+ * Called by the bg-task framework when a chained step completes.
+ * Updates the plan's step status, then either:
+ *   - queues the next step (chain continues),
+ *   - marks the plan completed (no more steps), or
+ *   - pauses the chain (step failed; owner notification surfaces elsewhere).
+ *
+ * Returns the next BackgroundTask if one was queued, or null otherwise.
+ *
+ * Safe to call multiple times for the same completed task (idempotent
+ * via the step's status check).
+ */
+export function advanceChain(opts) {
+    const { completedTask } = opts;
+    if (!completedTask.planId || typeof completedTask.stepIndex !== 'number') {
+        logger.debug({ taskId: completedTask.id }, 'advanceChain: task has no plan id/step index — not a chain step');
+        return null;
+    }
+    const loadPlanImpl = opts.loadPlanFn ?? loadPlan;
+    const savePlanImpl = opts.savePlanFn ?? savePlan;
+    const createTaskImpl = opts.createTaskFn ?? createBackgroundTask;
+    // Plans live alongside the project when one's set; the task carries
+    // the planId but not the project path. Try the project path first
+    // (fast path), then fall back to the global plans dir inside
+    // loadPlan itself.
+    const plan = loadPlanImpl(completedTask.planId, undefined);
+    if (!plan) {
+        logger.warn({ planId: completedTask.planId, taskId: completedTask.id }, 'advanceChain: plan not found — cannot advance');
+        return null;
+    }
+    const step = plan.steps[completedTask.stepIndex];
+    if (!step) {
+        logger.warn({ planId: plan.id, stepIndex: completedTask.stepIndex }, 'advanceChain: step index out of range');
+        return null;
+    }
+    // Idempotency: if the step has already been marked terminal, don't
+    // advance again. Protects against duplicate completion callbacks.
+    if (step.status === 'done' || step.status === 'failed' || step.status === 'skipped') {
+        logger.debug({ planId: plan.id, stepIndex: step.index, status: step.status }, 'advanceChain: step already terminal — skipping');
+        return null;
+    }
+    // Reflect the task's terminal status onto the plan step.
+    if (completedTask.status === 'done') {
+        step.status = 'done';
+        step.completedAt = completedTask.completedAt ?? new Date().toISOString();
+        step.resultPreview = (completedTask.result ?? '').slice(0, 400);
+    }
+    else {
+        // failed | aborted | interrupted — all map to plan-step failure for now
+        step.status = 'failed';
+        step.completedAt = completedTask.completedAt ?? new Date().toISOString();
+        step.resultPreview = (completedTask.error ?? completedTask.result ?? '').slice(0, 400);
+        plan.status = 'paused';
+        savePlanImpl(plan, plan.projectPath);
+        logger.warn({
+            planId: plan.id,
+            chainId: plan.chainId,
+            stepIndex: step.index,
+            stepTitle: step.title,
+            taskStatus: completedTask.status,
+            error: completedTask.error,
+        }, 'advanceChain: step failed — chain paused');
+        return null;
+    }
+    // Look for the next pending step.
+    const nextStep = plan.steps.find((s, i) => i > step.index && s.status === 'pending');
+    if (!nextStep) {
+        // Chain complete!
+        plan.status = 'completed';
+        savePlanImpl(plan, plan.projectPath);
+        logger.info({
+            planId: plan.id,
+            chainId: plan.chainId,
+            stepCount: plan.steps.length,
+        }, 'advanceChain: chain completed');
+        return null;
+    }
+    // Queue the next step.
+    const nextTask = createTaskImpl({
+        fromAgent: 'clementine',
+        prompt: buildStepPrompt(plan, nextStep),
+        maxMinutes: 30,
+        ...(plan.originatingSessionKey ? { sessionKey: plan.originatingSessionKey } : {}),
+        kind: 'step',
+        chainId: plan.chainId,
+        planId: plan.id,
+        stepIndex: nextStep.index,
+        parentTaskId: completedTask.id,
+    });
+    nextStep.taskId = nextTask.id;
+    nextStep.status = 'running';
+    savePlanImpl(plan, plan.projectPath);
+    logger.info({
+        planId: plan.id,
+        chainId: plan.chainId,
+        stepIndex: nextStep.index,
+        stepTitle: nextStep.title,
+        taskId: nextTask.id,
+        parentTaskId: completedTask.id,
+    }, 'advanceChain: queued next step');
+    return nextTask;
+}
+/**
+ * Pause a chain explicitly (e.g., owner intervention). The current
+ * running step is left alone — caller can mark it however the
+ * downstream cancellation flow does.
+ */
+export function pauseChain(planId, projectPath, reason) {
+    const plan = loadPlan(planId, projectPath ?? undefined);
+    if (!plan)
+        return;
+    plan.status = 'paused';
+    if (reason)
+        plan.notes = `${plan.notes ? plan.notes + '\n' : ''}[paused] ${reason}`;
+    savePlan(plan, plan.projectPath);
+    logger.info({ planId, reason }, 'pauseChain: chain paused');
+}
+/**
+ * Resume a paused chain by dispatching its next pending step. If
+ * all steps are terminal, marks the plan completed. Returns the
+ * dispatched task, or null when nothing to dispatch.
+ */
+export function resumeChain(planId, projectPath) {
+    const plan = loadPlan(planId, projectPath ?? undefined);
+    if (!plan)
+        return null;
+    if (plan.status === 'completed')
+        return null;
+    const nextStep = plan.steps.find((s) => s.status === 'pending');
+    if (!nextStep) {
+        plan.status = 'completed';
+        savePlan(plan, plan.projectPath);
+        return null;
+    }
+    const task = createBackgroundTask({
+        fromAgent: 'clementine',
+        prompt: buildStepPrompt(plan, nextStep),
+        maxMinutes: 30,
+        ...(plan.originatingSessionKey ? { sessionKey: plan.originatingSessionKey } : {}),
+        kind: 'step',
+        chainId: plan.chainId,
+        planId: plan.id,
+        stepIndex: nextStep.index,
+    });
+    nextStep.taskId = task.id;
+    nextStep.status = 'running';
+    plan.status = 'in_progress';
+    savePlan(plan, plan.projectPath);
+    logger.info({ planId, stepIndex: nextStep.index, taskId: task.id }, 'resumeChain: dispatched next step');
+    return task;
+}
+// ── Step prompt construction ─────────────────────────────────────────
+/**
+ * Build the focused prompt for one chained worker. Designed to be SMALL
+ * (~1-2KB) and ANCHORED to the step's deliverable so the worker has a
+ * clear stopping condition. Key elements:
+ *   - The original user request (for context, not for re-doing it)
+ *   - The plan summary (what's been done, what's next)
+ *   - THIS step's scope + expected tools + deliverable
+ *   - Posture: "do ONLY this step. Don't overshoot. State your deliverable
+ *     in your final response."
+ *
+ * State that the next step might need is read by that step from the
+ * project STATUS.md or the prior step's deliverable file — NOT from
+ * this step's response text. Result text is for the orchestrator's
+ * advancement decision; deliverables are for the work itself.
+ */
+export function buildStepPrompt(plan, step) {
+    const lines = [];
+    lines.push(`# Chained step ${step.index + 1} of ${plan.steps.length}`);
+    lines.push('');
+    lines.push(`## Original user request`);
+    lines.push(plan.userRequest);
+    lines.push('');
+    if (plan.projectPath) {
+        lines.push(`## Active project`);
+        lines.push(`Path: \`${plan.projectPath}\``);
+        lines.push('Your cwd is set to this project. Read sources from there, write outputs to `output/`.');
+        lines.push('');
+    }
+    // Concise plan summary — JUST what's been done and what's next.
+    // Don't include full step bodies; that's noise.
+    lines.push(`## Plan summary`);
+    for (const s of plan.steps) {
+        const marker = s.status === 'done' ? '✓' : s.status === 'failed' ? '✗' : s.index === step.index ? '→' : '·';
+        const detail = s.status === 'done' && s.deliverable ? ` (→ ${s.deliverable})` : '';
+        lines.push(`  ${marker} ${s.index + 1}. ${s.title}${detail}`);
+    }
+    lines.push('');
+    lines.push(`## Your step (the → above)`);
+    lines.push(`**Title**: ${step.title}`);
+    lines.push(`**Scope**: ${step.scope}`);
+    if (step.expectedTools.length > 0) {
+        lines.push(`**Expected tool calls**: ${step.expectedTools.join(', ')}`);
+    }
+    if (step.deliverable) {
+        lines.push(`**Deliverable**: ${step.deliverable}`);
+    }
+    lines.push('');
+    lines.push(`## Step posture`);
+    lines.push('Do ONLY this step. Don\'t start the next one — the orchestrator handles that. ' +
+        'When you\'re done, state your deliverable concretely in your final response ' +
+        '(file path, URL, confirmation) so the orchestrator can advance the chain. ' +
+        'If you hit a blocker (missing info, ambiguous scope, tool failure), say so explicitly ' +
+        'and stop — don\'t guess.');
+    return lines.join('\n');
+}
+// ── Convenience helpers used by run-agent-cron ───────────────────────
+/**
+ * Given a chain step's taskId, derive the directory where the plan
+ * lives. Used by run-agent-cron to set the SDK's `cwd` and
+ * `additionalDirectories` to the project root for the step.
+ */
+export function projectDirForChainTask(task) {
+    if (!task.planId)
+        return undefined;
+    const plan = loadPlan(task.planId);
+    return plan?.projectPath ?? undefined;
+}
+/**
+ * Format a status line for posting to the originating chat after each
+ * step completes — gives the owner a real-time view of chain progress.
+ */
+export function formatChainStatusUpdate(plan, justCompletedStep) {
+    const total = plan.steps.length;
+    const done = plan.steps.filter((s) => s.status === 'done').length;
+    const lines = [];
+    lines.push(`**Step ${justCompletedStep.index + 1}/${total} done**: ${justCompletedStep.title}`);
+    if (justCompletedStep.resultPreview) {
+        lines.push(`→ ${justCompletedStep.resultPreview.slice(0, 200)}`);
+    }
+    if (done < total && plan.status === 'in_progress') {
+        const nextStep = plan.steps.find((s) => s.status === 'pending');
+        if (nextStep)
+            lines.push(`Next: ${nextStep.title}`);
+    }
+    else if (plan.status === 'completed') {
+        lines.push(`Chain complete (${done}/${total} steps).`);
+    }
+    else if (plan.status === 'paused') {
+        lines.push(`Chain paused. Tell me how to proceed.`);
+    }
+    return lines.join('\n');
+}
+// path is imported but lint warns when unused — use it once just to keep import meaningful.
+// (orchestrator uses path indirectly via loadPlan/savePlan; this comment keeps the import obvious to future readers)
+void path;
+//# sourceMappingURL=bg-orchestrator.js.map

package/dist/agent/bg-planner.d.ts

@@ -0,0 +1,142 @@
+/**
+ * bg-planner — decompose a multi-step user request into a chain of
+ * focused PlanSteps that the orchestrator can dispatch one at a time.
+ *
+ * Why this exists (1.18.190)
+ * ──────────────────────────
+ * Before this, a complex multi-step user ask ("find the coaches project,
+ * build me an HTML report, deploy it to Netlify, verify the URL") got
+ * handed to a single monolithic bg-task worker. The worker had its own
+ * 200K context but still autocompact-thrashed because:
+ *   - tool outputs accumulated across all 5-6 phases of the work
+ *   - the model lost fidelity to its own past tool outputs as the
+ *     output-guard tightened from 30KB → 4KB
+ *   - one bad turn (huge file read, big Glob) poisoned the rest
+ *
+ * The decomposition pattern this module enables:
+ *   1. Planner runs ONCE with Sonnet (not Haiku — plans need real
+ *      reasoning, see "Model choice" below)
+ *   2. Emits a Plan: 3-7 PlanSteps, each with title + scope + expected
+ *      tool calls + deliverable artifact path
+ *   3. Plan persists to <project>/.clementine/plans/<planId>.json
+ *      (or BASE_DIR/plans/<planId>.json if no active project)
+ *   4. Orchestrator (bg-orchestrator.ts) queues one bg-task per step,
+ *      each with a tight scope and a fresh 200K worker window
+ *   5. State flows between steps via STATUS.md + the plan ledger;
+ *      no step accumulates context from prior steps
+ *
+ * Model choice: Sonnet, NOT Haiku
+ * ────────────────────────────────
+ * Planning is a reasoning task, not a transformation. A poorly
+ * decomposed plan costs $5+ in downstream worker thrash; a well-
+ * decomposed plan saves multiples of that. The marginal cost of
+ * Sonnet over Haiku (~$0.05-0.15 vs ~$0.01 per plan) is trivial
+ * compared to the downstream cost of bad decomposition. Haiku is for
+ * mechanical tasks (extraction, classification, routing); decomposing
+ * a multi-domain ask into proper steps is not mechanical.
+ *
+ * If you're tempted to "save tokens" by flipping this to Haiku, read
+ * the 2026-05-12 root-cause plan first
+ * (~/.claude/plans/look-at-the-last-vivid-rossum.md). The whole point
+ * of this ship is to NOT cut corners on the decomposition layer.
+ */
+import type { ProjectMeta } from './assistant.js';
+export interface PlanStep {
+    /** 0-indexed position. */
+    index: number;
+    /** Short imperative title (e.g., "Find the coaches project"). */
+    title: string;
+    /** What this step does, in 1-2 sentences. The chained worker sees this. */
+    scope: string;
+    /** Tools the step is expected to call. The chained worker sees this as
+     *  guidance, not enforcement — overshooting is allowed, just not
+     *  preferred. */
+    expectedTools: string[];
+    /** Where the step's output goes (file path, deploy URL, etc.) — used
+     *  by claim-verification + by the next step to find prior work. */
+    deliverable?: string;
+    /** Step status — orchestrator updates this. */
+    status: 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+    /** Set by orchestrator after dispatch. */
+    taskId?: string;
+    /** Worker's final result text (for visibility, capped). */
+    resultPreview?: string;
+    /** Set on completion. */
+    completedAt?: string;
+}
+export interface Plan {
+    /** Unique plan id — also the filename basename. */
+    id: string;
+    /** Chain id — shared by the planner task and all step tasks for one user request. */
+    chainId: string;
+    /** Original user request the planner decomposed. */
+    userRequest: string;
+    /** Resolved project path (if any) when the planner ran. */
+    projectPath?: string;
+    /** Session key of the originating chat — for delivering the final result. */
+    originatingSessionKey?: string;
+    /** ISO when the planner emitted this. */
+    createdAt: string;
+    /** Steps in execution order. */
+    steps: PlanStep[];
+    /** Overall chain status. Derived from steps; persisted for cheap reads. */
+    status: 'pending' | 'in_progress' | 'completed' | 'paused' | 'failed';
+    /** Total estimated cost (USD) for this plan if every step's expectedTools fire as-projected.
+     *  Informational only — not enforced. */
+    estimatedCostUsd?: number;
+    /** Free-form notes from the planner: known risks, assumptions, etc. */
+    notes?: string;
+}
+/**
+ * Where plans live. If `projectPath` is set, plans go inside that
+ * project's `.clementine/plans/` so they travel with the project; if
+ * no project, plans go under `BASE_DIR/plans/` (global).
+ */
+export declare function plansDir(projectPath?: string | null): string;
+export declare function planFile(planId: string, projectPath?: string | null): string;
+export declare function savePlan(plan: Plan, projectPath?: string | null): string;
+export declare function loadPlan(planId: string, projectPath?: string | null): Plan | null;
+export interface PlanRequestOptions {
+    userRequest: string;
+    originatingSessionKey?: string;
+    project?: ProjectMeta | null;
+    /** Optional override; defaults to Sonnet. NEVER pass Haiku here. */
+    model?: string;
+    /** Override the SDK query function for tests. */
+    llmCall?: (prompt: string, systemPrompt: string, model: string) => Promise<string>;
+}
+/**
+ * Decompose a user request into a Plan. Pure async function — no side
+ * effects except the optional LLM call. Caller decides whether to
+ * persist the result via `savePlan`.
+ *
+ * Behavior:
+ *   - Builds a system prompt describing the decomposition contract
+ *   - Asks the model to emit a JSON object matching the Plan schema
+ *   - Validates the response against the schema; logs and retries once on parse failure
+ *   - Returns a Plan ready for orchestrator dispatch
+ *
+ * Failure modes:
+ *   - LLM returns non-JSON → throws PlanGenerationError
+ *   - LLM returns empty steps → throws PlanGenerationError
+ *   - LLM returns >12 steps → trimmed to first 12 with a warning
+ */
+export declare function planRequest(opts: PlanRequestOptions): Promise<Plan>;
+export declare class PlanGenerationError extends Error {
+    constructor(message: string);
+}
+interface RawPlannerResponse {
+    steps?: Array<{
+        title?: unknown;
+        scope?: unknown;
+        expectedTools?: unknown;
+        deliverable?: unknown;
+    }>;
+    estimatedCostUsd?: number;
+    notes?: unknown;
+}
+/** Defensive JSON parse — strips common LLM wrappers (markdown fences,
+ *  leading/trailing prose) before parsing. */
+export declare function parsePlannerResponse(raw: string): RawPlannerResponse | null;
+export {};
+//# sourceMappingURL=bg-planner.d.ts.map