@openhands/extensions 0.25.0 → 0.27.0

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 });
+  }
+});