agent-contracts 0.11.8 → 0.12.0

package/README.md

@@ -998,7 +998,7 @@ Each `context` type provides a different rendering scope:
 
 | Context | Scope | Output | Key variables |
 |---------|-------|--------|---------------|
-| `system` | Single file | `output` as-is | `system`, `dsl` |
+| `system` | Single file | `output` as-is | `system`, `dsl`, `guardrailEnforcement`\*, `bindings`\* |
 | `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` |
@@ -1027,6 +1027,18 @@ Each `context` type provides a different rendering scope:
 * `producerAgents` / `consumerAgents` / `editorAgents` — resolved agent records
 * `createdInWorkflows` — workflow phases where this artifact is written
 
+**`system` context** includes binding-aware guardrail enforcement data when `bindings` and `active_guardrail_policy` are configured:
+
+* `guardrailEnforcement` — array of enforcement entries, each with `guardrail_id`, `description`, `severity`, `action`, scoped entities (`scoped_agents`, `scoped_tasks`, `scoped_workflows`, `scoped_tools`, `scoped_artifacts`), `allow_override`, `override_requires`, `trigger` (from binding matcher type), and `escalation`
+* `bindings` — array of loaded `SoftwareBinding` objects
+
+These fields are only populated when the config specifies `bindings` and `active_guardrail_policy`. Existing templates that do not reference these fields are unaffected.
+
+**Matrix helpers** are available in `context: system` templates:
+
+* `guardrailCoverageMatrix` — generates a Guardrail Coverage Matrix table (guardrail × severity × action × scoped entities × trigger × override × escalation)
+* `taskGuardrailMatrix` — generates a Task × Guardrail cross-reference table showing which action applies to each task
+
 **`tool` context** resolves agent and artifact references:
 
 * `invokableAgents` — agents listed in `invokable_by`

package/dist/cli.js

@@ -53574,8 +53574,52 @@ import { dirname as dirname5 } from "path";
 import Handlebars from "handlebars";
 
 // src/renderer/context.ts
