@webskill/sdk 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -6,6 +6,6 @@ import { $ as IntegrityVerdict, $n as diffUserProfile, $t as SessionMeta, A as D
  * Version of the published `@webskill/sdk` package, injected at build time.
  * @stable
  */
-declare const SDK_VERSION = "0.17.0";
+declare const SDK_VERSION = "0.19.0";
 //#endregion
 export { ALLOWED_TOOLS_EXCLUSION_REASON, ASK_USER_FIELD_TYPES, ASK_USER_INPUT_SCHEMA, ASK_USER_MAX_FIELDS, ASK_USER_TOOL, ASK_USER_TOOL_NAME, ATOMIC_TMP_SUFFIX_PATTERN, ATTACHMENT_TEXT_LIMIT, type ActivateLifecycleData, AgentLoop, type AgentLoopConfig, type AgentLoopDeps, AnthropicClient, type AnthropicClientConfig, type ApprovalDecision, type ApprovalScope, type ArchiveLimits, type Artifact, type ArtifactStore, type AttachmentTextInput, BEHAVIOR_RECORDS_KEY, type BehaviorRecord, type BehaviorRecordKind, type BehaviorScene, type BridgeCapabilities, type BridgeCapability, type BridgeRequest, type BridgeResponse, CapabilityApproval, type CapabilityMode, type CatalogRenderer, type ChartSpec, type ChatAttachmentKind, type CryptoKeyLike, DEFAULT_ARCHIVE_LIMITS, DEFAULT_LOOP_LIMITS, DEFAULT_MAX_DATA_SOURCE_BYTES, DEFAULT_MAX_DOCUMENT_BYTES, DEFAULT_MAX_DOCUMENT_TEXT_BYTES, DEFAULT_MAX_UPLOAD_FILE_BYTES, DEFAULT_USER_PROFILE_LIMITS, DOCX_MIME, type DataSourceInfo, type DiscoveryResult, type DocumentSurfaceHost, type DocumentSurfacePort, type DocxTextExtractor, EMPTY_USER_PROFILE, EventBus, type ExecuteLifecycleData, type ExternalSkillProvider, type ExternalToolSource, FILE_MIME_TYPES, FS_SESSION_PAGE_SIZE, type FileStat, type FileSystemProvider, type FormField, FsArtifactStore, FsMemoryStore, FsRunSnapshotStore, FsRunTraceStore, FsSessionStore, FsToolStepStore, FsTrustedKeyStore, FullDisclosureRouter, GoogleGenAiClient, type GoogleGenAiClientConfig, HookRunner, type HookRunnerOptions, IMAGE_MIME_TYPES, type InstalledSkillManifest, type IntegrityVerdict, type InteractLifecycleData, type InteractionOrigin, type InteractionPolicy, type InteractionRequest, type InteractionResponse, type JsonSchema, type LifecycleEvent, type LifecycleEventInit, type LifecycleHook, type LifecycleHookContext, type LifecycleListener, type LinkedDocumentReader, type LlmClient, type LlmCompleteInput, type LlmContentPart, type LlmMessage, type LlmResponse, type LlmStreamEvent, type LlmTokenUsage, type LlmToolCall, type LlmToolSpec, MANIFEST_EXCLUDED_FILES, MAX_TOOL_STEP_ARG_BYTES, MemoryFS, type MemoryStore, type NetworkPolicy, OpenAiCompatibleClient, type OpenAiCompatibleClientConfig, type Page, type PageQuery, type PdfTextExtractor, ProgressiveRouter, READ_LINKED_DOCUMENT_TOOL, READ_LINKED_DOCUMENT_TOOL_NAME, READ_SKILL_FILE_INPUT_SCHEMA, READ_SKILL_FILE_TOOL, READ_SKILL_FILE_TOOL_NAME, RUN_SNAPSHOT_SCHEMA_VERSION, RUN_TRACE_SCHEMA_VERSION, type RedactedArgs, type RefineUserProfileInput, type RemoteUrlPolicy, type RenderBlock, type RenderResultRequest, type RouteLifecycleData, type RouteResult, type RunLimitErrorDetails, type RunResult, type RunSnapshot, type RunSnapshotListEntry, type RunSnapshotStore, type RunTerminationReason, type RunToolCall, type RunTraceFile, type RunTraceFilter, type RunTraceMetrics, type RunTraceStore, type RunTraceSummary, type RunUploadFiles, type RunUsageSummary, type RuntimePhase, type RuntimeRun, type RuntimeSession, type RuntimeSessionHandle, SDK_VERSION, SENSITIVE_ANNOTATION, SESSION_SCHEMA_VERSION, SIGNATURE_SCHEMA_VERSION, SKILLS_LOCKFILE, SKILL_MANIFEST_FILE, SKILL_NAME_MAX_LENGTH, SKILL_NAME_PATTERN, SKILL_PACK_FILE, SKILL_SIGNATURE_FILE, SUPPORTED_DOCUMENT_MIME, type SchemaInferer, type ScriptExecutionContext, type ScriptExecutor, type SealOptions, type SealRecord, type SealResult, SerializingMemoryStore, type SessionListPage, type SessionMeta, type SessionRecord, type SessionStore, type SignatureAuditSink, type SignatureVerdict, type SkillArchiveDetection, type SkillArchiveShape, type SkillCandidateMarker, type SkillCatalog, type SkillCatalogEntry, SkillDiscovery, type SkillDocument, type SkillFailureReport, type SkillInstallSource, type SkillIntegrityGuard, type SkillIssue, type SkillLocation, type SkillManagerPort, type SkillManifest, type SkillMetadata, type SkillOutcomeReporter, type SkillPackManifest, SkillReader, type SkillRouter, type SkillScriptDescriptor, type SkillScriptSchemaSource, type SkillSignature, type SkillSource, type SkillStateGuard, type SkillSuccessReport, type SkillsLockfile, TEXT_BUDGETED_CONTENT_TYPES, TEXT_EXTENSIONS, type TerminalLifecycleData, type TextualToolContent, type TodoTraceEvent, type ToolCallContext, type ToolContent, type ToolDefinition, type ToolDisclosure, type ToolResolution, type ToolResult, type ToolStepReader, type ToolStepRecord, type ToolStepStore, type ToolStepTrust, type TraceClock, type TraceEvent, type TraceEventType, TraceRecorder, type TrustedKey, type TrustedKeyStore, UNSUPPORTED_DOCUMENT_MESSAGE, UNTRUSTED_LINE_LIMIT, UPLOAD_FILES_UNAVAILABLE, USER_PROFILE_EXPORT_VERSION, USER_PROFILE_KEY, USER_PROFILE_NO_INVENTION_RULE, USER_PROFILE_PROMPT_HEADER, USER_PROFILE_REFINE_PROMPT, type UiBridge, type UiSpecActionCapability, type UiSpecDrafts, type UiSpecEvent, type UiSpecNode, type UiSpecPatch, type UiSpecSnapshot, type UiSurfaceActionRequest, type UiSurfaceActionResponse, type UnsignedPolicy, type UnsupportedRunSnapshot, type UploadFileInfo, type UserProfile, type UserProfileEntry, type UserProfileExport, type UserProfileImportDiff, type UserProfileLimits, type ValidationReport, type VercelToolSpec, type VerifyResult, type WebSkillApi, WebSkillError, type WebSkillErrorCode, WebSkillRuntime, type WebSkillRuntimeDeps, XLSX_MIME, type XlsxTextExtractor, appendBehaviorRecords, applyUserProfileImport, assertRemoteUrlAllowed, assertSafePathSegment, atomicWriteText, bridgeError, buildCatalog, buildManifest, buildRenderResult, checkDependencyCycles, checkSkillRules, classifyAttachment, computeDigest, createScriptContext, createWebSkillApi, detectSkillArchiveShape, detectSkillArchiveShapeFromFs, diffUserProfile, escapeXml, exportSkills, exportUserProfile, extractChartSpec, extractSkillCandidate, extractTodoTraceEvents, extractUiSpecEvents, findUnpairedToolCalls, formatAttachmentText, formatSkillScriptManifest, fromVercelResult, fromVercelStreamPart, interruptedToolResult, isAtomicTempPath, isNetworkAllowed, isUnsupportedRunSnapshot, isValidSkillName, jsonRenderer, keyIdOf, listSkillScripts, mergeCatalogEntries, mergeProfileEntries, messageOf, networkPolicyLibSource, networkUrlHost, normalizeErrorCode, normalizePath, normalizeToolContent, normalizeToolError, parseBridgeRequest, parseSkillMarkdown, parseSkillPackManifest, parseUserProfileExport, partsToText, readBehaviorRecords, readProfileEntries, readResponseWithLimit, readSkillSignature, readUserProfile, redactToolStepArgs, refineUserProfile, renderAvailableSkillsXml, renderCatalogJson, renderUserProfileContext, resolveArchiveLimits, resolveInsideRoot, resolveToolName, sampleBehaviorRecords, sanitizeUntrustedLine, schemaSourceLabel, schemaToForm, scriptToolName, sealToolCallPairs, signSkill, signaturePayloadBytes, stripArchiveRoot, summarizeRunUsage, summarizeToolCalls, textParts, toBase64, toLlmToolSpec, toRecordDigests, toVercelToolSpecs, unzipWithLimits, validateSkills, validateUiSpecEvent, validateUiSpecNode, verifyManifest, verifySkillSignature, xmlRenderer };

package/dist/index.js

@@ -3,13 +3,13 @@ import { A as SKILL_MANIFEST_FILE, C as keyIdOf, D as verifySkillSignature, E as
 import { a as atomicWriteText, i as ATOMIC_TMP_SUFFIX_PATTERN, n as normalizePath, o as isAtomicTempPath, r as resolveInsideRoot, t as assertSafePathSegment } from "./pathSecurity-B1owvJAF.js";
 import { t as assertRemoteUrlAllowed } from "./urlSafety-CiSuCJvX.js";
 import { a as TEXT_EXTENSIONS, c as formatAttachmentText, i as IMAGE_MIME_TYPES, l as UNTRUSTED_LINE_LIMIT, n as DOCX_MIME, o as XLSX_MIME, r as FILE_MIME_TYPES, s as classifyAttachment, t as ATTACHMENT_TEXT_LIMIT, u as sanitizeUntrustedLine } from "./kind-DxgS8LM-.js";
-import { $ as scriptToolName, A as readUserProfile, B as createScriptContext, C as TraceRecorder, D as mergeProfileEntries, E as appendBehaviorRecords, F as DEFAULT_USER_PROFILE_LIMITS, G as ASK_USER_TOOL_NAME, H as ASK_USER_INPUT_SCHEMA, I as EMPTY_USER_PROFILE, J as READ_SKILL_FILE_TOOL_NAME, K as READ_SKILL_FILE_INPUT_SCHEMA, L as SerializingMemoryStore, M as USER_PROFILE_NO_INVENTION_RULE, N as USER_PROFILE_PROMPT_HEADER, O as readBehaviorRecords, P as renderUserProfileContext, Q as schemaSourceLabel, R as EventBus, S as extractTodoTraceEvents, T as USER_PROFILE_KEY, U as ASK_USER_MAX_FIELDS, V as ASK_USER_FIELD_TYPES, W as ASK_USER_TOOL, X as formatSkillScriptManifest, Y as ALLOWED_TOOLS_EXCLUSION_REASON, Z as listSkillScripts, _ as RUN_SNAPSHOT_SCHEMA_VERSION, a as networkPolicyLibSource, at as xmlRenderer, b as MAX_TOOL_STEP_ARG_BYTES, c as bridgeError, d as FsMemoryStore, et as resolveToolName, f as WebSkillRuntime, g as FsRunSnapshotStore, h as redactToolStepArgs, i as isNetworkAllowed, it as renderAvailableSkillsXml, j as sampleBehaviorRecords, k as readProfileEntries, l as parseBridgeRequest, m as SENSITIVE_ANNOTATION, n as normalizeErrorCode, nt as ProgressiveRouter, o as networkUrlHost, p as AgentLoop, q as READ_SKILL_FILE_TOOL, r as normalizeToolError, rt as escapeXml, s as UPLOAD_FILES_UNAVAILABLE, t as CapabilityApproval, tt as toLlmToolSpec, u as FsArtifactStore, v as isUnsupportedRunSnapshot, w as BEHAVIOR_RECORDS_KEY, x as extractSkillCandidate, y as DEFAULT_LOOP_LIMITS, z as schemaToForm } from "./approval-CBPnGPIm.js";
-import { a as GoogleGenAiClient, c as findUnpairedToolCalls, d as partsToText, f as promptText, i as toVercelToolSpecs, l as interruptedToolResult, n as fromVercelResult, o as AnthropicClient, p as textParts, r as fromVercelStreamPart, s as OpenAiCompatibleClient, u as sealToolCallPairs } from "./llm-B7lLH0ZI.js";
+import { $ as scriptToolName, A as readUserProfile, B as createScriptContext, C as TraceRecorder, D as mergeProfileEntries, E as appendBehaviorRecords, F as DEFAULT_USER_PROFILE_LIMITS, G as ASK_USER_TOOL_NAME, H as ASK_USER_INPUT_SCHEMA, I as EMPTY_USER_PROFILE, J as READ_SKILL_FILE_TOOL_NAME, K as READ_SKILL_FILE_INPUT_SCHEMA, L as SerializingMemoryStore, M as USER_PROFILE_NO_INVENTION_RULE, N as USER_PROFILE_PROMPT_HEADER, O as readBehaviorRecords, P as renderUserProfileContext, Q as schemaSourceLabel, R as EventBus, S as extractTodoTraceEvents, T as USER_PROFILE_KEY, U as ASK_USER_MAX_FIELDS, V as ASK_USER_FIELD_TYPES, W as ASK_USER_TOOL, X as formatSkillScriptManifest, Y as ALLOWED_TOOLS_EXCLUSION_REASON, Z as listSkillScripts, _ as RUN_SNAPSHOT_SCHEMA_VERSION, a as networkPolicyLibSource, at as xmlRenderer, b as MAX_TOOL_STEP_ARG_BYTES, c as bridgeError, d as FsMemoryStore, et as resolveToolName, f as WebSkillRuntime, g as FsRunSnapshotStore, h as redactToolStepArgs, i as isNetworkAllowed, it as renderAvailableSkillsXml, j as sampleBehaviorRecords, k as readProfileEntries, l as parseBridgeRequest, m as SENSITIVE_ANNOTATION, n as normalizeErrorCode, nt as ProgressiveRouter, o as networkUrlHost, p as AgentLoop, q as READ_SKILL_FILE_TOOL, r as normalizeToolError, rt as escapeXml, s as UPLOAD_FILES_UNAVAILABLE, t as CapabilityApproval, tt as toLlmToolSpec, u as FsArtifactStore, v as isUnsupportedRunSnapshot, w as BEHAVIOR_RECORDS_KEY, x as extractSkillCandidate, y as DEFAULT_LOOP_LIMITS, z as schemaToForm } from "./approval-Bbh_Apwg.js";
+import { a as GoogleGenAiClient, c as findUnpairedToolCalls, d as partsToText, f as promptText, i as toVercelToolSpecs, l as interruptedToolResult, n as fromVercelResult, o as AnthropicClient, p as textParts, r as fromVercelStreamPart, s as OpenAiCompatibleClient, u as sealToolCallPairs } from "./llm-eIQNO9tr.js";
 import { c as DEFAULT_MAX_DOCUMENT_BYTES, d as TEXT_BUDGETED_CONTENT_TYPES, i as UNSUPPORTED_DOCUMENT_MESSAGE, l as DEFAULT_MAX_DOCUMENT_TEXT_BYTES, n as READ_LINKED_DOCUMENT_TOOL_NAME, o as toBase64, r as SUPPORTED_DOCUMENT_MIME, s as DEFAULT_MAX_DATA_SOURCE_BYTES, t as READ_LINKED_DOCUMENT_TOOL, u as DEFAULT_MAX_UPLOAD_FILE_BYTES } from "./linkedDocument-xNXF-z8n.js";
 import { n as normalizeToolContent, t as mergeCatalogEntries } from "./external-_ZRQe-V9.js";
 import { n as extractChartSpec, t as buildRenderResult } from "./renderResult-D9Q-Vu2x.js";
 import { n as validateUiSpecEvent, r as validateUiSpecNode, t as extractUiSpecEvents } from "./surface-DVGiCmwq.js";
-import { t as createWebSkillApi } from "./webSkillApi-Ce2OO5S5.js";
+import { t as createWebSkillApi } from "./webSkillApi-CsvA69qk.js";
 
 //#region ../core/src/fs/memoryFs.ts
 const ROOT = "/";
@@ -1004,7 +1004,7 @@ var FsToolStepStore = class {
 * Version of the published `@webskill/sdk` package, injected at build time.
 * @stable
 */
-const SDK_VERSION = "0.17.0";
+const SDK_VERSION = "0.19.0";
 
 //#endregion
 export { ALLOWED_TOOLS_EXCLUSION_REASON, ASK_USER_FIELD_TYPES, ASK_USER_INPUT_SCHEMA, ASK_USER_MAX_FIELDS, ASK_USER_TOOL, ASK_USER_TOOL_NAME, ATOMIC_TMP_SUFFIX_PATTERN, ATTACHMENT_TEXT_LIMIT, AgentLoop, AnthropicClient, BEHAVIOR_RECORDS_KEY, CapabilityApproval, DEFAULT_ARCHIVE_LIMITS, DEFAULT_LOOP_LIMITS, DEFAULT_MAX_DATA_SOURCE_BYTES, DEFAULT_MAX_DOCUMENT_BYTES, DEFAULT_MAX_DOCUMENT_TEXT_BYTES, DEFAULT_MAX_UPLOAD_FILE_BYTES, DEFAULT_USER_PROFILE_LIMITS, DOCX_MIME, EMPTY_USER_PROFILE, EventBus, FILE_MIME_TYPES, FS_SESSION_PAGE_SIZE, FsArtifactStore, FsMemoryStore, FsRunSnapshotStore, FsRunTraceStore, FsSessionStore, FsToolStepStore, FsTrustedKeyStore, FullDisclosureRouter, GoogleGenAiClient, HookRunner, IMAGE_MIME_TYPES, MANIFEST_EXCLUDED_FILES, MAX_TOOL_STEP_ARG_BYTES, MemoryFS, OpenAiCompatibleClient, ProgressiveRouter, READ_LINKED_DOCUMENT_TOOL, READ_LINKED_DOCUMENT_TOOL_NAME, READ_SKILL_FILE_INPUT_SCHEMA, READ_SKILL_FILE_TOOL, READ_SKILL_FILE_TOOL_NAME, RUN_SNAPSHOT_SCHEMA_VERSION, RUN_TRACE_SCHEMA_VERSION, SDK_VERSION, SENSITIVE_ANNOTATION, SESSION_SCHEMA_VERSION, SIGNATURE_SCHEMA_VERSION, SKILLS_LOCKFILE, SKILL_MANIFEST_FILE, SKILL_NAME_MAX_LENGTH, SKILL_NAME_PATTERN, SKILL_PACK_FILE, SKILL_SIGNATURE_FILE, SUPPORTED_DOCUMENT_MIME, SerializingMemoryStore, SkillDiscovery, SkillReader, TEXT_BUDGETED_CONTENT_TYPES, TEXT_EXTENSIONS, TraceRecorder, UNSUPPORTED_DOCUMENT_MESSAGE, UNTRUSTED_LINE_LIMIT, UPLOAD_FILES_UNAVAILABLE, USER_PROFILE_EXPORT_VERSION, USER_PROFILE_KEY, USER_PROFILE_NO_INVENTION_RULE, USER_PROFILE_PROMPT_HEADER, USER_PROFILE_REFINE_PROMPT, WebSkillError, WebSkillRuntime, XLSX_MIME, appendBehaviorRecords, applyUserProfileImport, assertRemoteUrlAllowed, assertSafePathSegment, atomicWriteText, bridgeError, buildCatalog, buildManifest, buildRenderResult, checkDependencyCycles, checkSkillRules, classifyAttachment, computeDigest, createScriptContext, createWebSkillApi, detectSkillArchiveShape, detectSkillArchiveShapeFromFs, diffUserProfile, escapeXml, exportSkills, exportUserProfile, extractChartSpec, extractSkillCandidate, extractTodoTraceEvents, extractUiSpecEvents, findUnpairedToolCalls, formatAttachmentText, formatSkillScriptManifest, fromVercelResult, fromVercelStreamPart, interruptedToolResult, isAtomicTempPath, isNetworkAllowed, isUnsupportedRunSnapshot, isValidSkillName, jsonRenderer, keyIdOf, listSkillScripts, mergeCatalogEntries, mergeProfileEntries, messageOf, networkPolicyLibSource, networkUrlHost, normalizeErrorCode, normalizePath, normalizeToolContent, normalizeToolError, parseBridgeRequest, parseSkillMarkdown, parseSkillPackManifest, parseUserProfileExport, partsToText, readBehaviorRecords, readProfileEntries, readResponseWithLimit, readSkillSignature, readUserProfile, redactToolStepArgs, refineUserProfile, renderAvailableSkillsXml, renderCatalogJson, renderUserProfileContext, resolveArchiveLimits, resolveInsideRoot, resolveToolName, sampleBehaviorRecords, sanitizeUntrustedLine, schemaSourceLabel, schemaToForm, scriptToolName, sealToolCallPairs, signSkill, signaturePayloadBytes, stripArchiveRoot, summarizeRunUsage, summarizeToolCalls, textParts, toBase64, toLlmToolSpec, toRecordDigests, toVercelToolSpecs, unzipWithLimits, validateSkills, validateUiSpecEvent, validateUiSpecNode, verifyManifest, verifySkillSignature, xmlRenderer };

package/dist/{llm-B7lLH0ZI.js → llm-eIQNO9tr.js}

@@ -809,6 +809,44 @@ const toOpenAiTools = (tools) => tools.map((tool) => ({
 	}
 }));
 const errorMessage$2 = (e) => e instanceof Error ? e.message : String(e);
+/** 错误正文只给能定位问题的开头一段，整份上游响应仍在 cause 里 */
+const DETAIL_LIMIT = 500;
+/**
+* 2xx 响应体里的业务错误文本。兼容端点在「HTTP 成功但业务失败」时的三种常见形态：
+* OpenAI `{error:{message}}`、Ollama `{error:"..."}`、vLLM `{object:"error",message:"..."}`。
+*/
+const upstreamErrorText = (data) => {
+	if (typeof data !== "object" || data === null) return void 0;
+	const record = data;
+	const error = record["error"];
+	if (typeof error === "string" && error !== "") return error;
+	if (typeof error === "object" && error !== null) {
+		const message = error["message"];
+		if (typeof message === "string" && message !== "") return message;
+	}
+	const top = record["message"];
+	if (record["object"] === "error" && typeof top === "string" && top !== "") return top;
+};
+const parseJsonOrUndefined = (text) => {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+};
+/**
+* 错误正文会进 trace 与控制台，而网关形态的 baseUrl 里常带凭据
+* （`https://user:pass@host`、`?api-key=...`）。报 URL 只为了让宿主认出自己指错了地方，
+* origin + pathname 已经够；解不出来的就原样给回（那就不是一个能藏凭据的 URL）。
+*/
+const redactUrl = (url) => {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return url;
+	}
+};
 /** OpenAI chat completions 协议客户端（兼容端点通用） */
 var OpenAiCompatibleClient = class {
 	#config;
@@ -827,19 +865,19 @@ var OpenAiCompatibleClient = class {
 		};
 	}
 	async complete(input) {
-		const res = await this.#postChat(input, false);
+		const { res, endpoint } = await this.#postChat(input, false);
 		let data;
 		try {
 			data = await res.json();
 		} catch (e) {
-			throw new WebSkillError("LLM_REQUEST_FAILED", `Failed to parse LLM response: ${errorMessage$2(e)}`, e);
+			throw new WebSkillError("LLM_REQUEST_FAILED", `Failed to parse the LLM response from ${endpoint}: ${errorMessage$2(e)}`, e);
 		}
-		return this.#parseResponse(data);
+		return this.#parseResponse(data, endpoint);
 	}
 	/** SSE 流式：fetch + ReadableStream 按行解析 data: 帧（Node/浏览器通用） */
 	async *stream(input) {
-		const res = await this.#postChat(input, true);
-		if (!res.body) throw new WebSkillError("LLM_REQUEST_FAILED", "LLM streaming response has no body");
+		const { res, endpoint } = await this.#postChat(input, true);
+		if (!res.body) throw new WebSkillError("LLM_REQUEST_FAILED", `The LLM streaming response from ${endpoint} has no body`);
 		const toolCallsByIndex = /* @__PURE__ */ new Map();
 		const decoder = new TextDecoder();
 		const reader = res.body.getReader();
@@ -847,6 +885,8 @@ var OpenAiCompatibleClient = class {
 		const think = createThinkTagSplitter();
 		let done = false;
 		let usage;
+		let sawFrame = false;
+		let head = "";
 		const handleFrame = function* (data) {
 			if (data === "[DONE]") {
 				done = true;
@@ -897,7 +937,10 @@ var OpenAiCompatibleClient = class {
 		try {
 			for (;;) {
 				const { value, done: readerDone } = await reader.read();
-				const payloads = readerDone ? frames.flush() : frames.push(decoder.decode(value, { stream: true }));
+				const text = readerDone ? "" : decoder.decode(value, { stream: true });
+				const payloads = readerDone ? frames.flush() : frames.push(text);
+				if (payloads.length > 0) sawFrame = true;
+				else if (!sawFrame && head.length < DETAIL_LIMIT) head += text;
 				for (const payload of payloads) {
 					yield* handleFrame(payload);
 					if (done) break;
@@ -907,6 +950,10 @@ var OpenAiCompatibleClient = class {
 		} finally {
 			reader.releaseLock();
 		}
+		if (!sawFrame) {
+			const upstream = upstreamErrorText(parseJsonOrUndefined(head));
+			throw new WebSkillError("LLM_REQUEST_FAILED", upstream === void 0 ? `The LLM stream from ${endpoint} carried no data frames; the endpoint answered HTTP 200 but not an event stream${head === "" ? "" : `: ${head.slice(0, DETAIL_LIMIT)}`}` : `The endpoint ${endpoint} answered HTTP 200 with an error instead of a stream: ${upstream.slice(0, DETAIL_LIMIT)}`, head);
+		}
 		const tail = think.flush();
 		if (tail.thinking !== "") yield {
 			type: "thinking-delta",
@@ -955,9 +1002,11 @@ var OpenAiCompatibleClient = class {
 			body["stream"] = true;
 			body["stream_options"] = { include_usage: true };
 		}
+		const endpoint = `${baseUrl}/chat/completions`;
+		const shown = redactUrl(endpoint);
 		let res;
 		try {
-			res = await this.#fetch(`${baseUrl}/chat/completions`, {
+			res = await this.#fetch(endpoint, {
 				method: "POST",
 				headers: {
 					"content-type": "application/json",
@@ -967,13 +1016,16 @@ var OpenAiCompatibleClient = class {
 				signal: input.signal ?? (this.#config.requestTimeoutMs ? AbortSignal.timeout(this.#config.requestTimeoutMs) : null)
 			});
 		} catch (e) {
-			throw new WebSkillError("LLM_REQUEST_FAILED", `LLM request failed: ${errorMessage$2(e)}`, e);
+			throw new WebSkillError("LLM_REQUEST_FAILED", `The LLM request to ${shown} failed: ${errorMessage$2(e)}`, e);
 		}
 		if (!res.ok) {
 			const detail = await res.text().catch(() => "");
-			throw new WebSkillError("LLM_REQUEST_FAILED", `LLM request failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`, { status: res.status });
+			throw new WebSkillError("LLM_REQUEST_FAILED", `The LLM request to ${shown} failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, DETAIL_LIMIT)}` : ""}`, { status: res.status });
 		}
-		return res;
+		return {
+			res,
+			endpoint: shown
+		};
 	}
 	/** 轻量探测（GET /models），集成测试据此决定 skip */
 	async checkAvailability() {
@@ -984,10 +1036,13 @@ var OpenAiCompatibleClient = class {
 			return false;
 		}
 	}
-	#parseResponse(data) {
+	#parseResponse(data, endpoint) {
 		try {
 			const choice = data.choices?.[0]?.message;
-			if (!choice) throw new Error("response has no choices[0].message");
+			if (!choice) {
+				const upstream = upstreamErrorText(data);
+				throw new Error(upstream === void 0 ? `the response from ${endpoint} has no choices[0].message` : `the endpoint ${endpoint} answered HTTP 200 with an error instead of a completion: ${upstream.slice(0, DETAIL_LIMIT)}`);
+			}
 			const toolCalls = choice["tool_calls"]?.map((tc) => {
 				let args = {};
 				let parseError;

package/dist/mcp.d.ts

@@ -568,4 +568,280 @@ interface RemoteEndpointHandle {
  */
 declare function connectRemoteEndpoint(registry: EndpointRegistry<McpClientLike>, config: RemoteEndpointConfig): Promise<RemoteEndpointHandle>;
 //#endregion
-export { type BrowserModelContextLike, EndpointRegistry, ExperimentalWebMcpAdapter, type McpClientLike, type McpOAuthClient, type McpOAuthConfig, type McpOAuthHandshake, type McpOAuthHandshakeStore, type McpOAuthProvider, type McpOAuthStage, type McpOAuthTokenStore, type McpOAuthTokens, McpRuntimePlugin, type McpSourceTrust, type McpToolDisclosure, McpToolResolver, type McpToolVisibility, MessageChannelTransport, type MessageChannelTransportOptions, type MessagePortLike, PAGE_HOST_ANCHOR_KEY, type PageHostAnchor, type RemoteEndpointConfig, type RemoteEndpointHandle, type ServedSkill, TemporarySkillProvider, type TransportState, WEB_MCP_SOURCE_ID_MAX, type WebMcpToolDescriptor, type WebMcpToolLike, catalogMerge, connectRemoteEndpoint, createMemoryOAuthStores, createOAuthProvider, declareDataSourcesToPageHost, endpointToolLlmName, notifyPageHost, parseEndpointToolLlmName, parseWebMcpToolLlmName, serveSkillAsMcp, validateJsonRpcMessage, webMcpToolLlmName };
+//#region src/pageHost/mcpVisibilityStore.d.ts
+/**
+ * 启停与披露的状态存储（0.19.0 分册 10 · FR-10.3）。
+ *
+ * 做成注入点，是因为四份宿主的存量键各不相同：默认实现统一键形之后，
+ * 不接受「禁用名单不迁移」代价的接入方可以自己实现一份读旧键的。
+ *
+ * **WebMCP 工具用保留端点名 `'webmcp'`**，不再走 `webmcp:` 前缀混进同一张名单。
+ */
+interface McpVisibilityStore {
+  isEndpointEnabled(endpoint: string): boolean;
+  setEndpointEnabled(endpoint: string, enabled: boolean): void;
+  isToolEnabled(endpoint: string, tool: string): boolean;
+  setToolEnabled(endpoint: string, tool: string, enabled: boolean): void;
+  toolDisclosure(endpoint: string, tool: string): McpToolDisclosure;
+  setToolDisclosure(endpoint: string, tool: string, value: McpToolDisclosure): void;
+  isWebMcpEnabled(): boolean;
+  setWebMcpEnabled(enabled: boolean): void;
+}
+/** WebMCP 在名单里占用的保留端点名 */
+declare const WEB_MCP_ENDPOINT = "webmcp";
+/**
+ * localStorage 默认实现。键形：
+ * `<ns>.mcp.endpoints-disabled` / `<ns>.mcp.tools-disabled` /
+ * `<ns>.mcp.tools-on-demand` / `<ns>.webmcp-enabled`。
+ *
+ * 名单里的工具**一律带 endpoint**（`<endpoint>/<tool>`）。旧实现存裸工具名，
+ * 两个端点注册同名工具时禁用其一会连坐另一个——那个缺陷在这里一次修完。
+ *
+ * 一律实时读存储、不做进程内缓存：console 改完当轮生效是既有语义。
+ */
+declare function createLocalStorageMcpVisibility(namespace: string): McpVisibilityStore;
+//#endregion
+//#region src/pageHost/createPageMcpEndpoint.d.ts
+/**
+ * 进程内 MCP 端点装配（0.19.0 分册 10）。
+ *
+ * 把页面工具与页面临时技能经**真实 MCP 通道**供给对话运行时：治理面（启停、披露）
+ * 因此对 chatbot 与 console 同时生效，而不是两张皮。
+ *
+ * 这段装配有三处必须写对、宿主各自手写时反复写错的地方，全部收在这里：
+ * (a) `MessagePort` 一经转移就归对方所有 → 每次挂载新建 `MessageChannel`；
+ * (b) 先建后换 → `registry.set`（不是 `register`），且新通道握手成功后才关旧的；
+ * (c) 串行化 → `catch` 必须在 `then` **之前**，否则一次失败会让此后每次重挂被静默跳过。
+ */
+/** 页面工具的统一形态：裸返回值由 SDK 裹成 MCP 的 content / structuredContent */
+interface PageMcpTool {
+  spec: LlmToolSpec;
+  run(args: Record<string, unknown>): Promise<unknown> | unknown;
+}
+type Supplier<T> = readonly T[] | (() => readonly T[]);
+interface PageMcpEndpointOptions {
+  /** 端点名（进入 LLM 可见的工具名前缀） */
+  endpoint: string;
+  /**
+   * 工具清单。函数形态用于「清单随宿主状态变化」的场景；
+   * 每次 `serve()` 重新求值。
+   */
+  tools: Supplier<PageMcpTool>;
+  /** 当前该端点暴露的临时技能；换屏即换一批，用函数形态 */
+  skills?: Supplier<ServedSkill>;
+  /** 启停与披露状态；缺省用 `createLocalStorageMcpVisibility(endpoint)` */
+  visibility?: McpVisibilityStore;
+  /**
+   * WebMCP 通道。缺省自建一个解析 `document.modelContext ?? navigator.modelContext`
+   * 的适配器；`false` 显式关闭（Node 宿主、无 DOM 环境）。
+   */
+  webMcp?: ExperimentalWebMcpAdapter | readonly ExperimentalWebMcpAdapter[] | false;
+  /**
+   * 参数留存的信任声明（分册 30 / FR-30.6）。缺省不声明任何来源可信，
+   * 于是本端点每个工具的入参都按 `untrusted` 全量脱敏——由此生成的技能参数为空。
+   * 宿主自己写的页面工具若已审查过 inputSchema，显式声明 `isEndpointTrusted` 才留存。
+   */
+  trust?: McpSourceTrust;
+  /** 透传给 `ExternalToolSource.systemPrompt`（已有扩展点，本册不改语义） */
+  systemPrompt?: () => Promise<string | undefined>;
+  serverInfo?: {
+    name?: string;
+    version?: string;
+  };
+  clientInfo?: {
+    name?: string;
+    version?: string;
+  };
+  onWarning?: (message: string) => void;
+}
+interface PageMcpEndpoint {
+  /** 端点名（门面与 console 都要用它区分内置端点与远程端点） */
+  readonly endpoint: string;
+  readonly registry: EndpointRegistry<McpClientLike>;
+  readonly plugin: McpRuntimePlugin;
+  readonly pageSkills: TemporarySkillProvider;
+  /** 缺省或宿主注入的 WebMCP 适配器；`webMcp: false` 时为 undefined */
+  readonly webmcp: ExperimentalWebMcpAdapter | undefined;
+  /** 全部 WebMCP 来源（分册 26：主文档与各嵌入页各算一个，**不合并**） */
+  readonly webMcpSources: readonly ExperimentalWebMcpAdapter[];
+  /** chatbot adapter 的 pageSkillSource：工具源 + 技能提供者的合体对象 */
+  readonly toolSource: ExternalToolSource & ExternalSkillProvider;
+  readonly visibility: McpVisibilityStore;
+  /**
+   * 首次挂载完成。**失败也 resolve**：读 registry 的一侧按现状继续，
+   * 不能因为一次挂载失败被永久挂起。
+   */
+  readonly ready: Promise<void>;
+  /** 重新挂载当前工具/技能清单；幂等且串行 */
+  serve(): Promise<void>;
+  /** 关闭当前通道并从 registry 注销 */
+  close(): Promise<void>;
+}
+declare function createPageMcpEndpoint(options: PageMcpEndpointOptions): PageMcpEndpoint;
+//#endregion
+//#region src/pageHost/createConnectFacade.d.ts
+/**
+ * console 连接页的门面实现（0.19.0 分册 11）。
+ *
+ * 这里**不 import `@webskill/console` 的类型**，只声明结构等价的形状：
+ * 让 `@webskill/mcp` 依赖 console 会倒转依赖边（console 的 peer 里已经有 sdk）。
+ * 代价是 console 给 `ConnectFacade` 加必填方法时这里不会红，因此
+ * 「宿主侧真实赋值」的守卫测试是本方案成立的前提，不是可选项（同 0.8.0 D-18）。
+ */
+/** 结构等价于 `ConnectEndpointConfig` */
+interface ConnectEndpointConfigShape {
+  name: string;
+  url: string;
+  transport?: 'streamable-http' | 'sse';
+  headers?: Record<string, string>;
+  allowHttp?: boolean;
+  allowPrivateHosts?: boolean;
+  oauth?: {
+    clientId: string;
+    redirectUri: string;
+    scopes?: string[];
+  };
+  enabled?: boolean;
+  disabledTools?: string[];
+  disclosure?: 'always' | 'on-demand';
+}
+/** 结构等价于 `ConnectEndpointView` */
+interface ConnectEndpointViewShape {
+  config: ConnectEndpointConfigShape;
+  status: 'connected' | 'failed' | 'unavailable' | 'connecting';
+  error?: string;
+  toolCount?: number;
+}
+/** 结构等价于 `ConnectToolView` */
+interface ConnectToolViewShape {
+  endpoint: string;
+  name: string;
+  description?: string;
+  schemaSummary?: string;
+  inputSchema?: unknown;
+  origin?: string;
+  annotations?: {
+    untrustedContentHint?: boolean;
+  };
+  enabled?: boolean;
+  disclosure?: 'always' | 'on-demand';
+}
+/** 结构等价于 `ConnectTemporarySkill` */
+interface ConnectTemporarySkillShape {
+  name: string;
+  description?: string;
+  source?: string;
+  origin?: string;
+}
+/** 结构等价于 `ConnectTemporarySkillDetail` */
+interface ConnectTemporarySkillDetailShape {
+  name: string;
+  description?: string;
+  source?: string;
+  origin?: string;
+  body: string;
+  metadata?: Record<string, unknown>;
+}
+/** 结构等价于 `ConnectTestResult` */
+interface ConnectTestResultShape {
+  ok: boolean;
+  latencyMs: number;
+  error?: string;
+  detail?: string;
+  checkedAt?: string;
+}
+/** 结构等价于 `ConnectWebMcpSource` */
+interface ConnectWebMcpSourceShape {
+  id?: string;
+  label?: string;
+  isAvailable(): boolean;
+  isEnabled(): boolean;
+  setEnabled(on: boolean): void;
+  listTools(): Promise<ConnectToolViewShape[]>;
+  setToolEnabled?(tool: string, enabled: boolean): void;
+  setToolDisclosure?(tool: string, disclosure: 'always' | 'on-demand'): void;
+}
+/** 结构等价于 `ConnectFacade` */
+interface ConnectFacadeShape {
+  listEndpoints(): Promise<ConnectEndpointViewShape[]>;
+  addEndpoint(config: ConnectEndpointConfigShape): Promise<void>;
+  removeEndpoint(name: string): Promise<void>;
+  reconnect(name: string): Promise<void>;
+  listTools(): Promise<ConnectToolViewShape[]>;
+  testEndpoint(name: string): Promise<ConnectTestResultShape>;
+  temporarySkills(): Promise<ConnectTemporarySkillShape[]>;
+  temporarySkillDetail?(name: string, origin?: string): Promise<ConnectTemporarySkillDetailShape>;
+  pagePerception?(): Promise<ConnectPerceptionViewShape>;
+  pageActionConsents?(): Promise<readonly ConnectPageActionConsentViewShape[]>;
+  forgetPageActionConsent?(id: string): Promise<void>;
+  forgetPageActionConsentScope?(scope: string): Promise<void>;
+  setEndpointEnabled?(name: string, enabled: boolean): Promise<void>;
+  setToolEnabled?(endpoint: string, tool: string, enabled: boolean): Promise<void>;
+  setToolDisclosure?(endpoint: string, tool: string, disclosure: 'always' | 'on-demand'): Promise<void>;
+  webmcp: ConnectWebMcpSourceShape & {
+    sources?: readonly ConnectWebMcpSourceShape[];
+  };
+}
+/** 结构等价于 `ConnectPerceptionView` */
+interface ConnectPerceptionViewShape {
+  enabled: boolean;
+  include: readonly string[];
+  exclude?: readonly string[];
+  records: readonly {
+    at: string;
+    include: readonly string[];
+    exclude?: readonly string[];
+    nodeCount: number;
+    imageCount?: number;
+    imagesOmitted?: number;
+    imageFailures?: number;
+  }[];
+  actionScope?: {
+    include: readonly string[];
+    exclude?: readonly string[];
+  };
+}
+/** 结构等价于 `ConnectPageActionConsentView` */
+interface ConnectPageActionConsentViewShape {
+  id: string;
+  scope: string;
+  action: string;
+  grantedAt?: string;
+}
+/** 远程端点配置的持久化端口 */
+interface RemoteEndpointStore {
+  load(): ConnectEndpointConfigShape[];
+  save(configs: ConnectEndpointConfigShape[]): void;
+}
+interface PageActionConsentStore {
+  list(): Promise<readonly ConnectPageActionConsentViewShape[]>;
+  forget(id: string): Promise<void>;
+  forgetScope(scope: string): Promise<void>;
+}
+interface ConnectFacadeOptions {
+  /** 分册 10 的端点句柄 */
+  host: PageMcpEndpoint;
+  /** 内置端点在连接页显示的 url 串；缺省 `in-process://<endpoint>` */
+  builtinEndpointUrl?: string;
+  /**
+   * 远程端点存储。`false` = 这个宿主不支持手工加端点（浏览器扩展：端点由页面给），
+   * 此时 add/remove 抛说明式的 `TOOL_UNSUPPORTED`，而不是给个能点但必然失败的按钮。
+   */
+  remoteEndpoints?: RemoteEndpointStore | false;
+  /**
+   * 已**声明**的临时技能（不是当前服务状态）。技能随屏生灭，
+   * 只反映当前活跃端点会让用户切屏后看到空列表、以为技能丢了。
+   * 不注入时回落到 `host.pageSkills.listSkills()`——那是服务状态，语义不同。
+   */
+  temporarySkills?: () => Promise<ConnectTemporarySkillShape[]> | ConnectTemporarySkillShape[];
+  temporarySkillDetail?: (name: string, origin?: string) => Promise<ConnectTemporarySkillDetailShape> | ConnectTemporarySkillDetailShape;
+  /** 页面只读感知视图；不注入时 `pagePerception` 方法整体缺席 */
+  pagePerception?: () => Promise<ConnectPerceptionViewShape> | ConnectPerceptionViewShape;
+  /** 页面操作授权存储；不注入时三个 consent 方法整体缺席 */
+  pageActionConsent?: PageActionConsentStore;
+}
+/** localStorage 版远程端点存储（键 `<ns>.mcp.remote-endpoints`） */
+declare function createLocalStorageRemoteEndpoints(namespace: string): RemoteEndpointStore;
+declare function createConnectFacade(options: ConnectFacadeOptions): ConnectFacadeShape;
+//#endregion
+export { type BrowserModelContextLike, type ConnectEndpointConfigShape, type ConnectEndpointViewShape, type ConnectFacadeOptions, type ConnectFacadeShape, type ConnectPageActionConsentViewShape, type ConnectPerceptionViewShape, type ConnectTemporarySkillDetailShape, type ConnectTemporarySkillShape, type ConnectTestResultShape, type ConnectToolViewShape, type ConnectWebMcpSourceShape, EndpointRegistry, ExperimentalWebMcpAdapter, type McpClientLike, type McpOAuthClient, type McpOAuthConfig, type McpOAuthHandshake, type McpOAuthHandshakeStore, type McpOAuthProvider, type McpOAuthStage, type McpOAuthTokenStore, type McpOAuthTokens, McpRuntimePlugin, type McpSourceTrust, type McpToolDisclosure, McpToolResolver, type McpToolVisibility, type McpVisibilityStore, MessageChannelTransport, type MessageChannelTransportOptions, type MessagePortLike, PAGE_HOST_ANCHOR_KEY, type PageActionConsentStore, type PageHostAnchor, type PageMcpEndpoint, type PageMcpEndpointOptions, type PageMcpTool, type RemoteEndpointConfig, type RemoteEndpointHandle, type RemoteEndpointStore, type ServedSkill, TemporarySkillProvider, type TransportState, WEB_MCP_ENDPOINT, WEB_MCP_SOURCE_ID_MAX, type WebMcpToolDescriptor, type WebMcpToolLike, catalogMerge, connectRemoteEndpoint, createConnectFacade, createLocalStorageMcpVisibility, createLocalStorageRemoteEndpoints, createMemoryOAuthStores, createOAuthProvider, createPageMcpEndpoint, declareDataSourcesToPageHost, endpointToolLlmName, notifyPageHost, parseEndpointToolLlmName, parseWebMcpToolLlmName, serveSkillAsMcp, validateJsonRpcMessage, webMcpToolLlmName };