@iowarp/clio-coder 0.3.4 → 0.3.7

package/dist/{chunk-VJWL6YS5.js → chunk-UUVG37B4.js}

@@ -7,7 +7,7 @@ import {
   WORKSPACE_EXCLUDED_DIRS,
   enumerateWorkspaceFiles,
   enumerateWorkspaceFilesAsync
-} from "./chunk-EKMEHE4H.js";
+} from "./chunk-33YXPOE3.js";
 import {
   init_esm_shims
 } from "./chunk-3R73A4XB.js";
@@ -241,4 +241,4 @@ export {
   computeFingerprintCached,
   isStale
 };
-//# sourceMappingURL=chunk-VJWL6YS5.js.map
+//# sourceMappingURL=chunk-UUVG37B4.js.map

package/dist/chunk-UVDSQ6LW.js

@@ -0,0 +1,472 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  assertAgentIdNamespace
+} from "./chunk-DR52UMZW.js";
+import {
+  loadSkills
+} from "./chunk-C4JBQ5SR.js";
+import {
+  parseFrontmatter
+} from "./chunk-KCMKRQX4.js";
+import {
+  parseResultContract
+} from "./chunk-DJNLUABN.js";
+import {
+  assertAgentSpecPolicy,
+  isAgentAudience,
+  isAgentCapabilityClass,
+  isAgentCategory,
+  isAgentLatencyClass,
+  isAgentProduct,
+  isAgentProjectContextTier,
+  isShadowAgent,
+  normalizeAgentSpec
+} from "./chunk-AOCYTWAV.js";
+import {
+  clioConfigDir
+} from "./chunk-BNAZZHFG.js";
+import {
+  resolvePackageRoot
+} from "./chunk-IWHMRKLL.js";
+import {
+  init_esm_shims
+} from "./chunk-3R73A4XB.js";
+
+// src/domains/agents/index.ts
+init_esm_shims();
+
+// src/domains/agents/extension.ts
+init_esm_shims();
+import path3 from "node:path";
+
+// src/domains/agents/registry.ts
+init_esm_shims();
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path2 from "node:path";
+
+// src/domains/agents/recipe.ts
+init_esm_shims();
+import path from "node:path";
+var AGENT_BUDGET_KEYS = ["toolCalls", "readReserve", "synthesis", "maximum"];
+function parseAgentBudgetPhase(value, prefix, relationTarget) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${prefix} must be a non-null YAML object`);
+  }
+  const record = value;
+  for (const key of Object.keys(record)) {
+    if (key !== "toolCalls" && key !== "readReserve") throw new Error(`${prefix}.${key} is unknown`);
+  }
+  for (const key of ["toolCalls", "readReserve"]) {
+    if (!Object.hasOwn(record, key)) throw new Error(`${prefix}.${key} is required`);
+  }
+  const toolCalls = record.toolCalls;
+  if (typeof toolCalls !== "number" || !Number.isSafeInteger(toolCalls)) {
+    throw new Error(`${prefix}.toolCalls must be a finite safe integer`);
+  }
+  if (toolCalls <= 0) throw new Error(`${prefix}.toolCalls must be greater than 0`);
+  const readReserve = record.readReserve;
+  if (typeof readReserve !== "number" || !Number.isSafeInteger(readReserve)) {
+    throw new Error(`${prefix}.readReserve must be a finite safe integer`);
+  }
+  if (readReserve < 0) throw new Error(`${prefix}.readReserve must be greater than or equal to 0`);
+  if (readReserve >= toolCalls) throw new Error(`${prefix}.readReserve must be less than ${relationTarget}`);
+  return { toolCalls, readReserve };
+}
+function parseAgentBudget(value, sourcePath) {
+  if (value === void 0) return void 0;
+  const prefix = `agent budget: ${sourcePath}: budget`;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${prefix} must be a non-null YAML object`);
+  }
+  const record = value;
+  for (const key of Object.keys(record)) {
+    if (!AGENT_BUDGET_KEYS.includes(key)) {
+      throw new Error(`${prefix}.${key} is unknown`);
+    }
+  }
+  for (const key of ["toolCalls", "readReserve", "synthesis"]) {
+    if (!Object.hasOwn(record, key)) throw new Error(`${prefix}.${key} is required`);
+  }
+  const phase = parseAgentBudgetPhase(
+    { toolCalls: record.toolCalls, readReserve: record.readReserve },
+    prefix,
+    "budget.toolCalls"
+  );
+  const synthesis = record.synthesis;
+  if (typeof synthesis !== "boolean") throw new Error(`${prefix}.synthesis must be a boolean`);
+  const maximum = record.maximum === void 0 ? void 0 : parseAgentBudgetPhase(record.maximum, `${prefix}.maximum`, "budget.maximum.toolCalls");
+  if (maximum !== void 0) {
+    if (maximum.toolCalls < phase.toolCalls) {
+      throw new Error(`${prefix}.maximum.toolCalls must be greater than or equal to budget.toolCalls`);
+    }
+    if (maximum.readReserve < phase.readReserve) {
+      throw new Error(`${prefix}.maximum.readReserve must be greater than or equal to budget.readReserve`);
+    }
+  }
+  return { ...phase, synthesis, ...maximum === void 0 ? {} : { maximum } };
+}
+function recipeIdFromPath(absPath, rootDir) {
+  const resolvedRoot = path.resolve(rootDir);
+  const resolvedPath = path.resolve(absPath);
+  const relPath = path.relative(resolvedRoot, resolvedPath);
+  if (relPath === "" || relPath.startsWith("..") || path.isAbsolute(relPath)) {
+    throw new Error(`recipe: path must live under rootDir (${resolvedPath} not under ${resolvedRoot})`);
+  }
+  if (path.dirname(relPath) !== ".") {
+    throw new Error(`recipe: recipes must live directly under rootDir (${resolvedPath})`);
+  }
+  if (path.extname(relPath) !== ".md") {
+    throw new Error(`recipe: recipe files must end in .md (${resolvedPath})`);
+  }
+  const id = path.basename(relPath, ".md");
+  if (id === "") {
+    throw new Error(`recipe: recipe filename must not be empty (${resolvedPath})`);
+  }
+  return id;
+}
+
+// src/domains/agents/recipe-schema.ts
+init_esm_shims();
+var RECIPE_KEYS = [
+  "version",
+  "name",
+  "description",
+  "tools",
+  "skills",
+  "audience",
+  "category",
+  "capabilityClass",
+  "latencyClass",
+  "projectContextTier",
+  "budget",
+  "resultContract",
+  "tags"
+];
+var OPTIONAL_RECIPE_KEYS = ["product"];
+var ALL_RECIPE_KEYS = [...RECIPE_KEYS, ...OPTIONAL_RECIPE_KEYS];
+function requiredString(value, path4) {
+  if (typeof value !== "string" || value.trim().length === 0)
+    throw new Error(`agent recipe: ${path4} must be a non-empty string`);
+  return value;
+}
+function requiredStringArray(value, path4) {
+  if (!Array.isArray(value)) throw new Error(`agent recipe: ${path4} must be an array of strings`);
+  const entries = value.map((entry, index) => requiredString(entry, `${path4}[${index}]`));
+  if (new Set(entries).size !== entries.length) throw new Error(`agent recipe: ${path4} must not contain duplicates`);
+  return entries;
+}
+function enumValue(value, path4, predicate) {
+  if (!predicate(value)) throw new Error(`agent recipe: ${path4} has an unsupported value`);
+  return value;
+}
+function parseAudience(value, source, filepath) {
+  const audience = enumValue(value, `${filepath}: audience`, isAgentAudience);
+  if (source === "builtin") {
+    if (audience === "custom") {
+      throw new Error(`agent recipe: ${filepath}: a builtin recipe must not declare audience 'custom'`);
+    }
+    return audience;
+  }
+  if (audience !== "custom") {
+    throw new Error(
+      `agent recipe: ${filepath}: a ${source} recipe must declare audience 'custom', not '${audience}'; audience follows where the recipe was discovered and cannot be claimed in frontmatter`
+    );
+  }
+  return audience;
+}
+function parseTools(value, filepath) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`agent recipe: ${filepath}: tools must be a { required, optional } object`);
+  }
+  const record = value;
+  if (Object.keys(record).some((key) => key !== "required" && key !== "optional")) {
+    throw new Error(`agent recipe: ${filepath}: tools has an unknown key`);
+  }
+  if (!("required" in record) || !("optional" in record)) {
+    throw new Error(`agent recipe: ${filepath}: tools.required and tools.optional are required`);
+  }
+  if (!Array.isArray(record.required) || !Array.isArray(record.optional)) {
+    throw new Error(`agent recipe: ${filepath}: tools.required and tools.optional must be arrays`);
+  }
+  const required = record.required.map((entry, index) => {
+    const entryPath = `${filepath}: tools.required[${index}]`;
+    if (typeof entry === "string") return requiredString(entry, entryPath);
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`agent recipe: ${entryPath} must be a tool name or { anyOf: [...] }`);
+    }
+    const group = entry;
+    if (Object.keys(group).length !== 1 || !("anyOf" in group)) {
+      throw new Error(`agent recipe: ${entryPath} must contain only anyOf`);
+    }
+    const anyOf = requiredStringArray(group.anyOf, `${entryPath}.anyOf`);
+    if (anyOf.length === 0) throw new Error(`agent recipe: ${entryPath}.anyOf must not be empty`);
+    return { anyOf };
+  });
+  const optional = requiredStringArray(record.optional, `${filepath}: tools.optional`);
+  const tools = [
+    ...required.flatMap((requirement) => typeof requirement === "string" ? [requirement] : requirement.anyOf),
+    ...optional
+  ];
+  if (new Set(tools).size !== tools.length)
+    throw new Error(`agent recipe: ${filepath}: tools contains duplicate requirements`);
+  return { tools, toolRequirements: { required, optional } };
+}
+function parseAgentRecipeSchema(input) {
+  const { frontmatter, filepath } = input;
+  for (const key of Object.keys(frontmatter)) {
+    if (!ALL_RECIPE_KEYS.includes(key)) {
+      throw new Error(`agent recipe: ${filepath}: unknown key '${key}'`);
+    }
+  }
+  for (const key of RECIPE_KEYS) {
+    if (!(key in frontmatter)) throw new Error(`agent recipe: ${filepath}: ${key} is required`);
+  }
+  if (frontmatter.version !== 1) throw new Error(`agent recipe: ${filepath}: version must be the supported integer 1`);
+  if (input.body.trim().length === 0) throw new Error(`agent recipe: ${filepath}: persona body must not be empty`);
+  const parsedTools = parseTools(frontmatter.tools, filepath);
+  const budget = parseAgentBudget(frontmatter.budget, filepath);
+  if (budget === void 0) throw new Error(`agent recipe: ${filepath}: budget is required`);
+  return {
+    version: 1,
+    id: input.id,
+    name: requiredString(frontmatter.name, `${filepath}: name`),
+    description: requiredString(frontmatter.description, `${filepath}: description`),
+    tools: parsedTools.tools,
+    toolRequirements: parsedTools.toolRequirements,
+    skills: requiredStringArray(frontmatter.skills, `${filepath}: skills`),
+    boundSkillPaths: [],
+    audience: parseAudience(frontmatter.audience, input.source, filepath),
+    category: enumValue(frontmatter.category, `${filepath}: category`, isAgentCategory),
+    capabilityClass: enumValue(
+      frontmatter.capabilityClass,
+      `${filepath}: capabilityClass`,
+      isAgentCapabilityClass
+    ),
+    latencyClass: enumValue(
+      frontmatter.latencyClass,
+      `${filepath}: latencyClass`,
+      isAgentLatencyClass
+    ),
+    projectContextTier: enumValue(
+      frontmatter.projectContextTier,
+      `${filepath}: projectContextTier`,
+      isAgentProjectContextTier
+    ),
+    budget,
+    resultContract: parseResultContract(frontmatter.resultContract, filepath),
+    // Optional, but not lenient. A misspelled product silently costs the run
+    // the delivery tools its reserve window was supposed to keep, and the
+    // only symptom is a blocked tool call deep in a dispatch log.
+    ...frontmatter.product === void 0 ? {} : { product: enumValue(frontmatter.product, `${filepath}: product`, isAgentProduct) },
+    tags: requiredStringArray(frontmatter.tags, `${filepath}: tags`),
+    source: input.source,
+    filepath,
+    body: input.body
+  };
+}
+
+// src/domains/agents/registry.ts
+var RESERVED_CUSTOM_AGENT_IDS = /* @__PURE__ */ new Set(["worker", "delegate", "auto"]);
+function resolveBoundSkills(recipe, source) {
+  if (recipe.skills.length === 0) return { ...recipe, boundSkillPaths: [] };
+  const packageSkills = path2.resolve(source.dir, "..", "..", "..", "..", "skills");
+  const skills = loadSkills({
+    cwd: process.cwd(),
+    ...source.source === "builtin" && existsSync(packageSkills) ? { explicitSkillPaths: [packageSkills] } : {}
+  });
+  const byName = new Map(skills.items.map((skill) => [skill.name, skill.filePath]));
+  const missing = recipe.skills.filter((skill) => !byName.has(skill));
+  if (missing.length > 0) {
+    throw new Error(`agent recipe: ${recipe.filepath}: bound skill(s) unavailable: ${missing.join(", ")}`);
+  }
+  const boundSkillPaths = recipe.skills.map((skill) => {
+    const filePath = byName.get(skill);
+    if (filePath === void 0) throw new Error(`agent recipe: ${recipe.filepath}: bound skill unavailable: ${skill}`);
+    return filePath;
+  });
+  return { ...recipe, boundSkillPaths };
+}
+function loadRecipesFromDir(source, diagnostics = []) {
+  let entries;
+  try {
+    entries = readdirSync(source.dir, { withFileTypes: true });
+  } catch (err) {
+    const error = err;
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return [];
+    throw err;
+  }
+  const recipes = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const filepath = path2.join(source.dir, entry.name);
+    try {
+      const id = recipeIdFromPath(filepath, source.dir);
+      const raw = readFileSync(filepath, "utf8");
+      const { frontmatter, body } = parseFrontmatter(raw, filepath);
+      const parsedRecipe = parseAgentRecipeSchema({ id, source: source.source, filepath, body, frontmatter });
+      const recipe = resolveBoundSkills(parsedRecipe, source);
+      assertAgentSpecPolicy(normalizeAgentSpec(recipe));
+      recipes.push(recipe);
+    } catch (error) {
+      if (source.source === "builtin") throw error;
+      const message = error instanceof Error ? error.message : String(error);
+      diagnostics.push({ source: source.source, filepath, message });
+      process.stderr.write(`[clio:agents] quarantine path=${filepath} source=${source.source} reason=${message}
+`);
+    }
+  }
+  recipes.sort((left, right) => left.id.localeCompare(right.id));
+  return recipes;
+}
+function mergeRecipes(...sources) {
+  const byId = /* @__PURE__ */ new Map();
+  const builtinById = /* @__PURE__ */ new Map();
+  for (const group of sources) {
+    for (const recipe of group) {
+      if (recipe.source === "builtin") builtinById.set(recipe.id, recipe);
+    }
+  }
+  for (const group of sources) {
+    for (const recipe of group) {
+      if (recipe.source !== "builtin" && RESERVED_CUSTOM_AGENT_IDS.has(recipe.id)) {
+        process.stderr.write(`[clio:agents] ignore id=${recipe.id} by=${recipe.source} reason=reserved-agent-id
+`);
+        continue;
+      }
+      const builtin = builtinById.get(recipe.id);
+      if (recipe.source === "user" && builtin && isShadowAgent(normalizeAgentSpec(builtin))) {
+        process.stderr.write(`[clio:agents] ignore override id=${recipe.id} by=user reason=reserved-shadow
+`);
+        continue;
+      }
+      if (recipe.source === "project" && builtin) {
+        process.stderr.write(`[clio:agents] ignore override id=${recipe.id} by=project reason=reserved-builtin
+`);
+        continue;
+      }
+      if (byId.has(recipe.id)) process.stderr.write(`[clio:agents] override id=${recipe.id} by=${recipe.source}
+`);
+      byId.set(recipe.id, recipe);
+    }
+  }
+  return Array.from(byId.values()).sort((left, right) => left.id.localeCompare(right.id));
+}
+
+// src/domains/agents/extension.ts
+function createAgentsBundle(_context) {
+  let recipes = [];
+  let specs = [];
+  let diagnostics = [];
+  function discover() {
+    const builtinDir = path3.join(resolvePackageRoot(), "src", "domains", "agents", "builtins");
+    const userDir = path3.join(clioConfigDir(), "agents");
+    const projectDir = path3.join(process.cwd(), ".clio-coder", "agents");
+    const nextDiagnostics = [];
+    const builtin = loadRecipesFromDir({ dir: builtinDir, source: "builtin" }, nextDiagnostics);
+    const user = loadRecipesFromDir({ dir: userDir, source: "user" }, nextDiagnostics);
+    const project = loadRecipesFromDir({ dir: projectDir, source: "project" }, nextDiagnostics);
+    const merged = mergeRecipes(builtin, user, project);
+    const config = _context.getContract("config");
+    assertAgentIdNamespace(merged, config?.get()?.delegation?.agents ?? []);
+    recipes = merged;
+    specs = recipes.map(normalizeAgentSpec);
+    diagnostics = nextDiagnostics;
+  }
+  const extension = {
+    async start() {
+      discover();
+    },
+    async stop() {
+    }
+  };
+  const contract = {
+    list() {
+      return recipes;
+    },
+    get(id) {
+      return recipes.find((r) => r.id === id) ?? null;
+    },
+    diagnostics() {
+      return diagnostics.map((diagnostic) => ({ ...diagnostic }));
+    },
+    listSpecs() {
+      const config = _context.getContract("config");
+      const delegationAgents = config?.get()?.delegation?.agents ?? [];
+      const delegationSpecs = delegationAgents.map((agent) => ({
+        version: 1,
+        id: agent.id,
+        name: agent.id,
+        description: `External ACP delegation agent: ${agent.command} ${(agent.args ?? []).join(" ")}`,
+        source: "custom",
+        filepath: "settings.yaml",
+        tools: [],
+        toolRequirements: { required: [], optional: [] },
+        category: "explore",
+        capabilityClass: "orchestration",
+        latencyClass: "deep",
+        projectContextTier: "none",
+        audience: "custom",
+        tags: ["delegation", "acp"],
+        skills: [],
+        resultContract: { kind: "external-delegation" },
+        budget: { toolCalls: 1, readReserve: 0, synthesis: false },
+        body: "External ACP delegation."
+      }));
+      return [...specs, ...delegationSpecs];
+    },
+    getSpec(id) {
+      const found = specs.find((r) => r.id === id);
+      if (found) return found;
+      const config = _context.getContract("config");
+      const agent = config?.get()?.delegation?.agents?.find((entry) => entry.id === id);
+      if (agent) {
+        return {
+          version: 1,
+          id: agent.id,
+          name: agent.id,
+          description: `External ACP delegation agent: ${agent.command} ${(agent.args ?? []).join(" ")}`,
+          source: "custom",
+          filepath: "settings.yaml",
+          tools: [],
+          toolRequirements: { required: [], optional: [] },
+          category: "explore",
+          capabilityClass: "orchestration",
+          latencyClass: "deep",
+          projectContextTier: "none",
+          audience: "custom",
+          tags: ["delegation", "acp"],
+          skills: [],
+          resultContract: { kind: "external-delegation" },
+          budget: { toolCalls: 1, readReserve: 0, synthesis: false },
+          body: "External ACP delegation."
+        };
+      }
+      return null;
+    },
+    reload() {
+      discover();
+    }
+  };
+  return { extension, contract };
+}
+
+// src/domains/agents/manifest.ts
+init_esm_shims();
+var AgentsManifest = {
+  name: "agents",
+  dependsOn: ["config"]
+};
+
+// src/domains/agents/index.ts
+var AgentsDomainModule = {
+  manifest: AgentsManifest,
+  createExtension: createAgentsBundle
+};
+
+export {
+  parseAgentRecipeSchema,
+  loadRecipesFromDir,
+  mergeRecipes,
+  AgentsDomainModule
+};
+//# sourceMappingURL=chunk-UVDSQ6LW.js.map