@wordrhyme/plugin 0.1.0-alpha.5 → 0.1.0-alpha.6

package/dist/index.d.ts

@@ -1,14 +1,14 @@
-import { a as PluginContext, c as PluginLogger } from './types-8P7XyoyQ.js';
-export { A as ApiPayload, E as EAuthModel, d as EAuthProvider, e as EAuthRefreshInput, f as EAuthRefreshResult, g as EAuthStatus, h as EAuthTokenResult, i as EAuthUpsertInput, j as EAuthUse, k as HookAbortError, H as HookContext, l as HookEmitOptions, b as HookHandlerOptions, m as HookPriority, n as HookTransaction, M as MARKETPLACE_PUBLISH_AUTH_METHODS, o as MarketplaceAttestationTargetV1, p as MarketplaceExecutionErrorCode, q as MarketplaceExecutionFailureCode, r as MarketplaceOrganizationExecutionV1, s as MarketplacePlatformReadAction, t as MarketplacePublishActor, u as MarketplacePublishAuthMethod, v as MarketplacePublisherAction, w as MarketplaceRegistrySigningCapability, O as OpaquePublisherCandidateV1, x as PluginApisCapability, y as PluginArtifactCapability, z as PluginAssetCapability, B as PluginAssetCreateOptions, C as PluginAssetInfo, D as PluginAssetQuery, F as PluginAssetUpdateData, G as PluginAssetVariant, I as PluginCurrencyCapability, J as PluginEAuthCapability, K as PluginEntityExtensionCapability, L as PluginEntityExtensionFilter, N as PluginFileCapability, Q as PluginFileInfo, R as PluginFileQuery, S as PluginFileUploadInput, T as PluginHookCapability, U as PluginJobOptions, V as PluginJobStatus, W as PluginMediaCapability, P as PluginMediaInfo, X as PluginMediaQuery, Y as PluginMediaUpdateData, Z as PluginMediaUploadInput, _ as PluginMediaVariant, $ as PluginMetricsAllowedLabels, a0 as PluginMetricsCapability, a1 as PluginNotificationActor, a2 as PluginNotificationCapability, a3 as PluginNotificationChannel, a4 as PluginNotificationEvent, a5 as PluginNotificationInput, a6 as PluginNotificationResult, a7 as PluginNotificationSendParams, a8 as PluginNotificationSendResult, a9 as PluginNotificationTarget, aa as PluginNotificationTemplate, ab as PluginOrganizationProvisioningCapability, ac as PluginPaginatedResult, ad as PluginPermissionCapability, ae as PluginPermissionCheckContext, af as PluginPermissionDef, ag as PluginQueueCapability, ah as PluginScopedDb, ai as PluginSettingEntry, aj as PluginSettingOptions, ak as PluginSettingsCapability, al as PluginStorageCapability, am as PluginStorageProvider, an as PluginStorageProviderConfig, ao as PluginStorageProviderInfo, ap as PluginStorageUploadInput, aq as PluginStorageUploadResult, ar as PluginTraceCapability, as as PluginUsageCapability, at as PluginWebCapability, au as ReadonlyPluginScopedDb, av as WebPluginHead, aw as WebPluginHeadLink, ax as WebPluginRouteHandler, ay as WebPluginRouteRequest, az as WebPluginRouteResult, aA as WebPluginSiteInfo, aB as WebPluginTenantInfo, aC as WebSlotExtensionQuery, aD as WebSlotQueryResult, aE as WebSlotRemoteExtension, aF as WebSlotRenderOptions, aG as WebSlotRenderRequest, aH as WebSlotRenderResult, aI as WebSlotRenderer } from './types-8P7XyoyQ.js';
+import { a as PluginContext, d as PluginLogger, W as WebPluginSiteInfo } from './types-oPAs313y.js';
+export { A as ActionContractMeta, e as ActionDescriptor, f as ActionInvokeRequest, g as AgentToolDescriptor, h as AiAliasDescriptor, i as AiBudget, j as AiModelCatalog, k as AiModelHint, l as AiModelListRequest, m as AiModelOption, n as AiObjectRequest, o as AiObjectResult, p as AiObjectSchema, q as AiRuntimeHandler, r as AiRuntimeHost, s as AiRuntimeInvocation, t as AiStreamEvent, u as AiTextRequest, v as AiTextResult, w as AiUsage, x as AiUsageAuthorization, y as AiUsageObservation, z as ApiPayload, E as EAuthModel, B as EAuthProvider, C as EAuthRefreshInput, D as EAuthRefreshResult, F as EAuthStatus, G as EAuthTokenResult, I as EAuthUpsertInput, J as EAuthUse, K as HookAbortError, H as HookContext, L as HookEmitOptions, b as HookHandlerOptions, M as HookPriority, c as HookTransaction, N as MARKETPLACE_PUBLISH_AUTH_METHODS, O as MarketplaceAttestationTargetV1, Q as MarketplaceExecutionErrorCode, R as MarketplaceExecutionFailureCode, S as MarketplaceOrganizationExecutionV1, T as MarketplacePlatformReadAction, U as MarketplacePublishActor, V as MarketplacePublishAuthMethod, X as MarketplacePublisherAction, Y as MarketplaceRegistrySigningCapability, Z as OpaquePublisherCandidateV1, _ as PluginActionInvokerCapability, $ as PluginAgentCapability, a0 as PluginAiCapability, a1 as PluginAiRuntimeCapability, a2 as PluginApisCapability, a3 as PluginArtifactCapability, a4 as PluginAssetCapability, a5 as PluginAssetCreateOptions, a6 as PluginAssetInfo, a7 as PluginAssetQuery, a8 as PluginAssetUpdateData, a9 as PluginAssetVariant, aa as PluginCurrencyCapability, ab as PluginEAuthCapability, ac as PluginEntityExtensionCapability, ad as PluginEntityExtensionFilter, ae as PluginFileCapability, af as PluginFileInfo, ag as PluginFileQuery, ah as PluginFileUploadInput, ai as PluginHookCapability, aj as PluginJobOptions, ak as PluginJobStatus, al as PluginMediaCapability, P as PluginMediaInfo, am as PluginMediaQuery, an as PluginMediaUpdateData, ao as PluginMediaUploadInput, ap as PluginMediaVariant, aq as PluginMetricsAllowedLabels, ar as PluginMetricsCapability, as as PluginNotificationActor, at as PluginNotificationCapability, au as PluginNotificationChannel, av as PluginNotificationEvent, aw as PluginNotificationInput, ax as PluginNotificationResult, ay as PluginNotificationSendParams, az as PluginNotificationSendResult, aA as PluginNotificationTarget, aB as PluginNotificationTemplate, aC as PluginOrganizationProvisioningCapability, aD as PluginPaginatedResult, aE as PluginPermissionCapability, aF as PluginPermissionCheckContext, aG as PluginPermissionDef, aH as PluginQueueCapability, aI as PluginScopedDb, aJ as PluginSettingEntry, aK as PluginSettingOptions, aL as PluginSettingsCapability, aM as PluginStorageCapability, aN as PluginStorageProvider, aO as PluginStorageProviderConfig, aP as PluginStorageProviderInfo, aQ as PluginStorageUploadInput, aR as PluginStorageUploadResult, aS as PluginTraceCapability, aT as PluginUsageCapability, aU as PluginWebCapability, aV as ReadonlyPluginScopedDb, aW as WebPluginHead, aX as WebPluginHeadLink, aY as WebPluginRouteHandler, aZ as WebPluginRouteRequest, a_ as WebPluginRouteResult, a$ as WebPluginTenantInfo, b0 as WebSlotExtensionQuery, b1 as WebSlotQueryResult, b2 as WebSlotRemoteExtension, b3 as WebSlotRenderOptions, b4 as WebSlotRenderRequest, b5 as WebSlotRenderResult, b6 as WebSlotRenderer } from './types-oPAs313y.js';
 import { z } from 'zod';
 export { CurrencyInfo, DEFAULT_CURRENCY, FormatPriceOptions, GlobalizationState, I18nTextField, LanguageInfo, PriceFormatter, TextDirection, TranslationMessages, Translator, bankersRound, buildGlobalizationUrl, convertCurrency, createPriceFormatter, createTranslator, findCurrency, formatCurrencyAmount, formatPrice, fromCents, getBaseCurrency, getI18nText, getTextDirection, normalizeCurrencies, normalizeCurrencyInfo, resolveCurrencyInfo, toCents, withGlobalizationHelpers } from './globalization.js';
 export { CLIENT_TIME_ZONE_COOKIE, CLIENT_TIME_ZONE_HEADER, DEFAULT_TIME_ZONE, DateFilterInput, DateFilterRange, DateRangeResolver, FormatDateTimeOptions, canonicalizeTimeZone, formatDateTime, getClientTimeZone, getSupportedTimeZones, isValidTimeZone, normalizeTimeZone, resolveDateFilterRange, toDateTimeLocal, toUtcDateTime, toUtcDayRange } from './time.js';
