@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/dist/agents/chain-serializer.js

@@ -0,0 +1,367 @@
+import { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.js";
+import { parseFrontmatter } from "./frontmatter.js";
+import { ChainOutputValidationError, validateChainOutputBindings } from "../runs/shared/chain-outputs.js";
+import { validateAcceptanceInput } from "../runs/shared/acceptance.js";
+import { Errors, Check } from "../shared/native-typebox.js";
+import { ChainItemSchema } from "../extension/schemas.js";
+function parseStepBody(agent, sectionBody) {
+    const lines = sectionBody.split("\n");
+    const blankIndex = lines.findIndex((line) => line.trim() === "");
+    const configLines = blankIndex === -1 ? lines : lines.slice(0, blankIndex);
+    const leadingTaskLines = [];
+    const taskLines = blankIndex === -1 ? [] : lines.slice(blankIndex + 1);
+    const step = { agent, task: "" };
+    let encodedTask;
+    for (const line of configLines) {
+        const match = line.match(/^([\w-]+):\s*(.*)$/);
+        if (!match) {
+            leadingTaskLines.push(line);
+            continue;
+        }
+        const key = match[1].trim().toLowerCase();
+        const rawValue = match[2].trim();
+        if (key === "task-json") {
+            if (encodedTask !== undefined)
+                throw new Error(`Duplicate task-json for step '${agent}'.`);
+            const value = JSON.parse(rawValue);
+            if (typeof value !== "string")
+                throw new Error(`task-json for step '${agent}' must be a JSON string.`);
+            encodedTask = value;
+            continue;
+        }
+        if (key === "output") {
+            if (rawValue === "false")
+                step.output = false;
+            else if (rawValue)
+                step.output = rawValue;
+            continue;
+        }
+        if (key === "phase") {
+            if (rawValue)
+                step.phase = rawValue;
+            continue;
+        }
+        if (key === "label") {
+            if (rawValue)
+                step.label = rawValue;
+            continue;
+        }
+        if (key === "as") {
+            if (rawValue)
+                step.as = rawValue;
+            continue;
+        }
+        if (key === "outputschema") {
+            if (rawValue.startsWith("{") || rawValue.startsWith("[")) {
+                throw new Error("Inline outputSchema values are not supported in .chain.md files; use a schema file path.");
+            }
+            if (rawValue)
+                step.outputSchema = rawValue;
+            continue;
+        }
+        if (key === "outputmode") {
+            if (rawValue !== "inline" && rawValue !== "file-only")
+                throw new Error(`Invalid outputMode '${rawValue}' for step '${agent}'.`);
+            step.outputMode = rawValue;
+            continue;
+        }
+        if (key === "reads") {
+            if (rawValue === "false") {
+                step.reads = false;
+            }
+            else {
+                const reads = rawValue
+                    .split(",")
+                    .map((v) => v.trim())
+                    .filter(Boolean);
+                step.reads = reads.length > 0 ? reads : false;
+            }
+            continue;
+        }
+        if (key === "model") {
+            if (rawValue)
+                step.model = rawValue;
+            continue;
+        }
+        if (key === "skills") {
+            if (rawValue === "false") {
+                step.skills = false;
+            }
+            else {
+                const skills = rawValue
+                    .split(",")
+                    .map((v) => v.trim())
+                    .filter(Boolean);
+                step.skills = skills.length > 0 ? skills : false;
+            }
+            continue;
+        }
+        if (key === "progress") {
+            if (rawValue !== "true" && rawValue !== "false")
+                throw new Error(`Invalid progress '${rawValue}' for step '${agent}'; use true or false.`);
+            step.progress = rawValue === "true";
+            continue;
+        }
+        leadingTaskLines.push(line);
+    }
+    const proseTask = [...leadingTaskLines, ...taskLines].join("\n").trim();
+    if (encodedTask !== undefined && proseTask)
+        throw new Error(`Step '${agent}' cannot combine task-json with task prose.`);
+    step.task = encodedTask ?? proseTask;
+    return step;
+}
+export function parseChain(content, source, filePath) {
+    const { frontmatter, body } = parseFrontmatter(content);
+    if (!frontmatter.name || !frontmatter.description) {
+        throw new Error("Chain frontmatter must include name and description");
+    }
+    const matches = [...body.matchAll(/^##\s+(.+)[^\S\n]*$/gm)];
+    const steps = [];
+    for (let i = 0; i < matches.length; i++) {
+        const match = matches[i];
+        const agent = match[1].trim();
+        const lineEndOffset = body[match.index + match[0].length] === "\n" ? 1 : 0;
+        const sectionStart = match.index + match[0].length + lineEndOffset;
+        const sectionEnd = i + 1 < matches.length ? matches[i + 1].index : body.length;
+        const sectionBody = body.slice(sectionStart, sectionEnd).trimEnd();
+        steps.push(parseStepBody(agent, sectionBody));
+    }
+    if (steps.length === 0)
+        throw new Error("Chain must include at least one ## agent step.");
+    const localName = frontmatter.name;
+    const parsedPackage = parsePackageName(frontmatter.package, `Chain '${localName}' package`);
+    if (parsedPackage.error)
+        throw new Error(parsedPackage.error);
+    const packageName = parsedPackage.packageName;
+    const extraFields = {};
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (key === "name" || key === "package" || key === "description")
+            continue;
+        extraFields[key] = value;
+    }
+    return {
+        name: buildRuntimeName(localName, packageName),
+        localName,
+        packageName,
+        description: frontmatter.description,
+        source,
+        filePath,
+        steps,
+        extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
+    };
+}
+const JSON_CHAIN_STEP_KEYS = new Set(["agent", "task", "phase", "label", "as", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "acceptance", "parallel", "expand", "collect", "concurrency", "failFast", "worktree"]);
+const JSON_PARALLEL_TASK_KEYS = new Set(["agent", "task", "phase", "label", "as", "outputSchema", "cwd", "count", "output", "outputMode", "reads", "progress", "skill", "model", "acceptance"]);
+export function parseJsonChain(content, source, filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON chain '${filePath}': ${message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`JSON chain '${filePath}' must contain an object root.`);
+    }
+    const input = parsed;
+    if (typeof input.name !== "string" || !input.name.trim()) {
+        throw new Error(`JSON chain '${filePath}' must include string name.`);
+    }
+    if (typeof input.description !== "string" || !input.description.trim()) {
+        throw new Error(`JSON chain '${filePath}' must include string description.`);
+    }
+    if (!Array.isArray(input.chain) || input.chain.length === 0) {
+        throw new Error(`JSON chain '${filePath}' must include a non-empty array chain.`);
+    }
+    for (let i = 0; i < input.chain.length; i++) {
+        const step = input.chain[i];
+        if (!step || typeof step !== "object" || Array.isArray(step)) {
+            throw new Error(`JSON chain '${filePath}' step ${i + 1} must be an object.`);
+        }
+        const stepRecord = step;
+        const unknownKeys = Object.keys(stepRecord).filter((key) => !JSON_CHAIN_STEP_KEYS.has(key));
+        if (unknownKeys.length)
+            throw new Error(`JSON chain '${filePath}' step ${i + 1} has unknown field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.join(", ")}.`);
+        const parallel = stepRecord.parallel;
+        if (parallel !== undefined && stepRecord.agent !== undefined)
+            throw new Error(`JSON chain '${filePath}' step ${i + 1} cannot set both agent and parallel.`);
+        if (parallel === undefined) {
+            if (typeof stepRecord.agent !== "string" || !stepRecord.agent.trim())
+                throw new Error(`JSON chain '${filePath}' step ${i + 1} must include a non-empty agent.`);
+        }
+        else if (Array.isArray(parallel)) {
+            if (parallel.length === 0)
+                throw new Error(`JSON chain '${filePath}' step ${i + 1} parallel must not be empty.`);
+            for (let taskIndex = 0; taskIndex < parallel.length; taskIndex++) {
+                const task = parallel[taskIndex];
+                if (!task || typeof task !== "object" || Array.isArray(task) || typeof task.agent !== "string" || !task.agent.trim()) {
+                    throw new Error(`JSON chain '${filePath}' step ${i + 1} parallel task ${taskIndex + 1} must include a non-empty agent.`);
+                }
+                const taskUnknownKeys = Object.keys(task).filter((key) => !JSON_PARALLEL_TASK_KEYS.has(key));
+                if (taskUnknownKeys.length)
+                    throw new Error(`JSON chain '${filePath}' step ${i + 1} parallel task ${taskIndex + 1} has unknown field${taskUnknownKeys.length === 1 ? "" : "s"}: ${taskUnknownKeys.join(", ")}.`);
+            }
+        }
+        else if (typeof parallel === "object" && parallel !== null) {
+            if (typeof parallel.agent !== "string" || !parallel.agent.trim())
+                throw new Error(`JSON chain '${filePath}' step ${i + 1} dynamic template must include a non-empty agent.`);
+            if (!stepRecord.expand || typeof stepRecord.expand !== "object" || !stepRecord.collect || typeof stepRecord.collect !== "object")
+                throw new Error(`JSON chain '${filePath}' step ${i + 1} dynamic fanout requires expand and collect objects.`);
+        }
+        else {
+            throw new Error(`JSON chain '${filePath}' step ${i + 1} parallel must be an array or object.`);
+        }
+        if (stepRecord.concurrency !== undefined && (typeof stepRecord.concurrency !== "number" || !Number.isInteger(stepRecord.concurrency) || stepRecord.concurrency < 1))
+            throw new Error(`JSON chain '${filePath}' step ${i + 1} concurrency must be an integer >= 1.`);
+        if (Array.isArray(parallel) && Object.hasOwn(stepRecord, "acceptance")) {
+            throw new Error(`Invalid JSON chain '${filePath}': step ${i + 1} acceptance is not supported on static parallel groups; set acceptance on each parallel task.`);
+        }
+        if (parallel && typeof parallel === "object" && !Array.isArray(parallel) && Object.hasOwn(stepRecord, "acceptance")) {
+            throw new Error(`Invalid JSON chain '${filePath}': step ${i + 1} acceptance is not supported on dynamic fanout groups; set acceptance on the dynamic template.`);
+        }
+        const acceptanceErrors = validateAcceptanceInput(stepRecord.acceptance, `step ${i + 1} acceptance`);
+        if (acceptanceErrors.length > 0) {
+            throw new Error(`Invalid JSON chain '${filePath}': ${acceptanceErrors.join(" ")}`);
+        }
+        if (Array.isArray(parallel)) {
+            for (let taskIndex = 0; taskIndex < parallel.length; taskIndex++) {
+                const task = parallel[taskIndex];
+                if (!task || typeof task !== "object" || Array.isArray(task))
+                    continue;
+                const taskErrors = validateAcceptanceInput(task.acceptance, `step ${i + 1} parallel task ${taskIndex + 1} acceptance`);
+                if (taskErrors.length > 0) {
+                    throw new Error(`Invalid JSON chain '${filePath}': ${taskErrors.join(" ")}`);
+                }
+            }
+        }
+        else if (parallel && typeof parallel === "object") {
+            const templateErrors = validateAcceptanceInput(parallel.acceptance, `step ${i + 1} dynamic template acceptance`);
+            if (templateErrors.length > 0) {
+                throw new Error(`Invalid JSON chain '${filePath}': ${templateErrors.join(" ")}`);
+            }
+        }
+    }
+    try {
+        validateChainOutputBindings(input.chain, { maxItems: Number.MAX_SAFE_INTEGER });
+    }
+    catch (error) {
+        if (error instanceof ChainOutputValidationError)
+            throw new Error(`Invalid JSON chain '${filePath}': ${error.message}`);
+        throw error;
+    }
+    for (let i = 0; i < input.chain.length; i++) {
+        const step = input.chain[i];
+        if (!Check(ChainItemSchema, step)) {
+            const issue = [...Errors(ChainItemSchema, step)][0];
+            throw new Error(`JSON chain '${filePath}' step ${i + 1} is invalid${issue ? `: ${issue.message}` : ""}.`);
+        }
+    }
+    const parsedPackage = parsePackageName(typeof input.package === "string" ? input.package : undefined, `Chain '${input.name}' package`);
+    if (parsedPackage.error)
+        throw new Error(parsedPackage.error);
+    const extraFields = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (key === "name" || key === "package" || key === "description" || key === "chain")
+            continue;
+        if (typeof value === "string")
+            extraFields[key] = value;
+    }
+    const steps = input.chain.map((step) => {
+        if (!Object.hasOwn(step, "skill"))
+            return step;
+        const { skill, ...normalized } = step;
+        return {
+            ...normalized,
+            skills: typeof skill === "string" ? [skill] : skill,
+        };
+    });
+    return {
+        name: buildRuntimeName(input.name.trim(), parsedPackage.packageName),
+        localName: input.name.trim(),
+        packageName: parsedPackage.packageName,
+        description: input.description.trim(),
+        source,
+        filePath,
+        steps,
+        extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
+    };
+}
+export function serializeJsonChain(config) {
+    const chain = config.steps.map((step) => {
+        const { skills, ...serialized } = step;
+        return skills === undefined ? serialized : { ...serialized, skill: skills };
+    });
+    const root = {
+        name: frontmatterNameForConfig(config),
+        description: config.description,
+        chain,
+    };
+    if (config.packageName)
+        root.package = config.packageName;
+    if (config.extraFields) {
+        for (const [key, value] of Object.entries(config.extraFields)) {
+            if (key !== "name" && key !== "description" && key !== "package" && key !== "chain")
+                root[key] = value;
+        }
+    }
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+export function serializeChain(config) {
+    const lines = [];
+    lines.push("---");
+    lines.push(`name: ${frontmatterNameForConfig(config)}`);
+    if (config.packageName)
+        lines.push(`package: ${config.packageName}`);
+    lines.push(`description: ${config.description}`);
+    if (config.extraFields) {
+        for (const [key, value] of Object.entries(config.extraFields)) {
+            lines.push(`${key}: ${value}`);
+        }
+    }
+    lines.push("---");
+    lines.push("");
+    for (let i = 0; i < config.steps.length; i++) {
+        const step = config.steps[i];
+        lines.push(`## ${step.agent}`);
+        if (step.output === false)
+            lines.push("output: false");
+        else if (step.output)
+            lines.push(`output: ${step.output}`);
+        if (step.phase)
+            lines.push(`phase: ${step.phase}`);
+        if (step.label)
+            lines.push(`label: ${step.label}`);
+        if (step.as)
+            lines.push(`as: ${step.as}`);
+        if (step.outputSchema)
+            lines.push(`outputSchema: ${step.outputSchema}`);
+        if (step.outputMode)
+            lines.push(`outputMode: ${step.outputMode}`);
+        if (step.reads === false)
+            lines.push("reads: false");
+        else if (Array.isArray(step.reads) && step.reads.length > 0)
+            lines.push(`reads: ${step.reads.join(", ")}`);
+        if (step.model)
+            lines.push(`model: ${step.model}`);
+        if (step.skills === false)
+            lines.push("skills: false");
+        else if (Array.isArray(step.skills) && step.skills.length > 0)
+            lines.push(`skills: ${step.skills.join(", ")}`);
+        if (step.progress !== undefined)
+            lines.push(`progress: ${step.progress ? "true" : "false"}`);
+        const task = step.task ?? "";
+        if (/^##\s+/m.test(task)) {
+            // JSON leaves these separators raw, but the Markdown header regex treats them as line breaks.
+            const encoded = JSON.stringify(task).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+            lines.push(`task-json: ${encoded}`);
+        }
+        else {
+            lines.push("");
+            lines.push(task);
+        }
+        if (i < config.steps.length - 1)
+            lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/agents/frontmatter.js

@@ -0,0 +1,21 @@
+export function parseFrontmatter(content) {
+    const frontmatter = {};
+    const normalized = content.replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    if (!/^---\s*$/.test(lines[0] ?? ""))
+        return { frontmatter, body: normalized };
+    const endIndex = lines.findIndex((line, index) => index > 0 && /^---\s*$/.test(line));
+    if (endIndex === -1)
+        return { frontmatter, body: normalized };
+    for (const line of lines.slice(1, endIndex)) {
+        const match = line.match(/^([\w-]+):\s*(.*)$/);
+        if (!match)
+            continue;
+        let value = match[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        frontmatter[match[1]] = value;
+    }
+    return { frontmatter, body: lines.slice(endIndex + 1).join("\n").trim() };
+}

package/dist/agents/identity.js

@@ -0,0 +1,29 @@
+const IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
+function normalizePackageName(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9.-]/g, "").replace(/-+/g, "-").replace(/\.+/g, ".").replace(/(?:^[-.]+|[-.]+$)/g, "");
+}
+export function parsePackageName(value, label = "package") {
+    if (value === undefined || value === false || value === "")
+        return { packageName: undefined };
+    if (typeof value !== "string")
+        return { error: `${label} must be a string or false when provided.` };
+    const packageName = normalizePackageName(value);
+    if (!packageName || !IDENTIFIER_PATTERN.test(packageName))
+        return { error: `${label} is invalid after sanitization.` };
+    return { packageName };
+}
+export function buildRuntimeName(localName, packageName) {
+    const trimmedPackage = packageName?.trim();
+    return trimmedPackage ? `${trimmedPackage}.${localName}` : localName;
+}
+export function frontmatterNameForConfig(config) {
+    if (config.localName)
+        return config.localName;
+    if (config.packageName && config.name.startsWith(`${config.packageName}.`)) {
+        return config.name.slice(config.packageName.length + 1);
+    }
+    return config.name;
+}