@openhands/extensions 0.24.0 → 0.26.0

package/skills/canvas-extension-api/references/sidecar-pattern.md

@@ -1,29 +1,68 @@
 # Sidecar-backed Apps
 
-Use this reference when an App needs a separately installed service. Host API 1 supports a browser App package and authenticated Agent Server HTTP requests; it does not provide Sidecar installation, process management, connection brokering, Automation adaptation, arbitrary install hooks, or an Agent Server WebSocket capability.
+Use this reference when an App needs a service in addition to its browser bundle. Choose either an optional package-owned managed backend, when the target Agent Server and Canvas host expose that capability, or a manual/deployment-owned Sidecar. Browser-only Apps remain valid.
+
+The managed-backend contract is available on the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Until a release containing both lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` in `GET /server_info`; absence means the managed view path is unsupported, not that the App should guess a port or fall back to hidden Canvas state. Use the host helper only at the minimum host version documented in [v1-contract.md](v1-contract.md).
 
 ## Keep three boundaries
 
-1. **Canvas App package**: ship `canvas-extension.json` and exactly one self-contained browser ESM entrypoint exporting `activate(host)`. Bundle UI dependencies, CSS, and required assets into that entrypoint.
-2. **Sidecar distribution**: distribute the service, its versioned artifacts, and its service-specific installation and operation mechanism separately.
-3. **Onboarding and operator layer**: implement this as a guided UI in the App view. Present status, disclosures, explicit consent, and lifecycle actions there. Do not infer that installing or enabling the Canvas App authorizes any Sidecar mutation.
+1. **Canvas App UI**: always ship `canvas-extension.json` and exactly one self-contained browser ESM entrypoint exporting `activate(host)`. Bundle UI dependencies, CSS, and required assets into that entrypoint.
+2. **Service distribution and ownership**: for a managed backend, declare checksum-pinned platform artifacts in the same package and let the owning Agent Server prepare and run them. For a manual Sidecar, distribute and operate the service separately. Do not combine the models or add a general install hook.
+3. **Onboarding and operator layer**: implement this as guided UI in the App view. Present status, disclosures, explicit revision-bound consent, and lifecycle actions there. Installing or enabling the App never authorizes backend preparation or startup.
+
+## Declare a package-owned managed backend
+
+Add the optional `backend` block only when the App owns its service artifacts:
+
+```json
+{
+  "backend": {
+    "schema_version": 1,
+    "artifacts": {
+      "linux-amd64": {
+        "path": "backend/linux-amd64.tar.gz",
+        "sha256": "<64 lowercase hex characters>"
+      },
+      "linux-arm64": {
+        "path": "backend/linux-arm64.tar.gz",
+        "sha256": "<64 lowercase hex characters>"
+      }
+    },
+    "argv": [
+      "{artifact_dir}/bin/server",
+      "--host=127.0.0.1",
+      "--port={port}",
+      "--data-dir={data_dir}"
+    ],
+    "health": {
+      "path": "/health",
+      "timeout_seconds": 30,
+      "interval_seconds": 0.1
+    },
+    "inherit_environment": ["LANG", "PATH", "TZ"]
+  }
+}
+```
+
+Artifact paths are package-relative `.tar.gz` files. The executable in `argv[0]` must resolve inside `{artifact_dir}`. The argv is a structured string list, never shell source; supported placeholders are `{artifact_dir}`, `{data_dir}`, and `{port}`. The current server supports Linux amd64 and arm64 and reports other platforms as `unsupported`.
 
 ## Choose a connection boundary
 
 Prefer connection patterns in this order:
 
-1. **Narrow Agent Server bridge**: add a backend-owned, authenticated endpoint for the required Sidecar operations and call it through `host.agentServer.request` with root-relative paths. Keep Sidecar credentials and routing on the backend.
-2. **Documented future or deployment capability**: require a host or deployment adapter that deliberately exposes Sidecar access, feature-detect it, and document the required version and deployment contract.
-3. **Direct browser connection only when explicitly non-portable**: document its origin, authentication, exposure, and deployment ownership. Do not represent this design as a portable host API 1 App.
-4. **Bounded polling through the Agent Server**: use a narrow bridge for status where live events are unavailable in v1. Bound intervals, respect visibility, abort on disposal, and show stale state.
+1. **Managed backend view**: for a package-owned backend, feature-detect `host.appBackendView` and call `host.appBackendView.mount({ container })`. Canvas owns session creation, iframe isolation, ingress validation, and revocation.
+2. **Narrow Agent Server bridge**: for a manual Sidecar, add a backend-owned, authenticated endpoint for only the required operations and call it through `host.agentServer.request` with root-relative paths. Keep Sidecar credentials and routing on the backend.
+3. **Documented deployment capability**: require a deployment adapter that deliberately exposes Sidecar access, feature-detect it, and document its version and contract.
+4. **Direct browser connection only when explicitly non-portable**: document its origin, authentication, exposure, and deployment ownership. Do not represent this design as a portable host API 1 App.
+5. **Bounded polling through the Agent Server**: use a narrow bridge for status where live events are unavailable in v1. Bound intervals, respect visibility, abort on disposal, and show stale state.
 
 Reject guessed localhost names or ports, `window.location` derivation, Canvas internals, undocumented globals, and embedded credentials. Do not attempt to route a Sidecar or Automation call through `host.agentServer.request` without a documented Agent Server bridge.
 
 ## Model onboarding and operations
 
-Represent service state explicitly: `unknown`, `probing`, `missing`, `stopped`, `incompatible`, `ready`, and `unhealthy`. Preserve actionable failures and transition deliberately for consent, install, start, repair, upgrade, and stop failures. Treat unavailable Sidecar status as a supported UI state.
+For a managed backend, use the server states exactly: `missing`, `stopped`, `starting`, `ready`, `unhealthy`, and `unsupported`. For a manual Sidecar, model additional UI-only states such as `unknown`, `probing`, and `incompatible` when needed. Preserve actionable failures and transition deliberately for consent, prepare/install, start, repair, upgrade, and stop failures.
 
-Before any mutating action, disclose the source, version, checksum, install and data paths, ports and network exposure, process behavior, credentials, and rollback or uninstall behavior. Obtain explicit consent for each applicable action.
+Before any mutating action, disclose the source, resolved revision, version, checksums, install and data paths, ports and network exposure, process behavior, inherited environment names, and rollback or uninstall behavior. Obtain explicit consent for each applicable action. Managed-backend prepare and start calls carry the exact installed revision; updating the package invalidates prior approval.
 
 Keep these actions separate and idempotent where meaningful:
 

package/skills/canvas-extension-api/references/v1-contract.md

@@ -23,7 +23,7 @@ Inspect these files when targeting a newer OpenHands revision:
 
 Treat the active Agent Server as the owner of installed apps. Source, resolved revision, files, manifest, and enabled state live on that backend. Switching backend replaces the active app inventory.
 
-Treat enabled code as trusted same-realm JavaScript. No iframe, worker sandbox, granular permission boundary, or CSS security boundary exists in v1. Enabled code has the ambient browser authority available to Canvas and can use authenticated helpers for the current backend.
+Treat enabled code as trusted same-realm JavaScript. No iframe, worker sandbox, granular permission boundary, or CSS security boundary exists in v1 for App-authored code or the App's own frame. Enabled code has the ambient browser authority available to Canvas and can use authenticated helpers for the current backend. The only frame in v1 is the host-owned managed-backend view, created by the `host.appBackendView` helper described below and never by the App; it isolates the backend's own content on a separate ingress origin and grants the App no authority it did not already have.
 
 Keep install and enable separate. Installation produces a disabled app. Enabling is the explicit execution consent point. Enablement and disablement are hot and require no restart.
 
@@ -42,6 +42,22 @@ interface CanvasExtensionManifest {
   contributes?: {
     pages?: CanvasExtensionPageContribution[] | null;
   } | null;
+  backend?: CanvasExtensionBackend | null;
+}
+
+interface CanvasExtensionBackend {
+  schema_version: 1;
+  artifacts: Partial<Record<"linux-amd64" | "linux-arm64", {
+    path: string;
+    sha256: string;
+  }>>;
+  argv: string[];
+  health?: {
+    path?: string;
+    timeout_seconds?: number;
+    interval_seconds?: number;
+  };
+  inherit_environment?: string[];
 }
 
 interface CanvasExtensionPageContribution {
@@ -53,7 +69,23 @@ interface CanvasExtensionPageContribution {
 }
 ```
 
