@ryuhq/sdk 0.1.14 → 0.2.0

package/src/generated/plugin-manifest.ts

@@ -32,6 +32,17 @@ export type SettingsFieldOption =
 			 */
 			value: string;
 	  };
+/**
+ * Authentication Ryu performs on behalf of the user for a remote MCP server.
+ *
+ * `deny_unknown_fields` is a security boundary: a publisher cannot smuggle a
+ * client secret, token endpoint, redirect URI, token or scope list into a signed
+ * manifest and have an older Core silently ignore it.
+ */
+export type McpServerAuthDecl = {
+	client_id?: string | null;
+	type: "oauth";
+};
 /**
  * What a capability provider acts on — see [`ProvidesEntry::target`].
  *
@@ -192,6 +203,13 @@ export interface PluginManifest {
 	 * Prompt-chip examples (contract key `examplePrompts`; Ryu extension).
 	 */
 	examplePrompts?: string[];
+	/**
+	 * Whether the provider operates outside the local Ryu runtime, for example a
+	 * hosted browser or remote MCP service. This is a presentation/provenance
+	 * flag, not a permission grant; the actual remote endpoint remains declared
+	 * under `mcp_servers` and is governed by the Gateway.
+	 */
+	external?: boolean;
 	/**
 	 * Hide this listing from the Store without uninstalling or disabling it.
 	 *
@@ -403,6 +421,12 @@ export interface PluginManifest {
 	 * `sidecar`/`route` exists (like `contributes`).
 	 */
 	provides?: ProvidesEntry[];
+	/**
+	 * Public source repository URL (Claude/Codex `repository`). This is listing
+	 * metadata only; install and signature resolution still use the catalog's
+	 * authoritative source fields.
+	 */
+	repository?: string | null;
 	/**
 	 * **Plugin-to-plugin dependencies** — the other plugins this one needs (the
 	 * npm-shaped edge that lets the app decompose into a kernel + features).
@@ -483,6 +507,14 @@ export interface PluginManifest {
 	 * Short one-line tagline shown under the name (Ryu extension).
 	 */
 	tagline?: string | null;
