@intentic/extension-manifest 1.312.0 → 1.314.0

package/src/points/capabilities.ts

@@ -1,7 +1,9 @@
 import { evaluateWhen, isWhenExpression, parseWhen } from "@intentic/base/when";
 import { z } from "zod";
 import type { ContributionPoint } from "../contribution-point.js";
+import { TOOL_PATH } from "./tools.js";
 import { MARK_FIELDS } from "../mark.js";
+import { type EffectMeaning, fieldMeanings, unwrapMeaning } from "../meaning.js";
 
 // A field the install dialog's config form renders (key, label, secret/optional flags, a select, a `when` gate);
 // mirrors the platform catalog's own field shape.
@@ -167,7 +169,8 @@ export const CapabilityContributionSchema = z
                 .string()
                 .min(1)
                 .optional()
-                .describe("A Dockerfile fragment holding the client binary this tool needs (psql, mysql, whisper)."),
+                .describe("A Dockerfile fragment holding the client binary this tool needs (psql, mysql, whisper).")
+                .meta({ effect: "image" }),
             // Prefer over `fragment` whenever the sandbox already ships a pack for the tool: an image that bakes the
             // pack needs no rebuild, and the overlay can't drift from it.
             pack: z
@@ -176,20 +179,25 @@ export const CapabilityContributionSchema = z
                 .optional()
                 .describe(
                     "A sandbox feature pack name (whisper, llamacpp, browser, …) supplying this tool. Preferred over `fragment`: an image that already bakes the pack needs no rebuild, and there is no copy to drift.",
-                ),
+                )
+                .meta({ effect: "image" }),
             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.",
             ),
-            // A stdio server in the extension's agent plugin is spawned once per session; this is served by the one
-            // backend host the sandbox already runs, so N sessions cost N requests rather than N processes.
+            // 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
                 .string()
-                .regex(/^[a-z0-9][a-z0-9/-]*$/)
-                .refine((value) => !value.endsWith("/"), { message: "mcp must not end in a slash" })
+                .regex(TOOL_PATH)
                 .optional()
                 .describe(
-                    "A path in this extension's backend (`server`) answering MCP over Streamable HTTP. Every turn granted a card of this kind gets it as a server named by the card's id; each request arrives at `<path>/<card id>`, so the backend reads that card's config through the daemon rather than the turn's environment.",
-                ),
+                    "Deprecated: declare `contributes.tools` with `perCard` naming this card instead, and serve the tools with `api.tools.serve`. A path in this extension's backend (`server`) answering MCP over Streamable HTTP; every turn granted a card of this kind gets it as a server named by the card's id, each request arriving at `<path>/<card id>`.",
+                )
+                .meta({
+                    effect: "mcp",
+                    mintsServer: true,
+                    power: { key: "capability-tools:${id}", sentence: 'serves MCP tools to the agent for each "${catalog.name}" card' },
+                }),
         }),
         // A site the agent acts on as the owner through the shared browser; `loginUrl`/`homeUrl` are both optional so a
         // card can be the generic one that asks for them on its form instead.
@@ -217,20 +225,24 @@ export const CapabilityContributionSchema = z
         }),
         // An operating system a connected computer can run; enrollment, socket and scope enforcement are core, only the
         // skill pack varies.
-        z.object({
-            ...contributionBase,
-            kind: z.literal("device"),
-            skill: z.string().min(1).describe("Checkout-relative SKILL.md teaching the agent that machine's shell."),
-        }),
+        z
+            .object({
+                ...contributionBase,
+                kind: z.literal("device"),
+                skill: z.string().min(1).describe("Checkout-relative SKILL.md teaching the agent that machine's shell."),
+            })
+            .meta({ mintsServer: true }),
         // A browser family the user connects their own copy of; `install` is a URL since each family has its own store
         // or none at all. Omitted until that family's listing exists: the connect dialog then shows no link, which is
         // better than a store URL that quietly lands on the store's front page.