-Required manifest fields are `schema_version`, `name`, `version`, and `entrypoint`. A useful page package also supplies `display_name`, `description`, and at least one `contributes.pages` entry.
+Required manifest fields are `schema_version`, `name`, `version`, and `entrypoint`. A useful page package also supplies `display_name`, `description`, and at least one `contributes.pages` entry. `backend` is optional: omitting it preserves a browser-only App or a manual/deployment-owned Sidecar.
+
+The managed-backend contract requires the stacked, unreleased Agent Server changes in [software-agent-sdk PR #5270](https://github.com/OpenHands/software-agent-sdk/pull/5270) at `ac7b322ddf7d2e0e90a3643c5e26d848236af9a3` and [PR #5272](https://github.com/OpenHands/software-agent-sdk/pull/5272) at `6d9c82973e765cce4843d6a2fb52f634efa64293`. Until a release containing both lands, those exact revisions are the minimum Agent Server implementation. Feature-detect `canvas_app_backend_bridge_v1` in `GET /server_info`; the same response must provide `app_backend_ingress_url`.
+
+The minimum host is the Agent Canvas revision that adds the optional `host.appBackendView` helper specified under Host API 1 below — the frontend change in OpenHands/OpenHands#17641, which this document's PR lists as a merge prerequisite. No upstream release pins that helper yet, so there is no release number to name; until there is, the minimum host is exactly "the build whose `host.appBackendView` is present", and feature-detecting that helper is the only supported test. Absence is an actionable unsupported state, not a reason to guess an ingress port or read Canvas internals.
+
+All references in this bundle to "the minimum host version documented in `v1-contract.md`" mean this paragraph.
+
+For a managed backend:
+
+- Key `artifacts` only by `linux-amd64` or `linux-arm64`; one matching entry is sufficient.
+- Keep each artifact `path` package-relative, contained, and ending in `.tar.gz`.
+- Set `sha256` to exactly 64 lowercase hexadecimal characters.
+- Use a non-empty structured `argv`; `argv[0]` must resolve inside `{artifact_dir}`.
+- Use only `{artifact_dir}`, `{data_dir}`, and `{port}` placeholders.
+- Keep `health.path` root-relative. Defaults are `/health`, 30 seconds, and 0.1 seconds.
+- Request only `LANG`, `LC_ALL`, `LC_CTYPE`, `PATH`, `TMPDIR`, or `TZ` in `inherit_environment`, without duplicates. Ambient Agent Server credentials are never inherited.
 
 Apply these rules:
 
@@ -95,6 +127,9 @@ interface CanvasExtensionHost {
       headers?: Record<string, string>;
     }): Promise<T>;
   };
