@kernel.chat/kbot 3.99.20 → 3.99.22

package/dist/observer.js

@@ -11,8 +11,12 @@
 // The log file is written by a Claude Code hook (PostToolUse) that appends
 // one JSON line per tool call to ~/.kbot/observer/session.jsonl
 //
-// Format per line:
+// Format per line (schema v1 — legacy):
 //   {"ts":"ISO","tool":"Read","args":{"file_path":"/src/foo.ts"},"result_length":1234,"session":"abc"}
+//
+// Format per line (schema v2 — includes action-token training fields):
+//   {"schema":2,"ts":"ISO","tool":"Read","args":{...},"result_length":1234,"session":"abc",
+//    "durationMs":42,"outcome":"success","resultSize":1234,"error":false}
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';

package/dist/planner/hierarchical/dag.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Task-Decoupled Planning (TDP) — DAG node types.
+ *
+ * Adopted from "Beyond Entangled Planning: Task-Decoupled Planning for
+ * Long-Horizon Agents" (arXiv:2601.07577, 2026). The paper reports up to 82%
+ * token reduction by decomposing a task into a DAG of sub-goals, each executed
+ * under a context scoped to only that node's ancestors — not the full history.
+ *
+ * This module is types-only. Phase 2 of the hierarchical planner will wrap
+ * existing Phase nodes as DAG nodes; no runtime here.
+ *
+ * Scoping rule (paper §3.2): a DAG node's context window contains
+ *   - the node's own sub-goal + acceptance criteria
+ *   - outputs (summaries) of ancestor nodes only
+ *   - the typed tool schemas available for that node
+ * Non-ancestor siblings are excluded. Replanning fires only when the node's
+ * verifier rejects — never regenerates the whole trajectory.
+ */
+import type { Phase, Action, TierVerdict } from './types.js';
+/** Stable node identifier within a DAG. */
+export type NodeId = string;
+/**
+ * One node in the task DAG. In the kbot mapping, a `DAGNode` wraps a `Phase`
+ * and its child `Action`s, adding explicit parent edges and a scoped-context
+ * marker. Keeping `phase` as an embedded field means Phase 2 can migrate
+ * incrementally — tools that walk Phases still work.
+ */
+export interface DAGNode {
+    id: NodeId;
+    /** Parent node ids — the node's inputs. Empty for root. */
+    parents: NodeId[];
+    /** The wrapped Phase. Its `id` is duplicated here as the node id. */
+    phase: Phase;
+    /** Actions executed inside this node. */
+    actions: Action[];
+    /**
+     * Summary of the node's output, produced once status flips to done.
+     * This is what descendants see — not the full action trace.
+     */
+    outputSummary?: string;
+    /** Verdicts emitted against this node only. */
+    verdicts: TierVerdict[];
+    status: 'pending' | 'running' | 'done' | 'failed';
+}
+export interface TaskDAG {
+    /** Root node ids — usually one. */
+    roots: NodeId[];
+    nodes: Record<NodeId, DAGNode>;
+}
+/**
+ * Build the context a node sees during execution. Paper §3.2 calls this the
+ * "scoped context". Returns ancestor summaries plus the node's own sub-goal.
+ *
+ * Ordering: breadth-first from roots, so earlier context appears first in the
+ * prompt. The ancestor set is closed under the transitive parent relation.
+ */
+export declare function buildScopedContext(dag: TaskDAG, nodeId: NodeId): {
+    subGoal: string;
+    ancestorSummaries: Array<{
+        id: NodeId;
+        summary: string;
+    }>;
+};
+/**
+ * Topological order of `dag`. Throws on cycles — DAG invariant is caller's
+ * responsibility to maintain; this is the detector of last resort.
+ */
+export declare function topologicalOrder(dag: TaskDAG): NodeId[];
+/** Nodes whose parents are all done — eligible to run next. */
+export declare function readyNodes(dag: TaskDAG): DAGNode[];
+//# sourceMappingURL=dag.d.ts.map

