@intentic/extension-manifest 1.176.3

package/src/points/capabilities.ts

@@ -0,0 +1,271 @@
+import { evaluateWhen, isWhenExpression, parseWhen } from "@intentic/base/when";
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+import { MARK_FIELDS } from "../mark.js";
+
+// A field the "+" install dialog renders for a capability's config form (a slug key, a label, secret/optional
+// flags, an optional select, a `when` gate). Mirrors the platform catalog's field shape so the web can render
+// contributed cards from installed extensions exactly like core capability cards.
+export const CapabilityFieldSchema = z.object({
+    key: z.string().regex(/^[a-zA-Z][a-zA-Z0-9]*$/),
+    label: z.string().min(1),
+    placeholder: z.string().optional(),
+    secret: z.boolean().optional().describe("Mask it, and never echo it back."),
+    optional: z.boolean().optional(),
+    multiline: z.boolean().optional(),
+    // An OPT-IN EXTRA rather than a decision — rendered as a switch, carried as the "on"/"off" the config
+    // schemas already speak (the vpn's pfs/aggressive precedent). A two-option Segmented can express the same
+    // value, and reads wrong for this: it presents a choice the user must make to proceed, sized like the
+    // required fields around it. Something the capability works fine without wants the control that is quiet
+    // when it is off. A switch always holds one of its two values, so such a field never blocks a submit
+    // whatever `optional` says.
+    boolean: z
+        .boolean()
+        .optional()
+        .describe(
+            'Render it as a switch, carrying "on"/"off". For an opt-in EXTRA rather than a decision: a two-option picker says the same thing but presents a choice the user must make to proceed, sized like the required fields around it. A switch always holds a value, so a field like this never blocks a submit.',
+        ),
+    // A line under the control, for what the user cannot see from the label alone (a host requirement, when a
+    // value takes effect). The card's `hint` speaks for the whole card; this one is bound to the field it
+    // qualifies, which is where a per-option caveat has to sit to be read at all.
+    hint: z
+        .string()
+        .optional()
+        .describe(
+            "A line under this control, for what the label alone cannot say — a host requirement, when a value takes effect. The card's own `hint` speaks for the whole card; this one is bound to the field it qualifies.",
+        ),
+    /* This field's value only takes effect after the sandbox is REBUILT — it rides the environment overlay
+     * rather than something the daemon can act on now. Rendered as a chip beside the label.
+     *
+     * The one fact a user needs before touching a control, and the one the form cannot infer: two switches
+     * side by side, identical in every visible way, can cost five seconds and five minutes. The docker card
+     * has exactly that pair (its GPU option is baked into the image; its engine options are a file dockerd
+     * rereads), and without this flag the only way to find out which you pressed is to press it. */
+    rebuild: z
+        .boolean()
+        .optional()
+        .describe(
+            "This value only takes effect after the sandbox is rebuilt, because it rides the image overlay. Shown as a chip beside the label — two switches side by side, identical in every visible way, can otherwise cost five seconds or five minutes with no way to tell which.",
+        ),
+    default: z.string().optional(),
+    options: z
+        .array(z.object({ value: z.string(), label: z.string() }))
+        .optional()
+        .describe("Turns the field into a select."),
+    /* Gates this field on the answers already given — the SSH credential that only applies to the auth mode
+     * chosen, the gateway fields that belong to one VPN provider. A `when` condition (@intentic/base/when)
+     * evaluated against the form's live values, so it re-reads as the user toggles.
+     *
+     * Refused at parse when it does not parse. A card is data an extension ships, and a condition nobody can
+     * evaluate is not a field that is always shown or always hidden — it is a card whose author believes it
+     * asks something it never asks. Failing the manifest names the card; failing at render names nothing. */
+    when: z
+        .string()
+        .refine(isWhenExpression, { message: "not a valid `when` condition" })
+        .optional()
+        .describe(
+            "Only show this field while a condition over the answers already given holds — `auth == 'key'`, `provider in ['ipsec', 'fortinet']`, `!advanced`. Supports `&&`, `||`, `!`, comparisons and `in`.",
+        ),
+    // A fixed value baked into the config rather than asked for — how a card pins a discriminator
+    // (platform="reddit", provider="stripe"). Rendered as nothing; sent as itself.
+    value: z
+        .string()
+        .optional()
+        .describe(
+            'A fixed value baked into the config rather than asked for — how a card pins its discriminator (platform="reddit", provider="stripe"). Renders as nothing.',
+        ),
+    /* This field holds a TOTP seed — the base32 key (or otpauth:// URI) a service shows when enrolling an
+     * authenticator app. Declare it WITH `secret: true`: the seed is a durable second factor, so it is never
+     * echoed and, unlike an ordinary secret, never enters the agent's environment either — the daemon mints the
+     * six-digit codes on demand (`otp <name>` / GET /capabilities/<id>/otp) and only those cross, each dead
+     * within its period. A cli entry whose env references a totp field therefore fails to parse (see below). */
+    totp: z
+        .boolean()
+        .optional()
+        .describe(
+            "This field holds a TOTP seed — the base32 key or otpauth:// URI a service shows when enrolling an authenticator app. Declare it with `secret: true`. Unlike an ordinary secret it never enters the agent's environment: the daemon mints the six-digit codes on demand and only those cross.",
+        ),
+});
+export type CapabilityField = z.infer<typeof CapabilityFieldSchema>;
+
+/* WHETHER A FIELD IS IN PLAY, given what has been answered so far — and the only place that decides it.
+ *
+ * Two tiers ask this question about the same card. The web's form asks it to decide what to draw and what to
+ * validate; the daemon asks it at install to decide which fields it may demand. They used to answer it with
+ * their own copies of the same comparison, in different packages, and the answers only had to diverge once for
+ * a card to become unusable in exactly one direction: a field the form never showed, refused at submit for
+ * being empty. Nothing in either copy referred to the other, so the divergence would have arrived as a bug
+ * report about one card rather than as a broken rule.
+ *
+ * It lives beside the schema for the reason the description does: this is a fact about the shape, and the two
+ * consumers are in different packages. Parsed per call rather than cached — a card has a handful of fields,
+ * this runs on a keystroke at worst, and a cache keyed by manifest strings is a map that outlives every
+ * extension that ever declared one. */
+export const fieldApplies = (field: CapabilityField, values: Readonly<Record<string, unknown>>): boolean =>
+    field.when === undefined || evaluateWhen(parseWhen(field.when), values);
+
+// The "+" card an entry renders: how it looks in the grid and how the user gets the credential it asks for.
+// Shared by every arm below, because none of that varies with the kind.
+const CatalogSchema = z.object({
+    name: z.string().min(1),
+    ...MARK_FIELDS,
+    // ONE LINE — aim for 60 characters or fewer. The grid clamps this at two lines and a card sits beside two
+    // others in a pane the index column has already taken 16rem out of, so a paragraph here is a paragraph the
+    // reader gets truncated. Everything longer belongs in `hint`, which the config form prints in full and the
+    // catalog's search reads. Not capped in the schema: an extension published before this rule should still
+    // install, and a card that reads badly is a worse outcome than one that fails to load only in theory.
+    description: z
+        .string()
+        .min(1)
+        .describe(
+            "ONE LINE — aim for 60 characters or fewer. The grid clamps it at two lines in a narrow pane, so a paragraph here is a paragraph the reader gets truncated. Everything longer belongs in `hint`.",
+        ),
+    category: z.string().min(1),
+    // The paragraph. Shown under the add-form, and searched from the catalog — so the words that identify this
+    // card to someone hunting for it ("webauthn", "socket mode") belong here even when the tile can't show them.
+    hint: z
+        .string()
+        .optional()
+        .describe(
+            'The paragraph, shown under the add form and searched from the catalog — so the words that identify this card to someone hunting for it ("webauthn", "socket mode") belong here even when the tile cannot show them.',
+        ),
+    // The credential-creation walkthrough the install dialog renders (the platform catalog's guide shape).
+    guide: z
+        .object({
+            url: z.string().optional(),
+            urlFromField: z.string().optional(),
+            path: z.string().optional(),
+            linkLabel: z.string().optional(),
+            scopes: z.string().optional(),
+            steps: z.array(z.string()).optional(),
+        })
+        .optional()
+        .describe("The walkthrough the install dialog renders for getting the credential this card asks for."),
+});
+
+// Every arm carries these: the slug that becomes the card's /capabilities/<id> route AND the discriminator
+// value the daemon's handler resolves (a cli `provider`, a browser/host `platform`), plus the card and its form.
+const contributionBase = {
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    catalog: CatalogSchema,
+    fields: z.array(CapabilityFieldSchema),
+};
+
+/* A CAPABILITY CARD AS DATA. The catalog is the extensible layer; the HANDLERS are core — so an entry names one
+ * of the kinds whose daemon-side machinery is fully generic over its data, and the machinery stays put. The
+ * kinds NOT listed here are the ones whose card is one-to-one with a handler that owns real privilege (`docker`
+ * bakes --privileged, `vpn` bakes NET_ADMIN, `extension` installs extensions, `devops` scaffolds repos): their
+ * cards live in the platform catalog because separating card from handler would split one concept in two, and
+ * because a manifest that could name them would be a manifest that grants itself privilege. That restriction is
+ * this discriminated union, not a comment — a manifest naming any other kind fails to parse.
+ *
+ * `${id}` in a skill file is substituted with the instance name at apply time (so a host pack's tool names read
+ * `mcp__my-laptop__run_command`), and, for `cli`, each `$ENVVAR` becomes its per-instance suffixed name. */
+export const CapabilityContributionSchema = z
+    .discriminatedUnion("kind", [
+        // A CLI tool the AGENT gets, authenticated: the env vars its shell receives (value templates over the
+        // fields — `${field}` substitutes, `${field:uri}` percent-encodes), a SKILL.md cheatsheet, and an optional
+        // image fragment holding the client binary (psql, mysql, whisper).
+        z.object({
+            ...contributionBase,
+            kind: z.literal("cli"),
+            fields: z.array(CapabilityFieldSchema).min(1),
+            env: z
+                .record(z.string().regex(/^[A-Z][A-Z0-9_]*$/), z.string())
+                .describe(
+                    "The environment the agent's shell gets, as value templates over the fields — `${field}` substitutes, `${field:uri}` percent-encodes. Each name is suffixed per instance.",
+                ),
+            skill: z
+                .string()
+                .min(1)
+                .describe("Checkout-relative SKILL.md teaching the agent this tool. `${id}` in it is replaced with the instance name at apply time."),
+            fragment: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("A Dockerfile fragment holding the client binary this tool needs (psql, mysql, whisper)."),
+        }),
+        /* A site the agent acts on AS THE OWNER, through the shared logged-in Chromium. `loginUrl` is what the
+         * sign-in window opens; the profile it persists is the credential. `homeUrl` is where that same profile
+         * opens once it HAS one — the owner's own hands on the connected browser, which a login page is the wrong
+         * place to start (signed in, it only redirects). Two fields because for some platforms the login lives on
+         * another site entirely (YouTube signs in at accounts.google.com), so one cannot be derived from the other.
+         * No `env` and no `fragment`: the browser itself is core (one Chromium install serves every platform),
+         * only the identity is per-entry. A card never declares the account's username/password either — those are
+         * CORE form fields on every browser card (the catalog appends them; the daemon's add validation accepts
+         * them), because which box a login form wants filled is the same fact on every site.
+         *
+         * BOTH URLs ARE OPTIONAL, so that one card can be the GENERIC one: a site card pins them (Reddit knows
+         * where Reddit signs in), and the generic "browser session" card asks for them on its form instead, which
+         * is what lets a user connect a site nobody shipped a card for. A card must do one or the other — pin a
+         * URL or declare a field that supplies it — and the daemon's apply says so on the form when neither does,
+         * because the alternative is a sign-in window that opens on nothing. */
+        z.object({
+            ...contributionBase,
+            kind: z.literal("browser"),
+            loginUrl: z
+                .url()
+                .optional()
+                .describe(
+                    "What the sign-in window opens; the profile it persists IS the credential. Optional so one card can be the generic one that asks for the URL on its form instead — but a card must either pin this or declare a field that supplies it, or the window opens on nothing.",
+                ),
+            homeUrl: z
+                .url()
+                .optional()
+                .describe(
+                    "Where that same profile opens once it HAS a session — the owner's own hands on the connected browser. Separate from loginUrl because for some platforms the login lives on another site entirely (YouTube signs in at accounts.google.com).",
+                ),
+            skill: z.string().min(1).describe("Checkout-relative SKILL.md teaching the agent this site's actions."),
+        }),
+        // An operating system a connected computer can run — the skill pack that teaches the agent THAT machine's
+        // shell. The enrollment, the socket and the scope enforcement are core; only the pack varies.
+        z.object({
+            ...contributionBase,
+            kind: z.literal("host"),
+            skill: z.string().min(1).describe("Checkout-relative SKILL.md teaching the agent that machine's shell."),
+        }),
+        /* A PRESET over a core kind: no payload at all, just a named card whose `fields` carry the defaults. What an
+         * ACP agent needs is a command, so "OpenCode" is entirely a name, a logo and a filled-in form — which is
+         * exactly what a catalog row is. */
+        z.object({ ...contributionBase, kind: z.literal("agent") }),
+    ])
+    .superRefine((spec, ctx) => {
+        // The totp flag's one invariant, enforced where the manifest is parsed rather than trusted to authors: a
+        // seed the daemon mints codes from must never ride the env into the agent's shell — that would hand the
+        // agent the second factor itself instead of one expiring code at a time.
+        if (spec.kind !== "cli") {
+            return;
+        }
+        for (const field of spec.fields.filter((candidate) => candidate.totp === true)) {
+            if (Object.values(spec.env).some((template) => template.includes(`\${${field.key}}`) || template.includes(`\${${field.key}:uri}`))) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: `env must not reference the totp field "${field.key}" — the daemon mints codes from it instead`,
+                });
+            }
+        }
+    });
+export type CapabilityContribution = z.infer<typeof CapabilityContributionSchema>;
+// The arms carrying a per-instance SKILL.md — the daemon templates and installs these identically.
+export type SkillContribution = Extract<CapabilityContribution, { skill: string }>;
+
+/* The config key a kind's cards PIN to their own id, so a stored capability can be traced back to the card that
+ * made it — the daemon resolves the entry's handler data through it, and the web tells one card's instances from
+ * another's. `agent` has none on purpose: its cards are presets over one config shape, differing only in their
+ * defaults, so every agent instance belongs to every agent card equally.
+ *
+ * Here, beside the schema, because it is a fact about the contribution shape — the daemon, the catalog and the
+ * web all need it, and three copies of it is three chances for a card's instances to go missing. `satisfies`
+ * rather than a lookup table so a new arm above is a compile error until this answers for it. */
+const DISCRIMINATOR = { cli: "provider", browser: "platform", host: "platform", agent: undefined } satisfies Record<
+    CapabilityContribution["kind"],
+    string | undefined
+>;
+export const contributionDiscriminator = (kind: string): string | undefined => DISCRIMINATOR[kind as keyof typeof DISCRIMINATOR];
+
+export const capabilitiesPoint = {
+    name: "capabilities",
+    description:
+        '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, 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 four kinds.',
+    schema: z.array(CapabilityContributionSchema),
+} as const satisfies ContributionPoint;