+  readonly appBackendView?: {
+    mount(options: { container: HTMLElement }): () => void;
+  };
 }
 
 type CanvasExtensionPageMount = (context: {
@@ -114,6 +149,11 @@ export function activate(
 
 The loader fetches authenticated JavaScript text, creates a temporary Blob URL, imports it as ESM, verifies the `activate` export, and revokes the Blob URL. Import does not activate a disabled installation.
 
+`appBackendView` is additive and optional. Feature-detect it before mounting. It is absent for host builds without the helper, no-backend and cloud selections, or selected Agent Servers without `canvas_app_backend_bridge_v1`, `app_backend_ingress_url`, and the compatible typed client. `mount({ container })` returns a disposer. The helper obtains an app-scoped session, validates the HTTP(S) ingress and sandbox, renders loading/error/retry and safe new-tab fallback, and revokes the session on disposal. It does not prepare, start, stop, or delete backend data.
+
+Every App API call is scoped to the active backend. When the user changes backend, Canvas disposes the old activation, mounted backend views, and sessions before activating the App with a fresh host snapshot.
+
+
 ## Registration constraints
 
 Register each page during activation using exactly the page ID declared in the manifest. The runtime rejects undeclared IDs and duplicate registrations.
@@ -213,6 +253,16 @@ The current Canvas frontend service calls:
 | `PATCH` | `/api/canvas-extensions/installed/{name}` | Set enabled state |
 | `DELETE` | `/api/canvas-extensions/installed/{name}` | Uninstall |
 | `GET` | `/api/canvas-extensions/installed/{name}/bundle` | Fetch entrypoint JavaScript text |
+| `GET` | `/api/canvas-extensions/installed/{name}/backend` | Read managed-backend status and revision |
+| `POST` | `/api/canvas-extensions/installed/{name}/backend/prepare` | Verify and prepare the approved revision |
+| `POST` | `/api/canvas-extensions/installed/{name}/backend/start` | Start the prepared approved revision |
+| `POST` | `/api/canvas-extensions/installed/{name}/backend/stop` | Stop the owned process group |
+| `GET` | `/api/canvas-extensions/installed/{name}/backend/logs` | Read bounded backend logs |
+| `DELETE` | `/api/canvas-extensions/installed/{name}/backend/data` | Separately delete preserved mutable data |
+
+Prepare and start bodies are `{"revision":"<exact installed revision>"}`. Status is exactly `missing`, `stopped`, `starting`, `ready`, `unhealthy`, or `unsupported`. Installation, enablement, activation, and page mounting never prepare or start a backend. Updating invalidates approval. Disable and uninstall stop owned processes and revoke bridge access but preserve backend data; data deletion is separate.
+
+The bridge advertises `canvas_app_backend_bridge_v1` and `app_backend_ingress_url` through `GET /server_info`. Its control endpoints are `POST` and `DELETE` on `/app-backends/{name}/session` at the configured ingress, which must be a separate browser origin from Canvas. Session responses contain `ingress_url`, `expires_at`, and `iframe_sandbox`; the credential is an HttpOnly cookie and never appears in the response or URL. The v1 sandbox is `allow-forms allow-modals allow-popups allow-same-origin allow-scripts`. Preserve `allow-same-origin`: the separate ingress origin is the isolation boundary, while an opaque sandbox origin causes Chromium to send `Origin: null` for mutating fetches and WebSockets, omit the partitioned cookie, and reject Worker creation with `SecurityError`.
 
 Install request:
 
@@ -243,7 +293,7 @@ Do not promise or implement these features without confirming a newer contract:
 - visualizer augmentation or replacement;
 - marketplace signing or publisher verification;
 - enforceable fine-grained permissions;
-- iframe or worker isolation;
+- iframe or worker isolation for App-authored frames: an App must not create its own frames or Workers to obtain an isolation boundary. (A host-owned managed-backend view is the one exception and is not App-authored: it is reachable only through the feature-detected `host.appBackendView` helper, which owns the ingress origin, sandbox attributes, and session lifecycle. The App never constructs that frame, picks its URL, or reads its credential.)
 - arbitrary install lifecycle scripts;
 - automatic agent-driven enablement.
 

package/skills/canvas-extension-api/scripts/validate-extension.mjs

@@ -48,6 +48,58 @@ for (const field of ["name", "version", "entrypoint"]) {
 if (typeof manifest.name === "string" && !name.test(manifest.name)) fail("Manifest name must use lowercase kebab-case.");
 if (typeof manifest.version === "string" && !semver.test(manifest.version)) fail("Manifest version must use semantic versioning.");
 
+if (manifest.backend !== undefined && manifest.backend !== null) {
+  const backend = manifest.backend;
+  if (typeof backend !== "object" || Array.isArray(backend)) {
+    fail("Manifest backend must be an object.");
+  } else {
+    if (backend.schema_version !== 1) fail("Manifest backend.schema_version must equal 1.");
+    const artifacts = backend.artifacts;
+    if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts) || Object.keys(artifacts).length === 0) {
+      fail("Manifest backend.artifacts must be a non-empty platform map.");
+    } else {
+      for (const [platform, artifact] of Object.entries(artifacts)) {
+        const label = `backend.artifacts[${platform}]`;
+        if (!new Set(["linux-amd64", "linux-arm64"]).has(platform)) fail(`${label} uses an unsupported platform.`);
+        if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) { fail(`${label} must be an object.`); continue; }
+        if (typeof artifact.path !== "string" || !artifact.path || artifact.path.startsWith("/") || artifact.path.split(/[\\/]/).includes("..") || !artifact.path.endsWith(".tar.gz")) fail(`${label}.path must be a contained relative .tar.gz path.`);
+        if (typeof artifact.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(artifact.sha256)) fail(`${label}.sha256 must be a lowercase SHA-256 checksum.`);
+      }
+    }
+    if (!Array.isArray(backend.argv) || backend.argv.length === 0 || backend.argv.some((argument) => typeof argument !== "string" || !argument || argument.includes("\0"))) {
+      fail("Manifest backend.argv must be a non-empty array of strings.");
+    } else {
+      if (!backend.argv[0].startsWith("{artifact_dir}/")) {
+        fail("Manifest backend.argv[0] must execute from {artifact_dir}.");
+      } else if (backend.argv[0].slice("{artifact_dir}/".length).split(/[\\/]/).includes("..")) {
+        fail("Manifest backend.argv[0] must resolve inside {artifact_dir}.");
+      }
+      const allowed = new Set(["{port}", "{data_dir}", "{artifact_dir}"]);
+      for (const argument of backend.argv) {
+        for (const placeholder of argument.match(/\{[^{}]+\}/g) ?? []) {
+          if (!allowed.has(placeholder)) fail(`Manifest backend.argv contains unsupported placeholder ${placeholder}.`);
+        }
+      }
+    }
+    if (backend.health !== undefined) {
+      const health = backend.health;
+      if (!health || typeof health !== "object" || Array.isArray(health)) {
+        fail("Manifest backend.health must be an object.");
+      } else {
+        if (health.path !== undefined && (typeof health.path !== "string" || !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$/.test(health.path))) fail("Manifest backend.health.path must be a root-relative HTTP path.");
+        for (const [field, maximum] of [["timeout_seconds", 300], ["interval_seconds", 10]]) {
+          if (health[field] !== undefined && (typeof health[field] !== "number" || health[field] <= 0 || health[field] > maximum)) fail(`Manifest backend.health.${field} must be greater than 0 and at most ${maximum}.`);
+        }
+      }
+    }
+    if (backend.inherit_environment !== undefined) {
+      const environment = backend.inherit_environment;
+      const allowed = new Set(["LANG", "LC_ALL", "LC_CTYPE", "PATH", "TMPDIR", "TZ"]);
+      if (!Array.isArray(environment) || environment.some((variable) => typeof variable !== "string" || !allowed.has(variable)) || new Set(environment).size !== environment.length) fail("Manifest backend.inherit_environment must contain unique names from the supported non-credential allowlist.");
+    }
+  }
+}
+
 const ids = new Set();
 const paths = new Set();
 const pages = manifest.contributes?.pages;

package/skills/canvas-extension-api/scripts/validate-extension.test.mjs

@@ -7,7 +7,7 @@ import test from "node:test";
 
 const validator = new URL("./validate-extension.mjs", import.meta.url);
 
-async function createApp(entrypoint) {
+async function createApp(entrypoint, manifestOverrides = {}) {
   const root = await mkdtemp(path.join(os.tmpdir(), "canvas-extension-validator-"));
   await mkdir(path.join(root, "dist"), { recursive: true });
   await writeFile(
@@ -20,6 +20,7 @@ async function createApp(entrypoint) {
       contributes: {
         pages: [{ id: "home", title: "Home", path: "/home" }],
       },
+      ...manifestOverrides,
     }),
   );
   await writeFile(
@@ -29,6 +30,29 @@ async function createApp(entrypoint) {
   return root;
 }
 
+function validate(root, ...options) {
+  return spawnSync(process.execPath, [validator.pathname, root, ...options], {
+    encoding: "utf8",
+  });
+}
+
+const backend = {
+  schema_version: 1,
+  artifacts: {
+    "linux-amd64": {
+      path: "backend/linux-amd64.tar.gz",
+      sha256: "a".repeat(64),
+    },
+    "linux-arm64": {
+      path: "backend/linux-arm64.tar.gz",
+      sha256: "b".repeat(64),
+    },
+  },
+  argv: ["{artifact_dir}/bin/service", "--port", "{port}", "--data", "{data_dir}"],
+  health: { path: "/health", timeout_seconds: 30, interval_seconds: 0.1 },
+  inherit_environment: ["LANG", "TZ"],
+};
+
 test("--dist uses the manifest entrypoint name", async () => {
   const root = await createApp("bundle.mjs");
   try {
@@ -58,3 +82,170 @@ test("--dist rejects sibling output chunks", async () => {
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("accepts a package-owned backend declaration", async () => {
+  const root = await createApp("extension.js", { backend });
+  try {
+    const result = validate(root, "--dist");
+    assert.equal(result.status, 0, result.stderr);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects a backend artifact path outside the package", async () => {
+  const root = await createApp("extension.js", {
+    backend: {
+      ...backend,
+      artifacts: {
+        "linux-amd64": {
+          path: "../service.tar.gz",
+          sha256: "a".repeat(64),
+        },
+      },
+    },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.notEqual(result.status, 0);
+    assert.match(
+      result.stderr,
+      /backend\.artifacts\[linux-amd64\]\.path must be a contained relative \.tar\.gz path/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects a backend argument vector that is not a structured list", async () => {
+  const root = await createApp("extension.js", {
+    backend: { ...backend, argv: "service --port {port}" },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.notEqual(result.status, 0);
+    assert.match(
+      result.stderr,
+      /backend\.argv must be a non-empty array of strings/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects a backend executable outside the prepared artifact", async () => {
+  const root = await createApp("extension.js", {
+    backend: { ...backend, argv: ["bin/service", "--port", "{port}"] },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.notEqual(result.status, 0);
+    assert.match(
+      result.stderr,
+      /backend\.argv\[0\] must execute from \{artifact_dir\}/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects a backend executable that traverses outside the artifact", async () => {
+  const root = await createApp("extension.js", {
+    backend: { ...backend, argv: ["{artifact_dir}/../outside"] },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.notEqual(result.status, 0);
+    assert.match(
+      result.stderr,
+      /backend\.argv\[0\] must resolve inside \{artifact_dir\}/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects unsupported backend argument placeholders", async () => {
+  const root = await createApp("extension.js", {
+    backend: { ...backend, argv: ["{artifact_dir}/bin/service", "{secret}"] },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /backend\.argv contains unsupported placeholder \{secret\}/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects invalid backend health settings", async () => {
+  const root = await createApp("extension.js", {
+    backend: { ...backend, health: { path: "health", timeout_seconds: 0 } },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.notEqual(result.status, 0);
+    assert.match(
+      result.stderr,
+      /backend\.health\.path must be a root-relative HTTP path/,
+    );
+    assert.match(
+      result.stderr,
+      /backend\.health\.timeout_seconds must be greater than 0 and at most 300/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+
+
+test("accepts omitted managed backend health defaults", async () => {
+  const root = await createApp("extension.js", {
+    backend: { ...backend, health: {} },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.equal(result.status, 0, result.stderr);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("rejects disallowed or duplicate inherited environment names", async () => {
+  const root = await createApp("extension.js", {
+    backend: { ...backend, inherit_environment: ["LANG", "SECRET", "LANG"] },
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.notEqual(result.status, 0);
+    assert.match(
+      result.stderr,
+      /backend\.inherit_environment must contain unique names from the supported non-credential allowlist/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("preserves browser-only packages without a backend declaration", async () => {
+  const root = await createApp("extension.js");
+  try {
+    const result = validate(root, "--dist");
+    assert.equal(result.status, 0, result.stderr);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("preserves manual sidecars with no managed backend declaration", async () => {
+  const root = await createApp("extension.js", {
+    description: "Connects to a deployment-owned sidecar configured by an operator.",
+  });
+  try {
+    const result = validate(root, "--dist");
+    assert.equal(result.status, 0, result.stderr);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});