loadout-ai 0.8.0 → 0.9.0

package/dist/src/core/coordination/session-manager.js

@@ -0,0 +1,366 @@
+/**
+ * Session manager for coordinated agent sessions.
+ *
+ * Tracks active sessions across providers, handles reconnection with
+ * snapshot replay, and routes coordination events as follow-up turns.
+ */
+import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { formatEventsForInjection } from "./adapters/types.js";
+import { snapshot, readAfterCursor } from "./coordinator.js";
+import { watchCoordination } from "./watcher.js";
+import { isKillSwitchActive } from "./crash-recovery.js";
+import { categorizeEvents, DEFAULT_POLICY, loadPolicy, } from "./interrupt-policy.js";
+const COORD_DIR = ".handoff";
+const SESSIONS_FILE = "sessions.json";
+const agentSessionSchema = z
+    .object({
+    sessionId: z.string().trim().min(1).max(1_024),
+    agent: z.string().trim().min(1).max(128),
+    provider: z.string().trim().min(1).max(128),
+    active: z.boolean(),
+    busy: z.boolean(),
+    cursor: z.number().int().min(-1),
+    startedAt: z.iso.datetime({ offset: true }),
+    cwd: z.string().min(1),
+})
+    .strict();
+const sessionStoreSchema = z
+    .object({
+    sessions: z.array(agentSessionSchema).max(100),
+    updatedAt: z.iso.datetime({ offset: true }),
+})
+    .strict();
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+export class SessionManager {
+    sessions = new Map();
+    adapters = new Map();
+    pendingEvents = new Map();
+    watcher = null;
+    options;
+    policy = DEFAULT_POLICY;
+    autoTurnCounts = new Map();
+    constructor(options) {
+        if (options.maxAutoTurnsPerSession !== undefined &&
+            (!Number.isSafeInteger(options.maxAutoTurnsPerSession) ||
+                options.maxAutoTurnsPerSession < 1)) {
+            throw new Error("maxAutoTurnsPerSession must be a positive integer");
+        }
+        this.options = options;
+        for (const adapter of options.adapters) {
+            this.adapters.set(adapter.provider, adapter);
+        }
+    }
+    /** Start the session manager — load persisted sessions and watch for events. */
+    async start() {
+        await this.loadSessions();
+        this.policy = await loadPolicy(this.options.projectRoot);
+        if (this.options.autoSubmit !== false) {
+            this.watcher = await watchCoordination(this.options.projectRoot, {
+                onEvents: (events) => {
+                    void this.handleEvents(events).catch((error) => {
+                        const message = error instanceof Error ? error.message : String(error);
+                        console.error(`Session manager routing error: ${message}`);
+                    });
+                },
+                onError: (err) => console.error(`Session manager watcher error: ${err.message}`),
+            });
+        }
+    }
+    /** Stop the session manager. */
+    async stop() {
+        this.watcher?.stop();
+        this.watcher = null;
+    }
+    /** Detect which agent CLIs are available. */
+    async detectProviders() {
+        const results = [];
+        for (const adapter of this.adapters.values()) {
+            const version = await adapter.detect();
+            if (version) {
+                results.push({ provider: adapter.provider, version });
+            }
+        }
+        return results;
+    }
+    /** Start a new agent session. */
+    async startSession(provider, cwd, prompt, timeout) {
+        const killSwitch = await isKillSwitchActive(this.options.projectRoot);
+        if (killSwitch.active) {
+            throw new Error(`Coordination kill switch is active${killSwitch.reason ? `: ${killSwitch.reason}` : ""}`);
+        }
+        const adapter = this.adapters.get(provider);
+        if (!adapter)
+            throw new Error(`No adapter for provider: ${provider}`);
+        const session = await adapter.start({
+            cwd,
+            prompt,
+            ...(timeout === undefined ? {} : { timeout }),
+        });
+        this.sessions.set(session.sessionId, session);
+        await this.saveSessions();
+        // A tracking-only manager must never create an implicit paid turn.
+        // Bridge managers replay the current snapshot once start() is idle.
+        if (this.options.autoSubmit !== false &&
+            adapter.capabilities.canSubmitTurn) {
+            const snap = await snapshot(this.options.projectRoot, provider);
+            await this.submitEvents(session, snap.unackedForAgent);
+        }
+        return session;
+    }
+    /** Resume an existing session with snapshot replay. */
+    async resumeSession(provider, sessionId, cwd) {
+        const killSwitch = await isKillSwitchActive(this.options.projectRoot);
+        if (killSwitch.active) {
+            throw new Error(`Coordination kill switch is active${killSwitch.reason ? `: ${killSwitch.reason}` : ""}`);
+        }
+        const adapter = this.adapters.get(provider);
+        if (!adapter)
+            throw new Error(`No adapter for provider: ${provider}`);
+        if (!adapter.capabilities.canResume) {
+            throw new Error(`${provider} does not support session resumption`);
+        }
+        const tracked = this.sessions.get(sessionId);
+        if (!tracked || tracked.provider !== provider) {
+            throw new Error(`Session ${sessionId} is not tracked by Loadout`);
+        }
+        const session = await adapter.resume(sessionId, cwd);
+        session.cursor = tracked.cursor;
+        session.startedAt = tracked.startedAt;
+        this.sessions.set(session.sessionId, session);
+        // Replay missed events
+        if (adapter.capabilities.canSubmitTurn && session.cursor >= 0) {
+            const { events } = await readAfterCursor(this.options.projectRoot, session.cursor);
+            const relevant = events.filter((e) => e.from !== provider &&
+                (e.to === provider || e.to === "*") &&
+                e.type !== "ack");
+            if (relevant.length > 0) {
+                await this.submitEvents(session, relevant);
+            }
+        }
+        await this.saveSessions();
+        return session;
+    }
+    /**
+     * Attach a session that was created by the provider rather than Loadout.
+     * This is the explicit bridge boundary: the user supplies the host session
+     * id, then Loadout can resume it and route future coordination turns.
+     */
+    async attachSession(provider, sessionId, cwd) {
+        const killSwitch = await isKillSwitchActive(this.options.projectRoot);
+        if (killSwitch.active) {
+            throw new Error(`Coordination kill switch is active${killSwitch.reason ? `: ${killSwitch.reason}` : ""}`);
+        }
+        const adapter = this.adapters.get(provider);
+        if (!adapter)
+            throw new Error(`No adapter for provider: ${provider}`);
+        if (!adapter.capabilities.canResume) {
+            throw new Error(`${provider} does not support session resumption`);
+        }
+        const tracked = this.sessions.get(sessionId);
+        if (tracked && tracked.provider !== provider) {
+            throw new Error(`Session ${sessionId} is already tracked for ${tracked.provider}`);
+        }
+        const session = await adapter.resume(sessionId, cwd);
+        session.cursor = tracked?.cursor ?? -1;
+        session.startedAt = tracked?.startedAt ?? session.startedAt;
+        this.sessions.set(sessionId, session);
+        if (this.options.autoSubmit !== false) {
+            const snap = await snapshot(this.options.projectRoot, provider);
+            await this.submitEvents(session, snap.unackedForAgent);
+        }
+        await this.saveSessions();
+        return session;
+    }
+    /** Stop a session. */
+    async stopSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        const adapter = this.adapters.get(session.provider);
+        if (adapter) {
+            await adapter.stop(session);
+        }
+        session.active = false;
+        await this.saveSessions();
+    }
+    /** Get all tracked sessions. */
+    getSessions() {
+        return [...this.sessions.values()];
+    }
+    /** Get active sessions only. */
+    getActiveSessions() {
+        return [...this.sessions.values()].filter((s) => s.active);
+    }
+    /** Read the most recent in-memory provider response without persisting it. */
+    getLastResponse(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return undefined;
+        return this.adapters.get(session.provider)?.lastResponse?.(sessionId);
+    }
+    /** Submit a direct follow-up turn, denying it while the session is busy. */
+    async submitTurn(sessionId, message, timeout) {
+        if ((await isKillSwitchActive(this.options.projectRoot)).active) {
+            return false;
+        }
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} is not tracked by Loadout`);
+        }
+        if (!session.active)
+            return false;
+        const adapter = this.adapters.get(session.provider);
+        if (!adapter?.capabilities.canSubmitTurn)
+            return false;
+        if (session.busy)
+            return false;
+        const success = await adapter.submitTurn(session, {
+            message,
+            ...(timeout === undefined ? {} : { timeout }),
+        });
+        if (success) {
+            this.options.onTurnCompleted?.(session, adapter.lastResponse?.(session.sessionId));
+            await this.flushPendingEvents(session);
+        }
+        await this.saveSessions();
+        return success;
+    }
+    /** Route coordination events to active sessions. */
+    async handleEvents(events) {
+        if ((await isKillSwitchActive(this.options.projectRoot)).active)
+            return;
+        const deliveries = [];
+        for (const session of this.sessions.values()) {
+            if (!session.active)
+                continue;
+            const adapter = this.adapters.get(session.provider);
+            if (!adapter)
+                continue;
+            // Filter events relevant to this session's agent
+            const relevant = events.filter((e) => e.from !== session.agent &&
+                (e.to === session.agent || e.to === "*") &&
+                e.type !== "ack");
+            if (relevant.length === 0)
+                continue;
+            deliveries.push(this.submitEvents(session, relevant));
+        }
+        await Promise.all(deliveries);
+    }
+    async submitEvents(session, events) {
+        if (events.length === 0)
+            return;
+        if ((await isKillSwitchActive(this.options.projectRoot)).active)
+            return;
+        const categorized = categorizeEvents(events, this.policy);
+        if (categorized.passive.length > 0) {
+            this.options.onPendingEvents?.(session, categorized.passive);
+        }
+        const deliverable = [
+            ...categorized.immediate,
+            ...categorized.boundary,
+        ].sort((left, right) => left.seq - right.seq);
+        if (deliverable.length === 0)
+            return;
+        const adapter = this.adapters.get(session.provider);
+        if (!adapter?.capabilities.canSubmitTurn) {
+            this.options.onPendingEvents?.(session, deliverable);
+            return;
+        }
+        const turns = this.autoTurnCounts.get(session.sessionId) ?? 0;
+        const maxTurns = this.options.maxAutoTurnsPerSession ?? 20;
+        if (turns >= maxTurns) {
+            this.options.onPendingEvents?.(session, deliverable);
+            return;
+        }
+        if (session.busy) {
+            this.queueEvents(session, deliverable);
+            return;
+        }
+        const message = formatEventsForInjection(deliverable);
+        const success = await adapter.submitTurn(session, { message });
+        if (!success) {
+            if (session.busy) {
+                this.queueEvents(session, deliverable);
+            }
+            else {
+                this.options.onPendingEvents?.(session, deliverable);
+            }
+            return;
+        }
+        this.autoTurnCounts.set(session.sessionId, turns + 1);
+        session.cursor = Math.max(session.cursor, deliverable[deliverable.length - 1].seq);
+        this.options.onTurnCompleted?.(session, adapter.lastResponse?.(session.sessionId));
+        await this.saveSessions();
+        await this.flushPendingEvents(session);
+    }
+    queueEvents(session, events) {
+        const pending = this.pendingEvents.get(session.sessionId) ?? [];
+        pending.push(...events);
+        this.pendingEvents.set(session.sessionId, pending);
+        this.options.onPendingEvents?.(session, events);
+    }
+    async flushPendingEvents(session) {
+        if (session.busy)
+            return;
+        const pending = this.pendingEvents.get(session.sessionId);
+        if (!pending?.length)
+            return;
+        this.pendingEvents.delete(session.sessionId);
+        await this.submitEvents(session, pending);
+    }
+    /** Load persisted session state. */
+    async loadSessions() {
+        let raw;
+        try {
+            raw = await readFile(join(this.options.projectRoot, COORD_DIR, SESSIONS_FILE), "utf-8");
+        }
+        catch (error) {
+            if (errorCode(error) === "ENOENT")
+                return;
+            throw error;
+        }
+        let decoded;
+        try {
+            decoded = JSON.parse(raw);
+        }
+        catch {
+            throw new Error("Invalid persisted session state: expected JSON");
+        }
+        const parsed = sessionStoreSchema.safeParse(decoded);
+        if (!parsed.success) {
+            throw new Error(`Invalid persisted session state: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`);
+        }
+        for (const stored of parsed.data.sessions) {
+            const session = {
+                ...stored,
+                // A process restart detaches every host session until explicitly resumed.
+                active: false,
+                busy: false,
+            };
+            this.sessions.set(session.sessionId, session);
+        }
+    }
+    /** Persist session state. */
+    async saveSessions() {
+        const dir = join(this.options.projectRoot, COORD_DIR);
+        await mkdir(dir, { recursive: true });
+        const store = {
+            sessions: [...this.sessions.values()],
+            updatedAt: new Date().toISOString(),
+        };
+        const path = join(dir, SESSIONS_FILE);
+        const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        await writeFile(temporary, JSON.stringify(store, null, 2) + "\n", {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+        await rename(temporary, path);
+    }
+}

package/dist/src/core/coordination/watcher.js

@@ -0,0 +1,128 @@
+/**
+ * Live file watcher for coordination events.
+ *
+ * Watches `.handoff/coordination.jsonl` and calls back when new events appear.
+ * This is the "live" part of Phase 2 — no daemon, no SQLite, just fs.watch on
+ * the append-only log.
+ */
+import { watch } from "node:fs";
+import { join } from "node:path";
+import { readCoordLog } from "./coordinator.js";
+const COORD_DIR = ".handoff";
+const COORD_LOG = "coordination.jsonl";
+export async function watchCoordination(projectRoot, options) {
+    // Get initial state
+    const initial = await readCoordLog(projectRoot);
+    let cursor = options.cursor ?? initial.highSeq;
+    let debounceTimer;
+    let stopped = false;
+    async function checkForUpdates() {
+        if (stopped)
+            return;
+        try {
+            const log = await readCoordLog(projectRoot);
+            if (log.highSeq <= cursor)
+                return;
+            let events = log.events.filter((e) => e.seq > cursor);
+            // Filter for agent if specified
+            if (options.agent) {
+                const agent = options.agent;
+                events = events.filter((e) => e.to === agent || e.to === "*" || e.from === agent);
+            }
+            cursor = log.highSeq;
+            if (events.length > 0) {
+                options.onEvents(events, log.highSeq);
+            }
+        }
+        catch (error) {
+            options.onError?.(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    // Debounced check — multiple rapid writes only trigger one read
+    function scheduleCheck() {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            checkForUpdates();
+        }, 100);
+    }
+    // Watch the directory (more reliable than watching a single file across platforms)
+    let fsWatcher;
+    try {
+        fsWatcher = watch(join(projectRoot, COORD_DIR), { persistent: true }, (eventType, filename) => {
+            if (filename === COORD_LOG || filename === null) {
+                scheduleCheck();
+            }
+        });
+    }
+    catch {
+        // Directory might not exist yet — watch the project root for its creation
+        fsWatcher = watch(projectRoot, { persistent: true }, (eventType, filename) => {
+            if (filename === COORD_DIR) {
+                scheduleCheck();
+            }
+        });
+    }
+    fsWatcher.on("error", (error) => {
+        options.onError?.(error);
+    });
+    return {
+        stop() {
+            stopped = true;
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            fsWatcher.close();
+        },
+        get cursor() {
+            return cursor;
+        },
+    };
+}
+/**
+ * Format a live event for terminal display.
+ */
+export function formatLiveEvent(event) {
+    const time = event.timestamp.slice(11, 19);
+    const typeColors = {
+        contract: "\x1b[36m", // cyan
+        ownership: "\x1b[33m", // yellow
+        decision: "\x1b[35m", // magenta
+        update: "\x1b[32m", // green
+        ack: "\x1b[90m", // gray
+        task: "\x1b[34m", // blue
+        done: "\x1b[32m", // green
+        error: "\x1b[31m", // red
+    };
+    const color = typeColors[event.type] ?? "\x1b[0m";
+    const reset = "\x1b[0m";
+    const bold = "\x1b[1m";
+    const parts = [
+        `${bold}${time}${reset}`,
+        `${color}[${event.type}]${reset}`,
+        `${bold}${event.from}${reset}`,
+        event.to !== "*" ? `→ ${event.to}` : "",
+        event.description,
+    ].filter(Boolean);
+    const lines = [parts.join(" ")];
+    // Show payload highlights for interesting event types
+    if (event.type === "contract" && event.payload) {
+        const p = event.payload;
+        lines.push(`  📋 ${p.name} rev${p.revision}${p.format ? ` (${p.format})` : ""}`);
+    }
+    if (event.type === "ownership" && event.payload) {
+        const p = event.payload;
+        lines.push(`  🔒 ${p.mode}: ${p.paths.join(", ")}`);
+    }
+    if (event.type === "update" && event.payload) {
+        const p = event.payload;
+        if (p.blockers?.length)
+            lines.push(`  🚫 Blockers: ${p.blockers.join(", ")}`);
+        if (p.next)
+            lines.push(`  ⏭️  Next: ${p.next}`);
+    }
+    if (event.type === "decision" && event.payload) {
+        const p = event.payload;
+        lines.push(`  📌 ${p.rationale.slice(0, 120)}`);
+    }
+    return lines.join("\n");
+}

package/dist/src/core/{routing → delegation}/first-party-skills.js

@@ -2,11 +2,12 @@ import { cp, rm, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { detectAgents } from "../agents/paths.js";
+import { runMutationTransaction } from "../install/transaction.js";
 export const FIRST_PARTY_SKILLS = [
     {
-        id: "loadout-router",
-        displayName: "Loadout Router",
-        summary: "Lets an agent pick the right model tier for a task and hand work to another agent",
+        id: "loadout-handoff",
+        displayName: "Loadout Handoff",
+        summary: "Lets an agent pass tasks to your other agent and pick up what was left for it",
     },
     {
         id: "loadout-curator",
@@ -74,18 +75,29 @@ export async function planFirstPartySkill(id, options = {}) {
     return { skill, source, targets };
 }
 export async function applyFirstPartySkill(plan) {
-    for (const target of plan.targets) {
-        // Replace wholesale so a reinstall cannot leave files from an older
-        // version of the skill behind.
-        if (target.replacing)
-            await rm(target.destination, { recursive: true });
-        await cp(plan.source, target.destination, { recursive: true });
-    }
+    const applied = await runMutationTransaction(async () => ({
+        targets: plan.targets.map((target) => target.destination),
+        value: plan,
+    }), async (freshPlan) => {
+        for (const target of freshPlan.targets) {
+            // Replace wholesale so a reinstall cannot leave files from an older
+            // version of the skill behind.
+            await rm(target.destination, { recursive: true, force: true });
+            await cp(freshPlan.source, target.destination, { recursive: true });
+        }
+    }, { label: `install first-party skill ${plan.skill.id}` });
+    return applied.snapshotId;
 }
 export async function removeFirstPartySkill(plan) {
-    for (const target of plan.targets)
-        if (target.replacing)
-            await rm(target.destination, { recursive: true });
+    const present = plan.targets.filter((target) => target.replacing);
+    const applied = await runMutationTransaction(async () => ({
+        targets: present.map((target) => target.destination),
+        value: present,
+    }), async (freshTargets) => {
+        for (const target of freshTargets)
+            await rm(target.destination, { recursive: true, force: true });
+    }, { label: `remove first-party skill ${plan.skill.id}` });
+    return applied.snapshotId;
 }
 export function formatFirstPartySkillList(installedIds = new Set()) {
     const lines = ["Skills that ship with Loadout:", ""];

package/dist/src/core/{routing → delegation}/handoff.js

@@ -2,6 +2,30 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { writeFileAtomically } from "../install/atomic-file.js";
+import { z } from "zod";
+const handoffMessageSchema = z.object({
+    id: z.string().trim().min(1),
+    type: z.enum([
+        "task",
+        "handoff",
+        "question",
+        "done",
+        "status",
+        "error",
+        "cancel",
+    ]),
+    from: z.string().trim().min(1),
+    to: z.string().trim().min(1),
+    description: z.string().trim().min(1),
+    context: z.string().optional(),
+    timestamp: z.iso.datetime({ offset: true }),
+    resolves: z.string().trim().min(1).optional(),
+});
+function handoffValidationReason(error) {
+    return error.issues
+        .map((issue) => `${issue.path.join(".") || "message"}: ${issue.message}`)
+        .join("; ");
+}
 /** Message types that settle a task, so it stops appearing in an inbox. */
 const TERMINAL_TYPES = new Set(["done", "error", "cancel"]);
 const HANDOFF_DIR = ".handoff";
@@ -66,7 +90,7 @@ export async function sendHandoff(projectRoot, to, description, options = {}) {
     if (!(await isHandoffInitialized(projectRoot))) {
         throw new Error("Handoff is not set up here. Send a task and it will create itself: loadout handoff <agent> '<task>'");
     }
-    const message = {
+    const candidate = {
         id: randomUUID().slice(0, 8),
         type: options.type ?? "task",
         from: options.from ?? "user",
@@ -76,18 +100,24 @@ export async function sendHandoff(projectRoot, to, description, options = {}) {
         ...(options.resolves ? { resolves: options.resolves } : {}),
         timestamp: new Date().toISOString(),
     };
+    const parsed = handoffMessageSchema.safeParse(candidate);
+    if (!parsed.success)
+        throw new Error(`Invalid handoff message: ${handoffValidationReason(parsed.error)}`);
+    const message = parsed.data;
     const path = messagesPath(projectRoot);
     const line = JSON.stringify(message) + "\n";
     await writeFile(path, line, { flag: "a" });
     return message;
 }
 export async function markDone(projectRoot, messageId) {
-    const messages = await readMessages(projectRoot);
-    const original = messages.find((m) => m.id === messageId);
+    const state = await getHandoffState(projectRoot);
+    const original = state.messages.find((m) => m.id === messageId);
     if (!original)
         throw new Error(`Message '${messageId}' not found`);
-    if (original.type === "done")
-        throw new Error(`Message '${messageId}' is already done`);
+    if (original.type !== "task")
+        throw new Error(`Message '${messageId}' is not a task`);
+    if (state.done.some((message) => message.id === messageId))
+        throw new Error(`Message '${messageId}' is already settled`);
     return sendHandoff(projectRoot, original.from, `Completed: ${original.description}`, {
         from: original.to,
         type: "done",
@@ -115,10 +145,11 @@ export async function readMessagesDetailed(projectRoot) {
         if (!raw.trim())
             return;
         try {
-            const parsed = JSON.parse(raw);
-            if (!parsed || typeof parsed.id !== "string" || !parsed.type)
-                throw new Error("missing id or type");
-            messages.push(parsed);
+            const parsed = handoffMessageSchema.safeParse(JSON.parse(raw));
+            if (!parsed.success) {
+                throw new Error(handoffValidationReason(parsed.error));
+            }
+            messages.push(parsed.data);
         }
         catch (error) {
             corrupt.push({