-        z.object({
-            ...contributionBase,
-            kind: z.literal("webext"),
-            install: z.url().optional().describe("Where this browser's extension is installed from: its store listing, or a page offering the build."),
-            skill: z.string().min(1).describe("Checkout-relative SKILL.md teaching the agent to drive this browser."),
-        }),
+        z
+            .object({
+                ...contributionBase,
+                kind: z.literal("webext"),
+                install: z.url().optional().describe("Where this browser's extension is installed from: its store listing, or a page offering the build."),
+                skill: z.string().min(1).describe("Checkout-relative SKILL.md teaching the agent to drive this browser."),
+            })
+            .meta({ mintsServer: true }),
         // A preset over a core kind: no payload, just a name, a logo and a filled-in form.
         z.object({ ...contributionBase, kind: z.literal("agent") }),
     ])
@@ -248,7 +260,8 @@ export const CapabilityContributionSchema = z
                 });
             }
         }
-    });
+    })
+    .meta({ power: { key: "capability:${id}", sentence: 'a ${kind} capability card "${catalog.name}"' } });
 export type CapabilityContribution = z.infer<typeof CapabilityContributionSchema>;
 // Arms carrying a per-instance SKILL.md, templated and installed identically by the daemon.
 export type SkillContribution = Extract<CapabilityContribution, { skill: string }>;
@@ -281,3 +294,38 @@ export const capabilitiesPoint = {
         'Capability cards this pack adds to the "+" grid: a connected CLI tool, a site the agent acts on as the owner through the shared browser, an operating system pack, a browser family the owner connects their own copy of, or a preset over a core kind. The card and its form are data here; the machinery that acts on them is core, which is why a card may only name one of these five kinds.',
     schema: z.array(CapabilityContributionSchema),
 } as const satisfies ContributionPoint;
+
+// Every contributable kind a card of which registers an `mcp__<card id>__` server: the arm itself says so (a device, a
+// connected browser), or one of its fields may (a cli card's `mcp`; `contributes.tools` can name only a cli card as
+// `perCard`). Read off the schema's meanings, so a kind that starts minting names itself here.
+export const contributedServerMintingKinds = (): ReadonlySet<CapabilityContribution["kind"]> => {
+    const kinds = new Set<CapabilityContribution["kind"]>();
+    for (const option of CapabilityContributionSchema.options) {
+        const shape = option.shape as Record<string, z.ZodType>;
+        const kind = (shape["kind"]?._zod.def as { values?: readonly string[] } | undefined)?.values?.[0] as CapabilityContribution["kind"] | undefined;
+        if (kind === undefined) {
+            continue;
+        }
+        if (unwrapMeaning(option).meaning.mintsServer === true || [...fieldMeanings(option).values()].some((meaning) => meaning.mintsServer === true)) {
+            kinds.add(kind);
+        }
+    }
+    return kinds;
+};
+
+// What the fields a card sets add to the sandbox, as effect kinds: an image rebuild for a fragment or a pack, an MCP
+// server for a card that serves tools.
+export const contributionEffectsOf = (contribution: CapabilityContribution): ReadonlySet<EffectMeaning> => {
+    const effects = new Set<EffectMeaning>();
+    const option = CapabilityContributionSchema.options.find((candidate) => candidate.shape.kind.value === contribution.kind);
+    if (option === undefined) {
+        return effects;
+    }
+    for (const [key, meaning] of fieldMeanings(option)) {
+        const value = (contribution as Record<string, unknown>)[key];
+        if (meaning.effect !== undefined && value !== undefined && value !== false) {
+            effects.add(meaning.effect);
+        }
+    }
+    return effects;
+};

package/src/points/commands.ts