package/dist/planner/hierarchical/dag.js

@@ -0,0 +1,97 @@
+/**
+ * Task-Decoupled Planning (TDP) — DAG node types.
+ *
+ * Adopted from "Beyond Entangled Planning: Task-Decoupled Planning for
+ * Long-Horizon Agents" (arXiv:2601.07577, 2026). The paper reports up to 82%
+ * token reduction by decomposing a task into a DAG of sub-goals, each executed
+ * under a context scoped to only that node's ancestors — not the full history.
+ *
+ * This module is types-only. Phase 2 of the hierarchical planner will wrap
+ * existing Phase nodes as DAG nodes; no runtime here.
+ *
+ * Scoping rule (paper §3.2): a DAG node's context window contains
+ *   - the node's own sub-goal + acceptance criteria
+ *   - outputs (summaries) of ancestor nodes only
+ *   - the typed tool schemas available for that node
+ * Non-ancestor siblings are excluded. Replanning fires only when the node's
+ * verifier rejects — never regenerates the whole trajectory.
+ */
+/**
+ * Build the context a node sees during execution. Paper §3.2 calls this the
+ * "scoped context". Returns ancestor summaries plus the node's own sub-goal.
+ *
+ * Ordering: breadth-first from roots, so earlier context appears first in the
+ * prompt. The ancestor set is closed under the transitive parent relation.
+ */
+export function buildScopedContext(dag, nodeId) {
+    const node = dag.nodes[nodeId];
+    if (!node) {
+        throw new Error(`buildScopedContext: node ${nodeId} not in DAG`);
+    }
+    const ancestors = collectAncestors(dag, nodeId);
+    const ancestorSummaries = [];
+    for (const aid of ancestors) {
+        const a = dag.nodes[aid];
+        if (a?.outputSummary) {
+            ancestorSummaries.push({ id: aid, summary: a.outputSummary });
+        }
+    }
+    return { subGoal: node.phase.objective, ancestorSummaries };
+}
+/** Transitive parents of `nodeId`, breadth-first, excluding the node itself. */
+function collectAncestors(dag, nodeId) {
+    const seen = new Set();
+    const order = [];
+    const queue = [...(dag.nodes[nodeId]?.parents ?? [])];
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (seen.has(next))
+            continue;
+        seen.add(next);
+        order.push(next);
+        const parent = dag.nodes[next];
+        if (parent)
+            queue.push(...parent.parents);
+    }
+    return order;
+}
+/**
+ * Topological order of `dag`. Throws on cycles — DAG invariant is caller's
+ * responsibility to maintain; this is the detector of last resort.
+ */
+export function topologicalOrder(dag) {
+    const inDegree = {};
+    for (const id of Object.keys(dag.nodes))
+        inDegree[id] = 0;
+    for (const node of Object.values(dag.nodes)) {
+        for (const _p of node.parents) {
+            inDegree[node.id] = (inDegree[node.id] ?? 0) + 1;
+        }
+    }
+    const ready = Object.keys(inDegree).filter(id => inDegree[id] === 0);
+    const out = [];
+    while (ready.length > 0) {
+        const id = ready.shift();
+        out.push(id);
+        for (const other of Object.values(dag.nodes)) {
+            if (other.parents.includes(id)) {
+                inDegree[other.id] -= 1;
+                if (inDegree[other.id] === 0)
+                    ready.push(other.id);
+            }
+        }
+    }
+    if (out.length !== Object.keys(dag.nodes).length) {
+        throw new Error('topologicalOrder: cycle detected in task DAG');
+    }
+    return out;
+}
+/** Nodes whose parents are all done — eligible to run next. */
+export function readyNodes(dag) {
+    return Object.values(dag.nodes).filter(n => {
+        if (n.status !== 'pending')
+            return false;
+        return n.parents.every(pid => dag.nodes[pid]?.status === 'done');
+    });
+}
+//# sourceMappingURL=dag.js.map

