@deeeed/metamask-harness 0.91.0 → 0.91.2

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.91.2 - 2026-10-13
+
+### Added
+
+- Support the registered terminal-backend pack through the public provider, with pack-owned startup, invocation-owned teardown and indexed attempt logs. Backend recipes inherit the shared engine.
+- Forward existing shared QA suite, recipe digest, owned-process and portability helpers through the public provider so dependency-free packs can use their installed tooling.
+
+## 0.91.1 - 2026-10-12
+
+### Fixed
+
+- Restore the selected web-dapp venue policy, digest fence and MetaMask signer on each provider invocation, including live conformance after static preflight.
+- Use adapter-web 0.7.2 so Terminal recipes record their owned browser through the shared recorder.
+
 ## 0.91.0 - 2026-10-12
 
 - Support Extension `ui.navigate page=settings` through the visible account menu and verify the Settings page before returning.

package/adapters/terminal-backend/action-manifest.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://farmslot.io/schemas/action-manifest-v1.schema.json",
+  "actions": {
+    "end": { "description": "Finish a headless recipe.", "examples": [{ "action": "end", "status": "pass" }] }
+  }
+}

package/dist/adapters/plugin-surface.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fencePolicy, POLICY_DIGEST_ENV, POLICY_ENV, PolicyFenceError } from "@farmslot/adapter-web/web-dapp";
-import { adapterPlugin, AdapterPluginError } from "@farmslot/recipe-cli/harness";
+import { adapterPlugin, AdapterPluginError, harnessAdapter } from "@farmslot/recipe-cli/harness";
 import { libraryAdapterFiles } from "@farmslot/recipe-runner";
 import { configPath, declaredLibraryPathEnv, readConfig } from "../review/knowledge.js";
 import { bindWebDappPolicy } from "./web-dapp/surface.js";
@@ -41,7 +41,8 @@ async function fenceBoundPolicy() {
     throw error;
   }
 }
