loadout-ai 0.8.0 → 0.9.1

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

@@ -0,0 +1,161 @@
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Event type enum — superset of handoff message types
+// ---------------------------------------------------------------------------
+export const COORDINATION_EVENT_TYPES = [
+    // Original handoff types
+    "task",
+    "handoff",
+    "question",
+    "done",
+    "status",
+    "error",
+    "cancel",
+    // Live collaboration types (Phase 1)
+    "contract",
+    "ownership",
+    "decision",
+    "update",
+    "ack",
+    "discussion",
+];
+// ---------------------------------------------------------------------------
+// Typed payloads for collaboration events
+// ---------------------------------------------------------------------------
+export const contractPayloadSchema = z.object({
+    /** A stable name for this contract, e.g. "auth-api" or "db-schema". */
+    name: z.string().trim().min(1).max(200),
+    /** Monotonically increasing version for this contract name. */
+    revision: z.number().int().positive(),
+    /** The contract body — OpenAPI fragment, TypeScript types, SQL, etc. */
+    body: z.string().max(100_000),
+    /** MIME-ish hint: "typescript", "openapi-yaml", "sql", "json-schema". */
+    format: z.string().trim().min(1).max(50).optional(),
+});
+export const ownershipPayloadSchema = z.object({
+    /** File or directory paths this agent claims. Relative to project root. */
+    paths: z.array(z.string().trim().min(1).max(1_024)).min(1).max(256),
+    /** "exclusive" blocks other agents; "shared" allows concurrent reads. */
+    mode: z.enum(["exclusive", "shared", "release"]),
+    /** Optional reason for the claim. */
+    reason: z.string().max(500).optional(),
+});
+export const decisionPayloadSchema = z.object({
+    /** Short title: "Use Zod for validation", "REST over GraphQL". */
+    title: z.string().trim().min(1).max(200),
+    /** The rationale. */
+    rationale: z.string().max(10_000),
+    /** ID of the decision this supersedes, if any. */
+    supersedes: z.string().trim().min(1).max(128).optional(),
+    /** Discussion thread that produced this decision, when applicable. */
+    discussionId: z.string().trim().min(1).max(128).optional(),
+});
+export const updatePayloadSchema = z.object({
+    /** Files touched since last update. */
+    files: z.array(z.string().max(1_024)).max(256).optional(),
+    /** Commands run and their outcomes. */
+    commands: z
+        .array(z.object({
+        command: z.string().max(500),
+        exitCode: z.number().int().optional(),
+        summary: z.string().max(1000).optional(),
+    }))
+        .max(20)
+        .optional(),
+    /** Free-form progress note. */
+    note: z.string().max(5000).optional(),
+    /** Blockers preventing further progress. */
+    blockers: z.array(z.string().max(500)).max(10).optional(),
+    /** What this agent plans to do next. */
+    next: z.string().max(1000).optional(),
+});
+export const ackPayloadSchema = z.object({
+    /** Sequence number of the event being acknowledged. */
+    eventSeq: z.number().int().nonnegative(),
+    /** Optional note about what the agent did with this event. */
+    note: z.string().max(1000).optional(),
+});
+export const discussionPayloadSchema = z
+    .object({
+    /** Stable ID shared by every event in one bounded design discussion. */
+    threadId: z.string().trim().min(1).max(128),
+    /** The semantic place of this statement in the discussion. */
+    kind: z.enum([
+        "started",
+        "proposal",
+        "critique",
+        "revision",
+        "summary",
+        "closed",
+    ]),
+    /** Zero for lifecycle events, otherwise the user-visible round number. */
+    round: z.number().int().min(0).max(8),
+    /** The participant function represented by this event. */
+    role: z.enum(["system", "proposer", "reviewer"]),
+    /** Explicit public output. Hidden provider reasoning is never requested. */
+    content: z.string().trim().min(1).max(16_384),
+    /** Present on the opening event so state can be reconstructed from JSONL. */
+    participants: z
+        .tuple([
+        z.string().trim().min(1).max(128),
+        z.string().trim().min(1).max(128),
+    ])
+        .optional(),
+    /** Event ID this statement directly answers. */
+    replyTo: z.string().trim().min(1).max(128).optional(),
+    /** Alternatives preserved by the final lifecycle event. */
+    alternatives: z
+        .array(z.string().trim().min(1).max(2_000))
+        .max(10)
+        .optional(),
+    /** Disagreements or evidence gaps the final decision does not conceal. */
+    unresolved: z.array(z.string().trim().min(1).max(2_000)).max(10).optional(),
+    /** Set on the terminal event so failures cannot be mistaken for decisions. */
+    outcome: z.enum(["decided", "failed"]).optional(),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Coordination event — extends HandoffMessage with seq + typed payload
+// ---------------------------------------------------------------------------
+export const coordinationEventSchema = z.object({
+    id: z.string().trim().min(1).max(128),
+    seq: z.number().int().nonnegative(),
+    type: z.enum(COORDINATION_EVENT_TYPES),
+    from: z.string().trim().min(1).max(128),
+    to: z.string().trim().min(1).max(128),
+    description: z.string().trim().min(1).max(8_192),
+    context: z.string().max(65_536).optional(),
+    timestamp: z.iso.datetime({ offset: true }),
+    resolves: z.string().trim().min(1).max(128).optional(),
+    /** Typed payload — shape depends on `type`. */
+    payload: z.record(z.string(), z.unknown()).optional(),
+});
+/** Validate the typed payload matches the event type. */
+export function validatePayload(type, payload) {
+    const schemas = {
+        contract: contractPayloadSchema,
+        ownership: ownershipPayloadSchema,
+        decision: decisionPayloadSchema,
+        update: updatePayloadSchema,
+        ack: ackPayloadSchema,
+        discussion: discussionPayloadSchema,
+    };
+    const schema = schemas[type];
+    if (!schema) {
+        // Original handoff types don't require typed payloads
+        return { success: true, data: payload };
+    }
+    if (!payload) {
+        return { success: false, error: `Event type '${type}' requires a payload` };
+    }
+    const result = schema.safeParse(payload);
+    if (!result.success) {
+        return {
+            success: false,
+            error: result.error.issues
+                .map((i) => `${i.path.join(".") || "payload"}: ${i.message}`)
+                .join("; "),
+        };
+    }
+    return { success: true, data: result.data };
+}

package/dist/src/core/coordination/git-ownership.js

@@ -0,0 +1,217 @@
+/**
+ * Git-aware auto-ownership — infer directory ownership from git history.
+ *
+ * Scans recent commits to find which agent (author) has been working
+ * in which directories, then suggests or applies ownership claims.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { claimOwnership, getOwnership, } from "./coordinator.js";
+const execFileAsync = promisify(execFile);
+function parseAgentAuthorMappings(values) {
+    const mappings = values.map((value) => {
+        const separator = value.indexOf("=");
+        const agent = (separator >= 0 ? value.slice(0, separator) : value).trim();
+        const author = (separator >= 0 ? value.slice(separator + 1) : value).trim();
+        if (!agent || !author)
+            throw new Error(`Invalid agent/author mapping '${value}'; use agent=Git Author`);
+        return { agent, author };
+    });
+    if (new Set(mappings.map((mapping) => mapping.agent)).size !== mappings.length)
+        throw new Error("Each agent may have only one Git author mapping");
+    return mappings;
+}
+// ── Git scanning ───────────────────────────────────────────────────────
+const SKIP_DIRS = new Set([
+    ".git",
+    ".handoff",
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    "coverage",
+]);
+/**
+ * Scan git log for directory-level author stats.
+ *
+ * Uses `git log --name-only` to get file paths per commit, groups by
+ * top-level directory, and counts commits per author per directory.
+ */
+export async function scanGitHistory(projectRoot, options = {}) {
+    const maxCommits = options.maxCommits ?? 200;
+    const depth = options.depth ?? 1;
+    if (!Number.isInteger(maxCommits) || maxCommits < 1 || maxCommits > 10_000)
+        throw new Error("Max commits must be an integer from 1 to 10000");
+    if (!Number.isInteger(depth) || depth < 1 || depth > 20)
+        throw new Error("Directory depth must be an integer from 1 to 20");
+    let stdout;
+    try {
+        const result = await execFileAsync("git", [
+            "log",
+            `--max-count=${maxCommits}`,
+            "--name-only",
+            "--format=COMMIT:%aN",
+            "--no-merges",
+        ], { cwd: projectRoot, maxBuffer: 5 * 1024 * 1024 });
+        stdout = result.stdout;
+    }
+    catch {
+        return []; // Not a git repo or no commits
+    }
+    // Parse: each commit starts with "COMMIT:<author>", followed by file paths
+    const authorDirCommits = new Map();
+    const blocks = stdout.split("COMMIT:").filter(Boolean);
+    for (const block of blocks) {
+        const lines = block.split("\n").filter(Boolean);
+        if (lines.length < 1)
+            continue;
+        const author = lines[0].trim();
+        if (!author)
+            continue;
+        if (options.authors && !options.authors.includes(author))
+            continue;
+        const dirs = new Set();
+        for (let i = 1; i < lines.length; i++) {
+            const filePath = lines[i].trim();
+            if (!filePath)
+                continue;
+            const dir = extractDirectory(filePath, depth);
+            if (dir && !SKIP_DIRS.has(dir.split("/")[0])) {
+                dirs.add(dir);
+            }
+        }
+        const stats = authorDirCommits.get(author) ?? {
+            dirs: new Map(),
+            total: 0,
+        };
+        stats.total++;
+        for (const dir of dirs) {
+            stats.dirs.set(dir, (stats.dirs.get(dir) ?? 0) + 1);
+        }
+        authorDirCommits.set(author, stats);
+    }
+    return [...authorDirCommits.entries()].map(([author, stats]) => ({
+        author,
+        directories: stats.dirs,
+        totalCommits: stats.total,
+    }));
+}
+function extractDirectory(filePath, depth) {
+    const parts = filePath.split("/");
+    if (parts.length <= depth)
+        return null; // File at root level
+    return parts.slice(0, depth).join("/");
+}
+// ── Suggestion generation ──────────────────────────────────────────────
+export async function suggestOwnership(projectRoot, agents, options = {}) {
+    const threshold = options.threshold ?? 60;
+    if (!Number.isInteger(threshold) || threshold < 1 || threshold > 100)
+        throw new Error("Ownership threshold must be an integer from 1 to 100");
+    const mappings = parseAgentAuthorMappings(agents);
+    const agentForAuthor = new Map(mappings.map((mapping) => [mapping.author, mapping.agent]));
+    const stats = await scanGitHistory(projectRoot, {
+        maxCommits: options.maxCommits,
+        depth: options.depth,
+    });
+    const existingOwnership = await getOwnership(projectRoot);
+    // Collect all directories across all authors
+    const allDirs = new Set();
+    for (const s of stats) {
+        for (const dir of s.directories.keys()) {
+            allDirs.add(dir);
+        }
+    }
+    const suggestions = [];
+    for (const dir of allDirs) {
+        // Find commit counts per author for this directory
+        const authorCounts = [];
+        let totalDirCommits = 0;
+        for (const s of stats) {
+            const count = s.directories.get(dir) ?? 0;
+            if (count > 0) {
+                authorCounts.push({ author: s.author, count });
+                totalDirCommits += count;
+            }
+        }
+        if (totalDirCommits === 0)
+            continue;
+        // Find dominant author
+        authorCounts.sort((a, b) => b.count - a.count);
+        const dominant = authorCounts[0];
+        const percentage = Math.round((dominant.count / totalDirCommits) * 100);
+        const suggestedOwner = agentForAuthor.get(dominant.author);
+        if (percentage < threshold || !suggestedOwner)
+            continue;
+        const alreadyClaimed = [...existingOwnership.values()].some((claim) => claim.agent === suggestedOwner &&
+            claim.paths.some((p) => p === dir || dir.startsWith(p + "/")));
+        suggestions.push({
+            directory: dir,
+            suggestedOwner,
+            commits: dominant.count,
+            percentage,
+            alreadyClaimed,
+        });
+    }
+    // Sort by confidence (percentage) descending
+    suggestions.sort((a, b) => b.percentage - a.percentage);
+    return { suggestions, authorStats: stats, ownershipApplied: false };
+}
+// ── Apply suggestions ──────────────────────────────────────────────────
+export async function applyGitOwnership(projectRoot, agents, options = {}) {
+    const result = await suggestOwnership(projectRoot, agents, options);
+    if (options.dryRun)
+        return result;
+    const unclaimed = result.suggestions.filter((s) => !s.alreadyClaimed);
+    if (unclaimed.length === 0)
+        return result;
+    // Group by agent
+    const agentPaths = new Map();
+    for (const s of unclaimed) {
+        const paths = agentPaths.get(s.suggestedOwner) ?? [];
+        paths.push(s.directory);
+        agentPaths.set(s.suggestedOwner, paths);
+    }
+    for (const [agent, paths] of agentPaths) {
+        const claim = {
+            agent,
+            paths,
+            mode: "exclusive",
+            reason: "Auto-assigned from git history",
+        };
+        await claimOwnership(projectRoot, claim);
+    }
+    result.ownershipApplied = true;
+    return result;
+}
+// ── Terminal formatting ────────────────────────────────────────────────
+export function formatGitOwnership(result, dryRun) {
+    const lines = [];
+    if (result.suggestions.length === 0) {
+        lines.push("No ownership suggestions from git history.");
+        if (result.authorStats.length === 0) {
+            lines.push("\x1b[90mNo matching commits found. Are the agent names the same as git author names?\x1b[0m");
+        }
+        return lines.join("\n");
+    }
+    lines.push(`\x1b[1mGit-based ownership suggestions\x1b[0m (${result.suggestions.length})`);
+    lines.push("");
+    for (const s of result.suggestions) {
+        const status = s.alreadyClaimed
+            ? "\x1b[32m✓ claimed\x1b[0m"
+            : "\x1b[33m⚠ unclaimed\x1b[0m";
+        lines.push(`  ${s.directory}/  →  \x1b[36m${s.suggestedOwner}\x1b[0m  ${s.percentage}% (${s.commits} commits)  ${status}`);
+    }
+    lines.push("");
+    const unclaimed = result.suggestions.filter((s) => !s.alreadyClaimed);
+    if (unclaimed.length === 0) {
+        lines.push("\x1b[32mAll suggested directories already claimed.\x1b[0m");
+    }
+    else if (dryRun) {
+        lines.push(`\x1b[90m${unclaimed.length} unclaimed. Add --yes to apply.\x1b[0m`);
+    }
+    else if (result.ownershipApplied) {
+        lines.push(`\x1b[32m✓ Applied ${unclaimed.length} ownership claim(s).\x1b[0m`);
+    }
+    return lines.join("\n");
+}

package/dist/src/core/coordination/http-api.js

@@ -0,0 +1,118 @@
+import { isLoopbackHostname } from "./auth.js";
+export const MAX_BODY_BYTES = 1024 * 1024;
+export class HttpError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "HttpError";
+    }
+}
+function parseAuthority(value) {
+    try {
+        return new URL(`http://${value}`);
+    }
+    catch {
+        return null;
+    }
+}
+export function validateRequestSource(req) {
+    const host = req.headers.host;
+    const hostUrl = host ? parseAuthority(host) : null;
+    if (!hostUrl || !isLoopbackHostname(hostUrl.hostname)) {
+        throw new HttpError(403, "forbidden_host", "Host is not loopback");
+    }
+    const origin = req.headers.origin;
+    if (!origin)
+        return;
+    let originUrl;
+    try {
+        originUrl = new URL(origin);
+    }
+    catch {
+        throw new HttpError(403, "forbidden_origin", "Origin is not same-origin");
+    }
+    if (!isLoopbackHostname(originUrl.hostname) ||
+        originUrl.host.toLowerCase() !== hostUrl.host.toLowerCase() ||
+        originUrl.protocol !== "http:" ||
+        originUrl.origin !== origin) {
+        throw new HttpError(403, "forbidden_origin", "Origin is not same-origin");
+    }
+}
+function matchingOrigin(req) {
+    const host = req.headers.host;
+    const origin = req.headers.origin;
+    const hostUrl = host ? parseAuthority(host) : null;
+    if (!hostUrl || !origin)
+        return undefined;
+    try {
+        const originUrl = new URL(origin);
+        return originUrl.protocol === "http:" &&
+            isLoopbackHostname(originUrl.hostname) &&
+            originUrl.host.toLowerCase() === hostUrl.host.toLowerCase() &&
+            originUrl.origin === origin
+            ? origin
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function setResponseHeaders(req, res) {
+    res.setHeader("Cache-Control", "no-store");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    const origin = matchingOrigin(req);
+    if (origin) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
+    }
+}
+export function sendJson(req, res, data, status = 200) {
+    setResponseHeaders(req, res);
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(data));
+}
+export function sendError(req, res, code, message, status) {
+    sendJson(req, res, { error: { code, message } }, status);
+}
+export function setEventStreamHeaders(req, res) {
+    setResponseHeaders(req, res);
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-store",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no",
+    });
+}
+export async function readJsonBody(req) {
+    const contentLength = Number(req.headers["content-length"]);
+    if (Number.isFinite(contentLength) && contentLength > MAX_BODY_BYTES) {
+        throw new HttpError(413, "payload_too_large", "Request body too large");
+    }
+    const chunks = [];
+    let size = 0;
+    let tooLarge = false;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > MAX_BODY_BYTES) {
+            tooLarge = true;
+        }
+        else if (!tooLarge) {
+            chunks.push(buffer);
+        }
+    }
+    if (tooLarge) {
+        throw new HttpError(413, "payload_too_large", "Request body too large");
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+    }
+    catch {
+        throw new HttpError(400, "invalid_json", "Request body must be valid JSON");
+    }
+}

