@kernel.chat/kbot 3.99.19 → 3.99.21

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

package/dist/tool-pipeline.d.ts

@@ -57,6 +57,40 @@ export declare function truncationMiddleware(maxSize?: number): ToolMiddleware;
  * Emits tool_call_start and tool_call_end events.
  */
 export declare function telemetryMiddleware(emit: (event: string, data: any) => void): ToolMiddleware;
+/**
+ * Thresholds for outcome classification.
+ * Exported so downstream code (training, analytics) can mirror them.
+ */
+export declare const OUTCOME_EMPTY_THRESHOLD = 5;
+export declare const OUTCOME_LARGE_THRESHOLD = 10240;
+/**
+ * Classify a tool execution outcome from its ToolContext.
+ *
+ * Priority:
+ *   1. timeout  — aborted with timeout reason
+ *   2. error    — ctx.error is set (or aborted for any other reason)
+ *   3. empty    — result present but shorter than OUTCOME_EMPTY_THRESHOLD chars
+ *   4. large    — result byte length > OUTCOME_LARGE_THRESHOLD
+ *   5. success  — anything else
+ */
+export declare function classifyOutcome(ctx: ToolContext): 'success' | 'error' | 'timeout' | 'empty' | 'large';
+/**
+ * Observer middleware — writes an observation to ~/.kbot/observer/session.jsonl.
+ *
+ * Records the three fields that cannot be backfilled for action-token training:
+ *   - durationMs: wall-clock time of tool execution
+ *   - outcome:    success | error | timeout | empty | large
+ *   - resultSize: byte length of the serialized result
+ *
+ * Emits schema v2 events. Backward compatible — consumers that don't know
+ * about the new fields will ignore them (the tokenizer has fallbacks).
+ *
+ * Place this as the OUTERMOST middleware so duration captures the true
+ * wall-clock of the full pipeline (including timeout, truncation, fallback).
+ */
+export declare function observerMiddleware(sessionId: string, options?: {
+    enabled?: () => boolean;
+}): ToolMiddleware;
 /**
  * Execution middleware — the actual tool call.
  * This should be the last middleware in the pipeline.
@@ -100,7 +134,7 @@ export declare function fallbackMiddleware(rules: FallbackRule[], execute: (name
 export declare function resourceAwareMiddleware(): ToolMiddleware;
 /**
  * Create the default pipeline with the standard middleware stack.
- * Order: telemetry? → permission → hooks → resource → metrics → timeout → truncation → fallback? → execution
+ * Order: observer? → telemetry? → permission → hooks → resource → metrics → timeout → truncation → fallback? → execution
  */
 export declare function createDefaultPipeline(deps: {
     checkPermission: (name: string, args: any) => Promise<boolean>;
@@ -116,5 +150,9 @@ export declare function createDefaultPipeline(deps: {
     recordMetrics: (name: string, duration: number, error?: string) => void;
     emit?: (event: string, data: any) => void;
     fallbackRules?: FallbackRule[];
+    /** If set, observerMiddleware is added as the outermost layer and writes to ~/.kbot/observer/session.jsonl. */
+    observerSessionId?: string;
+    /** Runtime gate for observer writes. */
+    observerEnabled?: () => boolean;
 }): ToolPipeline;
 //# sourceMappingURL=tool-pipeline.d.ts.map

package/dist/tool-pipeline.js

@@ -162,6 +162,111 @@ export function telemetryMiddleware(emit) {
         });
     };
 }