package/src/points/commands.ts

@@ -0,0 +1,44 @@
+import { isWhenExpression } from "@intentic/base/when";
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// A command the extension may register a handler for (api.commands.register); surfaced in the command palette.
+export const CommandContributionSchema = z.object({
+    command: z.string().regex(/^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/),
+    title: z.string().min(1).describe("What the command palette shows. The manifest's value wins over the one passed at registration."),
+    icon: z.string().optional().describe("A name from the host's icon set, drawn beside the title."),
+    // An optional global keyboard shortcut, in the host's chord notation (`Mod`/`Ctrl`/`Shift`/`Alt` + key, e.g.
+    // "Mod+Shift+K"; `Mod` = ⌘ on Apple, Ctrl elsewhere). It is DECLARED here so it rides the install dialog's
+    // approval surface — a global shortcut is consequential, so like title/icon the manifest value is authoritative
+    // and the host binds only what was approved. Whitespace-free; an unparseable chord simply never fires.
+    keybinding: z
+        .string()
+        .regex(/^\S+$/)
+        .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.',
+        ),
+    /* When the KEYBINDING applies — a condition over the shell's context keys (`tabSurface == 'chat'`,
+     * `!editableTarget`; see @intentic/base/when). The palette ignores it: a command is always runnable by
+     * name, and what a condition decides is whether the chord is claimed from whatever else would have had it.
+     *
+     * Declared here because it could not be declared anywhere. The shell's own commands used to gate on a
+     * JavaScript predicate, which an extension has no way to ship — so every extension command took its chord
+     * globally, from every surface, including terminals where a bare key belongs to the program on the other
+     * end. A condition an extension can write is what makes a contributed shortcut safe to grant. */
+    when: z
+        .string()
+        .refine(isWhenExpression, { message: "not a valid `when` condition" })
+        .optional()
+        .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.",
+        ),
+});
+export type CommandContribution = z.infer<typeof CommandContributionSchema>;
+
+export const commandsPoint = {
+    name: "commands",
+    description:
+        "Commands this extension may register handlers for, surfaced in the command palette. Title, icon and shortcut all come from here rather than from the registration call, because this is what the owner approved at install.",
+    schema: z.array(CommandContributionSchema),
+} as const satisfies ContributionPoint;