@@ -22,7 +22,8 @@ export const CommandContributionSchema = z.object({
         .optional()
         .describe(
             'A global keyboard shortcut, e.g. "Mod+Shift+K" — `Mod` is ⌘ on Apple and Ctrl elsewhere. Declared here because a global shortcut is consequential: the owner approves it at install, and the host binds only what was approved.',
-        ),
+        )
+        .meta({ power: { key: "keybinding:${command}", sentence: 'the global shortcut ${keybinding} ("${title}")' } }),
     // When the keybinding applies, as a condition over the shell's context keys; the palette ignores it since a command
     // is always runnable by name. Without one the chord is claimed everywhere, including inside a terminal.
     when: z
@@ -32,7 +33,8 @@ export const CommandContributionSchema = z.object({
         .describe(
             "When the shortcut applies, as a condition over the shell's context keys, `tabSurface == 'chat'`, `!editableTarget`. Without one the chord is claimed everywhere, including inside a terminal where a bare key belongs to the program running in it. The command palette ignores this: a command is always runnable by name.",
         ),
-});
+})
+    .meta({ power: { key: "command:${command}", sentence: 'a palette command "${title}"' } });
 export type CommandContribution = z.infer<typeof CommandContributionSchema>;
 
 export const commandsPoint = {

package/src/points/documents.ts

@@ -13,7 +13,8 @@ export const DocumentContributionSchema = z.object({
         .describe(
             "The family's name, shown in the install dialog beside your other contributions. Per-row wording stays with the provider, which is the only thing that knows what it found.",
         ),
-});
+})
+    .meta({ power: { key: "document:${id}", sentence: 'marks workspace directories ("${label}")' } });
 export type DocumentContribution = z.infer<typeof DocumentContributionSchema>;
 
 export const documentsPoint = {

package/src/points/environment.ts

@@ -14,7 +14,8 @@ export const EnvironmentContributionSchema = z.object({
         .describe(
             "Checkout-relative path to a file holding ONLY RUN and ENV instructions. FROM and privileged directives are rejected: those stay daemon-owned.",
         ),
-});
+})
+    .meta({ effect: "image", power: { key: "environment", sentence: "bakes an environment fragment into the sandbox image" } });
 export type EnvironmentContribution = z.infer<typeof EnvironmentContributionSchema>;
 
 export const environmentPoint = {

package/src/points/files.ts

@@ -24,7 +24,8 @@ export const FileContributionSchema = z.object({
         .describe(
             "The query keys this path makes stale, the first element of your own api.sandbox.key(...) keys. Keep both this and the path as narrow as the view actually needs: a broad prefix costs every connected browser a refetch on every matching write.",
         ),
-});
+})
+    .meta({ power: { key: "files:${path}", sentence: 'is told when ${path} changes' } });
 export type FileContribution = z.infer<typeof FileContributionSchema>;
 
 export const filesPoint = {

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 { toolsPoint } from "./tools.js";
 import { viewersPoint } from "./viewers.js";
 import { viewsPoint } from "./views.js";
 
@@ -25,6 +26,7 @@ export * from "./files.js";
 export * from "./listener.js";
 export * from "./processes.js";
 export * from "./settings.js";
+export * from "./tools.js";
 export * from "./viewers.js";
 export * from "./views.js";
 
@@ -45,6 +47,7 @@ export const CONTRIBUTION_POINTS = [
     listenerPoint,
     automationTemplatesPoint,
     binPoint,
+    toolsPoint,
 ] as const satisfies readonly ContributionPoint[];
 
 // The `contributes` shape those points assemble to. A mapped type rather than a widened record, so

package/src/points/listener.ts

@@ -66,7 +66,8 @@ export const ListenerContributionSchema = z.object({
                 ),
         })
         .describe("How the generic automation editor presents this source: its name, its filters, and the prompt it starts people on."),
