agent-contracts 0.6.0 → 0.7.0

package/README.md

@@ -244,6 +244,7 @@ Design regressions become testable.
 * **Structured handoff definitions**
 * **Artifact ownership and lifecycle modeling**
 * **Config-driven prompt rendering**
+* **Variable substitution** via `${vars.xxx}` in DSL values
 * **Inheritance with merge operators via `extends`**
 * **Flexible file splitting** via `$ref` (replacement) and `$refs` (import + deep-merge)
 * **JSON Schema for editor support and external tooling**
@@ -533,6 +534,67 @@ Supported merge operators:
 
 ---
 
+## Variable substitution
+
+When using `extends` to share a base DSL across projects, base definitions often contain values that differ per project (project name, language, repository URL, etc.).
+
+`vars` in `agent-contracts.config.yaml` lets you define project-specific values that are substituted into DSL string values using `${vars.xxx}` syntax.
+
+### Defining vars
+
+Add a `vars` section to your config file. Values must be flat string key-value pairs.
+
+````yaml
+# agent-contracts.config.yaml
+vars:
+  project_name: "my-service"
+  language: "TypeScript"
+  repo_url: "https://github.com/org/my-service"
+````
+
+### Using placeholders in DSL
+
+Use `${vars.<key>}` in any string value within the DSL YAML (base or project).
+
+````yaml
+# base/agent-contracts.yaml
+agents:
+  implementer:
+    purpose: "Implements features for ${vars.project_name}"
+    constraints:
+      - "Use ${vars.language} for all implementations"
+      - "Repository: ${vars.repo_url}"
+````
+
+### Processing order
+
+Variable substitution happens **after** DSL resolution (`extends` merge) and **before** schema validation:
+
+1. Load config (including `vars`)
+2. Resolve DSL (load + merge `extends`)
+3. Substitute `${vars.xxx}` in all string values
+4. Validate schema
+5. Render / lint / check
+
+This ensures that merged strings from both base and project are substituted, and the resulting values pass schema validation.
+
+### Error handling
+
+If a placeholder references an undefined variable, the command exits with an error:
+
+````
+VarsSubstitutionError: Undefined variable "repo_url" in value "Repository: ${vars.repo_url}"
+  Defined vars: project_name, language
+````
+
+### Notes
+
+- Only string values are substituted; object keys are not affected.
+- `vars` is optional. If omitted, no substitution occurs.
+- Patterns that do not match `${vars.<key>}` (e.g. `${env.HOME}`, `$vars.xxx`, `{{vars.xxx}}`) are left unchanged.
+
+---
+
 ## CLI
 
 ### Installation
@@ -576,6 +638,11 @@ Rendering is configured via `agent-contracts.config.yaml`.
 ````yaml
 dsl: ./agent-contracts.yaml
 
+vars:
+  project_name: "my-service"
+  language: "TypeScript"
+  repo_url: "https://github.com/org/my-service"
+
 renders:
   - template: ./templates/agent-prompt.md.hbs
     context: agent
@@ -597,6 +664,67 @@ This lets you generate static outputs for:
 
 all from the same resolved DSL.
 
