@darkhorseprojects/circuitry 0.3.0 → 0.3.2

package/dist/bundle.d.ts

@@ -16,13 +16,14 @@ type SceneElement = {
         elementId?: string;
     } | null;
 };
-export declare const BUNDLE_MIME = "application/vnd.circuitry.bundle+json";
+export declare const BUNDLE_MIME = "application/vnd.circuitry.bundle+yaml";
 export type CircuitryBundle = {
     version: 1;
     createdAt: string;
     elements: SceneElement[];
 };
 export declare const createBundleFromSelection: (elements: readonly SceneElement[], selectedIds: Readonly<Record<string, true>>) => CircuitryBundle | null;
+export declare const stringifyBundle: (bundle: CircuitryBundle) => string;
 export declare const parseBundleText: (text: string) => CircuitryBundle;
 export declare const importBundleElements: (bundle: CircuitryBundle, opts?: {
     offsetX?: number;

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFile as readFile2 } from "node:fs/promises";
+
+// src/node.ts
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// src/yaml.ts
+import YAML2 from "yaml";
+
+// src/graph.ts
+import YAML from "yaml";
+var CIRCUITRY_SPEC_VERSION = "0.3.2";
+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 ruleName = (rule) => typeof rule === "string" ? rule : rule.rule;
+var executableKindsFromRules = (rules) => rules.find((rule) => typeof rule !== "string" && rule.rule === "require-executable-inputs")?.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,
+          tools: agent.tools,
+          instructions: agent.instructions,
+          personality: agent.personality,
+          context: agent.context
+        },
+        skills: agent.skills,
+        expect: agent.expect
+      });
+      for (const input of agent.inputs || []) edges.push({ from: input, 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 input of tool.inputs || []) edges.push({ from: input, 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) return { ...graph };
+  return { ...graph, ...expandResources(graph.resources) };
+};
+var validateCircuitryGraphInternal = (graph, standard = {}, source) => {
+  const resolved = createCircuitryValidationStandard(standard, graph && typeof graph === "object" && !Array.isArray(graph) ? graph : void 0);
+  const errors = [];
+  const issue = (code, message = code, path2) => errors.push({ code, message, ...path2 ? { path: path2 } : {} });
+  if (!graph || typeof graph !== "object" || Array.isArray(graph)) return { ok: false, errors: [{ code: "invalid_graph", message: "invalid graph" }], standard: resolved };
+  const g = graph;
+  if (resolved.requireSpecVersion && g.circuitry !== resolved.version) issue("invalid_version", "invalid version", ["circuitry"]);
+  if (source) {
+    const raw = g;
+    if (!g.resources || Object.keys(g.resources).length === 0) issue("missing_resources", "missing resources", ["resources"]);
+    if (raw.agents) issue("forbidden_agents", "forbidden agents", ["agents"]);
+    if (raw.inputs) issue("forbidden_inputs", "forbidden inputs", ["inputs"]);
+    if (g.nodes?.length) issue("forbidden_nodes", "forbidden nodes", ["nodes"]);
+    if (g.edges?.length) issue("forbidden_edges", "forbidden edges", ["edges"]);
+    if (raw.links) issue("forbidden_links", "forbidden links", ["links"]);
+  }
+  const rules = new Set(resolved.rules.map(ruleName));
+  const normalized = normalizeCircuitryGraph(g);
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, node] of (normalized.nodes || []).entries()) {
+    if (!node.id) {
+      issue("missing_node_id", "missing node id", ["nodes", index, "id"]);
+      continue;
+    }
+    if (ids.has(node.id)) issue("duplicate_node_id", "duplicate node id", ["nodes", index, "id"]);
+    ids.add(node.id);
+    if (!node.kind) issue("missing_node_kind", "missing node kind", ["nodes", index, "kind"]);
+  }
+  const adjacency = /* @__PURE__ */ new Map();
+  const incoming = /* @__PURE__ */ new Map();
+  for (const id of ids) {
+    adjacency.set(id, []);
+    incoming.set(id, 0);
+  }
+  for (const [index, edge] of (normalized.edges || []).entries()) {
+    if (!edge.from || !edge.to) {
+      issue("missing_edge_endpoint", "missing edge endpoint", ["edges", index]);
+      continue;
+    }
+    if (rules.has("no-self-loops") && edge.from === edge.to) {
+      issue("self_loop", "self loop", ["edges", index]);
+      continue;
+    }
+    const ok = ids.has(edge.from) && ids.has(edge.to);
+    if (rules.has("no-unknown-edge-endpoints")) {
+      if (!ids.has(edge.from)) issue("unknown_edge_source", "unknown edge source", ["edges", index, "from"]);
+      if (!ids.has(edge.to)) issue("unknown_edge_target", "unknown edge target", ["edges", index, "to"]);
+    }
+    if (ok) {
+      adjacency.get(edge.from).push(edge.to);
+      incoming.set(edge.to, (incoming.get(edge.to) || 0) + 1);
+    }
+  }
+  if (rules.has("require-executable-inputs")) {
+    const executable = new Set(resolved.executableKinds);
+    for (const [index, node] of (normalized.nodes || []).entries()) {
+      if (executable.has(node.kind) && (incoming.get(node.id) || 0) === 0) issue("missing_executable_input", "missing executable input", ["nodes", index]);
+    }
+  }
+  if (rules.has("no-cycles")) {
+    const visiting = /* @__PURE__ */ new Set();
+    const visited = /* @__PURE__ */ new Set();
+    const visit = (id) => {
+      if (visiting.has(id)) return true;
+      if (visited.has(id)) return false;
+      visiting.add(id);
+      for (const next of adjacency.get(id) || []) if (visit(next)) return true;
+      visiting.delete(id);
+      visited.add(id);
+      return false;
+    };
+    for (const id of ids) if (visit(id)) {
+      issue("cycle", "cycle");
+      break;
+    }
+  }
+  return { ok: errors.length === 0, errors, standard: resolved };
+};
+var validateCircuitryGraphWithStandard = (graph, standard = {}) => validateCircuitryGraphInternal(graph, standard, true);
+var validateCircuitryExecutionGraphWithStandard = (graph, standard = {}) => validateCircuitryGraphInternal(graph, standard, false);
+var validateCircuitryGraph = (graph, standard = {}) => validateCircuitryGraphWithStandard(graph, standard).errors.map((error) => error.message);
+
+// src/yaml.ts
+var parseYamlData = (text) => {
+  try {
+    return YAML2.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not parse YAML.
+${message}`);
+  }
+};
+var stringifyYamlData = (value) => YAML2.stringify(value);
+var parseCircuitryYaml = (text, standard = {}, options = {}) => {
+  const graph = parseYamlData(text);
+  if (!graph || typeof graph !== "object" || Array.isArray(graph)) {
+    throw new Error("Circuitry YAML must be a graph object.");
+  }
+  if (options.validate !== false) {
+    const errors = validateCircuitryGraph(graph, standard);
+    if (errors.length) throw new Error(`Invalid Circuitry graph:
+${errors.join("\n")}`);
+  }
+  return graph;
+};
+var parseCircuitryText = (text, standard = {}, options = {}) => parseCircuitryYaml(text, standard, options);
+
+// src/scheduler.ts
+import YAML3 from "yaml";
+
+// 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, 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|parse> <file.yaml>");
+  process.exit(2);
+};
+if (!command || !filename) usage();
+try {
+  if (command === "parse") {
+    const text = await readFile2(filename, "utf8");
+    process.stdout.write(stringifyYamlData(parseYamlData(text)));
+  } else {
+    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") {
+      process.stdout.write(stringifyYamlData({ circuitryBundle: CIRCUITRY_SPEC_VERSION, graph: loaded.graph, origins: loaded.origins }));
+    } else {
+      usage();
+    }
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/graph.d.ts

@@ -1,13 +1,12 @@
-export declare const CIRCUITRY_SPEC_VERSION: "0.3.0";
-export type CircuitrySpecVersion = typeof CIRCUITRY_SPEC_VERSION | "0.2";
+export declare const CIRCUITRY_SPEC_VERSION: "0.3.2";
+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 CircuitryEdgeKind = "dependency" | "context" | "message" | "control" | string;
 export type CircuitryInputKind = "text" | "file" | "url" | "image" | "uri" | "canvas" | "mcp" | string;
 export type CircuitryAgent = {
     uses?: string;
     model?: string;
     tools?: string[];
-    thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
     identity?: string;
     personality?: string;
     instructions?: string;
@@ -51,9 +50,7 @@ export type CircuitryEdge = {
 export type CircuitryExpectFieldType = "str" | "int" | "float" | "bool" | "list" | "dict" | (string & {});
 export type CircuitryExpectField = {
     type: CircuitryExpectFieldType;
-    /** Optional substring that must appear in the string value. */
     contains?: string;
-    /** For list fields: shape of each item. */
     items?: CircuitryExpectSchema | CircuitryExpectFieldType;
     optional?: boolean;
 };
@@ -70,14 +67,9 @@ export type CircuitryResourceAgent = {
     identity?: string;
     label?: string;
     model?: string;
-    thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
-    /** References to other resource ids that feed this agent. */
     inputs?: string[];
-    /** Per-resource tool whitelist. */
     tools?: string[];
-    /** Per-resource skill whitelist. */
     skills?: string[];
-    /** Expected output schema — stored as metadata, used for optional validation. */
     expect?: CircuitryExpectSchema;
     instructions?: string;
     personality?: string;
@@ -89,7 +81,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;
@@ -126,80 +127,47 @@ export type CircuitryRuntime = {
     permissions?: Record<string, unknown>;
 };
 export type CircuitryBuiltInValidationRule = "no-self-loops" | "no-unknown-edge-endpoints" | "require-executable-inputs" | "no-cycles";
-export type CircuitryStringValidationMatch = {
-    field: string;
-    value: string;
-    nodeKinds?: string[];
-    edgeKinds?: string[];
-};
-export type CircuitryAdditionalValidationRule = {
-    rule: "require-graph-field";
-    field: string;
-} | {
-    rule: "require-node-field";
-    field: string;
-    nodeKinds?: string[];
-} | {
-    rule: "require-edge-field";
-    field: string;
-    edgeKinds?: string[];
-} | {
-    rule: "require-string";
-    graph?: CircuitryStringValidationMatch[];
-    nodes?: CircuitryStringValidationMatch[];
-    edges?: CircuitryStringValidationMatch[];
-} | {
-    rule: "reject-string";
-    graph?: CircuitryStringValidationMatch[];
-    nodes?: CircuitryStringValidationMatch[];
-    edges?: CircuitryStringValidationMatch[];
-};
 export type CircuitryValidationRuleEntry = CircuitryBuiltInValidationRule | {
-    rule: CircuitryBuiltInValidationRule;
+    rule: "require-executable-inputs";
     executableKinds?: string[];
-} | CircuitryAdditionalValidationRule;
+};
 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.
- *
- * Runtime inputs are execution-time args for graph programs: small overlays on
- * declared text inputs. They must target declared input resources; this keeps
- * 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;
+    resources: "*" | string[] | Record<string, string>;
+    prefix?: string;
 };
 export type CircuitryGraph = {
-    /** 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[];
+    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. */
     agents?: never;
-    /** Forbidden in authored v0.2 graph files. */
-    inputs?: never;
     runtime?: CircuitryRuntime;
     validation?: CircuitryGraphValidation;
     metadata?: Record<string, unknown>;
 };
+export type LoadedCircuitryBundle = {
+    circuitryBundle: CircuitrySpecVersion;
+    graph: CircuitryGraph;
+    origins: Record<string, string>;
+};
 export type CircuitryAgentPreset = {
     name: string;
     description?: string;
@@ -226,18 +194,15 @@ export type CircuitryValidationResult = {
 };
 export declare const DEFAULT_CIRCUITRY_VALIDATION_RULES: CircuitryValidationRuleEntry[];
 export declare const DEFAULT_CIRCUITRY_VALIDATION_STANDARD: {
-    readonly version: "0.3.0";
+    readonly version: "0.3.2";
     readonly requireSpecVersion: true;
     readonly rules: CircuitryValidationRuleEntry[];
     readonly executableKinds: ["agent", "tool", "output"];
 };
+export declare const applyCircuitryRuntimeInputs: (graph: CircuitryGraph, inputs?: CircuitryRuntimeInputs) => CircuitryGraph;
 export declare const createCircuitryValidationStandard: (standard?: CircuitryValidationStandard, graph?: CircuitryGraph) => Required<CircuitryValidationStandard>;
 export declare const normalizeCircuitryGraph: (graph: CircuitryGraph) => CircuitryGraph;
 export declare const validateCircuitryGraphWithStandard: (graph: unknown, standard?: CircuitryValidationStandard) => CircuitryValidationResult;
 export declare const validateCircuitryExecutionGraphWithStandard: (graph: unknown, standard?: CircuitryValidationStandard) => CircuitryValidationResult;
 export declare const validateCircuitryGraph: (graph: unknown, standard?: CircuitryValidationStandard) => string[];
-export declare const parseCircuitryJson: (text: string, standard?: CircuitryValidationStandard, options?: {
-    validate?: boolean;
-}) => CircuitryGraph;
-export declare const stringifyCircuitryJson: (graph: CircuitryGraph) => string;
 export declare const isUriInput: (input: CircuitryInput | Omit<CircuitryInput, "id">) => boolean;