npm - @foresthubai/workflow-cli - Versions diffs - 0.4.4 → 0.4.6 - Mend

@foresthubai/workflow-cli 0.4.4 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/assets/index-DY0leyGX.js +75 -0
package/dist/index.html +1 -1
package/dist-cli/cli.js +140 -67
package/dist-cli/deployment.yaml +43 -21
package/dist-cli/llmproxy.yaml +5 -2
package/dist-cli/workflow.yaml +13 -12
package/package.json +1 -1
package/dist/assets/index-D7a-pqL0.js +0 -75

package/dist/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" href="/favicon.png" type="image/png" />
     <title>Edge Agents Builder</title>
-    <script type="module" crossorigin src="/assets/index-D7a-pqL0.js"></script>
+    <script type="module" crossorigin src="/assets/index-DY0leyGX.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CiLOHdeR.css">
   </head>
   <body class="bg-background text-foreground">

package/dist-cli/cli.js CHANGED Viewed

@@ -12782,9 +12782,29 @@ function isAllowed(target, roots) {
     return rel === "" || !rel.startsWith("..") && !path.isAbsolute(rel);
   });
 }
+function isLoopbackHost(host) {
+  if (!host) return false;
+  const name = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.replace(/:\d+$/, "");
+  return name === "localhost" || name === "127.0.0.1" || name === "[::1]";
+}
+function isTrustedRequest(req) {
+  if (!isLoopbackHost(req.headers.host)) return false;
+  const origin = req.headers.origin;
+  if (origin === void 0) return true;
+  try {
+    return isLoopbackHost(new URL(origin).host);
+  } catch {
+    return false;
+  }
+}
 async function handleFileRequest(req, res, allowedRoots) {
   const url2 = new URL(req.url ?? "", "http://localhost");
   if (url2.pathname !== "/api/file") return false;
+  if (!isTrustedRequest(req)) {
+    res.statusCode = 403;
+    res.end("forbidden: non-local request");
+    return true;
+  }
   try {
     const filePath = url2.searchParams.get("path");
     if (!filePath) {
@@ -12810,7 +12830,7 @@ async function handleFileRequest(req, res, allowedRoots) {
       }
       return true;
     }
-    if (req.method === "PUT" || req.method === "POST") {
+    if (req.method === "PUT") {
       const chunks = [];
       for await (const chunk of req) chunks.push(chunk);
       const body = Buffer.concat(chunks).toString("utf-8");
@@ -14495,6 +14515,9 @@ function buildFunctionNodeDef(fn, t = (key) => key) {
 }
 // ../workflow-core/src/node/serialization.ts
+function draft(value) {
+  return value;
+}
 function serialize6(node, isToolInput) {
   const result = serializeNodeData(node, node.position, isToolInput);
   if (node.label) {
@@ -14505,6 +14528,10 @@ function serialize6(node, isToolInput) {
     if (def) {
       pruneArguments(result.arguments, def.parameters, isToolInput);
     }
+    const args2 = result.arguments;
+    for (const key of Object.keys(args2)) {
+      if (args2[key] === void 0) delete args2[key];
+    }
   }
   return result;
 }
@@ -14516,7 +14543,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          pinReference: data.arguments.pinReference,
+          pinReference: draft(data.arguments.pinReference),
           signalType: data.arguments.signalType,
           output: data.arguments.output,
           toolDescription: data.arguments.toolDescription
@@ -14528,7 +14555,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          portReference: data.arguments.portReference,
+          portReference: draft(data.arguments.portReference),
           ...data.arguments.prompt !== void 0 ? { prompt: data.arguments.prompt } : {},
           output: data.arguments.output
         }
@@ -14539,7 +14566,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          pinReference: data.arguments.pinReference,
+          pinReference: draft(data.arguments.pinReference),
           signalType: data.arguments.signalType,
           value: data.arguments.value
         }
@@ -14550,7 +14577,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          portReference: data.arguments.portReference,
+          portReference: draft(data.arguments.portReference),
           value: data.arguments.value
         }
       };
@@ -14598,7 +14625,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          pinReference: data.arguments.pinReference,
+          pinReference: draft(data.arguments.pinReference),
           edge: data.arguments.edge
         }
       };
@@ -14608,7 +14635,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          portReference: data.arguments.portReference,
+          portReference: draft(data.arguments.portReference),
           output: data.arguments.output
         }
       };
