@foresthubai/workflow-core 0.4.6 → 0.4.7

package/src/api/workflow.ts

@@ -8,7 +8,7 @@ export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
         /** @enum {string} */
-        DataType: "int" | "float" | "bool" | "string";
+        DataType: "int" | "float" | "bool" | "string" | "image";
         /** @enum {string} */
         SignalType: "digital" | "analog";
         /** @enum {string} */
@@ -145,7 +145,7 @@ export interface components {
              */
             mode: "r" | "rw";
         };
-        Model: components["schemas"]["LLMModel"];
+        Model: components["schemas"]["LLMModel"] | components["schemas"]["MLModel"];
         /** @description A custom or self-hosted language model that agent nodes can reference. */
         LLMModel: {
             /**
@@ -160,7 +160,19 @@ export interface components {
             /** @description Capabilities this model supports. */
             capabilities: components["schemas"]["ModelCapability"][];
         };
-        Node: components["schemas"]["ReadPinNode"] | components["schemas"]["WritePinNode"] | components["schemas"]["AgentNode"] | components["schemas"]["IfNode"] | components["schemas"]["SerialReadNode"] | components["schemas"]["SerialWriteNode"] | components["schemas"]["RetrieverNode"] | components["schemas"]["WebFetchNode"] | components["schemas"]["FunctionCallNode"] | components["schemas"]["OnFunctionCallNode"] | components["schemas"]["DelayNode"] | components["schemas"]["TickerNode"] | components["schemas"]["AlarmNode"] | components["schemas"]["WebSearchToolNode"] | components["schemas"]["OnStartupNode"] | components["schemas"]["OnPinEdgeNode"] | components["schemas"]["OnSerialReceiveNode"] | components["schemas"]["OnThresholdNode"] | components["schemas"]["SetVariableNode"] | components["schemas"]["MqttPublishNode"] | components["schemas"]["OnMqttMessageNode"];
+        /** @description A machine-learning model, served by an inference component, that nodes can reference. */
+        MLModel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "MLModel";
+            /** @description Stable identifier; this is the model name nodes reference and the component selects on. */
+            id: string;
+            /** @description Display name. */
+            label: string;
+        };
+        Node: components["schemas"]["ReadPinNode"] | components["schemas"]["WritePinNode"] | components["schemas"]["AgentNode"] | components["schemas"]["IfNode"] | components["schemas"]["SerialReadNode"] | components["schemas"]["SerialWriteNode"] | components["schemas"]["RetrieverNode"] | components["schemas"]["WebFetchNode"] | components["schemas"]["MLInferenceNode"] | components["schemas"]["CameraCaptureNode"] | components["schemas"]["FunctionCallNode"] | components["schemas"]["OnFunctionCallNode"] | components["schemas"]["DelayNode"] | components["schemas"]["TickerNode"] | components["schemas"]["AlarmNode"] | components["schemas"]["WebSearchToolNode"] | components["schemas"]["OnStartupNode"] | components["schemas"]["OnPinEdgeNode"] | components["schemas"]["OnSerialReceiveNode"] | components["schemas"]["OnThresholdNode"] | components["schemas"]["SetVariableNode"] | components["schemas"]["MqttPublishNode"] | components["schemas"]["OnMqttMessageNode"];
         WebSearchToolNode: {
             id: string;
             /**
@@ -363,6 +375,38 @@ export interface components {
                 output: components["schemas"]["OutputBinding"];
             };
         };
+        MLInferenceNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "MLInference";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to an MLModel id. */
+                model: string;
+                /** @description Variable holding the model input. Its type is resolved at runtime and dispatched to the matching handler. */
+                input: components["schemas"]["Reference"];
+                output: components["schemas"]["OutputBinding"];
+            };
+        };
+        CameraCaptureNode: {
+            id: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "CameraCapture";
+            label?: string;
+            position: components["schemas"]["NodePosition"];
+            arguments: {
+                /** @description Reference to a CAMERA channel id. The channel carries optional capture defaults; it resolves to a capture component endpoint at deploy time. */
+                cameraReference: string;
+                output: components["schemas"]["OutputBinding"];
+            };
+        };
         ReadPinNode: {
             id: string;
             /**
@@ -519,7 +563,7 @@ export interface components {
                 output: components["schemas"]["OutputBinding"];
             };
         };
-        Channel: components["schemas"]["GPIOINChannel"] | components["schemas"]["GPIOOUTChannel"] | components["schemas"]["ADCChannel"] | components["schemas"]["PWMChannel"] | components["schemas"]["DACChannel"] | components["schemas"]["UARTChannel"] | components["schemas"]["MQTTChannel"] | components["schemas"]["LOGChannel"];
+        Channel: components["schemas"]["GPIOINChannel"] | components["schemas"]["GPIOOUTChannel"] | components["schemas"]["ADCChannel"] | components["schemas"]["PWMChannel"] | components["schemas"]["DACChannel"] | components["schemas"]["UARTChannel"] | components["schemas"]["MQTTChannel"] | components["schemas"]["CAMERAChannel"] | components["schemas"]["LOGChannel"];
         GPIOINChannel: {
             /**
              * @description discriminator enum property added by openapi-typescript
@@ -594,6 +638,19 @@ export interface components {
             /** @description Topic this channel publishes to / subscribes on. */
             topic: string;
         };
