loadout-ai 0.6.0 → 0.8.0

package/dist/src/core/routing/handoff.js

@@ -0,0 +1,314 @@
+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";
+/** 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";
+const MESSAGES_FILE = "messages.jsonl";
+const PROTOCOL_FILE = "PROTOCOL.md";
+function handoffDir(projectRoot) {
+    return join(projectRoot, HANDOFF_DIR);
+}
+function messagesPath(projectRoot) {
+    return join(handoffDir(projectRoot), MESSAGES_FILE);
+}
+export async function isHandoffInitialized(projectRoot) {
+    try {
+        await readFile(join(handoffDir(projectRoot), PROTOCOL_FILE), "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function initHandoff(projectRoot) {
+    const dir = handoffDir(projectRoot);
+    await mkdir(dir, { recursive: true });
+    const protocol = [
+        "# Handoff",
+        "",
+        "A shared task log so two AI coding agents can pass work between them.",
+        "Created by `loadout handoff`. Append-only JSONL; no server, no daemon.",
+        "",
+        "## Using it",
+        "",
+        "```",
+        "loadout handoff codex 'write unit tests for auth' --context 'see src/auth.ts'",
+        "loadout handoff codex          # what is waiting for codex",
+        "loadout handoff                # everything pending, both directions",
+        "loadout handoff --done <id>    # finished",
+        "```",
+        "",
+        "Sending sets this directory up on first use and adds a short block to",
+        "CLAUDE.md and AGENTS.md telling each agent to check its inbox at session",
+        "start. Only the text between the loadout:handoff markers is managed.",
+        "",
+        "## Files",
+        "",
+        "- `messages.jsonl` — the log, one JSON object per line",
+        "- `PROTOCOL.md` — this file",
+        "",
+        "Commit both if you want the log shared across machines.",
+        "",
+    ].join("\n");
+    await writeFileAtomically(join(dir, PROTOCOL_FILE), protocol);
+    // Create empty messages file if it doesn't exist
+    try {
+        await readFile(messagesPath(projectRoot));
+    }
+    catch {
+        await writeFile(messagesPath(projectRoot), "", "utf8");
+    }
+    return dir;
+}
+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 = {
+        id: randomUUID().slice(0, 8),
+        type: options.type ?? "task",
+        from: options.from ?? "user",
+        to,
+        description,
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.resolves ? { resolves: options.resolves } : {}),
+        timestamp: new Date().toISOString(),
+    };
+    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);
+    if (!original)
+        throw new Error(`Message '${messageId}' not found`);
+    if (original.type === "done")
+        throw new Error(`Message '${messageId}' is already done`);
+    return sendHandoff(projectRoot, original.from, `Completed: ${original.description}`, {
+        from: original.to,
+        type: "done",
+        resolves: messageId,
+    });
+}
+/**
+ * Parse the log one line at a time. A single truncated write previously made
+ * the whole inbox look empty, which is the worst possible failure for a queue:
+ * silent and total. Bad lines are collected and reported instead.
+ */
+export async function readMessagesDetailed(projectRoot) {
+    if (!(await isHandoffInitialized(projectRoot)))
+        return { messages: [], corrupt: [] };
+    let content;
+    try {
+        content = await readFile(messagesPath(projectRoot), "utf8");
+    }
+    catch {
+        return { messages: [], corrupt: [] };
+    }
+    const messages = [];
+    const corrupt = [];
+    content.split("\n").forEach((raw, index) => {
+        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);
+        }
+        catch (error) {
+            corrupt.push({
+                line: index + 1,
+                reason: error instanceof Error ? error.message : "unparseable",
+            });
+        }
+    });
+    return { messages, corrupt };
+}
+export async function readMessages(projectRoot) {
+    return (await readMessagesDetailed(projectRoot)).messages;
+}
+export async function getHandoffState(projectRoot) {
+    const initialized = await isHandoffInitialized(projectRoot);
+    const { messages, corrupt } = initialized
+        ? await readMessagesDetailed(projectRoot)
+        : { messages: [], corrupt: [] };
+    // A task is settled by completion, failure, or withdrawal. Treating only
+    // `done` as terminal left failed tasks pending forever.
+    const resolvedIds = new Set(messages
+        .filter((m) => TERMINAL_TYPES.has(m.type))
+        .flatMap((m) => {
+        if (m.resolves)
+            return [m.resolves];
+        // Logs written before `resolves` existed encode it in the context.
+        const match = m.context?.match(/Resolves (\w+)/);
+        return match ? [match[1]] : [];
+    }));
+    const pending = messages.filter((m) => m.type === "task" && !resolvedIds.has(m.id));
+    const done = messages.filter((m) => m.type === "task" && resolvedIds.has(m.id));
+    return {
+        initialized,
+        directory: handoffDir(projectRoot),
+        messages,
+        pending,
+        done,
+        corrupt,
+    };
+}
+// ---------------------------------------------------------------------------
+// Consumption — the half that makes a handoff more than an outbox
+// ---------------------------------------------------------------------------
+/** Pending tasks addressed to one agent, oldest first. */
+export async function readInbox(projectRoot, agent) {
+    const state = await getHandoffState(projectRoot);
+    return state.pending.filter((m) => m.to === agent);
+}
+/**
+ * Render an agent's inbox as instructions the agent itself can act on. This is
+ * what `loadout handoff <agent>` prints, and what the generated pickup block
+ * tells each agent to run, so the message log is consumed rather than merely
+ * written.
+ */
+export function formatInbox(agent, messages) {
+    if (!messages.length)
+        return `No pending handoff tasks for ${agent}.`;
+    const lines = [
+        `${messages.length} pending handoff task(s) for ${agent}:`,
+        "",
+    ];
+    for (const m of messages) {
+        lines.push(`[${m.id}] from ${m.from} (${m.timestamp.slice(0, 16).replace("T", " ")})`);
+        lines.push(`  ${m.description}`);
+        if (m.context)
+            lines.push(`  context: ${m.context}`);
+        lines.push(`  when finished: loadout handoff --done ${m.id}`);
+        lines.push("");
+    }
+    lines.push("Work these in order. Mark each done as you complete it so the sender sees progress.");
+    return lines.join("\n");
+}
+const PICKUP_START = "<!-- loadout:handoff:start -->";
+const PICKUP_END = "<!-- loadout:handoff:end -->";
+/** The managed instruction block written into an agent's context file. */
+export function pickupBlock(agent) {
+    return [
+        PICKUP_START,
+        "",
+        "## Handoff inbox",
+        "",
+        `At the start of a session, and whenever you finish a task, run:`,
+        "",
+        "```bash",
+        `loadout handoff ${agent}`,
+        "```",
+        "",
+        "If it lists pending tasks, work them in order and run the `loadout handoff --done`",
+        "command it prints for each one. If it reports none, continue as normal.",
+        "",
+        PICKUP_END,
+    ].join("\n");
+}
+/** Agent context files, relative to the project root. */
+const AGENT_CONTEXT_FILES = {
+    "claude-code": "CLAUDE.md",
+    codex: "AGENTS.md",
+};
+/** True when this agent has a context file Loadout knows how to write. */
+export function isPickupTarget(agent) {
+    return agent in AGENT_CONTEXT_FILES;
+}
+export function agentContextFile(agent) {
+    const file = AGENT_CONTEXT_FILES[agent];
+    if (!file)
+        throw new Error(`No known context file for agent '${agent}'. Supported: ${Object.keys(AGENT_CONTEXT_FILES).join(", ")}`);
+    return file;
+}
+/**
+ * Compute the new content for an agent's context file with the pickup block
+ * added or refreshed. Existing content is preserved; only the managed block
+ * between the markers is replaced.
+ */
+export async function planPickup(projectRoot, agent) {
+    const file = agentContextFile(agent);
+    const path = join(projectRoot, file);
+    const block = pickupBlock(agent);
+    let existing = "";
+    let exists = false;
+    try {
+        existing = await readFile(path, "utf8");
+        exists = true;
+    }
+    catch {
+        // A missing context file is created with just the managed block.
+    }
+    const start = existing.indexOf(PICKUP_START);
+    const end = existing.indexOf(PICKUP_END);
+    const replacing = start !== -1 && end !== -1 && end > start;
+    // A block written by an older release still tells the agent to run commands
+    // that no longer exist, so a rewrite is a migration, not a no-op.
+    const stale = replacing &&
+        /loadout handoff (?:inbox|send|init|status|done)\b/.test(existing.slice(start, end));
+    const content = replacing
+        ? existing.slice(0, start) + block + existing.slice(end + PICKUP_END.length)
+        : exists
+            ? `${existing.replace(/\s*$/, "")}\n\n${block}\n`
+            : `${block}\n`;
+    return { path, agent, exists, replacing, stale, content };
+}
+export async function applyPickup(plan) {
+    await writeFileAtomically(plan.path, plan.content);
+}
+export function formatPickupPlan(plans) {
+    const lines = ["Handoff pickup instructions:", ""];
+    for (const plan of plans) {
+        const action = plan.stale
+            ? "migrate outdated block in"
+            : plan.replacing
+                ? "refresh managed block in"
+                : plan.exists
+                    ? "append managed block to"
+                    : "create";
+        lines.push(`  ${action} ${plan.path}`);
+    }
+    lines.push("", "This teaches each agent to check its handoff inbox at session start.", "Only the block between the loadout:handoff markers is managed; the rest of", "each file is preserved.");
+    return lines.join("\n");
+}
+export function formatHandoffStatus(state) {
+    if (!state.initialized)
+        return "No handoff log here yet. Send a task and it creates itself: loadout handoff <agent> '<task>'";
+    if (state.messages.length === 0)
+        return "No handoff messages yet. Send one with `loadout handoff <agent> '<task>'`.";
+    const lines = [];
+    if (state.pending.length) {
+        lines.push(`Pending (${state.pending.length}):`);
+        for (const m of state.pending) {
+            lines.push(`  ${m.id}  ${m.from} → ${m.to}  ${m.description}`);
+        }
+    }
+    if (state.done.length) {
+        if (lines.length)
+            lines.push("");
+        lines.push(`Done (${state.done.length}):`);
+        for (const m of state.done) {
+            lines.push(`  ${m.id}  ${m.from} → ${m.to}  ${m.description}`);
+        }
+    }
+    if (state.corrupt.length) {
+        if (lines.length)
+            lines.push("");
+        lines.push(`Warning: ${state.corrupt.length} unreadable line(s) in the log — ${state.corrupt
+            .map((entry) => `line ${entry.line}`)
+            .join(", ")}.`, "The other messages are shown; repair or delete those lines to clear this.");
+    }
+    const other = state.messages.filter((m) => m.type !== "task" && m.type !== "done");
+    if (other.length) {
+        if (lines.length)
+            lines.push("");
+        lines.push(`Other messages: ${other.length}`);
+    }
+    return lines.join("\n");
+}

