@intentic/extension-manifest 1.317.0 → 1.319.0

package/src/permissions.test.ts

@@ -0,0 +1,98 @@
+import { ExtensionManifestSchema } from "./manifest.js";
+import { permissionProblem, sandboxRouteAllowed } from "./permissions.js";
+
+// The glob grammar: each segment of the declared path is literal or a lone `*`, and a `*` matches one whole segment
+// that the URL layer would route rather than resolve away.
+
+describe("sandboxRouteAllowed", () => {
+    test.each([
+        ["an exact route", "GET /panels", "GET", "/panels", true],
+        ["the root", "GET /", "GET", "/", true],
+        ["a trailing slash is its own route", "GET /panels", "GET", "/panels/", false],
+        ["a `*` matches one segment", "POST /panels/*/start", "POST", "/panels/my-repo/start", true],
+        ["two `*`s, two segments", "POST /workspace/repos/*/apps/*/start", "POST", "/workspace/repos/intentic/apps/web/start", true],
+        ["a `*` matches an encoded slash, which stays inside its segment", "GET /git/*/log", "GET", "/git/a%2Fb/log", true],
+        ["a `*` matches a segment holding dots", "GET /git/*/log", "GET", "/git/.config/log", true],
+        ["a `*` matches a segment of dots beyond two", "GET /git/*/log", "GET", "/git/.../log", true],
+        ["a `*` never matches an empty segment", "POST /panels/*/start", "POST", "/panels//start", false],
+        ["a `*` never crosses a slash", "POST /panels/*/start", "POST", "/panels/a/b/start", false],
+        ["a `*` never matches `..`, which resolves to /start", "POST /panels/*/start", "POST", "/panels/../start", false],
+        ["a `*` never matches `.`", "POST /panels/*/start", "POST", "/panels/./start", false],
+        ["a `*` never matches an encoded `..`", "DELETE /approvals/*", "DELETE", "/approvals/%2e%2E", false],
+        ["a `*` never matches a half-encoded `..`", "DELETE /approvals/*", "DELETE", "/approvals/.%2e", false],
+        ["a `*` never matches a backslash, which a URL reads as a slash", "POST /panels/*/start", "POST", "/panels/..\\..\\secrets/start", false],
+        ["the query string is ignored", "GET /logs/file", "GET", "/logs/file?name=daemon.log&bytes=4096", true],
+        ["the method is case-insensitive", "get /panels", "GET", "/panels", true],
+        ["the asked method is case-insensitive", "GET /panels", "get", "/panels", true],
+        ["the wrong method", "GET /panels/*/start", "POST", "/panels/a/start", false],
+        ["an undeclared path", "GET /panels", "GET", "/secrets", false],
+        ["a relative path", "GET /panels", "GET", "panels", false],
+    ] as const)("%s", (_name, entry, method, path, allowed) => {
+        expect(sandboxRouteAllowed([entry], method, path)).toBe(allowed);
+    });
+
+    test("any declared entry covering the call is enough", () => {
+        expect(sandboxRouteAllowed(["GET /panels", "POST /panels/*/start"], "POST", "/panels/a/start")).toBe(true);
+    });
+
+    test("an empty permission list allows nothing", () => {
+        expect(sandboxRouteAllowed([], "GET", "/panels")).toBe(false);
+    });
+
+    test("a malformed entry throws, naming itself", () => {
+        expect(() => sandboxRouteAllowed(["/panels"], "GET", "/panels")).toThrow(
+            `invalid permission "/panels": expected "<METHOD> <path-glob>", e.g. "GET /panels"`,
+        );
+    });
+});
+
+describe("permissionProblem", () => {
+    test.each(["GET /panels", "post /panels/*/start", "  DELETE   /approvals/*  ", "PUT /secrets/*", "GET /", "HEAD /panels/"])("%s is well formed", (entry) => {
+        expect(permissionProblem(entry)).toBe(undefined);
+    });
+
+    test.each([
+        ["/panels", `expected "<METHOD> <path-glob>", e.g. "GET /panels"`],
+        ["GET", `expected "<METHOD> <path-glob>", e.g. "GET /panels"`],
+        ["GET /panels extra", `expected "<METHOD> <path-glob>", e.g. "GET /panels"`],
+        ["FETCH /panels", `"FETCH" is not one of GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS`],
+        ["GET panels", `the path must start with "/"`],
+        ["GET /logs/file?name=x", `the path may not hold "?", "#" or "\\": routes are matched on the path alone`],
+        ["GET /panels#top", `the path may not hold "?", "#" or "\\": routes are matched on the path alone`],
+        ["GET /panels\\x", `the path may not hold "?", "#" or "\\": routes are matched on the path alone`],
+        [
+            "GET /files/**",
+            `"**" is not a segment glob: a \`*\` stands alone between slashes and matches one whole segment, so \`**\` and a \`*\` inside a segment are not supported`,
+        ],
+        [
+            "GET /files/*.json",
+            `"*.json" is not a segment glob: a \`*\` stands alone between slashes and matches one whole segment, so \`**\` and a \`*\` inside a segment are not supported`,
+        ],
+        ["GET /panels/../secrets", `".." is not a route segment: the URL resolves it away before any route sees it`],
+        ["GET /panels/%2E/x", `"%2E" is not a route segment: the URL resolves it away before any route sees it`],
+    ])("%s is refused", (entry, problem) => {
+        expect(permissionProblem(entry)).toBe(`invalid permission "${entry}": ${problem}`);
+    });
+});
+
+describe("a manifest's permissions", () => {
+    const parse = (permissions: object) =>
+        ExtensionManifestSchema.safeParse({ publisher: "acme", name: "demo", version: "1.0.0", engines: { intentic: "^1.0.0" }, permissions });
+
+    test("well-formed entries parse", () => {
+        expect(parse({ sandbox: ["GET /panels"], daemon: ["POST /panels/*/start"] }).data?.permissions).toEqual({
+            sandbox: ["GET /panels"],
+            daemon: ["POST /panels/*/start"],
+        });
+    });
+
+    test.each(["sandbox", "daemon"])("a malformed %s entry fails the parse, at the entry, with the reason", (half) => {
+        expect(parse({ [half]: ["GET /panels", "GET /files/**"] }).error?.issues).toEqual([
+            {
+                code: "custom",
+                path: ["permissions", half, 1],
+                message: `invalid permission "GET /files/**": "**" is not a segment glob: a \`*\` stands alone between slashes and matches one whole segment, so \`**\` and a \`*\` inside a segment are not supported`,
+            },
+        ]);
+    });
+});

