@darkhorseprojects/circuitry 0.2.32 → 0.2.99

package/dist/graph.d.ts

@@ -1,5 +1,5 @@
-export declare const CIRCUITRY_SPEC_VERSION: "0.2";
-export type CircuitrySpecVersion = typeof CIRCUITRY_SPEC_VERSION;
+export declare const CIRCUITRY_SPEC_VERSION: "0.2.99";
+export type CircuitrySpecVersion = typeof CIRCUITRY_SPEC_VERSION | "0.2";
 export type CircuitryNodeKind = "agent" | "input" | "tool" | "output" | string;
 export type CircuitryEdgeKind = "context" | "dependency" | "message" | "control" | string;
 export type CircuitryInputKind = "text" | "file" | "url" | "image" | "uri" | "canvas" | "mcp" | string;
@@ -170,12 +170,20 @@ export type CircuitryRuntimeInputs = Record<string, unknown>;
  * graph source stable and catches misspelled input names before execution.
  */
 export declare const applyCircuitryRuntimeInputs: (graph: CircuitryGraph, inputs?: CircuitryRuntimeInputs) => CircuitryGraph;
+export type CircuitryGraphLink = string | {
+    /** Path to another .circuitry.yaml/.json file, resolved relative to this file. */
+    path: string;
+    /** Optional id prefix applied to imported resources. */
+    prefix?: string;
+};
 export type CircuitryGraph = {
-    /** Spec version. Use "0.2" for new graphs. */
+    /** Spec version. Use "0.2.99" for linked graph files. */
     circuitry: CircuitrySpecVersion | string;
     id?: string;
     title?: string;
     description?: string;
+    /** Files whose resources are merged into this graph before validation/execution. */
+    links?: CircuitryGraphLink[];
     resources?: Record<string, CircuitryResourceEntry>;
     /** Internal normalized execution nodes. Authored graph files must not set this. */
     nodes?: CircuitryNode[];
@@ -215,7 +223,7 @@ export type CircuitryValidationResult = {
 };
 export declare const DEFAULT_CIRCUITRY_VALIDATION_RULES: CircuitryValidationRuleEntry[];
 export declare const DEFAULT_CIRCUITRY_VALIDATION_STANDARD: {
-    readonly version: "0.2";
+    readonly version: "0.2.99";
     readonly requireSpecVersion: true;
     readonly rules: CircuitryValidationRuleEntry[];
     readonly executableKinds: ["agent", "tool", "output"];

package/dist/index.js

@@ -27,7 +27,7 @@ var isNodeElement = (element) => {
 };
 
 // src/graph.ts
-var CIRCUITRY_SPEC_VERSION = "0.2";
+var CIRCUITRY_SPEC_VERSION = "0.2.99";
 var runtimeInputToText = (value) => {
   if (typeof value === "string") return value;
   if (value === void 0) return "";
@@ -136,7 +136,7 @@ var normalizeCircuitryGraph = (graph) => {
   const { nodes, edges } = expandResources(graph.resources);
   return { ...graph, nodes, edges };
 };
-var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set([CIRCUITRY_SPEC_VERSION]);
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.2", CIRCUITRY_SPEC_VERSION]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -519,6 +519,96 @@ ${contextSection}`
   ].filter(Boolean).join("\n\n");
 };
 var collectImages = (contextInputs) => contextInputs.filter((item) => item.kind === "image" && item.image).map((item) => item.image);
+var stripJsonFence = (output) => {
+  const trimmed = output.trim();
+  const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return fenced ? fenced[1].trim() : trimmed;
+};
+var parseExpectedOutput = (nodeId, output) => {
+  try {
+    return JSON.parse(stripJsonFence(output));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Node ${nodeId} output does not match expect: output is not valid JSON (${detail})`);
+  }
+};
+var isFieldObject = (schema) => !!schema && typeof schema === "object" && !Array.isArray(schema) && typeof schema.type === "string";
+var describeExpectedType = (schema) => Array.isArray(schema) ? "list" : typeof schema === "string" ? schema : isFieldObject(schema) ? schema.type : "dict";
+var matchesPrimitiveType = (value, type) => {
+  switch (type) {
+    case "str":
+      return typeof value === "string";
+    case "int":
+      return Number.isInteger(value);
+    case "float":
+      return typeof value === "number" && Number.isFinite(value);
+    case "bool":
+      return typeof value === "boolean";
+    case "list":
+      return Array.isArray(value);
+    case "dict":
+      return !!value && typeof value === "object" && !Array.isArray(value);
+    default:
+      return true;
+  }
+};
+var validateExpectValue = (value, schema, path, errors) => {
+  if (typeof schema === "string") {
+    if (!matchesPrimitiveType(value, schema)) {
+      errors.push(`${path} expected ${schema}, got ${Array.isArray(value) ? "list" : typeof value}`);
+    }
+    return;
+  }
+  if (Array.isArray(schema)) {
+    if (!Array.isArray(value)) {
+      errors.push(`${path} expected list, got ${typeof value}`);
+      return;
+    }
+    if (schema.length > 0) {
+      value.forEach((item, index) => validateExpectValue(item, schema[0], `${path}[${index}]`, errors));
+    }
+    return;
+  }
+  if (isFieldObject(schema)) {
+    if (schema.optional && value === void 0) return;
+    if (!matchesPrimitiveType(value, schema.type)) {
+      errors.push(`${path} expected ${schema.type}, got ${Array.isArray(value) ? "list" : typeof value}`);
+      return;
+    }
+    if (schema.contains && typeof value === "string" && !value.includes(schema.contains)) {
+      errors.push(`${path} must include string: ${schema.contains}`);
+    }
+    if (schema.type === "list" && schema.items && Array.isArray(value)) {
+      value.forEach((item, index) => validateExpectValue(item, schema.items, `${path}[${index}]`, errors));
+    }
+    return;
+  }
+  if (schema && typeof schema === "object") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      errors.push(`${path} expected dict, got ${Array.isArray(value) ? "list" : typeof value}`);
+      return;
+    }
+    for (const [key, childSchema] of Object.entries(schema)) {
+      const childOptional = isFieldObject(childSchema) && childSchema.optional;
+      const childValue = value[key];
+      if (childValue === void 0 && !childOptional) {
+        errors.push(`${path}.${key} is missing required field of type ${describeExpectedType(childSchema)}`);
+        continue;
+      }
+      validateExpectValue(childValue, childSchema, `${path}.${key}`, errors);
+    }
+  }
+};
+var assertExpectedOutput = (node, output) => {
+  if (!node.expect) return;
+  const parsed = parseExpectedOutput(node.id, output);
+  const errors = [];
+  validateExpectValue(parsed, node.expect, node.id, errors);
+  if (errors.length) {
+    throw new Error(`Node ${node.id} output does not match expect:
+${errors.join("\n")}`);
+  }
+};
 var executeCircuitryNode = async ({
   graph,
   item,
@@ -542,8 +632,9 @@ var executeCircuitryNode = async ({
     };
   }
   const agent = item.node.agent || {};
+  let result;
   try {
-    const result = await executeNode({
+    result = await executeNode({
       nodeId: item.id,
       model: (agent.model === "inherit" ? void 0 : agent.model) || (defaultModel === "inherit" ? void 0 : defaultModel) || "inherit",
       tools: agent.tools || [],
@@ -556,13 +647,6 @@ var executeCircuitryNode = async ({
       images: collectImages(contextInputs),
       prompt: composeCircuitryPrompt(graph, item.node, inputPayload, contextInputs)
     });
-    onNodeComplete?.(item.id, { output: result.output });
-    return {
-      nodeId: item.id,
-      fallbackCycle,
-      inputNodeIds: inputPayload.map((input) => input.nodeId),
-      output: result.output
-    };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     onNodeComplete?.(item.id, { error: message });
@@ -574,6 +658,14 @@ var executeCircuitryNode = async ({
       error: message
     };
   }
+  assertExpectedOutput(item.node, result.output);
+  onNodeComplete?.(item.id, { output: result.output });
+  return {
+    nodeId: item.id,
+    fallbackCycle,
+    inputNodeIds: inputPayload.map((input) => input.nodeId),
+    output: result.output
+  };
 };
 var runCircuitryGraphExecution = async ({
   graph,

package/dist/node.d.ts

@@ -8,6 +8,12 @@ export declare class NodeCircuitryHost implements CircuitryHost {
     private exists;
     private parseIssue;
     private parseGraphForValidation;
+    private linkPath;
+    private linkPrefix;
+    private prefixResourceIds;
+    private mergeResources;
+    private resolveGraphLinks;
+    private parseAndResolveGraph;
     private readGraphFile;
     readGraph(input?: {
         filename?: string;

package/dist/node.js

@@ -8,7 +8,7 @@ import os from "node:os";
 import YAML from "yaml";
 
 // src/graph.ts
-var CIRCUITRY_SPEC_VERSION = "0.2";
+var CIRCUITRY_SPEC_VERSION = "0.2.99";
 var runtimeInputToText = (value) => {
   if (typeof value === "string") return value;
   if (value === void 0) return "";
@@ -117,7 +117,7 @@ var normalizeCircuitryGraph = (graph) => {
   const { nodes, edges } = expandResources(graph.resources);
   return { ...graph, nodes, edges };
 };
-var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set([CIRCUITRY_SPEC_VERSION]);
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.2", CIRCUITRY_SPEC_VERSION]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -441,6 +441,96 @@ ${contextSection}`
   ].filter(Boolean).join("\n\n");
 };
 var collectImages = (contextInputs) => contextInputs.filter((item) => item.kind === "image" && item.image).map((item) => item.image);
+var stripJsonFence = (output) => {
+  const trimmed = output.trim();
+  const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return fenced ? fenced[1].trim() : trimmed;
+};
+var parseExpectedOutput = (nodeId, output) => {
+  try {
+    return JSON.parse(stripJsonFence(output));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Node ${nodeId} output does not match expect: output is not valid JSON (${detail})`);
+  }
+};
+var isFieldObject = (schema) => !!schema && typeof schema === "object" && !Array.isArray(schema) && typeof schema.type === "string";
+var describeExpectedType = (schema) => Array.isArray(schema) ? "list" : typeof schema === "string" ? schema : isFieldObject(schema) ? schema.type : "dict";
+var matchesPrimitiveType = (value, type) => {
+  switch (type) {
+    case "str":
+      return typeof value === "string";
+    case "int":
+      return Number.isInteger(value);
+    case "float":
+      return typeof value === "number" && Number.isFinite(value);
+    case "bool":
+      return typeof value === "boolean";
+    case "list":
+      return Array.isArray(value);
+    case "dict":
+      return !!value && typeof value === "object" && !Array.isArray(value);
+    default:
+      return true;
+  }
+};
+var validateExpectValue = (value, schema, path2, errors) => {
+  if (typeof schema === "string") {
+    if (!matchesPrimitiveType(value, schema)) {
+      errors.push(`${path2} expected ${schema}, got ${Array.isArray(value) ? "list" : typeof value}`);
+    }
+    return;
+  }
+  if (Array.isArray(schema)) {
+    if (!Array.isArray(value)) {
+      errors.push(`${path2} expected list, got ${typeof value}`);
+      return;
+    }
+    if (schema.length > 0) {
+      value.forEach((item, index) => validateExpectValue(item, schema[0], `${path2}[${index}]`, errors));
+    }
+    return;
+  }
+  if (isFieldObject(schema)) {
+    if (schema.optional && value === void 0) return;
+    if (!matchesPrimitiveType(value, schema.type)) {
+      errors.push(`${path2} expected ${schema.type}, got ${Array.isArray(value) ? "list" : typeof value}`);
+      return;
+    }
+    if (schema.contains && typeof value === "string" && !value.includes(schema.contains)) {
+      errors.push(`${path2} must include string: ${schema.contains}`);
+    }
+    if (schema.type === "list" && schema.items && Array.isArray(value)) {
+      value.forEach((item, index) => validateExpectValue(item, schema.items, `${path2}[${index}]`, errors));
+    }
+    return;
+  }
+  if (schema && typeof schema === "object") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      errors.push(`${path2} expected dict, got ${Array.isArray(value) ? "list" : typeof value}`);
+      return;
+    }
+    for (const [key, childSchema] of Object.entries(schema)) {
+      const childOptional = isFieldObject(childSchema) && childSchema.optional;
+      const childValue = value[key];
+      if (childValue === void 0 && !childOptional) {
+        errors.push(`${path2}.${key} is missing required field of type ${describeExpectedType(childSchema)}`);
+        continue;
+      }
+      validateExpectValue(childValue, childSchema, `${path2}.${key}`, errors);
+    }
+  }
+};
+var assertExpectedOutput = (node, output) => {
+  if (!node.expect) return;
+  const parsed = parseExpectedOutput(node.id, output);
+  const errors = [];
+  validateExpectValue(parsed, node.expect, node.id, errors);
+  if (errors.length) {
+    throw new Error(`Node ${node.id} output does not match expect:
+${errors.join("\n")}`);
+  }
+};
 var executeCircuitryNode = async ({
   graph,
   item,
@@ -464,8 +554,9 @@ var executeCircuitryNode = async ({
     };
   }
   const agent = item.node.agent || {};
+  let result;
   try {
-    const result = await executeNode({
+    result = await executeNode({
       nodeId: item.id,
       model: (agent.model === "inherit" ? void 0 : agent.model) || (defaultModel === "inherit" ? void 0 : defaultModel) || "inherit",
       tools: agent.tools || [],
@@ -478,13 +569,6 @@ var executeCircuitryNode = async ({
       images: collectImages(contextInputs),
       prompt: composeCircuitryPrompt(graph, item.node, inputPayload, contextInputs)
     });
-    onNodeComplete?.(item.id, { output: result.output });
-    return {
-      nodeId: item.id,
-      fallbackCycle,
-      inputNodeIds: inputPayload.map((input) => input.nodeId),
-      output: result.output
-    };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     onNodeComplete?.(item.id, { error: message });
@@ -496,6 +580,14 @@ var executeCircuitryNode = async ({
       error: message
     };
   }
+  assertExpectedOutput(item.node, result.output);
+  onNodeComplete?.(item.id, { output: result.output });
+  return {
+    nodeId: item.id,
+    fallbackCycle,
+    inputNodeIds: inputPayload.map((input) => input.nodeId),
+    output: result.output
+  };
 };
 var runCircuitryGraphExecution = async ({
   graph,
@@ -745,11 +837,84 @@ var NodeCircuitryHost = class {
       return { error: this.parseIssue(error, filename) };
     }
   }
+  linkPath(link) {
+    return typeof link === "string" ? link : link.path;
+  }
+  linkPrefix(link) {
+    return typeof link === "string" ? "" : link.prefix || "";
+  }
+  prefixResourceIds(resources, prefix) {
+    if (!prefix) return resources;
+    const ids = new Set(Object.keys(resources));
+    const prefixed = {};
+    for (const [id, resource] of Object.entries(resources)) {
+      const next = { ...resource };
+      if ((next.type === "agent" || next.type === "tool") && next.inputs) {
+        next.inputs = next.inputs.map((input) => ids.has(input) ? `${prefix}${input}` : input);
+      }
+      prefixed[`${prefix}${id}`] = next;
+    }
+    return prefixed;
+  }
+  mergeResources(target, source, fromFile) {
+    for (const [id, resource] of Object.entries(source)) {
+      if (target[id]) {
+        throw new Error(`Linked Circuitry resource id collision: ${id} from ${fromFile}`);
+      }
+      target[id] = resource;
+    }
+  }
+  async resolveGraphLinks(graph, filename, standard, stack = []) {
+    const graphFile = path.resolve(filename);
+    if (stack.includes(graphFile)) {
+      throw new Error(`Circuitry graph link cycle: ${[...stack, graphFile].join(" -> ")}`);
+    }
+    const linkedResources = {};
+    const nextStack = [...stack, graphFile];
+    for (const link of graph.links || []) {
+      const rawPath = this.linkPath(link);
+      if (!rawPath) throw new Error(`Circuitry graph link is missing path in ${graphFile}`);
+      const linkedFile = path.resolve(path.dirname(graphFile), rawPath);
+      const linkedText = await readFile(linkedFile, "utf8");
+      const parsed = parseCircuitryText(linkedText, linkedFile, standard, { validate: false });
+      const resolved = await this.resolveGraphLinks(parsed, linkedFile, standard, nextStack);
+      this.mergeResources(
+        linkedResources,
+        this.prefixResourceIds(resolved.resources || {}, this.linkPrefix(link)),
+        linkedFile
+      );
+    }
+    return {
+      ...graph,
+      resources: {
+        ...linkedResources,
+        ...graph.resources || {}
+      }
+    };
+  }
+  async parseAndResolveGraph(text, filename, standard) {
+    const parsed = this.parseGraphForValidation(text, filename, standard);
+    if (!parsed.graph) return parsed;
+    try {
+      return { graph: await this.resolveGraphLinks(parsed.graph, filename, standard) };
+    } catch (error) {
+      return { error: this.parseIssue(error, filename) };
+    }
+  }
   async readGraphFile(filename) {
     const graphFile = this.resolveGraphFile(filename);
     const text = await readFile(graphFile, "utf8");
-    const graph = parseCircuitryText(text, graphFile);
-    return { graphFile, text, graph };
+    const parsed = await this.parseAndResolveGraph(text, graphFile);
+    if (!parsed.graph) throw new Error(`Invalid Circuitry graph:
+${parsed.error?.message}`);
+    const validation = validateCircuitryGraphWithStandard(parsed.graph);
+    if (validation.errors.length) {
+      throw new Error(
+        `Invalid Circuitry graph:
+${validation.errors.map((e) => e.message).join("\n")}`
+      );
+    }
+    return { graphFile, text, graph: normalizeCircuitryGraph(parsed.graph) };
   }
   async readGraph(input = {}) {
     const { graphFile, text, graph } = await this.readGraphFile(input.filename);
@@ -761,8 +926,8 @@ var NodeCircuitryHost = class {
     if (input.graph)
       return validateCircuitryGraphWithStandard(input.graph, input.standard);
     const filename = input.filename || defaultFilename;
-    const parsed = this.parseGraphForValidation(input.text, filename, input.standard);
-    if (parsed.error) {
+    const parsed = await this.parseAndResolveGraph(input.text, filename, input.standard);
+    if ("error" in parsed) {
       return {
         ok: false,
         errors: [parsed.error],
@@ -773,7 +938,7 @@ var NodeCircuitryHost = class {
   }
   async writeGraph(input) {
     const graphFile = this.resolveGraphFile(input.filename);
-    const parsed = input.graph ? { graph: input.graph } : this.parseGraphForValidation(
+    const parsed = input.graph ? { graph: input.graph } : await this.parseAndResolveGraph(
       input.text,
       input.filename || graphFile,
       input.standard
@@ -804,7 +969,7 @@ ${validation.errors.map((e) => e.message).join("\n")}`
   async runGraph(input = {}) {
     const source = input.source || (input.text ? "text" : "current");
     const graphFile = this.resolveGraphFile(input.filename);
-    const parsed = source === "text" ? this.parseGraphForValidation(
+    const parsed = source === "text" ? await this.parseAndResolveGraph(
       input.text,
       input.filename || graphFile,
       input.standard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkhorseprojects/circuitry",
-  "version": "0.2.32",
+  "version": "0.2.99",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",