@kernel.chat/kbot 3.99.20 → 3.99.21

package/dist/integrations/kbot-control-client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * kbot-control-client.ts — TCP client for kbot-control.amxd
+ *
+ * Singleton client that connects to the kbot-control Max for Live device
+ * at 127.0.0.1:9000. Newline-delimited JSON-RPC 2.0 over plain TCP.
+ * Zero npm dependencies — uses node:net only.
+ *
+ * Supersedes:
+ *   - ableton-osc.ts (UDP 11000, AbletonOSC Remote Script)
+ *   - ableton-bridge.ts (TCP 9001, AbletonBridge)
+ *   - ableton-m4l.ts (TCP 9999, kbot-bridge.amxd)
+ *
+ * Fallback order when this client can't connect:
+ *   1. kbot-control.amxd (this)
+ *   2. ableton-osc.ts (legacy)
+ *   3. Claude computer-use MCP (last resort)
+ */
+export interface RpcRequest {
+    jsonrpc: '2.0';
+    id: number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface RpcResponse<T = unknown> {
+    jsonrpc: '2.0';
+    id: number | null;
+    result?: T;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export type Listener = (value: unknown) => void;
+export declare class KbotControlClient {
+    private static instance;
+    private socket;
+    private connected;
+    private buffer;
+    private pending;
+    private listeners;
+    private nextId;
+    private connectAttempt;
+    static HOST: string;
+    static PORT: number;
+    static TIMEOUT: number;
+    static CONNECT_TIMEOUT: number;
+    private constructor();
+    static get(): KbotControlClient;
+    connect(): Promise<void>;
+    private handleData;
+    private handleMessage;
+    call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    subscribe(path: string, fn: Listener): Promise<void>;
+    unsubscribe(path: string, fn: Listener): Promise<void>;
+    private pollers;
+    private startPolling;
+    private stopPolling;
+    disconnect(): void;
+    get isConnected(): boolean;
+}
+/**
+ * Convenience: connect + call + return result.
+ * Throws if kbot-control.amxd isn't loaded in Ableton.
+ */
+export declare function kc<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+//# sourceMappingURL=kbot-control-client.d.ts.map

package/dist/integrations/kbot-control-client.js

@@ -0,0 +1,224 @@
+/**
+ * kbot-control-client.ts — TCP client for kbot-control.amxd
+ *
+ * Singleton client that connects to the kbot-control Max for Live device
+ * at 127.0.0.1:9000. Newline-delimited JSON-RPC 2.0 over plain TCP.
+ * Zero npm dependencies — uses node:net only.
+ *
+ * Supersedes:
+ *   - ableton-osc.ts (UDP 11000, AbletonOSC Remote Script)
+ *   - ableton-bridge.ts (TCP 9001, AbletonBridge)
+ *   - ableton-m4l.ts (TCP 9999, kbot-bridge.amxd)
+ *
+ * Fallback order when this client can't connect:
+ *   1. kbot-control.amxd (this)
+ *   2. ableton-osc.ts (legacy)
+ *   3. Claude computer-use MCP (last resort)
+ */
+import * as net from 'node:net';
+export class KbotControlClient {
+    static instance = null;
+    socket = null;
+    connected = false;
+    buffer = '';
+    pending = new Map();
+    listeners = new Map();
+    nextId = 1;
+    connectAttempt = null;
+    static HOST = '127.0.0.1';
+    static PORT = 9000;
+    static TIMEOUT = 15_000;
+    static CONNECT_TIMEOUT = 3_000;
+    constructor() { }
+    static get() {
+        if (!this.instance)
+            this.instance = new KbotControlClient();
+        return this.instance;
+    }
+    async connect() {
+        if (this.connected)
+            return;
+        if (this.connectAttempt)
+            return this.connectAttempt;
+        this.connectAttempt = new Promise((resolve, reject) => {
+            const sock = new net.Socket();
+            const timer = setTimeout(() => {
+                sock.destroy();
+                reject(new Error(`kbot-control: connect timeout (${KbotControlClient.CONNECT_TIMEOUT}ms)`));
+            }, KbotControlClient.CONNECT_TIMEOUT);
+            sock.connect(KbotControlClient.PORT, KbotControlClient.HOST, () => {
+                clearTimeout(timer);
+                this.socket = sock;
+                this.connected = true;
+                resolve();
+            });
+            sock.on('data', (chunk) => this.handleData(chunk.toString()));
+            sock.on('close', () => {
+                this.connected = false;
+                this.socket = null;
+                for (const [, p] of this.pending) {
+                    clearTimeout(p.timer);
+                    p.reject(new Error('kbot-control: connection closed'));
+                }
+                this.pending.clear();
+            });
+            sock.on('error', (e) => {
+                clearTimeout(timer);
+                this.connected = false;
+                reject(new Error(`kbot-control: ${e.message} — is kbot-control.amxd loaded in Ableton on a track?`));
+            });
+        });
+        try {
+            await this.connectAttempt;
+        }
+        finally {
+            this.connectAttempt = null;
+        }
+    }
+    handleData(chunk) {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() || '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            this.handleMessage(trimmed);
+        }
+    }
+    handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        // Notifications (listener events) — no id
+        if ('method' in msg && msg.method === 'notify') {
+            const { path, value } = msg.params || {};
+            if (path) {
+                const set = this.listeners.get(path);
+                if (set)
+                    for (const fn of set)
+                        fn(value);
+            }
+            return;
+        }
+        // Server hello greeting
+        if ('method' in msg && msg.method === 'hello')
+            return;
+        const response = msg;
+        if (response.id == null)
+            return;
+        const p = this.pending.get(response.id);
+        if (!p)
+            return;
+        this.pending.delete(response.id);
+        clearTimeout(p.timer);
+        if (response.error)
+            p.reject(new Error(`[${response.error.code}] ${response.error.message}`));
+        else
+            p.resolve(response.result);
+    }
+    async call(method, params) {
+        await this.connect();
+        if (!this.socket)
+            throw new Error('kbot-control: not connected');
+        const id = this.nextId++;
+        const req = { jsonrpc: '2.0', id, method, params };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`kbot-control: timeout on ${method} (${KbotControlClient.TIMEOUT}ms)`));
+            }, KbotControlClient.TIMEOUT);
+            this.pending.set(id, {
+                resolve: (r) => resolve(r),
+                reject,
+                timer,
+            });
+            this.socket.write(JSON.stringify(req) + '\n');
+        });
+    }
+    async subscribe(path, fn) {
+        let set = this.listeners.get(path);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(path, set);
+            await this.call('listen.subscribe', { path });
+            // Start a polling loop as a fallback until the outlet-based push works.
+            // This also catches events even when the push path breaks.
+            this.startPolling(path);
+        }
+        set.add(fn);
+    }
+    async unsubscribe(path, fn) {
+        const set = this.listeners.get(path);
+        if (!set)
+            return;
+        set.delete(fn);
+        if (set.size === 0) {
+            this.listeners.delete(path);
+            this.stopPolling(path);
+            try {
+                await this.call('listen.unsubscribe', { path });
+            }
+            catch { /* ignore */ }
+        }
+    }
+    pollers = new Map();
+    startPolling(path, intervalMs = 150) {
+        if (this.pollers.has(path))
+            return;
+        const state = { timer: null, since: 0 };
+        state.timer = setInterval(async () => {
+            try {
+                const r = await this.call('listen.poll', { path, since: state.since });
+                if (r && r.events && r.events.length > 0) {
+                    state.since = r.latest_seq;
+                    const set = this.listeners.get(path);
+                    if (set) {
+                        for (const ev of r.events) {
+                            // LiveAPI often reports values as [propertyName, value]; unwrap.
+                            let v = ev.value;
+                            if (Array.isArray(v) && v.length === 2 && typeof v[0] === 'string')
+                                v = v[1];
+                            for (const fn of set)
+                                fn(v);
+                        }
+                    }
+                }
+                else if (r && typeof r.latest_seq === 'number') {
+                    state.since = r.latest_seq;
+                }
+            }
+            catch { /* ignore transient errors */ }
+        }, intervalMs);
+        this.pollers.set(path, state);
+    }
+    stopPolling(path) {
+        const s = this.pollers.get(path);
+        if (s) {
+            clearInterval(s.timer);
+            this.pollers.delete(path);
+        }
+    }
+    disconnect() {
+        for (const [, s] of this.pollers)
+            clearInterval(s.timer);
+        this.pollers.clear();
+        if (this.socket)
+            this.socket.destroy();
+        this.socket = null;
+        this.connected = false;
+    }
+    get isConnected() { return this.connected; }
+}
+/**
+ * Convenience: connect + call + return result.
+ * Throws if kbot-control.amxd isn't loaded in Ableton.
+ */
+export async function kc(method, params) {
+    return KbotControlClient.get().call(method, params);
+}
+//# sourceMappingURL=kbot-control-client.js.map

package/dist/observer.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Outcome classification for tool calls.
+ * Required for training an action-token model — cannot be backfilled from logs.
+ */
+export type ToolOutcome = 'success' | 'error' | 'timeout' | 'empty' | 'large';
 export interface ObservedToolCall {
     ts: string;
     tool: string;
@@ -5,6 +10,14 @@ export interface ObservedToolCall {
     result_length?: number;
     session?: string;
     error?: boolean;
+    /** Schema version. Absent = v1 (legacy). 2 = includes durationMs/outcome/resultSize. */
+    schema?: number;
+    /** Wall-clock duration of tool execution in milliseconds. (schema v2+) */
+    durationMs?: number;
+    /** Outcome classification for training. (schema v2+) */
+    outcome?: ToolOutcome;
+    /** Bytes of serialized result (Buffer.byteLength of result string). (schema v2+) */
+    resultSize?: number;
 }
 export interface ObserverStats {
     totalObserved: number;

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/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