+        CAMERAChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "CAMERA";
+            id: string;
+            label: string;
+            /** @description Default capture width in pixels. The source picks its native resolution when omitted. */
+            width?: number;
+            /** @description Default capture height in pixels. The source picks its native resolution when omitted. */
+            height?: number;
+        };
         LOGChannel: {
             /**
              * @description discriminator enum property added by openapi-typescript

package/src/channel/Channel.ts

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (c) 2026 ForestHub.
 
-export type ChannelType = "GPIOIN" | "GPIOOUT" | "ADC" | "PWM" | "DAC" | "UART" | "MQTT" | "LOG";
+export type ChannelType = "GPIOIN" | "GPIOOUT" | "ADC" | "PWM" | "DAC" | "UART" | "MQTT" | "LOG" | "CAMERA";
 
-export const ALL_CHANNEL_TYPES: ChannelType[] = ["GPIOIN", "GPIOOUT", "ADC", "PWM", "DAC", "UART", "MQTT", "LOG"];
+export const ALL_CHANNEL_TYPES: ChannelType[] = ["GPIOIN", "GPIOOUT", "ADC", "PWM", "DAC", "UART", "MQTT", "LOG", "CAMERA"];
 
 /** Interface for a channel instance in the workflow */
 export interface Channel {

package/src/channel/ChannelDefinition.ts

@@ -97,5 +97,21 @@ export const CHANNEL_DEFINITION: ChannelDefinition = {
       optional: true,
       activationRules: [{ type: "parameterIn", parameterId: "type", values: ["LOG"] }],
     },
+    {
+      id: "width",
+      label: "Width (px)",
+      description: "Default capture width in pixels (source's native resolution when empty)",
+      type: "int",
+      optional: true,
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["CAMERA"] }],
+    },
+    {
+      id: "height",
+      label: "Height (px)",
+      description: "Default capture height in pixels (source's native resolution when empty)",
+      type: "int",
+      optional: true,
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["CAMERA"] }],
+    },
   ],
 };

package/src/channel/serialization.ts

@@ -45,6 +45,8 @@ export function serialize(ch: Channel): ApiChannel {
       return { type, id, label, topic: args.topic as string };
     case "LOG":
       return { type, id, label, level: args.level as Schemas["LOGChannel"]["level"], tag: args.tag as string | undefined };
+    case "CAMERA":
+      return { type, id, label, width: args.width as number | undefined, height: args.height as number | undefined };
   }
 }
 