package/src/points/documents.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+/* A per-directory document family the extension may register at runtime (api.documents.register): the provider
+ * marks the directory rows it can explain in the Workspace tree, and the host opens its component as a tab —
+ * see DocumentProviderRegistration.
+ *
+ * Only the id and the label are declared, deliberately. The consequential part of a viewer is which FILES it
+ * takes over, and of a command its global shortcut — both are decided in the manifest because the owner must see
+ * them. A document provider takes nothing over: it adds an icon to rows it has something for, and every one of
+ * those rows is evidence the owner can see for themselves. So the manifest gates WHETHER the extension may mark
+ * up the tree at all, and the per-row wording stays with the provider, which is the only thing that knows what
+ * it found. */
+export const DocumentContributionSchema = z.object({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    // The family's human name, shown in the install dialog beside the extension's other contributions.
+    label: z
+        .string()
+        .min(1)
+        .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.",
+        ),
+});
+export type DocumentContribution = z.infer<typeof DocumentContributionSchema>;
+
+export const documentsPoint = {
+    name: "documents",
+    description:
+        "Per-directory documents this extension can offer. Your provider marks the rows in the Workspace tree it has something to say about, and the host opens your component as a tab.",
+    schema: z.array(DocumentContributionSchema),
+} as const satisfies ContributionPoint;