+### Available context types
+
+Each `context` type provides a different rendering scope:
+
+| Context | Scope | Output | Key variables |
+|---------|-------|--------|---------------|
+| `system` | Single file | `output` as-is | `system`, `dsl` |
+| `agent` | Per agent | `{agent.id}` in output path | `agent`, `receivableTasks`, `delegatableTasks`, `relatedArtifacts`, `relatedTools`, `relatedHandoffTypes`, `mergedBehavior`, `dsl` |
+| `task` | Per task | `{task.id}` in output path | `task`, `targetAgent`, `dsl` |
+| `artifact` | Per artifact | `{artifact.id}` in output path | `artifact`, `relatedTools`, `relatedValidations`, `producerAgents`, `consumerAgents`, `editorAgents`, `createdInWorkflows`, `dsl` |
+| `tool` | Per tool | `{tool.id}` in output path | `tool`, `invokableAgents`, `inputArtifactDetails`, `outputArtifactDetails`, `dsl` |
+| `validation` | Per validation | `{validation.id}` in output path | `validation`, `dsl` |
+| `handoff_type` | Per handoff type | `{handoff_type.id}` in output path | `handoff_type`, `relatedTasks`, `dsl` |
+| `workflow` | Per workflow phase | `{workflow.id}` in output path | `workflow`, `relatedAgents`, `relatedTasks`, `relatedTools`, `relatedArtifacts`, `relatedValidations`, `dsl` |
+| `policy` | Per policy | `{policy.id}` in output path | `policy`, `dsl` |
+
+#### Enriched context details
+
+**`workflow` context** collects all entities involved in a phase:
+
+* `relatedTasks` — tasks where `task.workflow` matches this phase
+* `relatedAgents` — agents from task `target_agent`, `allowed_from_agents`, step `from_agent`, and validation executors
+* `relatedTools` — tools from `can_execute_tools` of all related agents
+* `relatedArtifacts` — artifacts from `can_read_artifacts`, `can_write_artifacts`, and `input_artifacts`
+* `relatedValidations` — validations referenced in workflow steps
+
+**`artifact` context** provides ownership and cross-reference data:
+
+* `relatedTools` — tools with this artifact in `input_artifacts` or `output_artifacts`
+* `relatedValidations` — validations targeting this artifact
+* `producerAgents` / `consumerAgents` / `editorAgents` — resolved agent records
+* `createdInWorkflows` — workflow phases where this artifact is written
+
+**`tool` context** resolves agent and artifact references:
+
+* `invokableAgents` — agents listed in `invokable_by`
+* `inputArtifactDetails` / `outputArtifactDetails` — resolved artifact records
+
+### Handlebars helpers
+
+Templates can use these built-in helpers:
+
+| Helper | Usage | Description |
+|--------|-------|-------------|
+| `eq` | `{{#if (eq a b)}}` | Strict equality |
+| `notEmpty` | `{{#if (notEmpty obj)}}` | True when object has at least one key |
+| `inc` | `{{inc @index}}` | Increment number by 1 (for 1-based indexing) |
+| `yamlBlock` | `{{{yamlBlock obj}}}` | Render value as YAML-formatted text |
+| `lookupPayloadFields` | `{{#each (lookupPayloadFields payload)}}` | Extract payload field info (name, type, required, enum) |
+| `join` | `{{join arr ", "}}` | Join array elements with separator |
+| `contains` | `{{#if (contains arr "x")}}` | True when array includes value |
+| `groupBy` | `{{#with (groupBy arr "key")}}` | Group array elements by field value |
+| `filterByField` | `{{#each (filterByField arr "field" "val")}}` | Filter array by field match |
+| `keys` | `{{#each (keys obj)}}` | Object keys as array |
+| `values` | `{{#each (values obj)}}` | Object values as array |
+| `size` | `{{size obj}}` | Array length or object key count |
+| `not` | `{{#if (not x)}}` | Boolean negation |
+| `or` | `{{#if (or a b)}}` | Boolean OR (variadic) |
+| `and` | `{{#if (and a b)}}` | Boolean AND (variadic) |
+| `gt` / `gte` / `lt` | `{{#if (gt a b)}}` | Numeric comparisons |
+
 ---
 
 ## Validation model

package/dist/cli.js

