@tea-agent/loop-agent 0.1.0

package/dist/workflows/dag/runtime.js

@@ -0,0 +1,5 @@
+export * from "./canvas-observer.js";
+export * from "./executor-registry.js";
+export * from "./lifecycle.js";
+export * from "./runner.js";
+export * from "./topo.js";

package/dist/workflows/dag/skill-instructions.js

@@ -0,0 +1,471 @@
+import { createHash } from "node:crypto";
+import { access, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const DEFAULT_SKILL_INSTRUCTION_MAX_CHARS = 2_500;
+export const DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS = 10_000;
+const SKILL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function normalizeCandidate(filePath) {
+    return path.resolve(filePath);
+}
+function bundledSkillCandidatePaths(name) {
+    const candidates = [];
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        candidates.push(normalizeCandidate(path.join(current, "skills", name, "SKILL.md")));
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return candidates;
+}
+function buildSkillCandidatePaths(input) {
+    const candidates = [];
+    const agentDir = input.env.PI_CODING_AGENT_DIR;
+    if (agentDir) {
+        candidates.push(normalizeCandidate(path.join(agentDir, "skills", input.name, "SKILL.md")), normalizeCandidate(path.join(agentDir, "skills", `${input.name}.md`)));
+    }
+    const piSkillsDir = path.join(input.homeDir, ".pi", "agent", "skills");
+    candidates.push(normalizeCandidate(path.join(piSkillsDir, input.name, "SKILL.md")), normalizeCandidate(path.join(piSkillsDir, `${input.name}.md`)));
+    candidates.push(normalizeCandidate(path.join(input.cwd, "skills", input.name, "SKILL.md")));
+    if (input.name === "loop-agent") {
+        candidates.push(normalizeCandidate(path.join(input.cwd, "skill", "SKILL.md")));
+    }
+    candidates.push(...bundledSkillCandidatePaths(input.name));
+    return Array.from(new Set(candidates));
+}
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+export function splitSkillFrontmatter(content) {
+    const match = content.match(FRONTMATTER_RE);
+    if (!match) {
+        return { frontmatter: null, body: content };
+    }
+    return {
+        frontmatter: match[1],
+        body: content.slice(match[0].length),
+    };
+}
+export function parseSkillReferenceDeclarations(frontmatter) {
+    const lines = frontmatter.split(/\r?\n/);
+    let inReferences = false;
+    let referencesKeyIndent = -1;
+    const declarations = [];
+    let currentObject = null;
+    const flushCurrentObject = () => {
+        if (currentObject?.path) {
+            declarations.push(currentObject);
+        }
+        currentObject = null;
+    };
+    for (const line of lines) {
+        if (!inReferences) {
+            if (/^references:\s*$/.test(line)) {
+                inReferences = true;
+                referencesKeyIndent = 0;
+            }
+            continue;
+        }
+        if (line.trim() === "")
+            continue;
+        const indent = line.search(/\S/);
+        if (indent === -1)
+            continue;
+        if (indent <= referencesKeyIndent && !/^\s*-\s+/.test(line)) {
+            flushCurrentObject();
+            break;
+        }
+        const listMatch = line.match(/^(\s*)-\s+(.*)$/);
+        if (listMatch) {
+            flushCurrentObject();
+            const rest = listMatch[2].trim();
+            if (rest.startsWith("path:")) {
+                currentObject = {
+                    path: rest.slice("path:".length).trim().replace(/^['"]|['"]$/g, ""),
+                };
+            }
+            else if (!rest.includes(":")) {
+                declarations.push({
+                    path: rest.replace(/^['"]|['"]$/g, ""),
+                });
+            }
+            continue;
+        }
+        if (currentObject) {
+            const propMatch = line.match(/^\s+(\w+):\s*(.*)$/);
+            if (propMatch) {
+                const key = propMatch[1];
+                const value = propMatch[2].trim().replace(/^['"]|['"]$/g, "");
+                if (key === "path")
+                    currentObject.path = value;
+                if (key === "name")
+                    currentObject.name = value;
+                if (key === "maxChars") {
+                    const parsed = Number.parseInt(value, 10);
+                    if (Number.isFinite(parsed) && parsed > 0) {
+                        currentObject.maxChars = parsed;
+                    }
+                }
+                if (key === "required")
+                    currentObject.required = value === "true";
+            }
+        }
+    }
+    flushCurrentObject();
+    return declarations;
+}
+function isValidReferencePath(refPath) {
+    if (!refPath || refPath.includes("\\"))
+        return false;
+    if (path.isAbsolute(refPath))
+        return false;
+    if (/[*?[\]{}]/.test(refPath))
+        return false;
+    if (!refPath.endsWith(".md"))
+        return false;
+    return !refPath
+        .split("/")
+        .some((segment) => segment === "" || segment === "." || segment === "..");
+}
+function isPathWithinDir(resolvedPath, dir) {
+    const normalizedDir = path.resolve(dir);
+    const normalizedResolved = path.resolve(resolvedPath);
+    return (normalizedResolved === normalizedDir ||
+        normalizedResolved.startsWith(`${normalizedDir}${path.sep}`));
+}
+function referenceDisplayName(declaration) {
+    if (declaration.name)
+        return declaration.name;
+    const base = path.basename(declaration.path, ".md");
+    return base || declaration.path;
+}
+function truncateReferenceContent(content, maxChars) {
+    if (content.length <= maxChars) {
+        return { excerpt: content, truncated: false };
+    }
+    return {
+        excerpt: `${content.slice(0, Math.max(0, maxChars))}\n[reference truncated at ${maxChars} chars]`,
+        truncated: true,
+    };
+}
+async function resolveSkillReferences(input) {
+    const sections = [];
+    const references = [];
+    const unresolvedReferences = [];
+    let remainingTotal = input.remainingTotal;
+    for (const declaration of input.declarations) {
+        const name = referenceDisplayName(declaration);
+        const refPath = declaration.path;
+        if (!isValidReferencePath(refPath)) {
+            unresolvedReferences.push({
+                name,
+                path: refPath,
+                reason: "invalid-path",
+            });
+            continue;
+        }
+        const resolvedPath = normalizeCandidate(path.join(input.skillDir, refPath));
+        if (!isPathWithinDir(resolvedPath, input.skillDir)) {
+            unresolvedReferences.push({
+                name,
+                path: refPath,
+                reason: "invalid-path",
+            });
+            continue;
+        }
+        if (input.resolvedReferencePaths.has(resolvedPath)) {
+            unresolvedReferences.push({
+                name,
+                path: refPath,
+                reason: "already-resolved",
+            });
+            continue;
+        }
+        if (remainingTotal <= 0) {
+            unresolvedReferences.push({
+                name,
+                path: refPath,
+                reason: "budget",
+            });
+            continue;
+        }
+        if (!(await fileExists(resolvedPath))) {
+            unresolvedReferences.push({
+                name,
+                path: refPath,
+                reason: "missing",
+            });
+            continue;
+        }
+        try {
+            const content = await readFile(resolvedPath, "utf-8");
+            const contentSha256 = sha256(content);
+            const bytes = Buffer.byteLength(content, "utf-8");
+            const budget = Math.max(0, Math.min(declaration.maxChars ?? input.perReferenceMaxChars, remainingTotal));
+            const { excerpt, truncated } = truncateReferenceContent(content, budget);
+            input.resolvedReferencePaths.add(resolvedPath);
+            references.push({
+                name,
+                path: resolvedPath,
+                sha256: contentSha256,
+                bytes,
+                ...(truncated ? { truncated: true } : {}),
+            });
+            remainingTotal = Math.max(0, remainingTotal - Math.min(content.length, budget));
+            sections.push([
+                `Reference: ${name}`,
+                `Path: ${resolvedPath}`,
+                `Sha256: ${contentSha256}`,
+                excerpt,
+            ].join("\n"));
+        }
+        catch (error) {
+            unresolvedReferences.push({
+                name,
+                path: refPath,
+                reason: "read-error",
+            });
+        }
+    }
+    return {
+        sections,
+        references,
+        unresolvedReferences,
+        remainingTotal,
+    };
+}
+function buildResolvedPromptText(input) {
+    const truncated = input.content.length > input.maxChars;
+    const excerpt = truncated
+        ? input.content.slice(0, Math.max(0, input.maxChars))
+        : input.content;
+    const instructions = truncated
+        ? `${excerpt}\n[skill instructions truncated at ${input.maxChars} chars]`
+        : excerpt;
+    const lines = [
+        `Skill: ${input.name}`,
+        "Resolution: resolved",
+        `Path: ${input.filePath}`,
+        `Sha256: ${input.contentSha256}`,
+        "Injection mode: bounded-inline",
+        "Instructions:",
+        instructions,
+    ];
+    if (input.referenceSections && input.referenceSections.length > 0) {
+        lines.push("Resolved references:", ...input.referenceSections);
+    }
+    return {
+        truncated,
+        promptText: lines.join("\n"),
+    };
+}
+function buildMissingPromptText(input) {
+    return [
+        `Skill: ${input.name}`,
+        "Resolution: missing",
+        "Searched paths:",
+        ...input.searchedPaths.map((candidate) => `- ${candidate}`),
+        "Injection mode: name-only",
+        "Effect: only the skill name is available; no instructions were loaded.",
+    ].join("\n");
+}
+function buildErrorPromptText(input) {
+    return [
+        `Skill: ${input.name}`,
+        "Resolution: error",
+        `Error: ${input.error}`,
+        "Injection mode: name-only",
+        "Effect: only the skill name is available; no instructions were loaded.",
+    ].join("\n");
+}
+export function skillInstructionMetadata(instructions) {
+    return instructions.map(({ promptText: _promptText, ...metadata }) => metadata);
+}
+export async function resolveDagSkillInstructions(skills, options) {
+    if (skills.length === 0)
+        return [];
+    const env = options.env ?? process.env;
+    const homeDir = options.homeDir ?? os.homedir();
+    const perSkillMaxChars = options.perSkillMaxChars ?? DEFAULT_SKILL_INSTRUCTION_MAX_CHARS;
+    let remainingTotal = options.totalMaxChars ?? DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS;
+    const resolved = [];
+    const resolvedReferencePaths = new Set();
+    for (const name of skills) {
+        if (!SKILL_NAME_PATTERN.test(name)) {
+            const error = `invalid skill name: ${name}`;
+            resolved.push({
+                name,
+                resolution: "error",
+                error,
+                injectionMode: "name-only",
+                promptText: buildErrorPromptText({ name, error }),
+            });
+            continue;
+        }
+        const searchedPaths = buildSkillCandidatePaths({
+            name,
+            cwd: options.cwd,
+            env,
+            homeDir,
+        });
+        const filePath = await findFirstExistingFile(searchedPaths);
+        if (!filePath) {
+            resolved.push({
+                name,
+                resolution: "missing",
+                searchedPaths,
+                injectionMode: "name-only",
+                promptText: buildMissingPromptText({ name, searchedPaths }),
+            });
+            continue;
+        }
+        try {
+            const content = await readFile(filePath, "utf-8");
+            const { frontmatter, body } = splitSkillFrontmatter(content);
+            const instructionContent = frontmatter ? body : content;
+            const referenceDeclarations = frontmatter
+                ? parseSkillReferenceDeclarations(frontmatter)
+                : [];
+            const contentSha256 = sha256(content);
+            const bytes = Buffer.byteLength(content, "utf-8");
+            const budget = Math.max(0, Math.min(perSkillMaxChars, remainingTotal));
+            remainingTotal = Math.max(0, remainingTotal - Math.min(instructionContent.length, budget));
+            const { sections: referenceSections, references, unresolvedReferences, remainingTotal: afterReferences, } = await resolveSkillReferences({
+                declarations: referenceDeclarations,
+                skillDir: path.dirname(filePath),
+                remainingTotal,
+                perReferenceMaxChars: perSkillMaxChars,
+                resolvedReferencePaths,
+            });
+            remainingTotal = afterReferences;
+            const { promptText, truncated } = buildResolvedPromptText({
+                name,
+                filePath,
+                content: instructionContent,
+                contentSha256,
+                bytes,
+                maxChars: budget,
+                referenceSections,
+            });
+            resolved.push({
+                name,
+                resolution: "resolved",
+                path: filePath,
+                sha256: contentSha256,
+                bytes,
+                truncated,
+                injectionMode: "bounded-inline",
+                ...(references.length > 0 ? { references } : {}),
+                ...(unresolvedReferences.length > 0
+                    ? { unresolvedReferences }
+                    : {}),
+                promptText,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            resolved.push({
+                name,
+                resolution: "error",
+                path: filePath,
+                error: message,
+                injectionMode: "name-only",
+                promptText: buildErrorPromptText({ name, error: message }),
+            });
+        }
+    }
+    if (options.includeLearnedPatterns && skills.includes("loop-agent")) {
+        const learned = await resolveLearnedPatternInstructions({
+            cwd: options.cwd,
+            maxChars: Math.max(0, Math.min(perSkillMaxChars, remainingTotal)),
+        });
+        if (learned) {
+            resolved.push(learned);
+        }
+    }
+    return resolved;
+}
+async function findFirstExistingFile(candidates) {
+    for (const candidate of candidates) {
+        if (await fileExists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+async function resolveLearnedPatternInstructions(input) {
+    const repoSlug = path.basename(input.cwd).replace(/[^A-Za-z0-9_-]+/g, "-");
+    const candidates = [
+        normalizeCandidate(path.join(input.cwd, "skills", "loop-agent", "references", "learned", `${repoSlug}.md`)),
+        normalizeCandidate(path.join(input.cwd, "skills", "loop-agent", "references", "learned", "default.md")),
+        normalizeCandidate(path.join(input.cwd, "tools", "loop-agent", "skill", "references", "learned", `${repoSlug}.md`)),
+        normalizeCandidate(path.join(input.cwd, "tools", "loop-agent", "skill", "references", "learned", "default.md")),
+    ];
+    const filePath = await findFirstExistingFile(candidates);
+    if (!filePath)
+        return undefined;
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const selected = selectTopLearnedSections(content, input.maxChars);
+        const contentSha256 = sha256(content);
+        return {
+            name: "loop-agent-learned",
+            resolution: "resolved",
+            path: filePath,
+            sha256: contentSha256,
+            bytes: Buffer.byteLength(content, "utf-8"),
+            truncated: selected.length < content.length,
+            injectionMode: "bounded-inline",
+            promptText: [
+                "Skill: loop-agent-learned",
+                "Resolution: resolved",
+                `Path: ${filePath}`,
+                `Sha256: ${contentSha256}`,
+                "Injection mode: bounded-inline",
+                "Instructions:",
+                "Human-gated learned repair patterns for implementer nodes:",
+                selected || "(empty learned guidance)",
+            ].join("\n"),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: "loop-agent-learned",
+            resolution: "error",
+            path: filePath,
+            error: message,
+            injectionMode: "name-only",
+            promptText: buildErrorPromptText({
+                name: "loop-agent-learned",
+                error: message,
+            }),
+        };
+    }
+}
+function selectTopLearnedSections(content, maxChars) {
+    if (maxChars <= 0)
+        return "";
+    const sections = content
+        .split(/\n(?=##\s+)/)
+        .filter((section) => section.trim().length > 0)
+        .slice(0, 3)
+        .join("\n")
+        .trim();
+    const selected = sections || content.trim();
+    return selected.length > maxChars
+        ? `${selected.slice(0, maxChars)}\n[learned patterns truncated at ${maxChars} chars]`
+        : selected;
+}

package/dist/workflows/dag/skills.js

@@ -0,0 +1,41 @@
+/**
+ * Built-in role skill defaults (prompt-level guidance only; no Pi ResourceLoader).
+ * Applied when a node has a role but the spec omits skillsByRole[role].
+ */
+export const DEFAULT_SKILLS_BY_ROLE = {
+    planner: ["loop-agent"],
+    scout: ["ai-engineering-context"],
+    implementer: ["verification-before-completion"],
+    verifier: ["verification-before-completion", "systematic-debugging"],
+    reviewer: ["requesting-code-review"],
+    supervisor: ["verification-before-completion", "loop-agent"],
+    closeout: ["loop-agent", "verification-before-completion"],
+};
+/**
+ * Resolve prompt-level skills for a DAG node.
+ *
+ * Merge order (first occurrence wins on dedup):
+ *   defaults.skills + skillsByRole[role] + node.skills
+ *
+ * When skillsByRole[role] is absent, built-in role defaults from
+ * DEFAULT_SKILLS_BY_ROLE are used instead.
+ */
+export function resolveDagNodeSkills(spec, task) {
+    const seen = new Set();
+    const resolved = [];
+    const add = (skills) => {
+        for (const skill of skills ?? []) {
+            if (seen.has(skill))
+                continue;
+            seen.add(skill);
+            resolved.push(skill);
+        }
+    };
+    add(spec.defaults?.skills);
+    if (task.role) {
+        const roleSkills = spec.skillsByRole?.[task.role] ?? DEFAULT_SKILLS_BY_ROLE[task.role];
+        add(roleSkills);
+    }
+    add(task.skills);
+    return resolved;
+}

package/dist/workflows/dag/spec.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./validate.js";
+export * from "./governance-constants.js";

package/dist/workflows/dag/topo.js

@@ -0,0 +1,30 @@
+/**
+ * Kahn's algorithm: each rank is the set of nodes with in-degree zero at that step.
+ */
+export function topoSortToRanks(spec) {
+    const inDegree = new Map();
+    for (const task of spec.tasks) {
+        inDegree.set(task.id, task.depends_on.length);
+    }
+    const processed = new Set();
+    const ranks = [];
+    while (processed.size < spec.tasks.length) {
+        const rank = spec.tasks
+            .filter((task) => !processed.has(task.id) && (inDegree.get(task.id) ?? 0) === 0)
+            .map((task) => task.id);
+        if (rank.length === 0) {
+            const remaining = spec.tasks.filter((task) => !processed.has(task.id)).map((task) => task.id);
+            return { ranks, hasCycle: true, cycleNodes: remaining };
+        }
+        ranks.push(rank);
+        for (const id of rank) {
+            processed.add(id);
+            for (const task of spec.tasks) {
+                if (task.depends_on.includes(id)) {
+                    inDegree.set(task.id, (inDegree.get(task.id) ?? 0) - 1);
+                }
+            }
+        }
+    }
+    return { ranks, hasCycle: false, cycleNodes: [] };
+}