package/src/points/environment.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// A Dockerfile fragment baked into the sandbox image overlay so the extension's tools are present at runtime
+// (a whisper binary, a psql client, …). The daemon rejects FROM and privileged `# intentic:runtime` directives
+// from extension fragments (those stay daemon-owned), and the owner approves the composed overlay + rebuilds
+// out-of-band.
+export const EnvironmentContributionSchema = z.object({
+    fragment: z
+        .string()
+        .min(1)
+        .refine((value) => !value.split("/").includes(".."), { message: "fragment must stay inside the checkout" })
+        .describe(
+            "Checkout-relative path to a file holding ONLY RUN and ENV instructions. FROM and privileged directives are rejected — those stay daemon-owned.",
+        ),
+});
+export type EnvironmentContribution = z.infer<typeof EnvironmentContributionSchema>;
+
+export const environmentPoint = {
+    name: "environment",
+    description:
+        "A Dockerfile fragment baked into the sandbox image so your tools are actually installed at runtime — a whisper binary, a psql client. The owner approves the composed overlay and rebuilds out of band, so this does not take effect immediately.",
+    schema: EnvironmentContributionSchema,
+} as const satisfies ContributionPoint;

package/src/points/files.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+/* WHICH WORKSPACE FILE MAKES THIS EXTENSION'S VIEW STALE — the extension's half of the core's
+ * WORKSPACE_STATE_FILES table (@intentic/sandbox-contract), in the same two fields so the browser can union them
+ * without translating.
+ *
+ * An intentic workspace is file-first: the agent edits /work with its own file tools, out of band from every
+ * HTTP route, and the daemon's filesystem watcher is the ONLY thing that can tell a browser its view went stale.
+ * Before this contribution point existed an extension had no way into that push, so every one of them polled —
+ * and the core's table had to hardcode `automations`/`automation-approvals`, query keys owned by an extension,
+ * because the extension itself couldn't declare them. Declaring is now the extension's job and unioning is the
+ * host's.
+ *
+ * It rides the manifest rather than a runtime api.workspace.onDidChangeFiles for two reasons: the owner sees at
+ * install which of their files an extension reads, and there is nothing imperative left to get wrong — no
+ * subscribe, no unsubscribe, no listener that quietly stops firing. */
+export const FileContributionSchema = z.object({
+    /* Workspace-root-relative, forward-slash — the space the watcher's changed paths arrive in. Matched by
+     * PREFIX, so one entry covers an exact file (`.intentic/automations.json`), a directory (`.intentic/drafts/`
+     * — keep the trailing slash so it cannot match a sibling file) or a name family (`.intentic/environment.`).
+     * Deliberately not a glob: prefix is the whole matching rule on both sides of this union. */
+    path: z
+        .string()
+        .min(1)
+        .refine((value) => !value.startsWith("/") && !value.split("/").includes(".."), {
+            message: "path must be workspace-root-relative and stay inside the workspace",
+        })
+        .describe(
+            "Workspace-root-relative, forward-slash, matched by prefix — so one entry covers an exact file (`.intentic/automations.json`), a directory (`.intentic/drafts/`, with the trailing slash so it cannot match a sibling file) or a name family (`.intentic/environment.`). Not a glob.",
+        ),
+    /* The browser query keys those contents feed — the first element of the extension's own
+     * `api.sandbox.key(...)` keys, which is what makes them match (the sandbox id is a SUFFIX). Empty is not
+     * allowed: a path that makes nothing stale is a declaration with no effect, and saying so at install beats
+     * discovering it as a view that never refreshes.
+     *
+     * Keep the paths as narrow as the view actually needs. A broad prefix costs every connected browser a
+     * refetch per matching write, and a write-heavy path (an index, a transcript, a log) turns that into a
+     * request storm — the reason the core table leaves the daemon's own machine state off the push entirely. */
+    invalidates: z
+        .array(z.string().min(1))
+        .min(1)
+        .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.",
+        ),
+});
+export type FileContribution = z.infer<typeof FileContributionSchema>;
+
+export const filesPoint = {
+    name: "files",
+    description:
+        "Which workspace files back your views, so the daemon's file watcher can tell the browser they went stale instead of you polling for it. The agent edits the workspace out of band from every HTTP route, and this push is the only thing that can notice.",
+    schema: z.array(FileContributionSchema),
+} as const satisfies ContributionPoint;

