@ai-agent-forge/plugin-sdk 0.87.0 → 0.88.1

package/dist/public-api.d.ts

@@ -110,6 +110,30 @@ export interface SubagentCommunicationWiringV1 {
         text: string;
     }[];
 }
+/**
+ * 模型目录条目的宿主结构视图（D-082 批 3b，契约 B）：只暴露 provider-failover
+ * 装载预检消费的五个字段（structural、JSON-safe），不透出内核 Model 对象。
+ * `compat`/`thinkingLevelMap` 随目录条目可选。
+ */
+export interface ModelCatalogModelViewV1 {
+    provider: string;
+    contextWindow: number;
+    maxTokens: number;
+    compat?: unknown;
+    thinkingLevelMap?: unknown;
+}
+/**
+ * 模型目录宿主服务（D-082 批 3b，契约 B；workspaceDirectory 同款可选宿主服务
+ * 成员先例）：装载预检/目录快照读面（provider-failover 家族），零网络、零
+ * OAuth——全部是宿主静态目录与凭据条目的即时读投影。宿主缺模型目录能力时
+ * 该成员缺席，插件必须按可选拒绝装配，不得假设其存在。
+ */
+export interface ModelCatalogV1 {
+    /** 未知 provider/model 对返回 undefined（"无候选"）。 */
+    resolveModel(provider: string, modelId: string): ModelCatalogModelViewV1 | undefined;
+    hasProvider(providerId: string): boolean;
+    hasConfiguredAuth(providerId: string): boolean;
+}
 export interface HostCapabilities {
     apiVersion: typeof EXPERIMENTAL_PUBLIC_API_VERSION;
     mode: HostMode;
@@ -173,6 +197,12 @@ export interface HostCapabilities {
      * nothing when no agentDir is declared.
      */
     memoryStorage?: MemoryStorageComponentsV1;
+    /**
+     * 模型目录宿主服务（D-082 批 3b，契约 B）：装载预检/目录快照读面
+     * （provider-failover 家族），零网络、零 OAuth——只读宿主静态模型目录与
+     * 凭据条目投影（`api.host.modelCatalog`）。缺席 = 宿主不提供目录读面。
+     */
+    modelCatalog?: ModelCatalogV1;
 }
 export interface DisposableRegistration {
     id: string;
@@ -1553,7 +1583,6 @@ export interface PolicyInvocationContextV1 {
 export interface RetryPolicyRequest {
     signal?: AbortSignal;
     retryable: boolean;
-    enabled: boolean;
     attempt: number;
     maxAttempts: number;
     baseDelayMs: number;
@@ -1577,7 +1606,6 @@ export interface RetryPolicy {
 }
 export interface CompactionPolicyRequest {
     signal?: AbortSignal;
-    enabled: boolean;
     reason: "overflow" | "threshold";
     contextOverflow: boolean;
     recoverableLength: boolean;
@@ -1585,14 +1613,6 @@ export interface CompactionPolicyRequest {
     contextUsage?: CompactionContextUsage;
     recoveryAttempted: boolean;
     canContinue: boolean;
-    /**
-     * Branch path entry snapshot (threshold requests only). Provided so a
-     * policy can plan CHEAP RELIEF (see {@link CompactionPolicyDecision.relief})
-     * from real history facts instead of ordering a summarization run.
-     */
-    branchEntries?: readonly unknown[];
-    /** Recent-tail protection budget (settings fact) for relief planning. */
-    keepRecentTokens?: number;
     context?: PolicyInvocationContextV1;
     execution?: ExecutionFactsV1;
 }
@@ -1612,18 +1632,6 @@ export interface CompactionPolicyDecision {
     compact: boolean;
     retry?: boolean;
     failureMessage?: string;
-    /**
-     * Cheap RELIEF plan: the host appends this custom entry (generic
-     * `appendCustomEntry`) and reprojects the context instead of running a
-     * summarization. The semantics of the entry belong entirely to the policy;
-     * the projection that interprets it is registered separately via
-     * {@link CapabilityAPI.registerEntryProjection}. When relief is present the
-     * host skips compaction, so `compact` must be false.
-     */
-    relief?: {
-        readonly customType: string;
-        readonly data?: unknown;
-    };
 }
 /** Provider-agnostic facts about the model the host will use for a summary call. */
 export interface SummaryModelFactsV1 {
@@ -1786,13 +1794,15 @@ export type StreamFnNext = (model: unknown, context: unknown, options: unknown)
 /**
  * Experimental request-time stream-function middleware (provider-failover
  * family): observe the provider stream's terminal state, substitute the
- * request model, and replay. Wrappers run in registration order — the first
- * registered wrapper is the outermost, its `next` covering every later
- * wrapper plus the host default. Must return (a promise of) the event stream
- * the caller consumes; failures belong inside the stream protocol, matching
- * the host stream-function contract. A session whose caller supplied an
- * explicit stream function bypasses the host default assembly entirely and
- * never sees these wrappers.
+ * request model, and replay. Wrapper order follows the registration
+ * priority (contract A, D-082 批 3b): lower `priority` wraps outermost;
+ * equal priorities keep registration order (first registered = outermost
+ * within the same priority). The outermost wrapper's `next` covers every
+ * later wrapper plus the host default. Must return (a promise of) the event
+ * stream the caller consumes; failures belong inside the stream protocol,
+ * matching the host stream-function contract. A session whose caller
+ * supplied an explicit stream function bypasses the host default assembly
+ * entirely and never sees these wrappers.
  */
 export type StreamFnWrapper = (model: unknown, context: unknown, options: unknown, next: StreamFnNext, host: StreamFnWrapperHostV1) => unknown;
 /**
@@ -1977,7 +1987,18 @@ export interface CapabilityAPI {
      */
     registerEntryProjection(projection: EntryProjection): DisposableRegistration;
     registerProviderHeaderTransform(name: string, transform: ProviderHeaderTransform): DisposableRegistration;
-    registerStreamFnWrapper(name: string, wrapper: StreamFnWrapper): DisposableRegistration;
+    /**
+     * Registers a stream-function wrapper (provider-failover family, contract
+     * A D-082 批 3b). `options.priority` orders the wrapper chain: lower
+     * values wrap outermost (default 0), so a rerouting wrapper can register
+     * with a negative priority and stay outermost regardless of plugin load
+     * order — every inner wrapper then observes the substituted model on each
+     * retry attempt. Equal priorities keep registration order (first
+     * registered = outermost), the pre-priority semantics.
+     */
+    registerStreamFnWrapper(name: string, wrapper: StreamFnWrapper, options?: {
+        priority?: number;
+    }): DisposableRegistration;
     registerSkill(definition: SkillDefinition): DisposableRegistration;
     registerRetryPolicy(name: string, policy: RetryPolicy): DisposableRegistration;
     registerCompactionPolicy(name: string, policy: CompactionPolicy): DisposableRegistration;