@@ -11927,7 +11927,7 @@ var require_getJsonPathForPosition = __commonJS({
         return;
       return path;
     };
-    function* walk(node) {
+    function* walk2(node) {
       switch (node.kind) {
         case types_1.Kind.MAP:
           if (node.mappings.length !== 0) {
@@ -11988,7 +11988,7 @@ var require_getJsonPathForPosition = __commonJS({
       return node;
     }
     function findClosestScalar(container, offset, line, lineMap) {
-      for (const node of walk(container)) {
+      for (const node of walk2(container)) {
         if (node.startPosition <= offset && offset <= node.endPosition) {
           return node.kind === types_1.Kind.SCALAR ? node : findClosestScalar(node, offset, line, lineMap);
         }
@@ -58342,6 +58342,7 @@ var RenderTargetSchema = z.object({
 );
 var AgentContractsConfigSchema = z.object({
   dsl: z.string(),
+  vars: z.record(z.string(), z.string()).optional(),
   renders: z.array(RenderTargetSchema).min(1)
 });
 
@@ -58410,6 +58411,7 @@ ${issues}`,
   const config = result.data;
   return {
     dsl: resolve(configDir, config.dsl),
+    vars: config.vars,
     renders: config.renders.map((r3) => ({
       ...r3,
       template: resolve(configDir, r3.template),
@@ -58980,6 +58982,50 @@ async function resolve4(projectDirOrFile) {
   };
 }
 
+// src/resolver/substitute-vars.ts
+var VAR_PATTERN = /\$\{vars\.([a-zA-Z0-9_-]+)\}/g;
+var VarsSubstitutionError = class extends Error {
+  constructor(varName, sourceValue, definedVars) {
+    const defined = definedVars.length > 0 ? definedVars.join(", ") : "(none)";
+    super(
+      `Undefined variable "${varName}" in value "${sourceValue}"
+  Defined vars: ${defined}`
+    );
+    this.varName = varName;
+    this.sourceValue = sourceValue;
+    this.definedVars = definedVars;
+    this.name = "VarsSubstitutionError";
+  }
+  varName;
+  sourceValue;
+  definedVars;
+};
+function substituteString(value, vars) {
+  return value.replace(VAR_PATTERN, (match, varName) => {
+    if (!(varName in vars)) {
+      throw new VarsSubstitutionError(varName, value, Object.keys(vars));
+    }
+    return vars[varName];
+  });
+}
+function walk(data, vars) {
+  if (typeof data === "string") return substituteString(data, vars);
+  if (Array.isArray(data)) return data.map((item) => walk(item, vars));
+  if (data !== null && typeof data === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(
+      data
+    )) {
+      result[key] = walk(value, vars);
+    }
+    return result;
+  }
+  return data;
+}
+function substituteVars(data, vars) {
+  return walk(data, vars);
+}
+
 // src/cli/commands/resolve.ts
 import { stringify } from "yaml";
 var DIR_DEFAULT = "agent-contracts.yaml";
@@ -58988,10 +59034,11 @@ var resolveCommand = new Command("resolve").description("Resolve DSL (load + mer
     const config = await loadConfig(opts.config);
     const dslPath = resolveDslPath(dir, DIR_DEFAULT, config);
     const result = await resolve4(dslPath);
+    const data = config?.vars ? substituteVars(result.data, config.vars) : result.data;
     if (opts.format === "json") {
-      process.stdout.write(JSON.stringify(result.data, null, 2) + "\n");
+      process.stdout.write(JSON.stringify(data, null, 2) + "\n");
     } else {
-      process.stdout.write(stringify(result.data));
+      process.stdout.write(stringify(data));
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -59512,7 +59559,8 @@ var validateCommand = new Command2("validate").description("Validate DSL against
     const config = await loadConfig(opts.config);
     const dslPath = resolveDslPath(dir, DIR_DEFAULT2, config);
     const resolved = await resolve4(dslPath);
-    const schemaResult = validateSchema(resolved.data);
+    const data = config?.vars ? substituteVars(resolved.data, config.vars) : resolved.data;
+    const schemaResult = validateSchema(data);
     if (!schemaResult.success) {
       const output = formatDiagnostics(schemaResult.diagnostics, opts);
       if (output) process.stderr.write(output + "\n");
@@ -60376,7 +60424,8 @@ var lintCommand = new Command3("lint").description("Run semantic lint rules on r
       const config = await loadConfig(opts.config);
       const dslPath = resolveDslPath(dir, DIR_DEFAULT3, config);
       const resolved = await resolve4(dslPath);
-      const schemaResult = validateSchema(resolved.data);
+      const data = config?.vars ? substituteVars(resolved.data, config.vars) : resolved.data;
+      const schemaResult = validateSchema(data);
       if (!schemaResult.success) {
         const output = formatDiagnostics(schemaResult.diagnostics, {
           format: opts.format,
@@ -60434,12 +60483,76 @@ function buildTaskContext(dsl, taskId) {
 function buildArtifactContext(dsl, artifactId) {
   const artifactDef = dsl.artifacts[artifactId];
   const artifact = { ...artifactDef, id: artifactId };
-  return { artifact, dsl };
+  const relatedTools = {};
+  for (const [id, tool] of Object.entries(dsl.tools)) {
+    if (tool.input_artifacts.includes(artifactId) || tool.output_artifacts.includes(artifactId)) {
+      relatedTools[id] = tool;
+    }
+  }
+  const relatedValidations = {};
+  for (const [id, val] of Object.entries(dsl.validations)) {
+    if (val.target_artifact === artifactId) {
+      relatedValidations[id] = val;
+    }
+  }
+  const pickAgents = (ids) => {
+    const result = {};
+    for (const id of ids) {
+      if (dsl.agents[id]) result[id] = dsl.agents[id];
+    }
+    return result;
+  };
+  const producerAgents = pickAgents(artifactDef.producers);
+  const consumerAgents = pickAgents(artifactDef.consumers);
+  const editorAgents = pickAgents(artifactDef.editors);
+  const createdInWorkflows = [];
+  for (const [_taskId, task] of Object.entries(dsl.tasks)) {
+    if (createdInWorkflows.includes(task.workflow)) continue;
+    const targetAgent = dsl.agents[task.target_agent];
+    if (targetAgent?.can_write_artifacts.includes(artifactId)) {
+      createdInWorkflows.push(task.workflow);
+      continue;
+    }
+    const steps = task.execution_steps ?? [];
+    for (const step of steps) {
+      if (step["produces_artifact"] === artifactId) {
+        createdInWorkflows.push(task.workflow);
+        break;
+      }
+    }
+  }
+  return {
+    artifact,
+    relatedTools,
+    relatedValidations,
+    producerAgents,
+    consumerAgents,
+    editorAgents,
+    createdInWorkflows,
+    dsl
+  };
 }
 function buildToolContext(dsl, toolId) {
   const toolDef = dsl.tools[toolId];
   const tool = { ...toolDef, id: toolId };
-  return { tool, dsl };
+  const invokableAgents = {};
+  for (const agentId of toolDef.invokable_by) {
+    if (dsl.agents[agentId]) invokableAgents[agentId] = dsl.agents[agentId];
+  }
+  const pickArtifacts = (ids) => {
+    const result = {};
+    for (const id of ids) {
+      if (dsl.artifacts[id]) result[id] = dsl.artifacts[id];
+    }
+    return result;
+  };
+  return {
+    tool,
+    invokableAgents,
+    inputArtifactDetails: pickArtifacts(toolDef.input_artifacts),
+    outputArtifactDetails: pickArtifacts(toolDef.output_artifacts),
+    dsl
+  };
 }
 function buildValidationContext(dsl, validationId) {
   const validationDef = dsl.validations[validationId];
@@ -60457,7 +60570,76 @@ function buildHandoffTypeContext(dsl, handoffTypeId) {
 function buildWorkflowContext(dsl, workflowId) {
   const wfDef = dsl.workflow[workflowId];
   const workflow = { ...wfDef, id: workflowId };
-  return { workflow, dsl };
+  const relatedTasks = Object.entries(dsl.tasks).filter(([, t3]) => t3.workflow === workflowId).map(([id, t3]) => ({ ...t3, id }));
+  const agentIds = /* @__PURE__ */ new Set();
+  for (const task of relatedTasks) {
+    agentIds.add(task.target_agent);
+    for (const fromAgent of task.allowed_from_agents) {
+      agentIds.add(fromAgent);
+    }
+  }
+  for (const step of wfDef.steps) {
+    if (step.type === "handoff" && step.from_agent) {
+      agentIds.add(step.from_agent);
+    }
+    if (step.type === "validation") {
+      const val = dsl.validations[step.validation];
+      if (val?.executor_type === "agent" && val.executor) {
+        agentIds.add(val.executor);
+      }
+    }
+  }
+  const relatedAgents = {};
+  for (const id of agentIds) {
+    if (dsl.agents[id]) relatedAgents[id] = dsl.agents[id];
+  }
+  const toolIds = /* @__PURE__ */ new Set();
+  for (const id of agentIds) {
+    const agent = dsl.agents[id];
+    if (agent) {
+      for (const toolId of agent.can_execute_tools) {
+        toolIds.add(toolId);
+      }
+    }
+  }
+  const relatedTools = {};
+  for (const id of toolIds) {
+    if (dsl.tools[id]) relatedTools[id] = dsl.tools[id];
+  }
+  const artifactIds = /* @__PURE__ */ new Set();
+  for (const task of relatedTasks) {
+    for (const artId of task.input_artifacts) artifactIds.add(artId);
+  }
+  for (const id of agentIds) {
+    const agent = dsl.agents[id];
+    if (agent) {
+      for (const artId of agent.can_read_artifacts) artifactIds.add(artId);
+      for (const artId of agent.can_write_artifacts) artifactIds.add(artId);
+    }
+  }
+  const relatedArtifacts = {};
+  for (const id of artifactIds) {
+    if (dsl.artifacts[id]) relatedArtifacts[id] = dsl.artifacts[id];
+  }
+  const validationIds = /* @__PURE__ */ new Set();
+  for (const step of wfDef.steps) {
+    if (step.type === "validation") {
+      validationIds.add(step.validation);
+    }
+  }
+  const relatedValidations = {};
+  for (const id of validationIds) {
+    if (dsl.validations[id]) relatedValidations[id] = dsl.validations[id];
+  }
+  return {
+    workflow,
+    relatedAgents,
+    relatedTasks,
+    relatedTools,
+    relatedArtifacts,
+    relatedValidations,
+    dsl
+  };
 }
 function buildPolicyContext(dsl, policyId) {
   const policyDef = dsl.policies[policyId];
@@ -60572,6 +60754,11 @@ function buildPerAgentContext(dsl, agent) {
 
 // src/renderer/renderer.ts
 Handlebars.registerHelper("eq", (a3, b3) => a3 === b3);
+Handlebars.registerHelper("notEmpty", (obj) => {
+  if (!obj || typeof obj !== "object") return false;
+  return Object.keys(obj).length > 0;
+});
+Handlebars.registerHelper("inc", (val) => val + 1);
 Handlebars.registerHelper(
   "lookupPayloadFields",
   (payload) => {
@@ -60660,6 +60847,72 @@ function toYamlLines(obj, indent) {
 Handlebars.registerHelper("yamlBlock", (obj) => {
   return toYamlLines(obj, 0).join("\n");
 });
+Handlebars.registerHelper(
+  "join",
+  (arr, separator) => {
+    if (!Array.isArray(arr)) return "";
+    const sep = typeof separator === "string" ? separator : ", ";
+    return arr.join(sep);
+  }
+);
+Handlebars.registerHelper("contains", (arr, value) => {
+  if (!Array.isArray(arr)) return false;
+  return arr.includes(value);
+});
+Handlebars.registerHelper(
+  "groupBy",
+  (arr, key) => {
+    if (!Array.isArray(arr)) return {};
+    const result = {};
+    for (const item of arr) {
+      const k2 = String(
+        item?.[key] ?? "undefined"
+      );
+      (result[k2] ??= []).push(item);
+    }
+    return result;
+  }
+);
+Handlebars.registerHelper(
+  "keys",
+  (obj) => {
+    if (!obj || typeof obj !== "object") return [];
+    return Object.keys(obj);
+  }
+);
+Handlebars.registerHelper(
+  "values",
+  (obj) => {
+    if (!obj || typeof obj !== "object") return [];
+    return Object.values(obj);
+  }
+);
+Handlebars.registerHelper(
+  "filterByField",
+  (arr, field, value) => {
+    if (!Array.isArray(arr)) return [];
+    return arr.filter(
+      (item) => item?.[field] === value
+    );
+  }
+);
+Handlebars.registerHelper("not", (value) => !value);
+Handlebars.registerHelper("or", (...args) => {
+  const _options = args.pop();
+  return args.some((a3) => !!a3);
+});
+Handlebars.registerHelper("and", (...args) => {
+  const _options = args.pop();
+  return args.every((a3) => !!a3);
+});
+Handlebars.registerHelper("gt", (a3, b3) => a3 > b3);
+Handlebars.registerHelper("gte", (a3, b3) => a3 >= b3);
+Handlebars.registerHelper("lt", (a3, b3) => a3 < b3);
+Handlebars.registerHelper("size", (obj) => {
+  if (Array.isArray(obj)) return obj.length;
+  if (obj && typeof obj === "object") return Object.keys(obj).length;
+  return 0;
+});
 function getDslSection(dsl, context) {
   const sectionMap = {
     agent: dsl.agents,
@@ -60782,7 +61035,8 @@ var renderCommand = new Command4("render").description("Render resolved DSL with
         process.exit(1);
       }
       const resolved = await resolve4(config.dsl);
-      const schemaResult = validateSchema(resolved.data);
+      const data = config.vars ? substituteVars(resolved.data, config.vars) : resolved.data;
+      const schemaResult = validateSchema(data);
       if (!schemaResult.success) {
         process.stderr.write(
           "Schema validation failed. Run 'agent-contracts validate' for details.\n"
@@ -60847,7 +61101,8 @@ var checkCommand = new Command5("check").description("Run full pipeline: resolve
         process.exit(1);
       }
       const resolved = await resolve4(config.dsl);
-      const schemaResult = validateSchema(resolved.data);
+      const data = config.vars ? substituteVars(resolved.data, config.vars) : resolved.data;
+      const schemaResult = validateSchema(data);
       if (!schemaResult.success) {
         const output = formatDiagnostics(schemaResult.diagnostics, {
           format: opts.format,