package/src/points/index.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+import { agentPoint } from "./agent.js";
+import { automationTemplatesPoint } from "./automation-templates.js";
+import { binPoint } from "./bin.js";
+import { capabilitiesPoint } from "./capabilities.js";
+import { commandsPoint } from "./commands.js";
+import { documentsPoint } from "./documents.js";
+import { environmentPoint } from "./environment.js";
+import { filesPoint } from "./files.js";
+import { listenerPoint } from "./listener.js";
+import { processesPoint } from "./processes.js";
+import { settingsPoint } from "./settings.js";
+import { viewersPoint } from "./viewers.js";
+import { viewsPoint } from "./views.js";
+
+export * from "./agent.js";
+export * from "./automation-templates.js";
+export * from "./bin.js";
+export * from "./capabilities.js";
+export * from "./commands.js";
+export * from "./documents.js";
+export * from "./environment.js";
+export * from "./files.js";
+export * from "./listener.js";
+export * from "./processes.js";
+export * from "./settings.js";
+export * from "./viewers.js";
+export * from "./views.js";
+
+/* EVERYTHING A MANIFEST MAY DECLARE. `contributes` is assembled from this list (manifest.ts), the authoring
+ * JSON Schema is generated from it (json-schema.ts), and the SDK's surface guard reads the point names back out
+ * of it — so the three cannot disagree about what this build supports.
+ *
+ * Collected explicitly rather than by a module-load side effect, because two readers need the answer to be the
+ * same every time it is asked: the wire contract's lock file, which is a committed document a diff has to be
+ * able to guard, and the generated schema, which is committed too. A registry that filled itself as modules
+ * happened to load would make both of those depend on import order.
+ *
+ * Adding a point is a file in this directory and a line here — points.test.ts fails when a file appears without
+ * the line, so the pair cannot come apart. */
+export const CONTRIBUTION_POINTS = [
+    viewsPoint,
+    filesPoint,
+    viewersPoint,
+    documentsPoint,
+    commandsPoint,
+    settingsPoint,
+    processesPoint,
+    agentPoint,
+    environmentPoint,
+    capabilitiesPoint,
+    listenerPoint,
+    automationTemplatesPoint,
+    binPoint,
+] as const satisfies readonly ContributionPoint[];
+
+// The `contributes` shape those points assemble to: each point's key, its schema, optional. A mapped type
+// rather than a widened record so `manifest.contributes.views` keeps its exact type at every call site — the
+// whole point of the schema being typed at all.
+type ContributesShape = {
+    [Point in (typeof CONTRIBUTION_POINTS)[number] as Point["name"]]: z.ZodOptional<Point["schema"]>;
+};
+
+/* The `contributes` object, assembled rather than hand-written — which is what makes adding a point a file plus
+ * a line above, instead of an edit to a schema thirteen unrelated features share.
+ *
+ * Each point's description rides `z.describe` onto its own key, so it survives into the generated authoring
+ * schema and reaches the author as hover text. The cast is the one place the value side and the type side meet:
+ * `Object.fromEntries` can only say `Record<string, …>`, and ContributesShape is that said precisely. */
+export const contributesSchema = z.object(
+    Object.fromEntries(CONTRIBUTION_POINTS.map((point) => [point.name, point.schema.describe(point.description).optional()])) as ContributesShape,
+);