@@ -14618,8 +14645,8 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          variable: data.arguments.variable,
-          threshold: data.arguments.threshold,
+          variable: draft(data.arguments.variable),
+          threshold: draft(data.arguments.threshold),
           direction: data.arguments.direction,
           deadband: data.arguments.deadband,
           output: data.arguments.output
@@ -14631,7 +14658,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          delayMs: data.arguments.delayMs
+          delayMs: draft(data.arguments.delayMs)
         }
       };
     case "Ticker":
@@ -14640,7 +14667,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          intervalValue: data.arguments.intervalValue,
+          intervalValue: draft(data.arguments.intervalValue),
           intervalUnit: data.arguments.intervalUnit
         }
       };
@@ -14670,7 +14697,7 @@ function serializeNodeData(data, position, isToolInput) {
         position,
         arguments: {
           memoryReference: data.arguments.memoryReference,
-          topK: data.arguments.topK,
+          topK: draft(data.arguments.topK),
           query: data.arguments.query,
           output: data.arguments.output,
           toolDescription: data.arguments.toolDescription
@@ -14720,7 +14747,7 @@ function serializeNodeData(data, position, isToolInput) {
         type: data.type,
         position,
         arguments: {
-          variable: data.arguments.variable,
+          variable: draft(data.arguments.variable),
           value: data.arguments.value
         }
       };
@@ -14733,7 +14760,8 @@ function serializeNodeData(data, position, isToolInput) {
           channelReference: data.arguments.channelReference ?? "",
           dataType: data.arguments.dataType,
           value: data.arguments.value,
-          qos: Number(data.arguments.qos),
+          // Unset stays unset — Number(undefined) is NaN, which stringifies to null.
+          qos: draft(data.arguments.qos === void 0 ? void 0 : Number(data.arguments.qos)),
           retain: data.arguments.retain
         }
       };
@@ -17027,12 +17055,21 @@ function printReport(file2, result) {
 `);
     for (const d of result.memoryDiagnostics) printDiagnostic(d, "    ");
   }
+  if (result.modelDiagnostics.length > 0) {
+    out.write(`
+  models:
+`);
+    for (const d of result.modelDiagnostics) printDiagnostic(d, "    ");
+  }
 }
 function printDiagnostic(d, indent) {
   const where = [];
   if (d.nodeId) where.push(`node ${d.nodeId}`);
   if (d.edgeId) where.push(`edge ${d.edgeId}`);
   if (d.channelId) where.push(`channel ${d.channelId}`);
+  if (d.memoryId) where.push(`memory ${d.memoryId}`);
+  if (d.modelId) where.push(`model ${d.modelId}`);
+  if (d.functionId) where.push(`function ${d.functionId}`);
   if (d.paramId) where.push(`param ${d.paramId}`);
   if (d.outputId) where.push(`output ${d.outputId}`);
   const location = where.length > 0 ? ` (${where.join(", ")})` : "";
@@ -19593,7 +19630,11 @@ function deriveRequirements(workflow) {
 }
 // ../workflow-core/src/deploy/spec.ts
-var ENGINE_MEMORY_PATH = "/var/lib/foresthub/memory";
+var COMPONENT_WORKSPACE_PATH = "/var/lib/foresthub/workspace";
+var STATE_ROOT = ".";
+function workspaceDir(container) {
+  return `${STATE_ROOT}/workspaces/${container}`;
+}
 var RefAllocator = class {
   byKey = /* @__PURE__ */ new Map();
   used = /* @__PURE__ */ new Set();
@@ -19626,7 +19667,7 @@ function ggufNameError(name) {
   const t = (name ?? "").trim();
   if (!t) return "a model filename is required";
   if (!t.toLowerCase().endsWith(".gguf")) return "must be a .gguf file (llama-server only loads GGUF)";
-  if (t.includes("/")) return "just the filename, not a path \u2014 the file goes in ./models/";
+  if (t.includes("/")) return "just the filename, not a path \u2014 the file goes in the model's workspace dir (./workspaces/llama-\u2026/)";
   return null;
 }
 function hardwareAddressKey(family, chipOrDevice, index) {
@@ -19758,7 +19799,7 @@ function buildDeploymentSpec(workflow, inputs, meta3, customComponents = []) {
     const ref = refs.alloc(`mqtt:${JSON.stringify(conn)}:${b.password ?? ""}`, `mqtt-${brokerHost(b.brokerUrl)}`);
     externalResources[ref] = conn;
     mapping[ch.id] = { ref };
-    if (b.password) resourceSecrets[ref] = { ...resourceSecrets[ref], password: b.password };
+    if (b.password) resourceSecrets[ref] = b.password;
   }
   const llamaComponents = [];
   for (const m of req.customModels) {
@@ -19775,7 +19816,7 @@ function buildDeploymentSpec(workflow, inputs, meta3, customComponents = []) {
         image: meta3.llamaServerImage,
         command: [
           "--model",
-          `/models/${b.modelFile}`,
+          `${COMPONENT_WORKSPACE_PATH}/${b.modelFile}`,
           "--host",
           "0.0.0.0",
           "--port",
@@ -19783,11 +19824,13 @@ function buildDeploymentSpec(workflow, inputs, meta3, customComponents = []) {
           "--ctx-size",
           String(b.ctxSize ?? 4096)
         ],
-        volumes: ["./models:/models:ro"]
+        // The model lives in this sidecar's own workspace; read-only, so no chown
+        // is needed (docs §5). The operator drops the GGUF in workspaceDir(service).
+        volumes: [`${workspaceDir(service)}:${COMPONENT_WORKSPACE_PATH}:ro`]
       });
     } else {
       externalResources[ref] = { type: "selfhosted", url: b.url };
-      if (b.apiKey) resourceSecrets[ref] = { apiKey: b.apiKey };
+      if (b.apiKey) resourceSecrets[ref] = b.apiKey;
     }
   }
   const manifest = {};
@@ -19806,17 +19849,21 @@ function buildDeploymentSpec(workflow, inputs, meta3, customComponents = []) {
     pull: "never",
     // built locally before deploy, in no registry
     config: config2,
-    volumes: [`engine-memory:${ENGINE_MEMORY_PATH}`]
+    // Durable memory: a host bind mount under the state root, read-write, at the
+    // in-container workspace path (docs/device-filesystem.md §10).
+    volumes: [`${workspaceDir("engine")}:${COMPONENT_WORKSPACE_PATH}`],
+    // Run as root: writes the rw workspace bind mount without a host chown step
+    // (the OSS default, §5), and also opens root-owned device nodes when hardware
+    // (cdev passthrough / sysfs-privileged) is mapped in below.
+    user: "0:0"
   };
   if (cdev.size > 0) engine.devices = [...cdev];
   if (privileged) engine.privileged = true;
-  if (cdev.size > 0 || privileged) engine.user = "0:0";
   const components = [engine, ...llamaComponents, ...customComponents];
   assertNoNameCollisions(components);
   const spec = {
     schemaVersion: 1,
     id: meta3.id,
-    status: meta3.status,
     components
   };
   if (meta3.createdAt) spec.createdAt = meta3.createdAt;
@@ -36714,7 +36761,7 @@ async function promptModels(models, seed) {
     });
     if (location === "device") {
       const modelFile = await dist_default6({
-        message: `${m.label}: model filename in ./models/ (e.g. model.gguf)`,
+        message: `${m.label}: model filename, dropped in its workspace dir (e.g. model.gguf)`,
         validate: (v) => ggufNameError(v) ?? true
       });
       const ctxSize = await dist_default6({ message: `${m.label}: context window in tokens`, default: "4096", validate: isUint });
@@ -36849,27 +36896,42 @@ import path11 from "node:path";
 // cli/deploy/generate.ts
 import { createHash } from "node:crypto";
-var DEFAULT_CONFIG_PATH = "/etc/foresthub/config.json";
+var CONFIG_PATH = "/etc/foresthub/config.json";
+var SECRETS_PATH = "/etc/foresthub/secrets.json";
 function configFileName(name) {
   return `${name}-config.json`;
 }
+function secretsFileName(name) {
+  return `${name}-secrets.json`;
+}
 function namedVolumeSource(mount) {
   const src = mount.split(":")[0] ?? "";
   return src && !src.startsWith(".") && !src.startsWith("/") ? src : null;
 }
-function serviceBlock(c) {
+function serviceBlock(c, secretDoc) {
+  const hasSecretDoc = secretDoc !== void 0 && Object.keys(secretDoc).length > 0;
   const lines = [`  ${c.name}:`, `    image: ${c.image}`, `    pull_policy: ${c.pull ?? "missing"}`, "    restart: unless-stopped"];
+  const labels = [];
   if (c.config !== void 0) {
     const hash2 = createHash("sha256").update(JSON.stringify(c.config)).digest("hex");
-    lines.push("    labels:", `      com.foresthub.config-hash: "${hash2}"`);
+    labels.push(`      com.foresthub.config-hash: "${hash2}"`);
   }
+  if (hasSecretDoc) {
+    const hash2 = createHash("sha256").update(JSON.stringify(secretDoc)).digest("hex");
+    labels.push(`      com.foresthub.secrets-hash: "${hash2}"`);
+  }
+  if (labels.length > 0) lines.push("    labels:", ...labels);
   if (c.user) lines.push(`    user: "${c.user}"`);
   if (c.command && c.command.length > 0) {
     lines.push("    command:");
     for (const arg of c.command) lines.push(`      - "${arg}"`);
   }
   lines.push("    env_file:", `      - path: ${c.name}.env`, "        required: false");
-  const volumes = [...c.config !== void 0 ? [`./${configFileName(c.name)}:${c.configPath ?? DEFAULT_CONFIG_PATH}:ro`] : [], ...c.volumes ?? []];
+  const volumes = [
+    ...c.config !== void 0 ? [`./${configFileName(c.name)}:${CONFIG_PATH}:ro`] : [],
+    ...hasSecretDoc ? [`./${secretsFileName(c.name)}:${SECRETS_PATH}:ro`] : [],
+    ...c.volumes ?? []
+  ];
   if (volumes.length > 0) {
     lines.push("    volumes:");
     for (const v of volumes) lines.push(`      - ${v}`);
@@ -36891,8 +36953,8 @@ function serviceBlock(c) {
   }
   return lines.join("\n");
 }
-function composeYaml(spec) {
-  const services = spec.components.map(serviceBlock).join("\n\n");
+function composeYaml(spec, secretDocs = {}) {
+  const services = spec.components.map((c) => serviceBlock(c, secretDocs[c.name])).join("\n\n");
   const named = [...new Set(spec.components.flatMap((c) => (c.volumes ?? []).map(namedVolumeSource).filter((s) => s !== null)))];
   const volumesBlock = named.length > 0 ? `
 volumes:
@@ -36906,7 +36968,7 @@ services:
 ${services}
 ${volumesBlock}`;
 }
-function envFile(cfg, resourceSecrets = {}) {
+function envFile(cfg) {
   const localProviders = ALL_PROVIDERS.filter((p) => Boolean(cfg.llmKeys[p]));
   const providerSection = localProviders.length === 0 ? "" : `# ----- LLM provider keys -----
 # Each key here = that provider runs locally with your API key.
@@ -36917,25 +36979,23 @@ ${localProviders.map((p) => `${p.toUpperCase()}_API_KEY=${cfg.llmKeys[p] ?? ""}`
 ENGINE_WEB_SEARCH_PROVIDER=${cfg.webSearch.provider}
 ENGINE_WEB_SEARCH_API_KEY=${cfg.webSearch.apiKey}
-` : "";
-  const resourceSecretsSection = Object.keys(resourceSecrets).length > 0 ? `# ----- External-resource secrets -----
-FH_RESOURCE_SECRETS=${JSON.stringify(resourceSecrets)}
 ` : "";
   return `# Edge Agents engine \u2014 operator configuration.
 # Auto-generated by \`fh-workflow deploy\`. Loaded into the engine via the compose
 # \`env_file\`. Secret values: chmod 600 this file after editing.
-${providerSection}${webSearchSection}${resourceSecretsSection}# ----- Runtime -----
+${providerSection}${webSearchSection}# ----- Runtime -----
 ENGINE_LOG_LEVEL=${cfg.logLevel}     # debug | info | warn | error
 `;
 }
-function readme(spec, cfg, hasProviderModel) {
+function readme(spec, cfg, hasProviderModel, hasSecrets = false) {
   const localProviders = ALL_PROVIDERS.filter((p) => Boolean(cfg.llmKeys[p]));
   const providerBlock = localProviders.length === 0 ? "_No local API keys set._ An Agent that uses a catalog model will fail at build \u2014 set the matching key in `engine.env`." : localProviders.map((p) => `- **${p}** \u2014 runs locally (your API key)`).join("\n");
   const engine = spec.components.find((c) => c.name === "engine");
   const hasHardware = (engine?.devices?.length ?? 0) > 0 || Boolean(engine?.privileged);
-  const deviceModelFiles = Object.values(cfg.models).flatMap((b) => b.location === "device" ? [b.modelFile] : []);
+  const deviceModels = Object.entries(cfg.models).flatMap(
+    ([id, b]) => b.location === "device" ? [{ dir: `./workspaces/${sidecarServiceName(id)}`, file: b.modelFile }] : []
+  );
   const hasNetworkModel = Object.values(cfg.models).some((b) => b.location === "network");
   const hasMqtt = Object.keys(cfg.mqtt).length > 0;
   const hasExternalService = hasMqtt || hasNetworkModel;
@@ -36959,19 +37019,20 @@ and tighten it to your security policy before deploying.`);
   if (hasExternalService) {
     notes.push(`## External resources
-The broker/endpoint credentials the engine connects with live in \`engine.env\`
-(\`FH_RESOURCE_SECRETS\`) \u2014 keep it \`chmod 600\`. This bundle does not start those
-services; it assumes the broker/endpoint already exists and is reachable from the
-controller.`);
+The broker/endpoint credentials the engine connects with live in the mounted secret
+document \`engine-secrets.json\` (a JSON map of resource id -> secret value, mounted
+read-only at \`/etc/foresthub/secrets.json\`) \u2014 keep it \`chmod 600\`. This
+bundle does not start those services; it assumes the broker/endpoint already exists
+and is reachable from the controller.`);
   }
-  if (deviceModelFiles.length > 0) {
+  if (deviceModels.length > 0) {
     notes.push(`## On-device models
 This bundle runs a llama-server container per on-device model; the engine reaches it
-over the compose network by service name. The GGUF file(s) below must sit in a
-\`models/\` folder next to the compose file on the controller. They are too large for
-the main \`scp\` line, so step 3 transfers them separately:
-${deviceModelFiles.map((f) => `- \`./models/${f}\``).join("\n")}`);
+over the compose network by service name. Each GGUF must sit in that model's workspace
+dir below (read-only mounted into its container). They are too large for the main
+\`scp\` line, so step 3 transfers them separately:
+${deviceModels.map((m) => `- \`${m.dir}/${m.file}\``).join("\n")}`);
   }
   if (hasNetworkModel) {
     notes.push(`## Network models
@@ -36985,13 +37046,13 @@ Ollama, ...) on another machine. This bundle does not start that server for you.
 The web-search API key is in \`engine.env\` (\`ENGINE_WEB_SEARCH_API_KEY\`).`);
   }
   const notesBlock = notes.length ? "\n" + notes.join("\n\n") + "\n" : "";