@@ -67,6 +69,10 @@ export function deserialize(api: ApiChannel): Channel {
       args.level = api.level;
       args.tag = api.tag;
       break;
+    case "CAMERA":
+      args.width = api.width;
+      args.height = api.height;
+      break;
     case "GPIOOUT":
     case "ADC":
     case "DAC":

package/src/deploy/constants.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+// The component contract: the fixed in-container paths every ForestHub component
+// reads/writes (also the targets the renderers bind-mount host dirs onto) and the
+// canonical component identities. The language-neutral source of truth is
+// contract/component-constants.json; these MUST equal it (enforced by
+// constants.test.ts) and the Go twins in go/component/constants.go. Changing a value
+// means changing all three in lockstep.
+
+// Fixed path a component's boot config (config.json) is mounted at, read-only.
+export const COMPONENT_CONFIG_PATH = "/etc/foresthub/config.json";
+
+// Fixed path a component's resolved secret document (secrets.json) is mounted at,
+// read-only. Dynamic, id-keyed credentials resolved fresh each deploy, never in the spec.
+export const COMPONENT_SECRETS_PATH = "/etc/foresthub/secrets.json";
+
+// Fixed path a component's durable workspace is mounted at (engine memory, model
+// weights, model repository) — persisted across deployments.
+export const COMPONENT_WORKSPACE_PATH = "/var/lib/foresthub/workspace";
+
+// Canonical identities of the singleton first-party components. For a singleton the
+// identity is ALSO its compose service/container name — so the renderer names the
+// container this, other components reach it at this hostname, and it stamps its logs
+// with it. llama-server is a singleton too: one container fronts every on-device model
+// with llama-swap, selected by id per request — so its name is fixed, not per-model.
+export const ENGINE_COMPONENT_NAME = "engine";
+export const LLAMA_COMPONENT_NAME = "llama-server";
+export const CAMERA_COMPONENT_NAME = "camera";
+export const ML_COMPONENT_NAME = "ml-inference";

package/src/deploy/index.ts

@@ -1,17 +1,14 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 ForestHub.
-
-export { getReferencedCatalogModelIds, deriveRequirements } from "./requirements";
-export type { DeployRequirements, HardwareChannel, MqttChannel, CustomModel, HardwareFamily } from "./requirements";
-export type { DeploymentInputs, HardwareBinding, MqttBinding, ModelBinding } from "./inputs";
-export {
-  buildDeploymentSpec,
-  assertDeployable,
-  hardwareConflicts,
-  familyMismatches,
-  hardwareAddressKey,
-  hardwareAddressLabel,
-  ggufNameError,
-  sidecarServiceName,
-} from "./spec";
-export type { DeploymentSpecMeta, DeploymentSpecResult, EngineSecrets } from "./spec";
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+// The deploy module's public surface: the language-neutral, cross-implementation
+// pieces of the deployment pipeline (docs/deployment-pipeline.md). The OSS CLI's
+// spec resolver (buildDeploymentSpec), its rich requirement analysis
+// (deriveRequirements) and its operator-input types live in the workflow-cli
+// package, not here — this module holds only what the backend path must
+// independently agree with: the Stage-0 binding surface (the cross-language seam),
+// the catalog-model walk it builds on, and the component contract.
+
+export { workflowBindingRequirements, getReferencedCatalogModelIds, type BindingKind } from "./requirements";
+export { COMPONENT_CONFIG_PATH, COMPONENT_SECRETS_PATH, COMPONENT_WORKSPACE_PATH } from "./constants";
+export { ENGINE_COMPONENT_NAME, CAMERA_COMPONENT_NAME, ML_COMPONENT_NAME, LLAMA_COMPONENT_NAME } from "./constants";

package/src/deploy/requirements.test.ts

@@ -1,64 +1,164 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 ForestHub.
-
-import { describe, it, expect } from "vitest";
-import { getReferencedCatalogModelIds } from "./requirements";
-import { MAIN_CANVAS_ID, type Workflow, type Canvas } from "../workflow";
-import type { Node } from "../node";
-import type { Model } from "../model";
-
-// Minimal Agent node referencing `model`. Cast through the union — only id/type/
-// arguments.model matter to the walk.
-function agent(id: string, model: string): Node {
-  return {
-    id,
-    type: "Agent",
-    position: { x: 0, y: 0 },
-    arguments: {
-      name: id,
-      model,
-      instructions: "",
-      outputDeclarations: [],
-      memoryRefs: [],
-      answer: { active: true, mode: "emit", name: "answer" },
-    },
-  } as Node;
-}
-
-function canvas(nodes: Node[]): Canvas {
-  return { nodes, edges: [], variables: {} };
-}
-
-const customModel: Model = { id: "custom-llm", label: "Custom", type: "LLMModel", arguments: {} };
-
-function workflow(canvases: Workflow["canvases"], models: Record<string, Model> = {}): Workflow {
-  return { canvases, functions: {}, channels: {}, memory: {}, models };
-}
-
-describe("getReferencedCatalogModelIds", () => {
-  it("returns catalog ids (referenced but not declared), excluding declared customs", () => {
-    const wf = workflow(
-      { [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "custom-llm")]) },
-      { "custom-llm": customModel },
-    );
-    expect(getReferencedCatalogModelIds(wf)).toEqual(["claude-opus-4-7"]);
-  });
-
-  it("ignores unset model references", () => {
-    const wf = workflow({ [MAIN_CANVAS_ID]: canvas([agent("n1", "")]) });
-    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
-  });
-
-  it("dedupes across nodes and walks every canvas (main + function bodies)", () => {
-    const wf = workflow({
-      [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "claude-opus-4-7")]),
-      fnBody: canvas([agent("n3", "gemini-2")]),
-    });
-    expect(getReferencedCatalogModelIds(wf).sort()).toEqual(["claude-opus-4-7", "gemini-2"]);
-  });
-
-  it("returns nothing when every referenced model is declared", () => {
-    const wf = workflow({ [MAIN_CANVAS_ID]: canvas([agent("n1", "custom-llm")]) }, { "custom-llm": customModel });
-    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
-  });
-});
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+import { describe, it, expect } from "vitest";
+import { workflowBindingRequirements, getReferencedCatalogModelIds, type BindingKind } from "./requirements";
+import { MAIN_CANVAS_ID, type Workflow, type Canvas } from "../workflow";
+import type { Channel, ChannelType } from "../channel";
+import type { Model } from "../model";
+import type { Node } from "../node";
+
+function channel(id: string, type: ChannelType): Channel {
+  return { id, label: id, type, arguments: {} };
+}
+
+const llm = (id: string): Model => ({ id, label: id, type: "LLMModel", arguments: {} });
+const ml = (id: string): Model => ({ id, label: id, type: "MLModel", arguments: {} });
+
+// Minimal Agent node referencing a catalog model by id — only the model ref
+// matters to the requirement walk. Cast through the union: the other Agent args
+// are irrelevant here.
+function agent(id: string, model: string): Node {
+  return {
+    id,
+    type: "Agent",
+    position: { x: 0, y: 0 },
+    arguments: {
+      name: id,
+      model,
+      instructions: "",
+      outputDeclarations: [],
+      memoryRefs: [],
+      answer: { active: true, mode: "emit", name: "answer" },
+    },
+  } as unknown as Node;
+}
+
+const canvas = (nodes: Node[]): Canvas => ({ nodes, edges: [], variables: {} });
+
+// Build a workflow from parts. `nodes` fills the main canvas; pass `canvases`
+// instead to model multiple bodies (main + function). Any other field
+// (channels, models) overrides the empty default.
+function workflow(parts: Partial<Workflow> & { nodes?: Node[] }): Workflow {
+  const { nodes = [], ...rest } = parts;
+  return {
+    canvases: { [MAIN_CANVAS_ID]: canvas(nodes) },
+    functions: {},
+    channels: {},
+    memory: {},
+    models: {},
+    ...rest,
+  };
+}
+
+const byId = (chs: Channel[]): Record<string, Channel> => Object.fromEntries(chs.map((c) => [c.id, c]));
+const modelsById = (ms: Model[]): Record<string, Model> => Object.fromEntries(ms.map((m) => [m.id, m]));
+
+// CROSS-LANGUAGE CONFORMANCE. Each case below is a golden fixture: a workflow in,
+// an exact id->kind surface out. The backend's deploy.WorkflowBindingRequirements
+// must produce the identical map for the same workflow — mirror these fixtures on
+// the Go side so the two extractors stay pinned. Divergence here is deploy drift:
+// OSS and the backend disagreeing about what a workflow needs bound.
+describe("workflowBindingRequirements", () => {
+  it("returns an empty surface for an empty workflow", () => {
+    expect(workflowBindingRequirements(workflow({}))).toEqual({});
+  });
+
+  it("maps every hardware channel family to 'hardware'", () => {
+    const chs = byId([
+      channel("in", "GPIOIN"),
+      channel("out", "GPIOOUT"),
+      channel("adc", "ADC"),
+      channel("dac", "DAC"),
+      channel("pwm", "PWM"),
+      channel("uart", "UART"),
+    ]);
+    const expected: Record<string, BindingKind> = {
+      in: "hardware",
+      out: "hardware",
+      adc: "hardware",
+      dac: "hardware",
+      pwm: "hardware",
+      uart: "hardware",
+    };
+    expect(workflowBindingRequirements(workflow({ channels: chs }))).toEqual(expected);
+  });
+
+  it("maps MQTT to 'mqtt' and CAMERA to 'camera' (OSS-ahead kind)", () => {
+    const chs = byId([channel("telemetry", "MQTT"), channel("cam0", "CAMERA")]);
+    expect(workflowBindingRequirements(workflow({ channels: chs }))).toEqual({ telemetry: "mqtt", cam0: "camera" });
+  });
+
+  it("binds nothing for a LOG channel", () => {
+    const chs = byId([channel("log", "LOG"), channel("led", "GPIOOUT")]);
+    expect(workflowBindingRequirements(workflow({ channels: chs }))).toEqual({ led: "hardware" });
+  });
+
+  it("maps every declared model to 'declaredModel', LLM and ML alike", () => {
+    const models = modelsById([llm("local-llm"), ml("yolo")]);
+    expect(workflowBindingRequirements(workflow({ models }))).toEqual({ "local-llm": "declaredModel", yolo: "declaredModel" });
+  });
+
+  it("maps a referenced-but-undeclared catalog model to 'catalogModel', keyed by model id", () => {
+    const wf = workflow({ nodes: [agent("a1", "gpt-4o")] });
+    expect(workflowBindingRequirements(wf)).toEqual({ "gpt-4o": "catalogModel" });
+  });
+
+  it("prefers 'declaredModel' when an id is both declared and referenced (no overwrite)", () => {
+    const wf = workflow({ models: modelsById([llm("shared")]), nodes: [agent("a1", "shared")] });
+    expect(workflowBindingRequirements(wf)).toEqual({ shared: "declaredModel" });
+  });
+
+  it("does not extract MemoryFile / VectorDatabase memory (RAG not yet in the OSS surface)", () => {
+    const wf = workflow({
+      memory: { notes: { id: "notes", label: "Notes", type: "MemoryFile", arguments: {} } as Workflow["memory"][string] },
+    });
+    expect(workflowBindingRequirements(wf)).toEqual({});
+  });
+
+  it("produces the full surface for a mixed workflow", () => {
+    const wf = workflow({
+      channels: byId([channel("led", "GPIOOUT"), channel("telemetry", "MQTT"), channel("cam0", "CAMERA"), channel("log", "LOG")]),
+      models: modelsById([llm("local-llm")]),
+      nodes: [agent("a1", "claude-sonnet")],
+    });
+    const expected: Record<string, BindingKind> = {
+      led: "hardware",
+      telemetry: "mqtt",
+      cam0: "camera",
+      "local-llm": "declaredModel",
+      "claude-sonnet": "catalogModel",
+    };
+    expect(workflowBindingRequirements(wf)).toEqual(expected);
+  });
+});
+
+describe("getReferencedCatalogModelIds", () => {
+  it("returns catalog ids (referenced but not declared), excluding declared customs", () => {
+    const wf = workflow({
+      canvases: { [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "custom-llm")]) },
+      models: modelsById([llm("custom-llm")]),
+    });
+    expect(getReferencedCatalogModelIds(wf)).toEqual(["claude-opus-4-7"]);
+  });
+
+  it("ignores unset model references", () => {
+    const wf = workflow({ nodes: [agent("n1", "")] });
+    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
+  });
+
+  it("dedupes across nodes and walks every canvas (main + function bodies)", () => {
+    const wf = workflow({
+      canvases: {
+        [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "claude-opus-4-7")]),
+        fnBody: canvas([agent("n3", "gemini-2")]),
+      },
+    });
+    expect(getReferencedCatalogModelIds(wf).sort()).toEqual(["claude-opus-4-7", "gemini-2"]);
+  });
+
+  it("returns nothing when every referenced model is declared", () => {
+    const wf = workflow({ nodes: [agent("n1", "custom-llm")], models: modelsById([llm("custom-llm")]) });
+    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
+  });
+});