package/src/points/listener.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// One narrowing field the generic automation editor draws for a source — a channel, a branch. `hint` is the
+// sentence under the input, for a filter whose empty case is easy to get wrong.
+const TriggerFieldContributionSchema = z.object({
+    label: z.string().min(1),
+    placeholder: z.string().min(1),
+    hint: z.string().min(1).optional().describe("The sentence under the input, for a filter whose empty case is easy to get wrong."),
+});
+
+/* A realtime listener source the extension supplies. This is the ONE catalog both halves consume: the daemon
+ * derives its accepted event types from `events` and folds `automation` into the trigger catalogue it serves,
+ * while the automation editor derives the source picker, filters and starter from that. Keeping those facts on
+ * the provider extension is what lets a newly installed listener become configurable without a matching app
+ * release.
+ *
+ * The daemon serves a provider-scoped control surface — GET /listeners/<provider>/state to reconcile, POST
+ * …/dispatch to wake an automation (optionally holding a turn-stream), …/failure + …/status to report. The
+ * daemon holds no provider connection itself.
+ *
+ * WHAT DISPATCHES IT IS OPEN. A gateway process (contributes.processes) is the usual answer and the one the
+ * reconcile feed is shaped for — it holds a live connection the daemon must not. But an extension BACKEND can
+ * dispatch through the same route by declaring the dispatch path in `permissions.daemon`, which is
+ * how an area that learns things on its own schedule (an estate poller noticing a container died) contributes
+ * a trigger without running a gateway at all. Declaring this with neither is legal and inert: the source is
+ * offered, and nothing ever fires it. */
+export const ListenerContributionSchema = z.object({
+    provider: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/)
+        .describe("The slug this source's automation triggers fire on."),
+    events: z
+        .array(
+            z.object({
+                type: z.string().regex(/^[a-z0-9][a-z0-9_]*$/),
+                label: z.string().min(1),
+            }),
+        )
+        .min(1)
+        .refine((events) => new Set(events.map((event) => event.type)).size === events.length, {
+            message: "listener event types must be unique",
+        })
+        .describe("The event types this source can fire, with the wording the automation editor offers them under. The daemon accepts no others."),
+    automation: z
+        .object({
+            label: z.string().min(1),
+            // Only sources whose `message` events distinguish addressed messages declare this. Absent means the
+            // generic editor offers no mention-only filter rather than inventing provider semantics.
+            mentionLabel: z
+                .string()
+                .min(1)
+                .optional()
+                .describe(
+                    "Only for a source whose message events distinguish being addressed. Absent ⇒ the editor offers no mention-only filter, rather than inventing semantics you did not promise.",
+                ),
+            channel: TriggerFieldContributionSchema.describe("The primary narrowing filter — a channel, a room, a repo."),
+            // A SECOND narrowing axis, for a source whose events carry one — a pipeline's git ref, so a trigger can
+            // say "the branch that ships" rather than "every agent's every failure". Absent ⇒ the editor offers
+            // only the channel filter.
+            branchField: TriggerFieldContributionSchema.optional().describe(
+                'A second narrowing axis, for a source whose events carry one — a pipeline\'s git ref, so a trigger can say "the branch that ships" rather than "every agent\'s every failure".',
+            ),
+            // The provider owns the payload vocabulary, so it also owns the first prompt that explains that payload.
+            starterPrompt: z
+                .string()
+                .min(1)
+                .describe(
+                    "The first prompt a new automation on this source is prefilled with. You own the payload vocabulary, so you own the prompt that explains it.",
+                ),
+        })
+        .describe("How the generic automation editor presents this source: its name, its filters, and the prompt it starts people on."),
+});
+export type ListenerContribution = z.infer<typeof ListenerContributionSchema>;
+
+export const listenerPoint = {
+    name: "listener",
+    description:
+        "A realtime event source this extension supplies, so automations can trigger on it. One declaration feeds both halves: the daemon accepts these event types and serves this provider's control surface, and the automation editor derives its source picker, filters and starter prompt from it — so a newly installed listener is configurable without a matching app release.",
+    schema: ListenerContributionSchema,
+} as const satisfies ContributionPoint;

