loadout-ai 0.5.9 → 0.7.0

package/dist/src/core/{freshness-alerts.js → reporting/freshness-alerts.js}

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { loadEffectiveCatalog } from "./catalog.js";
-import { ensureDirectory, loadoutHome } from "./paths.js";
-import { readInstallState } from "./state.js";
-import { buildUpdatePlan } from "./update.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { loadEffectiveCatalog } from "../catalog/catalog.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
+import { buildUpdatePlan } from "../install/update.js";
 const decisionsPath = () => join(loadoutHome(), "alert-decisions.json");
 function alertId(packageId, kind, evidence) {
     return `${packageId}-${kind}-${createHash("sha256")

package/dist/src/core/{health.js → reporting/health.js}

@@ -1,12 +1,12 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { managedFileReadPath } from "./active-set.js";
-import { detectAgents } from "./paths.js";
-import { readInstallState } from "./state.js";
-import { buildUpdatePlan } from "./update.js";
-import { codexMcpServerFingerprint } from "./codex-mcp.js";
-import { listInstalledRuntimeToolSkillTargets, listInstalledRuntimeTools, } from "./runtime-tools.js";
+import { managedFileReadPath } from "../workspace/active-set.js";
+import { detectAgents } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
+import { buildUpdatePlan } from "../install/update.js";
+import { codexMcpServerFingerprint } from "../agents/codex-mcp.js";
+import { listInstalledRuntimeToolSkillTargets, listInstalledRuntimeTools, } from "../agents/runtime-tools.js";
 async function drift(record, activations) {
     const changed = [];
     for (const file of record.files) {

package/dist/src/core/{loadout-card.js → reporting/loadout-card.js}

@@ -1,4 +1,4 @@
-import { buildLocalAgentHealthScores } from "./health-score-evidence.js";
+import { buildLocalAgentHealthScores } from "../agents/health-score-evidence.js";
 import { buildHealthReport, gradeHealth } from "./health.js";
 import { buildPrivacySafeReport, } from "./share-report.js";
 export async function buildLoadoutCard(options = {}) {

package/dist/src/core/{readme-claims.js → reporting/readme-claims.js}

@@ -1,4 +1,4 @@
-import { formatSchemaError, readmeClaimManifestSchema, } from "../shared/schemas.js";
+import { formatSchemaError, readmeClaimManifestSchema, } from "../../shared/schemas.js";
 export { readmeClaimManifestSchema };
 /** Parse the versioned index of evidence for material README statements. */
 export function parseReadmeClaimManifest(value) {

package/dist/src/core/{readme-facts.js → reporting/readme-facts.js}

@@ -1,5 +1,5 @@
-import { supportedAdapterNames } from "./adapters.js";
-import { buildCatalogCoverage } from "./catalog-coverage.js";
+import { supportedAdapterNames, } from "../agents/adapters.js";
+import { buildCatalogCoverage } from "../catalog/catalog-coverage.js";
 function profileFacts(allowlist) {
     return {
         sources: Object.keys(allowlist).length,

package/dist/src/core/{share-report.js → reporting/share-report.js}

@@ -1,7 +1,7 @@
 import { dirname } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { ensureDirectory } from "./paths.js";
-import { readInstallState } from "./state.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
 export function parsePrivacySafeLoadoutReport(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("Privacy-safe Loadout report must be an object");

package/dist/src/core/{upgrade.js → reporting/upgrade.js}

@@ -1,11 +1,11 @@
-import { buildAdapterCapabilityGaps, } from "./adapters.js";
-import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, } from "./catalog-install.js";
-import { DEFAULT_ACTIVE_SKILL_LIMIT } from "./active-limit.js";
-import { loadEffectiveCatalog } from "./catalog.js";
+import { buildAdapterCapabilityGaps, } from "../agents/adapters.js";
+import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, } from "../install/catalog-install.js";
+import { DEFAULT_ACTIVE_SKILL_LIMIT } from "../workspace/active-limit.js";
+import { loadEffectiveCatalog, } from "../catalog/catalog.js";
 import { buildHealthReport, formatHealthReport } from "./health.js";
-import { buildLocalAgentHealthScores } from "./health-score-evidence.js";
-import { formatRecommendations, personalizeRecommendations, recommendPackages, scanProject, } from "./recommend.js";
-import { readLocalOutcomes } from "./outcomes.js";
+import { buildLocalAgentHealthScores } from "../agents/health-score-evidence.js";
+import { formatRecommendations, personalizeRecommendations, recommendPackages, scanProject, } from "../workspace/recommend.js";
+import { readLocalOutcomes, } from "../workspace/outcomes.js";
 /**
  * Builds the complete first-run preview without changing agent or Loadout state.
  * Network access is limited to the same immutable catalog preparation performed by

package/dist/src/core/routing/first-party-skills.js

@@ -0,0 +1,118 @@
+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";
+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-curator",
+        displayName: "Loadout Curator",
+        summary: "Lets an agent decide which skills and MCP servers should be active for the current repository",
+    },
+];
+/**
+ * Locate the bundled `skills/` directory. Resolution walks upward so it works
+ * both from `src/` under tsx and from `dist/src/` in the published package.
+ */
+export async function bundledSkillsRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 5; depth += 1) {
+        const candidate = join(dir, "skills");
+        try {
+            if ((await stat(candidate)).isDirectory())
+                return candidate;
+        }
+        catch {
+            // Keep walking toward the package root.
+        }
+        dir = dirname(dir);
+    }
+    throw new Error("Bundled skills directory not found; this build may be incomplete.");
+}
+export function findFirstPartySkill(id) {
+    const skill = FIRST_PARTY_SKILLS.find((item) => item.id === id);
+    if (!skill)
+        throw new Error(`Unknown Loadout skill '${id}'. Available: ${FIRST_PARTY_SKILLS.map((s) => s.id).join(", ")}`);
+    return skill;
+}
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build a preview of where one first-party skill would be installed. Nothing is
+ * written; the caller decides whether to apply.
+ */
+export async function planFirstPartySkill(id, options = {}) {
+    const skill = findFirstPartySkill(id);
+    const source = join(await bundledSkillsRoot(), skill.id);
+    if (!(await directoryExists(source)))
+        throw new Error(`Bundled skill '${skill.id}' is missing from this build.`);
+    const detected = options.detected ?? (await detectAgents());
+    const installed = detected.filter((agent) => agent.installed);
+    const requested = options.agents?.length
+        ? installed.filter((agent) => options.agents.includes(agent.id))
+        : installed;
+    const targets = [];
+    for (const agent of requested) {
+        const destination = join(agent.skillsDirectory, skill.id);
+        targets.push({
+            agent: agent.id,
+            displayName: agent.displayName,
+            destination,
+            replacing: await directoryExists(destination),
+        });
+    }
+    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 });
+    }
+}
+export async function removeFirstPartySkill(plan) {
+    for (const target of plan.targets)
+        if (target.replacing)
+            await rm(target.destination, { recursive: true });
+}
+export function formatFirstPartySkillList(installedIds = new Set()) {
+    const lines = ["Skills that ship with Loadout:", ""];
+    for (const skill of FIRST_PARTY_SKILLS) {
+        const marker = installedIds.has(skill.id) ? "✓" : "○";
+        lines.push(`  ${marker} ${skill.id} — ${skill.summary}`);
+    }
+    lines.push("", "Install with: loadout skills install <id> --yes", "These teach your agents to use Loadout from inside a conversation.");
+    return lines.join("\n");
+}
+export function formatFirstPartySkillPlan(plan) {
+    if (!plan.targets.length)
+        return `No installed agents detected, so '${plan.skill.id}' has nowhere to go. Install an agent first.`;
+    const lines = [`${plan.skill.displayName} (${plan.skill.id})`, ""];
+    for (const target of plan.targets)
+        lines.push(`  ${target.replacing ? "replace" : "install"} → ${target.destination}  [${target.displayName}]`);
+    return lines.join("\n");
+}
+/** Which first-party skills are already present for at least one agent. */
+export async function installedFirstPartySkills(detected) {
+    const agents = (detected ?? (await detectAgents())).filter((agent) => agent.installed);
+    const found = new Set();
+    for (const skill of FIRST_PARTY_SKILLS)
+        for (const agent of agents)
+            if (await directoryExists(join(agent.skillsDirectory, skill.id))) {
+                found.add(skill.id);
+                break;
+            }
+    return found;
+}

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

@@ -0,0 +1,278 @@
+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";
+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 Protocol",
+        "",
+        "This directory enables asynchronous task handoff between AI coding agents.",
+        "Generated by `loadout handoff init`. Compatible with the JSONL handoff convention.",
+        "",
+        "## Message types",
+        "",
+        "- **task**: assign work to another agent",
+        "- **handoff**: transfer in-progress work with context",
+        "- **question**: ask another agent for input",
+        "- **done**: signal completion",
+        "- **status**: progress update",
+        "- **error**: report a failure",
+        "- **cancel**: withdraw a task",
+        "",
+        "## Files",
+        "",
+        "- `messages.jsonl` — append-only message log (one JSON object per line)",
+        "- `PROTOCOL.md` — this file",
+        "",
+        "## Usage",
+        "",
+        "```",
+        "loadout handoff send codex 'write unit tests for auth module'",
+        "loadout handoff send claude-code 'review the API changes' --context 'see PR #42'",
+        "loadout handoff status",
+        "loadout handoff done <message-id>",
+        "```",
+        "",
+        "## Making agents read this",
+        "",
+        "A message log only helps if the other agent checks it. Run:",
+        "",
+        "```",
+        "loadout handoff pickup --yes",
+        "```",
+        "",
+        "That adds a managed block to CLAUDE.md and AGENTS.md telling each agent to",
+        "run `loadout handoff inbox <agent>` at session start and act on what it finds.",
+        "Only the block between the loadout:handoff markers is managed.",
+        "",
+    ].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 not initialized. Run `loadout handoff init` first.");
+    }
+    const message = {
+        id: randomUUID().slice(0, 8),
+        type: options.type ?? "task",
+        from: options.from ?? "user",
+        to,
+        description,
+        ...(options.context ? { context: options.context } : {}),
+        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",
+        context: `Resolves ${messageId}`,
+    });
+}
+export async function readMessages(projectRoot) {
+    if (!(await isHandoffInitialized(projectRoot)))
+        return [];
+    try {
+        const content = await readFile(messagesPath(projectRoot), "utf8");
+        return content
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+export async function getHandoffState(projectRoot) {
+    const initialized = await isHandoffInitialized(projectRoot);
+    const messages = initialized ? await readMessages(projectRoot) : [];
+    const doneIds = new Set(messages
+        .filter((m) => m.type === "done")
+        .flatMap((m) => {
+        const match = m.context?.match(/Resolves (\w+)/);
+        return match ? [match[1]] : [];
+    }));
+    const pending = messages.filter((m) => m.type === "task" && !doneIds.has(m.id));
+    const done = messages.filter((m) => m.type === "task" && doneIds.has(m.id));
+    return {
+        initialized,
+        directory: handoffDir(projectRoot),
+        messages,
+        pending,
+        done,
+    };
+}
+// ---------------------------------------------------------------------------
+// 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 inbox` 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 inbox ${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",
+};
+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;
+    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, 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.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 "Handoff not initialized. Run `loadout handoff init`.";
+    if (state.messages.length === 0)
+        return "No handoff messages yet. Send one with `loadout handoff send <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}`);
+        }
+    }
+    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