package/dist/src/core/coordination/interrupt-policy.js

@@ -0,0 +1,89 @@
+/**
+ * Interrupt policy for coordination events.
+ *
+ * Determines whether an incoming event should interrupt an active agent
+ * session immediately, queue for the next safe boundary, or be silently
+ * recorded for later consumption.
+ *
+ * Policies are configurable per project via .handoff/policy.json.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+const DEFAULT_POLICY = {
+    defaultLevel: "boundary",
+    rules: [
+        // Ownership conflicts should interrupt immediately
+        { type: "ownership", from: "*", level: "immediate" },
+        // Contract changes interrupt at boundary
+        { type: "contract", from: "*", level: "boundary" },
+        // Decisions interrupt at boundary
+        { type: "decision", from: "*", level: "boundary" },
+        // Public design-room turns route sequentially at safe boundaries
+        { type: "discussion", from: "*", level: "boundary" },
+        // Progress updates are passive
+        { type: "update", from: "*", level: "passive" },
+        // Acks are always passive
+        { type: "ack", from: "*", level: "passive" },
+        // Tasks should interrupt at boundary
+        { type: "task", from: "*", level: "boundary" },
+        // Errors interrupt immediately
+        { type: "error", from: "*", level: "immediate" },
+        // Done events at boundary
+        { type: "done", from: "*", level: "boundary" },
+    ],
+};
+const policySchema = z
+    .object({
+    defaultLevel: z.enum(["immediate", "boundary", "passive"]).optional(),
+    rules: z
+        .array(z
+        .object({
+        type: z.string().trim().min(1).max(128),
+        from: z.string().trim().min(1).max(128),
+        level: z.enum(["immediate", "boundary", "passive"]),
+    })
+        .strict())
+        .max(100)
+        .optional(),
+})
+    .strict();
+export function evaluatePolicy(event, policy = DEFAULT_POLICY) {
+    for (const rule of policy.rules) {
+        const typeMatch = rule.type === "*" || rule.type === event.type;
+        const fromMatch = rule.from === "*" || rule.from === event.from;
+        if (typeMatch && fromMatch) {
+            return rule.level;
+        }
+    }
+    return policy.defaultLevel;
+}
+export function categorizeEvents(events, policy = DEFAULT_POLICY) {
+    const result = {
+        immediate: [],
+        boundary: [],
+        passive: [],
+    };
+    for (const event of events) {
+        const level = evaluatePolicy(event, policy);
+        result[level].push(event);
+    }
+    return result;
+}
+export async function loadPolicy(projectRoot) {
+    try {
+        const raw = await readFile(join(projectRoot, ".handoff", "policy.json"), "utf-8");
+        const parsed = policySchema.safeParse(JSON.parse(raw));
+        if (!parsed.success)
+            return DEFAULT_POLICY;
+        const custom = parsed.data;
+        return {
+            defaultLevel: custom.defaultLevel ?? DEFAULT_POLICY.defaultLevel,
+            rules: custom.rules ?? DEFAULT_POLICY.rules,
+        };
+    }
+    catch {
+        return DEFAULT_POLICY;
+    }
+}
+export { DEFAULT_POLICY };