package/src/points/processes.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// A long-lived background process the daemon runs for the extension (tmux-managed, like panel dev servers).
+export const ProcessContributionSchema = z.object({
+    name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    command: z.string().min(1),
+    cwd: z.string().optional().describe("Relative to the extension checkout. Absent ⇒ the checkout root."),
+    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."),
+});
+export type ProcessContribution = z.infer<typeof ProcessContributionSchema>;
+
+export const processesPoint = {
+    name: "processes",
+    description:
+        "Long-lived background processes the daemon runs for this extension — a gateway holding a connection the daemon must not, a dev server. Managed the same way panel dev servers are, and startable and stoppable from the Extensions tab.",
+    schema: z.array(ProcessContributionSchema),
+} as const satisfies ContributionPoint;

package/src/points/settings.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import type { ContributionPoint } from "../contribution-point.js";
+
+// A typed setting descriptor the host renders schema-driven into the Settings page and persists daemon-side.
+export const SettingContributionSchema = z.object({
+    key: z.string().regex(/^[a-z0-9][a-zA-Z0-9-]*$/),
+    type: z.enum(["boolean", "string", "number", "enum"]).describe("Which control the Settings page draws. `enum` reads its choices from `enum`."),
+    title: z.string().min(1),
+    description: z.string().optional().describe("The line under the control."),
+    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    enum: z.array(z.string()).optional().describe('The choices, for type "enum". Meaningless otherwise.'),
+    secret: z
+        .boolean()
+        .optional()
+        .describe("Mask the value in the UI and strip it from reads — a set secret round-trips as “still set”, never as its value."),
+    env: z
+        .string()
+        .regex(/^[A-Z][A-Z0-9_]*$/)
+        .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.",
+        ),
+});
+export type SettingContribution = z.infer<typeof SettingContributionSchema>;
+
+export const settingsPoint = {
+    name: "settings",
+    description:
+        "Typed settings the host renders into the Settings page for you and persists daemon-side. You never draw the form or store the value; you read it back with api.settings.get.",
+    schema: z.array(SettingContributionSchema),
+} as const satisfies ContributionPoint;