@autohq/cli 0.1.478 → 0.1.479

package/dist/agent-bridge.js

@@ -30866,7 +30866,7 @@ Object.assign(lookup, {
 // package.json
 var package_default = {
   name: "@autohq/cli",
-  version: "0.1.478",
+  version: "0.1.479",
   license: "SEE LICENSE IN README.md",
   publishConfig: {
     access: "public"
@@ -38169,8 +38169,10 @@ var SpendCapRuntimeErrorResponseSchema = external_exports.object({
   issues: external_exports.array(external_exports.unknown()).optional()
 });
 
-// ../../packages/schemas/src/templates/public-source.ts
+// ../../packages/schemas/src/templates/variable-contract.ts
 var import_yaml = __toESM(require_dist(), 1);
+
+// ../../packages/schemas/src/templates/public-source.ts
 var MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN = "https://www.auto.sh";
 var MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH = "/api/v1/templates";
 var SOURCE_COMMENT_PREFIX = `# Source: ${MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN}${MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH}/`;

package/dist/index.js

@@ -22590,12 +22590,70 @@ var init_content_source = __esm({
   }
 });
 
-// ../../packages/schemas/src/templates/public-source.ts
+// ../../packages/schemas/src/templates/variable-contract.ts
 import { parseAllDocuments } from "yaml";
+function readTemplateVariableContract(document, path2) {
+  const value = document.templateVariables;
+  if (value === void 0) {
+    return { declared: false, required: /* @__PURE__ */ new Set(), optional: /* @__PURE__ */ new Set() };
+  }
+  if (!isRecord(value)) {
+    throw new Error(
+      `Invalid templateVariables in ${path2}: expected a map with required and optional lists`
+    );
+  }
+  const required2 = readVariableNames(value.required, "required", path2);
+  const optional2 = readVariableNames(value.optional, "optional", path2);
+  const overlap = [...required2].filter((name) => optional2.has(name)).sort();
+  if (overlap.length > 0) {
+    throw new Error(
+      `Invalid templateVariables in ${path2}: variables cannot be both required and optional (${overlap.join(", ")})`
+    );
+  }
+  return { declared: true, required: required2, optional: optional2 };
+}
+function readVariableNames(value, kind, path2) {
+  if (value === void 0) {
+    return /* @__PURE__ */ new Set();
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `Invalid templateVariables.${kind} in ${path2}: expected a list of variable names`
+    );
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const name of value) {
+    if (typeof name !== "string" || !VARIABLE_NAME_PATTERN.test(name)) {
+      throw new Error(
+        `Invalid templateVariables.${kind} in ${path2}: names must match [A-Za-z_][A-Za-z0-9_]*`
+      );
+    }
+    if (names.has(name)) {
+      throw new Error(
+        `Invalid templateVariables.${kind} in ${path2}: duplicate variable ${name}`
+      );
+    }
+    names.add(name);
+  }
+  return names;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var VARIABLE_NAME_PATTERN;
+var init_variable_contract = __esm({
+  "../../packages/schemas/src/templates/variable-contract.ts"() {
+    "use strict";
+    VARIABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+  }
+});
+
+// ../../packages/schemas/src/templates/public-source.ts
 var MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN, MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH, SOURCE_COMMENT_PREFIX;
 var init_public_source = __esm({
   "../../packages/schemas/src/templates/public-source.ts"() {
     "use strict";
+    init_variable_contract();
     MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN = "https://www.auto.sh";
     MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH = "/api/v1/templates";
     SOURCE_COMMENT_PREFIX = `# Source: ${MANAGED_TEMPLATE_PUBLIC_SOURCE_ORIGIN}${MANAGED_TEMPLATE_PUBLIC_SOURCE_PATH}/`;
@@ -54702,6 +54760,7 @@ var init_templates = __esm({
     init_hardcoded();
     init_subscription();
     init_catalog();
+    init_variable_contract();
   }
 });
 
@@ -57700,7 +57759,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@autohq/cli",
-      version: "0.1.478",
+      version: "0.1.479",
       license: "SEE LICENSE IN README.md",
       publishConfig: {
         access: "public"
@@ -57961,7 +58020,7 @@ function compileAgentDocument(document, path2, stack, context) {
       `Agent import cycle detected: ${[...stack, resolvedPath].join(" -> ")}`
     );
   }
-  if (!isRecord2(document)) {
+  if (!isRecord3(document)) {
     throw new Error(`Invalid agent authoring file ${path2}: expected object`);
   }
   const imports = importPaths(document).map(
@@ -58086,25 +58145,25 @@ function authoringDocumentApplyShape(document, path2) {
   };
 }
 function finalizeAgentApplyShape(document, path2) {
-  if (!isRecord2(document) || !isRecord2(document.spec)) {
+  if (!isRecord3(document) || !isRecord3(document.spec)) {
     return { resource: document, resources: [] };
   }
   const next = structuredClone(document);
   const spec = next.spec;
   const resources = [];
-  if (isRecord2(spec.environment)) {
+  if (isRecord3(spec.environment)) {
     const environment = inlineEnvironmentResource(spec.environment, path2);
     spec.environment = environment.metadata.name;
     resources.push(environment);
   }
-  if (isRecord2(spec.identity)) {
+  if (isRecord3(spec.identity)) {
     const identity2 = inlineIdentityResource(spec.identity, next, path2);
     spec.identity = identity2.metadata.name;
     resources.push(identity2);
   }
   if (Array.isArray(spec.triggers)) {
     spec.triggers = spec.triggers.map((trigger) => {
-      if (!isRecord2(trigger) || !("name" in trigger)) {
+      if (!isRecord3(trigger) || !("name" in trigger)) {
         return trigger;
       }
       const compiledTrigger = { ...trigger };
@@ -58152,7 +58211,7 @@ function inlineIdentityResource(document, agentDocument, path2) {
     }
     spec[key] = value;
   }
-  if (metadata.name === void 0 && isRecord2(agentDocument.metadata) && typeof agentDocument.metadata.name === "string") {
+  if (metadata.name === void 0 && isRecord3(agentDocument.metadata) && typeof agentDocument.metadata.name === "string") {
     metadata.name = agentDocument.metadata.name;
   }
   const parsed = IdentityApplyRequestSchema.safeParse({ metadata, spec });
@@ -58188,7 +58247,7 @@ function resolveFileBackedFields(spec, path2) {
   };
 }
 function resolveFileBackedString(value, input) {
-  if (!isRecord2(value) || !("file" in value)) {
+  if (!isRecord3(value) || !("file" in value)) {
     return value;
   }
   const file2 = value.file;
@@ -58206,8 +58265,8 @@ function resolveFileBackedString(value, input) {
   return readFileSync8(resolve3(dirname8(input.path), filePath), "utf8");
 }
 function removalDirectives(document, path2) {
-  const raw = isRecord2(document.remove) ? document.remove : {};
-  if (!isRecord2(raw)) {
+  const raw = isRecord3(document.remove) ? document.remove : {};
+  if (!isRecord3(raw)) {
     return [];
   }
   const directives = [];
@@ -58229,18 +58288,18 @@ function stringList(value, label) {
   });
 }
 function applyRemoval(value, removal) {
-  if (!isRecord2(value)) {
+  if (!isRecord3(value)) {
     return value;
   }
   const next = structuredClone(value);
-  if (!isRecord2(next.spec)) {
+  if (!isRecord3(next.spec)) {
     return next;
   }
   const spec = { ...next.spec };
   next.spec = spec;
   switch (removal.target) {
     case "tools": {
-      if (!isRecord2(spec[removal.target])) {
+      if (!isRecord3(spec[removal.target])) {
         return next;
       }
       const collection = {
@@ -58284,7 +58343,7 @@ function mergeValues2(base, override, path2) {
   if (Array.isArray(base) && Array.isArray(override)) {
     return mergeArrays(base, override, path2);
   }
-  if (isRecord2(base) && isRecord2(override)) {
+  if (isRecord3(base) && isRecord3(override)) {
     const merged = { ...base };
     for (const [key, value] of Object.entries(override)) {
       merged[key] = mergeValues2(merged[key], value, [...path2, key]);
@@ -58327,7 +58386,7 @@ function isNamedArrayMergePath(path2) {
   return path2 === "spec.mounts" || path2 === "spec.triggers";
 }
 function collectionItemKey(collection, item) {
-  if (!isRecord2(item)) {
+  if (!isRecord3(item)) {
     return void 0;
   }
   if (typeof item.name === "string") {
@@ -58359,7 +58418,7 @@ function isAgentFile(path2) {
     return false;
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var AGENT_FILE_EXTENSIONS, AGENT_SPEC_FIELDS, AGENT_METADATA_FIELDS;
@@ -58768,7 +58827,7 @@ function sourceFileIndex(files) {
 function isAbsoluteSourcePath(path2) {
   return path2.startsWith("/");
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var APPLY_DIRECTORIES, PROJECT_APPLY_RESOURCE_DIRECTORIES;
@@ -58847,7 +58906,7 @@ function resolveTemplateImportPath(importPath, fileIndex) {
   return key;
 }
 function removalDirectives2(document, path2) {
-  const raw = isRecord3(document.remove) ? document.remove : {};
+  const raw = isRecord4(document.remove) ? document.remove : {};
   const directives = [];
   for (const [target, value] of Object.entries(raw)) {
     const names = stringList2(value, `remove.${target}`);
@@ -58992,7 +59051,7 @@ function mergeValues3(base, override) {
   if (override === void 0) {
     return base;
   }
-  if (isRecord3(base) && isRecord3(override)) {
+  if (isRecord4(base) && isRecord4(override)) {
     const merged = { ...base };
     for (const [key, value] of Object.entries(override)) {
       merged[key] = mergeValues3(merged[key], value);
@@ -59012,7 +59071,7 @@ function sortJson(value) {
   if (Array.isArray(value)) {
     return value.map(sortJson);
   }
-  if (isRecord3(value)) {
+  if (isRecord4(value)) {
     return Object.fromEntries(
       Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, sortJson(nested)])
     );
@@ -59028,7 +59087,9 @@ var init_helpers = __esm({
       "import",
       "imports",
       "remove",
-      "variables"
+      "templateVariables",
+      "variables",
+      "when"
     ]);
     AGENT_METADATA_FIELD_KEYS = ["name", "labels", "annotations"];
   }
@@ -59048,7 +59109,7 @@ function fileBackedStringField() {
   };
 }
 function rejectDirectiveObject(value, input) {
-  if (isRecord3(value) && "append" in value) {
+  if (isRecord4(value) && "append" in value) {
     throw new Error(
       `Invalid agent authoring file ${input.path}: ${input.field} does not support directive objects; append is supported on ${APPEND_CAPABLE_FIELDS}`
     );
@@ -59056,7 +59117,7 @@ function rejectDirectiveObject(value, input) {
   return value;
 }
 function resolveFileBackedString2(value, input) {
-  if (!isRecord3(value)) {
+  if (!isRecord4(value)) {
     return value;
   }
   if ("file" in value && !("append" in value)) {
@@ -59154,11 +59215,11 @@ function rejectUnresolvedAppendDirective(value) {
   );
 }
 function appendDirectiveFromMarker(value) {
-  if (!isRecord3(value)) {
+  if (!isRecord4(value)) {
     return void 0;
   }
   const marker = value[APPEND_DIRECTIVE_MARKER_KEY];
-  if (!isRecord3(marker)) {
+  if (!isRecord4(marker)) {
     return void 0;
   }
   return marker;
@@ -59180,7 +59241,7 @@ function inlineEnvironmentField() {
     target: "spec",
     merge: (base, override) => mergeValues3(base, override),
     compile: (value, context) => {
-      if (!isRecord3(value)) {
+      if (!isRecord4(value)) {
         return { resources: [], value };
       }
       const resource = inlineEnvironmentResource2(value, context.path);
@@ -59193,7 +59254,7 @@ function inlineIdentityField() {
     target: "spec",
     merge: (base, override) => mergeValues3(base, override),
     compile: (value, context) => {
-      if (!isRecord3(value)) {
+      if (!isRecord4(value)) {
         return { resources: [], value };
       }
       const resource = inlineIdentityResource2(
@@ -59206,7 +59267,7 @@ function inlineIdentityField() {
   };
 }
 function assertAgentAuthoringDocument(document, path2) {
-  if (!isRecord3(document) || !("kind" in document)) {
+  if (!isRecord4(document) || !("kind" in document)) {
     return;
   }
   if (document.kind === "session") {
@@ -59359,12 +59420,12 @@ function compileRoutingInlineBindings(input) {
   const bindings = input.bindings ? cloneBindings(input.bindings) : {};
   const compiledTriggers = [];
   for (const trigger of input.triggers) {
-    if (!isRecord3(trigger) || trigger.kind === "heartbeat") {
+    if (!isRecord4(trigger) || trigger.kind === "heartbeat") {
       compiledTriggers.push(trigger);
       continue;
     }
     const routing = trigger.routing;
-    if (!isRecord3(routing)) {
+    if (!isRecord4(routing)) {
       compiledTriggers.push(trigger);
       continue;
     }
@@ -59395,7 +59456,7 @@ function extractDeliverContribution(routing, path2) {
   if (bindBlock === void 0) {
     return void 0;
   }
-  if (!isRecord3(bindBlock)) {
+  if (!isRecord4(bindBlock)) {
     throw inlineShapeError(
       path2,
       "deliver",
@@ -59425,7 +59486,7 @@ function extractBindArmContribution(routing, path2) {
 }
 function extractSpawnArmContribution(routing, path2) {
   const bindBlock = routing.bind;
-  if (!isRecord3(bindBlock)) {
+  if (!isRecord4(bindBlock)) {
     return void 0;
   }
   if (bindBlock.lifecycle === void 0 && bindBlock.continuity === void 0) {
@@ -59463,7 +59524,7 @@ function mergeContributionIntoBindings(bindings, contribution, path2) {
 }
 function ensureEntry(bindings, target) {
   const existing = bindings[target];
-  if (isRecord3(existing)) {
+  if (isRecord4(existing)) {
     return existing;
   }
   const entry = {};
@@ -59485,7 +59546,7 @@ function stripInlineRoutingFields(trigger, routing) {
       return { ...trigger, routing: rest };
     }
     case "spawn": {
-      if (!isRecord3(routing.bind)) {
+      if (!isRecord4(routing.bind)) {
         return trigger;
       }
       const {
@@ -59550,7 +59611,7 @@ function rejectSingletonTarget(target, path2, arm) {
 function cloneBindings(bindings) {
   const clone2 = {};
   for (const [key, value] of Object.entries(bindings)) {
-    clone2[key] = isRecord3(value) ? { ...value } : value;
+    clone2[key] = isRecord4(value) ? { ...value } : value;
   }
   return clone2;
 }
@@ -59600,7 +59661,7 @@ function triggersField() {
       const withNamesStripped = removeAuthoringTriggerNames(value);
       const { triggers, bindings } = compileRoutingInlineBindings({
         triggers: withNamesStripped,
-        bindings: isRecord3(context.draft.spec.bindings) ? context.draft.spec.bindings : void 0,
+        bindings: isRecord4(context.draft.spec.bindings) ? context.draft.spec.bindings : void 0,
         path: context.path
       });
       context.draft.spec.bindings = bindings;
@@ -59609,7 +59670,7 @@ function triggersField() {
   };
 }
 function mountItemKey(item) {
-  if (!isRecord3(item)) {
+  if (!isRecord4(item)) {
     return void 0;
   }
   if (typeof item.name === "string") {
@@ -59621,7 +59682,7 @@ function mountItemKey(item) {
   return void 0;
 }
 function triggerItemKey(item) {
-  if (!isRecord3(item)) {
+  if (!isRecord4(item)) {
     return void 0;
   }
   if (typeof item.name === "string") {
@@ -59674,7 +59735,7 @@ function removeAuthoringTriggerNames(value) {
     return value;
   }
   return value.map((trigger) => {
-    if (!isRecord3(trigger) || !("name" in trigger)) {
+    if (!isRecord4(trigger) || !("name" in trigger)) {
       return trigger;
     }
     const next = { ...trigger };
@@ -59697,7 +59758,7 @@ function namedMapField() {
     target: "spec",
     merge: (base, override) => mergeValues3(base, override),
     remove: (value, names) => {
-      if (!isRecord3(value)) {
+      if (!isRecord4(value)) {
         return value;
       }
       const next = { ...value };
@@ -59796,7 +59857,7 @@ function mergeSourceLocations(base, override) {
         continue;
       }
       const prefix = `${target}.${key}`;
-      if (!isRecord3(value)) {
+      if (!isRecord4(value)) {
         merged = Object.fromEntries(
           Object.entries(merged).filter(
             ([path2]) => path2 !== prefix && !path2.startsWith(`${prefix}.`)
@@ -59923,14 +59984,14 @@ function readVariableScope(document, path2) {
   if (declared === void 0) {
     return /* @__PURE__ */ new Map();
   }
-  if (!isRecord3(declared)) {
+  if (!isRecord4(declared)) {
     throw new Error(
       `Invalid variables in ${path2}: variables must be a map of name to value`
     );
   }
   const scope = /* @__PURE__ */ new Map();
   for (const [name, value] of Object.entries(declared)) {
-    if (!VARIABLE_NAME_PATTERN.test(name)) {
+    if (!VARIABLE_NAME_PATTERN2.test(name)) {
       throw new Error(
         `Invalid variable name "${name}" in ${path2}: names must match [A-Za-z_][A-Za-z0-9_]*`
       );
@@ -59939,6 +60000,66 @@ function readVariableScope(document, path2) {
   }
   return scope;
 }
+function registerTemplateVariableContract(declarations, contract, path2) {
+  for (const [kind, names] of [
+    ["required", contract.required],
+    ["optional", contract.optional]
+  ]) {
+    for (const name of names) {
+      const existing = declarations.get(name);
+      if (existing && existing.kind !== kind) {
+        throw new Error(
+          `Conflicting template variable declaration for "${name}": ${existing.kind} in ${existing.path}, ${kind} in ${path2}`
+        );
+      }
+      declarations.set(name, existing ?? { kind, path: path2 });
+    }
+  }
+}
+function assertRequiredTemplateVariables(required2, variables, path2) {
+  for (const name of [...required2].sort()) {
+    if (!variables.has(name)) {
+      throw new Error(
+        `Required template variable "${name}" is missing for imported ${path2}`
+      );
+    }
+  }
+}
+function includeConditionalTemplateDocument(input) {
+  const optional2 = new Set(
+    [...input.declarations.entries()].filter(([, declaration]) => declaration.kind === "optional").map(([name]) => name)
+  );
+  const referencedOptional = optionalVariableReferences(
+    input.document,
+    optional2
+  );
+  const condition = readVariableCondition(input.document.when, input.path);
+  if (referencedOptional.size > 0) {
+    if (!condition || referencedOptional.size !== 1 || !referencedOptional.has(condition)) {
+      throw new Error(
+        `Optional template variables in ${input.path} must be referenced only inside a document gated by matching when.variable`
+      );
+    }
+  }
+  if (!condition) {
+    return true;
+  }
+  if (!optional2.has(condition)) {
+    throw new Error(
+      `Invalid when.variable in ${input.path}: "${condition}" must be declared in templateVariables.optional`
+    );
+  }
+  const value = input.variables.get(condition);
+  if (value === void 0) {
+    return false;
+  }
+  if (value.trim().length === 0) {
+    throw new Error(
+      `Optional template variable "${condition}" in ${input.path} must be non-empty when supplied`
+    );
+  }
+  return true;
+}
 function substituteVariables(document, scope, site) {
   if (scope.size === 0) {
     return document;
@@ -59952,7 +60073,7 @@ function substituteValue(value, scope, site) {
   if (Array.isArray(value)) {
     return value.map((item) => substituteValue(item, scope, site));
   }
-  if (isRecord3(value)) {
+  if (isRecord4(value)) {
     return Object.fromEntries(
       Object.entries(value).map(([key, nested]) => [
         key,
@@ -59987,13 +60108,49 @@ function coerceVariableValue(name, value, path2) {
 function availableNames(scope) {
   return [...scope.keys()].sort().map((name) => `{{ $${name} }}`).join(", ");
 }
-var VARIABLE_DECLARATIONS_FIELD, VARIABLE_NAME_PATTERN, VARIABLE_REFERENCE_PATTERN;
+function readVariableCondition(value, path2) {
+  if (value === void 0) return void 0;
+  if (!isRecord4(value) || typeof value.variable !== "string" || value.variable.length === 0 || Object.keys(value).some((key) => key !== "variable")) {
+    throw new Error(
+      `Invalid when in ${path2}: expected exactly { variable: <optional variable name> }`
+    );
+  }
+  return value.variable;
+}
+function optionalVariableReferences(value, optional2) {
+  const found = /* @__PURE__ */ new Set();
+  collectOptionalVariableReferences(value, optional2, found);
+  return found;
+}
+function collectOptionalVariableReferences(value, optional2, found) {
+  if (typeof value === "string") {
+    for (const match of value.matchAll(VARIABLE_REFERENCE_PATTERN)) {
+      if (match[1] && optional2.has(match[1])) found.add(match[1]);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectOptionalVariableReferences(item, optional2, found);
+    }
+    return;
+  }
+  if (isRecord4(value)) {
+    for (const [key, nested] of Object.entries(value)) {
+      if (key !== "templateVariables" && key !== "when") {
+        collectOptionalVariableReferences(nested, optional2, found);
+      }
+    }
+  }
+}
+var VARIABLE_DECLARATIONS_FIELD, VARIABLE_NAME_PATTERN2, VARIABLE_REFERENCE_PATTERN;
 var init_template_variables = __esm({
   "../../packages/schemas/src/project-apply-files/template-variables.ts"() {
     "use strict";
+    init_templates();
     init_source();
     VARIABLE_DECLARATIONS_FIELD = "variables";
-    VARIABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+    VARIABLE_NAME_PATTERN2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
     VARIABLE_REFERENCE_PATTERN = /\{\{\s*\$([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
   }
 });
@@ -60080,7 +60237,7 @@ function projectCompiledTriggerSourceLocations(locations, authoredTriggers) {
   );
   let compiledIndex = 0;
   for (const [authoredIndex, trigger] of authoredTriggers.entries()) {
-    if (!isRecord3(trigger)) {
+    if (!isRecord4(trigger)) {
       continue;
     }
     const events = authoredTriggerEvents(trigger);
@@ -60148,9 +60305,24 @@ function validateAgentFragmentDocument(document, path2, context) {
       `Agent import cycle detected: ${[...context.stack, normalizedPath].join(" -> ")}`
     );
   }
-  if (!isRecord3(document)) {
+  if (!isRecord4(document)) {
     throw new Error(`Invalid agent fragment file ${path2}: expected object`);
   }
+  const variableContract = readTemplateVariableContract(
+    document,
+    normalizedPath
+  );
+  registerTemplateVariableContract(
+    context.templateVariableKinds,
+    variableContract,
+    normalizedPath
+  );
+  includeConditionalTemplateDocument({
+    document,
+    declarations: context.templateVariableKinds,
+    variables: context.variables,
+    path: normalizedPath
+  });
   for (const imported of importPaths2(document).map(
     (importPath) => resolveImportPath2(importPath, normalizedPath, context.fileIndex)
   )) {
@@ -60160,6 +60332,7 @@ function validateAgentFragmentDocument(document, path2, context) {
       {
         fileIndex: context.fileIndex,
         stack: [...context.stack, normalizedPath],
+        templateVariableKinds: context.templateVariableKinds,
         variables: context.variables
       }
     );
@@ -60198,20 +60371,59 @@ function conflictingGeneratedResourceMessage(key, existing, record2) {
   return `Conflicting generated resource "${key}" from agent authoring: ${location}. Inline generated resources must be identical when they share a name.`;
 }
 function compileAgentDocumentValue(document, path2, fileIndex, contextVariables) {
+  const templateVariableKinds = /* @__PURE__ */ new Map();
+  collectTemplateVariableContracts(
+    document,
+    path2,
+    fileIndex,
+    [],
+    templateVariableKinds
+  );
   const draft = compileAgentDocument2(document, path2, {
     fileIndex,
     stack: [],
+    templateVariableKinds,
     variables: /* @__PURE__ */ new Map(),
     ...contextVariables && Object.keys(contextVariables).length > 0 ? { contextVariables: new Map(Object.entries(contextVariables)) } : {}
   });
   const authoredTriggers = structuredClone(draft.spec.triggers);
-  const removals = isRecord3(document) ? removalDirectives2(document, normalizeSourcePath(path2)) : [];
+  const removals = isRecord4(document) ? removalDirectives2(document, normalizeSourcePath(path2)) : [];
   return {
     ...compileAgentDraftResources(draft, path2, removals),
     sourceLocations: draft.sourceLocations,
     authoredTriggers
   };
 }
+function collectTemplateVariableContracts(document, path2, fileIndex, stack, declarations) {
+  const normalizedPath = normalizeSourcePath(path2);
+  if (stack.includes(normalizedPath)) {
+    throw new Error(
+      `Agent import cycle detected: ${[...stack, normalizedPath].join(" -> ")}`
+    );
+  }
+  if (!isRecord4(document)) {
+    throw new Error(`Invalid agent authoring file ${path2}: expected object`);
+  }
+  registerTemplateVariableContract(
+    declarations,
+    readTemplateVariableContract(document, normalizedPath),
+    normalizedPath
+  );
+  const imports = [
+    ...stack.length === 0 && document.name === BUILT_IN_DEFAULT_AGENT_NAME ? [BUILT_IN_DEFAULT_AGENT_TEMPLATE_IMPORT] : [],
+    ...importPaths2(document)
+  ];
+  for (const importPath of imports) {
+    const imported = resolveImportPath2(importPath, normalizedPath, fileIndex);
+    collectTemplateVariableContracts(
+      readSingleDocument2(imported, fileIndex),
+      imported,
+      fileIndex,
+      [...stack, normalizedPath],
+      declarations
+    );
+  }
+}
 function compileAgentDocument2(document, path2, context) {
   const normalizedPath = normalizeSourcePath(path2);
   if (context.stack.includes(normalizedPath)) {
@@ -60219,13 +60431,35 @@ function compileAgentDocument2(document, path2, context) {
       `Agent import cycle detected: ${[...context.stack, normalizedPath].join(" -> ")}`
     );
   }
-  if (!isRecord3(document)) {
+  if (!isRecord4(document)) {
     throw new Error(`Invalid agent authoring file ${path2}: expected object`);
   }
+  const variableContract = readTemplateVariableContract(
+    document,
+    normalizedPath
+  );
+  registerTemplateVariableContract(
+    context.templateVariableKinds,
+    variableContract,
+    normalizedPath
+  );
   const variables = context.stack.length === 0 ? new Map([
     ...context.contextVariables ?? /* @__PURE__ */ new Map(),
     ...readVariableScope(document, normalizedPath)
   ]) : context.variables;
+  assertRequiredTemplateVariables(
+    variableContract.required,
+    variables,
+    normalizedPath
+  );
+  if (context.stack.length > 0 && !includeConditionalTemplateDocument({
+    document,
+    declarations: context.templateVariableKinds,
+    variables,
+    path: normalizedPath
+  })) {
+    return emptyAgentDraft();
+  }
   let merged = emptyAgentDraft();
   const imports = [
     ...context.stack.length === 0 && document.name === BUILT_IN_DEFAULT_AGENT_NAME ? [BUILT_IN_DEFAULT_AGENT_TEMPLATE_IMPORT] : [],
@@ -60237,16 +60471,47 @@ function compileAgentDocument2(document, path2, context) {
       normalizedPath,
       context.fileIndex
     );
+    const rawImportedDocument = readSingleDocument2(imported, context.fileIndex);
+    if (!isRecord4(rawImportedDocument)) {
+      throw new Error(
+        `Invalid agent authoring file ${imported}: expected object`
+      );
+    }
+    const importedContract = readTemplateVariableContract(
+      rawImportedDocument,
+      imported
+    );
+    registerTemplateVariableContract(
+      context.templateVariableKinds,
+      importedContract,
+      imported
+    );
+    assertRequiredTemplateVariables(
+      importedContract.required,
+      variables,
+      imported
+    );
+    if (!includeConditionalTemplateDocument({
+      document: rawImportedDocument,
+      declarations: context.templateVariableKinds,
+      variables,
+      path: imported
+    })) {
+      continue;
+    }
     const importedDocument = substituteVariables(
-      readSingleDocument2(imported, context.fileIndex),
+      rawImportedDocument,
       variables,
-      { importPath }
+      {
+        importPath
+      }
     );
     merged = mergeAgentDrafts(
       merged,
       compileAgentDocument2(importedDocument, imported, {
         fileIndex: context.fileIndex,
         stack: [...context.stack, normalizedPath],
+        templateVariableKinds: context.templateVariableKinds,
         variables
       })
     );
@@ -60263,6 +60528,7 @@ var init_agent_authoring = __esm({
   "../../packages/schemas/src/project-apply-files/agent-authoring.ts"() {
     "use strict";
     init_default_agent();
+    init_templates();
     init_agent_document_merge();
     init_agent_fields();
     init_source();
@@ -60508,7 +60774,7 @@ function hasBuiltInDefaultAgentDocument(files) {
   return files.some((file2) => {
     try {
       return readDocumentsFromSource(file2).some(
-        (document) => isRecord3(document) && document.name === BUILT_IN_DEFAULT_AGENT_NAME
+        (document) => isRecord4(document) && document.name === BUILT_IN_DEFAULT_AGENT_NAME
       );
     } catch {
       return false;
@@ -60519,7 +60785,7 @@ function templateImportsInFile(file2) {
   try {
     const specifiers = [];
     for (const document of readDocumentsFromSource(file2)) {
-      if (!isRecord3(document)) {
+      if (!isRecord4(document)) {
         continue;
       }
       for (const importPath of importPaths2(document)) {
@@ -60768,6 +61034,7 @@ function assertValidFragmentSourceFiles(files, resourceRoot, fileIndex) {
       validateAgentFragmentDocument(documents[0], file2.path, {
         fileIndex,
         stack: [],
+        templateVariableKinds: /* @__PURE__ */ new Map(),
         variables: /* @__PURE__ */ new Map()
       });
     } catch (error51) {
@@ -69460,7 +69727,7 @@ var AgentFacingAutoMcpShim = class {
   }
 };
 function agentFacingDryRunTool(tool) {
-  if (!isRecord(tool) || tool.name !== DRY_RUN_TOOL_NAME) {
+  if (!isRecord2(tool) || tool.name !== DRY_RUN_TOOL_NAME) {
     return tool;
   }
   if (typeof tool.description !== "string" || !tool.description.includes(AUTO_RESOURCES_DRY_RUN_PATHS_PROTOCOL_MARKER)) {
@@ -69489,7 +69756,7 @@ function agentFacingDryRunTool(tool) {
   };
 }
 function resolveAgentFacingDryRun(input) {
-  if (!isRecord(input.arguments)) {
+  if (!isRecord2(input.arguments)) {
     throw new Error(`Dry-run arguments must be an object. ${correctedCall}`);
   }
   const argumentsValue = input.arguments;
@@ -69649,7 +69916,7 @@ function localImportPaths(content, importerPath) {
   const imports = [];
   for (const document of parseAllDocuments2(content)) {
     const value = document.toJS();
-    if (!isRecord(value) || !Array.isArray(value.imports)) {
+    if (!isRecord2(value) || !Array.isArray(value.imports)) {
       continue;
     }
     for (const importPath of value.imports) {
@@ -69800,8 +70067,8 @@ async function startAutoMcpProxy(input) {
   return { server, url: `http://127.0.0.1:${address.port}/mcp` };
 }
 function prepareDryRunToolCall(input) {
-  const params = isRecord(input.message.params) ? input.message.params : {};
-  const argumentsValue = isRecord(params.arguments) ? params.arguments : {};
+  const params = isRecord2(input.message.params) ? input.message.params : {};
+  const argumentsValue = isRecord2(params.arguments) ? params.arguments : {};
   const hasLegacyDialect = ["files", "resources"].some(
     (key) => Object.hasOwn(argumentsValue, key)
   );
@@ -69846,7 +70113,7 @@ function transformToolsListResponse(body) {
   const parsed = JSON.parse(body);
   let compatible = false;
   const transformed = transformJsonRpcMessages(parsed, (message) => {
-    if (!isRecord(message.result) || !Array.isArray(message.result.tools)) {
+    if (!isRecord2(message.result) || !Array.isArray(message.result.tools)) {
       return message;
     }
     const tools = message.result.tools.map((tool) => {
@@ -69863,16 +70130,16 @@ function transformToolsListResponse(body) {
 function transformJsonRpcMessages(value, transform2) {
   if (Array.isArray(value)) {
     return value.map(
-      (message) => isRecord(message) ? transform2(message) : message
+      (message) => isRecord2(message) ? transform2(message) : message
     );
   }
-  return isRecord(value) ? transform2(value) : value;
+  return isRecord2(value) ? transform2(value) : value;
 }
 function isToolsListRequest(value) {
-  return isRecord(value) && value.method === "tools/list";
+  return isRecord2(value) && value.method === "tools/list";
 }
 function isDryRunToolCall(value) {
-  if (!isRecord(value) || value.method !== "tools/call" || !isRecord(value.params)) {
+  if (!isRecord2(value) || value.method !== "tools/call" || !isRecord2(value.params)) {
     return false;
   }
   return value.params.name === DRY_RUN_TOOL_NAME;
@@ -69937,7 +70204,7 @@ function writeResponse(response, status, headers, body) {
   }
   response.end(body);
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
@@ -80465,7 +80732,7 @@ async function selectRepository(context, github, explicitRepo) {
   const selection = github.grant.providerResourceSelection;
   if (selection.kind === "selected") {
     const repos = selection.resources.map(
-      (resource) => isRecord4(resource) && typeof resource.fullName === "string" ? resource.fullName : void 0
+      (resource) => isRecord5(resource) && typeof resource.fullName === "string" ? resource.fullName : void 0
     ).filter(isDefined);
     if (repos.length === 1) {
       context.writeOutput(`Using GitHub repository ${repos[0]}.`);
@@ -80795,7 +81062,7 @@ function slackWorkspaceUrl(slack) {
 function organizationLabel(organization) {
   return `${organization.organizationName} (${organization.organizationSlug})`;
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isDefined(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autohq/cli",
-  "version": "0.1.478",
+  "version": "0.1.479",
   "license": "SEE LICENSE IN README.md",
   "publishConfig": {
     "access": "public"