@x-otto/plugin 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { TypedEventEmitter } from "@x-otto/shared";
 import * as _$_x_otto_interchange0 from "@x-otto/interchange";
 import { PluginInputRegistry, SigilEntry, SigilKind, SigilPrefix, SigilProvider, SigilSource, sigilOf } from "@x-otto/interchange";
 import * as _$_x_otto_provider0 from "@x-otto/provider";
+import { HookAbortSignal, HookPayloadMap, WaterfallTiming } from "@x-otto/hook-contracts";
 
 //#region src/capabilities.d.ts
 /**
@@ -2355,6 +2356,10 @@ type PreToolUseDecision = {
  * RFC-129 D1 边界纪律：新增的 9 个字段全部是 observer-only——不开放任何可变换消息/参数的
  * interceptor timing（`messages.transform`/`chat.params`/`system.prompt.transform`/
  * `chat.message.after` 均不对插件开放，见 RFC-129 §1.2 非目标 + 放弃方案）。
+ *
+ * RFC-327 修订 D1（M1）显式修订：上述边界纪律对 `waterfall` 贡献面**不再成立**——
+ * waterfall 是**新的贡献面**（不是 observer 改 interceptor），经受控白名单 timing
+ * （`WaterfallTiming`）开放三个受控中间产物的改写点，见下方 `waterfall` 字段说明。
  */
 interface PluginHooks {
   preToolUse?: (ctx: ToolUseContext) => PreToolUseDecision | void | Promise<PreToolUseDecision | void>;
@@ -2436,7 +2441,36 @@ interface PluginHooks {
     taskId: string;
     agent: string;
   }) => void | Promise<void>;
+  /**
+   * RFC-327 修订 D1（M1）：waterfall 贡献面——插件经受控白名单 timing 改写主循环中间产物。
+   *
+   * 语义对齐 HookRegistry 既有 interceptor（priority 序 → 共享可变 output → 后续可见前者
+   * 改写），**外加** serial-with-early-bail：任一 handler 返回 `{ abort: true }` →
+   * 终止该 timing 的整条 hook 链，output 保留已累积值（后续引擎 hook 不执行）。
+   *
+   * 安全边界（R1'/R10）：
+   * - 只作用于白名单 timing 的**受控中间产物**（`system.prompt.transform` /
+   *   `chat.params` / `messages.transform`）——不开放历史消息、用户输入、tool 参数；
+   * - 白名单编译期强制（`WaterfallTiming` 从 `HookPayloadMap` Pick），装载器运行时校验兜底，
+   *   白名单外 timing 一律拒绝注册（fail-closed）；
+   * - `system.prompt.transform` 默认只开放 `systemTail`（volatile，cache 断点后，逐轮可变）
+   *   + 预算闸（4KB 顶）——`systemPrompt`（stable，进 prompt cache）**第一版不开放**，
+   *   尝试写入被装载器拒绝（fail-closed，写入会永久污染后续所有轮次的 prompt cache 前缀）；
+   * - 全程审计（pluginId + timing + 变更摘要），走既有 capability/trust/隔离 RPC 三重门，
+   *   不另建旁路。
+   *
+   * 能力面跃迁声明：从「插件只能 deny/ask 升级限制」到「插件能改写受控中间产物」是质变，
+   * 本字段是新贡献面（非 observer 改 interceptor），配套 D1a 分权与安全门见 RFC-327 修订 §3。
+   */
+  waterfall?: PluginWaterfallHooks;
 }