package/dist/planner/hierarchical/persistence.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Hierarchical Planner — persistence helpers.
+ *
+ * Goals are stored as individual JSON files under
+ * `~/.kbot/planner/goals/<id>.json`. The currently-active goal id is recorded
+ * at `~/.kbot/planner/active.json` as `{ "goalId": "<ulid>" }`.
+ *
+ * Scope: atomic read/write, listing, and active-pointer management. No
+ * tier logic here.
+ */
+import type { SessionGoal } from './types.js';
+/** Default on-disk root: `~/.kbot/planner/`. */
+export declare function defaultStateDir(): string;
+/** Read a single goal by id, or null if missing. */
+export declare function readGoal(stateDir: string, id: string): Promise<SessionGoal | null>;
+/** Write (create-or-overwrite) a goal file. */
+export declare function writeGoal(stateDir: string, goal: SessionGoal): Promise<void>;
+/** List every goal on disk (unsorted). */
+export declare function listGoals(stateDir: string): Promise<SessionGoal[]>;
+/** Set the active goal pointer. The goal must already exist on disk. */
+export declare function setActive(stateDir: string, goalId: string): Promise<void>;
+/** Read the active goal (resolves pointer → goal file). Returns null if unset. */
+export declare function getActive(stateDir: string): Promise<SessionGoal | null>;
+/** Clear the active pointer (goal files untouched). */
+export declare function clearActive(stateDir: string): Promise<void>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/planner/hierarchical/persistence.js

