@ethisyscore/plugin-ui 1.123.0 → 1.125.0

package/dist/platform-react/index.d.cts

@@ -1087,6 +1087,116 @@ declare function createReactRouterShim(options?: ReactRouterShimOptions): {
  */
 declare function usePluginRealtime(typeCode: string, handler: (payload: unknown) => void): void;
 
+/**
+ * A background operation as a plugin surface sees it through the host's `plugin-operations:*`
+ * tools and the plugin-group push. `kind` and `parentEntityType` are the plugin's own LOCAL names:
+ * the host strips its namespacing before anything reaches a surface.
+ */
+interface PluginOperation {
+    operationId: string;
+    kind: string;
+    status: PluginOperationStatus | string;
+    currentStageCode?: string | null;
+    currentStageLabel?: string | null;
+    stageIndex?: number | null;
+    currentStageOrdinal?: number | null;
+    totalStages?: number | null;
+    stageProgressCurrent?: number | null;
+    stageProgressTotal?: number | null;
+    message?: string | null;
+    errorMessage?: string | null;
+    errorCode?: string | null;
+    parentEntityType?: string | null;
+    parentEntityId?: string | null;
+    retryAttempt?: number;
+    startedUtc?: string | null;
+    completedUtc?: string | null;
+    lastUpdatedUtc?: string;
+    estimatedCompletionUtc?: string | null;
+    eventSequence: number;
+    /** Only populated by `plugin-operations:get` (and so by {@link useBackgroundOperation}). */
+    resultPayloadJson?: string | null;
+}
+/** The statuses the host records. Terminal ones are `Succeeded`, `Failed` and `Cancelled`. */
+type PluginOperationStatus = "Pending" | "Running" | "PausedRateLimited" | "Succeeded" | "Failed" | "Cancelled";
+/** Payload of the `operations.plugin-operation.state-changed` push. */
+interface PluginOperationStateChanged extends Omit<PluginOperation, "resultPayloadJson"> {
+    extensionId: string;
+    previousStatus: string;
+}
+/** Type code of the host's plugin-group push for a plugin's own operation state changes. */
+declare const PLUGIN_OPERATION_STATE_CHANGED = "operations.plugin-operation.state-changed";
+/** The host tools the hooks read through. Declare the ones you use under `McpToolDependencies`. */
+declare const PLUGIN_OPERATION_TOOLS: {
+    readonly get: "plugin-operations:get";
+    readonly listByParent: "plugin-operations:list-by-parent";
+    readonly listActive: "plugin-operations:list-active";
+    readonly latestTerminalByParent: "plugin-operations:latest-terminal-by-parent";
+};
+/** Poll cadence used ONLY when the host supplies no realtime source (matches the host web). */
+declare const OPERATION_FALLBACK_POLL_MS = 8000;
+
+/**
+ * Follows one of this plugin's own background operations by id: its stage, progress, outcome and,
+ * once it has finished, the result payload the plugin recorded.
+ *
+ * Reads through `plugin-operations:get` and then follows the host's push, merging each state change
+ * by `eventSequence` so a late delivery cannot move the operation backwards. When the operation
+ * reaches a terminal state it refetches once, because the push carries no result payload. Polls
+ * every 8 s only when the host supplied no realtime source and the operation is still running.
+ *
+ * The data is `PluginOperation | null`; a missing operation, or one that belongs to another app,
+ * surfaces as the query's error.
+ */
+declare function useBackgroundOperation(operationId: string | null | undefined): _tanstack_react_query.UseQueryResult<NoInfer<PluginOperation | null>, Error>;
+
+/**
+ * Follows this plugin's own background operations against one parent entity (for example every
+ * import of one repository), newest first, at most 50.
+ *
+ * `parentEntityType` is the plugin's LOCAL type name, the one it passed when starting the
+ * operation. Reads through `plugin-operations:list-by-parent`, then merges each pushed state change
+ * for this parent by `eventSequence`, prepending operations that start after the first read. Polls
+ * every 8 s only when the host supplied no realtime source and some operation is still running.
+ */
+declare function useOperationsByParent(parentEntityType: string, parentEntityId: string | null | undefined): _tanstack_react_query.UseQueryResult<NoInfer<PluginOperation[]>, Error>;
+
+/**
+ * The newest FINISHED operation (succeeded, failed or cancelled) of this plugin against one parent
+ * entity, or null: the "last import failed at 10:42" line on a detail page.
+ *
+ * Reads through `plugin-operations:latest-terminal-by-parent` and refetches when a pushed state
+ * change for this parent reaches a terminal status. A finished row cannot change, so there is no
+ * fallback poll; without a realtime source the value refreshes on the query's own refetches.
+ */
+declare function useLatestTerminalOperationByParent(parentEntityType: string, parentEntityId: string | null | undefined): _tanstack_react_query.UseQueryResult<NoInfer<PluginOperation | null>, Error>;
+
+/**
+ * Matches an operation's kind against the plugin's own (unscoped) kind. Mirrors the .NET
+ * `HasKind` / `BackgroundOperationScope.Matches` rule (analyser ECP0016): the host-namespaced
+ * form `p:{extensionId}:` is stripped before comparing, so the check is right whether the value
+ * came from the de-namespacing `plugin-operations:*` tools or anywhere else. Never compare kinds
+ * with `===`.
+ */
+declare function hasKind(operation: {
+    kind: string;
+} | string | null | undefined, unscopedKind: string): boolean;
+/** The parent-type counterpart of {@link hasKind}; strips `po:{scopeHash}:` before comparing. */
+declare function hasParentEntityType(operation: {
+    parentEntityType?: string | null;
+} | string | null | undefined, unscopedParentEntityType: string): boolean;
+
+/** Whether an operation has finished: succeeded, failed or cancelled. */
+declare function isTerminalOperationStatus(status: string | null | undefined): boolean;
+
+/** Query keys for the operation hooks. The plugin's own query client already isolates the realm. */
+declare const pluginOperationKeys: {
+    all: readonly ["plugin-operations"];
+    byId: (operationId: string) => readonly ["plugin-operations", "get", string];
+    byParent: (parentEntityType: string, parentEntityId: string) => readonly ["plugin-operations", "by-parent", string, string];
+    latestTerminalByParent: (parentEntityType: string, parentEntityId: string) => readonly ["plugin-operations", "latest-terminal", string, string];
+};
+
 /**
  * Advisory client-side upload ceiling (UX only). The kernel's streaming route
  * applies the authoritative size cap mid-stream; this default lets the hook
@@ -1458,4 +1568,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useTypedToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, OPERATION_FALLBACK_POLL_MS, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, PLUGIN_OPERATION_STATE_CHANGED, PLUGIN_OPERATION_TOOLS, type PlatformReactOverlayProps, type PluginOperation, type PluginOperationStateChanged, type PluginOperationStatus, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, hasKind, hasParentEntityType, injectPluginStyles, isComponent, isTerminalOperationStatus, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, pluginOperationKeys, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useBackgroundOperation, useCurrency, useLatestTerminalOperationByParent, useManagedLifecycle, useMcpUpload, useOperationsByParent, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.d.ts

@@ -1087,6 +1087,116 @@ declare function createReactRouterShim(options?: ReactRouterShimOptions): {
  */
 declare function usePluginRealtime(typeCode: string, handler: (payload: unknown) => void): void;
 
+/**
+ * A background operation as a plugin surface sees it through the host's `plugin-operations:*`
+ * tools and the plugin-group push. `kind` and `parentEntityType` are the plugin's own LOCAL names:
+ * the host strips its namespacing before anything reaches a surface.
+ */
+interface PluginOperation {
+    operationId: string;
+    kind: string;
+    status: PluginOperationStatus | string;
+    currentStageCode?: string | null;
+    currentStageLabel?: string | null;
+    stageIndex?: number | null;
+    currentStageOrdinal?: number | null;
+    totalStages?: number | null;
+    stageProgressCurrent?: number | null;
+    stageProgressTotal?: number | null;
+    message?: string | null;
+    errorMessage?: string | null;
+    errorCode?: string | null;
+    parentEntityType?: string | null;
+    parentEntityId?: string | null;
+    retryAttempt?: number;
+    startedUtc?: string | null;
+    completedUtc?: string | null;
+    lastUpdatedUtc?: string;
+    estimatedCompletionUtc?: string | null;
+    eventSequence: number;
+    /** Only populated by `plugin-operations:get` (and so by {@link useBackgroundOperation}). */
+    resultPayloadJson?: string | null;
+}
+/** The statuses the host records. Terminal ones are `Succeeded`, `Failed` and `Cancelled`. */
+type PluginOperationStatus = "Pending" | "Running" | "PausedRateLimited" | "Succeeded" | "Failed" | "Cancelled";
+/** Payload of the `operations.plugin-operation.state-changed` push. */
+interface PluginOperationStateChanged extends Omit<PluginOperation, "resultPayloadJson"> {
+    extensionId: string;
+    previousStatus: string;
+}
+/** Type code of the host's plugin-group push for a plugin's own operation state changes. */
+declare const PLUGIN_OPERATION_STATE_CHANGED = "operations.plugin-operation.state-changed";
+/** The host tools the hooks read through. Declare the ones you use under `McpToolDependencies`. */
+declare const PLUGIN_OPERATION_TOOLS: {
+    readonly get: "plugin-operations:get";
+    readonly listByParent: "plugin-operations:list-by-parent";
+    readonly listActive: "plugin-operations:list-active";
+    readonly latestTerminalByParent: "plugin-operations:latest-terminal-by-parent";
+};
+/** Poll cadence used ONLY when the host supplies no realtime source (matches the host web). */
+declare const OPERATION_FALLBACK_POLL_MS = 8000;
+
+/**
+ * Follows one of this plugin's own background operations by id: its stage, progress, outcome and,
+ * once it has finished, the result payload the plugin recorded.
+ *
+ * Reads through `plugin-operations:get` and then follows the host's push, merging each state change
+ * by `eventSequence` so a late delivery cannot move the operation backwards. When the operation
+ * reaches a terminal state it refetches once, because the push carries no result payload. Polls
+ * every 8 s only when the host supplied no realtime source and the operation is still running.
+ *
+ * The data is `PluginOperation | null`; a missing operation, or one that belongs to another app,
+ * surfaces as the query's error.
+ */
+declare function useBackgroundOperation(operationId: string | null | undefined): _tanstack_react_query.UseQueryResult<NoInfer<PluginOperation | null>, Error>;
+
+/**
+ * Follows this plugin's own background operations against one parent entity (for example every
+ * import of one repository), newest first, at most 50.
+ *
+ * `parentEntityType` is the plugin's LOCAL type name, the one it passed when starting the
+ * operation. Reads through `plugin-operations:list-by-parent`, then merges each pushed state change
+ * for this parent by `eventSequence`, prepending operations that start after the first read. Polls
+ * every 8 s only when the host supplied no realtime source and some operation is still running.
+ */
+declare function useOperationsByParent(parentEntityType: string, parentEntityId: string | null | undefined): _tanstack_react_query.UseQueryResult<NoInfer<PluginOperation[]>, Error>;
+
+/**
+ * The newest FINISHED operation (succeeded, failed or cancelled) of this plugin against one parent
+ * entity, or null: the "last import failed at 10:42" line on a detail page.
+ *
+ * Reads through `plugin-operations:latest-terminal-by-parent` and refetches when a pushed state
+ * change for this parent reaches a terminal status. A finished row cannot change, so there is no
+ * fallback poll; without a realtime source the value refreshes on the query's own refetches.
+ */
+declare function useLatestTerminalOperationByParent(parentEntityType: string, parentEntityId: string | null | undefined): _tanstack_react_query.UseQueryResult<NoInfer<PluginOperation | null>, Error>;
+
+/**
+ * Matches an operation's kind against the plugin's own (unscoped) kind. Mirrors the .NET
+ * `HasKind` / `BackgroundOperationScope.Matches` rule (analyser ECP0016): the host-namespaced
+ * form `p:{extensionId}:` is stripped before comparing, so the check is right whether the value
+ * came from the de-namespacing `plugin-operations:*` tools or anywhere else. Never compare kinds
+ * with `===`.
+ */
+declare function hasKind(operation: {
+    kind: string;
+} | string | null | undefined, unscopedKind: string): boolean;
+/** The parent-type counterpart of {@link hasKind}; strips `po:{scopeHash}:` before comparing. */
+declare function hasParentEntityType(operation: {
+    parentEntityType?: string | null;
+} | string | null | undefined, unscopedParentEntityType: string): boolean;
+
+/** Whether an operation has finished: succeeded, failed or cancelled. */
+declare function isTerminalOperationStatus(status: string | null | undefined): boolean;
+
+/** Query keys for the operation hooks. The plugin's own query client already isolates the realm. */
+declare const pluginOperationKeys: {
+    all: readonly ["plugin-operations"];
+    byId: (operationId: string) => readonly ["plugin-operations", "get", string];
+    byParent: (parentEntityType: string, parentEntityId: string) => readonly ["plugin-operations", "by-parent", string, string];
+    latestTerminalByParent: (parentEntityType: string, parentEntityId: string) => readonly ["plugin-operations", "latest-terminal", string, string];
+};
+
 /**
  * Advisory client-side upload ceiling (UX only). The kernel's streaming route
  * applies the authoritative size cap mid-stream; this default lets the hook
@@ -1458,4 +1568,4 @@ interface MenuConfigHostSidebarOptions {
  */
 declare function menuConfigToHostSidebarInput(config: HeaderMenuItem[], opts: MenuConfigHostSidebarOptions): HostSidebarHookInput;
 
-export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, type PlatformReactOverlayProps, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useTypedToolInvokerMap, useView };
+export { type AuthenticatedQueryResult, type CurrencyInfo, type CurrencySelector, DEFAULT_MAX_UPLOAD_BYTES, type DefinePlatformReactPluginOverlayOptions, type DefinePlatformReactPluginPageOptions, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HostSidebarHookInput, HostSidebarInput, type InsetLease, LIST_CURRENCIES_TOOL, type ManagedLifecycle, type McpToolArgs, type McpToolContract, type McpToolContracts, type McpToolResult, type MenuConfigHostSidebarOptions, MissingViewFallback, OPERATION_FALLBACK_POLL_MS, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, type OverlayHostApi, type OverlayHostCapabilities, OverlayHostContext, PLUGIN_OPERATION_STATE_CHANGED, PLUGIN_OPERATION_TOOLS, type PlatformReactOverlayProps, type PluginOperation, type PluginOperationStateChanged, type PluginOperationStatus, type PluginOverlayDefinerConfig, type PluginPageDefinerConfig, PluginPortalScope, type PluginQueryMeta, PluginStyleScope, REPORTING_CURRENCY_TOOL, type ReactRouterShimOptions, SurfaceBaseContext, type SurfaceBaseValue, TemplateContext, type TemplateManifest, type ToHostSidebarInputOptions, ToolInvoker, TypedMcpService, type UseCurrencyResult, type UseMcpUploadOptions, type UseMcpUploadResult, type UseMcpUploadTarget, type ViewComponent, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, hasKind, hasParentEntityType, injectPluginStyles, isComponent, isTerminalOperationStatus, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, pluginOperationKeys, resolveSurfaceBase, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useBackgroundOperation, useCurrency, useLatestTerminalOperationByParent, useManagedLifecycle, useMcpUpload, useOperationsByParent, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useTypedToolInvokerMap, useView };

