@ryuhq/sdk 0.0.5

package/dist/manifest.d.cts

@@ -0,0 +1,355 @@
+import { z } from 'zod';
+
+/**
+ * Ryu SDK manifest types — TypeScript mirror of the Core `plugin_manifest` and
+ * `runnable` schemas (`apps/core/src/plugin_manifest/mod.rs` and
+ * `apps/core/src/runnable/mod.rs`).
+ *
+ * These types must stay in sync with the Rust serde shapes so that a manifest
+ * authored here deserialises cleanly by `PluginManifestLoader::load()` in Core.
+ *
+ * Design note on engine/model fields: every field that holds an engine name,
+ * model id, or provider reference is typed as `string` — never a union of
+ * known provider literals.  A new provider must never require an SDK change.
+ */
+
+/**
+ * The kind of a Runnable. Mirrors `RunnableKind` in
+ * `apps/core/src/runnable/mod.rs`.
+ */
+declare const RunnableKindSchema: z.ZodEnum<{
+    agent: "agent";
+    workflow: "workflow";
+    tool: "tool";
+    skill: "skill";
+    companion: "companion";
+}>;
+type RunnableKind = z.infer<typeof RunnableKindSchema>;
+/**
+ * Kind-agnostic identity snapshot of a Runnable. Mirrors `RunnableMeta` in
+ * `apps/core/src/runnable/mod.rs`.
+ */
+declare const RunnableMetaSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        agent: "agent";
+        workflow: "workflow";
+        tool: "tool";
+        skill: "skill";
+        companion: "companion";
+    }>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type RunnableMeta = z.infer<typeof RunnableMetaSchema>;
+/**
+ * True when a companion `label` impersonates first-party Ryu/system chrome.
+ *
+ * Mirrors Core's `label_impersonates_system_chrome`
+ * (`apps/core/src/plugin_manifest/schema.rs`) and the desktop `validatePluginRoute`
+ * title gate (`apps/desktop/src/contributions/host/rpc.ts`): a plugin's visible
+ * label may not contain `"ryu"` or `"system"` (case-insensitive), so a third-party
+ * companion can never pose as built-in UI. The desktop host's mandatory,
+ * non-removable `"Plugin ·"` attribution prefix is the primary guarantee; this is
+ * defense in depth enforced at the authoring seam so a hostile label is rejected
+ * before `ryu pack`/publish rather than at load.
+ */
+declare function labelImpersonatesSystemChrome(label: string): boolean;
+/**
+ * Optional in-desktop overlay / sidebar panel descriptor. Mirrors
+ * `CompanionSurface` in `apps/core/src/plugin_manifest/mod.rs`.
+ */
+declare const CompanionSurfaceSchema: z.ZodObject<{
+    label: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    shortcut: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CompanionSurface = z.infer<typeof CompanionSurfaceSchema>;
+/**
+ * A server-side chat turn hook. Mirrors `TurnHookContribution` in
+ * `apps/core/src/plugin_manifest/mod.rs`. `code` is a JS body run in the plugin
+ * sandbox with `ctx` + `host` in scope; it returns a directive. Authors usually
+ * build this via `defineTurnHook` rather than writing the string by hand.
+ */
+declare const TurnHookContributionSchema: z.ZodObject<{
+    id: z.ZodString;
+    on: z.ZodDefault<z.ZodString>;
+    code: z.ZodString;
+}, z.core.$strip>;
+type TurnHookContribution = z.infer<typeof TurnHookContributionSchema>;
+/**
+ * One app-widget contribution (Ryu Apps). Binds the render tool that produces the
+ * widget to its `ui://widget/<slug>.html` template. Shape-identical to Core's
+ * `WidgetContribution` (`apps/core/src/plugin_manifest/mod.rs`): built-in apps
+ * serve the HTML from the in-process provider and leave `ui_entry` unset, while a
+ * third-party app authored here sets `ui_entry` so `ryu pack` bundles the source
+ * into the manifest's `ui_code`.
+ */
+declare const WidgetContributionSchema: z.ZodObject<{
+    tool_id: z.ZodString;
+    uri: z.ZodString;
+    ui_entry: z.ZodOptional<z.ZodString>;
+    mime: z.ZodDefault<z.ZodString>;
+    default_display_mode: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type WidgetContribution = z.infer<typeof WidgetContributionSchema>;
+/**
+ * The `config` blob carried by a Ryu App's `kind:"tool"` runnable. Core's strict
+ * `ToolConfig` (`apps/core/src/plugin_manifest/schema.rs`) requires `slug` and
+ * ignores unknown fields on the current shape; the widget flags below are read by
+ * Core's `register_app_tool_with_widget` synthesis path (a separate Core unit) to
+ * rebuild the `_meta` binding, mirroring how the in-process `apps::tools()`
+ * derives `outputTemplate` / `toolInvocation` / `widgetAccessible`.
+ */
+declare const ToolAppConfigSchema: z.ZodObject<{
+    slug: z.ZodString;
+    description: z.ZodString;
+    input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    widget: z.ZodDefault<z.ZodBoolean>;
+    widget_accessible: z.ZodDefault<z.ZodBoolean>;
+    invoking: z.ZodOptional<z.ZodString>;
+    invoked: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ToolAppConfig = z.infer<typeof ToolAppConfigSchema>;
+/**
+ * The `contributes` block. Mirrors `Contributes` in
+ * `apps/core/src/plugin_manifest/mod.rs`. The declarative UI surfaces
+ * (`composer_controls` / `settings_tabs` / `slash_commands`) are passed verbatim
+ * to the desktop renderer, so they are typed loosely here (records).
+ */
+declare const ContributesSchema: z.ZodObject<{
+    turn_hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        on: z.ZodDefault<z.ZodString>;
+        code: z.ZodString;
+    }, z.core.$strip>>>;
+    composer_controls: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    settings_tabs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    slash_commands: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    widgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        tool_id: z.ZodString;
+        uri: z.ZodString;
+        ui_entry: z.ZodOptional<z.ZodString>;
+        mime: z.ZodDefault<z.ZodString>;
+        default_display_mode: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type Contributes = z.infer<typeof ContributesSchema>;
+/**
+ * One optional post-install setup/companion card step surfaced on the
+ * marketplace detail dialog (Phase 1.5 Ryu extension). All fields optional so a
+ * card can be a bare call-to-action or a labelled instruction. `ryu publish`
+ * forwards this into the publish body's `setup` field.
+ */
+declare const SetupStepSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    actionLabel: z.ZodOptional<z.ZodString>;
+    actionUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SetupStep = z.infer<typeof SetupStepSchema>;
+/**
+ * A single plugin-to-plugin dependency edge. Mirrors `AppDependency` in
+ * `apps/core/src/plugin_manifest/mod.rs`.
+ *
+ * `min_version` is snake_case on the wire (Core declares no serde rename) and is
+ * a **minimum**, not a caret range: a bare `"1.2.0"` means `">=1.2.0"`, so an
+ * installed `2.0.0` satisfies it. Explicit comparator syntax (`">=1.2, <2"`,
+ * `"^1.2"`, `"~1.2"`) is honoured verbatim by Core's `parse_min_version`.
+ */
+declare const AppDependencySchema: z.ZodObject<{
+    id: z.ZodString;
+    min_version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type AppDependency = z.infer<typeof AppDependencySchema>;
+/**
+ * A single **capability** edge — the layered, provider-agnostic dependency
+ * (`requires: [{ capability: "rag" }]`) the capability broker resolves to a
+ * concrete provider app at bind time. Mirrors `CapabilityReq` in
+ * `crates/ryu-kernel-contracts/src/manifest.rs` (the canonical contract):
+ * `{ capability, min_version? }`. Distinct from an `apps` edge (which names a
+ * specific plugin id); a `capabilities` edge names an abstract capability and
+ * lets the binding registry pick — or the user override — which enabled provider
+ * serves it. This is the field the composable `defineAgent` slots lower to.
+ */
+declare const CapabilityReqSchema: z.ZodObject<{
+    capability: z.ZodString;
+    min_version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CapabilityReq = z.infer<typeof CapabilityReqSchema>;
+/**
+ * The `requires` block — this plugin's dependencies. Mirrors `Requires` in
+ * `apps/core/src/plugin_manifest/mod.rs`.
+ *
+ * Core resolves `apps` into a topological enable order (`plugins::graph`):
+ * enabling this plugin auto-enables its dependencies first, and disabling a
+ * dependency is REFUSED (409) while an enabled dependent still needs it.
+ *
+ * **Absent = no dependencies** — the backward-compatible default every manifest
+ * predating this field carries.
+ */
+declare const RequiresSchema: z.ZodObject<{
+    apps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        min_version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        capability: z.ZodString;
+        min_version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type Requires = z.infer<typeof RequiresSchema>;
+/**
+ * A host surface a plugin can declare support for via `targets`. Mirrors Core's
+ * `Surface` enum (`#[serde(rename_all = "kebab-case")]`), so these eight tokens
+ * are the exact wire values — also the vocabulary of the `x-ryu-surface` request
+ * header Core filters listings on.
+ */
+declare const SurfaceSchema: z.ZodEnum<{
+    gateway: "gateway";
+    core: "core";
+    desktop: "desktop";
+    island: "island";
+    mobile: "mobile";
+    extension: "extension";
+    web: "web";
+    cli: "cli";
+}>;
+type Surface = z.infer<typeof SurfaceSchema>;
+/**
+ * Full schema for a `plugin.json` Plugin manifest. Mirrors `PluginManifest` in
+ * `apps/core/src/plugin_manifest/mod.rs`.
+ *
+ * Validation rules (matching Core's `PluginManifestLoader`):
+ * - `id` must be non-empty
+ * - `version` must be a valid semver string (MAJOR.MINOR.PATCH)
+ * - `runnables` may be empty for a "surface-only" plugin, but each entry must be
+ *   a valid `RunnableMeta`
+ */
+declare const PluginManifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    ui_code_sha256: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runnables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            agent: "agent";
+            workflow: "workflow";
+            tool: "tool";
+            skill: "skill";
+            companion: "companion";
+        }>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    permission_grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    companion: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        shortcut: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    activation_events: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    contributes: z.ZodOptional<z.ZodObject<{
+        turn_hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            on: z.ZodDefault<z.ZodString>;
+            code: z.ZodString;
+        }, z.core.$strip>>>;
+        composer_controls: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        settings_tabs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        slash_commands: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        widgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            tool_id: z.ZodString;
+            uri: z.ZodString;
+            ui_entry: z.ZodOptional<z.ZodString>;
+            mime: z.ZodDefault<z.ZodString>;
+            default_display_mode: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    requires: z.ZodOptional<z.ZodObject<{
+        apps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            min_version: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            capability: z.ZodString;
+            min_version: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    targets: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        gateway: "gateway";
+        core: "core";
+        desktop: "desktop";
+        island: "island";
+        mobile: "mobile";
+        extension: "extension";
+        web: "web";
+        cli: "cli";
+    }>>>;
+    affiliate: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        rule: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<{
+                flat: "flat";
+                percent: "percent";
+            }>;
+            value: z.ZodNumber;
+            recurring: z.ZodDefault<z.ZodBoolean>;
+            durationMonths: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            fundedBy: z.ZodDefault<z.ZodEnum<{
+                platform: "platform";
+                seller: "seller";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    description: z.ZodOptional<z.ZodString>;
+    tagline: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    homepage: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    category: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
+    iconUrl: z.ZodOptional<z.ZodString>;
+    screenshots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    privacyPolicyUrl: z.ZodOptional<z.ZodString>;
+    termsOfServiceUrl: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    examplePrompts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    setup: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        actionLabel: z.ZodOptional<z.ZodString>;
+        actionUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        actionLabel: z.ZodOptional<z.ZodString>;
+        actionUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+}, z.core.$strip>;
+type PluginManifest = z.infer<typeof PluginManifestSchema>;
+/**
+ * Validate a plugin id with Core's strict reverse-domain, path-traversal-safe
+ * rules. Throws a descriptive `Error` when invalid.
+ */
+declare function validatePluginId(id: string): void;
+/**
+ * Validate a full `plugin.json` string against Core's authoritative rules
+ * (id, semver, per-kind runnable config contracts). Returns the normalized
+ * manifest JSON string, or throws.
+ */
+declare function validateManifestStrict(manifestJson: string): string;
+/**
+ * The Core-derived JSON Schema for a `plugin.json`, as a parsed object. Stays in
+ * lockstep with the Rust types because it is emitted from them.
+ */
+declare function coreManifestJsonSchema(): unknown;
+
+export { type AppDependency, AppDependencySchema, type CapabilityReq, CapabilityReqSchema, type CompanionSurface, CompanionSurfaceSchema, type Contributes, ContributesSchema, type PluginManifest, PluginManifestSchema, type Requires, RequiresSchema, type RunnableKind, RunnableKindSchema, type RunnableMeta, RunnableMetaSchema, type SetupStep, SetupStepSchema, type Surface, SurfaceSchema, type ToolAppConfig, ToolAppConfigSchema, type TurnHookContribution, TurnHookContributionSchema, type WidgetContribution, WidgetContributionSchema, coreManifestJsonSchema, labelImpersonatesSystemChrome, validateManifestStrict, validatePluginId };