loadout-ai 0.7.0 → 0.9.0

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

@@ -2,6 +2,32 @@ 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";
 const MESSAGES_FILE = "messages.jsonl";
 const PROTOCOL_FILE = "PROTOCOL.md";
@@ -24,46 +50,30 @@ 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",
+        "# Handoff",
         "",
-        "- `messages.jsonl` — append-only message log (one JSON object per line)",
-        "- `PROTOCOL.md` — this file",
+        "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.",
         "",
-        "## Usage",
+        "## Using it",
         "",
         "```",
-        "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>",
+        "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",
         "```",
         "",
-        "## Making agents read this",
+        "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.",
         "",
-        "A message log only helps if the other agent checks it. Run:",
+        "## Files",
         "",
-        "```",
-        "loadout handoff pickup --yes",
-        "```",
+        "- `messages.jsonl` — the log, one JSON object per line",
+        "- `PROTOCOL.md` — this file",
         "",
-        "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.",
+        "Commit both if you want the log shared across machines.",
         "",
     ].join("\n");
     await writeFileAtomically(join(dir, PROTOCOL_FILE), protocol);
@@ -78,66 +88,106 @@ export async function initHandoff(projectRoot) {
 }
 export async function sendHandoff(projectRoot, to, description, options = {}) {
     if (!(await isHandoffInitialized(projectRoot))) {
-        throw new Error("Handoff not initialized. Run `loadout handoff init` first.");
+        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",
         to,
         description,
         ...(options.context ? { context: options.context } : {}),
+        ...(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",
-        context: `Resolves ${messageId}`,
+        resolves: messageId,
     });
 }