package/dist/platform-react/index.js

@@ -1,6 +1,6 @@
 import { createContext, useContext, useEffect, useState, useMemo, useRef, createElement, useCallback, useSyncExternalStore } from 'react';
 import * as reactQuery from '@tanstack/react-query';
-import { QueryClient, MutationCache, QueryCache, useQuery, useQueries, QueryClientProvider } from '@tanstack/react-query';
+import { QueryClient, MutationCache, QueryCache, useQuery, useQueries, useQueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { definePlatformReactPage, emitNavigation } from '@ethisyscore/components-react';
 import * as extensionRuntime from '@ethisyscore/extension-runtime/plugin';
 import { useHostIdentity, useMcpTool, useOptionalExtensionRuntimeTransport, usePluginRealtimeSource, useExtensionRuntimeTransport } from '@ethisyscore/extension-runtime/plugin';
@@ -745,6 +745,147 @@ function usePluginRealtime(typeCode, handler) {
     return source.subscribe(typeCode, (payload) => ref.current(payload));
   }, [source, typeCode]);
 }
+
+// src/platform-react/operations/asStateChanged.ts
+function asStateChanged(payload) {
+  if (payload == null || typeof payload !== "object") {
+    return null;
+  }
+  const candidate = payload;
+  return typeof candidate.operationId === "string" && typeof candidate.eventSequence === "number" ? candidate : null;
+}
+
+// src/platform-react/operations/mergeOperation.ts
+function mergeOperation(current, event) {
+  if (current && current.eventSequence >= event.eventSequence) {
+    return current;
+  }
+  const { extensionId: _extensionId, previousStatus: _previousStatus, ...fields } = event;
+  return { ...fields, resultPayloadJson: current?.resultPayloadJson ?? null };
+}
+function mergeIntoList(current, event) {
+  const rows = current ?? [];
+  const index = rows.findIndex((r) => r.operationId === event.operationId);
+  if (index < 0) {
+    return [mergeOperation(null, event), ...rows];
+  }
+  const merged = mergeOperation(rows[index], event);
+  if (merged === rows[index]) {
+    return rows;
+  }
+  const next = rows.slice();
+  next[index] = merged;
+  return next;
+}
+
+// src/platform-react/operations/queryKeys.ts
+var pluginOperationKeys = {
+  all: ["plugin-operations"],
+  byId: (operationId) => ["plugin-operations", "get", operationId],
+  byParent: (parentEntityType, parentEntityId) => ["plugin-operations", "by-parent", parentEntityType, parentEntityId],
+  latestTerminalByParent: (parentEntityType, parentEntityId) => ["plugin-operations", "latest-terminal", parentEntityType, parentEntityId]
+};
+
+// src/platform-react/operations/status.ts
+var TERMINAL = /* @__PURE__ */ new Set(["Succeeded", "Failed", "Cancelled"]);
+function isTerminalOperationStatus(status) {
+  return status != null && TERMINAL.has(status);
+}
+
+// src/platform-react/operations/types.ts
+var PLUGIN_OPERATION_STATE_CHANGED = "operations.plugin-operation.state-changed";
+var PLUGIN_OPERATION_TOOLS = {
+  get: "plugin-operations:get",
+  listByParent: "plugin-operations:list-by-parent",
+  listActive: "plugin-operations:list-active",
+  latestTerminalByParent: "plugin-operations:latest-terminal-by-parent"
+};
+var OPERATION_FALLBACK_POLL_MS = 8e3;
+
+// src/platform-react/operations/useBackgroundOperation.ts
+function useBackgroundOperation(operationId) {
+  const queryClient = useQueryClient();
+  const realtime = usePluginRealtimeSource();
+  const { invoke } = useMcpTool(PLUGIN_OPERATION_TOOLS.get);
+  const query = useQuery({
+    queryKey: pluginOperationKeys.byId(operationId ?? ""),
+    enabled: Boolean(operationId),
+    // Never undefined: TanStack Query rejects an undefined result.
+    queryFn: async () => await invoke({ operationId }) ?? null,
+    refetchInterval: (q) => realtime === null && q.state.data != null && !isTerminalOperationStatus(q.state.data.status) ? OPERATION_FALLBACK_POLL_MS : false
+  });
+  usePluginRealtime(PLUGIN_OPERATION_STATE_CHANGED, (payload) => {
+    const event = asStateChanged(payload);
+    if (!operationId || event?.operationId !== operationId) {
+      return;
+    }
+    const key = pluginOperationKeys.byId(operationId);
+    const before = queryClient.getQueryData(key);
+    const merged = mergeOperation(before, event);
+    queryClient.setQueryData(key, merged);
+    if (merged !== before && isTerminalOperationStatus(merged.status)) {
+      void queryClient.invalidateQueries({ queryKey: key });
+    }
+  });
+  return query;
+}
+
+// src/platform-react/operations/hasKind.ts
+var KIND_SCOPE = /^p:[0-9a-f]{32}:/i;
+var PARENT_SCOPE = /^po:[0-9A-F]{32}:/i;
+function hasKind(operation, unscopedKind) {
+  const kind = typeof operation === "string" ? operation : operation?.kind;
+  return kind != null && kind.replace(KIND_SCOPE, "") === unscopedKind;
+}
+function hasParentEntityType(operation, unscopedParentEntityType) {
+  const parentType = typeof operation === "string" ? operation : operation?.parentEntityType;
+  return parentType != null && parentType.replace(PARENT_SCOPE, "") === unscopedParentEntityType;
+}
+
+// src/platform-react/operations/useOperationsByParent.ts
+function useOperationsByParent(parentEntityType, parentEntityId) {
+  const queryClient = useQueryClient();
+  const realtime = usePluginRealtimeSource();
+  const { invoke } = useMcpTool(
+    PLUGIN_OPERATION_TOOLS.listByParent
+  );
+  const query = useQuery({
+    queryKey: pluginOperationKeys.byParent(parentEntityType, parentEntityId ?? ""),
+    enabled: Boolean(parentEntityId),
+    queryFn: async () => (await invoke({ parentEntityType, parentEntityId }))?.items ?? [],
+    refetchInterval: (q) => realtime === null && (q.state.data ?? []).some((op) => !isTerminalOperationStatus(op.status)) ? OPERATION_FALLBACK_POLL_MS : false
+  });
+  usePluginRealtime(PLUGIN_OPERATION_STATE_CHANGED, (payload) => {
+    const event = asStateChanged(payload);
+    if (!parentEntityId || event == null || event.parentEntityId !== parentEntityId || !hasParentEntityType(event, parentEntityType)) {
+      return;
+    }
+    queryClient.setQueryData(
+      pluginOperationKeys.byParent(parentEntityType, parentEntityId),
+      (current) => mergeIntoList(current, event)
+    );
+  });
+  return query;
+}
+function useLatestTerminalOperationByParent(parentEntityType, parentEntityId) {
+  const queryClient = useQueryClient();
+  const { invoke } = useMcpTool(
+    PLUGIN_OPERATION_TOOLS.latestTerminalByParent
+  );
+  const key = pluginOperationKeys.latestTerminalByParent(parentEntityType, parentEntityId ?? "");
+  const query = useQuery({
+    queryKey: key,
+    enabled: Boolean(parentEntityId),
+    queryFn: async () => (await invoke({ parentEntityType, parentEntityId }))?.item ?? null
+  });
+  usePluginRealtime(PLUGIN_OPERATION_STATE_CHANGED, (payload) => {
+    const event = asStateChanged(payload);
+    if (parentEntityId && event != null && event.parentEntityId === parentEntityId && hasParentEntityType(event, parentEntityType) && isTerminalOperationStatus(event.status)) {
+      void queryClient.invalidateQueries({ queryKey: key });
+    }
+  });
+  return query;
+}
 var DEFAULT_MAX_UPLOAD_BYTES = 30 * 1024 * 1024;
 function useMcpUpload(opts) {
   const transport = useExtensionRuntimeTransport(opts?.transport);
@@ -1252,6 +1393,6 @@ function withActiveNavHref(input, activeNavHref) {
   return { ...input, activeNavHref };
 }
 
-export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, LIST_CURRENCIES_TOOL, MissingViewFallback, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL2 as REPORTING_CURRENCY_TOOL, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, injectPluginStyles, isComponent, isHostChromeCompatible, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, reportHostChromeDiagnostic, resolveActiveNavHref, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useCurrency, useHostSidebarActions, useManagedLifecycle, useMcpUpload, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView, withActiveNavHref };
+export { BaseMcpService, DEFAULT_MAX_UPLOAD_BYTES, EHX_PLUGIN_PORTAL_ATTR, EHX_PLUGIN_PORTAL_CLASS, EHX_PLUGIN_ROOT_CLASS, HOST_CHROME_CONTRACT_VERSION, HostSidebarActionsContext, LIST_CURRENCIES_TOOL, MissingViewFallback, OPERATION_FALLBACK_POLL_MS, ORGANISATION_SETTINGS_URI, OVERLAY_HOST_CONTRACT_VERSION, OverlayHostContext, PLUGIN_OPERATION_STATE_CHANGED, PLUGIN_OPERATION_TOOLS, PluginPortalScope, PluginStyleScope, REPORTING_CURRENCY_TOOL2 as REPORTING_CURRENCY_TOOL, SIDEBAR_MODE, SurfaceBaseContext, TemplateContext, TypedMcpService, buildSurfaceUrl, createPluginOverlayDefiner, createPluginPageDefiner, createPluginQueryClient, createReactRouterShim, createUseView, definePlatformReactPluginOverlay, definePlatformReactPluginPage, deriveHostEntityToken, hasKind, hasParentEntityType, injectPluginStyles, isComponent, isHostChromeCompatible, isTerminalOperationStatus, mcpTool, menuConfigToHostSidebarInput, normaliseSlug, notViaMcp, pluginOperationKeys, reportHostChromeDiagnostic, resolveActiveNavHref, resolveSurfaceBase, setHostChromeDiagnosticSink, surfacePathFor, toHostSidebarInput, useAuthenticatedQueries, useAuthenticatedQuery, useBackgroundOperation, useCurrency, useHostSidebarActions, useLatestTerminalOperationByParent, useManagedLifecycle, useMcpUpload, useOperationsByParent, useOrgFormatSync, useOverlayHost, usePluginRealtime, useReportingCurrencySync, useSurfaceQueryClient, useSurfaceUrl, useToolInvoker, useToolInvokerMap, useTypedToolInvokerMap, useView, withActiveNavHref };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map