-});
+})
+    .meta({ power: { key: "listener:${provider}", sentence: 'a realtime listener provider "${provider}"' } });
 export type ListenerContribution = z.infer<typeof ListenerContributionSchema>;
 
 export const listenerPoint = {

package/src/points/processes.ts

@@ -9,7 +9,8 @@ export const ProcessContributionSchema = z.object({
     port: z.literal("auto").optional().describe("Assign a free port and inject it as PORT."),
     preview: z.boolean().optional().describe("Expose the port on a tunnelled preview hostname."),
     autoStart: z.boolean().optional().describe("Launch it on install and on daemon boot, rather than waiting to be started."),
-});
+})
+    .meta({ effect: "process", power: { key: "process:${name}", sentence: 'a background process "${name}"${autoStart? (starts on boot):}' } });
 export type ProcessContribution = z.infer<typeof ProcessContributionSchema>;
 
 export const processesPoint = {

package/src/points/settings.ts

@@ -19,7 +19,8 @@ export const SettingContributionSchema = z.object({
         .optional()
         .describe(
             "Inject the stored value into the agent's shell environment under this name, every turn. How a credential you hold reaches the agent's command-line tools.",
-        ),
+        )
+        .meta({ power: { key: "setting-env:${key}", sentence: 'puts the "${key}" setting into the agent\'s environment as ${env}' } }),
 });
 export type SettingContribution = z.infer<typeof SettingContributionSchema>;
 

package/src/points/tools.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// The one way an extension gives the agent tools: an MCP server the daemon mounts into every turn at its own door
+// (`/mcp/<name>`), whichever runtime serves the turn. A plugin's `.mcp.json` reached only Claude Code and spawned a
+// process per session; this is served once, for every session.
+
+// A path inside the extension's namespace or on a process's port: segments of [a-z0-9-], each starting alphanumeric,
+// joined by single slashes, with none leading or trailing. The regex says all of it, so the authoring schema does too.
+export const TOOL_PATH = /^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)*$/;
+
+export const ToolsContributionSchema = z
+    .object({
+        perCard: z
+            .string()
+            .regex(/^[a-z0-9][a-z0-9-]*$/)
+            .optional()
+            .describe(
+                "The id of one of this extension's `cli` capability cards. Every turn granted a card of that kind gets one server named by the card's id, handed that card's settings (secrets included) with each call. Absent ⇒ one server for the extension, named by its `name`, in every turn while the extension is enabled.",
+            ),
+        process: z
+            .string()
+            .regex(/^[a-z0-9][a-z0-9-]*$/)
+            .optional()
+            .describe(
+                'A process from `contributes.processes`, declared with `port: "auto"`, that answers MCP over Streamable HTTP at `path` on its port. Absent ⇒ your `server` bundle serves the tools.',
+            ),
+        path: z
+            .string()
+            .regex(TOOL_PATH)
+            .optional()
+            .describe(
+                "Where the MCP endpoint answers, without a leading or trailing slash: on the process's port, or in your backend's own namespace when your `server` bundle speaks MCP itself. Absent with no `process` ⇒ the host serves what `api.tools.serve` returns, which is what you want: the host owns the transport, the deadlines and the card lookup. With `perCard`, a request arrives at `<path>/<card id>`.",
+            ),
+    })
+    .meta({
+        effect: "mcp",
+        mintsServer: true,
+        power: { key: "tools${perCard?-${perCard}:}", sentence: 'gives the agent MCP tools${perCard?, one server for each "${perCard}" card:}' },
+    });
+export type ToolsContribution = z.infer<typeof ToolsContributionSchema>;
+
+export const toolsPoint = {
+    name: "tools",
+    description:
+        "Tools for the agent, as an MCP server the daemon mounts into every turn and every runtime (Claude Code, Codex, Cursor, ACP agents). Serve them from your `server` bundle with `api.tools.serve((card) => [...])`, or from a declared process's port. Replaces an agent plugin's `.mcp.json`, which only Claude Code read.",
+    schema: ToolsContributionSchema,
+} as const satisfies ContributionPoint;

package/src/points/viewers.ts