+/**
+ * RFC-327 修订 D1（M1）：waterfall handler 逐 timing 签名——input/output 与引擎
+ * `HookPayloadMap` 对齐（编译期逐 timing 精确类型，无双重断言），返回值支持 abort 哨兵。
+ */
+type PluginWaterfallHandler<T extends WaterfallTiming> = (input: HookPayloadMap[T]['input'], output: HookPayloadMap[T]['output']) => void | HookAbortSignal | Promise<void | HookAbortSignal>;
+/** RFC-327 修订 D1（M1）：waterfall 贡献面的逐 timing 映射（mapped type 保持 per-key 类型精确）。 */
+type PluginWaterfallHooks = { [T in WaterfallTiming]?: PluginWaterfallHandler<T> };
 /** 装载时注入工厂的上下文。 */
 interface PluginContext {
   /** 插件 id（= manifest.id = source 标签）。 */
@@ -2579,6 +2613,12 @@ interface PluginTool {
       data?: unknown;
       error?: unknown;
     };
+    /**
+     * 模型侧序列化契约（与 @x-otto/interchange 的 AgentTool.parameters 对齐）：
+     * provider 序列化时无此方法则模型收到空 {} schema、参数完全不可见。
+     * 手写 schema 必须与 safeParse 成对提供（2026-08-13 终局复核回归教训）。
+     */
+    toJSONSchema?: () => unknown;
   };
   /**
    * 执行体。第二参数 `ctx` 为 RFC-303 M4 可选上下文（pluginId/workspaceDir/logger/
@@ -3299,5 +3339,5 @@ declare class PluginI18nRegistry extends TypedEventEmitter<PluginI18nRegistryEve
   t(fullKey: string, locale?: string): string;
 }
 //#endregion
-export { type ActionContribution, type AgentContribution, type CommandContribution, type CommandRef, type ContextKeyProvider, type ContextMap, type ContextSourceContribution, type ContributionPoint, type DiscoverPluginsOptions, type DiscoveredPlugin, type DispatchCaps, EXTENSION_POINTS, type EngineCompatResult, type FeedbackIssueInput, type FeedbackIssueResult, type FeedbackProvider, type FileProviderOptions, HIGH_RISK_CAPABILITIES, type HostAskInput, ID_RE, MAX_I18N_ENTRIES_PER_PLUGIN, MAX_I18N_FILE_BYTES, MAX_I18N_LOCALE_FILES_PER_PLUGIN, MAX_I18N_TRANSLATION_BYTES, MAX_THEME_PRESETS_PER_PLUGIN, type McpContribution, type McpTransport, type MenuContribution, type MonitorEvent, type OAuthContribution, PLUGIN_API_VERSION, PLUGIN_CAPABILITIES, PLUGIN_MANIFEST_FILENAME, POINT, type PerfMetricContribution, type PluginA2uiComponentEntry, type PluginA2uiRendererEntry, type PluginCapability, type PluginCliContribution, type PluginContext, type PluginContributes, type PluginContributions, type PluginExecutableSurface, type PluginFactory, type PluginFileViewerEntry, type PluginHooks, type PluginHostCapabilities, type PluginI18nContribution, type PluginI18nEntry, PluginI18nRegistry, type PluginInputRegistry, type PluginManifest, type PluginModelEntry, type PluginModule, type PluginMonitor, type PluginPanelEntry, type PluginProviderEntry, type PluginProviderFactory, type PluginRendererEntry, type PluginScheduleSubscription, type PluginScopedStorageShape, type PluginScripts, type PluginService, type PluginServiceContext, type PluginServiceNotification, type PluginThemePresetColors, type PluginThemePresetContribution, type PluginTool, type PluginToolContext, type PluginTrustVerdict, type PluginWireProtocolRegistration, type PreToolUseDecision, type PulseSurveyEntry, type PulseSurveyRating, type PulseSurveyResolvedConfig, type ResolvedAction, SHELL_POINTS, type ScheduleTickNotification, type SessionIdleNotification, type SigilEntry, type SigilEntryContribution, type SigilKind, type SigilPrefix, type SigilProvider, type SigilSource, type SkillContribution, type StatusItemContribution, type StatusWidgetContribution, type ToolUseContext, type TopoSortResult, type TranscriptMessage, createBuiltinHashtags, createFileProvider, createPluginInputRegistry, definePlugin, detectPluginExecutableSurface, discoverPlugins, dispatch, evaluateContextKey, evaluateContextKeys, evaluatePluginTrust, evaluateWhen, expandPath, filterEngineCompatible, grantPluginCapabilities, grantedPluginCapabilities, isEngineCompatible, isPathTrusted, isPluginTrusted, mergeContributions, parsePluginManifest, pluginTrustStorePath, readHighRiskCapabilities, resolveActions, resolveActivationEvents, sigilOf, topoSortPlugins, trustPath, trustPlugin, untrustPath, untrustPlugin };
+export { type ActionContribution, type AgentContribution, type CommandContribution, type CommandRef, type ContextKeyProvider, type ContextMap, type ContextSourceContribution, type ContributionPoint, type DiscoverPluginsOptions, type DiscoveredPlugin, type DispatchCaps, EXTENSION_POINTS, type EngineCompatResult, type FeedbackIssueInput, type FeedbackIssueResult, type FeedbackProvider, type FileProviderOptions, HIGH_RISK_CAPABILITIES, type HostAskInput, ID_RE, MAX_I18N_ENTRIES_PER_PLUGIN, MAX_I18N_FILE_BYTES, MAX_I18N_LOCALE_FILES_PER_PLUGIN, MAX_I18N_TRANSLATION_BYTES, MAX_THEME_PRESETS_PER_PLUGIN, type McpContribution, type McpTransport, type MenuContribution, type MonitorEvent, type OAuthContribution, PLUGIN_API_VERSION, PLUGIN_CAPABILITIES, PLUGIN_MANIFEST_FILENAME, POINT, type PerfMetricContribution, type PluginA2uiComponentEntry, type PluginA2uiRendererEntry, type PluginCapability, type PluginCliContribution, type PluginContext, type PluginContributes, type PluginContributions, type PluginExecutableSurface, type PluginFactory, type PluginFileViewerEntry, type PluginHooks, type PluginHostCapabilities, type PluginI18nContribution, type PluginI18nEntry, PluginI18nRegistry, type PluginInputRegistry, type PluginManifest, type PluginModelEntry, type PluginModule, type PluginMonitor, type PluginPanelEntry, type PluginProviderEntry, type PluginProviderFactory, type PluginRendererEntry, type PluginScheduleSubscription, type PluginScopedStorageShape, type PluginScripts, type PluginService, type PluginServiceContext, type PluginServiceNotification, type PluginThemePresetColors, type PluginThemePresetContribution, type PluginTool, type PluginToolContext, type PluginTrustVerdict, type PluginWaterfallHandler, type PluginWaterfallHooks, type PluginWireProtocolRegistration, type PreToolUseDecision, type PulseSurveyEntry, type PulseSurveyRating, type PulseSurveyResolvedConfig, type ResolvedAction, SHELL_POINTS, type ScheduleTickNotification, type SessionIdleNotification, type SigilEntry, type SigilEntryContribution, type SigilKind, type SigilPrefix, type SigilProvider, type SigilSource, type SkillContribution, type StatusItemContribution, type StatusWidgetContribution, type ToolUseContext, type TopoSortResult, type TranscriptMessage, createBuiltinHashtags, createFileProvider, createPluginInputRegistry, definePlugin, detectPluginExecutableSurface, discoverPlugins, dispatch, evaluateContextKey, evaluateContextKeys, evaluatePluginTrust, evaluateWhen, expandPath, filterEngineCompatible, grantPluginCapabilities, grantedPluginCapabilities, isEngineCompatible, isPathTrusted, isPluginTrusted, mergeContributions, parsePluginManifest, pluginTrustStorePath, readHighRiskCapabilities, resolveActions, resolveActivationEvents, sigilOf, topoSortPlugins, trustPath, trustPlugin, untrustPath, untrustPlugin };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-otto/plugin",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.5",
   "files": [
     "dist",
     "README.md"
@@ -22,10 +22,11 @@
   "dependencies": {
     "semver": "7.7.4",
     "zod": "4.3.6",
-    "@x-otto/interchange": "0.1.0-alpha.3",
-    "@x-otto/env": "0.1.0-alpha.6",
+    "@x-otto/hook-contracts": "0.0.1-alpha.2",
+    "@x-otto/provider": "0.1.0-alpha.5",
     "@x-otto/shared": "0.1.0-alpha.6",
-    "@x-otto/provider": "0.1.0-alpha.5"
+    "@x-otto/interchange": "0.1.0-alpha.4",
+    "@x-otto/env": "0.1.0-alpha.6"
   },
   "devDependencies": {
     "@types/semver": "7.7.1"