@darkhorseprojects/circuitry 0.2.33 → 0.3.0

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.3.0";
+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,23 @@ 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;
+/** Import declaration for bringing resources from another graph file. */
+export type CircuitryImport = {
+    /** Path to another .circuitry.yaml/.json file, resolved relative to this file. */
+    path: string;
+    /** Resource id to import from the source file. */
+    resource: string;
+    /** Optional local name (alias) for the imported resource. */
+    as?: string;
+};
 export type CircuitryGraph = {
-    /** Spec version. Use "0.2" for new graphs. */
+    /** Spec version. Use "0.3.0" for import-based graph files. */
     circuitry: CircuitrySpecVersion | string;
     id?: string;
     title?: string;
     description?: string;
+    /** Explicit imports of specific resources from other graph files. */
+    imports?: CircuitryImport[];
     resources?: Record<string, CircuitryResourceEntry>;
     /** Internal normalized execution nodes. Authored graph files must not set this. */
     nodes?: CircuitryNode[];
@@ -215,7 +226,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.3.0";
     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.3.0";
 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.3"]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -160,19 +160,22 @@ var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   }
   if (options.sourceFormat) {
     if (!graphObject.resources || Object.keys(graphObject.resources).length === 0) {
-      addError("missing_resources", "Circuitry v0.2 graphs must use a resources: section", ["resources"]);
+      addError("missing_resources", "Circuitry v0.3 graphs must use a resources: section", ["resources"]);
     }
     if (graphObject.agents && Object.keys(graphObject.agents).length > 0) {
-      addError("forbidden_agents", "Circuitry v0.2 graph files must not use top-level agents:; use resources:", ["agents"]);
+      addError("forbidden_agents", "Circuitry v0.3 graph files must not use top-level agents:; use resources:", ["agents"]);
     }
     if (graphObject.inputs && Object.keys(graphObject.inputs).length > 0) {
-      addError("forbidden_inputs", "Circuitry v0.2 graph files must not use top-level inputs:; use resources:", ["inputs"]);
+      addError("forbidden_inputs", "Circuitry v0.3 graph files must not use top-level inputs:; use resources:", ["inputs"]);
     }
     if (graphObject.nodes && graphObject.nodes.length > 0) {
-      addError("forbidden_nodes", "Circuitry v0.2 graph files must not use top-level nodes:; use resources:", ["nodes"]);
+      addError("forbidden_nodes", "Circuitry v0.3 graph files must not use top-level nodes:; use resources:", ["nodes"]);
     }
     if (graphObject.edges && graphObject.edges.length > 0) {
-      addError("forbidden_edges", "Circuitry v0.2 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+      addError("forbidden_edges", "Circuitry v0.3 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+    }
+    if (graphObject.links && graphObject.links.length > 0) {
+      addError("forbidden_links", "Circuitry v0.3 graph files must use imports: instead of links:", ["links"]);
     }
   }
   const normalized = normalizeCircuitryGraph(graphObject);

package/dist/node.d.ts

@@ -8,6 +8,10 @@ export declare class NodeCircuitryHost implements CircuitryHost {
     private exists;
     private parseIssue;
     private parseGraphForValidation;
+    private resolveGraphImports;
+    /** Rewrite inputs in imported resource to use aliased resource ids. */
+    private rewriteImportInputs;
+    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.3.0";
 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.3"]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -141,19 +141,22 @@ var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   }
   if (options.sourceFormat) {
     if (!graphObject.resources || Object.keys(graphObject.resources).length === 0) {
-      addError("missing_resources", "Circuitry v0.2 graphs must use a resources: section", ["resources"]);
+      addError("missing_resources", "Circuitry v0.3 graphs must use a resources: section", ["resources"]);
     }
     if (graphObject.agents && Object.keys(graphObject.agents).length > 0) {
-      addError("forbidden_agents", "Circuitry v0.2 graph files must not use top-level agents:; use resources:", ["agents"]);
+      addError("forbidden_agents", "Circuitry v0.3 graph files must not use top-level agents:; use resources:", ["agents"]);
     }
     if (graphObject.inputs && Object.keys(graphObject.inputs).length > 0) {
-      addError("forbidden_inputs", "Circuitry v0.2 graph files must not use top-level inputs:; use resources:", ["inputs"]);
+      addError("forbidden_inputs", "Circuitry v0.3 graph files must not use top-level inputs:; use resources:", ["inputs"]);
     }
     if (graphObject.nodes && graphObject.nodes.length > 0) {
-      addError("forbidden_nodes", "Circuitry v0.2 graph files must not use top-level nodes:; use resources:", ["nodes"]);
+      addError("forbidden_nodes", "Circuitry v0.3 graph files must not use top-level nodes:; use resources:", ["nodes"]);
     }
     if (graphObject.edges && graphObject.edges.length > 0) {
-      addError("forbidden_edges", "Circuitry v0.2 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+      addError("forbidden_edges", "Circuitry v0.3 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+    }
+    if (graphObject.links && graphObject.links.length > 0) {
+      addError("forbidden_links", "Circuitry v0.3 graph files must use imports: instead of links:", ["links"]);
     }
   }
   const normalized = normalizeCircuitryGraph(graphObject);
@@ -837,11 +840,71 @@ var NodeCircuitryHost = class {
       return { error: this.parseIssue(error, filename) };
     }
   }
+  async resolveGraphImports(graph, filename, standard, stack = []) {
+    const graphFile = path.resolve(filename);
+    if (stack.includes(graphFile)) {
+      throw new Error(`Circuitry graph import cycle: ${[...stack, graphFile].join(" -> ")}`);
+    }
+    const importedResources = {};
+    const aliasMap = {};
+    const nextStack = [...stack, graphFile];
+    for (const imp of graph.imports || []) {
+      const linkedFile = path.resolve(path.dirname(graphFile), imp.path);
+      const linkedText = await readFile(linkedFile, "utf8");
+      const parsed = parseCircuitryText(linkedText, linkedFile, standard, { validate: false });
+      const resolved = await this.resolveGraphImports(parsed, linkedFile, standard, nextStack);
+      const resourceId = imp.resource;
+      const resource = resolved.resources?.[resourceId];
+      if (!resource) {
+        throw new Error(`Imported resource not found: ${resourceId} in ${imp.path}`);
+      }
+      const localId = imp.as || resourceId;
+      if (importedResources[localId]) {
+        throw new Error(`Imported Circuitry resource id collision: ${localId} from ${imp.path}`);
+      }
+      if (imp.as) aliasMap[resourceId] = localId;
+      const resourceWithRewrittenInputs = this.rewriteImportInputs(resource, aliasMap);
+      importedResources[localId] = resourceWithRewrittenInputs;
+    }
+    return {
+      ...graph,
+      resources: {
+        ...importedResources,
+        ...graph.resources || {}
+      }
+    };
+  }
+  /** Rewrite inputs in imported resource to use aliased resource ids. */
+  rewriteImportInputs(resource, aliasMap) {
+    if (resource.type === "agent" || resource.type === "tool") {
+      const newInputs = (resource.inputs || []).map((input) => aliasMap[input] || input);
+      return { ...resource, inputs: newInputs };
+    }
+    return resource;
+  }
+  async parseAndResolveGraph(text, filename, standard) {
+    const parsed = this.parseGraphForValidation(text, filename, standard);
+    if (!parsed.graph) return parsed;
+    try {
+      return { graph: await this.resolveGraphImports(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);
@@ -853,8 +916,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],
@@ -865,7 +928,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
@@ -896,7 +959,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.33",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",