+	/**
+	 * Curated store-filter tags (Ryu extension). Unlike `keywords`, which is
+	 * publisher search vocabulary, these stable labels are the values the
+	 * Marketplace filter exposes. Keeping both fields lets Claude/Codex
+	 * manifests round-trip their native `keywords` while Ryu authors opt into
+	 * a deliberately bounded taxonomy.
+	 */
+	tags?: string[];
 	/**
 	 * Host surfaces this plugin runs on (desktop / island / mobile / …).
 	 *
@@ -545,8 +577,8 @@ export interface CompanionSurface {
  * Most surfaces added since are **self-contained**: they carry their own payload
  * and reference no runnable at all (`widgets`, `views`, `dock_panels`,
  * `sidebar_sections`, `sidebar_buttons`, `settings_tabs`, `composer_controls`,
- * `slash_commands`, `turn_hooks`, `tool_filters`, `lsp_servers`,
- * `message_actions`, `context_menu_items`).
+ * `chat_features`, `slash_commands`, `turn_hooks`, `tool_filters`, `lsp_servers`,
+ * `message_actions`, `context_menu_items`, `agent_edit_panels`).
  *
  * # Extending
  *
@@ -563,7 +595,8 @@ export interface CompanionSurface {
  *    (`tool_filters`, `turn_hooks`, `widgets`, `lsp_servers`) it gets a fully typed
  *    struct, because a key Core does not know is by construction a key Core cannot
  *    act on. If a client shell renders it (`views`, `dock_panels`,
- *    `sidebar_sections`, `settings_tabs`, `composer_controls`) it stays opaque
+ *    `sidebar_sections`, `settings_tabs`, `composer_controls`,
+ *    `agent_edit_panels`) it stays opaque
  *    JSON, because deserializing into a struct here would DROP any key this Core
  *    build does not know about and a newer desktop would lose exactly the fields it
  *    was shipped to render.
@@ -573,10 +606,34 @@ export interface CompanionSurface {
  * they are gathered at their own consumption site instead.
  */
 export interface Contributes {
+	/**
+	 * Client-rendered panels for the agent edit page. Entries are deliberately
+	 * opaque and self-contained: the desktop owns the panel vocabulary, while
+	 * Core only stores, tags, and forwards the declaration through the plugin
+	 * contributions endpoint. This lets a newer desktop add an agent-edit
+	 * panel type without requiring every Core node to learn that type first.
+	 * These entries name no runnable ids and therefore are intentionally absent
+	 * from [`Contributes::referenced_ids`].
+	 */
+	agent_edit_panels?: unknown[];
 	/**
 	 * Agents the plugin contributes (referenced by runnable id).
 	 */
 	agents?: ContributionId[];
+	/**
+	 * Declarative chat feature descriptors. These are opaque, client-rendered
+	 * declarations used to feature-detect chat behaviors whose implementation
+	 * remains in the host (for example side chats or temporary chats). The
+	 * owning plugin id is stamped by Core when the contribution endpoint serves
+	 * them, so a disabled plugin removes both the descriptor and its UI affordance.
+	 */
+	chat_features?: unknown[];
+	/**
+	 * Metadata-only chat widget templates. Unlike [`Contributes::widgets`], this
+	 * catalog is safe to show before a turn runs: it names a host-owned prompt
+	 * affordance and a tool/view binding, never HTML, React, or capabilities.
+	 */
+	chat_widget_templates?: ChatWidgetTemplateContribution[] | null;
 	/**
 	 * Command-palette commands the plugin contributes (referenced by runnable id).
 	 */
@@ -737,6 +794,27 @@ export interface Contributes {
 	 * **self-contained** and stays out of [`Contributes::referenced_ids`].
 	 */
 	hook_events?: HookEventContribution[];
+	/**
+	 * **Live activities** the plugin contributes — small, always-live status cards
+	 * the desktop shell's "Dynamic Island" dock (empty-shell launchpad + sidebar)
+	 * renders for something in progress: an agent run, a download, a pending
+	 * approval, a recording. The desktop half of the same status vocabulary the
+	 * mobile `AgentActivity` uses, so one mental model spans devices.
+	 *
+	 * Each entry is a [`LiveActivityContribution`]: a typed envelope (`id`/`title`/
+	 * `icon`/`accent`/`order`) around an **opaque** `spec` payload the desktop
+	 * renderer interprets. Like a [`Contributes::sidebar_sections`] entry it carries
+	 * a `ViewSource` (a Core `/api/` path the shell polls) and a field-map; unlike a
+	 * section it maps response ROWS to live-activity cards (status/progress/target)
+	 * instead of nav rows. The app returns DATA — never code — so a live activity
+	 * cannot be made ugly and needs zero sidecar code.
+	 *
+	 * Self-contained (it names no runnable), so it stays out of
+	 * [`Contributes::referenced_ids`]; the `spec` stays opaque to Core so a new
+	 * activity capability is a renderer change, not a Core change. Served + tagged
+	 * with the owning `plugin` id at `GET /api/plugins/contributions`.
+	 */
+	live_activities?: LiveActivityContribution[];
 	/**
 	 * **Language servers** the plugin declares, keyed by server name — the
 	 * agent-neutral mirror of Claude Code's `.lsp.json` / `lspServers`, so a config
@@ -915,7 +993,7 @@ export interface Contributes {
 	 * ([`Contributes::sidebar_sections`]) and "what nav rows exist"
 	 * ([`Contributes::sidebar_buttons`]): **how the sidebar as a whole is
 	 * arranged**. The shell ships three modes of its own (every section stacked;
-	 * every section as a tab; Agent mode, which is the pair Sessions ⇄ Agents), and
+	 * every section as a tab; Bot mode, which is the pair Sessions ⇄ Agents), and
 	 * before this member an app could add a section to that list but could not
 	 * propose an arrangement — so a plugin wanting the Grok/Hermes bot-mode posture
 	 * had to ask for a shell change. See [`SidebarModeContribution`].
@@ -1058,6 +1136,36 @@ export interface ContributionId {
 	 */
 	title?: string | null;
 }
+/**
+ * A metadata-only entry the host may offer as a compact chat affordance.
+ *
+ * `backing` selects exactly one existing tool or view by id. The host owns the
+ * eventual rendering and action dispatch; `safe_action_ids` are identifiers only
+ * and are never executable payloads.
+ */
+export interface ChatWidgetTemplateContribution {
+	/**
+	 * `available`, `coming-soon`, or `unavailable`; unknown values are forwarded
+	 * for forward compatibility and are not offered by older shells.
+	 */
+	availability?: string;
+	backing: ChatWidgetTemplateBacking;
+	description?: string | null;
+	/**
+	 * Open vocabulary so newer shells can add display modes without breaking
+	 * older Core nodes; the desktop simply ignores modes it does not know.
+	 */
+	display_mode: string;
+	examples?: string[];
+	id: string;
+	safe_action_ids?: string[];
+	title: string;
+	triggers?: string[];
+}
+export interface ChatWidgetTemplateBacking {
+	tool_id?: string | null;
+	view_id?: string | null;
+}
 /**
  * One context-menu row a plugin contributes (see
  * [`Contributes::context_menu_items`]).
@@ -1302,6 +1410,50 @@ export interface HookEventContribution {
 	 */
 	title: string;
 }