package/src/permissions.ts

@@ -1,33 +1,92 @@
 /* The sandbox-route permission model. */
 
-const escapeRegExp = (literal: string): string => literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// An entry is "<METHOD> <path-glob>": an HTTP method, then an absolute path whose segments are each literal or a lone
+// `*`. A `*` matches exactly one segment, and never a dot segment (`.` or `..`, percent-encoded or not) or one holding a
+// backslash, since the URL layer resolves those away before any route sees them: `POST /panels/*/start` must not reach
+// `/panels/../start`, which is `/start`. A `**` or a `*` inside a segment is refused rather than read in some way its
+// author did not mean.
+
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/iu;
 
 interface CompiledRoute {
     readonly method: string;
-    readonly test: (path: string) => boolean;
+    // Each segment of the glob after its leading slash, undefined for a `*`.
+    readonly segments: readonly (string | undefined)[];
+}
+
+// Why a glob segment cannot be declared, or undefined when it can.
+const segmentProblem = (segment: string): string | undefined => {
+    if (segment.includes("*") && segment !== "*") {
+        return `"${segment}" is not a segment glob: a \`*\` stands alone between slashes and matches one whole segment, so \`**\` and a \`*\` inside a segment are not supported`;
+    }
+    if (DOT_SEGMENT.test(segment)) {
+        return `"${segment}" is not a route segment: the URL resolves it away before any route sees it`;
+    }
+    return undefined;
+};
+
+// Why the entry is malformed, or undefined when it is well formed.
+const syntaxProblem = (method: string, glob: string): string | undefined => {
+    if (glob === "") {
+        return `expected "<METHOD> <path-glob>", e.g. "GET /panels"`;
+    }
+    if (!METHODS.has(method.toUpperCase())) {
+        return `"${method}" is not one of ${[...METHODS].join(", ")}`;
+    }
+    if (!glob.startsWith("/")) {
+        return `the path must start with "/"`;
+    }
+    if (/[?#\\]/u.test(glob)) {
+        return `the path may not hold "?", "#" or "\\": routes are matched on the path alone`;
+    }
+    return glob.slice(1).split("/").map(segmentProblem).find((found) => found !== undefined);
+};
+
+interface Entry {
+    readonly method: string;
+    readonly glob: string;
 }
 
-// "<METHOD> <path-glob>" → a method + an anchored path matcher. Each `*` in the glob matches one path segment
-// ([^/]+); everything else is literal. Throws on a malformed entry so a bad manifest fails loudly at load.
+const split = (entry: string): Entry => {
+    const [, method = "", glob = ""] = /^(\S+)\s+(\S+)$/u.exec(entry.trim()) ?? [];
+    return { method, glob };
+};
+
+// Why `entry` is not a permission, as the message a manifest parse reports, or undefined when it is one.
+export const permissionProblem = (entry: string): string | undefined => {
+    const { method, glob } = split(entry);
+    const problem = syntaxProblem(method, glob);
+    return problem === undefined ? undefined : `invalid permission "${entry}": ${problem}`;
+};
+
+// The entry as a method and its glob's segments. Throws on a malformed one; the manifest parse refuses that first
+// (manifest.ts), so this only fires on a list that never went through it.
 const compile = (entry: string): CompiledRoute => {
-    const spaceIndex = entry.indexOf(" ");
-    if (spaceIndex < 0) {
-        throw new Error(`invalid sandbox permission "${entry}": expected "<METHOD> <path-glob>", e.g. "GET /panels"`);
+    const problem = permissionProblem(entry);
+    if (problem !== undefined) {
+        throw new Error(problem);
     }
-    const method = entry.slice(0, spaceIndex).trim().toUpperCase();
-    const glob = entry.slice(spaceIndex + 1).trim();
-    const source = `^${glob.split("*").map(escapeRegExp).join("[^/]+")}$`;
-    const regex = new RegExp(source);
-    return { method, test: (path) => regex.test(path) };
+    const { method, glob } = split(entry);
+    return { method: method.toUpperCase(), segments: glob.slice(1).split("/").map((segment) => (segment === "*" ? undefined : segment)) };
 };
 
+const segmentMatches = (glob: string | undefined, segment: string): boolean =>
+    glob === undefined ? segment !== "" && !segment.includes("\\") && !DOT_SEGMENT.test(segment) : glob === segment;
+
 // Whether `method path` is covered by any of the declared permissions. The query string is ignored (routes are
 // matched on path only), and the method is compared case-insensitively.
 export const sandboxRouteAllowed = (permissions: readonly string[], method: string, path: string): boolean => {
     const route = path.split("?")[0] ?? path;
     const wanted = method.toUpperCase();
+    const segments = route.startsWith("/") ? route.slice(1).split("/") : [];
     return permissions.some((entry) => {
         const compiled = compile(entry);
-        return compiled.method === wanted && compiled.test(route);
+        return (
+            compiled.method === wanted &&
+            compiled.segments.length === segments.length &&
+            compiled.segments.every((glob, index) => segmentMatches(glob, segments[index] ?? ""))
+        );
     });
 };

package/src/points/capabilities.ts

@@ -184,6 +184,13 @@ export const CapabilityContributionSchema = z
             probe: ProbeSchema.optional().describe(
                 "One authenticated request that tests this card's settings before they are saved, so a wrong token or an unreachable host is answered on the form rather than by a card that says 'not connected' afterwards.",
             ),
+            // Only narrows what the credential may do, so it carries no effect: nothing here grants the extension reach.
+            hosts: z
+                .array(z.string().min(1))
+                .optional()
+                .describe(
+                    "The hosts this card's credential is meant for, as templates over the fields like `env` (`api.github.com`, `*.githubusercontent.com`, `${url}`); a value that comes out as a URL counts as its host. The sandbox limits the credential's `{{secret:…}}` reference to them by default, so a use aimed anywhere else asks a person first. The owner can change or lift the list on the Secrets view.",
+                ),
             // The first way a card served tools, kept one release as an alias of `contributes.tools` with this card as
             // `perCard` and this value as `path` (points/tools.ts); a manifest declaring both is served by `tools`.
             mcp: z

package/src/points/index.ts

@@ -11,6 +11,7 @@ import { filesPoint } from "./files.js";
 import { listenerPoint } from "./listener.js";
 import { processesPoint } from "./processes.js";
 import { settingsPoint } from "./settings.js";
+import { sideViewsPoint } from "./side-views.js";
 import { toolsPoint } from "./tools.js";
 import { viewersPoint } from "./viewers.js";
 import { viewsPoint } from "./views.js";
@@ -26,6 +27,7 @@ export * from "./files.js";
 export * from "./listener.js";
 export * from "./processes.js";
 export * from "./settings.js";
+export * from "./side-views.js";
 export * from "./tools.js";
 export * from "./viewers.js";
 export * from "./views.js";
@@ -38,6 +40,7 @@ export const CONTRIBUTION_POINTS = [
     filesPoint,
     viewersPoint,
     documentsPoint,
+    sideViewsPoint,
     commandsPoint,
     settingsPoint,
     processesPoint,

package/src/points/side-views.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// A side view the extension may register at runtime (api.sideViews.register): something it can show in the editor's side
+// panel for one input (a CI run, a workflow run), beside whichever section the reader is in, and move into its own view
+// on request. The host owns the panel and the tab; the extension answers what the tab says and draws its body.
+export const SideViewContributionSchema = z.object({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    label: z
+        .string()
+        .min(1)
+        .describe(
+            "What one of these is called (\"CI run\"), shown in the install dialog and on a tab whose own title could not be read. Each tab's title is the extension's to say for the thing it shows.",
+        ),
+    // Whether this side view may take links the chat renders (SideViewRegistration.claim): a link it recognises opens
+    // beside the chat instead of in a new browser tab. Declared, like a badge, because it changes what the reader's
+    // click does; absent, the host never asks it.
+    links: z
+        .boolean()
+        .optional()
+        .describe(
+            "Allow this side view to take links the chat renders: a link it recognises (its registration's `claim`) opens beside the chat instead of in a new browser tab. Declared because it changes what the reader's click does; leave it out and the host never asks.",
+        )
+        .meta({ power: { key: "side-view-links:${id}", sentence: 'opens links it recognises as "${label}" beside the chat' } }),
+})
+    .meta({ power: { key: "side-view:${id}", sentence: 'shows "${label}" in the side panel' } });
+export type SideViewContribution = z.infer<typeof SideViewContributionSchema>;
+
+export const sideViewsPoint = {
+    name: "sideViews",
+    description:
+        "Things this extension can show in the editor's side panel, one input at a time, beside whatever the reader is doing. Each entry reserves an id; the extension supplies the component with api.sideViews.register and opens one with api.sideViews.open, and the host refuses any id this list does not cover.",
+    schema: z.array(SideViewContributionSchema),
+} as const satisfies ContributionPoint;

package/src/points/viewers.ts

@@ -21,7 +21,7 @@ export const ViewerContributionSchema = z.object({
     fetch: z
         .enum(["text", "blob", "url", "path"])
         .describe(
-            "How much of the file the host hands you. `text` for a format that is text (svg, a subtitle track). `blob` for one that must be parsed end to end before any of it shows (a .docx, a spreadsheet), bounded by the daemon's raw-read cap. `url` for anything range-read rather than parsed (audio, video): your component gets a streaming URL to point an element at, never the bytes. `path` for a viewer whose own backend reads and writes the file: you get the workspace path and the scope it is viewed in, nothing else.",
+            "How much of the file the host hands you. `text` for a format that is text (svg, a subtitle track). `blob` for one that must be parsed end to end before any of it shows (a .docx, a spreadsheet), bounded by the daemon's raw-read cap. `url` for anything range-read rather than parsed (audio, video): your component gets a streaming URL to point an element at, never the bytes. `path` for a viewer whose own backend reads and writes the file: you get the workspace path and the scope it is viewed in, plus `readOnly` where the window may not write the file and, in a desktop app's local window, a `text` slot holding the document's text for while your own view can't show it. Emit `dirty` (a boolean) whenever you start or stop holding edits the file doesn't have, so a window closing over them can ask first.",
         ),
     // An editing viewer outranks a render-only one claiming the same extension; among equals the later registration
     // wins. Declared, not timed: activation order is not stable across extensions.

package/src/powers.test.ts

@@ -0,0 +1,212 @@
+import { z } from "zod";
+import { manifestJsonSchema } from "./json-schema.js";
+import { ExtensionManifestSchema } from "./manifest.js";
+import { powersOf } from "./powers-diff.js";
+
+// Every power the schema declares must COUNT: a manifest that sets the field folds to exactly one more power than the
+// same manifest without it, under the key and sentence below. The powers are the owner's approval (a workspace
+// extension's digest is taken over their keys), so one the fold silently drops is a power granted without being asked
+// for. The list of declared powers is read off the published authoring schema, where each field's `.meta({ power })`
+// lands, rather than off the walker under test: a new power with no row here fails, and so does a zod change that
+// hides a field from the walker (a union's internals, a wrapper it does not see through).
+
+// What a row sets beyond the identity every manifest carries.
+type Fields = Omit<z.input<typeof ExtensionManifestSchema>, "publisher" | "name" | "version" | "engines">;
+type Contributes = NonNullable<Fields["contributes"]>;
+type Card = NonNullable<Contributes["capabilities"]>[number];
+
+const manifest = (fields: Fields): ReturnType<typeof ExtensionManifestSchema.parse> =>
+    ExtensionManifestSchema.parse({ publisher: "acme", name: "demo", version: "1.0.0", engines: { intentic: "^1.0.0" }, ...fields });
+
+const contributes = (points: Contributes, fields: Fields = {}): Fields => ({ ...fields, contributes: points });
+
+const CATALOG = { name: "Acme", description: "One line.", category: "code" };
+const CLI_CARD = {
+    id: "acme-cli",
+    kind: "cli",
+    catalog: CATALOG,
+    fields: [{ key: "token", label: "Token", secret: true }],
+    env: { ACME_TOKEN: "${token}" },
+    skill: "skills/acme/SKILL.md",
+} satisfies Card;
+const VIEW = { id: "board", label: "Board", surface: "rail" } as const;
+const COMMAND = { command: "acme.run", title: "Run" };
+const SETTING = { key: "token", type: "string", title: "Token" } as const;
+const SERVER = { server: "dist/server.js" };
+// One card of each kind, so every arm of the capability union is reached through it.
+const CARDS: readonly Card[] = [
+    CLI_CARD,
+    { id: "acme-web", kind: "browser", catalog: CATALOG, fields: [], loginUrl: "https://acme.test/login", skill: "skills/web.md" },
+    { id: "acme-os", kind: "device", catalog: CATALOG, fields: [], skill: "skills/os.md" },
+    { id: "acme-ext", kind: "webext", catalog: CATALOG, fields: [], skill: "skills/ext.md" },
+    { id: "acme-agent", kind: "agent", catalog: CATALOG, fields: [] },
+];
+
+interface Row {
+    // The power's key template, as the schema declares it.
+    readonly power: string;
+    readonly without: Fields;
+    readonly with: Fields;
+    // The one power `with` adds: its filled key and sentence.
+    readonly adds: readonly [string, string];
+}
+
+const ROWS: readonly Row[] = [
+    { power: "entry", without: {}, with: { entry: "dist/extension.js" }, adds: ["entry", "runs a UI bundle in your browser"] },
+    { power: "server", without: {}, with: SERVER, adds: ["server", "runs a backend bundle inside the daemon's extension host"] },
+    {
+        power: "sandbox:${value}",
+        without: { permissions: {} },
+        with: { permissions: { sandbox: ["POST /panels/*/start"] } },
+        adds: ["sandbox:POST /panels/*/start", "its UI calls the sandbox route POST /panels/*/start"],
+    },
+    {
+        power: "daemon:${value}",
+        without: { permissions: {} },
+        with: { permissions: { daemon: ["GET /workspace/tree"] } },
+        adds: ["daemon:GET /workspace/tree", "its backend calls the daemon route GET /workspace/tree"],
+    },
+    { power: "view:${id}", without: contributes({ views: [] }), with: contributes({ views: [VIEW] }), adds: ["view:board", 'a rail view "Board"'] },
+    {
+        power: "view-badge:${id}",
+        without: contributes({ views: [{ ...VIEW, badge: false }] }),
+        with: contributes({ views: [{ ...VIEW, badge: true }] }),
+        adds: ["view-badge:board", 'may badge the "Board" tile from any screen'],
+    },
+    {
+        power: "files:${path}",
+        without: contributes({ files: [] }),
+        with: contributes({ files: [{ path: ".intentic/config/acme.json", invalidates: ["acme"] }] }),
+        adds: ["files:.intentic/config/acme.json", "is told when .intentic/config/acme.json changes"],
+    },
+    {
+        power: "viewer:${id}",
+        without: contributes({ viewers: [] }),
+        with: contributes({ viewers: [{ id: "office", extensions: ["docx", "xlsx"], fetch: "blob", edit: true, compare: true }] }),
+        adds: ["viewer:office", "opens and edits and compares .docx, .xlsx files (blob)"],
+    },
+    {
+        power: "document:${id}",
+        without: contributes({ documents: [] }),
+        with: contributes({ documents: [{ id: "readmes", label: "Readmes" }] }),
+        adds: ["document:readmes", 'marks workspace directories ("Readmes")'],
+    },
+    {
+        power: "side-view:${id}",
+        without: contributes({ sideViews: [] }),
+        with: contributes({ sideViews: [{ id: "run", label: "CI run" }] }),
+        adds: ["side-view:run", 'shows "CI run" in the side panel'],
+    },
+    {
+        power: "side-view-links:${id}",
+        without: contributes({ sideViews: [{ id: "run", label: "CI run", links: false }] }),
+        with: contributes({ sideViews: [{ id: "run", label: "CI run", links: true }] }),
+        adds: ["side-view-links:run", 'opens links it recognises as "CI run" beside the chat'],
+    },
+    {
+        power: "command:${command}",
+        without: contributes({ commands: [] }),
+        with: contributes({ commands: [COMMAND] }),
+        adds: ["command:acme.run", 'a palette command "Run"'],
+    },
+    {
+        power: "keybinding:${command}",
+        without: contributes({ commands: [COMMAND] }),
+        with: contributes({ commands: [{ ...COMMAND, keybinding: "Mod+Shift+K" }] }),
+        adds: ["keybinding:acme.run", 'the global shortcut Mod+Shift+K ("Run")'],
+    },
+    {
+        power: "setting-env:${key}",
+        without: contributes({ settings: [SETTING] }),
+        with: contributes({ settings: [{ ...SETTING, env: "ACME_TOKEN" }] }),
+        adds: ["setting-env:token", `puts the "token" setting into the agent's environment as ACME_TOKEN`],
+    },
+    {
+        power: "process:${name}",
+        without: contributes({ processes: [] }),
+        with: contributes({ processes: [{ name: "worker", command: "node worker.js", autoStart: true }] }),
+        adds: ["process:worker", 'a background process "worker" (starts on boot)'],
+    },
+    {
+        power: "agent",
+        without: contributes({}),
+        with: contributes({ agent: {} }),
+        adds: ["agent", "contributes skills, agents and hooks to the agent's turns"],
+    },
+    {
+        power: "environment",
+        without: contributes({}),
+        with: contributes({ environment: { fragment: "environment/Dockerfile" } }),
+        adds: ["environment", "bakes an environment fragment into the sandbox image"],
+    },
+    ...CARDS.map(
+        (card): Row => ({
+            power: "capability:${id}",
+            without: contributes({ capabilities: [] }),
+            with: contributes({ capabilities: [card] }),
+            adds: [`capability:${card.id}`, `a ${card.kind} capability card "Acme"`],
+        }),
+    ),
+    {
+        power: "capability-tools:${id}",
+        without: contributes({ capabilities: [CLI_CARD] }, SERVER),
+        with: contributes({ capabilities: [{ ...CLI_CARD, mcp: "mcp" }] }, SERVER),
+        adds: ["capability-tools:acme-cli", 'serves MCP tools to the agent for each "Acme" card'],
+    },
+    {
+        power: "listener:${provider}",
+        without: contributes({}),
+        with: contributes({
+            listener: {
+                provider: "acme",
+                events: [{ type: "message", label: "A message" }],
+                automation: { label: "Acme", channel: { label: "Channel", placeholder: "#general" }, starterPrompt: "Answer it." },
+            },
+        }),
+        adds: ["listener:acme", 'a realtime listener provider "acme"'],
+    },
+    { power: "bin", without: contributes({}), with: contributes({ bin: "bin" }), adds: ["bin", "puts its shipped tools on the agent's PATH"] },
+    {
+        power: "tools${perCard?-${perCard}:}",
+        without: contributes({}, SERVER),
+        with: contributes({ tools: {} }, SERVER),
+        adds: ["tools", "gives the agent MCP tools"],
+    },
+    {
+        power: "tools${perCard?-${perCard}:}",
+        without: contributes({ capabilities: [CLI_CARD] }, SERVER),
+        with: contributes({ capabilities: [CLI_CARD], tools: { perCard: "acme-cli" } }, SERVER),
+        adds: ["tools-acme-cli", 'gives the agent MCP tools, one server for each "acme-cli" card'],
+    },
+];
+
+// Every power key template the authoring schema carries, wherever it sits: the serializer visits every node.
+const PowerNode = z.object({ power: z.object({ key: z.string() }) });
+const declaredPowers = (): Set<string> => {
+    const keys = new Set<string>();
+    JSON.stringify(manifestJsonSchema(), (_key, node) => {
+        const declared = PowerNode.safeParse(node);
+        if (declared.success) {
+            keys.add(declared.data.power.key);
+        }
+        return node;
+    });
+    return keys;
+};
+
+describe("powersOf", () => {
+    test("a manifest declaring nothing consequential folds to no powers", () => {
+        expect([...powersOf(manifest({}))]).toEqual([]);
+    });
+
+    test("every power the schema declares has a row below, and every row names a declared power", () => {
+        expect([...declaredPowers()].toSorted()).toEqual([...new Set(ROWS.map((row) => row.power))].toSorted());
+    });
+
+    test.each(ROWS.map((row) => [row.adds[0], row] as const))("%s counts", (_key, row) => {
+        const before = powersOf(manifest(row.without));
+        const after = powersOf(manifest(row.with));
+        expect([...after].filter(([key]) => !before.has(key))).toEqual([[...row.adds]]);
+        expect([...before].filter(([key]) => !after.has(key))).toEqual([]);
+    });
+});