-export async function readMessages(projectRoot) {
+/**
+ * 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 [];
+        return { messages: [], corrupt: [] };
+    let content;
     try {
-        const content = await readFile(messagesPath(projectRoot), "utf8");
-        return content
-            .split("\n")
-            .filter(Boolean)
-            .map((line) => JSON.parse(line));
+        content = await readFile(messagesPath(projectRoot), "utf8");
     }
     catch {
-        return [];
+        return { messages: [], corrupt: [] };
     }
+    const messages = [];
+    const corrupt = [];
+    content.split("\n").forEach((raw, index) => {
+        if (!raw.trim())
+            return;
+        try {
+            const parsed = handoffMessageSchema.safeParse(JSON.parse(raw));
+            if (!parsed.success) {
+                throw new Error(handoffValidationReason(parsed.error));
+            }
+            messages.push(parsed.data);
+        }
+        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 = initialized ? await readMessages(projectRoot) : [];
-    const doneIds = new Set(messages
-        .filter((m) => m.type === "done")
+    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" && !doneIds.has(m.id));
-    const done = messages.filter((m) => m.type === "task" && doneIds.has(m.id));
+    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,
     };
 }
 // ---------------------------------------------------------------------------
@@ -150,7 +200,7 @@ export async function readInbox(projectRoot, 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
+ * 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.
  */
@@ -166,7 +216,7 @@ export function formatInbox(agent, messages) {
         lines.push(`  ${m.description}`);
         if (m.context)
             lines.push(`  context: ${m.context}`);
-        lines.push(`  when finished: loadout handoff done ${m.id}`);
+        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.");
@@ -184,10 +234,10 @@ export function pickupBlock(agent) {
         `At the start of a session, and whenever you finish a task, run:`,
         "",
         "```bash",
-        `loadout handoff inbox ${agent}`,
+        `loadout handoff ${agent}`,
         "```",
         "",
-        "If it lists pending tasks, work them in order and run the `loadout handoff done`",
+        "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,
@@ -198,6 +248,10 @@ 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)
@@ -225,12 +279,16 @@ export async function planPickup(projectRoot, agent) {
     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, content };
+    return { path, agent, exists, replacing, stale, content };
 }
 export async function applyPickup(plan) {
     await writeFileAtomically(plan.path, plan.content);
@@ -238,11 +296,13 @@ export async function applyPickup(plan) {
 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";
+        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.");
@@ -250,9 +310,9 @@ export function formatPickupPlan(plans) {
 }
 export function formatHandoffStatus(state) {
     if (!state.initialized)
-        return "Handoff not initialized. Run `loadout handoff init`.";
+        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 send <agent> <task>`.";
+        return "No handoff messages yet. Send one with `loadout handoff <agent> '<task>'`.";
     const lines = [];
     if (state.pending.length) {
         lines.push(`Pending (${state.pending.length}):`);
@@ -268,6 +328,13 @@ export function formatHandoffStatus(state) {
             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)

package/dist/src/core/discovery/candidate-intelligence-evidence.js

@@ -0,0 +1,108 @@
+import { join } from "node:path";
+export function installabilityFor(components) {
+    if (components.some((component) => ["skill", "rule", "command", "agent"].includes(component)))
+        return "portable-components";
+    if (components.some((component) => component === "mcp" || component === "plugin"))
+        return "explicit-runtime-setup";
+    return "unsupported-source-shape";
+}
+export function componentsFor(inspection) {
+    const result = [];
+    if (inspection.counts.skills)
+        result.push("skill");
+    if (inspection.counts.rules)
+        result.push("rule");
+    if (inspection.counts.commands)
+        result.push("command");
+    if (inspection.counts.agents)
+        result.push("agent");
+    if (inspection.plugins.some((plugin) => !plugin.warnings.some((warning) => warning.startsWith("invalid plugin manifest"))))
+        result.push("plugin");
+    if (inspection.mcpServers.length)
+        result.push("mcp");
+    return result;
+}
+export function evidencePathsFor(inspection) {
+    return [
+        ...inspection.skills.map((item) => join(item.path, "SKILL.md")),
+        ...inspection.resources.map((item) => item.path),
+        ...inspection.plugins
+            .filter((item) => !item.warnings.some((warning) => warning.startsWith("invalid plugin manifest")))
+            .map((item) => item.path),
+        ...inspection.mcpServers.map((item) => item.path),
+    ]
+        .map((path) => path.split(/[\\/]/).join("/"))
+        .filter((path) => path !== "." && !path.startsWith("../"))
+        .filter((path, index, paths) => paths.indexOf(path) === index)
+        .sort();
+}
+const STOP_WORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "that",
+    "this",
+    "your",
+    "into",
+    "agent",
+    "agents",
+    "skill",
+    "skills",
+    "mcp",
+    "server",
+    "servers",
+    "workflow",
+    "workflows",
+    "code",
+    "coding",
+    "developer",
+    "development",
+    "platform",
+    "context",
+    "open",
+    "source",
+    "using",
+    "across",
+    "tool",
+    "tools",
+    "github",
+]);
+function tokens(...values) {
+    return new Set(values
+        .join(" ")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length >= 3 && !STOP_WORDS.has(word)));
+}
+export function overlapFor(discovery, inspection, catalog) {
+    const candidateTokens = tokens(discovery.repository, discovery.description, discovery.topics.join(" "), ...inspection.skills.flatMap((item) => [item.name, item.description]), ...inspection.resources.map((item) => item.name), ...inspection.plugins.flatMap((item) => [item.name, item.description]), ...inspection.mcpServers.map((item) => item.name));
+    const candidateComponents = new Set(componentsFor(inspection));
+    return catalog
+        .map((pkg) => {
+        const packageTokens = tokens(pkg.id, pkg.displayName, pkg.description, pkg.category, pkg.topics?.join(" "));
+        const common = [...candidateTokens]
+            .filter((word) => packageTokens.has(word))
+            .sort();
+        // Containment is more useful than union similarity here: a large skill
+        // collection can overlap a focused package even when most collection
+        // tokens describe unrelated capabilities.
+        const smallerVocabulary = Math.min(candidateTokens.size, packageTokens.size);
+        const score = smallerVocabulary ? common.length / smallerVocabulary : 0;
+        const componentMatch = pkg.components?.some((component) => candidateComponents.has(component)) ?? false;
+        return {
+            packageId: pkg.id,
+            repository: pkg.repository,
+            score: Math.round(score * 1000) / 1000,
+            relationship: componentMatch && common.length >= 2 && score >= 0.2
+                ? "possible-overlap"
+                : "same-tooling-area",
+            evidence: common.slice(0, 8).map((word) => `shared term: ${word}`),
+        };
+    })
+        .filter((item) => item.evidence.length >= 1 && item.score >= 0.1)
+        .sort((left, right) => right.score - left.score ||
+        left.packageId.localeCompare(right.packageId))
+        .slice(0, 5);
+}

package/dist/src/core/discovery/candidate-intelligence-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/discovery/candidate-intelligence-validation.js

@@ -0,0 +1,108 @@
+import { componentsFor, evidencePathsFor, installabilityFor, } from "./candidate-intelligence-evidence.js";
+export function isTextArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+export function finiteNonnegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+export function validDate(value) {
+    return typeof value === "string" && !Number.isNaN(Date.parse(value));
+}
+export function validPersistedEvaluation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const evaluation = value;
+    const categories = evaluation.categories;
+    return (evaluation.evaluatorVersion === 1 &&
+        typeof evaluation.uncertainty === "string" &&
+        Array.isArray(categories) &&
+        categories.length === 2 &&
+        new Set(categories.map((item) => item.category)).size === 2 &&
+        categories.every((item) => (item.category === "skills" || item.category === "mcp") &&
+            ["ready", "needs-review", "blocked", "not-applicable"].includes(item.status) &&
+            isTextArray(item.findings)));
+}
+function safeEvidencePath(value) {
+    return (typeof value === "string" &&
+        Boolean(value) &&
+        !value.startsWith("/") &&
+        !value.split(/[\\/]/).includes(".."));
+}
+export function validPersistedInspection(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const inspection = value;
+    const validCount = (count) => typeof count === "number" && Number.isSafeInteger(count) && count >= 0;
+    const validNamedPath = (item, type) => Boolean(item &&
+        typeof item === "object" &&
+        !Array.isArray(item) &&
+        item.type === type &&
+        typeof item.name === "string" &&
+        safeEvidencePath(item.path));
+    if (!Array.isArray(inspection.skills) ||
+        !inspection.skills.every((item) => validNamedPath(item, "skill") &&
+            (item.description === undefined ||
+                typeof item.description === "string")) ||
+        !Array.isArray(inspection.resources) ||
+        !inspection.resources.every((item) => ["rule", "command", "agent"].includes(item.type) &&
+            validNamedPath(item, item.type)) ||
+        !Array.isArray(inspection.plugins) ||
+        !inspection.plugins.every((item) => validNamedPath(item, "plugin") &&
+            (item.description === undefined ||
+                typeof item.description === "string") &&
+            (item.version === undefined || typeof item.version === "string") &&
+            (item.author === undefined || typeof item.author === "string") &&
+            Array.isArray(item.components) &&
+            item.components.every((component) => [
+                "skill",
+                "rule",
+                "command",
+                "agent",
+                "mcp",
+                "plugin",
+                "root",
+            ].includes(component)) &&
+            isTextArray(item.hookEvents) &&
+            isTextArray(item.mcpServers) &&
+            isTextArray(item.warnings)) ||
+        !Array.isArray(inspection.mcpServers) ||
+        !inspection.mcpServers.every((item) => validNamedPath(item, "mcp") &&
+            ["command", "url", "unknown"].includes(item.transport) &&
+            (item.command === undefined || typeof item.command === "string") &&
+            (item.url === undefined || typeof item.url === "string") &&
+            validCount(item.argumentCount) &&
+            validCount(item.environmentVariableCount) &&
+            isTextArray(item.warnings)) ||
+        !inspection.counts ||
+        !validCount(inspection.counts.skills) ||
+        !validCount(inspection.counts.rules) ||
+        !validCount(inspection.counts.commands) ||
+        !validCount(inspection.counts.agents) ||
+        !validCount(inspection.counts.plugins) ||
+        !validCount(inspection.counts.mcpServers) ||
+        !validCount(inspection.counts.manifests) ||
+        !isTextArray(inspection.warnings))
+        return false;
+    return (inspection.counts.skills === inspection.skills.length &&
+        inspection.counts.rules ===
+            inspection.resources.filter((item) => item.type === "rule").length &&
+        inspection.counts.commands ===
+            inspection.resources.filter((item) => item.type === "command").length &&
+        inspection.counts.agents ===
+            inspection.resources.filter((item) => item.type === "agent").length &&
+        inspection.counts.plugins === inspection.plugins.length &&
+        inspection.counts.mcpServers === inspection.mcpServers.length);
+}
+export function assertDossierEvidence(dossier) {
+    if (!validPersistedInspection(dossier.inspection))
+        throw new Error("Candidate dossier inspection evidence is invalid");
+    const inspection = { root: ".", ...dossier.inspection };
+    const components = componentsFor(inspection);
+    const evidencePaths = evidencePathsFor(inspection);
+    if (JSON.stringify(dossier.components) !== JSON.stringify(components))
+        throw new Error("Candidate dossier components do not match inspection evidence");
+    if (dossier.installability !== installabilityFor(components))
+        throw new Error("Candidate dossier installability does not match inspection evidence");
+    if (JSON.stringify(dossier.evidencePaths) !== JSON.stringify(evidencePaths))
+        throw new Error("Candidate dossier evidencePaths do not match inspection evidence");
+}