@zhama/tego-plugin-sdk 0.0.0-stage → 1.36.0

package/dist/index.d.cts

@@ -0,0 +1,528 @@
+import { P as PluginPublicRoute, a as PluginBackendRuntime, b as PluginScope, c as PluginPartName, d as PluginDeclares, e as PluginConfigSection, f as PluginConfigSectionSummary, T as TegoPluginManifest, L as LocalizedText, g as PluginNavIcon, h as PluginNavEntry, i as PluginAgentReadinessDeclaration } from './manifest-types-DQARCQJt.cjs';
+export { C as CLAW_MANIFEST_FILENAME, E as EMPTY_CONFIG_SECTION_SUMMARY, j as PLUGIN_BACKEND_PLATFORMS, k as PLUGIN_BACKEND_RUNTIMES, l as PLUGIN_CONFIG_SECRET_SENTINEL, m as PLUGIN_CONFIG_SECTIONS, n as PLUGIN_MANIFEST_FILENAME, o as PLUGIN_NAV_ICONS, p as PLUGIN_NAV_ICON_FALLBACK, q as PLUGIN_PART_DEFAULTS, r as PLUGIN_PART_NAMES, s as PluginAgentReadinessItem, t as PluginAgentReadinessResponse, u as PluginAuditDeclarations, v as PluginAuditToolDeclaration, w as PluginBackendLimits, x as PluginBackendPart, y as PluginBackendPlatform, z as PluginClawPart, A as PluginConfigDeclaration, B as PluginConfigFieldSchema, D as PluginConfigFieldType, F as PluginConfigSchema, G as PluginConfigUiHint, H as PluginFrontendPart, I as PluginParts, J as PluginPermissions, K as PluginPublicFrontendPart, M as PluginPublicRouteMethod, N as PluginSchemaRepair, O as PluginWorkDelegationDeclaration, R as ResolvedBackendPart, Q as ResolvedClawPart, S as ResolvedFrontendPart, U as ResolvedPluginParts, V as ResolvedPublicFrontendPart, W as applyConfigDefaults, X as configFieldLabel, Y as declaredPartNames, Z as redactSecrets, _ as resolvePluginDeclares, $ as resolvePluginParts, a0 as resolvePluginScope, a1 as restoreSecrets, a2 as summarizeClawConfig, a3 as summarizeConfigDeclaration } from './manifest-types-DQARCQJt.cjs';
+import { A as AccessCatalog } from './catalog-CSSbrfEf.cjs';
+import 'zod';
+
+/**
+ * Anonymous entry points: how a `publicRoutes` declaration is written, and
+ * how a request is matched against it.
+ *
+ * Shared by the manifest validator, which refuses ambiguous declarations, and
+ * the gateway, which forwards only what matches. One definition, so a route
+ * the validator accepted cannot be matched differently at request time.
+ */
+
+declare const PLUGIN_PUBLIC_ROUTE_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+/**
+ * Where anonymous traffic enters, under the API prefix. The two share a
+ * prefix so a public page can find its API from its own address.
+ */
+declare const PLUGIN_PUBLIC_API_PATH = "/public/plugins/api";
+declare const PLUGIN_PUBLIC_PAGES_PATH = "/public/plugins/pages";
+declare const PLUGIN_AVATAR_PUBLIC_API_PATH = "/public/plugins/avatars/api";
+declare const PLUGIN_AVATAR_PUBLIC_PAGES_PATH = "/public/plugins/avatars/pages";
+/** `GET /public/inspections/:token` — the form the gateway forwards and the backend reads. */
+declare function formatPublicRoute(route: PluginPublicRoute): string;
+interface PublicRouteMatch {
+    /** The declaration, formatted with {@link formatPublicRoute}. */
+    route: string;
+    /** Parameter values, still percent-encoded as they arrived. */
+    params: Record<string, string>;
+}
+/**
+ * The declaration this request matches, or null.
+ *
+ * `path` is the part after the plugin's public prefix, as it appears on the
+ * wire. Exact on method and on the number of segments; a trailing slash or an
+ * empty segment matches nothing.
+ */
+declare function matchPublicRoute(routes: readonly PluginPublicRoute[], method: string, path: string): PublicRouteMatch | null;
+/**
+ * The API prefix a public page should call, derived from the page's own path.
+ *
+ * `/api/v1/tego-os/public/plugins/pages/<tenant>/<plugin>/` →
+ * `/api/v1/tego-os/public/plugins/api/<tenant>/<plugin>`. Null when the page
+ * is not being served from the public pages route — a local dev server, say —
+ * so the caller can fall back to its own configuration.
+ */
+declare function publicApiBaseFromPagePath(pathname: string): string | null;
+
+/**
+ * What an operator is shown before confirming an install.
+ *
+ * Everything here is derived from facts the package already states — the claw
+ * manifest's tool contract, the nav entries, the declares block — and computed
+ * once at upload rather than at each install, so the admin UI never has to
+ * open an archive and the payload can be snapshotted onto the install row.
+ *
+ * That snapshot is the point. Upgrading to a release that adds five tools and
+ * a menu entry is the moment those additions are decided, and the only way to
+ * show "this is more than you accepted last time" is to have kept last time's
+ * answer.
+ *
+ * Disclosure is not itself authorisation. The host separately enforces gated
+ * capabilities such as `directory.read`; database declaration controls schema
+ * provisioning. Frontend code still runs with the shell's own privileges.
+ */
+
+interface PluginDisclosureNavEntry {
+    key: string;
+    /** Resolved against the plugin's own bundle, as everywhere else. */
+    labelKey: string;
+    /**
+     * The menu permission name derived from the entry. Older hosts wrote and
+     * granted it; this one does not, and keeps the field so stored snapshots
+     * keep their shape.
+     */
+    permission: string;
+    /** Host route the entry links to. */
+    path: string;
+}
+interface PluginInstallDisclosure {
+    /** Optional only for snapshots created before host capability disclosure. */
+    requiredPermissions?: string[];
+    /**
+     * External targets the backend may reach through the egress proxy. Optional
+     * only for snapshots created before egress existed; those releases could
+     * reach none.
+     */
+    egress?: string[];
+    /**
+     * Routes anyone can call without signing in, as `METHOD /path`. Optional
+     * only for snapshots created before public routes existed; those releases
+     * had none.
+     */
+    publicRoutes?: string[];
+    /** Absent when there is no backend part, and on snapshots that predate it. */
+    backendRuntime?: PluginBackendRuntime;
+    scope: PluginScope;
+    parts: PluginPartName[];
+    declares: Required<PluginDeclares>;
+    nav: PluginDisclosureNavEntry[];
+    /**
+     * Tool names the claw part adds to every selected avatar's agent.
+     *
+     * From the claw manifest's own `contracts.tools`, which claw already treats
+     * as the extension's declared surface. Empty for a plugin with no claw part,
+     * and also for a claw part that declares no contract — the second case is
+     * indistinguishable here, which is why the UI phrases it as "declares no
+     * tools" rather than "adds nothing".
+     */
+    clawTools: string[];
+    /**
+     * Claw tools with no `audit.tools` wording. The audit trail shows these by
+     * raw tool name and parameters. Absent on snapshots that predate it.
+     */
+    auditUndeclaredTools?: string[];
+    /**
+     * What the operator will be asked to fill in, per section.
+     *
+     * Three summaries rather than one total, because only the backend section's
+     * required fields can hold a container back — the install screen has to be
+     * able to say which of the three is the blocking one.
+     */
+    config: Record<PluginConfigSection, PluginConfigSectionSummary>;
+    /**
+     * Size of the plugin's own role model: permissions it defines (the two the
+     * SDK reserves for managing access are not counted) and the roles it ships.
+     * Absent when the release declares no access catalog.
+     */
+    access?: {
+        permissions: number;
+        roles: number;
+    };
+}
+/**
+ * How `audit.tools` lines up with the tools the claw part registers.
+ *
+ * `undeclared` tools still appear in the audit trail, only by raw name.
+ * `unknown` declarations can never match a call, which is almost always a
+ * renamed tool, so upload refuses them.
+ */
+declare function auditDeclarationGaps(manifest: TegoPluginManifest, clawTools: string[]): {
+    undeclared: string[];
+    unknown: string[];
+};
+/**
+ * @param clawManifest The parsed `openclaw.plugin.json` of the claw part, or
+ *   null when the package ships none.
+ * @param accessCatalog The validated `manifest.access.catalog`, or null when
+ *   the release declares none.
+ */
+declare function buildInstallDisclosure(manifest: TegoPluginManifest, clawManifest?: Record<string, unknown> | null, accessCatalog?: AccessCatalog | null): PluginInstallDisclosure;
+/**
+ * Whether an operator has to fill something in before this release can run.
+ *
+ * Only the backend section counts. A missing frontend or claw setting is a
+ * page or an agent behaving with defaults, which is a choice the plugin made;
+ * a missing backend setting is a process that would start and fail.
+ */
+declare function requiresBackendConfig(disclosure: PluginInstallDisclosure): boolean;
+/** One thing a target release discloses that the accepted snapshot did not. */
+interface PluginDisclosureAddition {
+    kind: 'part' | 'declares' | 'nav' | 'clawTool' | 'configRequired' | 'permission' | 'egress' | 'publicRoute';
+    /**
+     * Part name, declares key, nav key, tool name, `<section>.<field>` for a
+     * newly required setting, or `METHOD /path` for a public route.
+     */
+    value: string;
+}
+/**
+ * What an upgrade adds relative to what was accepted.
+ *
+ * Additions only. A release that drops a tool or a menu entry needs no consent
+ * — the operator is not being asked for anything new — and listing removals
+ * alongside additions in the same confirmation makes the additions harder to
+ * see, which is the one thing the screen exists for.
+ *
+ * A null snapshot means the install predates disclosure, so everything the
+ * target declares is new to the record. Reporting it all is the honest answer:
+ * nobody ever saw a list for this install.
+ */
+declare function diffInstallDisclosure(accepted: PluginInstallDisclosure | null, target: PluginInstallDisclosure): PluginDisclosureAddition[];
+
+/**
+ * The host API contract: which modules the shell shares with plugin frontends,
+ * and how a plugin declares the version it was built against.
+ *
+ * Plugin frontends are built as SystemJS modules with every id below marked
+ * external, so the shell hands them its own singletons at load time. That is
+ * what lets a plugin use `@tego/ui` and share one React instance with the host
+ * instead of shipping — and duplicating — its own copy.
+ *
+ * SystemJS rather than import maps: the app's Vite `build.target` is
+ * `chrome87 / firefox78 / safari14 / edge88`, and import maps need Chrome 89 /
+ * Safari 16.4 / Firefox 108. The shared module *ids* are the contract, so the
+ * loader can be swapped once those targets rise without touching plugins.
+ */
+/**
+ * Version of the shared module surface below.
+ *
+ * Bump the major whenever any shared module's public surface breaks — that
+ * includes upgrading `@tego/ui` or `@tego/chat` across a breaking change.
+ * Installed plugins declaring an incompatible range are then refused at load
+ * time with a readable reason instead of failing inside a hook.
+ *
+ * The minor moves when the surface gains something a plugin can require
+ * without older plugins caring: 1.1.0 added `ChatSurface` and the optional
+ * `metadata` argument to `useTopic().createTopic`, 1.2.0 added
+ * `PluginHostContext.route` and `user.displayName`, 1.3.0 added
+ * `PluginHostContext.events`, 1.4.0 added `PluginHostContext.config`, and
+ * 1.7.0 adds source-paragraph citations without model-transcribed quotes.
+ * 1.5.0 added the backend `directory` capability; 1.6.0 added verified
+ * references to existing platform knowledge through `knowledge`. 1.10.0 adds
+ * python backends, declared egress, public routes with
+ * `PluginHostContext.publicPagesUrl`, and plugin-owned knowledge
+ * collections. 1.12.0 adds browser uploads of large objects: backend
+ * `storage.uploadPath` / `head` / `signedPath` / `get` with `firstBytes`,
+ * resolved in the frontend by `PluginHostContext.hostUrl`. 1.14.0 adds
+ * `PluginHostContext.layout.collapseSidebar` for plugin pages that need the
+ * host navigation sidebar to yield space. A plugin needing a newer surface
+ * declares e.g. `^1.14.0` while one built against `^1.0.0` keeps loading.
+ *
+ * 1.18.0 adds ordinary platform account password resets through the existing\n * accounts.provision capability; platform administrator accounts remain protected.\n *
+ * 1.22.0 adds the manifest `access` field (plugin-owned roles and permissions
+ * through `@tego/plugin-sdk/access`) and `PluginHostApi.tenantId`, which the
+ * access engine needs before any request arrives.
+ *
+ * 1.24.0 adds authorized library reads and revision-checked Office artifact saves
+ * through PluginHostContext.office; all business ownership remains in plugins.
+ *
+ * 1.25.0 adds organization-mapped, multi-target file sync and visible sync locations.
+ *
+ * 1.26.0 adds backend `proactive.emit`: an event that starts the user's
+ * event-triggered scheduled tasks listening for this plugin.
+ *
+ * 1.27.0 adds an optional execution budget to frontend `ai.draft` through
+ * `timeoutMs`, with a separate final-response grace period.
+ *
+ * 1.28.0 adds `@tego/ui` analysis primitives: `ComboChart`, `WaterfallChart`,
+ * `Sparkline`, `DeltaIndicator`, `DateRangePicker` and the `chartScale` axis
+ * helpers behind them.
+ *
+ * 1.29.0 adds backend `mail.send`: email from the person's own connected
+ * mailbox, at most once per idempotency key, with the host's unsubscribe link.
+ *
+ * 1.30.0 adds the manifest `agentReadiness` endpoint and
+ * `workDelegation.settingsRoute`, both read by the employee usage guide.
+ *
+ * 1.31.0 adds `@tego/ui` `InfoTip`: the (?) that holds a label's explanation.
+ *
+ * 1.32.0 adds the `@tego/ui` token readers (`tokenColor`, `contrastRatio` and
+ * the HSL helpers), `useChartTheme` / `buildChartTheme` for ECharts,
+ * `MetricValue`, `PanelHeader`, the `live` `StatusDot` tone, and the shared
+ * Tailwind preset that plugin frontends compile against: the `success`,
+ * `warning`, `info`, `signal` tones with their `-soft` / `-foreground` forms,
+ * surfaces (`raised`, `sunken`, `inset`, `overlay`, `border-strong`),
+ * `chart-1..8`, `action`, `file-*`, the named shadows, durations, easings and
+ * radii, and the `.identity-surface` hue variables.
+ *
+ * 1.33.0 adds `PluginHostContext.delegation`: the host's work delegation
+ * consent dialog and state, plus the manifest `workDelegation.summary`,
+ * `privacyPolicyUrl` and `conversationCapture` it shows.
+ *
+ * 1.34.0 adds backend `attention.request` / `get` / `cancel`: ask a person
+ * to answer, approve or take over, on behalf of the user the plugin acts for.
+ *
+ * 1.35.0 adds `@tego/ui` design token `chatBubbles.user` (the bubble of a
+ * message the viewer sent), and `useResizableWidth` with `ResizeHandle`: a
+ * panel edge the user drags to resize, remembered per viewer.
+ *
+ * 1.36.0 adds write-side knowledge ACL projection: collection read suspension,
+ * identity revision fencing and durable document moves by externalId. Managed
+ * collection reads use existing ACLs; policyScope is deprecated.
+ *
+ * This numbers the *host API surface*, not the `@tego/plugin-sdk` npm package
+ * — the two move on their own clocks. A manifest declares compatibility
+ * against this constant through `hostApiRange`; the SDK's own package version
+ * is a build-time dependency and never reaches a manifest.
+ */
+declare const HOST_API_VERSION = "1.36.0";
+/**
+ * Module specifiers the shell provides to plugin frontends.
+ *
+ * Everything listed here is frozen: its public surface is part of
+ * `HOST_API_VERSION`, so breaking any of it means a major bump that refuses
+ * every installed plugin declaring an older range. That cost is why the list
+ * is the minimum a native-looking page cannot be built without, and why two
+ * things are not on it.
+ *
+ * `@tego/chat/plugin-surface` is a narrow subpath rather than the `@tego/chat`
+ * barrel: plugins need the conversation panel and topic resolution (a
+ * record-page agent panel is the point), but freezing the store, every slice
+ * hook and the pages would stop chat from evolving.
+ *
+ * `@tego/shared` is absent for the same reason, having no subpath narrow
+ * enough to be worth one yet. Its barrel reaches from `HttpClient` and
+ * `TypedStorage` through the license payload and the paywall bridge to the
+ * chat store context — a contract nothing has asked for, over which a plugin
+ * would reach the platform's own APIs directly instead of through
+ * `PluginHostContext.api`, where the namespace and the tenant are enforced.
+ * `cn` — the one thing a plugin composing `@tego/ui` reliably needs — is
+ * re-exported by `@tego/ui` itself. When a plugin page genuinely cannot be
+ * built without something else from shared, add a `plugin-surface` subpath
+ * exporting that and bump the host API version.
+ *
+ * `@tanstack/react-query` is absent for a different reason: sharing it is a
+ * trap. A plugin mounts into its own React root (see `frontend.ts`), so the
+ * shell's `QueryClientProvider` is not an ancestor of anything the plugin
+ * renders, and the first `useQuery` throws "No QueryClient set" — the module
+ * would be shared while the provider that makes it usable is not. A plugin
+ * needing it brings its own client and provider, which costs a few KB and
+ * works. Passing the shell's client through the host context is the
+ * alternative, and it would put React in the SDK's contract to buy a shared
+ * cache nothing needs yet.
+ *
+ * The three React entries are what genuinely cannot be duplicated: two React
+ * instances break hooks on the first render. `react-i18next` is here because
+ * it resolves the default i18next instance the host has already merged the
+ * plugin's own bundle into, so it works without a provider.
+ */
+declare const SHARED_MODULE_IDS: readonly ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "@tego/ui", "react-i18next", "lucide-react", "@tego/chat/plugin-surface"];
+type SharedModuleId = (typeof SHARED_MODULE_IDS)[number];
+/**
+ * Only `^X.Y.Z` and exact `X.Y.Z` are accepted.
+ *
+ * A plugin needs to say no more than "built against 1.2.0, fine with any
+ * later 1.x". Supporting the full npm range grammar would add a dependency and
+ * a set of ambiguities (`||`, `-`, `x` wildcards) that nothing here benefits
+ * from, and the repo already hand-rolls the comparison in `skill-semver.ts`
+ * for the same reason.
+ */
+declare function isValidHostApiRange(range: string): boolean;
+/**
+ * Oldest host version a valid range admits — the version a manifest feature
+ * introduced in must not be newer than this.
+ */
+declare function hostApiRangeMinimum(range: string): string;
+/**
+ * @param range A range accepted by {@link isValidHostApiRange}.
+ * @param hostVersion Usually {@link HOST_API_VERSION}.
+ * @throws Error when the range grammar is unsupported, so an invalid manifest
+ *   fails loudly at validation rather than silently denying every load.
+ */
+declare function satisfiesHostApiRange(range: string, hostVersion: string): boolean;
+
+/**
+ * What the shell learns about a plugin before any of its code runs.
+ *
+ * The sidebar has to render a plugin's entries at startup, which is before the
+ * plugin module is fetched — otherwise every installed plugin would be on the
+ * critical path of the first paint. So the labels, the routes and the version
+ * gate all travel in this payload, and the plugin's own JavaScript is fetched
+ * only when the user opens one of its pages.
+ *
+ * The naming helpers live here rather than on either side because both sides
+ * derive the same strings: the server writes the permission rows at install
+ * time and the shell checks them at render time. Two copies of the format
+ * would drift, and the symptom would be a sidebar entry that is invisible for
+ * reasons no log explains.
+ */
+
+interface InstalledPluginFrontend {
+    /**
+     * SystemJS entry module, as a path under the API root.
+     *
+     * A path rather than a URL because the desktop shell is served from a
+     * custom protocol and its API lives on another origin: only the client
+     * knows which base to join this to. The path carries the version, and
+     * releases are immutable, so the module itself can be cached forever.
+     */
+    entryPath: string;
+    /** Prefix the rest of the frontend part is served under, entry included. */
+    assetBasePath: string;
+    /**
+     * Where this plugin's locale bundles are served, one JSON per tag.
+     *
+     * Resolved by the host because the manifest lets a plugin move the
+     * directory; the shell only ever joins a language tag onto this.
+     */
+    localeBasePath: string;
+    /**
+     * Locale tags the package ships a bundle for.
+     *
+     * The shell fetches only the active language, and falls back to the first
+     * listed tag when the active language is not among them.
+     */
+    locales: string[];
+    /** The plugin's icon in the sidebar. Absent when it declared none. */
+    icon?: PluginNavIcon;
+    nav: PluginNavEntry[];
+    /**
+     * The `frontend` configuration section, with declared defaults applied.
+     *
+     * Travels with discovery rather than being fetched by the plugin, so a
+     * surface has its settings before it renders anything — a plugin whose theme
+     * or endpoint came in a second round trip would flash the wrong one first.
+     *
+     * This section only, and it carries no secrets: a frontend section that
+     * marks a field sensitive is refused at upload, because everything the
+     * browser receives is public.
+     */
+    config: Record<string, unknown>;
+}
+interface InstalledPlugin {
+    pluginId: string;
+    version: string;
+    displayName: LocalizedText;
+    /**
+     * Host API range the release declares, or null for a claw-only plugin that
+     * loads nothing into this process.
+     */
+    hostApiRange: string | null;
+    /** Absent when the plugin ships no frontend part. */
+    frontend?: InstalledPluginFrontend;
+    /** Whether {@link pluginApiPath} reaches a running backend. */
+    hasBackend: boolean;
+    /** What the manifest declares; decides whether {@link avatarIds} applies. */
+    scope: PluginScope;
+    /**
+     * Avatars this viewer can reach that have the plugin installed.
+     *
+     * The sidebar shows an avatar-scoped plugin only while the active avatar is
+     * in this list, so switching avatars changes which plugins are on offer
+     * without another round trip. Always empty for a tenant-scoped plugin,
+     * which belongs to no avatar and is always shown.
+     *
+     * Filtered to what the viewer may see, so it is never a listing of avatars
+     * they have no access to.
+     */
+    avatarIds: string[];
+    /** Declared per-user business readiness endpoint when present. */
+    agentReadiness?: PluginAgentReadinessDeclaration;
+    /** Plugin page where a person delegates work to an employee, when declared. */
+    workDelegationSettingsRoute?: string;
+    /** What the host consent dialog shows; present exactly when the manifest declares `workDelegation`. */
+    workDelegation?: InstalledPluginWorkDelegation;
+}
+interface InstalledPluginWorkDelegation {
+    summary?: LocalizedText;
+    privacyPolicyUrl?: string;
+    conversationCapture?: boolean;
+    /** External targets the backend may reach, from the install disclosure. `*` means any. */
+    egress: string[];
+}
+interface InstalledPluginsResponse {
+    plugins: InstalledPlugin[];
+}
+/**
+ * Locale tags every plugin that ships UI must provide a bundle for.
+ *
+ * The same ten the platform itself serves. A plugin page is not a separate
+ * product: shipping only `en` and `zh-CN` means a Japanese operator sees a
+ * sidebar where most rows are translated and this plugin's are not, which
+ * reads as the platform being half-finished rather than as one package
+ * lagging.
+ *
+ * Enforced at upload, where the author can act on it, rather than left to the
+ * runtime fallback — a fallback hides the gap forever.
+ */
+declare const PLUGIN_SUPPORTED_LOCALES: readonly ["zh-CN", "zh-TW", "en", "ja", "ko", "de", "es", "fr", "it", "pt"];
+type PluginSupportedLocale = (typeof PLUGIN_SUPPORTED_LOCALES)[number];
+/**
+ * i18next namespace a plugin's bundle is registered under.
+ *
+ * Namespaced because plugin bundles are merged into the host's i18n instance,
+ * and a plugin shipping a `common.save` key must not overwrite the host's.
+ *
+ * Dot-separated, not colon-separated: i18next splits `ns:key` on the first
+ * colon, so a namespace containing one would swallow part of the key. A plugin
+ * id may itself contain dots, which is harmless — only the colon matters.
+ */
+declare function pluginI18nNamespace(pluginId: string): string;
+/** Fully qualified `ns:key` for one of a plugin's own translation keys. */
+declare function pluginI18nKey(pluginId: string, labelKey: string): string;
+/** The `system_menus.key` older hosts derived for one nav entry. */
+declare function pluginMenuKey(pluginId: string, navKey: string): string;
+/**
+ * Longest a derived permission name may be.
+ *
+ * Older hosts write the name into `permissions.name` and `system_menus.key`,
+ * both `varchar(100)`, and the id and nav key limits allow far more than that
+ * between them. A pair that overflows is refused at upload, with a message
+ * naming the two fields that are too long together, so a manifest that
+ * validates also installs on the older hosts its `hostApiRange` admits.
+ */
+declare const MAX_PLUGIN_MENU_PERMISSION_LENGTH = 100;
+/** Route prefix one plugin's frontend owns. */
+declare function pluginBasePath(pluginId: string): string;
+/**
+ * Route for one nav entry a plugin contributes.
+ *
+ * `entryPath` is the plugin's own internal route, so `/deals` for plugin
+ * `acme-crm` becomes `/p/acme-crm/deals`. Every plugin page therefore lives
+ * under a prefix the host owns, which is what lets a single catch-all route
+ * serve all of them.
+ */
+declare function pluginNavPath(pluginId: string, entryPath?: string): string;
+/**
+ * API-root-relative path for a call into one plugin's own backend part.
+ *
+ * Derived here, next to the route helpers, because the server mounts the
+ * gateway at this prefix and the shell has to hit the same one. When the shell
+ * owned its own copy it built `plugins/<id>/api/...` — the older proxy's
+ * prefix — and every plugin backend call 404'd on a plugin the platform had no
+ * reason to know about.
+ *
+ * The prefix is the host's, so a plugin cannot reach another plugin's backend
+ * or the platform API by writing a path: a crafted one 404s inside its own
+ * namespace.
+ */
+declare function pluginApiPath(pluginId: string, path?: string): string;
+/**
+ * Pick one string out of a possibly per-locale display value.
+ *
+ * Used where a single string is unavoidable — a database column, a log line —
+ * not for rendering, which goes through i18n.
+ */
+declare function localizedTextToString(value: LocalizedText, preferred?: string): string;
+/**
+ * The `menu.` permission name older hosts derived for one nav entry.
+ *
+ * The host no longer writes plugin menus or permissions — access follows the
+ * AI employees a plugin is installed on — but the name is still what the
+ * manifest length check and install disclosure snapshots are built from.
+ */
+declare function pluginMenuPermission(pluginId: string, navKey: string): string;
+
+export { HOST_API_VERSION, type InstalledPlugin, type InstalledPluginFrontend, type InstalledPluginWorkDelegation, type InstalledPluginsResponse, LocalizedText, MAX_PLUGIN_MENU_PERMISSION_LENGTH, PLUGIN_AVATAR_PUBLIC_API_PATH, PLUGIN_AVATAR_PUBLIC_PAGES_PATH, PLUGIN_PUBLIC_API_PATH, PLUGIN_PUBLIC_PAGES_PATH, PLUGIN_PUBLIC_ROUTE_METHODS, PLUGIN_SUPPORTED_LOCALES, PluginAgentReadinessDeclaration, PluginBackendRuntime, PluginConfigSection, PluginConfigSectionSummary, PluginDeclares, type PluginDisclosureAddition, type PluginDisclosureNavEntry, type PluginInstallDisclosure, PluginNavEntry, PluginNavIcon, PluginPartName, PluginPublicRoute, PluginScope, type PluginSupportedLocale, type PublicRouteMatch, SHARED_MODULE_IDS, type SharedModuleId, TegoPluginManifest, auditDeclarationGaps, buildInstallDisclosure, diffInstallDisclosure, formatPublicRoute, hostApiRangeMinimum, isValidHostApiRange, localizedTextToString, matchPublicRoute, pluginApiPath, pluginBasePath, pluginI18nKey, pluginI18nNamespace, pluginMenuKey, pluginMenuPermission, pluginNavPath, publicApiBaseFromPagePath, requiresBackendConfig, satisfiesHostApiRange };