+/**
+ * One app-registered **live activity** — a small, always-live status card the
+ * desktop's "Dynamic Island" dock (empty-shell launchpad + sidebar) renders for
+ * something in progress: an agent run, a download, a pending approval, a
+ * recording. The desktop half of the status vocabulary the mobile `AgentActivity`
+ * uses (`running` / `waiting` / `review` / `done` / `error`), so one mental model
+ * spans devices.
+ *
+ * A typed envelope around an opaque `spec` (the `LiveActivitySpec` in
+ * `@ryu/app-host/live-activity`: a `ViewSource` for the live rows, a field-map
+ * from rows to card fields, and a `target` route template). Core stores it
+ * verbatim and tags it with the owning `plugin` id; the `spec` stays opaque so a
+ * new activity capability is a renderer change, not a Core change.
+ */
+export interface LiveActivityContribution {
+	/**
+	 * Optional accent colour hint (any CSS color) tinting the card.
+	 */
+	accent?: string | null;
+	/**
+	 * Optional glyph id resolved by the shell's Icon primitive (Iconify/Hugeicons).
+	 */
+	icon?: string | null;
+	/**
+	 * Stable id for this activity within the plugin (namespaced into the shell's
+	 * dock identity as `plugin:<pluginId>:<id>:<rowId>`).
+	 */
+	id: string;
+	/**
+	 * Optional placement hint among the dock's activities (lower = first).
+	 */
+	order?: number | null;
+	/**
+	 * The opaque activity spec (source/map/target). Interpreted by the desktop
+	 * renderer, never by Core. Absent = a header-only activity (renders nothing).
+	 */
+	spec?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Human-facing title shown on the dock card (falls back to the row title).
+	 */
+	title: string;
+}
 /**
  * One **language server** a plugin declares (see [`Contributes::lsp_servers`]).
  *
@@ -1746,7 +1898,7 @@ export interface SidebarModeContribution {
 	/**
 	 * Which of `sections` the mode opens on. Absent (or naming a section not in
 	 * `sections`) = the first one. This is the field that makes a mode an opinion
-	 * rather than a filter: the shell's own Agent mode lists Sessions first but
+	 * rather than a filter: the shell's own Bot mode lists Sessions first but
 	 * opens on Agents, because the roster is what the mode is for.
 	 */
 	default_section?: string | null;
