@darkhorseprojects/circuitry 0.2.99 → 0.3.1

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,427 @@
+#!/usr/bin/env node
+
+// src/node.ts
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// src/yaml.ts
+import YAML from "yaml";
+
+// src/graph.ts
+var CIRCUITRY_SPEC_VERSION = "0.3.1";
+var DEFAULT_CIRCUITRY_VALIDATION_RULES = [
+  "no-self-loops",
+  "no-unknown-edge-endpoints",
+  "require-executable-inputs",
+  "no-cycles"
+];
+var DEFAULT_CIRCUITRY_VALIDATION_STANDARD = {
+  version: CIRCUITRY_SPEC_VERSION,
+  requireSpecVersion: true,
+  rules: DEFAULT_CIRCUITRY_VALIDATION_RULES,
+  executableKinds: ["agent", "tool", "output"]
+};
+var executableKindsFromRules = (rules = []) => {
+  const executableRule = rules.find(
+    (entry) => typeof entry !== "string" && entry.rule === "require-executable-inputs"
+  );
+  return executableRule?.executableKinds;
+};
+var createCircuitryValidationStandard = (standard = {}, graph) => {
+  const rules = [
+    ...DEFAULT_CIRCUITRY_VALIDATION_RULES,
+    ...graph?.validation?.rules || [],
+    ...standard.rules || []
+  ];
+  return {
+    version: standard.version || DEFAULT_CIRCUITRY_VALIDATION_STANDARD.version,
+    requireSpecVersion: standard.requireSpecVersion ?? DEFAULT_CIRCUITRY_VALIDATION_STANDARD.requireSpecVersion,
+    rules,
+    executableKinds: standard.executableKinds || executableKindsFromRules(rules) || [
+      ...DEFAULT_CIRCUITRY_VALIDATION_STANDARD.executableKinds
+    ]
+  };
+};
+var expandResources = (resources) => {
+  const nodes = [];
+  const edges = [];
+  for (const [id, resource] of Object.entries(resources)) {
+    if (resource.type === "text") {
+      nodes.push({
+        id,
+        kind: "input",
+        label: resource.label || id,
+        input: { type: "text", value: resource.value }
+      });
+    } else if (resource.type === "agent") {
+      const agent = resource;
+      nodes.push({
+        id,
+        kind: "agent",
+        label: agent.label || agent.identity || id,
+        agent: {
+          identity: agent.identity || agent.label || id,
+          model: agent.model,
+          thinkingLevel: agent.thinkingLevel,
+          tools: agent.tools,
+          instructions: agent.instructions,
+          personality: agent.personality,
+          context: agent.context
+        },
+        skills: agent.skills,
+        expect: agent.expect
+      });
+      for (const inputRef of agent.inputs || []) {
+        edges.push({ from: inputRef, to: id, kind: "dependency" });
+      }
+    } else if (resource.type === "tool") {
+      const tool = resource;
+      nodes.push({
+        id,
+        kind: "tool",
+        label: tool.label || id,
+        agent: { instructions: tool.instructions }
+      });
+      for (const inputRef of tool.inputs || []) {
+        edges.push({ from: inputRef, to: id, kind: "dependency" });
+      }
+    } else {
+      const input = resource;
+      nodes.push({
+        id,
+        kind: "input",
+        label: input.label || id,
+        input: {
+          type: input.type,
+          value: input.value,
+          uri: input.uri || input.path,
+          mimeType: input.mimeType,
+          data: input.data
+        }
+      });
+    }
+  }
+  return { nodes, edges };
+};
+var normalizeCircuitryGraph = (graph) => {
+  if (!graph.resources || Object.keys(graph.resources).length === 0) return { ...graph };
+  const { nodes, edges } = expandResources(graph.resources);
+  return { ...graph, nodes, edges };
+};
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set([CIRCUITRY_SPEC_VERSION]);
+var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
+  const resolvedStandard = createCircuitryValidationStandard(
+    standard,
+    graph && typeof graph === "object" && !Array.isArray(graph) ? graph : void 0
+  );
+  const errors = [];
+  const addError = (code, message, path3) => errors.push({ code, message, ...path3 ? { path: path3 } : {} });
+  if (!graph || typeof graph !== "object" || Array.isArray(graph)) {
+    addError("invalid_graph", "Circuitry graph must be an object");
+    return { ok: false, errors, standard: resolvedStandard };
+  }
+  const graphObject = graph;
+  const rules = resolvedStandard.rules;
+  const hasRule = (name) => rules.some((entry) => (typeof entry === "string" ? entry : entry.rule) === name);
+  if (resolvedStandard.requireSpecVersion && !VALID_SPEC_VERSIONS.has(String(graphObject.circuitry))) {
+    addError(
+      "invalid_spec_version",
+      `Expected circuitry: "${CIRCUITRY_SPEC_VERSION}"`,
+      ["circuitry"]
+    );
+  }
+  if (options.sourceFormat) {
+    if (!graphObject.resources || Object.keys(graphObject.resources).length === 0) {
+      addError("missing_resources", "Circuitry graphs must use a resources: section", ["resources"]);
+    }
+    if (graphObject.agents && Object.keys(graphObject.agents).length > 0) {
+      addError("forbidden_agents", "Circuitry graph files must not use top-level agents:; use resources:", ["agents"]);
+    }
+    if (graphObject.inputs && Object.keys(graphObject.inputs).length > 0) {
+      addError("forbidden_inputs", "Circuitry graph files use args: for runtime arguments and resource inputs for edges", ["inputs"]);
+    }
+    if (graphObject.nodes && graphObject.nodes.length > 0) {
+      addError("forbidden_nodes", "Circuitry graph files must not use top-level nodes:; use resources:", ["nodes"]);
+    }
+    if (graphObject.edges && graphObject.edges.length > 0) {
+      addError("forbidden_edges", "Circuitry graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+    }
+    if (graphObject.links && graphObject.links.length > 0) {
+      addError("forbidden_links", "Circuitry graph files use imports: for multi-file graphs", ["links"]);
+    }
+  }
+  const normalized = normalizeCircuitryGraph(graphObject);
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, node] of (normalized.nodes || []).entries()) {
+    if (!node.id) {
+      addError("missing_node_id", "Node is missing id", ["nodes", index, "id"]);
+      continue;
+    }
+    if (ids.has(node.id)) {
+      addError("duplicate_node_id", `Duplicate node id: ${node.id}`, ["nodes", index, "id"]);
+    }
+    ids.add(node.id);
+    if (!node.kind) {
+      addError("missing_node_kind", `Node ${node.id} is missing kind`, ["nodes", index, "kind"]);
+    }
+  }
+  const adjacency = /* @__PURE__ */ new Map();
+  const incomingCount = /* @__PURE__ */ new Map();
+  for (const id of ids) {
+    adjacency.set(id, []);
+    incomingCount.set(id, 0);
+  }
+  for (const [index, edge] of (normalized.edges || []).entries()) {
+    if (!edge.from || !edge.to) {
+      addError("missing_edge_endpoint", "Edge is missing from/to", ["edges", index]);
+      continue;
+    }
+    if (hasRule("no-self-loops") && edge.from === edge.to) {
+      addError("self_loop", `Edge creates self loop: ${edge.from} -> ${edge.to}`, ["edges", index]);
+      continue;
+    }
+    if (hasRule("no-unknown-edge-endpoints") && !ids.has(edge.from)) {
+      addError("unknown_edge_source", `Edge references unknown source: ${edge.from}`, ["edges", index, "from"]);
+    }
+    if (hasRule("no-unknown-edge-endpoints") && !ids.has(edge.to)) {
+      addError("unknown_edge_target", `Edge references unknown target: ${edge.to}`, ["edges", index, "to"]);
+    }
+    if (ids.has(edge.from) && ids.has(edge.to)) {
+      adjacency.get(edge.from).push(edge.to);
+      incomingCount.set(edge.to, (incomingCount.get(edge.to) || 0) + 1);
+    }
+  }
+  const executableKinds = new Set(resolvedStandard.executableKinds);
+  if (hasRule("require-executable-inputs")) {
+    for (const [index, node] of (normalized.nodes || []).entries()) {
+      if (executableKinds.has(node.kind) && (incomingCount.get(node.id) || 0) === 0) {
+        addError("executable_without_inputs", `Executable node has no inputs: ${node.id}`, ["nodes", index]);
+      }
+    }
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const path2 = [];
+  let cycleMessage = "";
+  const visit = (id) => {
+    if (cycleMessage) return;
+    if (visiting.has(id)) {
+      cycleMessage = [...path2.slice(path2.indexOf(id)), id].join(" -> ");
+      return;
+    }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    path2.push(id);
+    for (const next of adjacency.get(id) || []) visit(next);
+    path2.pop();
+    visiting.delete(id);
+    visited.add(id);
+  };
+  if (hasRule("no-cycles")) {
+    for (const id of ids) {
+      visit(id);
+      if (cycleMessage) {
+        addError("cycle", `Graph contains cycle: ${cycleMessage}`);
+        break;
+      }
+    }
+  }
+  const additionalRules = rules.filter((rule) => {
+    if (typeof rule === "string") return false;
+    return rule.rule === "require-graph-field" || rule.rule === "require-node-field" || rule.rule === "require-edge-field" || rule.rule === "require-string" || rule.rule === "reject-string";
+  });
+  const fieldPath = (field) => field.split(".").filter(Boolean);
+  const getField = (value, field) => fieldPath(field).reduce((current, key) => {
+    if (!current || typeof current !== "object") return void 0;
+    return current[key];
+  }, value);
+  const isPresent = (value) => value !== void 0 && value !== null && value !== "";
+  for (const rule of additionalRules) {
+    if (rule.rule === "require-graph-field") {
+      if (!isPresent(getField(normalized, rule.field))) {
+        addError("missing_required_graph_field", `Graph is missing required field: ${rule.field}`, fieldPath(rule.field));
+      }
+      continue;
+    }
+    if (rule.rule === "require-node-field") {
+      const nodeKinds = new Set(rule.nodeKinds || []);
+      for (const [index, node] of (normalized.nodes || []).entries()) {
+        if (nodeKinds.size > 0 && !nodeKinds.has(node.kind)) continue;
+        if (!isPresent(getField(node, rule.field))) {
+          addError("missing_required_node_field", `Node ${node.id || "<missing id>"} is missing required field: ${rule.field}`, ["nodes", index, ...fieldPath(rule.field)]);
+        }
+      }
+      continue;
+    }
+    if (rule.rule === "require-edge-field") {
+      const edgeKinds = new Set(rule.edgeKinds || []);
+      for (const [index, edge] of (normalized.edges || []).entries()) {
+        if (edgeKinds.size > 0 && (!edge.kind || !edgeKinds.has(edge.kind))) continue;
+        if (!isPresent(getField(edge, rule.field))) {
+          addError("missing_required_edge_field", `Edge ${edge.id || index} is missing required field: ${rule.field}`, ["edges", index, ...fieldPath(rule.field)]);
+        }
+      }
+      continue;
+    }
+    const checkString = (target, subject, id, match, path3) => {
+      const value = getField(subject, match.field);
+      const text = typeof value === "string" ? value : "";
+      const includes = text.includes(match.value);
+      if (rule.rule === "require-string" && !includes) {
+        addError("missing_required_string", `${target} ${id} field ${match.field} must include string: ${match.value}`, path3);
+      }
+      if (rule.rule === "reject-string" && includes) {
+        addError("rejected_string", `${target} ${id} field ${match.field} must not include string: ${match.value}`, path3);
+      }
+    };
+    for (const match of rule.graph || []) checkString("graph", normalized, "<root>", match, fieldPath(match.field));
+    for (const match of rule.nodes || []) {
+      const nodeKinds = new Set(match.nodeKinds || []);
+      for (const [index, node] of (normalized.nodes || []).entries()) {
+        if (nodeKinds.size > 0 && !nodeKinds.has(node.kind)) continue;
+        checkString("node", node, node.id || "<missing id>", match, ["nodes", index, ...fieldPath(match.field)]);
+      }
+    }
+    for (const match of rule.edges || []) {
+      const edgeKinds = new Set(match.edgeKinds || []);
+      for (const [index, edge] of (normalized.edges || []).entries()) {
+        if (edgeKinds.size > 0 && (!edge.kind || !edgeKinds.has(edge.kind))) continue;
+        checkString("edge", edge, edge.id || String(index), match, ["edges", index, ...fieldPath(match.field)]);
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors, standard: resolvedStandard };
+};
+var validateCircuitryGraphWithStandard = (graph, standard = {}) => validateCircuitryGraphInternal(graph, standard, { sourceFormat: true });
+var validateCircuitryExecutionGraphWithStandard = (graph, standard = {}) => validateCircuitryGraphInternal(graph, standard, { sourceFormat: false });
+var validateCircuitryGraph = (graph, standard = {}) => validateCircuitryGraphWithStandard(graph, standard).errors.map(
+  (error) => error.message
+);
+var parseCircuitryJson = (text, standard = {}, options = {}) => {
+  let graph;
+  try {
+    graph = JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not parse Circuitry JSON. Check commas, quotes, and braces.
+${message}`);
+  }
+  if (options.validate === false) return graph;
+  const errors = validateCircuitryGraph(graph, standard);
+  if (errors.length) {
+    throw new Error(`Invalid Circuitry graph:
+${errors.join("\n")}`);
+  }
+  return normalizeCircuitryGraph(graph);
+};
+
+// src/yaml.ts
+var parseCircuitryYaml = (text, standard = {}, options = {}) => {
+  let graph;
+  try {
+    graph = YAML.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not parse Circuitry YAML. Check indentation and quotes.
+${message}`);
+  }
+  if (!graph || typeof graph !== "object" || Array.isArray(graph)) {
+    throw new Error("Could not parse Circuitry YAML. Expected a graph object.");
+  }
+  if (options.validate === false) return graph;
+  const errors = validateCircuitryGraph(graph, standard);
+  if (errors.length) {
+    throw new Error(`Invalid Circuitry graph:
+${errors.join("\n")}`);
+  }
+  return normalizeCircuitryGraph(graph);
+};
+var parseCircuitryText = (text, filename2 = "graph.circuitry.yaml", standard = {}, options = {}) => {
+  return filename2.endsWith(".json") ? parseCircuitryJson(text, standard, options) : parseCircuitryYaml(text, standard, options);
+};
+
+// src/node.ts
+var defaultFilename = "graph.circuitry.yaml";
+var resourceInputs = (resource) => "inputs" in resource && Array.isArray(resource.inputs) ? resource.inputs : [];
+var withResourceInputs = (resource, inputs) => "inputs" in resource ? { ...resource, inputs } : resource;
+var selectedImportResources = (imp, resources) => {
+  if (imp.resources === "*") return Object.fromEntries(Object.keys(resources).map((id) => [id, id]));
+  if (Array.isArray(imp.resources)) return Object.fromEntries(imp.resources.map((id) => [id, id]));
+  return imp.resources;
+};
+var importedId = (localId, prefix) => `${prefix || ""}${localId}`;
+var rewriteResourceInputs = (resource, aliasMap) => {
+  const inputs = resourceInputs(resource);
+  if (inputs.length === 0) return resource;
+  return withResourceInputs(resource, inputs.map((input) => aliasMap[input] || input));
+};
+var resolveCircuitryGraph = async (parsed, graphFile, text, standard, stack = []) => {
+  if (stack.includes(graphFile)) {
+    throw new Error(`Circuitry graph import cycle: ${[...stack, graphFile].join(" -> ")}`);
+  }
+  const nextStack = [...stack, graphFile];
+  const resources = {};
+  const origins = {};
+  for (const imp of parsed.imports || []) {
+    const linkedFile = path.resolve(path.dirname(graphFile), imp.path);
+    const loaded = await loadCircuitryGraphFile(linkedFile, standard, nextStack);
+    const available = loaded.graph.resources || {};
+    const aliases = selectedImportResources(imp, available);
+    const aliasMap = {};
+    for (const [sourceId, localId] of Object.entries(aliases)) aliasMap[sourceId] = importedId(localId, imp.prefix);
+    for (const [sourceId, localId] of Object.entries(aliases)) {
+      const resource = available[sourceId];
+      if (!resource) throw new Error(`Imported resource not found: ${sourceId} in ${imp.path}`);
+      const nextId = importedId(localId, imp.prefix);
+      if (resources[nextId]) throw new Error(`Imported Circuitry resource id collision: ${nextId} from ${imp.path}`);
+      resources[nextId] = rewriteResourceInputs(resource, aliasMap);
+      origins[nextId] = loaded.origins[sourceId] || linkedFile;
+    }
+  }
+  for (const [id, resource] of Object.entries(parsed.resources || {})) {
+    if (resources[id]) throw new Error(`Circuitry resource id collision: ${id} in ${graphFile}`);
+    resources[id] = resource;
+    origins[id] = graphFile;
+  }
+  const graph = normalizeCircuitryGraph({ ...parsed, imports: [], resources });
+  if (stack.length === 0) {
+    const validation = validateCircuitryExecutionGraphWithStandard(graph, standard);
+    if (validation.errors.length) {
+      throw new Error(`Invalid Circuitry graph:
+${validation.errors.map((e) => e.message).join("\n")}`);
+    }
+  }
+  return { filename: graphFile, text, graph, origins };
+};
+var loadCircuitryGraphFile = async (filename2 = defaultFilename, standard, stack = []) => {
+  const graphFile = path.resolve(process.cwd(), filename2);
+  const text = await readFile(graphFile, "utf8");
+  const parsed = parseCircuitryText(text, graphFile, standard, { validate: false });
+  return resolveCircuitryGraph(parsed, graphFile, text, standard, stack);
+};
+
+// src/cli.ts
+var [, , command, filename] = process.argv;
+var usage = () => {
+  console.error("usage: circuitry <check|normalize> <graph.circuitry.yaml>");
+  process.exit(2);
+};
+if (!command || !filename) usage();
+try {
+  const loaded = await loadCircuitryGraphFile(filename);
+  if (command === "check") {
+    const result = validateCircuitryExecutionGraphWithStandard(loaded.graph);
+    if (!result.ok) {
+      console.error(result.errors.map((error) => error.message).join("\n"));
+      process.exit(1);
+    }
+    console.log(`ok: ${loaded.filename}`);
+  } else if (command === "normalize") {
+    console.log(JSON.stringify({ graph: loaded.graph, origins: loaded.origins }, null, 2));
+  } else {
+    usage();
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/graph.d.ts

@@ -1,5 +1,5 @@
-export declare const CIRCUITRY_SPEC_VERSION: "0.2.99";
-export type CircuitrySpecVersion = typeof CIRCUITRY_SPEC_VERSION | "0.2";
+export declare const CIRCUITRY_SPEC_VERSION: "0.3.1";
+export type CircuitrySpecVersion = typeof CIRCUITRY_SPEC_VERSION;
 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;
@@ -89,7 +89,16 @@ export type CircuitryResourceTool = {
     inputs?: string[];
     instructions?: string;
 };
-export type CircuitryResourceEntry = CircuitryResourceText | CircuitryResourceAgent | CircuitryResourceTool;
+export type CircuitryResourceData = {
+    type: CircuitryInputKind;
+    value?: string;
+    uri?: string;
+    path?: string;
+    mimeType?: string;
+    label?: string;
+    data?: Record<string, unknown>;
+};
+export type CircuitryResourceEntry = CircuitryResourceText | CircuitryResourceAgent | CircuitryResourceTool | CircuitryResourceData;
 export type CircuitrySandboxProvider = "local" | "docker" | "e2b" | "daytona" | "cloudflare" | "modal" | "openai" | (string & {});
 export type CircuitrySandboxClient = {
     provider: CircuitrySandboxProvider;
@@ -161,6 +170,14 @@ export type CircuitryValidationRuleEntry = CircuitryBuiltInValidationRule | {
 export type CircuitryGraphValidation = {
     rules?: CircuitryValidationRuleEntry[];
 };
+export type CircuitryGraphArg = {
+    type: CircuitryInputKind;
+    required?: boolean;
+    label?: string;
+    description?: string;
+    default?: unknown;
+    mimeType?: string;
+};
 export type CircuitryRuntimeInputs = Record<string, unknown>;
 /**
  * Return a graph copy with runtime input values applied to existing text inputs.
@@ -170,29 +187,32 @@ 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 | {
+/** 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;
-    /** Optional id prefix applied to imported resources. */
+    /** Import all resources, a resource list, or an old->new resource id map. */
+    resources: "*" | string[] | Record<string, string>;
+    /** Optional namespace applied to imported resource ids and their internal refs. */
     prefix?: string;
 };
 export type CircuitryGraph = {
-    /** Spec version. Use "0.2.99" for linked graph files. */
+    /** Spec version. */
     circuitry: CircuitrySpecVersion | string;
     id?: string;
     title?: string;
     description?: string;
-    /** Files whose resources are merged into this graph before validation/execution. */
-    links?: CircuitryGraphLink[];
+    /** Explicit imports of resources from other graph files. */
+    imports?: CircuitryImport[];
+    /** Runtime call contract. Args bind to resources with matching ids. */
+    args?: Record<string, CircuitryGraphArg>;
     resources?: Record<string, CircuitryResourceEntry>;
     /** Internal normalized execution nodes. Authored graph files must not set this. */
     nodes?: CircuitryNode[];
     /** Internal normalized execution edges. Authored graph files must not set this. */
     edges?: CircuitryEdge[];
-    /** Forbidden in authored v0.2 graph files. */
+    /** Forbidden in authored graph files. */
     agents?: never;
-    /** Forbidden in authored v0.2 graph files. */
-    inputs?: never;
     runtime?: CircuitryRuntime;
     validation?: CircuitryGraphValidation;
     metadata?: Record<string, unknown>;
@@ -223,7 +243,7 @@ export type CircuitryValidationResult = {
 };
 export declare const DEFAULT_CIRCUITRY_VALIDATION_RULES: CircuitryValidationRuleEntry[];
 export declare const DEFAULT_CIRCUITRY_VALIDATION_STANDARD: {
-    readonly version: "0.2.99";
+    readonly version: "0.3.1";
     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.99";
+var CIRCUITRY_SPEC_VERSION = "0.3.1";
 var runtimeInputToText = (value) => {
   if (typeof value === "string") return value;
   if (value === void 0) return "";
@@ -98,35 +98,51 @@ var expandResources = (resources) => {
         input: { type: "text", value: resource.value }
       });
     } else if (resource.type === "agent") {
+      const agent = resource;
       nodes.push({
         id,
         kind: "agent",
-        label: resource.label || resource.identity || id,
+        label: agent.label || agent.identity || id,
         agent: {
-          identity: resource.identity || resource.label || id,
-          model: resource.model,
-          thinkingLevel: resource.thinkingLevel,
-          tools: resource.tools,
-          instructions: resource.instructions,
-          personality: resource.personality,
-          context: resource.context
+          identity: agent.identity || agent.label || id,
+          model: agent.model,
+          thinkingLevel: agent.thinkingLevel,
+          tools: agent.tools,
+          instructions: agent.instructions,
+          personality: agent.personality,
+          context: agent.context
         },
-        skills: resource.skills,
-        expect: resource.expect
+        skills: agent.skills,
+        expect: agent.expect
       });
-      for (const inputRef of resource.inputs || []) {
+      for (const inputRef of agent.inputs || []) {
         edges.push({ from: inputRef, to: id, kind: "dependency" });
       }
     } else if (resource.type === "tool") {
+      const tool = resource;
       nodes.push({
         id,
         kind: "tool",
-        label: resource.label || id,
-        agent: { instructions: resource.instructions }
+        label: tool.label || id,
+        agent: { instructions: tool.instructions }
       });
-      for (const inputRef of resource.inputs || []) {
+      for (const inputRef of tool.inputs || []) {
         edges.push({ from: inputRef, to: id, kind: "dependency" });
       }
+    } else {
+      const input = resource;
+      nodes.push({
+        id,
+        kind: "input",
+        label: input.label || id,
+        input: {
+          type: input.type,
+          value: input.value,
+          uri: input.uri || input.path,
+          mimeType: input.mimeType,
+          data: input.data
+        }
+      });
     }
   }
   return { nodes, edges };
@@ -136,7 +152,7 @@ var normalizeCircuitryGraph = (graph) => {
   const { nodes, edges } = expandResources(graph.resources);
   return { ...graph, nodes, edges };
 };
-var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.2", CIRCUITRY_SPEC_VERSION]);
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set([CIRCUITRY_SPEC_VERSION]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -160,19 +176,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 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 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 graph files use args: for runtime arguments and resource inputs for edges", ["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 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 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+    }
+    if (graphObject.links && graphObject.links.length > 0) {
+      addError("forbidden_links", "Circuitry graph files use imports: for multi-file graphs", ["links"]);
     }
   }
   const normalized = normalizeCircuitryGraph(graphObject);

package/dist/node.d.ts

@@ -2,17 +2,20 @@ import type { CircuitryHost } from "./host";
 import type { CircuitryGraph, CircuitryRuntimeInputs, CircuitryValidationStandard } from "./graph";
 import type { NodeExecutionRequest, NodeExecutionResult, SimulationRunItem } from "./simulation";
 export declare const runNodeWithPiSDK: ({ model, prompt, images, tools, thinkingLevel, }: NodeExecutionRequest) => Promise<NodeExecutionResult>;
+export type CircuitryResourceOrigins = Record<string, string>;
+export type LoadedCircuitryGraph = {
+    filename: string;
+    text: string;
+    graph: CircuitryGraph;
+    origins: CircuitryResourceOrigins;
+};
+export declare const loadCircuitryGraphFile: (filename?: string, standard?: CircuitryValidationStandard, stack?: string[]) => Promise<LoadedCircuitryGraph>;
 export declare class NodeCircuitryHost implements CircuitryHost {
     private resolveGraphFile;
     private runFileFor;
     private exists;
     private parseIssue;
     private parseGraphForValidation;
-    private linkPath;
-    private linkPrefix;
-    private prefixResourceIds;
-    private mergeResources;
-    private resolveGraphLinks;
     private parseAndResolveGraph;
     private readGraphFile;
     readGraph(input?: {

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.99";
+var CIRCUITRY_SPEC_VERSION = "0.3.1";
 var runtimeInputToText = (value) => {
   if (typeof value === "string") return value;
   if (value === void 0) return "";
@@ -79,35 +79,51 @@ var expandResources = (resources) => {
         input: { type: "text", value: resource.value }
       });
     } else if (resource.type === "agent") {
+      const agent = resource;
       nodes.push({
         id,
         kind: "agent",
-        label: resource.label || resource.identity || id,
+        label: agent.label || agent.identity || id,
         agent: {
-          identity: resource.identity || resource.label || id,
-          model: resource.model,
-          thinkingLevel: resource.thinkingLevel,
-          tools: resource.tools,
-          instructions: resource.instructions,
-          personality: resource.personality,
-          context: resource.context
+          identity: agent.identity || agent.label || id,
+          model: agent.model,
+          thinkingLevel: agent.thinkingLevel,
+          tools: agent.tools,
+          instructions: agent.instructions,
+          personality: agent.personality,
+          context: agent.context
         },
-        skills: resource.skills,
-        expect: resource.expect
+        skills: agent.skills,
+        expect: agent.expect
       });
-      for (const inputRef of resource.inputs || []) {
+      for (const inputRef of agent.inputs || []) {
         edges.push({ from: inputRef, to: id, kind: "dependency" });
       }
     } else if (resource.type === "tool") {
+      const tool = resource;
       nodes.push({
         id,
         kind: "tool",
-        label: resource.label || id,
-        agent: { instructions: resource.instructions }
+        label: tool.label || id,
+        agent: { instructions: tool.instructions }
       });
-      for (const inputRef of resource.inputs || []) {
+      for (const inputRef of tool.inputs || []) {
         edges.push({ from: inputRef, to: id, kind: "dependency" });
       }
+    } else {
+      const input = resource;
+      nodes.push({
+        id,
+        kind: "input",
+        label: input.label || id,
+        input: {
+          type: input.type,
+          value: input.value,
+          uri: input.uri || input.path,
+          mimeType: input.mimeType,
+          data: input.data
+        }
+      });
     }
   }
   return { nodes, edges };
@@ -117,7 +133,7 @@ var normalizeCircuitryGraph = (graph) => {
   const { nodes, edges } = expandResources(graph.resources);
   return { ...graph, nodes, edges };
 };
-var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.2", CIRCUITRY_SPEC_VERSION]);
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set([CIRCUITRY_SPEC_VERSION]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -141,19 +157,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 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 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 graph files use args: for runtime arguments and resource inputs for edges", ["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 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 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+    }
+    if (graphObject.links && graphObject.links.length > 0) {
+      addError("forbidden_links", "Circuitry graph files use imports: for multi-file graphs", ["links"]);
     }
   }
   const normalized = normalizeCircuitryGraph(graphObject);
@@ -801,6 +820,63 @@ var runNodeWithPiSDK = async ({
   }
 };
 var defaultFilename = "graph.circuitry.yaml";
+var resourceInputs = (resource) => "inputs" in resource && Array.isArray(resource.inputs) ? resource.inputs : [];
+var withResourceInputs = (resource, inputs) => "inputs" in resource ? { ...resource, inputs } : resource;
+var selectedImportResources = (imp, resources) => {
+  if (imp.resources === "*") return Object.fromEntries(Object.keys(resources).map((id) => [id, id]));
+  if (Array.isArray(imp.resources)) return Object.fromEntries(imp.resources.map((id) => [id, id]));
+  return imp.resources;
+};
+var importedId = (localId, prefix) => `${prefix || ""}${localId}`;
+var rewriteResourceInputs = (resource, aliasMap) => {
+  const inputs = resourceInputs(resource);
+  if (inputs.length === 0) return resource;
+  return withResourceInputs(resource, inputs.map((input) => aliasMap[input] || input));
+};
+var resolveCircuitryGraph = async (parsed, graphFile, text, standard, stack = []) => {
+  if (stack.includes(graphFile)) {
+    throw new Error(`Circuitry graph import cycle: ${[...stack, graphFile].join(" -> ")}`);
+  }
+  const nextStack = [...stack, graphFile];
+  const resources = {};
+  const origins = {};
+  for (const imp of parsed.imports || []) {
+    const linkedFile = path.resolve(path.dirname(graphFile), imp.path);
+    const loaded = await loadCircuitryGraphFile(linkedFile, standard, nextStack);
+    const available = loaded.graph.resources || {};
+    const aliases = selectedImportResources(imp, available);
+    const aliasMap = {};
+    for (const [sourceId, localId] of Object.entries(aliases)) aliasMap[sourceId] = importedId(localId, imp.prefix);
+    for (const [sourceId, localId] of Object.entries(aliases)) {
+      const resource = available[sourceId];
+      if (!resource) throw new Error(`Imported resource not found: ${sourceId} in ${imp.path}`);
+      const nextId = importedId(localId, imp.prefix);
+      if (resources[nextId]) throw new Error(`Imported Circuitry resource id collision: ${nextId} from ${imp.path}`);
+      resources[nextId] = rewriteResourceInputs(resource, aliasMap);
+      origins[nextId] = loaded.origins[sourceId] || linkedFile;
+    }
+  }
+  for (const [id, resource] of Object.entries(parsed.resources || {})) {
+    if (resources[id]) throw new Error(`Circuitry resource id collision: ${id} in ${graphFile}`);
+    resources[id] = resource;
+    origins[id] = graphFile;
+  }
+  const graph = normalizeCircuitryGraph({ ...parsed, imports: [], resources });
+  if (stack.length === 0) {
+    const validation = validateCircuitryExecutionGraphWithStandard(graph, standard);
+    if (validation.errors.length) {
+      throw new Error(`Invalid Circuitry graph:
+${validation.errors.map((e) => e.message).join("\n")}`);
+    }
+  }
+  return { filename: graphFile, text, graph, origins };
+};
+var loadCircuitryGraphFile = async (filename = defaultFilename, standard, stack = []) => {
+  const graphFile = path.resolve(process.cwd(), filename);
+  const text = await readFile(graphFile, "utf8");
+  const parsed = parseCircuitryText(text, graphFile, standard, { validate: false });
+  return resolveCircuitryGraph(parsed, graphFile, text, standard, stack);
+};
 var NodeCircuitryHost = class {
   resolveGraphFile(filename) {
     return path.resolve(
@@ -837,84 +913,19 @@ 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) };
+      const graphFile = path.resolve(process.cwd(), filename);
+      const source = text || "";
+      const parsed = parseCircuitryText(source, graphFile, standard, { validate: false });
+      return { graph: (await resolveCircuitryGraph(parsed, graphFile, source, standard)).graph };
     } catch (error) {
       return { error: this.parseIssue(error, filename) };
     }
   }
   async readGraphFile(filename) {
-    const graphFile = this.resolveGraphFile(filename);
-    const text = await readFile(graphFile, "utf8");
-    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) };
+    const loaded = await loadCircuitryGraphFile(this.resolveGraphFile(filename));
+    return { graphFile: loaded.filename, text: loaded.text, graph: loaded.graph, origins: loaded.origins };
   }
   async readGraph(input = {}) {
     const { graphFile, text, graph } = await this.readGraphFile(input.filename);
@@ -927,10 +938,10 @@ ${validation.errors.map((e) => e.message).join("\n")}`
       return validateCircuitryGraphWithStandard(input.graph, input.standard);
     const filename = input.filename || defaultFilename;
     const parsed = await this.parseAndResolveGraph(input.text, filename, input.standard);
-    if ("error" in parsed) {
+    if (!("graph" in parsed)) {
       return {
         ok: false,
-        errors: [parsed.error],
+        errors: parsed.error ? [parsed.error] : [],
         standard: validateCircuitryGraphWithStandard({}, input.standard).standard
       };
     }
@@ -943,11 +954,12 @@ ${validation.errors.map((e) => e.message).join("\n")}`
       input.filename || graphFile,
       input.standard
     );
-    if (!parsed.graph)
+    if (!("graph" in parsed))
       throw new Error(`Invalid Circuitry graph:
 ${parsed.error?.message}`);
+    const graph = parsed.graph;
     const validation = await this.validateGraph({
-      graph: parsed.graph,
+      graph,
       standard: input.standard
     });
     if (validation.errors.length)
@@ -957,12 +969,12 @@ ${validation.errors.map((e) => e.message).join("\n")}`
       );
     await writeFile(
       graphFile,
-      stringifyCircuitryText(parsed.graph, graphFile),
+      stringifyCircuitryText(graph, graphFile),
       "utf8"
     );
     return {
       filename: graphFile,
-      graph: parsed.graph,
+      graph,
       mode: "replace"
     };
   }
@@ -1004,5 +1016,6 @@ ${validation.errors.map((e) => e.message).join("\n")}`
 };
 export {
   NodeCircuitryHost,
+  loadCircuitryGraphFile,
   runNodeWithPiSDK
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkhorseprojects/circuitry",
-  "version": "0.2.99",
+  "version": "0.3.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,6 +14,9 @@
       "import": "./dist/node.js"
     }
   },
+  "bin": {
+    "circuitry": "./dist/cli.js"
+  },
   "license": "LGPL-3.0-only",
   "files": [
     "dist",