-async function afterAdapterLoad() {
+async function afterAdapterLoad(adapterId) {
+  if (adapterId) bindPluginPolicy(harnessAdapter(adapterId));
   try {
     await fenceBoundPolicy();
   } catch (error) {
@@ -51,12 +52,16 @@ async function afterAdapterLoad() {
     throw error;
   }
 }
-function adoptPluginAdapter(adapter) {
+function bindPluginPolicy(adapter) {
   const surface = bindWebDappPolicy(adapter);
   const policy = adapter;
   if (policy.extends === "web-dapp" && typeof policy.policy?.module === "string") {
     boundPolicy = { adapterId: adapter.id, file: policy.policy.module };
   }
+  return surface;
+}
+function adoptPluginAdapter(adapter) {
+  const surface = bindPluginPolicy(adapter);
   return {
     ...surface,
     run: {

package/dist/adapters/terminal-backend/provider.js

@@ -0,0 +1,152 @@
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { defineAdapter } from "@farmslot/adapter-sdk";
+import { indexArtifactManifest, isRecipeExecution, usageError, writeContainedArtifact } from "@farmslot/recipe-cli/harness";
+import { validatePackPortability } from "@farmslot/protocol/node/pack-portability";
+async function createBackendProvider(context) {
+  if (!context.project?.root || !path.isAbsolute(context.project.root)) {
+    throw usageError("terminal-backend requires a registered project root.");
+  }
+  const root = fs.realpathSync(context.project.root);
+  const lifecycle = fs.realpathSync(path.join(root, "scripts/backend.mjs"));
+  if (!lifecycle.startsWith(root + path.sep)) throw usageError("Backend lifecycle must belong to the registered pack.");
+  const { configuration, health, main } = await import(pathToFileURL(lifecycle).href);
+  const target = context.target.value;
+  const ports = context.slot && "ports" in context.slot ? context.slot.ports : {};
+  const cfg = () => {
+    const state = path.join(target, ".agent/terminal-backend/service.json");
+    const record = fs.existsSync(state) ? JSON.parse(fs.readFileSync(state, "utf8")) : {};
+    return configuration(
+      target,
+      context.options?.watcherPort ?? ports.port ?? ports.devServerPort ?? record.api,
+      ports.redis_port ?? record.redis,
+      context.slot?.value ?? record.slot
+    );
+  };
+  const args = (action) => {
+    const c = cfg();
+    return [action, c.checkout, String(c.api), String(c.redis), c.slot];
+  };
+  const executing = isRecipeExecution(context.command, context.options ?? {});
+  if (executing) cfg();
+  const owner = executing ? randomBytes(16).toString("hex") : void 0;
+  const previous = /* @__PURE__ */ new Map();
+  const setEnv = (key, value) => {
+    if (!previous.has(key)) previous.set(key, process.env[key]);
+    process.env[key] = value;
+  };
+  const serviceLog = path.join(target, ".agent/terminal-backend/service.log");
+  const logOffset = fs.existsSync(serviceLog) ? fs.statSync(serviceLog).size : 0;
+  const output = path.resolve(target, String(context.options?.artifactsDir ?? context.project.artifactDir));
+  const manifest = path.join(output, "artifact-manifest.json");
+  const manifestIdentity = () => {
+    try {
+      const s = fs.statSync(manifest, { bigint: true });
+      return [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].join(":");
+    } catch (error) {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    }
+  };
+  const previousManifest = manifestIdentity();
+  if (owner) {
+    setEnv("BACKEND_OWNER_ID", owner);
+    setEnv("BACKEND_LIFECYCLE_SCRIPT", lifecycle);
+  }
+  const cleanup = async () => {
+    if (owner) await main([...args("stop"), owner]);
+  };
+  const logSource = () => ({ label: "NestJS and monitor", path: serviceLog });
+  const hint = "Prepare the selected slot with the full profile.";
+  const runtime = defineAdapter({
+    id: "terminal-backend",
+    sdkVersion: 1,
+    targets: ["cli"],
+    headless: true,
+    resolveSlotPorts() {
+      const c = cfg();
+      setEnv("BACKEND_API_PORT", String(c.api));
+      setEnv("BACKEND_REDIS_PORT", String(c.redis));
+      setEnv("BACKEND_SLOT_ID", c.slot);
+    },
+    async runtimeStatus() {
+      try {
+        await health(cfg());
+        return { decision: "ready", reasons: ["Redis and a fresh complete v3 snapshot are ready."] };
+      } catch (error) {
+        return { decision: "blocked", reasons: [error.message], nextAction: hint };
+      }
+    },
+    readiness: { statusRuntime: true, captureProviders: [], readyIndicator: () => "OK" },
+    logSources: () => [logSource()],
+    appLogSource: logSource,
+    hints: { launch: hint, relaunch: hint, runtimeProbeRecovery: () => "Inspect the slot service.log and run farmslot doctor --conformance." },
+    devServer: {
+      label: "NestJS",
+      describe: () => "Slot backend",
+      stop() {
+        const result = spawnSync(process.execPath, [lifecycle, ...args("stop"), owner ?? ""], { encoding: "utf8", timeout: 3e4 });
+        if (result.error || result.status !== 0) throw result.error ?? new Error(result.stderr);
+        return { kind: "headless", message: "Backend stopped; Redis volume retained.", userAction: hint };
+      }
+    },
+    harness: {
+      // Installation and destructive cleanup belong to the pack's lifecycle hooks.
+      install: { entry: "", fallback: "" },
+      cleanup: { entry: "", fallback: "" },
+      verify: () => ({ inProcess: async () => async (_args, io) => {
+        const result = await validatePackPortability(root);
+        if (result.length) throw new Error(result.join("\n"));
+        io.out("Portable headless API provider; capture and HUD are unsupported.");
+        return 0;
+      } })
+    },
+    runtimeContext: { forbiddenFields: ["cdpPort", "metroPort", "simulator", "adbSerial", "extensionId"] },
+    launch: async () => {
+      await main(args("start"));
+      return 0;
+    },
+    actions: {
+      manifestPath: () => {
+        const product = path.join(target, "tests/recipes/action-manifest.json");
+        return fs.existsSync(product) ? product : fileURLToPath(new URL("../../../adapters/terminal-backend/action-manifest.json", import.meta.url));
+      },
+      semantic: [],
+      cdpTarget: { transport: "none", probePath: "" }
+    }
+  });
+  if (executing) runtime.resolveSlotPorts();
+  let finalized = false;
+  return {
+    runtime,
+    ...owner ? {
+      cancel: cleanup,
+      async finalize() {
+        if (finalized) return;
+        finalized = true;
+        try {
+          try {
+            await cleanup();
+          } finally {
+            const currentManifest = manifestIdentity();
+            if (fs.existsSync(serviceLog) && currentManifest !== void 0 && currentManifest !== previousManifest) {
+              await writeContainedArtifact(output, "logs/backend.log", fs.readFileSync(serviceLog).subarray(logOffset), "Backend logs");
+              await indexArtifactManifest(manifest, [{ category: "log", label: "Backend and monitor logs", path: "logs/backend.log", type: "text" }]);
+            }
+          }
+        } finally {
+          for (const [key, value] of previous) {
+            if (value === void 0) delete process.env[key];
+            else process.env[key] = value;
+          }
+        }
+      }
+    } : {}
+  };
+}
+export {
+  createBackendProvider
+};

package/dist/provider.js

@@ -9,6 +9,7 @@ import {
   optionStrings,
   usageError
 } from "@farmslot/recipe-cli/harness";
+import { createAdapterRegistry } from "@farmslot/adapter-sdk";
 import { MAINNET_RUN_OWNER_ENV } from "../library/actions/shared/perps/mainnet-order-ledger.mjs";
 import { adoptPluginAdapter, afterAdapterLoad, configuredLibrarySources, operatorLibraryEnv } from "./adapters/plugin-surface.js";
 import { abortRunMainnetOrders, cancelRunMainnetOrders } from "./adapters/perps-mainnet-cleanup.js";
@@ -20,14 +21,26 @@ import { providerHost } from "./host.js";
 import { configureProviderReadiness, doctorOptions } from "./provider-doctor.js";
 import { statusOptions, stopOptions } from "./provider-lifecycle.js";
 import { createLogsOptions } from "./provider-logs.js";
+import { createBackendProvider } from "./adapters/terminal-backend/provider.js";
 import { providerHost as providerHost2 } from "./host.js";
 import { PUBLIC_COMMANDS } from "./command-contract.js";
+import { digestRecipeDocument, RECIPE_SUITE_SCOPE_SCHEMA_URL, validateRecipeActionManifestDocument } from "@farmslot/protocol";
+import { validatePackPortability, packMachineNames } from "@farmslot/protocol/node/pack-portability";
+import { freezeRecipeSuiteScope, finalizeRecipeSuite, digestRecipeLibrary } from "@farmslot/recipe-runner";
+import { runOwnedRecipeProcess } from "@farmslot/recipe-runner/adapters/core";
+import { withRecipeSignals } from "@farmslot/recipe-cli/harness";
 async function createProvider(context) {
   configureHarnessHost(context.host ?? providerHost);
   configureHarnessAdapters(adapterRegistry);
   const selection = context.adapter?.value;
   if (!selection) throw usageError("The MetaMask provider requires a resolved adapter.");
   const adapter = adapterForPlatform(selection) ?? selection;
+  if (adapter === "terminal-backend") {
+    const registry = createAdapterRegistry();
+    for (const id of adapterRegistry.list()) registry.register(adapterRegistry.get(id));
+    configureHarnessAdapters(registry);
+    return createBackendProvider(context);
+  }
   const options = {
     ...context.options,
     ...!context.options?.platform && (selection === "ios" || selection === "android") ? { platform: selection } : {}
@@ -38,7 +51,7 @@ async function createProvider(context) {
     env: operatorLibraryEnv(),
     adopt: adoptPluginAdapter
   });
-  await afterAdapterLoad();
+  await afterAdapterLoad(adapter);
   const runtime = getAdapterSurface(adapter);
   configureProviderReadiness(runtime);
   const executes = isRecipeExecution(context.command, options);
@@ -73,7 +86,17 @@ async function createProvider(context) {
   };
 }
 export {
+  RECIPE_SUITE_SCOPE_SCHEMA_URL,
   createProvider,
+  digestRecipeDocument,
+  digestRecipeLibrary,
+  finalizeRecipeSuite,
+  freezeRecipeSuiteScope,
+  packMachineNames,
   PUBLIC_COMMANDS as providerCommands,
-  providerHost2 as providerHost
+  providerHost2 as providerHost,
+  runOwnedRecipeProcess,
+  validatePackPortability,
+  validateRecipeActionManifestDocument,
+  withRecipeSignals
 };

package/docs/TERMINAL-BACKEND-PROVIDER.md

@@ -0,0 +1,21 @@
+# Terminal backend provider
+
+Registered backend packs select `@deeeed/metamask-harness/provider` and adapter `terminal-backend`. The pool supplies the installed package through `MM_HARNESS_PACKAGE_ROOT`. The shared project loader supplies `project.root`, the directory containing the registered pack's `project.json`.
+
+The provider imports that pack's `scripts/backend.mjs` and uses its existing `configuration`, `health` and `main` functions. The pack owns service startup, health checks, Redis ports, startup recovery and volumes. Slot resources must supply the API port and `redis_port`; there is no default Redis port. Installation and destructive cleanup run through pack hooks, not harness overlay installation.
+
+Backend recipes inherit the shared engine. Their action manifest lives at the selected checkout's `tests/recipes/action-manifest.json`; a packaged `end` manifest supports an empty checkout during planning. Recipe assets remain with the backend code. No backend recipes or generic runner implementations are bundled here.
+
+Executing `run` and `call` invocations assign a unique `BACKEND_OWNER_ID` and expose `BACKEND_LIFECYCLE_SCRIPT` and slot ports to action children. Cancellation and finalization stop only that owner through the pack lifecycle. Finalization indexes the current attempt's service log when this invocation creates or updates the shared artifact manifest and restores caller environment values. Early startup failures leave previous evidence packages untouched; service diagnostics remain in the slot's runtime log. Attached services keep their existing ownership. Previews assign no owner and start no services. Capture and HUD are unsupported for this headless runtime.
+
+The public provider forwards these existing shared APIs for dependency-free packs. Their contracts and versions remain owned by the listed packages:
+
+| Package | Forwarded exports |
+| --- | --- |
+| `@farmslot/protocol` | `digestRecipeDocument`, `RECIPE_SUITE_SCOPE_SCHEMA_URL`, `validateRecipeActionManifestDocument` |
+| `@farmslot/protocol/node/pack-portability` | `validatePackPortability`, `packMachineNames` |
+| `@farmslot/recipe-runner` | `freezeRecipeSuiteScope`, `finalizeRecipeSuite`, `digestRecipeLibrary` |
+| `@farmslot/recipe-runner/adapters/core` | `runOwnedRecipeProcess` |
+| `@farmslot/recipe-cli/harness` | `withRecipeSignals` |
+
+The backend pack's mandatory QA gate consumes the suite, digest, process and signal APIs. Its CI and prerequisite hooks consume portability. Packs import the public provider export and do not resolve private files or transitive package paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.91.0",
+  "version": "0.91.2",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -24,7 +24,7 @@
     "@farmslot/adapter-node": "0.1.14",
     "@farmslot/adapter-rn": "0.20.1",
     "@farmslot/adapter-sdk": "0.9.1",
-    "@farmslot/adapter-web": "0.7.1",
+    "@farmslot/adapter-web": "0.7.2",
     "@farmslot/agent-runtime": "0.18.1",
     "@farmslot/handoff": "^0.3.1",
     "@farmslot/protocol": "0.40.0",