-import { P as PluginManifest } from './manifest-CPSCN_Ft.js';
-export { A as AdminTour, b as AdminTourPlacement, c as AdminTourStep, d as AggregationStrategy, e as AutoCrudAction, f as AutoCrudActionZone, g as AutoCrudActions, h as EntityExtension, i as EntityExtensionCrudConfig, a as EntityExtensionField, E as EntityExtensionFieldType, j as EntityExtensionSlot, k as EntityExtensionUse, l as PluginCapabilities, m as PluginNotificationType, n as PluginStatus, W as WebDesignAction, o as WebDesignBlock, p as WebDesignDataSource, q as WebDesignSlot, r as WebDesignSurface, s as WebDesignTemplate, t as WebExtension, u as WebExtensionQuery, v as WebExtensionTarget, w as WebPluginRoute, x as WebSsrContractVersion, y as WebSurface, z as adminExtensionSchema, B as adminTourPlacementSchema, C as adminTourSchema, D as adminTourStepSchema, F as autoCrudActionSchema, G as autoCrudActionZoneSchema, H as autoCrudActionsSchema, I as autoCrudDataSourceSchema, J as autoCrudFieldConfigSchema, K as autoCrudFieldOptionSchema, L as dashboardTargetSchema, M as entityExtensionCrudConfigSchema, N as entityExtensionFieldSchema, O as entityExtensionSchema, Q as entityExtensionSlotSchema, R as entityExtensionUseSchema, S as navGroupTargetSchema, T as navTargetSchema, U as pluginI18nSchema, V as pluginManifestSchema, X as pluginUsesSchema, Y as routeTargetSchema, Z as settingsTargetSchema, _ as targetSchema, $ as webDesignActionSchema, a0 as webDesignBlockSchema, a1 as webDesignDataSourceSchema, a2 as webDesignSlotSchema, a3 as webDesignSurfaceSchema, a4 as webDesignTemplateSchema, a5 as webExtensionQuerySchema, a6 as webExtensionSchema, a7 as webExtensionTargetSchema, a8 as webPluginRouteSchema, a9 as webSsrContractVersionSchema, aa as webSurfaceSchema } from './manifest-CPSCN_Ft.js';
+import { P as PluginManifest } from './manifest-zSGjFCcJ.js';
+export { A as AdminTour, b as AdminTourPlacement, c as AdminTourStep, d as AggregationStrategy, e as AutoCrudAction, f as AutoCrudActionZone, g as AutoCrudActions, h as EntityExtension, i as EntityExtensionCrudConfig, a as EntityExtensionField, E as EntityExtensionFieldType, j as EntityExtensionSlot, k as EntityExtensionUse, l as PluginCapabilities, m as PluginNotificationType, n as PluginStatus, W as WebDesignAction, o as WebDesignBlock, p as WebDesignDataSource, q as WebDesignSlot, r as WebDesignSurface, s as WebDesignTemplate, t as WebExtension, u as WebExtensionQuery, v as WebExtensionTarget, w as WebPluginRoute, x as WebSsrContractVersion, y as WebSurface, z as adminExtensionSchema, B as adminTourPlacementSchema, C as adminTourSchema, D as adminTourStepSchema, F as autoCrudActionSchema, G as autoCrudActionZoneSchema, H as autoCrudActionsSchema, I as autoCrudDataSourceSchema, J as autoCrudFieldConfigSchema, K as autoCrudFieldOptionSchema, L as dashboardTargetSchema, M as entityExtensionCrudConfigSchema, N as entityExtensionFieldSchema, O as entityExtensionSchema, Q as entityExtensionSlotSchema, R as entityExtensionUseSchema, S as navGroupTargetSchema, T as navTargetSchema, U as pluginI18nSchema, V as pluginManifestSchema, X as pluginUsesSchema, Y as routeTargetSchema, Z as settingsTargetSchema, _ as targetSchema, $ as webDesignActionSchema, a0 as webDesignBlockSchema, a1 as webDesignDataSourceSchema, a2 as webDesignSlotSchema, a3 as webDesignSurfaceSchema, a4 as webDesignTemplateSchema, a5 as webExtensionQuerySchema, a6 as webExtensionSchema, a7 as webExtensionTargetSchema, a8 as webPluginRouteSchema, a9 as webSsrContractVersionSchema, aa as webSurfaceSchema } from './manifest-zSGjFCcJ.js';
 export { c as PLUGIN_ARCHIVE_MEDIA_TYPE, d as PLUGIN_RELEASE_SCHEMA_VERSION, e as PluginRegistryCatalog, f as PluginRegistryRelease, P as PluginRelease, g as PluginReleaseFile, h as PluginSignature, i as REGISTRY_CATALOG_SIGNATURE_DOMAIN, b as RegistryCatalogPageEnvelope, R as RegistryReleaseEnvelope, a as RegistrySignature, j as canonicalRegistryCatalogPageEnvelope, k as canonicalRegistryReleaseEnvelope, p as pluginArchivePathSchema, l as pluginRegistryCatalogSchema, m as pluginRegistryReleaseSchema, n as pluginReleaseFileSchema, o as pluginReleaseSchema, q as pluginSignatureSchema, r as registryCatalogPageEnvelopeSchema, s as registryCatalogPageSignaturePayload, t as registryCatalogReleasesPayload, u as registryReleaseEnvelopeSchema, v as registryReleaseSignaturePayload, w as registrySignatureSchema } from './release-CyapqJ3z.js';