@@ -1926,10 +2078,10 @@ export interface ThemePreview {
  * One **tool filter**: a fully-qualified tool id a plugin wants withheld from the
  * model's offered tool list.
  *
- * Tools are namespaced `<server>__<tool>` (e.g. `browser__navigate`), so `tool`
+ * Tools are namespaced `<server>.<tool>` (e.g. `browser.navigate`), so `tool`
  * must carry the namespace — a bare `navigate` would be ambiguous across servers
  * and is rejected at load. A **trailing** `*` is a prefix wildcard, which is how a
- * plugin withholds a whole server (`shadow__*`); it is the only wildcard position
+ * plugin withholds a whole server (`shadow.*`); it is the only wildcard position
  * allowed, because an interior or leading `*` invites a pattern that silently
  * matches far more than the author pictured.
  *
@@ -1947,7 +2099,7 @@ export interface ToolFilterContribution {
 	 */
 	reason?: string | null;
 	/**
-	 * Fully-qualified tool id (`<server>__<tool>`), optionally ending in `*` to
+	 * Fully-qualified tool id (`<server>.<tool>`), optionally ending in `*` to
 	 * hide every tool whose id starts with the preceding prefix.
 	 */
 	tool: string;
@@ -1999,6 +2151,11 @@ export interface TurnHookContribution {
 	 * The turn boundary this hook fires on. Today only `"post_assistant_turn"`.
 	 */
 	on: string;
+	/**
+	 * Higher-priority hooks run first within a phase. Ties are resolved by
+	 * plugin id and hook id, which makes first-writer-wins directives stable.
+	 */
+	priority?: number;
 }
 /**
  * A declarative pre-gate for a [`TurnHookContribution`]. The conditions are
@@ -2169,26 +2326,41 @@ export interface EnginesReq {
 	web?: string | null;
 }
 /**
- * One declarative **stdio MCP server** a plugin registers (see
- * [`PluginManifest::mcp_servers`]).
+ * One declarative **MCP server** a plugin registers (see
+ * [`PluginManifest::mcp_servers`]) — either a stdio command to spawn or a remote
+ * HTTP endpoint to call.
  *
  * This is the manifest-side, dependency-free mirror of Core's runtime
  * `McpServerConfig`: pure data (schemars/serde only) so it can live in
  * kernel-contracts, with Core lowering it into its registry type on enable. A
- * server is spawned per request as `command args…` (stdio); `command_env` lets
+ * stdio server is spawned per request as `command args…`; `command_env` lets
  * the manifest name an env var Core resolves to an absolute binary path
  * (e.g. `RYU_GHOST_BIN`) so a downloaded `~/.ryu/bin` binary can override the
- * bare `command`.
+ * bare `command`. An HTTP server names a [`url`](McpServerDecl::url) instead and
+ * spawns nothing at all.
+ *
+ * The field names mirror the `mcp.json` dialect users already paste from Cursor
+ * and Claude Desktop (`type` / `url` / `headers`) precisely so a manifest and a
+ * hand-written config entry are the same shape. Static API-key auth may live in
+ * [`headers`](McpServerDecl::headers). User-delegated OAuth is declared through
+ * [`auth`](McpServerDecl::auth), and Core owns the resulting token lifecycle.
  */
 export interface McpServerDecl {
 	/**
 	 * Arguments passed to the command.
 	 */
 	args?: string[];
+	/**
+	 * Core-owned OAuth for this remote MCP server. The manifest may name only an
+	 * optional public client id; discovery, PKCE, tokens and redirect URIs are
+	 * intentionally outside the publisher-controlled manifest.
+	 */
+	auth?: McpServerAuthDecl | null;
 	/**
 	 * Executable to spawn (e.g. `npx`, an absolute path, or a `~/.ryu/bin` name).
+	 * Absent for a remote (`url`) server.
 	 */
-	command: string;
+	command?: string | null;
 	/**
 	 * Optional env var whose value, when set, OVERRIDES [`command`] with an
 	 * absolute binary path. Lets a plugin ship a bare `command` that Core repoints
@@ -2212,6 +2384,22 @@ export interface McpServerDecl {
 	env?: {
 		[k: string]: string;
 	};
+	/**
+	 * Request headers sent with every call to a remote server (auth lives here).
+	 */
+	headers?: {
+		[k: string]: string;
+	};
+	/**
+	 * Transport: `stdio`, `http`, `streamable-http`, or `sse`. Absent ⇒ inferred
+	 * from whichever of `command`/`url` is present. `http` and `streamable-http`
+	 * select Streamable HTTP; `sse` selects the legacy HTTP+SSE transport.
+	 */
+	type?: string | null;
+	/**
+	 * Endpoint URL for a remote (HTTP) server. Absent for a stdio server.
+	 */
+	url?: string | null;
 }
 /**
  * One entry in an app's **user-facing permission vocabulary** — a level an admin
@@ -2413,7 +2601,7 @@ export interface ProvidesEntry {
 	 * model-visible tool surface stable across a swap.
 	 *
 	 * The key is a canonical verb from the host's capability verb table (e.g.
-	 * `"web__search"`); the value names the provider's own registered tool plus the
+	 * `"web.search"`); the value names the provider's own registered tool plus the
 	 * argument/response mapping into the canonical shape. A provider that omits a
 	 * verb simply does not serve it — the facade reports the verb unavailable
 	 * rather than guessing.
@@ -2431,7 +2619,7 @@ export interface ProvidesEntry {
 /**
  * How one capability **verb** maps onto a concrete provider tool.
  *
- * The facade tool (`web__search`, `browser__navigate`, …) is registered by the host
+ * The facade tool (`web.search`, `browser.navigate`, …) is registered by the host
  * from its canonical verb table; at call time it resolves the capability's bound
  * provider, reads this binding, renames the arguments, re-enters tool dispatch on
  * [`Self::tool`], and maps the response back. Swapping the provider therefore
@@ -2464,7 +2652,7 @@ export interface CapabilityToolBinding {
 	 * **canonical** argument name (before any rename).
 	 *
 	 * Exists because canonical schemas describe what agents may ask for, while
-	 * providers differ in what they accept: `web__search.limit` allows up to 100,
+	 * providers differ in what they accept: `web.search.limit` allows up to 100,
 	 * but Brave's `count` maxes at 20. Without this, selecting Brave turns a
 	 * perfectly valid `limit: 50` into an upstream 4xx — the swap stops being
 	 * transparent, which is the entire point of the facade. Clamping is the right
@@ -2514,8 +2702,8 @@ export interface CapabilityToolBinding {
 	 */
 	response?: CapabilityResponseMap | null;
 	/**
-	 * The provider's own fully-qualified tool id (e.g. `"exa__search"`,
-	 * `"app__firecrawl_scrape"`) that implements this verb.
+	 * The provider's own fully-qualified tool id (e.g. `"exa.search"`,
+	 * `"app.firecrawl_scrape"`) that implements this verb.
 	 */
 	tool: string;
 }
@@ -2801,17 +2989,17 @@ export interface ExternalRuntimeConfig {
 }
 /**
  * A single asset an external runtime needs, fetched before first run. Either a
- * direct https URL or an `hf:<owner>/<repo>/<path>` reference; `dest_under_ryu`
- * is the relative directory beneath `~/.ryu` where it lands (Core-owned) — the
- * filename is derived from the source's last path segment.
+ * direct https URL or an `hf:<owner>/<repo>/<path>` reference; the destination
+ * is a relative directory beneath the plugin's dedicated runtime `assets/`
+ * directory — the filename is derived from the source's last path segment.
  */
 export interface AssetSpec {
 	/**
 	 * Destination directory relative to `~/.ryu` (e.g. `"models/hf"`); the
-	 * fetched file lands at `~/.ryu/<dest_under_ryu>/<filename>`. Must be a
-	 * traversal-safe relative path (no `..`, not absolute).
+ * fetched file lands at `<runtime>/assets/<dest_under_runtime>/<filename>`. Must
+ * be a traversal-safe relative path (no `..`, not absolute).
 	 */
-	dest_under_ryu: string;
+	dest_under_runtime: string;
 	/**
 	 * Optional SHA-256 for checksum verification (direct-URL assets).
 	 */
@@ -2908,6 +3096,16 @@ export interface SidecarSpec {
 	 * until the first proxy/broker hit wakes it on demand; a bounded health-wait
 	 * warms it before the request is forwarded. `false` (the default) keeps the
 	 * eager behaviour every existing manifest has: started at enable. Additive.
+	 *
+	 * **Ignored when [`provides_provider`] is set.** Such a sidecar is always started
+	 * eagerly, because the two declarations are mutually exclusive by construction: a
+	 * lazy sidecar's only wake trigger is a proxy/broker hit, while a provider's only
+	 * client is Pi, which dials the registered `baseUrl` directly and never traverses
+	 * the proxy. Nothing could ever wake it, and Core's boot purge of stale
+	 * sidecar-owned provider entries would then leave the provider permanently dead.
+	 * The coercion is logged at `info`; the manifest is NOT rejected.
+	 *
+	 * [`provides_provider`]: SidecarSpec::provides_provider
 	 */
 	lazy?: boolean;
 	/**
@@ -2918,9 +3116,16 @@ export interface SidecarSpec {
 	name: string;
 	/**
 	 * TCP port the process's HTTP server binds to, used to build the health-check
-	 * URL. The plugin is responsible for choosing a free port — there is **no port
-	 * registry in v1**, so a collision with a built-in (e.g. llama.cpp on 8080) is
-	 * the plugin author's responsibility to avoid.
+	 * URL. The plugin is responsible for choosing a free port: there is **no
+	 * allocator** — this number is what Core tries (after the profile offset), and a
+	 * collision is not repaired by moving anyone.
+	 *
+	 * There *is* a gate. `SidecarManager::claim_port` checks a live-sidecar registry
+	 * and bind-probes the port, and **refuses to start** the sidecar if either fails,
+	 * so a collision with a built-in (e.g. llama.cpp on 8080) surfaces as an app that
+	 * does not come up rather than as silent breakage. Detection, not resolution:
+	 * picking a free port is still the author's job. See `docs/port-allocation.md`
+	 * for the band map.
 	 */
 	port: number;
 	/**
@@ -2939,6 +3144,17 @@ export interface SidecarSpec {
 	 * ext-proxy hop and `/api/host/*`), and the host-RPC vocabulary has no
 	 * provider-registration method. Registration is therefore Core-side, driven by
 	 * this declaration.
+	 *
+	 * **Declaring this forces eager start and disables idle-stop**, overriding
+	 * [`lazy`] and [`idle_stop_secs`]. Pi bypasses the ext proxy and dials the
+	 * registered `baseUrl` directly, so no request can ever wake this sidecar on
+	 * demand; a sidecar that is never started never reaches the Healthy edge that
+	 * registers it, and one that is scaled to zero drops out of Pi's model list until
+	 * a wake that will never come. Both coercions are logged at `info` rather than
+	 * rejected by the validator, so existing manifests keep loading.
+	 *
+	 * [`lazy`]: SidecarSpec::lazy
+	 * [`idle_stop_secs`]: SidecarSpec::idle_stop_secs
 	 */
 	provides_provider?: ProviderRegistrationSpec | null;
 }

package/src/index.ts

@@ -37,6 +37,8 @@ export type {
 	CapabilityReq,
 	CompanionSurface,
 	Contributes,
+	McpServerAuth,
+	McpServerDecl,
 	PluginManifest,
 	Requires,
 	RunnableKind,
@@ -51,6 +53,8 @@ export {
 	CapabilityReqSchema,
 	CompanionSurfaceSchema,
 	coreManifestJsonSchema,
+	McpServerAuthSchema,
+	McpServerDeclSchema,
 	PluginManifestSchema,
 	RequiresSchema,
 	RunnableKindSchema,
@@ -61,6 +65,20 @@ export {
 	validatePluginId,
 	WidgetContributionSchema,
 } from "./manifest.ts";
+export type {
+	JsonSchema,
+	McpStdioCommand,
+	McpTool,
+	PassthroughRegistration,
+	SdkRunnable,
+} from "./mcp/index.ts";
+export {
+	callTool,
+	listTools,
+	MCP_PROTOCOL_VERSION,
+	McpServer,
+	unwrapContent,
+} from "./mcp/index.ts";
 export type {
 	ChatDelta,
 	ChatMessage,
@@ -74,6 +92,21 @@ export {
 	resolveGatewayToken,
 	resolveGatewayUrl,
 } from "./model/gateway.ts";
+export type {
+	CommandContribution,
+	Disposable,
+	PanelContribution,
+	PanelRegion,
+	PluginContext,
+	RouteContribution,
+	RyuHostServices,
+	RyuPlugin,
+	RyuPluginModule,
+	SettingsSectionContribution,
+	StoreSectionContribution,
+	ThemeContribution,
+} from "./plugin/ryu-plugin.ts";
+export { toDisposable } from "./plugin/ryu-plugin.ts";
 export type {
 	AgentCard,
 	AgentManifestOptions,
@@ -91,6 +124,8 @@ export type {
 } from "./runnable/app.ts";
 export { appToolId, defineApp } from "./runnable/app.ts";
 export type {
+	BackgroundClient,
+	BackgroundProcess,
 	DurableClient,
 	EnginesClient,
 	HttpPrimitiveTransportOptions,

package/src/manifest-schema.test.ts

@@ -7,6 +7,7 @@
 import { describe, expect, test } from "bun:test";
 import {
 	CompanionSurfaceSchema,
+	ChatWidgetTemplateSchema,
 	labelImpersonatesSystemChrome,
 	PluginManifestSchema,
 	RunnableMetaSchema,
@@ -22,6 +23,34 @@ function baseManifest(overrides: Record<string, unknown> = {}) {
 	};
 }
 
+test("chat widget templates keep host rendering data-only and forward compatible", () => {
+	const available = ChatWidgetTemplateSchema.safeParse({
+		id: "meetings.chat",
+		title: "Meetings widget",
+		triggers: ["meetings widget"],
+		examples: ["Show my meetings"],
+		backing: { view_id: "surface:meetings" },
+		display_mode: "inline",
+		safe_action_ids: ["refresh"],
+	}).success;
+	const comingSoon = ChatWidgetTemplateSchema.safeParse({
+		id: "future.chat",
+		title: "Future widget",
+		backing: {},
+		display_mode: "compact-future-mode",
+		availability: "coming-soon",
+	}).success;
+	const unsafe = ChatWidgetTemplateSchema.safeParse({
+		id: "future/chat",
+		title: "Unsafe",
+		backing: { tool_id: "future.render" },
+		display_mode: "inline",
+	}).success;
+	expect(available).toBe(true);
+	expect(comingSoon).toBe(true);
+	expect(unsafe).toBe(false);
+});
+
 // ── semver regex ──────────────────────────────────────────────────────────────
 
 describe("PluginManifest version (semver regex)", () => {
@@ -171,7 +200,7 @@ describe("RunnableMetaSchema", () => {
 			id: "x",
 			name: "X",
 			kind: "tool",
-			config: { widget: true, slug: "x__render" },
+			config: { widget: true, slug: "x.render" },
 		});
 		expect(parsed.success).toBe(true);
 		if (!parsed.success) {

package/src/manifest.fixtures.test.ts

@@ -127,18 +127,28 @@ const SDK_KNOWN_KINDS = new Set([
 const VALID_HOOK_PHASES = new Set([
 	"post_assistant_turn",
 	"pre_user_turn",
+	"pre_model_select",
+	"action",
 	"session_start",
 	"stop",
 	"pre_tool_use",
 	"post_tool_use",
+	"tool_result",
 	"subagent_stop",
 	"session_end",
 	"notification",
+	"context",
+	"message_end",
+	"session_before_compact",
+	"session_compact",
+	"model_select",
+	"session_tree",
 	// Kernel lifecycle phases fired by Core's own subsystems (the workflow
 	// executor), not by any app.
 	"workflow_run_started",
 	"workflow_run_finished",
 	"workflow_run_failed",
+	"delegation_lifecycle",
 ]);
 
 /** An **app event** — a phase some app declares in `contributes.hook_events`,
@@ -303,15 +313,15 @@ describe("glob_match oracle (ported from Core)", () => {
 		expect(globMatch("bash", "bashx")).toBe(false);
 	});
 	it("trailing star is a prefix match", () => {
-		expect(globMatch("bash*", "bash__run")).toBe(true);
+		expect(globMatch("bash*", "bash.run")).toBe(true);
 		expect(globMatch("bash*", "sh")).toBe(false);
 	});
 	it("leading star is a suffix match", () => {
-		expect(globMatch("*write", "fs__write")).toBe(true);
+		expect(globMatch("*write", "fs.write")).toBe(true);
 		expect(globMatch("*write", "writer")).toBe(false);
 	});
 	it("double star is a substring match", () => {
-		expect(globMatch("*edit*", "editor__do_edit")).toBe(true);
+		expect(globMatch("*edit*", "editor.do_edit")).toBe(true);
 		expect(globMatch("*edit*", "read_only")).toBe(false);
 	});
 	it("an interior star degrades to an exact-literal match (Core has no compile step)", () => {