@@ -39,7 +39,8 @@ export const ViewerContributionSchema = z.object({
         .describe(
             "Whether this viewer also draws two versions of a file as one, with what changed marked in place: its registration then carries a `compare` component the host renders with `before` and `after` blobs. Only for `fetch: \"blob\"`.",
         ),
-});
+})
+    .meta({ power: { key: "viewer:${id}", sentence: '${edit?opens and edits:opens}${compare? and compares:} .${extensions|, .} files (${fetch})' } });
 export type ViewerContribution = z.infer<typeof ViewerContributionSchema>;
 
 export const viewersPoint = {

package/src/points/views.ts

@@ -22,8 +22,10 @@ export const ViewContributionSchema = z.object({
         .optional()
         .describe(
             "Allow this view to say something on its tile: a count, a glyph, or that work is running there. Declared because a badge interrupts from every other screen in the app; leave it out and any badge the extension registers is dropped.",
-        ),
-});
+        )
+        .meta({ power: { key: "view-badge:${id}", sentence: 'may badge the "${label}" tile from any screen' } }),
+})
+    .meta({ power: { key: "view:${id}", sentence: 'a ${surface} view "${label}"' } });
 export type ViewContribution = z.infer<typeof ViewContributionSchema>;
 
 export const viewsPoint = {

package/src/powers-diff.ts

@@ -1,4 +1,5 @@
-import type { ExtensionManifest } from "./manifest.js";
+import { type ExtensionManifest, ExtensionManifestSchema } from "./manifest.js";
+import { fillTemplate, walkMeaning } from "./meaning.js";
 
 // What an update asks for, mechanically. Each manifest folds to a set of POWERS, the consequential facts an owner
 // approved, under a stable key (compared) with a plain sentence (shown). The diff is set arithmetic over the keys.
@@ -12,68 +13,16 @@ export interface PowersDiff {
     readonly unchanged: string[];
 }
 
-const viewerPower = (viewer: { edit?: boolean | undefined; compare?: boolean | undefined; extensions: readonly string[]; fetch: string }): string =>
-    `${viewer.edit === true ? "opens and edits" : "opens"}${viewer.compare === true ? " and compares" : ""} .${viewer.extensions.join(", .")} files (${viewer.fetch})`;
-
-// The fold itself: every power a manifest declares, its stable key to the sentence shown for it.
+// The fold itself: every power a manifest declares, its stable key to the sentence shown for it. Read off the schema:
+// each field that grants a power says so in its `.meta({ power })` (meaning.ts), so a field added to the manifest is
+// either declared a power where it is defined or is not one.
 export const powersOf = (manifest: ExtensionManifest): Map<string, string> => {
     const powers = new Map<string, string>();
-    if (manifest.entry !== undefined) {
-        powers.set("entry", "runs a UI bundle in your browser");
-    }
-    if (manifest.server !== undefined) {
-        powers.set("server", "runs a backend bundle inside the daemon's extension host");
-    }
-    for (const route of manifest.permissions?.sandbox ?? []) {
-        powers.set(`sandbox:${route}`, `its UI calls the sandbox route ${route}`);
-    }
-    for (const route of manifest.permissions?.daemon ?? []) {
-        powers.set(`daemon:${route}`, `its backend calls the daemon route ${route}`);
-    }
-    for (const view of manifest.contributes?.views ?? []) {
-        powers.set(`view:${view.id}`, `a ${view.surface} view "${view.label}"`);
-        if (view.badge === true) {
-            powers.set(`view-badge:${view.id}`, `may badge the "${view.label}" tile from any screen`);
+    walkMeaning(ExtensionManifestSchema, manifest, (meaning, context) => {
+        if (meaning.power !== undefined) {
+            powers.set(fillTemplate(meaning.power.key, context), fillTemplate(meaning.power.sentence, context));
         }
-    }
-    for (const viewer of manifest.contributes?.viewers ?? []) {
-        powers.set(`viewer:${viewer.id}`, viewerPower(viewer));
-    }
-    for (const document of manifest.contributes?.documents ?? []) {
-        powers.set(`document:${document.id}`, `marks workspace directories ("${document.label}")`);
-    }
-    for (const command of manifest.contributes?.commands ?? []) {
-        powers.set(`command:${command.command}`, `a palette command "${command.title}"`);
-        if (command.keybinding !== undefined) {
-            powers.set(`keybinding:${command.command}`, `the global shortcut ${command.keybinding} ("${command.title}")`);
-        }
-    }
-    for (const setting of manifest.contributes?.settings ?? []) {
-        if (setting.env !== undefined) {
-            powers.set(`setting-env:${setting.key}`, `puts the "${setting.key}" setting into the agent's environment as ${setting.env}`);
-        }
-    }
-    for (const process of manifest.contributes?.processes ?? []) {
-        powers.set(`process:${process.name}`, `a background process "${process.name}"${process.autoStart === true ? " (starts on boot)" : ""}`);
-    }
-    for (const file of manifest.contributes?.files ?? []) {
-        powers.set(`files:${file.path}`, `is told when ${file.path} changes`);
-    }
-    if (manifest.contributes?.agent !== undefined) {
-        powers.set("agent", "contributes skills, agents and hooks to the agent's turns");
-    }
-    if (manifest.contributes?.environment !== undefined) {
-        powers.set("environment", "bakes an environment fragment into the sandbox image");
-    }
-    for (const capability of manifest.contributes?.capabilities ?? []) {
-        powers.set(`capability:${capability.id}`, `a ${capability.kind} capability card "${capability.catalog.name}"`);
-    }
-    if (manifest.contributes?.listener !== undefined) {
-        powers.set(`listener:${manifest.contributes.listener.provider}`, `a realtime listener provider "${manifest.contributes.listener.provider}"`);
-    }
-    if (manifest.contributes?.bin !== undefined) {
-        powers.set("bin", "puts its shipped tools on the agent's PATH");
-    }
+    });
     return powers;
 };
 

package/src/tool-servers.ts

@@ -0,0 +1,50 @@
+import type { ExtensionManifest } from "./manifest.js";
+
+// Every MCP server one manifest serves the agent, whichever way it declares it: `contributes.tools`, or a cli card's
+// `mcp` (the alias kept one release, points/capabilities.ts). One reading, so the daemon's mounts, the /x refusal and
+// the effects a card discloses cannot disagree about what a manifest serves.
+
+export type ToolServe =
+    // The host serves what the backend's `api.tools.serve` returns; nothing in the namespace answers MCP itself.
+    | { readonly by: "host" }
+    // The backend answers Streamable HTTP itself, at this path in its /x namespace.
+    | { readonly by: "backend"; readonly path: string }
+    // A declared process answers it on its port, at this path.
+    | { readonly by: "process"; readonly process: string; readonly path: string };
+
+export interface ToolServer {
+    // The cli card kind whose every granted card gets a server named by the card's id; absent, one server for the
+    // extension named by its `name`.
+    readonly perCard?: string;
+    readonly serve: ToolServe;
+}
+
+export const toolServersOf = (manifest: ExtensionManifest): ToolServer[] => {
+    const servers: ToolServer[] = [];
+    const tools = manifest.contributes?.tools;
+    if (tools !== undefined) {
+        const serve: ToolServe =
+            tools.process !== undefined
+                ? { by: "process", process: tools.process, path: tools.path ?? "" }
+                : tools.path !== undefined
+                  ? { by: "backend", path: tools.path }
+                  : { by: "host" };
+        servers.push({ ...(tools.perCard === undefined ? {} : { perCard: tools.perCard }), serve });
+    }
+    for (const card of manifest.contributes?.capabilities ?? []) {
+        // `tools` naming the same card wins: a manifest may keep `mcp` for a host older than `tools`.
+        if (card.kind === "cli" && card.mcp !== undefined && tools?.perCard !== card.id) {
+            servers.push({ perCard: card.id, serve: { by: "backend", path: card.mcp } });
+        }
+    }
+    return servers;
+};
+
+// The server a card of this cli kind gets, if the manifest serves one per card of it.
+export const toolServerForCard = (manifest: ExtensionManifest, cardKind: string): ToolServer | undefined =>
+    toolServersOf(manifest).find((server) => server.perCard === cardKind);
+
+// The /x paths (relative to the namespace) the backend answers MCP at itself: what /x/* refuses, since only the door
+// checks the calling turn's lease.
+export const backendToolPathsOf = (manifest: ExtensionManifest): string[] =>
+    toolServersOf(manifest).flatMap((server) => (server.serve.by === "backend" ? [server.serve.path] : []));