-function buildSystemContext(dsl) {
-  return { system: dsl.system, dsl };
+function buildSystemContext(dsl, options) {
+  const ctx = { system: dsl.system, dsl };
+  if (options?.loadedBindings && options.loadedBindings.length > 0) {
+    ctx.bindings = options.loadedBindings.map((lb) => lb.binding);
+    const policyName = options.activeGuardrailPolicy;
+    const policy = policyName ? dsl.guardrail_policies[policyName] : void 0;
+    if (policy) {
+      ctx.guardrailEnforcement = buildGuardrailEnforcement(dsl, policy, options.loadedBindings);
+    }
+  }
+  return ctx;
+}
+function buildGuardrailEnforcement(dsl, policy, loadedBindings) {
+  const entries = [];
+  const bindingTriggers = /* @__PURE__ */ new Map();
+  for (const lb of loadedBindings) {
+    const impl = lb.binding.guardrail_impl ?? {};
+    for (const [guardrailId, gi] of Object.entries(impl)) {
+      for (const check of gi.checks) {
+        if (check.matcher) {
+          bindingTriggers.set(guardrailId, check.matcher.type);
+        }
+      }
+    }
+  }
+  for (const rule of policy.rules) {
+    const guardrail = dsl.guardrails[rule.guardrail];
+    if (!guardrail) continue;
+    const scope = guardrail.scope ?? {};
+    entries.push({
+      guardrail_id: rule.guardrail,
+      description: guardrail.description,
+      severity: rule.severity,
+      action: rule.action,
+      scoped_agents: scope.agents ?? [],
+      scoped_tasks: scope.tasks ?? [],
+      scoped_workflows: scope.workflows ?? [],
+      scoped_tools: scope.tools ?? [],
+      scoped_artifacts: scope.artifacts ?? [],
+      allow_override: rule.allow_override,
+      override_requires: rule.override_requires ?? [],
+      trigger: bindingTriggers.get(rule.guardrail) ?? null,
+      escalation: rule.escalation ? { target: rule.escalation.target, condition: rule.escalation.condition } : null
+    });
+  }
+  return entries;
 }
 function buildTaskContext(dsl, taskId) {
   const taskDef = dsl.tasks[taskId];
@@ -54630,6 +54674,50 @@ Handlebars.registerHelper(
     return generateOverviewFlowchart(dsl);
   }
 );
+Handlebars.registerHelper(
+  "guardrailCoverageMatrix",
+  function() {
+    const enforcement = this["guardrailEnforcement"];
+    if (!enforcement || enforcement.length === 0) return "";
+    const header = "| Guardrail | Severity | Action | Agents | Tasks | Workflows | Tools | Artifacts | Trigger | Override | Escalation |";
+    const divider = "|-----------|----------|--------|--------|-------|-----------|-------|-----------|---------|----------|------------|";
+    const rows = enforcement.map((e3) => {
+      const agents = e3["scoped_agents"]?.join(", ") || "\u2014";
+      const tasks = e3["scoped_tasks"]?.join(", ") || "\u2014";
+      const workflows = e3["scoped_workflows"]?.join(", ") || "\u2014";
+      const tools = e3["scoped_tools"]?.join(", ") || "\u2014";
+      const artifacts = e3["scoped_artifacts"]?.join(", ") || "\u2014";
+      const trigger = e3["trigger"] || "\u2014";
+      const override = e3["allow_override"] ? "yes" : "no";
+      const esc = e3["escalation"];
+      const escalation = esc ? esc["target"] : "\u2014";
+      return `| ${e3["guardrail_id"]} | ${e3["severity"]} | ${e3["action"]} | ${agents} | ${tasks} | ${workflows} | ${tools} | ${artifacts} | ${trigger} | ${override} | ${escalation} |`;
+    });
+    return [header, divider, ...rows].join("\n");
+  }
+);
+Handlebars.registerHelper(
+  "taskGuardrailMatrix",
+  function() {
+    const dsl = this["dsl"];
+    const enforcement = this["guardrailEnforcement"];
+    if (!dsl || !enforcement || enforcement.length === 0) return "";
+    const taskIds = Object.keys(dsl.tasks);
+    if (taskIds.length === 0) return "";
+    const guardrailIds = enforcement.map((e3) => e3["guardrail_id"]);
+    const header = `| Task | ${guardrailIds.join(" | ")} |`;
+    const divider = `|------|${guardrailIds.map(() => "------").join("|")}|`;
+    const rows = taskIds.map((taskId) => {
+      const cells = enforcement.map((e3) => {
+        const scopedTasks = e3["scoped_tasks"];
+        if (scopedTasks.length > 0 && !scopedTasks.includes(taskId)) return "n/a";
+        return e3["action"];
+      });
+      return `| ${taskId} | ${cells.join(" | ")} |`;
+    });
+    return [header, divider, ...rows].join("\n");
+  }
+);
 function getDslSection(dsl, context) {
   const sectionMap = {
     agent: dsl.agents,
@@ -54694,13 +54782,13 @@ async function removeIfExists(filePath) {
   } catch {
   }
 }
-async function renderFromConfig(dsl, renderTargets) {
+async function renderFromConfig(dsl, renderTargets, options) {
   const outputFiles = [];
   for (const target of renderTargets) {
     const templateContent = await loadTemplate(target.template);
     const compiled = Handlebars.compile(templateContent, { noEscape: false });
     if (target.context === "system") {
-      const ctx = buildSystemContext(dsl);
+      const ctx = buildSystemContext(dsl, options);
       const output = compiled(ctx);
       if (target.skip_empty && isEffectivelyEmpty(output)) {
         await removeIfExists(target.output);
@@ -54749,13 +54837,13 @@ function checkExpectedVsExisting(expected, outputPath, skipEmpty, diffs) {
     diffs.push(outputPath);
   });
 }
-async function checkDriftFromConfig(dsl, renderTargets) {
+async function checkDriftFromConfig(dsl, renderTargets, options) {
   const diffs = [];
   for (const target of renderTargets) {
     const templateContent = await loadTemplate(target.template);
     const compiled = Handlebars.compile(templateContent, { noEscape: false });
     if (target.context === "system") {
-      const ctx = buildSystemContext(dsl);
+      const ctx = buildSystemContext(dsl, options);
       const expected = compiled(ctx);
       await checkExpectedVsExisting(expected, target.output, target.skip_empty, diffs);
     } else {
@@ -54793,10 +54881,19 @@ var renderCommand = new Command4("render").description("Render resolved DSL with
         );
         process.exit(1);
       }
+      let renderOptions;
+      if (config.bindings.length > 0) {
+        const loadedBindings = await loadBindings(config.bindings);
+        renderOptions = {
+          loadedBindings,
+          activeGuardrailPolicy: config.activeGuardrailPolicy
+        };
+      }
       if (opts.check) {
         const drift = await checkDriftFromConfig(
           schemaResult.data,
-          config.renders
+          config.renders,
+          renderOptions
         );
         if (drift.hasDrift) {
           process.stderr.write("Drift detected in the following files:\n");
@@ -54812,7 +54909,8 @@ var renderCommand = new Command4("render").description("Render resolved DSL with
       } else {
         const files = await renderFromConfig(
           schemaResult.data,
-          config.renders
+          config.renders,
+          renderOptions
         );
         if (!opts.quiet) {
           process.stdout.write(`Rendered ${files.length} file(s):