-  const modelsTransfer = deviceModelFiles.length ? `
+  const modelsTransfer = deviceModels.length ? `
 # On-device model weights \u2014 too large for the line above (GGUF can be several GB).
-# Copy them from this bundle:
-scp -r models/ $CONTROLLER_USER@$CONTROLLER_ADDR:~/fh-engine/
-# ...or download them directly into ~/fh-engine/models/ on the controller.` : "";
-  const runBlock = deviceModelFiles.length ? `ssh $CONTROLLER_USER@$CONTROLLER_ADDR 'cd ~/fh-engine && docker load -i fh-engine.tar'
+# Put each GGUF in its model's workspace dir, then copy the workspaces tree:
+scp -r workspaces/ $CONTROLLER_USER@$CONTROLLER_ADDR:~/fh-engine/
+# ...or download them directly into ~/fh-engine/workspaces/<model>/ on the controller.` : "";
+  const runBlock = deviceModels.length ? `ssh $CONTROLLER_USER@$CONTROLLER_ADDR 'cd ~/fh-engine && docker load -i fh-engine.tar'
 ssh $CONTROLLER_USER@$CONTROLLER_ADDR 'cd ~/fh-engine && docker compose up -d'
 # The engine and the llama-server sidecar start independently; the engine reaches the
@@ -37010,7 +37071,7 @@ the workflow from \`engine-config.json\` and runs it autonomously:
 - \`engine-config.json\` \u2014 the engine's single boot config (workflow + bindings + device manifest)
 - \`deployment-spec.json\` \u2014 the full resolved deployment spec (deployment record)
 - \`engine.env\` \u2014 operator configuration loaded into the engine (already filled in, \`chmod 600\` it)
-- \`fh-engine.tar\` \u2014 image tarball (you build this in step 1 below)
+${hasSecrets ? "- `engine-secrets.json` \u2014 resource credentials, mounted read-only at `/etc/foresthub/secrets.json` (already filled in, `chmod 600` it)\n" : ""}- \`fh-engine.tar\` \u2014 image tarball (you build this in step 1 below)
 ${notesBlock}
 ## 1. Build the image (on the dev machine)
@@ -37047,7 +37108,7 @@ docker save fh-engine:latest -o ../path/to/this/bundle/fh-engine.tar
 ssh $CONTROLLER_USER@$CONTROLLER_ADDR 'mkdir -p ~/fh-engine'
 cd path/to/this/bundle
-scp fh-engine.tar docker-compose.yml engine-config.json deployment-spec.json engine.env \\
+scp fh-engine.tar docker-compose.yml engine-config.json deployment-spec.json engine.env ${hasSecrets ? "engine-secrets.json " : ""}\\
     $CONTROLLER_USER@$CONTROLLER_ADDR:~/fh-engine/${modelsTransfer}
 \`\`\`
@@ -37057,14 +37118,18 @@ scp fh-engine.tar docker-compose.yml engine-config.json deployment-spec.json eng
 ${runBlock}
 \`\`\`
-## Agent memory
+## Agent memory & durable data
+Each container's durable data is a plain host directory in this bundle,
+\`./workspaces/<container>/\` (mounted read-write at \`/var/lib/foresthub/workspace\`):
-The workflow's memory files live in the named volume \`engine-memory\` (mounted at
-\`/var/lib/foresthub/memory\`). They survive restarts and \`docker compose down\`;
-only \`docker compose down -v\` deletes them. The volume is namespaced by the
-compose project name, which defaults to the bundle directory's name \u2014 keep it
-stable across updates, or pin it via \`COMPOSE_PROJECT_NAME\`. In this standalone
-bundle the volume is the only copy of the memory.
+- \`./workspaces/engine/\` \u2014 the engine's memory files.
+- \`./workspaces/<model>/\` \u2014 an on-device model's GGUF weights (see above).
+These are ordinary files: back them up by copying the folder, inspect them directly.
+They persist across restarts and redeploys **as long as you keep this bundle directory
+stable** \u2014 deploy into the same path each time; a fresh directory starts empty. This
+bundle is the only copy; there is no backend mirror.
 `;
 }
 function slugify2(name) {
@@ -37099,15 +37164,24 @@ async function writeOutput(spec, resourceSecrets, cfg, req, componentEnv = {}) {
   for (const c of spec.components) {
     if (c.config !== void 0) await emit(configFileName(c.name), json2(c.config));
   }
+  const secretDocs = Object.keys(resourceSecrets).length > 0 ? { engine: resourceSecrets } : {};
   await emit("deployment-spec.json", json2(spec));
-  await emit("docker-compose.yml", composeYaml(spec));
-  await emit("engine.env", envFile(cfg, resourceSecrets), true);
-  await emit("README.md", readme(spec, cfg, req.hasProviderModel));
+  await emit("docker-compose.yml", composeYaml(spec, secretDocs));
+  await emit("engine.env", envFile(cfg), true);
+  for (const [name, doc] of Object.entries(secretDocs)) {
+    await emit(secretsFileName(name), json2(doc), true);
+  }
+  await emit("README.md", readme(spec, cfg, req.hasProviderModel, Object.keys(secretDocs).length > 0));
   for (const [name, text] of Object.entries(componentEnv)) {
     await emit(`${name}.env`, text, true);
   }
-  if (Object.values(cfg.models).some((b) => b.location === "device")) {
-    await fs8.mkdir(path11.join(dir, "models"), { recursive: true });
+  const workspaceSources = new Set(
+    spec.components.flatMap(
+      (c) => (c.volumes ?? []).map((v) => v.split(":")[0] ?? "").filter((src) => src.startsWith("./workspaces/"))
+    )
+  );
+  for (const src of workspaceSources) {
+    await fs8.mkdir(path11.join(dir, src), { recursive: true });
   }
   return written;
 }
@@ -37391,7 +37465,6 @@ async function deployCommand(workflowPath, args2) {
       cfg,
       {
         id: slugify2(workflowName),
-        status: "active",
         engineImage: ENGINE_IMAGE,
         llamaServerImage: LLAMA_SERVER_IMAGE
       },

package/dist-cli/deployment.yaml CHANGED Viewed

@@ -1,16 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 ForestHub.
 openapi: 3.0.3
 info:
   title: ForestHub Deployment Spec Contract
   version: 0.1.0
-  description: "Resolved, contract-defined description of a device's component set for one deployment (types only). Produced once by a packaging step (the CLI for the OSS path, the FE/backend for the paid path) and consumed two ways: the OSS one-shot CLI renders it to containers and exits; the paid ranger reconciles desired-vs-actual against it. Components are generic: the spec never names engine, llama-server, or any specific component, so a new OSS or paid component is added without touching this contract."
+  description: "The resolved, component-agnostic set of containers to run on a device for one deployment."
 paths: {}
 components:
   schemas:
     DeploymentSpec:
       type: object
-      required: [schemaVersion, id, status, components]
-      description: "The resolved set of components to run on one device for one deployment, plus its identity and lifecycle status. Every decision (which components run, their images, device access, config file content) is computed once by the packaging step and frozen here, so a renderer renders it without re-deriving anything. The spec is the self-contained, restartable source of truth: spec + cached images + device-local env files are all a device needs to (re)start offline."
+      required: [schemaVersion, id, components]
+      description: "The resolved set of components to run on one device for one deployment, plus its identity. Every decision is frozen at packaging time."
       properties:
         schemaVersion:
           type: integer
@@ -22,52 +25,45 @@ components:
         createdAt:
           type: string
           format: date-time
-          description: "When the packaging step produced this spec. Stamped by the producer; drives deployment history ordering."
-        status:
-          type: string
-          enum: [active, inactive]
-          description: "Whether this spec is the one a device should currently be running. The active spec is the reconcile/render target; inactive specs are history or rollback candidates."
+          description: "When this spec was produced, stamped by the producer."
         components:
           type: array
-          description: "The components to run for this deployment, each a fully resolved container. The list is unordered: components do not declare dependencies on one another. Coupling between components (e.g. the engine reaching an on-device model) is expressed as a URL the consumer connects to at runtime with retry, never as a start-ordering edge, so the model works identically whether the dependency runs on this device or another one. The packaging step expands any one-to-many component (e.g. one llama-server image per on-device model) into separate concrete entries here."
+          description: "The components to run for this deployment, each a fully resolved container. Unordered — components declare no dependencies on one another."
           items:
             $ref: "#/components/schemas/DeployComponent"
     DeployComponent:
       type: object
       required: [name, image]
-      description: "One resolved container to run as part of a deployment. Generic by design: it carries only runtime-neutral container knobs the renderer passes through, never a component-typed config schema. A component's own config shape lives in that component's contract (e.g. the engine's EngineConfig in engine.yaml), referenced directly by whoever produces and consumes that config; this spec only transports the rendered config content as opaque file bytes. Adding a component, OSS or paid, means producing one of these, not editing this contract."
+      description: "One resolved container to run as part of a deployment. Generic by design: carries only runtime-neutral container knobs, never a component-typed config schema."
       properties:
         name:
           type: string
-          description: 'Unique component name within the deployment. Doubles as the container/service name the renderer emits, the basename of any device-local env file the operator supplies ("<name>.env"), and the address other components reach this one by over the container network.'
+          description: "Unique component name within the deployment."
         image:
           type: string
-          description: 'OCI image reference, frozen at packaging time. OSS: a local convention tag built before deploy, e.g. "foresthub/engine:local". Paid: a registry-qualified, digest-pinned ref the ranger resolves and freezes, e.g. "ghcr.io/foresthubai/engine:1.2.0@sha256:abc123...". Which registry and how the daemon authenticates to it are device-side config, not part of this string.'
+          description: 'OCI image reference, frozen at packaging time. OSS: a locally-built convention tag, e.g. "foresthub/engine:local". Paid: a registry-qualified, digest-pinned ref, e.g. "ghcr.io/foresthubai/engine:1.2.0@sha256:...".'
         pull:
           type: string
           enum: [always, missing, never]
-          description: 'Image pull policy, emitted as the renderer''s pull_policy. Omit to default to "missing" (pull only if absent locally — correct for any registry image). Use "never" for an image built locally and present in no registry (the OSS engine); "always" re-pulls on every start.'
+          description: 'Image pull policy. Omit to default to "missing" (pull only if absent locally); "never" for a locally-built image in no registry; "always" re-pulls on every start.'
         command:
           type: array
-          description: 'Overrides the image''s default command/entrypoint arguments, in exec form — one token per element, e.g. ["--model", "/models/x.gguf", "--ctx-size", "4096"]. Runtime-neutral: every runtime can override a container''s command. Lets a CLI-flag-configured image (llama-server and many third-party servers) run unwrapped — the packaging step puts the flags here instead of baking a JSON-to-flags translation into a wrapper image. Omit to use the image''s own default command.'
+          description: 'Overrides the image''s default command/entrypoint arguments, in exec form — one token per element, e.g. ["--model", "/path/x.gguf", "--ctx-size", "4096"]. Omit to use the image''s default command.'
           items:
             type: string
         config:
           type: object
           additionalProperties: true
-          description: "Structured config for the component, frozen at packaging time. The renderer serializes it to JSON, writes it to a device-local file, bind-mounts that file read-only at configPath, and hashes it into a recreate trigger (compose does not track bind-mount content). How the component interprets the file — read it as JSON, convert it to CLI args, expand it into several native config files — is the image's entrypoint, not this spec; a non-JSON image is wrapped with a thin entrypoint that converts. Omit for a component configured only by its image defaults and its device-local env. Never contains secrets; those arrive as environment variables from the device-local env file."
-        configPath:
-          type: string
-          description: 'Absolute in-container path to mount the config file at. Omit to use the convention default "/etc/foresthub/config.json", which first-party components read by default. Set it to drop in a JSON-configured third-party image that reads its config elsewhere, e.g. "/app/config.json". Ignored when config is absent.'
+          description: "Structured config for the component, frozen at packaging time. Omit for a component configured only by its image defaults and its device-local env. Never contains secrets."
         volumes:
           type: array
-          description: 'Persistent or host volume mounts in compose short form, e.g. "engine-memory:/var/lib/foresthub/memory" or "./models:/models:ro". Empty when the component is stateless and mounts nothing beyond its config files.'
+          description: 'Persistent or host volume mounts in compose short form, e.g. "./workspaces/engine:/var/lib/foresthub/workspace" or "./data:/data:ro". Empty when the component is stateless and mounts nothing beyond its config files.'
           items:
             type: string
         devices:
           type: array
-          description: 'Resolved host device nodes to pass into the container, e.g. "/dev/gpiochip0", "/dev/ttyUSB0". One entry per distinct cdev node the component binds, computed once from the workflow''s hardware against the device manifest. Empty when the component uses no cdev hardware; ADC/DAC/PWM have no single node and go through privileged instead.'
+          description: 'Resolved host device nodes to pass into the container, e.g. "/dev/gpiochip0", "/dev/ttyUSB0". Empty when the component binds no cdev hardware.'
           items:
             type: string
         ports:
@@ -80,4 +76,30 @@ components:
           description: "Run the container privileged. Required for hardware with no single device node to grant (ADC/DAC/PWM use sysfs paths like /sys/class/pwm, /sys/bus/iio). False when the component uses only cdev hardware (use devices) or none."
         user:
           type: string
-          description: 'Container user as "UID[:GID]", e.g. "0:0" for root. The renderer passes it through verbatim. Needed when a nonroot image must reach root-owned resources: the engine image runs nonroot but has to open the root-owned device nodes / sysfs files granted via devices/privileged, so its component sets "0:0". Omit to use the image''s own default user.'
+          description: 'Container user as "UID[:GID]", e.g. "0:0" for root. Set when a nonroot image must reach root-owned resources. Omit to use the image''s default user.'
+        healthcheck:
+          $ref: "#/components/schemas/HealthCheck"
+    HealthCheck:
+      type: object
+      required: [test]
+      description: "In-container readiness/liveness probe. Present only when the image ships a probe tool; omit otherwise."
+      properties:
+        test:
+          type: array
+          description: 'The probe command in compose exec form. The first token is the probe kind: "CMD" runs the remaining tokens as an argv, "CMD-SHELL" runs the single following string in a shell, "NONE" disables a healthcheck the image baked in. Point it at a tool present in the image, e.g. ["CMD", "curl", "-f", "http://localhost:8080/health"]. A component reachable only by liveness (no readiness endpoint) probes a cheaper signal; one with no in-image probe at all omits the enclosing healthcheck entirely.'
+          items:
+            type: string
+        interval:
+          type: string
+          description: 'How often to run the probe once the container is up, as a compose/Go duration, e.g. "30s". Omit to use the renderer default.'
+        timeout:
+          type: string
+          description: 'How long one probe may run before it counts as a failure, e.g. "10s". Omit to use the renderer default.'
+        retries:
+          type: integer
+          minimum: 1
+          description: "Consecutive probe failures before the container is marked unhealthy. Omit to use the renderer default."
+        startPeriod:
+          type: string
+          description: 'Grace window after container start during which probe failures neither count against retries nor mark the container unhealthy, sized to the component''s worst-case warmup, e.g. a llama-server loading a multi-GB model. A container still not healthy when this elapses is the universal failure backstop. e.g. "40s".'