@ryuhq/sdk 0.1.14 → 0.2.2

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.
 	 *
@@ -356,7 +374,7 @@ export interface PluginManifest {
 	permission_levels?: PermissionLevel[];
 	/**
 	 * **Unified, deny-by-default runtime permission set** — the single typed
-	 * grammar (`{fs, child_process, network, tool}`) Core lowers to every sandbox
+	 * grammar (`{fs, child_process, run, network, tool}`) Core lowers to every sandbox
 	 * backend (wasmtime WASI preopens, Docker `--mount`/`--network` flags, Deno
 	 * `--allow-*` flags). Absent = **deny-all** (the default for every manifest
 	 * predating this field), so an app that declares nothing keeps today's exact
@@ -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,9 @@ 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`, `selection_actions`, `context_menu_items`,
+ * `agent_edit_panels`).
  *
  * # Extending
  *
@@ -563,7 +596,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 +607,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 +795,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
@@ -883,6 +962,16 @@ export interface Contributes {
 	 * Gateway policies the plugin contributes (referenced by runnable id).
 	 */
 	policies?: ContributionId[];
+	/**
+	 * Buttons the plugin contributes to the floating text-selection toolbar.
+	 * This is the bridge between enabled apps/plugins and shared chat blocks:
+	 * Core validates and tags the declaration, while the desktop owns the
+	 * rendered toolbar and dispatches the selected text. A selection action may
+	 * either name a granted `capability` or provide a host-owned `args.dispatch`
+	 * (for example, a first-party shell action such as Side Chat). Self-contained
+	 * + opaque for the same forward-compatibility reason as `message_actions`.
+	 */
+	selection_actions?: SelectionActionContribution[];
 	/**
 	 * Declarative settings tabs the plugin contributes (model pickers, text
 	 * fields bound to preference keys). Served + rendered the same way.
@@ -915,7 +1004,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 +1147,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 +1421,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`]).
  *
@@ -1568,6 +1731,49 @@ export interface PiExtensionContribution {
 	 */
 	id: string;
 }