+// ── Outcome classification ──
+/**
+ * Thresholds for outcome classification.
+ * Exported so downstream code (training, analytics) can mirror them.
+ */
+export const OUTCOME_EMPTY_THRESHOLD = 5; // result under this many chars → "empty"
+export const OUTCOME_LARGE_THRESHOLD = 10_240; // result over this many bytes → "large"
+/**
+ * Classify a tool execution outcome from its ToolContext.
+ *
+ * Priority:
+ *   1. timeout  — aborted with timeout reason
+ *   2. error    — ctx.error is set (or aborted for any other reason)
+ *   3. empty    — result present but shorter than OUTCOME_EMPTY_THRESHOLD chars
+ *   4. large    — result byte length > OUTCOME_LARGE_THRESHOLD
+ *   5. success  — anything else
+ */
+export function classifyOutcome(ctx) {
+    // Timeout takes precedence over generic error because the error string is set too.
+    if (ctx.aborted && /timed?\s*out|timeout/i.test(ctx.abortReason ?? ctx.error ?? '')) {
+        return 'timeout';
+    }
+    if (ctx.error || ctx.aborted)
+        return 'error';
+    const result = ctx.result ?? '';
+    if (result.length < OUTCOME_EMPTY_THRESHOLD)
+        return 'empty';
+    if (Buffer.byteLength(result, 'utf8') > OUTCOME_LARGE_THRESHOLD)
+        return 'large';
+    return 'success';
+}
+/**
+ * Observer middleware — writes an observation to ~/.kbot/observer/session.jsonl.
+ *
+ * Records the three fields that cannot be backfilled for action-token training:
+ *   - durationMs: wall-clock time of tool execution
+ *   - outcome:    success | error | timeout | empty | large
+ *   - resultSize: byte length of the serialized result
+ *
+ * Emits schema v2 events. Backward compatible — consumers that don't know
+ * about the new fields will ignore them (the tokenizer has fallbacks).
+ *
+ * Place this as the OUTERMOST middleware so duration captures the true
+ * wall-clock of the full pipeline (including timeout, truncation, fallback).
+ */
+export function observerMiddleware(sessionId, options = {}) {
+    return async (ctx, next) => {
+        const start = Date.now();
+        let threw = undefined;
+        try {
+            await next();
+        }
+        catch (err) {
+            // Capture so we can still log; rethrow after.
+            threw = err;
+            if (!ctx.error)
+                ctx.error = err instanceof Error ? err.message : String(err);
+        }
+        const durationMs = Date.now() - start;
+        // Allow runtime opt-out (e.g. user disabled observer).
+        if (options.enabled && !options.enabled()) {
+            if (threw)
+                throw threw;
+            return;
+        }
+        const result = ctx.result ?? '';
+        const resultSize = Buffer.byteLength(result, 'utf8');
+        const outcome = classifyOutcome(ctx);
+        try {
+            const { recordObservation } = await import('./observer.js');
+            // Extract a few "safe" arg fields for indexing — mirror what agent.ts does.
+            const a = (ctx.toolArgs ?? {});
+            const args = {};
+            if (typeof a.file_path === 'string')
+                args.file_path = a.file_path;
+            else if (typeof a.path === 'string')
+                args.path = a.path;
+            if (typeof a.command === 'string')
+                args.command = a.command.slice(0, 200);
+            if (typeof a.pattern === 'string')
+                args.pattern = a.pattern;
+            if (typeof a.url === 'string')
+                args.url = a.url;
+            if (typeof a.query === 'string')
+                args.query = a.query;
+            recordObservation({
+                schema: 2,
+                ts: new Date(start).toISOString(),
+                tool: ctx.toolName,
+                args,
+                result_length: result.length,
+                session: sessionId,
+                error: Boolean(ctx.error),
+                durationMs,
+                outcome,
+                resultSize,
+            });
+        }
+        catch {
+            /* observer is non-critical — never break tool execution */
+        }
+        if (threw)
+            throw threw;
+    };
+}
 /**
  * Execution middleware — the actual tool call.
  * This should be the last middleware in the pipeline.
@@ -313,10 +418,13 @@ export function resourceAwareMiddleware() {
 }
 /**
  * Create the default pipeline with the standard middleware stack.
- * Order: telemetry? → permission → hooks → resource → metrics → timeout → truncation → fallback? → execution
+ * Order: observer? → telemetry? → permission → hooks → resource → metrics → timeout → truncation → fallback? → execution
  */
 export function createDefaultPipeline(deps) {
     const pipeline = new ToolPipeline();
+    if (deps.observerSessionId) {
+        pipeline.use(observerMiddleware(deps.observerSessionId, { enabled: deps.observerEnabled }));
+    }
     if (deps.emit) {
         pipeline.use(telemetryMiddleware(deps.emit));
     }

package/dist/tools/ableton-listen.d.ts

@@ -0,0 +1,2 @@
+export declare function registerAbletonListenTool(): void;
+//# sourceMappingURL=ableton-listen.d.ts.map

package/dist/tools/ableton-listen.js

@@ -0,0 +1,126 @@
+// ableton_listen — subscribe to real-time LOM events via kbot-control.
+//
+// AbletonOSC has no listener API. kbot-control implements listeners using
+// native Max LiveAPI property callbacks, streamed over the TCP JSON-RPC
+// connection as "notify" messages. This tool exposes that capability to
+// the agent so it can subscribe to beat, playing_position, parameter
+// changes, etc., and pull a buffered history for inspection.
+import { registerTool } from './index.js';
+import { KbotControlClient } from '../integrations/kbot-control-client.js';
+// Per-path ring buffer of recent events so the agent can poll history.
+const MAX_PER_PATH = 100;
+const history = new Map();
+const subscriptions = new Map();
+function recordEvent(path, value) {
+    let buf = history.get(path);
+    if (!buf) {
+        buf = [];
+        history.set(path, buf);
+    }
+    buf.push({ path, value, at: Date.now() });
+    if (buf.length > MAX_PER_PATH)
+        buf.shift();
+}
+export function registerAbletonListenTool() {
+    registerTool({
+        name: 'ableton_listen',
+        description: 'Subscribe to real-time Ableton events via kbot-control.amxd. ' +
+            'Subscriptions stream over the persistent TCP connection and the tool buffers the last 100 events per path. ' +
+            'Use action="subscribe" with a LOM-ish path (e.g. "song.is_playing", "song.tempo", "tracks[0].output_meter_left"), ' +
+            'then action="history" to pull what came in. action="list" shows active subscriptions. ' +
+            'Requires kbot-control.amxd loaded in Ableton.',
+        parameters: {
+            action: {
+                type: 'string',
+                description: '"subscribe" | "unsubscribe" | "list" | "history" | "clear"',
+                required: true,
+            },
+            path: {
+                type: 'string',
+                description: 'LOM path for subscribe/unsubscribe/history. Examples: "song.is_playing", "song.tempo", "song.current_song_time", "tracks[0].mute".',
+            },
+            limit: {
+                type: 'number',
+                description: 'For "history": max events to return (default 25).',
+            },
+        },
+        tier: 'free',
+        timeout: 15_000,
+        async execute(args) {
+            const action = String(args.action || '').toLowerCase();
+            const path = args.path !== undefined ? String(args.path) : '';
+            try {
+                switch (action) {
+                    case 'subscribe': {
+                        if (!path)
+                            return 'Error: subscribe needs a path.';
+                        if (subscriptions.has(path))
+                            return `Already subscribed to ${path}`;
+                        const handler = (value) => recordEvent(path, value);
+                        await KbotControlClient.get().subscribe(path, handler);
+                        subscriptions.set(path, handler);
+                        return `Subscribed to \`${path}\`. Events will be recorded; call action="history" to pull them.`;
+                    }
+                    case 'unsubscribe': {
+                        if (!path)
+                            return 'Error: unsubscribe needs a path.';
+                        const handler = subscriptions.get(path);
+                        if (!handler)
+                            return `Not subscribed to ${path}`;
+                        await KbotControlClient.get().unsubscribe(path, handler);
+                        subscriptions.delete(path);
+                        return `Unsubscribed from ${path}`;
+                    }
+                    case 'list': {
+                        if (subscriptions.size === 0)
+                            return 'No active subscriptions.';
+                        const lines = ['## Active subscriptions', ''];
+                        for (const p of subscriptions.keys()) {
+                            const buf = history.get(p);
+                            lines.push(`- \`${p}\` — ${buf ? buf.length : 0} events buffered`);
+                        }
+                        return lines.join('\n');
+                    }
+                    case 'history': {
+                        if (!path) {
+                            // Return summary of all paths
+                            if (history.size === 0)
+                                return 'No events recorded yet.';
+                            const lines = ['## Event history summary', ''];
+                            for (const [p, buf] of history.entries()) {
+                                const last = buf[buf.length - 1];
+                                lines.push(`- \`${p}\`: ${buf.length} events, last value = ${JSON.stringify(last?.value)}`);
+                            }
+                            return lines.join('\n');
+                        }
+                        const buf = history.get(path);
+                        if (!buf || buf.length === 0)
+                            return `No events recorded for \`${path}\`.`;
+                        const limit = Number(args.limit) || 25;
+                        const recent = buf.slice(-limit);
+                        const lines = [`## \`${path}\` — last ${recent.length} events`, ''];
+                        for (const ev of recent) {
+                            const dt = new Date(ev.at).toISOString().slice(11, 23);
+                            lines.push(`- ${dt} → ${JSON.stringify(ev.value)}`);
+                        }
+                        return lines.join('\n');
+                    }
+                    case 'clear': {
+                        if (path) {
+                            history.delete(path);
+                            return `Cleared history for ${path}`;
+                        }
+                        history.clear();
+                        return 'Cleared all history';
+                    }
+                    default:
+                        return `Unknown action "${action}". Options: subscribe, unsubscribe, list, history, clear`;
+                }
+            }
+            catch (e) {
+                return `ableton_listen error: ${e.message}`;
+            }
+        },
+    });
+}
+//# sourceMappingURL=ableton-listen.js.map