loadout-ai 0.8.0 → 0.9.1

package/dist/src/core/delegation/handoff-bundle.js

@@ -0,0 +1,253 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readFile, realpath, rm } from "node:fs/promises";
+import { isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { redactString } from "../coordination/redaction.js";
+export const HANDOFF_BUNDLE_MAX_FILES = 20;
+export const HANDOFF_BUNDLE_MAX_FILE_BYTES = 32 * 1024;
+export const HANDOFF_BUNDLE_MAX_TOTAL_BYTES = 50 * 1024;
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+const handoffBundleFileSchema = z
+    .object({
+    path: z
+        .string()
+        .trim()
+        .min(1)
+        .refine((path) => !path.startsWith("/") &&
+        !path.split("/").includes("..") &&
+        ![".git", ".handoff"].includes(path.split("/")[0] ?? ""), "must be a safe project-relative source path"),
+    sourceBytes: z.number().int().nonnegative(),
+    storedBytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(HANDOFF_BUNDLE_MAX_FILE_BYTES),
+    sourceSha256: sha256Schema,
+    isTruncated: z.boolean(),
+    content: z.string(),
+})
+    .strict();
+const handoffBundleSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    createdAt: z.iso.datetime({ offset: true }),
+    files: z
+        .array(handoffBundleFileSchema)
+        .min(1)
+        .max(HANDOFF_BUNDLE_MAX_FILES),
+})
+    .strict()
+    .superRefine((bundle, context) => {
+    let total = 0;
+    bundle.files.forEach((file, index) => {
+        const actual = Buffer.byteLength(file.content);
+        if (actual !== file.storedBytes) {
+            context.addIssue({
+                code: "custom",
+                path: ["files", index, "storedBytes"],
+                message: "does not match the UTF-8 content byte length",
+            });
+        }
+        total += actual;
+    });
+    if (total > HANDOFF_BUNDLE_MAX_TOTAL_BYTES) {
+        context.addIssue({
+            code: "custom",
+            path: ["files"],
+            message: `stored content exceeds ${HANDOFF_BUNDLE_MAX_TOTAL_BYTES} bytes`,
+        });
+    }
+});
+export const handoffBundleReferenceSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    path: z.string().regex(/^\.handoff\/bundles\/[a-f0-9-]+\.json$/),
+    fileCount: z.number().int().min(1).max(HANDOFF_BUNDLE_MAX_FILES),
+    storedBytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(HANDOFF_BUNDLE_MAX_TOTAL_BYTES),
+    isTruncated: z.boolean(),
+})
+    .strict();
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+async function assertNoSymlinkComponents(root, relativePath, allowMissing) {
+    let current = root;
+    let finalInfo;
+    for (const segment of relativePath.split("/")) {
+        current = join(current, segment);
+        try {
+            finalInfo = await lstat(current);
+        }
+        catch (error) {
+            if (allowMissing && errorCode(error) === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        if (finalInfo.isSymbolicLink())
+            throw new Error(`Bundle path cannot use a symlink: ${relativePath}`);
+    }
+    return finalInfo;
+}
+async function readBoundedTextFile(absolute, path, maximumBytes) {
+    const hash = createHash("sha256");
+    const utf8Validator = new TextDecoder("utf-8", { fatal: true });
+    const captured = [];
+    let capturedBytes = 0;
+    let sourceBytes = 0;
+    try {
+        for await (const value of createReadStream(absolute)) {
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            sourceBytes += chunk.byteLength;
+            hash.update(chunk);
+            utf8Validator.decode(chunk, { stream: true });
+            if (chunk.includes(0))
+                throw new Error(`Bundle path appears to be binary: ${path}`);
+            if (capturedBytes < maximumBytes) {
+                const remaining = maximumBytes - capturedBytes;
+                const part = chunk.subarray(0, remaining);
+                captured.push(part);
+                capturedBytes += part.byteLength;
+            }
+        }
+        utf8Validator.decode();
+    }
+    catch (error) {
+        if (error instanceof Error && /appears to be binary/.test(error.message))
+            throw error;
+        if (error instanceof TypeError)
+            throw new Error(`Bundle path appears to be binary: ${path}`);
+        throw error;
+    }
+    const prefix = Buffer.concat(captured);
+    let decoded = "";
+    let trim = 0;
+    for (; trim <= Math.min(3, prefix.byteLength); trim += 1) {
+        try {
+            decoded = new TextDecoder("utf-8", { fatal: true }).decode(prefix.subarray(0, prefix.byteLength - trim));
+            break;
+        }
+        catch {
+            // A bounded prefix can end in the middle of one UTF-8 code point.
+        }
+    }
+    if (trim > Math.min(3, prefix.byteLength))
+        throw new Error(`Bundle path appears to be binary: ${path}`);
+    const redacted = redactString(decoded);
+    const redactedBytes = Buffer.from(redacted);
+    let content = redacted;
+    if (redactedBytes.byteLength > maximumBytes) {
+        for (let remove = 0; remove <= 3; remove += 1) {
+            try {
+                content = new TextDecoder("utf-8", { fatal: true }).decode(redactedBytes.subarray(0, maximumBytes - remove));
+                break;
+            }
+            catch {
+                // Keep trimming until the byte cap lands on a UTF-8 boundary.
+            }
+        }
+    }
+    const storedBytes = Buffer.byteLength(content);
+    return {
+        sourceBytes,
+        sourceSha256: hash.digest("hex"),
+        content,
+        storedBytes,
+        isTruncated: sourceBytes > capturedBytes ||
+            trim > 0 ||
+            redactedBytes.byteLength > maximumBytes,
+    };
+}
+function projectRelativePath(projectRoot, requestedPath) {
+    if (!requestedPath.trim())
+        throw new Error("Bundle path cannot be empty");
+    if (isAbsolute(requestedPath))
+        throw new Error(`Bundle path must be project-relative: ${requestedPath}`);
+    const root = resolve(projectRoot);
+    const absolute = resolve(root, requestedPath);
+    const local = relative(root, absolute);
+    if (!local || local === ".." || local.startsWith(`..${sep}`))
+        throw new Error(`Bundle path must stay inside the project: ${requestedPath}`);
+    const normalized = local.split(sep).join(posix.sep);
+    const firstSegment = normalized.split(posix.sep)[0];
+    if (firstSegment === ".git" || firstSegment === ".handoff")
+        throw new Error(`Bundle path cannot read Loadout or Git internal state: ${requestedPath}`);
+    return normalized;
+}
+export async function createHandoffBundle(projectRoot, requestedPaths) {
+    if (!requestedPaths.length)
+        throw new Error("Bundle requires at least one file");
+    if (requestedPaths.length > HANDOFF_BUNDLE_MAX_FILES)
+        throw new Error(`Bundle accepts at most ${HANDOFF_BUNDLE_MAX_FILES} files`);
+    const files = [];
+    const canonicalRoot = await realpath(projectRoot);
+    let totalStoredBytes = 0;
+    for (const requestedPath of requestedPaths) {
+        const path = projectRelativePath(projectRoot, requestedPath);
+        const absolute = resolve(canonicalRoot, path);
+        const info = await assertNoSymlinkComponents(canonicalRoot, path, false);
+        if (!info)
+            throw new Error(`Bundle path does not exist: ${path}`);
+        if (!info.isFile())
+            throw new Error(`Bundle path is not a file: ${path}`);
+        const remaining = HANDOFF_BUNDLE_MAX_TOTAL_BYTES - totalStoredBytes;
+        const snapshot = await readBoundedTextFile(absolute, path, Math.min(HANDOFF_BUNDLE_MAX_FILE_BYTES, remaining));
+        files.push({
+            path,
+            ...snapshot,
+        });
+        totalStoredBytes += snapshot.storedBytes;
+    }
+    const bundle = {
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        files,
+    };
+    const id = randomUUID();
+    const path = `.handoff/bundles/${id}.json`;
+    await assertNoSymlinkComponents(canonicalRoot, ".handoff/bundles", true);
+    await writeFileAtomically(resolve(projectRoot, path), `${JSON.stringify(bundle, null, 2)}\n`);
+    return {
+        schemaVersion: 1,
+        path,
+        fileCount: files.length,
+        storedBytes: totalStoredBytes,
+        isTruncated: files.some((file) => file.isTruncated),
+    };
+}
+export async function readHandoffBundle(projectRoot, reference) {
+    const validReference = handoffBundleReferenceSchema.parse(reference);
+    const canonicalRoot = await realpath(projectRoot);
+    await assertNoSymlinkComponents(canonicalRoot, validReference.path, false);
+    const raw = await readFile(resolve(canonicalRoot, validReference.path), "utf8");
+    let bundle;
+    try {
+        bundle = handoffBundleSchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : "unparseable JSON";
+        throw new Error(`Invalid handoff bundle '${validReference.path}': ${reason}`);
+    }
+    const storedBytes = bundle.files.reduce((total, file) => total + file.storedBytes, 0);
+    const isTruncated = bundle.files.some((file) => file.isTruncated);
+    if (validReference.fileCount !== bundle.files.length ||
+        validReference.storedBytes !== storedBytes ||
+        validReference.isTruncated !== isTruncated) {
+        throw new Error(`Handoff bundle reference does not match '${validReference.path}'`);
+    }
+    return bundle;
+}
+/** Remove only a schema-valid bundle path, used to roll back a failed send. */
+export async function removeHandoffBundle(projectRoot, reference) {
+    const validReference = handoffBundleReferenceSchema.parse(reference);
+    const canonicalRoot = await realpath(projectRoot);
+    await assertNoSymlinkComponents(canonicalRoot, validReference.path, true);
+    await rm(resolve(canonicalRoot, validReference.path), { force: true });
+}

package/dist/src/core/delegation/handoff-templates.js

@@ -0,0 +1,222 @@
+/**
+ * Handoff templates — reusable task presets for common handoff patterns.
+ *
+ * Templates live in `.handoff/templates/` as JSON files. Each defines
+ * default fields (verification, context, bundle globs) so agents can
+ * hand off tasks with a single `--template <name>` flag.
+ */
+import { readFile, writeFile, readdir, mkdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+const templateNameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .regex(/^[a-z0-9][a-z0-9-]*$/, "template name must be kebab-case");
+const templateSchema = z.object({
+    name: templateNameSchema,
+    description: z.string().trim().min(1),
+    defaultAgent: z.string().trim().min(1).optional(),
+    taskTemplate: z.string().trim().min(1).optional(),
+    context: z.string().optional(),
+    bundleGlobs: z.array(z.string().trim().min(1)).optional(),
+    verifyCriteria: z.string().trim().min(1).optional(),
+    verifyCommand: z
+        .object({
+        executable: z.string().trim().min(1),
+        args: z.array(z.string()),
+        timeoutMs: z.number().int().min(1000).max(900_000).optional(),
+    })
+        .optional(),
+});
+// ── Built-in templates ─────────────────────────────────────────────────
+export const BUILTIN_TEMPLATES = [
+    {
+        name: "write-tests",
+        description: "Write tests for specified files",
+        taskTemplate: "Write tests for {{files}}",
+        verifyCriteria: "All new tests pass",
+        verifyCommand: {
+            executable: "npm",
+            args: ["test"],
+            timeoutMs: 120_000,
+        },
+    },
+    {
+        name: "review-code",
+        description: "Review code changes for bugs and style",
+        taskTemplate: "Review the changes in {{files}} for correctness and style",
+        verifyCriteria: "Review comments posted or no issues found",
+    },
+    {
+        name: "fix-bug",
+        description: "Fix a reported bug with verification",
+        taskTemplate: "Fix: {{description}}",
+        verifyCriteria: "Bug no longer reproduces and existing tests pass",
+        verifyCommand: {
+            executable: "npm",
+            args: ["test"],
+            timeoutMs: 120_000,
+        },
+    },
+    {
+        name: "implement-feature",
+        description: "Implement a feature from spec",
+        taskTemplate: "Implement: {{description}}",
+        context: "Follow existing patterns in the codebase",
+        verifyCriteria: "Feature works and tests pass",
+        verifyCommand: {
+            executable: "npm",
+            args: ["test"],
+            timeoutMs: 120_000,
+        },
+    },
+    {
+        name: "refactor",
+        description: "Refactor code for clarity without behavior changes",
+        taskTemplate: "Refactor {{files}} for clarity",
+        verifyCriteria: "All existing tests still pass, no behavior changes",
+        verifyCommand: {
+            executable: "npm",
+            args: ["test"],
+            timeoutMs: 120_000,
+        },
+    },
+];
+// ── File I/O ───────────────────────────────────────────────────────────
+const TEMPLATES_DIR = ".handoff/templates";
+function templatesDir(projectRoot) {
+    return join(projectRoot, TEMPLATES_DIR);
+}
+function templatePath(projectRoot, name) {
+    const safeName = templateNameSchema.parse(name);
+    return join(templatesDir(projectRoot), `${safeName}.json`);
+}
+export async function ensureTemplatesDir(projectRoot) {
+    await mkdir(templatesDir(projectRoot), { recursive: true });
+}
+export async function saveTemplate(projectRoot, template) {
+    const parsed = templateSchema.parse(template);
+    await ensureTemplatesDir(projectRoot);
+    await writeFile(templatePath(projectRoot, parsed.name), JSON.stringify(parsed, null, 2) + "\n", "utf8");
+}
+export async function deleteTemplate(projectRoot, name) {
+    const path = templatePath(projectRoot, name);
+    try {
+        await unlink(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function loadTemplate(projectRoot, name) {
+    // Check custom templates first
+    try {
+        const raw = await readFile(templatePath(projectRoot, name), "utf8");
+        return templateSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        // Fall through to builtins
+    }
+    return BUILTIN_TEMPLATES.find((t) => t.name === name) ?? null;
+}
+export async function listTemplates(projectRoot) {
+    const custom = [];
+    try {
+        const files = await readdir(templatesDir(projectRoot));
+        for (const file of files) {
+            if (!file.endsWith(".json"))
+                continue;
+            try {
+                const raw = await readFile(join(templatesDir(projectRoot), file), "utf8");
+                custom.push(templateSchema.parse(JSON.parse(raw)));
+            }
+            catch {
+                // Skip malformed templates
+            }
+        }
+    }
+    catch {
+        // No templates dir yet
+    }
+    // Filter builtins that have been overridden
+    const customNames = new Set(custom.map((t) => t.name));
+    const builtin = BUILTIN_TEMPLATES.filter((t) => !customNames.has(t.name));
+    return { custom, builtin };
+}
+export function applyTemplate(template, options = {}) {
+    const vars = options.vars ?? {};
+    // Resolve task description
+    let description = options.task ?? template.taskTemplate ?? template.name;
+    const resolvedVars = options.input
+        ? {
+            files: options.input,
+            description: options.input,
+            task: options.input,
+            ...vars,
+        }
+        : vars;
+    for (const [key, value] of Object.entries(resolvedVars)) {
+        description = description.replaceAll(`{{${key}}}`, value);
+    }
+    return {
+        agent: options.agent ?? template.defaultAgent,
+        description,
+        context: template.context,
+        bundleGlobs: template.bundleGlobs,
+        verifyCriteria: template.verifyCriteria,
+        verifyCommand: template.verifyCommand
+            ? {
+                executable: template.verifyCommand.executable,
+                args: template.verifyCommand.args,
+                timeoutMs: template.verifyCommand.timeoutMs ?? 120_000,
+            }
+            : undefined,
+    };
+}
+// ── Formatting ─────────────────────────────────────────────────────────
+export function formatTemplateList(templates) {
+    const lines = [];
+    if (templates.custom.length === 0 && templates.builtin.length === 0) {
+        return "No templates available.";
+    }
+    if (templates.custom.length) {
+        lines.push(`\x1b[1mCustom templates\x1b[0m (${templates.custom.length})`);
+        for (const t of templates.custom) {
+            lines.push(`  \x1b[36m${t.name}\x1b[0m — ${t.description}`);
+        }
+    }
+    if (templates.builtin.length) {
+        if (templates.custom.length)
+            lines.push("");
+        lines.push(`\x1b[1mBuilt-in templates\x1b[0m (${templates.builtin.length})`);
+        for (const t of templates.builtin) {
+            lines.push(`  \x1b[90m${t.name}\x1b[0m — ${t.description}`);
+        }
+    }
+    lines.push("");
+    lines.push("\x1b[90mUse: loadout handoff <agent> --template <name> [task...]\x1b[0m");
+    lines.push("\x1b[90mCreate: loadout template create <name> --description '...'\x1b[0m");
+    return lines.join("\n");
+}
+export function formatTemplateDetail(template) {
+    const lines = [];
+    lines.push(`\x1b[1m${template.name}\x1b[0m — ${template.description}`);
+    if (template.defaultAgent)
+        lines.push(`  Agent: ${template.defaultAgent}`);
+    if (template.taskTemplate)
+        lines.push(`  Task: ${template.taskTemplate}`);
+    if (template.context)
+        lines.push(`  Context: ${template.context}`);
+    if (template.bundleGlobs)
+        lines.push(`  Bundle: ${template.bundleGlobs.join(", ")}`);
+    if (template.verifyCriteria)
+        lines.push(`  Verify: ${template.verifyCriteria}`);
+    if (template.verifyCommand) {
+        lines.push(`  Command: ${template.verifyCommand.executable} ${template.verifyCommand.args.join(" ")}`);
+        if (template.verifyCommand.timeoutMs)
+            lines.push(`  Timeout: ${template.verifyCommand.timeoutMs / 1000}s`);
+    }
+    return lines.join("\n");
+}

package/dist/src/core/delegation/handoff-verification.js

@@ -0,0 +1,117 @@
+import { getHandoffState, sendHandoffUnlocked, withHandoffLock, HANDOFF_VERIFICATION_MAX_OUTPUT_BYTES, } from "./handoff.js";
+import { redactString } from "../coordination/redaction.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export const defaultHandoffVerificationRunner = async (projectRoot, command) => {
+    const started = Date.now();
+    try {
+        const result = await execFileAsync(command.executable, command.args, {
+            cwd: projectRoot,
+            timeout: command.timeoutMs,
+            maxBuffer: 1024 * 1024,
+            windowsHide: true,
+            shell: false,
+            encoding: "utf8",
+        });
+        return {
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exitCode: 0,
+            durationMs: Math.min(Date.now() - started, 900_000),
+            timedOut: false,
+        };
+    }
+    catch (error) {
+        const failure = error;
+        return {
+            stdout: failure.stdout ?? "",
+            stderr: failure.stderr ?? (error instanceof Error ? error.message : ""),
+            exitCode: typeof failure.code === "number" ? failure.code : 1,
+            durationMs: Math.min(Date.now() - started, 900_000),
+            timedOut: failure.killed === true,
+        };
+    }
+};
+function boundedOutput(value) {
+    const redacted = redactString(value);
+    const bytes = Buffer.from(redacted);
+    if (bytes.byteLength <= HANDOFF_VERIFICATION_MAX_OUTPUT_BYTES)
+        return { value: redacted, isTruncated: false };
+    for (let remove = 0; remove <= 3; remove += 1) {
+        try {
+            return {
+                value: new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, HANDOFF_VERIFICATION_MAX_OUTPUT_BYTES - remove)),
+                isTruncated: true,
+            };
+        }
+        catch {
+            // The byte cap can land inside one UTF-8 code point.
+        }
+    }
+    return { value: "", isTruncated: true };
+}
+export async function completeHandoff(projectRoot, messageId, options = {}) {
+    const original = await withHandoffLock(projectRoot, async () => {
+        const state = await getHandoffState(projectRoot);
+        const task = state.messages.find((message) => message.id === messageId);
+        if (!task)
+            throw new Error(`Message '${messageId}' not found`);
+        if (task.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 task;
+    });
+    if (original.verification &&
+        !original.verification.command &&
+        !options.manualEvidence?.trim())
+        throw new Error(`Task '${messageId}' requires manual evidence for: ${original.verification.criteria}`);
+    if (original.verification?.command && !options.approveCommand)
+        throw new Error(`Task '${messageId}' requires explicit approval to run its stored verification command`);
+    let completed = true;
+    let description = `Completed: ${original.description}`;
+    let evidence;
+    if (original.verification?.command) {
+        const command = original.verification.command;
+        const result = await (options.runner ?? defaultHandoffVerificationRunner)(projectRoot, command);
+        const passed = result.exitCode === 0 && !result.timedOut;
+        const stdout = boundedOutput(result.stdout);
+        const stderr = boundedOutput(result.stderr);
+        completed = passed;
+        description = passed
+            ? `Completed: ${original.description}`
+            : `Verification failed: ${original.verification.criteria}`;
+        evidence = {
+            mode: "command",
+            status: passed ? "passed" : "failed",
+            command: [command.executable, ...command.args],
+            exitCode: result.exitCode,
+            durationMs: result.durationMs,
+            stdout: stdout.value,
+            stderr: stderr.value,
+            timedOut: result.timedOut,
+            isTruncated: stdout.isTruncated || stderr.isTruncated,
+        };
+    }
+    else if (original.verification) {
+        evidence = {
+            mode: "manual",
+            status: "passed",
+            summary: options.manualEvidence.trim(),
+            isTruncated: false,
+        };
+    }
+    return withHandoffLock(projectRoot, async () => {
+        const current = await getHandoffState(projectRoot);
+        if (current.done.some((message) => message.id === messageId))
+            throw new Error(`Message '${messageId}' is already settled`);
+        const message = await sendHandoffUnlocked(projectRoot, original.from, description, {
+            from: original.to,
+            type: completed ? "done" : "status",
+            resolves: messageId,
+            ...(evidence ? { evidence } : {}),
+        });
+        return { completed, message };
+    });
+}