+/**
+ * One button a plugin contributes to the floating text-selection toolbar (see
+ * [`Contributes::selection_actions`]).
+ *
+ * `capability` is optional because a host-owned renderer can use an opaque
+ * `args.dispatch` bridge instead. The desktop never executes manifest code: it
+ * only renders this label and forwards the selected text to the owning host
+ * handler.
+ */
+export interface SelectionActionContribution {
+	/**
+	 * Static renderer/dispatch arguments. The selected text is supplied by the
+	 * host at click time and is never serialized into the manifest.
+	 */
+	args?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Optional granted capability for a plugin-owned dispatch.
+	 */
+	capability?: string | null;
+	/**
+	 * Optional glyph id resolved by the shell's icon primitive.
+	 */
+	icon?: string | null;
+	/**
+	 * Stable id for this action within the plugin.
+	 */
+	id: string;
+	/**
+	 * Render mode. The current desktop renders `"button"`; this remains open
+	 * so newer shells can add a mode without making older cores reject it.
+	 */
+	kind: string;
+	/**
+	 * Accessible label shown in the selection toolbar.
+	 */
+	label: string;
+	/**
+	 * Sort position among contributed selection actions (ascending).
+	 */
+	order?: number | null;
+}
 /**
  * One **settings tab** a plugin contributes (see [`Contributes::settings_tabs`]).
  *
@@ -1696,6 +1902,13 @@ export interface SettingsFieldContribution {
  * buttons (e.g. Memory) to the owning app.
  */
 export interface SidebarButtonContribution {
+	/**
+	 * Optional mount context passed to the owning Companion when the button opens it.
+	 * The host applies this only to the button's own app surface.
+	 */
+	context?: {
+		[k: string]: unknown;
+	} | null;
 	/**
 	 * Optional glyph id resolved by the shell's Icon primitive.
 	 */
@@ -1746,7 +1959,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 +2139,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 +2160,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 +2212,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 +2387,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 +2445,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
@@ -2289,6 +2538,12 @@ export interface PermissionSet {
 	 * Deno's `--allow-net` supports). See [`NetworkPermission`].
 	 */
 	network?: boolean | string[];
+	/**
+	 * Executable names sandboxed code may spawn when [`Self::child_process`] is
+	 * true. Core lowers this to Deno's scoped `--allow-run=<name,...>` list in
+	 * addition to declared capability shims. Empty grants no arbitrary binary.
+	 */
+	run?: string[];
 	/**
 	 * **Declaration-only** in v1: the registry tool ids this plugin's sandboxed
 	 * code may call through the stdio `tools.*` bridge. Tools are brokered over
@@ -2413,7 +2668,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 +2686,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 +2719,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 +2769,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 +3056,20 @@ 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).
+	 * Destination directory relative to the runtime's `assets/` directory
+	 * (e.g. `"models/hf"`). The fetched file lands at
+	 * `<runtime>/assets/<dest_under_runtime>/<filename>`. Must be a
+	 * traversal-safe relative path (no `..`, not absolute). The old
+	 * `dest_under_ryu` spelling is accepted as a wire alias but is never
+	 * resolved against the shared Core data directory.
 	 */
-	dest_under_ryu: string;
+	dest_under_runtime: string;
 	/**
 	 * Optional SHA-256 for checksum verification (direct-URL assets).
 	 */
@@ -2908,6 +3166,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 +3186,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 +3214,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;
 }
@@ -3013,6 +3299,13 @@ export interface RouteSpec {
 	 * webhook whose external caller cannot hold the node token).
 	 */
 	auth?: "protected" | "public";
+	/**
+	 * Optional HTTP method selector for this path (canonical uppercase such as
+	 * `GET` or `POST`). Absent preserves the legacy behavior and matches every
+	 * method. Declare one row per method when reads and writes share a path but
+	 * require different permission levels.
+	 */
+	method?: string | null;
 	/**
 	 * Path pattern for the sub-path after `/api/ext/<plugin_id>` (must start with
 	 * `/`). Supports `:param` (matches one non-empty segment) and a trailing

package/src/index.ts

@@ -37,10 +37,16 @@ export type {
 	CapabilityReq,
 	CompanionSurface,
 	Contributes,
+	McpServerAuth,
+	McpServerDecl,
 	PluginManifest,
 	Requires,
 	RunnableKind,
 	RunnableMeta,
+	SlashCommandArgument,
+	SlashCommandContribution,
+	SlashCommandCustomOption,
+	SlashCommandOption,
 	Surface,
 	ToolAppConfig,
 	TurnHookContribution,
@@ -51,16 +57,36 @@ export {
 	CapabilityReqSchema,
 	CompanionSurfaceSchema,
 	coreManifestJsonSchema,
+	McpServerAuthSchema,
+	McpServerDeclSchema,
 	PluginManifestSchema,
 	RequiresSchema,
 	RunnableKindSchema,
 	RunnableMetaSchema,
+	SlashCommandArgumentSchema,
+	SlashCommandContributionSchema,
+	SlashCommandCustomOptionSchema,
+	SlashCommandOptionSchema,
 	SurfaceSchema,
 	ToolAppConfigSchema,
 	validateManifestStrict,
 	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 +100,29 @@ 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 {
+	ActionAnnotations,
+	ActionEffect,
+	ActionManifestOptions,
+	ActionOptions,
+	ActionRunnable,
+} from "./runnable/action.ts";
+export { defineAction } from "./runnable/action.ts";
 export type {
 	AgentCard,
 	AgentManifestOptions,
@@ -91,6 +140,8 @@ export type {
 } from "./runnable/app.ts";
 export { appToolId, defineApp } from "./runnable/app.ts";
 export type {
+	BackgroundClient,
+	BackgroundProcess,
 	DurableClient,
 	EnginesClient,
 	HttpPrimitiveTransportOptions,
@@ -105,6 +156,7 @@ export type {
 	RealtimeClient,
 	RealtimeSubscription,
 	RyuPrimitives,
+	StorageClient,
 	SttClient,
 	TtsClient,
 } from "./runnable/primitives.ts";
@@ -121,6 +173,7 @@ export type {
 export type { SkillOptions } from "./runnable/skill.ts";
 export { defineSkill } from "./runnable/skill.ts";
 export type {
+	InlineToolManifestOptions,
 	JsonSchemaProperty,
 	ToolOptions,
 	ToolRunnable,