package/dist/src/core/{model-config.js → routing/model-config.js}

@@ -1,10 +1,10 @@
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { formatSchemaError, providerModelConfigurationSchema, } from "../shared/schemas.js";
-import { writeFileAtomically } from "./atomic-file.js";
-import { ensureDirectory, loadoutHome } from "./paths.js";
-import { runMutationTransaction } from "./transaction.js";
+import { formatSchemaError, providerModelConfigurationSchema, } from "../../shared/schemas.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { runMutationTransaction } from "../install/transaction.js";
 export const defaultModelConfigurationPath = () => join(loadoutHome(), "models.json");
 /**
  * Validate a portable, provider-neutral model configuration. This is not a

package/dist/src/core/routing/policy.js

@@ -0,0 +1,147 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { MODEL_CATALOG } from "./route.js";
+export const BUCKETS = ["hard", "normal", "cheap"];
+export const BUCKET_MEANING = {
+    hard: "architecture, security, migrations, tricky debugging, risky review",
+    normal: "most implementation, ordinary debugging, refactors",
+    cheap: "tests, docs, boilerplate, renames, mechanical edits",
+};
+export const policyPath = () => join(loadoutHome(), "routing.json");
+/**
+ * Defaults reflect a deliberate stance: on Claude the real choice is Opus or
+ * Sonnet, and the cheapest useful tier lives on Codex. Anyone who disagrees
+ * edits the file rather than arguing with a hardcoded table.
+ */
+export function defaultPolicy(installed = []) {
+    const hasCodex = installed.length === 0 || installed.includes("codex");
+    return {
+        version: 1,
+        rules: {
+            hard: "claude-opus-5",
+            normal: "claude-sonnet-5",
+            // Without Codex there is no fast tier to fall back to.
+            cheap: hasCodex ? "gpt-5.6-luna" : "claude-sonnet-5",
+        },
+    };
+}
+export function findModel(id) {
+    return MODEL_CATALOG.find((model) => model.id === id);
+}
+export function validatePolicy(value) {
+    const candidate = value;
+    if (!candidate || candidate.version !== 1)
+        throw new Error("Routing policy must have version 1");
+    const rules = candidate.rules;
+    if (!rules)
+        throw new Error("Routing policy has no rules");
+    for (const bucket of BUCKETS) {
+        const id = rules[bucket];
+        if (typeof id !== "string" || !id)
+            throw new Error(`Routing policy is missing a model for '${bucket}'`);
+        if (!findModel(id))
+            throw new Error(`Routing policy names unknown model '${id}' for '${bucket}'. Run 'loadout route --models' to list valid ids.`);
+    }
+    return { version: 1, rules: { ...rules } };
+}
+export async function readPolicy(installed = []) {
+    try {
+        const raw = await readFile(policyPath(), "utf8");
+        return { policy: validatePolicy(JSON.parse(raw)), source: "file" };
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            error.code === "ENOENT")
+            return { policy: defaultPolicy(installed), source: "default" };
+        throw error;
+    }
+}
+export async function writePolicy(policy) {
+    const path = policyPath();
+    await ensureDirectory(dirname(path));
+    await writeFileAtomically(path, `${JSON.stringify(policy, null, 2)}\n`);
+    return path;
+}
+export async function setRule(bucket, modelId, installed = []) {
+    if (!findModel(modelId))
+        throw new Error(`Unknown model '${modelId}'. Run 'loadout route --models' to list valid ids.`);
+    const { policy } = await readPolicy(installed);
+    const next = validatePolicy({
+        version: 1,
+        rules: { ...policy.rules, [bucket]: modelId },
+    });
+    await writePolicy(next);
+    return next;
+}
+/**
+ * A deliberately small classifier. It exists so the CLI can answer without an
+ * agent present, and it says plainly that it is guessing — the skill, which has
+ * the conversation and the code, is expected to do better.
+ */
+export function guessBucket(description) {
+    const text = description.toLowerCase();
+    const hard = /\b(architect|design|migrat|security|secure|auth|login|session|crypto|signature|signing|token|secret|credential|permission|payment|billing|checkout|stripe|webhook|invoice|concurren|race condition|deadlock|schema|rollout|rollback|encrypt|sanitiz|inject)\w*/;
+    const cheap = /\b(test|tests|spec|doc|docs|docstring|comment|readme|changelog|rename|typo|format|lint|boilerplate|scaffold)\w*/;
+    if (hard.test(text))
+        return "hard";
+    if (cheap.test(text))
+        return "cheap";
+    return "normal";
+}
+export function resolveRoute(policy, bucket, installed, guessed) {
+    const model = findModel(policy.rules[bucket]);
+    const answer = { bucket, model, guessed };
+    if (!installed.length)
+        return answer;
+    const runnable = model.nativeAgents.some((id) => installed.includes(id));
+    if (runnable)
+        return answer;
+    // Prefer a model of the same tier the user can actually run; otherwise the
+    // closest one by price, so the advice stays actionable.
+    const reachable = MODEL_CATALOG.filter((candidate) => candidate.nativeAgents.some((id) => installed.includes(id)));
+    const fallback = reachable.find((candidate) => candidate.tier === model.tier) ??
+        reachable.sort((a, b) => Math.abs(a.inputCostPer1M - model.inputCostPer1M) -
+            Math.abs(b.inputCostPer1M - model.inputCostPer1M))[0];
+    answer.unavailable = {
+        reason: `${model.name} needs ${model.nativeAgents.join(" or ")}, which is not installed`,
+        ...(fallback ? { fallback } : {}),
+    };
+    return answer;
+}
+function price(model) {
+    return `$${model.inputCostPer1M}/$${model.outputCostPer1M} per M`;
+}
+export function formatPolicy(policy, source) {
+    const lines = [
+        source === "file"
+            ? `Your routing policy — ${policyPath()}`
+            : "Default routing policy (not saved yet)",
+        "",
+    ];
+    for (const bucket of BUCKETS) {
+        const model = findModel(policy.rules[bucket]);
+        lines.push(`  ${bucket.padEnd(7)} ${model.name.padEnd(16)} ${price(model)}`);
+        lines.push(`  ${"".padEnd(7)} ${BUCKET_MEANING[bucket]}`);
+    }
+    lines.push("", "Change it:  loadout route --set normal=gpt-5.6-terra", source === "default"
+        ? "Save it:    loadout route --save"
+        : "Reset it:   loadout route --reset");
+    return lines.join("\n");
+}
+export function formatAnswer(answer, task) {
+    const lines = [];
+    if (task)
+        lines.push(`Task:   ${task}`, "");
+    lines.push(`Bucket: ${answer.bucket} — ${BUCKET_MEANING[answer.bucket]}`, `Use:    ${answer.model.name}  (${price(answer.model)})`);
+    if (answer.unavailable) {
+        lines.push("", `Note:   ${answer.unavailable.reason}.`);
+        if (answer.unavailable.fallback)
+            lines.push(`        Reachable alternative: ${answer.unavailable.fallback.name} (${price(answer.unavailable.fallback)}).`);
+    }
+    if (answer.guessed)
+        lines.push("", "This bucket was guessed from wording alone. If the work is riskier than it", "reads — payments, auth, migrations — treat it as hard and move up.");
+    return lines.join("\n");
+}