@@ -0,0 +1,113 @@
+/**
+ * Hierarchical Planner — persistence helpers.
+ *
+ * Goals are stored as individual JSON files under
+ * `~/.kbot/planner/goals/<id>.json`. The currently-active goal id is recorded
+ * at `~/.kbot/planner/active.json` as `{ "goalId": "<ulid>" }`.
+ *
+ * Scope: atomic read/write, listing, and active-pointer management. No
+ * tier logic here.
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Default on-disk root: `~/.kbot/planner/`. */
+export function defaultStateDir() {
+    return path.join(os.homedir(), '.kbot', 'planner');
+}
+function goalsDir(stateDir) {
+    return path.join(stateDir, 'goals');
+}
+function goalPath(stateDir, id) {
+    return path.join(goalsDir(stateDir), `${id}.json`);
+}
+function activePath(stateDir) {
+    return path.join(stateDir, 'active.json');
+}
+async function ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+/** Read a single goal by id, or null if missing. */
+export async function readGoal(stateDir, id) {
+    try {
+        const raw = await fs.readFile(goalPath(stateDir, id), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/** Write (create-or-overwrite) a goal file. */
+export async function writeGoal(stateDir, goal) {
+    await ensureDir(goalsDir(stateDir));
+    const tmp = goalPath(stateDir, goal.id) + '.tmp';
+    const final = goalPath(stateDir, goal.id);
+    await fs.writeFile(tmp, JSON.stringify(goal, null, 2), 'utf8');
+    await fs.rename(tmp, final);
+}
+/** List every goal on disk (unsorted). */
+export async function listGoals(stateDir) {
+    const dir = goalsDir(stateDir);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const goals = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        try {
+            const raw = await fs.readFile(path.join(dir, entry), 'utf8');
+            goals.push(JSON.parse(raw));
+        }
+        catch {
+            // skip unreadable / malformed files; don't let one bad file poison the list
+        }
+    }
+    return goals;
+}
+/** Set the active goal pointer. The goal must already exist on disk. */
+export async function setActive(stateDir, goalId) {
+    const existing = await readGoal(stateDir, goalId);
+    if (!existing) {
+        throw new Error(`setActive: goal ${goalId} not found in ${goalsDir(stateDir)}`);
+    }
+    await ensureDir(stateDir);
+    const tmp = activePath(stateDir) + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify({ goalId }, null, 2), 'utf8');
+    await fs.rename(tmp, activePath(stateDir));
+}
+/** Read the active goal (resolves pointer → goal file). Returns null if unset. */
+export async function getActive(stateDir) {
+    let ptr;
+    try {
+        const raw = await fs.readFile(activePath(stateDir), 'utf8');
+        ptr = JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    if (!ptr.goalId)
+        return null;
+    return readGoal(stateDir, ptr.goalId);
+}
+/** Clear the active pointer (goal files untouched). */
+export async function clearActive(stateDir) {
+    try {
+        await fs.unlink(activePath(stateDir));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+//# sourceMappingURL=persistence.js.map

package/dist/planner/hierarchical/session-planner.d.ts

@@ -0,0 +1,68 @@
+/**
+ * HierarchicalPlanner — Phase 1 passthrough.
+ *
+ * This file lays the pipe for the four-tier hierarchical planner described in
+ * ./types.ts. Today it does NOT implement tiers — `planAndExecute` delegates
+ * the entire user turn to the existing flat `autonomousExecute` from
+ * ../../planner.ts and synthesizes a `PlannerResult` shell around it.
+ *
+ * Real goal persistence is live: `loadGoal`, `createGoal`, and `setGoal` read
+ * and write `~/.kbot/planner/goals/<id>.json` plus the `active.json` pointer.
+ * The current PlannerResult.goal is always `null` in this phase because the
+ * tier-1 selection/creation loop isn't wired in yet — callers opt into goal
+ * tracking explicitly via createGoal/setGoal.
+ *
+ * Feature flag: `planAndExecute` throws unless `process.env.KBOT_PLANNER ===
+ * 'hierarchical'`. Nothing in production calls this class yet.
+ */
+import type { AgentOptions } from '../../agent.js';
+import type { Action, Phase, SessionGoal, TurnMetrics } from './types.js';
+export type Ulid = string;
+/** Minimal shape planAndExecute needs from the caller. Expand in Phase 2. */
+export interface SessionContext {
+    /** Optional session identifier (e.g. from memory.ts). */
+    sessionId?: string;
+    /** Agent options to thread into the underlying planner. */
+    agentOpts: AgentOptions;
+    /** When true, skip interactive approval on the underlying planner. */
+    autoApprove?: boolean;
+}
+/**
+ * Phase-1 `PlannerResult`. Shape matches the spec in this ticket — NOT the
+ * richer `PlannerResult` in ./types.ts, which targets Phase 2+. We use a local
+ * name to avoid a clash and to flag this is transitional.
+ */
+export interface PlannerResult {
+    /** Always null in Phase 1; Phase 2 will populate via tier-1 logic. */
+    goal: SessionGoal | null;
+    /** Ephemeral placeholder phase spanning just this turn. */
+    phase: Phase;
+    /** The action derived from autonomousExecute's flat plan. */
+    action: Action;
+    metrics: TurnMetrics;
+}
+export interface HierarchicalPlannerOptions {
+    /** Override persistence root; defaults to `~/.kbot/planner/`. */
+    stateDir?: string;
+}
+export declare class HierarchicalPlanner {
+    private readonly stateDir;
+    constructor(opts?: HierarchicalPlannerOptions);
+    /**
+     * Plan and execute one user turn.
+     *
+     * Phase 1: feature-flag gated passthrough to autonomousExecute.
+     * Phase 2+: replace the body with the Tier 1–4 cascade.
+     */
+    planAndExecute(userTurn: string, ctx: SessionContext): Promise<PlannerResult>;
+    /** Read the currently-active goal from disk, or null if none is set. */
+    loadGoal(): Promise<SessionGoal | null>;
+    /**
+     * Create a new goal on disk and mark it active.
+     * Fields the caller omits are filled with sensible defaults.
+     */
+    createGoal(spec?: Partial<SessionGoal>): Promise<SessionGoal>;
+    /** Activate an existing goal by id. Throws if the goal does not exist. */
+    setGoal(goalId: Ulid): Promise<void>;
+}
+//# sourceMappingURL=session-planner.d.ts.map

package/dist/planner/hierarchical/session-planner.js

@@ -0,0 +1,141 @@
+/**
+ * HierarchicalPlanner — Phase 1 passthrough.
+ *
+ * This file lays the pipe for the four-tier hierarchical planner described in
+ * ./types.ts. Today it does NOT implement tiers — `planAndExecute` delegates
+ * the entire user turn to the existing flat `autonomousExecute` from
+ * ../../planner.ts and synthesizes a `PlannerResult` shell around it.
+ *
+ * Real goal persistence is live: `loadGoal`, `createGoal`, and `setGoal` read
+ * and write `~/.kbot/planner/goals/<id>.json` plus the `active.json` pointer.
+ * The current PlannerResult.goal is always `null` in this phase because the
+ * tier-1 selection/creation loop isn't wired in yet — callers opt into goal
+ * tracking explicitly via createGoal/setGoal.
+ *
+ * Feature flag: `planAndExecute` throws unless `process.env.KBOT_PLANNER ===
+ * 'hierarchical'`. Nothing in production calls this class yet.
+ */
+import { randomBytes } from 'node:crypto';
+import { autonomousExecute } from '../../planner.js';
+import { defaultStateDir, getActive, readGoal, setActive, writeGoal, } from './persistence.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// ULID-ish id generator.
+// We depend on `ulid` if it's resolvable at runtime, otherwise fall back to a
+// 26-char Crockford-base32 string sourced from crypto.randomBytes. Either way
+// IDs are sortable-ish and collision-resistant enough for per-goal filenames.
+// ─────────────────────────────────────────────────────────────────────────────
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function cryptoUlid() {
+    // 10 chars of timestamp (ms) + 16 chars of randomness = 26 chars.
+    let ts = Date.now();
+    const tsChars = [];
+    for (let i = 0; i < 10; i++) {
+        tsChars.unshift(CROCKFORD[ts % 32]);
+        ts = Math.floor(ts / 32);
+    }
+    const bytes = randomBytes(10);
+    const rand = [];
+    // 80 bits → 16 base32 chars. Pull 5 bits at a time.
+    let acc = 0;
+    let accBits = 0;
+    for (const b of bytes) {
+        acc = (acc << 8) | b;
+        accBits += 8;
+        while (accBits >= 5) {
+            accBits -= 5;
+            rand.push(CROCKFORD[(acc >> accBits) & 0x1f]);
+        }
+    }
+    return tsChars.join('') + rand.slice(0, 16).join('');
+}
+export class HierarchicalPlanner {
+    stateDir;
+    constructor(opts = {}) {
+        this.stateDir = opts.stateDir ?? defaultStateDir();
+    }
+    /**
+     * Plan and execute one user turn.
+     *
+     * Phase 1: feature-flag gated passthrough to autonomousExecute.
+     * Phase 2+: replace the body with the Tier 1–4 cascade.
+     */
+    async planAndExecute(userTurn, ctx) {
+        const flag = process.env.KBOT_PLANNER;
+        if (flag !== 'hierarchical') {
+            throw new Error(`HierarchicalPlanner.planAndExecute is gated behind KBOT_PLANNER=hierarchical ` +
+                `(got ${flag ?? 'unset'}). This path is Phase-1 scaffolding only.`);
+        }
+        const startedAt = Date.now();
+        const plan = await autonomousExecute(userTurn, ctx.agentOpts, {
+            autoApprove: ctx.autoApprove ?? true,
+        });
+        const phase = {
+            id: cryptoUlid(),
+            goalId: '', // no goal linked in Phase 1
+            kind: 'other',
+            objective: userTurn,
+            exitCriteria: [],
+            startedAt: new Date(startedAt).toISOString(),
+            endedAt: new Date().toISOString(),
+            status: plan.status === 'completed' ? 'done' : 'active',
+        };
+        const steps = plan.steps.map(step => ({ ...step }));
+        const action = {
+            id: cryptoUlid(),
+            phaseId: phase.id,
+            userTurn,
+            summary: plan.summary,
+            steps,
+            createdAt: plan.createdAt,
+            status: plan.status === 'completed'
+                ? 'done'
+                : plan.status === 'failed'
+                    ? 'failed'
+                    : 'running',
+        };
+        const metrics = {
+            tier1Calls: 0,
+            tier2Calls: 0,
+            tier3Calls: 1, // autonomousExecute counts as one tier-3 invocation
+            tier4Calls: steps.length,
+            tokensIn: 0,
+            tokensOut: 0,
+            wallMs: Date.now() - startedAt,
+        };
+        // Phase 1 never attaches a goal — that's Phase 2.
+        return { goal: null, phase, action, metrics };
+    }
+    /** Read the currently-active goal from disk, or null if none is set. */
+    async loadGoal() {
+        return getActive(this.stateDir);
+    }
+    /**
+     * Create a new goal on disk and mark it active.
+     * Fields the caller omits are filled with sensible defaults.
+     */
+    async createGoal(spec = {}) {
+        const now = new Date().toISOString();
+        const goal = {
+            id: spec.id ?? cryptoUlid(),
+            title: spec.title ?? '(untitled goal)',
+            intent: spec.intent ?? '',
+            acceptance: spec.acceptance ?? [],
+            createdAt: spec.createdAt ?? now,
+            updatedAt: spec.updatedAt ?? now,
+            status: spec.status ?? 'active',
+            tags: spec.tags,
+        };
+        await writeGoal(this.stateDir, goal);
+        await setActive(this.stateDir, goal.id);
+        return goal;
+    }
+    /** Activate an existing goal by id. Throws if the goal does not exist. */
+    async setGoal(goalId) {
+        const existing = await readGoal(this.stateDir, goalId);
+        if (!existing) {
+            throw new Error(`setGoal: goal ${goalId} not found under ${this.stateDir}`);
+        }
+        await setActive(this.stateDir, goalId);
+    }
+}
+//# sourceMappingURL=session-planner.js.map

package/dist/planner/hierarchical/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Hierarchical Planner — Type Definitions
+ *
+ * Four tiers, increasing temporal resolution:
+ *   Tier 1  SessionGoal     days → weeks     (Opus, rarely re-planned)
+ *   Tier 2  Phase           hours            (Opus, on scope shift)
+ *   Tier 3  Action          minutes          (Sonnet, per user turn)
+ *   Tier 4  ToolCallSpec    seconds          (Haiku, per tool call)
+ *
+ * Inspired by Suno's 3-stage transformer (semantic → coarse acoustic → fine
+ * acoustic). Coarse intent is stable; fine actuation is cheap and rewritten.
+ *
+ * See DESIGN.md in this directory for the full rationale, cost model,
+ * decision logic, and integration plan. This file is types-only — no imports
+ * from heavy runtime modules, no implementation.
+ */
+import type { PlanStep } from '../../planner.js';
+/** Long-lived user objective that spans many turns and possibly many sessions. */
+export interface SessionGoal {
+    /** Stable identifier (uuid). Persists across sessions. */
+    id: string;
+    /** Short title: "ship hierarchical planner v1". */
+    title: string;
+    /** 1–3 sentence rationale: what success looks like. */
+    intent: string;
+    /** Acceptance criteria — bullet list the user would agree closes the goal. */
+    acceptance: string[];
+    /** ISO timestamps. */
+    createdAt: string;
+    updatedAt: string;
+    /** Lifecycle. `paused` goals stay on disk but don't get re-planned. */
+    status: 'active' | 'paused' | 'completed' | 'abandoned';
+    /** Free-form tags: repo name, domain, user-supplied label. */
+    tags?: string[];
+}
+/** Coarse mode the agent is currently operating in. */
+export type PhaseKind = 'explore' | 'build' | 'debug' | 'review' | 'write' | 'refactor' | 'deploy' | 'other';
+/** A contiguous stretch of work under one mode, toward one milestone. */
+export interface Phase {
+    id: string;
+    /** Parent goal. */
+    goalId: string;
+    kind: PhaseKind;
+    /** What this phase commits to producing. */
+    objective: string;
+    /** Exit criteria — when `kind` should flip or phase should close. */
+    exitCriteria: string[];
+    /** Files or subsystems scoped in. */
+    scope?: string[];
+    /** ISO timestamps. */
+    startedAt: string;
+    endedAt?: string;
+    status: 'active' | 'done' | 'aborted';
+}
+/**
+ * One action = one user turn's plan. Steps are the existing `PlanStep`s so we
+ * stay compatible with `planner.ts#executePlan`.
+ */
+export interface ActionStep extends PlanStep {
+}
+export interface Action {
+    id: string;
+    phaseId: string;
+    /** Verbatim user turn that triggered this action. */
+    userTurn: string;
+    /** One-sentence plan. */
+    summary: string;
+    /** Ordered steps; each step is a PlanStep-compatible record. */
+    steps: ActionStep[];
+    /** Agents this action expects to consult (from learned-router). */
+    expectedAgents?: string[];
+    createdAt: string;
+    status: 'pending' | 'running' | 'done' | 'failed';
+}
+/** Coarse hazard class used to gate permissions and verdict logic. */
+export type SideEffectClass = 'pure' | 'read' | 'write' | 'exec' | 'network' | 'destructive' | 'external';
+/** The final low-level tool call. Haiku fills this in. */
+export interface ToolCallSpec {
+    id: string;
+    actionId: string;
+    stepId: number;
+    tool: string;
+    args: Record<string, unknown>;
+    sideEffect: SideEffectClass;
+    /** Optional prediction of what the tool should return on success. */
+    expectedOutcome?: string;
+    /** Hard ceiling in ms; falls back to pipeline default when absent. */
+    timeoutMs?: number;
+}
+export type VerdictDecision = 'continue' | 'revise-action' | 'revise-phase' | 'revise-goal' | 'abort';
+/** Emitted after every tool call; consumed by the up-delegation ladder. */
+export interface TierVerdict {
+    decision: VerdictDecision;
+    tier: 'tool' | 'action' | 'phase' | 'goal';
+    reason: string;
+    /** Evidence: tool error, failed assertion, diff summary. */
+    evidence?: string;
+}
+export interface TurnMetrics {
+    tier1Calls: number;
+    tier2Calls: number;
+    tier3Calls: number;
+    tier4Calls: number;
+    tokensIn: number;
+    tokensOut: number;
+    wallMs: number;
+}
+/** Top-level return of `HierarchicalPlanner.planTurn`. */
+export interface PlannerResult {
+    goal: SessionGoal;
+    phase: Phase;
+    action: Action;
+    verdicts: TierVerdict[];
+    metrics: TurnMetrics;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/planner/hierarchical/types.js

@@ -0,0 +1,18 @@
+/**
+ * Hierarchical Planner — Type Definitions
+ *
+ * Four tiers, increasing temporal resolution:
+ *   Tier 1  SessionGoal     days → weeks     (Opus, rarely re-planned)
+ *   Tier 2  Phase           hours            (Opus, on scope shift)
+ *   Tier 3  Action          minutes          (Sonnet, per user turn)
+ *   Tier 4  ToolCallSpec    seconds          (Haiku, per tool call)
+ *
+ * Inspired by Suno's 3-stage transformer (semantic → coarse acoustic → fine
+ * acoustic). Coarse intent is stable; fine actuation is cheap and rewritten.
+ *
+ * See DESIGN.md in this directory for the full rationale, cost model,
+ * decision logic, and integration plan. This file is types-only — no imports
+ * from heavy runtime modules, no implementation.
+ */
+export {};
+//# sourceMappingURL=types.js.map