-export { E as ENTITY_EXTENSION_VALUES_SAVE_HOOK_ID, a as EXTENSION_PROJECT_SAVE_HOOK_ID, b as EntityExtensionProjectionValue, c as EntityExtensionValueSaveHandler, d as EntityExtensionValueSavePayload, e as EntityExtensionValueSaveResult, f as entityExtensions, r as registerEntityExtensionValueSaver } from './entity-extensions-B5BbZH-m.js';
+export { E as ENTITY_EXTENSION_VALUES_SAVE_HOOK_ID, a as EXTENSION_PROJECT_SAVE_HOOK_ID, b as EntityExtensionProjectionValue, c as EntityExtensionValueSaveHandler, d as EntityExtensionValueSavePayload, e as EntityExtensionValueSaveResult, f as entityExtensions, r as registerEntityExtensionValueSaver } from './entity-extensions-D09rvNgi.js';
 export { getPluginDevPort, getPluginDevRemoteEntry, getPluginMfName } from './dev-utils.js';
-export { D as DashboardTarget, E as ExtensionComponentMap, G as GenericTarget, N as NavGroupTarget, a as NavTarget, R as RouteTarget, S as SettingsTarget, b as SlotContext, T as Target, c as ToolbarHandlerMap, U as UIExtensionDef, d as dashboardExtension, e as defineExtension, m as multiSlotExtension, n as navExtension, r as routeExtension, s as settingsExtension } from './client-WXWbuuvd.js';
+export { D as DashboardTarget, E as ExtensionComponentMap, G as GenericTarget, N as NavGroupTarget, a as NavTarget, R as RouteTarget, S as SettingsTarget, b as SlotContext, T as Target, c as ToolbarHandlerMap, U as UIExtensionDef, d as dashboardExtension, e as defineExtension, m as multiSlotExtension, n as navExtension, r as routeExtension, s as settingsExtension } from './client-BJju2aT7.js';
 import 'decimal.js';
 
 declare const MARKETPLACE_PUBLISH_SOURCES: readonly ["web", "cli", "github-actions"];
