@ai-agent-forge/plugin-sdk 0.88.14 → 0.88.16

package/dist/public-api.d.ts

@@ -152,6 +152,53 @@ export interface ModelCatalogV1 {
     hasProvider(providerId: string): boolean;
     hasConfiguredAuth(providerId: string): boolean;
 }
+/** One bounded page of an archived session's entries (SessionArchiveHostV1.readEntries). */
+export interface SessionArchiveReadChunkV1 {
+    readonly entries: readonly SessionEntryView[];
+    /** Present when more entries remain; pass as `offset` for the next page. */
+    readonly nextOffset?: number;
+}
+/**
+ * Curation outcome for one archived session, as reported by a curator and
+ * recorded in the host-owned manifest (SessionArchiveHostV1.reportCuration).
+ * `curated` = the batch committed; `skipped` = the curator ran but had nothing
+ * to curate (no curation policy installed, or the host exposes no archive
+ * face — the latter is answered locally without a manifest fact). When the
+ * memory capability is off the curator never registers, so no curation fact
+ * is ever written; the archive can then only be physically deleted with an
+ * explicit uncurated-purge confirmation.
+ */
+export type SessionCurationStatusV1 = "curated" | "skipped";
+/**
+ * 会话归档协调面（记忆归档与整理设计 §4/§8，宿主服务契约；memoryStorage /
+ * agentTaskResults 同款可选宿主服务成员先例）。宿主拥有归档目录与 manifest
+ * （权威状态源），经本面向插件开放两件事：分页读取归档会话条目（curator 的
+ * 唯一公共读取路径——SessionAPI.getBranchEntries() 只见当前会话），以及整理
+ * 结果回写（archive 与 curation 是两个独立维度，事实都由宿主清单承载，插件
+ * 只上报）。缺席 = 宿主不开放归档：curator 不注册，manifest 里不会出现任何
+ * curation 事实，此类会话的物理删除需经宿主侧显式确认（未经整理明示）。
+ */
+export interface SessionArchiveHostV1 {
+    /** 未知 sessionId 或越界 offset 返回空页（fail-closed，不抛错）。 */
+    readEntries(sessionId: string, options?: {
+        readonly offset?: number;
+        readonly limit?: number;
+    }): Promise<SessionArchiveReadChunkV1>;
+    /** 未知 sessionId 幂等成功；重复上报以最后一次为准（manifest 按维度取末条）。 */
+    reportCuration(sessionId: string, status: SessionCurationStatusV1, info?: {
+        readonly batchId?: string;
+    }): Promise<void>;
+    curationStatus(sessionId: string): Promise<SessionCurationStatusV1 | undefined>;
+    /**
+     * 归档清单投影：每个当前处于归档态（archive 维度末条为 `archived`）的会话
+     * 一条，附其 curation 维度末条（未整理为 `undefined`）。清单是权威状态源，
+     * 本读面按清单合并归档目录；整理器启动时靠它找未整理会话。
+     */
+    listArchived(): Promise<{
+        readonly sessionId: string;
+        readonly curation: SessionCurationStatusV1 | undefined;
+    }[]>;
+}
 export interface HostCapabilities {
     apiVersion: typeof EXPERIMENTAL_PUBLIC_API_VERSION;
     mode: HostMode;
@@ -236,6 +283,21 @@ export interface HostCapabilities {
         readonly store: DurableServiceV1;
         readonly writerId: string;
     };
+    /**
+     * Session archive coordination (记忆归档与整理设计 §4/§7-§8, host service
+     * contract). Present on hosts that own the session archive
+     * (`<agentDir>/archive/sessions/`, manifest.jsonl). Two jobs: (1) bounded
+     * read access to an archived session's entries — the public path for
+     * curators, since `SessionAPI.getBranchEntries()` only sees the current
+     * session; (2) the write-back face for curation outcomes, so the
+     * host-owned manifest stays the single authoritative state source
+     * (archive and curation are two independent dimensions; the host owns
+     * both facts, the plugin reports them). Absent = the host exposes no
+     * archive: the curator does not register and no curation fact is ever
+     * written; physically deleting such archives requires an explicit
+     * host-side uncurated-purge confirmation.
+     */
+    sessionArchive?: SessionArchiveHostV1;
 }
 export interface DisposableRegistration {
     id: string;
@@ -708,6 +770,12 @@ export interface ModelFactsViewV1 {
     contextWindow: number;
     maxTokens: number;
     reasoning: boolean;
+    /** Declared provider-native web-search capability. Absent or `unknown` means unsupported. */
+    webSearch?: {
+        native: boolean | "unknown";
+        mode?: "openai-responses" | "anthropic-server-tool" | "google-grounding" | "chat-option";
+        confidence?: "declared" | "tested";
+    };
 }
 /** Scoped model entry: model facts plus the pattern's explicit thinking level, if any. */
 export interface ScopedModelFactsViewV1 {
@@ -855,6 +923,109 @@ export interface CredentialResolution {
 export interface CredentialAPI {
     resolve(request: CredentialResolveRequest): Promise<CredentialResolution | undefined>;
 }
+/** Session-scoped selected target for one capability. */
+export interface CapabilitySelectionSnapshotV1 {
+    readonly version: 1;
+    readonly capability: string;
+    readonly reference: string;
+    readonly provider: string;
+    readonly id: string;
+    readonly adapter?: string;
+    readonly options?: Readonly<Record<string, unknown>>;
+    readonly selectedAt: string;
+}
+/** Read-only view of one selected target against the current catalog. */
+export interface CapabilitySelectionViewV1 {
+    readonly capability: string;
+    readonly reference: string;
+    readonly provider: string;
+    readonly id: string;
+    readonly adapter?: string;
+    readonly options?: Readonly<Record<string, unknown>>;
+    readonly revision: number;
+    readonly available: boolean;
+    readonly error?: string;
+    readonly configChanged: boolean;
+    /** Capability-level `baseUrl` override from `capabilityConfig`, if set. */
+    readonly baseUrl?: string;
+    /** Effective provider/model base URL from the current catalog. */
+    readonly modelBaseUrl?: string;
+}
+export interface CapabilityCandidateViewV1 {
+    readonly capability: string;
+    readonly reference: string;
+    readonly provider: string;
+    readonly id: string;
+    readonly name?: string;
+    readonly adapter?: string;
+    readonly available: boolean;
+    readonly error?: string;
+}
+/**
+ * Host service: current session's selected target for a capability. Present
+ * only when the host supports capability selection. Plugins must not infer a
+ * target from the main model, provider ordering, or their own config.
+ */
+export interface CapabilitySelectionAPI {
+    get(capability: string): CapabilitySelectionViewV1 | undefined;
+}
+export interface ModelImageInputV1 {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
+export interface ModelInvocationTargetV1 {
+    readonly provider: string;
+    readonly id: string;
+}
+/** One isolated completion through the host's model runtime. No tools/session state. */
+export interface ModelInvocationRequestV1 {
+    readonly version: 1;
+    readonly target: ModelInvocationTargetV1;
+    /** Capability whose current `capabilityConfig` connection overrides
+     * (`baseUrl`, `headers`) apply to this call. Omit to use the model entry as is. */
+    readonly capability?: string;
+    readonly prompt: string;
+    readonly systemPrompt?: string;
+    readonly images?: readonly ModelImageInputV1[];
+    readonly maxTokens?: number;
+    /**
+     * Provider-native web search for this isolated call. `auto` asks the target's
+     * protocol adapter to inject its hosted search tool; the host rejects it when
+     * the target does not declare native search. `off`/absent leaves the request
+     * unchanged. Used by the search plugin's model mode and to keep URL
+     * summarization free of a second search path.
+     */
+    readonly webSearch?: "off" | "auto";
+}
+export type ModelInvocationResultV1 = {
+    readonly version: 1;
+    readonly status: "completed";
+    readonly text: string;
+    readonly model: ModelInvocationTargetV1;
+    readonly usage?: unknown;
+} | {
+    readonly version: 1;
+    readonly status: "cancelled";
+} | {
+    readonly version: 1;
+    readonly status: "failed";
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+/**
+ * Host service for an isolated model call against a registered target. The
+ * host resolves auth, model headers and transport; the plugin never sees
+ * credentials or provider SDK internals. Present only when the host declares
+ * `model-invocation-v1`.
+ */
+export interface ModelInvocationAPI {
+    complete(request: ModelInvocationRequestV1, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ModelInvocationResultV1>;
+}
 /**
  * Structural skill shape accepted by {@link BuildSystemPromptOptions.skills}
  * (D-075 S2). The host's full `Skill` type carries host-owned source facts;
@@ -946,6 +1117,14 @@ export type SessionMessageContent = string | ({
     data: string;
     mimeType: string;
 })[];
+/**
+ * How the TUI surfaces a message sent via {@link SessionAPI.sendMessage}.
+ * Absent means "transcript" (rendered as a transcript line); "notification"
+ * routes it to the host notice list instead and keeps it out of the
+ * transcript. Registered inline so this contract does not depend on host
+ * packages, same as {@link SessionMessageContent}.
+ */
+export type SessionMessagePresentation = "transcript" | "notification";
 export interface SessionAPI {
     getSessionId(): string;
     /**
@@ -990,6 +1169,12 @@ export interface SessionAPI {
     getScopedModels?(): readonly ScopedModelFactsViewV1[];
     /** Experimental (R3 model-domain slice): current thinking level. */
     getThinkingLevel?(): ThinkingLevel;
+    /**
+     * Experimental (native web-search slice): effective provider-native search mode for
+     * this session. Returns `auto` only when the child profile requested it and the
+     * current model declares native support; otherwise `off`.
+     */
+    getWebSearch?(): "off" | "auto";
     /** Experimental (R3 model-domain slice): set the thinking level. */
     setThinkingLevel?(level: ThinkingLevel): void;
     /** Experimental (R3 model-domain slice): set the session model by id (resolved against the scoped models). Resolves to false when the id is unknown or auth is not configured. */
@@ -1009,6 +1194,7 @@ export interface SessionAPI {
         customType: string;
         content: SessionMessageContent;
         display: boolean;
+        presentation?: SessionMessagePresentation;
     }, options?: {
         triggerTurn?: boolean;
     }): Promise<void>;
@@ -1268,8 +1454,18 @@ export interface AgentTaskChildProfileV1 {
     readonly thinkingLevel?: string;
     /** 工具面白名单：与宿主继承面求交；空数组表示"一个工具都不给"。 */
     readonly tools?: readonly string[];
+    /**
+     * 相对会话 cwd 的写入路径 glob（`/` 分隔；`**` 跨目录，`*` 不跨目录）。
+     * 缺席 = 不限制；空数组 = 不允许任何写入。只约束 `edit`/`write`，不约束 `bash`。
+     */
+    readonly writeScope?: readonly string[];
     /** 会话模式：`readonly` 只收窄不放宽（父会话已是 readonly 时保持 readonly）。 */
     readonly mode?: "readonly" | "full-control";
+    /**
+     * 本轮是否启用供应商原生（hosted）联网搜索。缺省 off；只有检索编排的原生轮次显式设
+     * auto，且目标模型必须声明 `webSearch.native === true`，否则宿主核验失败。
+     */
+    readonly webSearch?: "off" | "auto";
     /** 追加到子会话 system prompt 末尾的文本（不替换继承来的系统提示词）。 */
     readonly systemPromptAppend?: string;
     /**
@@ -1975,6 +2171,8 @@ export interface CapabilityAPI {
     /** Available when the host declares the `output-artifacts` feature. */
     readonly output?: OutputArtifactAPI;
     readonly credentials?: CredentialAPI;
+    readonly selection?: CapabilitySelectionAPI;
+    readonly modelInvocation?: ModelInvocationAPI;
     readonly agents?: AgentTaskAPI;
     /**
      * 宿主会话取消栅栏（D-044 §4.2）：getter 形态，按调用时刻返回当前 epoch 的