@@ -313,4 +313,343 @@ declare function requirePermission(ctx: PluginContext, capability: string): Prom
  */
 declare function hasCapability(ctx: PluginContext, capability: string): boolean;
 
-export { MARKETPLACE_PUBLISH_SOURCES, MARKETPLACE_SUBMISSION_STATUSES, type MarketplaceOwnedPlugin, type MarketplaceOwnedPluginInput, type MarketplaceOwnedPluginResponse, type MarketplaceOwnedPluginsResponse, type MarketplacePublishSource, type MarketplacePublisherError, type MarketplacePublisherProfile, type MarketplacePublisherProfileInput, type MarketplacePublisherProfileResponse, type MarketplaceReleaseAcceptedResponse, type MarketplaceSubmission, type MarketplaceSubmissionCursor, type MarketplaceSubmissionStatus, type MarketplaceSubmissionsResponse, PluginContext, PluginLogger, PluginManifest, checkPermission, createLogger, definePlugin, hasCapability, marketplaceOwnedPluginInputSchema, marketplaceOwnedPluginResponseSchema, marketplaceOwnedPluginSchema, marketplaceOwnedPluginsResponseSchema, marketplacePublishSourceSchema, marketplacePublisherErrorSchema, marketplacePublisherProfileInputSchema, marketplacePublisherProfileResponseSchema, marketplacePublisherProfileSchema, marketplaceReleaseAcceptedResponseSchema, marketplaceSubmissionCursorSchema, marketplaceSubmissionSchema, marketplaceSubmissionStatusSchema, marketplaceSubmissionsResponseSchema, requirePermission };
+type WebUrlSearchValue = boolean | number | string | null | undefined;
+type WebUrlSearchParams = URLSearchParams | Record<string, WebUrlSearchValue>;
+/**
+ * Builds an absolute URL for a public Web route without assuming how the site
+ * is hosted. Custom domains and platform subdomains use an empty basePath;
+ * platform-path sites provide a basePath such as `/s/acme`.
+ */
+declare function buildWebUrl(site: Pick<WebPluginSiteInfo, 'basePath' | 'publicOrigin'> | null | undefined, href: string, searchParams?: WebUrlSearchParams): string | null;
+
+/**
+ * Agent tool assembly + pre-call governance (AI Action Gateway, Phase 1).
+ *
+ * Translates the governed Action Catalog into the tool shape an LLM runtime
+ * consumes, and enforces the rules that must hold BEFORE a model-proposed call
+ * reaches the invoker. Kept in the SDK so any agent-host plugin gets identical
+ * semantics rather than re-deriving them.
+ *
+ * Two rules carry most of the weight (plan §9):
+ *
+ *   - **The model never picks a procedure path.** Tools are named after stable
+ *     `actionId`s; the Host resolves the binding. A hallucinated tool name is a
+ *     miss, not an arbitrary call.
+ *   - **The model cannot talk its way past a confirmation.** Risk comes from the
+ *     curated contract, never from tool output or model reasoning, and high-risk
+ *     calls are refused here unless an approval token is already present.
+ *
+ * Both rules assume the tool name arrived as protocol data. `ToolChannel` is
+ * where that assumption is made explicit and enforced.
+ */
+/**
+ * How a tool call reached us.
+ *
+ * `native` — the provider returned a structured tool call over its own protocol,
+ * so the tool name is a protocol fact and maps to a curated `actionId`.
+ *
+ * `text-recovered` — the call was parsed out of the model's prose, the way
+ * text-mode runtimes recover DeepSeek DSML markup and similar. There the tool
+ * name *is* model-authored free text, which collapses the boundary the two rules
+ * above rest on: prose becomes the source of the action to run. Such a channel
+ * therefore carries `query` actions only — a channel that cannot be trusted to
+ * name an action cannot be trusted to change data.
+ */
+type ToolChannel = "native" | "text-recovered";
+/** Minimal shape of a catalog entry; mirrors ActionDescriptor without importing it. */
+interface AgentToolSource {
+    actionId: string;
+    revision: number;
+    kind: "query" | "command";
+    risk: "low" | "medium" | "high";
+    summary?: string | undefined;
+}
+/** JSON-Schema-shaped tool definition, the lingua franca of tool-calling APIs. */
+interface AgentToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties: boolean;
+    };
+    /** Curated metadata; NOT model-supplied and NOT to be trusted from tool output. */
+    metadata: {
+        actionId: string;
+        revision: number;
+        kind: "query" | "command";
+        risk: "low" | "medium" | "high";
+        requiresApproval: boolean;
+    };
+}
+interface AssembleOptions {
+    /** Argument schemas by actionId, when the host can supply them. */
+    argumentSchemas?: Record<string, {
+        properties: Record<string, unknown>;
+        required?: string[];
+    }>;
+    /** Drop actions above this risk level from what the model can even see. */
+    maxRisk?: "low" | "medium" | "high";
+    /**
+     * The channel these tools will be offered on. A `text-recovered` channel is
+     * assembled without commands, so the model is never shown a write the gate
+     * would refuse anyway. Defaults to `native`: this is a pure helper, and the
+     * callers that hold a real channel (`runAgent`, the host endpoints) are the
+     * ones that treat an undeclared channel as untrusted.
+     */
+    channel?: ToolChannel;
+}
+/** Tool names must survive provider naming rules (letters, digits, _, -). */
+declare function toolNameFor(actionId: string): string;
+declare function requiresApprovalFor(risk: AgentToolSource["risk"]): boolean;
+/**
+ * Build the tool list exposed to a model.
+ *
+ * Descriptions state the governance consequence explicitly: models behave better
+ * when told a call will pause for a human than when silently refused later.
+ */
+declare function assembleTools(sources: readonly AgentToolSource[], options?: AssembleOptions): AgentToolDefinition[];
+type ToolCallDecision = {
+    allow: true;
+    actionId: string;
+    revision: number;
+} | {
+    allow: false;
+    reason: ToolCallRefusal;
+    message: string;
+};
+type ToolCallRefusal = "UNKNOWN_TOOL" | "APPROVAL_REQUIRED" | "BUDGET_EXHAUSTED" | "TENANT_PAUSED" | "CHANNEL_READ_ONLY";
+interface ToolCallGateInput {
+    toolName: string;
+    tools: readonly AgentToolDefinition[];
+    /** Present when the caller already holds a human approval for this call. */
+    approvalToken?: string | undefined;
+    /** Remaining tool calls in this run; `undefined` means unbounded. */
+    remainingCalls?: number | undefined;
+    /** Tenant-level kill switch for AI writes (plan §9 resource exhaustion). */
+    writesPaused?: boolean;
+    /** How this call reached us; a `text-recovered` channel carries reads only. */
+    channel?: ToolChannel;
+}
+/**
+ * Decide whether a model-proposed tool call may proceed.
+ *
+ * Runs before the invoker so refusals cost nothing and can be fed back to the
+ * model as a normal tool result — a refused call should steer the model, not
+ * crash the run.
+ */
+declare function gateToolCall(input: ToolCallGateInput): ToolCallDecision;
+/**
+ * Wrap a tool result before it re-enters the model context.
+ *
+ * Tool output is untrusted input (plan §9 malicious tool output): it is fenced
+ * and labelled so the model cannot pass it off as an instruction, and it can
+ * never carry governance metadata of its own.
+ */
+declare function encodeToolResult(actionId: string, result: unknown): string;
+
+/**
+ * Governed agent run loop (AI Action Gateway, Phase 1).
+ *
+ * The multi-turn loop that sits between a model and the governed action
+ * surface. It is deliberately **model-agnostic**: the LLM is reached through a
+ * narrow `ModelClient` seam, so the chosen runtime (Pi — see
+ * `docs/architecture/adr/2026-07-27-agent-runtime-pi.md`) is one implementation
+ * rather than a structural dependency, and the whole governance path is
+ * testable without a network or API key.
+ *
+ * What the loop guarantees, regardless of what the model does:
+ *
+ *   - **Budgets are hard.** Turn and tool-call ceilings are enforced by the loop,
+ *     not requested of the model. A runaway loop stops.
+ *   - **Refusals steer, they don't crash.** A gated call returns a tool result
+ *     explaining why, so the model can adapt; only infrastructure faults throw.
+ *   - **Tool output is data.** Results are fenced and labelled before re-entering
+ *     the context, and can never redirect which action runs next — the actionId
+ *     always comes from the curated catalog via the tool name.
+ *   - **Prose cannot become a command.** That last guarantee holds only while the
+ *     tool name is protocol data, so a client that recovers calls from model text
+ *     (`channel: 'text-recovered'`) is confined to read-only actions.
+ *   - **High-risk work pauses.** A call needing approval suspends the run with
+ *     everything the caller needs to raise a confirmation, instead of guessing.
+ */
+
+interface ModelToolCall {
+    id: string;
+    /** Tool name as emitted by the model; resolved against the catalog, never trusted as a path. */
+    name: string;
+    arguments?: unknown;
+}
+interface ModelMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    toolCalls?: ModelToolCall[];
+    toolCallId?: string;
+}
+interface ModelResponse {
+    text?: string;
+    toolCalls?: ModelToolCall[];
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        costUsd?: number;
+    };
+}
+interface ModelClient {
+    /**
+     * How this client surfaces tool calls. An adapter that parses them out of the
+     * model's prose rather than reading them off the wire MUST declare
+     * `text-recovered`; the loop then withholds every command action.
+     *
+     * Required so the choice is made by whoever writes the adapter, who is the
+     * only one who knows. An absent value is treated as `text-recovered` — the
+     * restrictive reading — because reaching that line means the declaration was
+     * bypassed rather than considered.
+     */
+    readonly channel: ToolChannel;
+    complete(input: {
+        messages: ModelMessage[];
+        tools: AgentToolDefinition[];
+        signal?: AbortSignal;
+    }): Promise<ModelResponse>;
+}
+/** Executes an accepted call. Implemented by the host over `ctx.actions.invoke`. */
+type ActionExecutor = (call: {
+    actionId: string;
+    revision: number;
+    args: unknown;
+}) => Promise<unknown>;
+type AgentRunEvent = {
+    type: "turn.started";
+    turn: number;
+} | {
+    type: "message.completed";
+    text: string;
+} | {
+    type: "tool.started";
+    toolName: string;
+    actionId: string;
+} | {
+    type: "tool.completed";
+    actionId: string;
+} | {
+    type: "tool.refused";
+    toolName: string;
+    reason: ToolCallRefusal;
+} | {
+    type: "tool.approval_required";
+    toolName: string;
+    actionId: string;
+    args: unknown;
+} | {
+    type: "run.completed";
+    reason: RunStopReason;
+} | {
+    type: "run.failed";
+    error: string;
+};
+type RunStopReason = "completed" | "turn_budget" | "tool_budget" | "approval_required" | "aborted";
+interface AgentRunOptions {
+    model: ModelClient;
+    tools: AgentToolDefinition[];
+    execute: ActionExecutor;
+    messages: ModelMessage[];
+    maxTurns?: number;
+    maxToolCalls?: number;
+    /** Tenant kill switch for AI writes; reads continue. */
+    writesPaused?: boolean;
+    /** Approval tokens already held, keyed by actionId. */
+    approvals?: Record<string, string>;
+    onEvent?: (event: AgentRunEvent) => void;
+    signal?: AbortSignal;
+}
+interface AgentRunResult {
+    stopReason: RunStopReason;
+    messages: ModelMessage[];
+    text: string;
+    toolCallsUsed: number;
+    turnsUsed: number;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+    };
+    /** Set when `stopReason === 'approval_required'`. */
+    pendingApproval?: {
+        toolName: string;
+        actionId: string;
+        revision: number;
+        args: unknown;
+    };
+}
+declare function runAgent(options: AgentRunOptions): Promise<AgentRunResult>;
+
+/**
+ * WordRhyme Connector — one codebase, two transports (AI Action Gateway, Phase 0 segment 3).
+ *
+ * `local`  — invokes governed actions in-process through `ctx.actions`
+ *            (ActionInvokerCapability); identity comes from the live request.
+ * `remote` — invokes the SAME action surface on ANOTHER WordRhyme instance over
+ *            HTTP `POST {baseUrl}/trpc/<path>` with `x-api-key`.
+ *
+ * Both transports share the `invoke(actionId, revision, args)` shape, so callers
+ * cannot tell them apart — that is the point of the segment-3 spike.
+ *
+ * Security posture (all fail closed):
+ *   - remote base URLs must be explicitly allowlisted; private/loopback hosts are
+ *     rejected unless the allowlist entry itself is loopback (dev/tests)
+ *   - redirects are never followed (`redirect: 'error'`) — no redirect-to-private-net
+ *   - the remote instance pins the organization to its API token; this client
+ *     therefore never sends an organizationId, and refuses to accept one
+ *   - `onBehalfOf` is delegation CONTEXT FOR AUDIT ONLY, never a permission source;
+ *     the remote side authorizes as the token's own principal
+ */
+/** Actions surface the local transport delegates to (subset of PluginActionInvokerCapability). */
+interface ConnectorLocalActions {
+    invoke(request: {
+        actionId: string;
+        revision: number;
+        args?: unknown;
+    }): Promise<unknown>;
+}
+interface ConnectorInvokeRequest {
+    actionId: string;
+    revision: number;
+    args?: unknown;
+    /** Audit-only delegation context. Never widens permissions on either side. */
+    onBehalfOf?: string;
+}
+interface WordRhymeConnector {
+    readonly transport: "local" | "remote";
+    invoke(request: ConnectorInvokeRequest): Promise<unknown>;
+}
+interface LocalConnectorOptions {
+    transport: "local";
+    actions: ConnectorLocalActions;
+}
+interface RemoteConnectorOptions {
+    transport: "remote";
+    baseUrl: string;
+    apiKey: string;
+    /** Exact origins this connector may call. Empty ⇒ nothing is allowed. */
+    allowedOrigins: string[];
+    /** Action ids this connector may invoke remotely. Empty ⇒ nothing is allowed. */
+    allowedActions: string[];
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+type ConnectorOptions = LocalConnectorOptions | RemoteConnectorOptions;
+declare class ConnectorError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Resolve a remote base URL against the allowlist.
+ * Private/loopback targets are only permitted when explicitly allowlisted,
+ * which keeps dev and tests usable without opening SSRF in production configs.
+ */
+declare function resolveRemoteOrigin(baseUrl: string, allowedOrigins: string[]): string;
+declare function createWordRhymeConnector(options: ConnectorOptions): WordRhymeConnector;
+
+export { type ActionExecutor, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentToolDefinition, type AgentToolSource, type AssembleOptions, ConnectorError, type ConnectorInvokeRequest, type ConnectorLocalActions, type ConnectorOptions, type LocalConnectorOptions, MARKETPLACE_PUBLISH_SOURCES, MARKETPLACE_SUBMISSION_STATUSES, type MarketplaceOwnedPlugin, type MarketplaceOwnedPluginInput, type MarketplaceOwnedPluginResponse, type MarketplaceOwnedPluginsResponse, type MarketplacePublishSource, type MarketplacePublisherError, type MarketplacePublisherProfile, type MarketplacePublisherProfileInput, type MarketplacePublisherProfileResponse, type MarketplaceReleaseAcceptedResponse, type MarketplaceSubmission, type MarketplaceSubmissionCursor, type MarketplaceSubmissionStatus, type MarketplaceSubmissionsResponse, type ModelClient, type ModelMessage, type ModelResponse, type ModelToolCall, PluginContext, PluginLogger, PluginManifest, type RemoteConnectorOptions, type RunStopReason, type ToolCallDecision, type ToolCallGateInput, type ToolCallRefusal, type ToolChannel, WebPluginSiteInfo, type WebUrlSearchParams, type WebUrlSearchValue, type WordRhymeConnector, assembleTools, buildWebUrl, checkPermission, createLogger, createWordRhymeConnector, definePlugin, encodeToolResult, gateToolCall, hasCapability, marketplaceOwnedPluginInputSchema, marketplaceOwnedPluginResponseSchema, marketplaceOwnedPluginSchema, marketplaceOwnedPluginsResponseSchema, marketplacePublishSourceSchema, marketplacePublisherErrorSchema, marketplacePublisherProfileInputSchema, marketplacePublisherProfileResponseSchema, marketplacePublisherProfileSchema, marketplaceReleaseAcceptedResponseSchema, marketplaceSubmissionCursorSchema, marketplaceSubmissionSchema, marketplaceSubmissionStatusSchema, marketplaceSubmissionsResponseSchema, requirePermission, requiresApprovalFor, resolveRemoteOrigin, runAgent, toolNameFor };