@skyold/protocol-engine 0.1.0-beta.0 → 0.1.0-beta.2

package/README.md

@@ -25,15 +25,16 @@ its own TypeScript build, its own test command, and one runtime dependency:
 concrete Provider Adapters, storage, HTTP frameworks, credential stores, or
 network clients.
 
-The package and its normalized-contract dependency are configured for public
-npm access, but no registry release has been made yet. Therefore:
+The package and its normalized-contract dependency have a public
+`0.1.0-beta.2` release under the `beta` dist-tag. Therefore:
 
 - it is independently embeddable and testable by packages in this repository;
 - its packed runtime surface is independently inspectable;
 - packed tarballs can be installed and exercised by an isolated external
   consumer;
-- public registry availability, a versioned release, and provenance signing are
-  not claimed until the release gate completes.
+- public registry installation has been smoke-tested from an isolated consumer;
+- exact-SHA CI for the release-preparation tree, downstream adoption,
+  provenance signing, and real-Provider acceptance remain separate gates.
 
 The local V1 core implementation is complete against its frozen execution
 boundary. Overall rollout certification is still incomplete: fixture-backed
@@ -302,6 +303,17 @@ selects the protocol Adapter, and returns one versioned execution start:
 - `accepted-job` for durable asynchronous Provider acceptance;
 - `rejected` for not-accepted or acceptance-unknown asynchronous starts.
 
+When a Provider response was received, `providerResponse` carries its status,
+headers, and body bytes as the authoritative result. Successfully parsed and
+semantically validated non-failure stream events carry their exact SSE frame in
+`providerWire`; normalized terminal and event fields are derived observations of
+that same result. Provider errors, malformed or unknown frames, cancellation,
+and bytes after a terminal never use raw passthrough and produce only bounded
+safe egress. Caller-facing direct egress projects headers through
+`projectProviderResponseHeadersForCallerV1`: connection, credential, cookie,
+representation-length/encoding, caching, CORS, rate-limit, and security-policy
+fields remain Host-owned and are not copied from upstream.
+
 Use `engine.jobs.get`, `engine.jobs.list`, and `engine.jobs.cancel` for later
 async-job operations. Persistence, polling, callbacks, materialization, usage,
 and settlement remain Host responsibilities.
@@ -315,25 +327,36 @@ support `get` without pretending to support `list` or `cancel`.
 ### Provider response compatibility
 
 Provider wire responses are an open-world boundary. An Adapter validates and
-extracts the fields understood by its protocol version, ignores additive fields
-in synchronous bodies and known stream frames, and never retains those unknown
-fields in normalized output. This lets a Provider add response metadata without
-breaking an otherwise compatible protocol implementation.
+extracts the fields understood by its protocol version as derived normalized
+facts. For same-protocol egress, status, raw headers, and body bytes remain the
+authoritative response. A recognized non-failure SSE event retains its exact
+validated frame, including additive fields. Unknown event kinds, malformed
+frames, Provider failures, cancellation, opaque passthrough, and post-terminal
+bytes fail closed or use bounded normalized egress; they are never returned as
+raw caller-visible wire. Headers cross a separate caller-safe projection so
+transport or security metadata for one HTTP hop is not mistaken for another.
 
 Compatibility does not turn malformed known facts into success. Missing,
 mistyped, conflicting, duplicated, unsafe, or semantically invalid known fields
-still fail. An unknown stream event kind can alter lifecycle semantics, so it is
-not treated as a harmless additive field and fails unless the protocol Adapter
-explicitly supports it. Parser depth, body-size, URL, base64, index, usage, and
-terminal-consistency limits remain enforced.
+make the derived normalization fail. Parser depth, body-size, URL, base64, index,
+usage, and terminal-consistency limits continue to protect normalization and
+execution; transport or framing failures can of course prevent a complete
+response from being received.
 
 The Engine then validates Adapter outputs before exposing them to a Host. This
 includes sync/stream acceptance, terminal structure and consistency, every
-normalized stream event, plus async start, snapshot, and list result structure.
+normalized stream event, plus async start, snapshot, list, and cancellation
+result structure.
 Normalized event, metadata, terminal, result, usage, Responses, and async-job
-objects are closed schemas: undeclared fields are rejected. Raw Provider
-extensions therefore cannot leak through an Adapter to Host egress, usage, or
-settlement.
+objects are closed schemas: undeclared derived facts are rejected. The explicit
+Provider response envelope is not part of that closed projection. Hosts may use
+only normalized facts for usage or settlement while returning the authoritative
+Provider response to a same-protocol caller.
+
+When an async follow-up receives a complete non-success Provider response, the
+Engine error exposes that validated response in `providerResponse`. Hosts must
+never serialize the whole Engine error or its diagnostic `cause`; they may
+explicitly apply same-protocol egress policy to the response envelope.
 
 Terminal results must match the requested Task kind, and duplicate result,
 terminal, and Responses usage facts must agree when present. A custom Adapter
@@ -371,13 +394,13 @@ No test suite can mathematically guarantee all future Engine functionality.
 TokenForge uses separate proof layers so a narrow unit test is not mistaken for
 complete proxy evidence.
 
-| Layer                       | Command                                                                                                                                                   | What it proves                                                                                                 | What it does not prove                                         |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Engine package              | `pnpm --dir packages/protocol-engine check`                                                                                                               | Independent build plus core Registry, binding, sync, stream, async-job, validation and Host-equivalence tests. | Concrete Adapter wire formats, Host persistence, live network. |
-| Built-in conformance        | `pnpm --filter @skyold/provider-adapters test -- src/conformance/runtime-conformance.test.ts`                                                             | Every registered built-in family executes through public Engine API with fixture Transports.                   | Provider credentials or current remote behavior.               |
-| Architecture boundary       | `pnpm --filter @tokenforge/acceptance test -- src/L1-kernel/import-boundary.test.ts`                                                                      | Engine dependency isolation, package surface, no raw-forward/direct Adapter bypass, Host neutrality.           | Runtime semantic correctness by itself.                        |
-| Host integration            | Targeted suites for each embedding application and repository `pnpm check`                                                                                | Caller-specific context binding, streams, media persistence, usage and settlement compatibility.               | Exact deployed SHA or live Provider availability.              |
-| Real Provider certification | `pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run --env-file .env --ack-real-provider-calls I_AUTHORIZE_REAL_PROVIDER_CALLS` | Current authenticated Provider behavior for every successful evidence shard.                                   | Deployment, billing correctness, or a missing family.          |
+| Layer                       | Command                                                                                                                                                                                | What it proves                                                                                                        | What it does not prove                                         |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Engine package              | `pnpm --dir packages/protocol-engine check`                                                                                                                                            | Independent build plus core Registry, binding, sync, stream, async-job, validation and Host-equivalence tests.        | Concrete Adapter wire formats, Host persistence, live network. |
+| Built-in conformance        | `pnpm --filter @skyold/provider-adapters test -- src/conformance/runtime-conformance.test.ts`                                                                                          | Every registered built-in family executes through public Engine API with fixture Transports.                          | Provider credentials or current remote behavior.               |
+| Architecture boundary       | `pnpm --filter @tokenforge/acceptance test -- src/L1-kernel/import-boundary.test.ts` (TokenForge source monorepo)                                                                      | Engine dependency isolation, package surface, explicit Provider response ownership through Adapters, Host neutrality. | Runtime semantic correctness by itself.                        |
+| Host integration            | Targeted suites for each embedding application and repository `pnpm check`                                                                                                             | Caller-specific context binding, streams, media persistence, usage and settlement compatibility.                      | Exact deployed SHA or live Provider availability.              |
+| Real Provider certification | `pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run --env-file .env --ack-real-provider-calls I_AUTHORIZE_REAL_PROVIDER_CALLS` (TokenForge source monorepo) | Current authenticated Provider behavior for every successful evidence shard.                                          | Deployment, billing correctness, or a missing family.          |
 
 For a local Engine change, the minimum independent gate is the Engine package
 command. A protocol or Adapter change must also pass built-in conformance. A
@@ -388,9 +411,11 @@ gates.
 
 ## Real-Provider certification
 
-The repository's opt-in certification Host drives this public Engine API and
-the built-in Adapter Registry directly; it does not enter through any product
-application route. A versioned JSON manifest supplies one or more cases for every
+The TokenForge source monorepo ships the opt-in certification Host that drives
+this public Engine API and the built-in Adapter Registry directly; it does not
+enter through any product application route. The certification commands in this
+section run in that monorepo, not in this repository. A versioned JSON manifest
+supplies one or more cases for every
 protocol family returned by `engine.protocolFamilies`, with resolved target and
 capability facts, normalized tasks, secret environment-variable names, exact
 Provider domains, and suite request/time ceilings. Pricing and Provider billing
@@ -434,6 +459,7 @@ Host can perform a one-request, read-only diagnostic through `engine.jobs.list`
 without creating another task:
 
 ```bash
+# Run in the TokenForge source monorepo (apps/acceptance), not in this repository.
 pnpm --filter @tokenforge/acceptance diagnose:protocol-engine-real-async \
   --manifest /protected/path/async-shard.json \
   --env-file /protected/path/provider.env \
@@ -451,6 +477,7 @@ exhausted after the Provider had accepted the task, recover that exact submitted
 task without creating another one:
 
 ```bash
+# Run in the TokenForge source monorepo (apps/acceptance), not in this repository.
 pnpm --filter @tokenforge/acceptance recover:protocol-engine-real-shard \
   --manifest /protected/path/async-shard.json \
   --failure-evidence /protected/path/polling-exhausted.json \

package/README.zh-CN.md

@@ -12,12 +12,13 @@
 
 引擎是一个独立的 workspace package，提供唯一的包根 ESM API、独立的 TypeScript 构建和测试命令，且只有一个运行时依赖：`@skyold/model-protocol`。它不依赖任何 TokenForge Host、具体 Provider Adapter、存储、HTTP 框架、凭证仓库或网络客户端。
 
-该包及其规范化协议依赖已经配置公开 npm 元数据，但尚未执行 registry 首次发布。因此，当前可以确认的是：
+该包及其规范化协议依赖已通过 `beta` dist-tag 公开发布为 `0.1.0-beta.2`。因此，当前可以确认的是：
 
 - 仓库内其他 package 可以独立嵌入并测试它；
 - 可以独立检查它的打包运行时边界；
 - 打包 tarball 已可由隔离的外部消费者安装与验证；
-- 在发布门禁完成前，不承诺公共 registry 可用性、版本化发布或来源签名。
+- 已从隔离消费者通过公共 registry 安装并完成运行 smoke；
+- 发布准备树的 exact-SHA CI、下游采用、来源签名和真实 Provider 验收仍是独立门禁。
 
 本地 V1 核心已经完成并冻结在既定执行边界内。整体上线认证尚未完成：九种内置协议族的 fixture conformance 已全部通过，当前已有七种协议的真实 Provider 成功证据；`openai-embeddings/v1` 和 `openai-images/v1` 仍待真实成功认证。公开发布、exact-SHA CI 和部署属于独立交付门禁，不是把 Host 业务逻辑加入引擎的理由。
 
@@ -225,17 +226,21 @@ try {
 - `accepted-job`：Provider 已持久接受异步任务；
 - `rejected`：异步启动未被接受，或接受状态未知。
 
+只要已经收到 Provider 响应，`providerResponse` 就以权威结果的身份携带状态码、响应头和 body 原始字节。成功解析并通过语义校验的非失败流事件会通过 `providerWire` 携带其精确 SSE frame；规范化 terminal 和 event 是对同一结果的派生观察。Provider error、malformed/unknown frame、取消、opaque passthrough 和终态后的字节一律不得 raw passthrough，只能产生有界的安全下行。面向调用方的 direct egress 还会通过 `projectProviderResponseHeadersForCallerV1` 投影响应头：连接级、凭证、Cookie、表示长度/编码、缓存、CORS、限流和安全策略字段都由 Host 持有，不能从上游直接复制。
+
 后续异步任务操作使用 `engine.jobs.get`、`engine.jobs.list` 和 `engine.jobs.cancel`。持久化、轮询、回调、物化、用量和结算仍是 Host 职责。
 
 异步 Adapter factory 通过 `jobOperations` 声明支持的后续操作。引擎会在绑定 Transport 前，以 `PROTOCOL_ENGINE_CAPABILITY_UNSUPPORTED` 拒绝未声明的操作。因此协议可以保留真实生命周期差异：例如，一个协议可以支持 `get`，而不需要伪装成支持 `list` 或 `cancel`。
 
 ### Provider response 兼容原则
 
-Provider wire response 是开放世界边界。Adapter 校验并提取当前协议版本理解的字段，忽略同步 body 和已知 stream frame 中新增的附加字段，且不会把这些未知字段保留到规范化输出中。这样 Provider 新增响应元数据时，不会破坏原本兼容的协议实现。
+Provider wire response 是开放世界边界。Adapter 会把当前协议版本理解的字段提取为派生的规范化事实；对于同协议下行，状态码、原始响应头和 body 原始字节仍是权威结果。已识别的非失败 SSE 事件会保留其通过校验的精确 frame，包括附加字段。未知事件类型、malformed frame、Provider failure、取消、opaque passthrough 和终态后字节必须 fail closed 或使用有界的规范化下行，绝不能作为 raw wire 返回调用方。响应头另行经过 caller-safe 投影，避免把上一段 HTTP 连接或安全元数据误用于下一段连接。
+
+兼容不代表把已知字段异常当作成功。已知字段缺失、类型错误、冲突、重复、不安全或语义无效会导致派生归一化失败。解析深度、body 大小、URL、base64、index、usage 和终态一致性限制继续保护归一化与执行；Transport 或 framing 失败则可能使完整响应根本无法被接收。
 
-兼容不代表把已知字段异常当作成功。已知字段缺失、类型错误、冲突、重复、不安全或语义无效仍然失败。未知 stream event kind 可能改变生命周期语义，不能视为无害附加字段；除非协议 Adapter 明确支持，否则必须失败。解析深度、body 大小、URL、base64、index、usage 和终态一致性限制继续生效。
+随后，引擎会在向 Host 暴露结果前校验 Adapter 输出，包括同步/流式接受结果、终态结构与一致性、每个规范化流事件，以及异步启动、snapshot、列表和取消结果结构。规范化 event、metadata、terminal、result、usage、Responses 和异步任务对象仍是封闭 schema：未声明的派生事实会被拒绝。显式 Provider response envelope 不属于这个封闭投影；Host 可以只用规范化事实处理用量或结算，同时把权威 Provider 响应返回给同协议调用者。
 
-随后，引擎会在向 Host 暴露结果前校验 Adapter 输出，包括同步/流式接受结果、终态结构与一致性、每个规范化流事件，以及异步启动、snapshot 和列表结果结构。规范化 event、metadata、terminal、result、usage、Responses 和异步任务对象都是封闭 schema：未声明字段会被拒绝。因此 Provider 原始扩展字段不能穿过 Adapter 泄漏到 Host egress、用量或结算流程。
+异步后续操作收到完整的非成功 Provider 响应时，引擎错误会在 `providerResponse` 中暴露经过校验的响应。Host 绝不能序列化整个引擎错误或诊断用 `cause`；只能显式地对该响应 envelope 应用同协议 egress 策略。
 
 终态 result 必须与请求的 Task kind 一致；当 result、terminal 和 Responses 中重复出现 usage 事实时，它们必须一致。自定义 Adapter 不能依赖 TypeScript 类型断言绕过 V1 运行时契约，也不能让 Host egress 和结算观察到不同事实。
 
@@ -251,19 +256,19 @@ Provider wire response 是开放世界边界。Adapter 校验并提取当前协
 
 任何测试套件都无法在数学意义上保证未来全部引擎功能。TokenForge 把证明拆分为不同层级，避免把一个狭窄单元测试误认为完整 proxy 证据。
 
-| 层级               | 命令                                                                                                                                                      | 能证明                                                                           | 不能证明                                        |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------- |
-| 引擎 package       | `pnpm --dir packages/protocol-engine check`                                                                                                               | 独立构建，以及 Registry、binding、同步、流式、异步任务、校验和 Host 等价性测试。 | 具体 Adapter wire 格式、Host 持久化、真实网络。 |
-| 内置 conformance   | `pnpm --filter @skyold/provider-adapters test -- src/conformance/runtime-conformance.test.ts`                                                             | 每个已注册内置协议族均通过公共 Engine API 和 fixture Transport 执行。            | Provider 凭证或当前远端行为。                   |
-| 架构边界           | `pnpm --filter @tokenforge/acceptance test -- src/L1-kernel/import-boundary.test.ts`                                                                      | 引擎依赖隔离、package surface、禁止 raw-forward/直接绕过 Adapter、Host 中立性。  | 单独证明运行时语义正确。                        |
-| Host 集成          | 各嵌入应用的定向测试与仓库 `pnpm check`                                                                                                                   | 相应调用方的上下文绑定、流式、媒体持久化、用量与结算兼容。                       | exact-SHA 部署或真实 Provider 可用性。          |
-| 真实 Provider 认证 | `pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run --env-file .env --ack-real-provider-calls I_AUTHORIZE_REAL_PROVIDER_CALLS` | 每个成功证据分片对应的当前、已认证 Provider 行为。                               | 部署、计费正确性或缺失协议族。                  |
+| 层级               | 命令                                                                                                                                                                                          | 能证明                                                                           | 不能证明                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------- |
+| 引擎 package       | `pnpm --dir packages/protocol-engine check`                                                                                                                                                   | 独立构建，以及 Registry、binding、同步、流式、异步任务、校验和 Host 等价性测试。 | 具体 Adapter wire 格式、Host 持久化、真实网络。 |
+| 内置 conformance   | `pnpm --filter @skyold/provider-adapters test -- src/conformance/runtime-conformance.test.ts`                                                                                                 | 每个已注册内置协议族均通过公共 Engine API 和 fixture Transport 执行。            | Provider 凭证或当前远端行为。                   |
+| 架构边界           | `pnpm --filter @tokenforge/acceptance test -- src/L1-kernel/import-boundary.test.ts`（在 TokenForge 源 monorepo 中执行）                                                                      | 引擎依赖隔离、package surface、经 Adapter 显式承载 Provider 响应、Host 中立性。  | 单独证明运行时语义正确。                        |
+| Host 集成          | 各嵌入应用的定向测试与仓库 `pnpm check`                                                                                                                                                       | 相应调用方的上下文绑定、流式、媒体持久化、用量与结算兼容。                       | exact-SHA 部署或真实 Provider 可用性。          |
+| 真实 Provider 认证 | `pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run --env-file .env --ack-real-provider-calls I_AUTHORIZE_REAL_PROVIDER_CALLS`（在 TokenForge 源 monorepo 中执行） | 每个成功证据分片对应的当前、已认证 Provider 行为。                               | 部署、计费正确性或缺失协议族。                  |
 
 本地修改引擎时，最低独立门禁是引擎 package 命令。协议或 Adapter 变更还必须通过内置 conformance。Host 集成变更还必须通过受影响 Host 的测试。只有 Registry 清单中所有协议族都取得真实 Provider 成功证据，且实际交付的 exact SHA 通过 CI 和部署门禁，整个目标才算完成。
 
 ## 真实 Provider 认证
 
-仓库内的 opt-in 认证 Host 会直接驱动这套公共 Engine API 和内置 Adapter Registry，不经过任何产品应用的 route。版本化 JSON manifest 为 `engine.protocolFamilies` 返回的每个协议族提供一个或多个 case，其中包含已解析 target 与 capability 事实、规范化 task、密钥环境变量名、精确 Provider 域名，以及 suite 请求/时长上限。定价和 Provider 计费刻意不属于引擎契约或认证事实。
+TokenForge 源 monorepo 内的 opt-in 认证 Host 会直接驱动这套公共 Engine API 和内置 Adapter Registry，不经过任何产品应用的 route。本节的认证命令都在该 monorepo 中执行，不在本仓库执行。版本化 JSON manifest 为 `engine.protocolFamilies` 返回的每个协议族提供一个或多个 case，其中包含已解析 target 与 capability 事实、规范化 task、密钥环境变量名、精确 Provider 域名，以及 suite 请求/时长上限。定价和 Provider 计费刻意不属于引擎契约或认证事实。
 
 默认只做离线校验：
 
@@ -286,6 +291,7 @@ pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run \
 对于已被接受且支持 list 的异步 target，Acceptance Host 可以通过 `engine.jobs.list` 执行一次只读诊断，不会创建新任务：
 
 ```bash
+# 在 TokenForge 源 monorepo（apps/acceptance）中执行，不在本仓库执行。
 pnpm --filter @tokenforge/acceptance diagnose:protocol-engine-real-async \
   --manifest /protected/path/async-shard.json \
   --env-file /protected/path/provider.env \
@@ -298,6 +304,7 @@ pnpm --filter @tokenforge/acceptance diagnose:protocol-engine-real-async \
 当支持 list 的异步分片已经被 Provider 接受、但认证仅因有界轮询耗尽而停止时，可以恢复这一笔已提交任务，而不创建第二笔任务：
 
 ```bash
+# 在 TokenForge 源 monorepo（apps/acceptance）中执行，不在本仓库执行。
 pnpm --filter @tokenforge/acceptance recover:protocol-engine-real-shard \
   --manifest /protected/path/async-shard.json \
   --failure-evidence /protected/path/polling-exhausted.json \

package/dist/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { AdapterTerminalOutcome, NormalizedStreamEventV1, PreparedMediaExecutionInputV2, ProtocolFamily, ProviderAsyncJobListInputV2, ProviderAsyncJobSnapshotV2, ProviderAsyncJobAdapterFactory, ProviderAcceptanceFacts, ProviderAdapterFactory, ProviderDispatchTargetV2, ProviderResponseMetadata, ProviderTransport, TaskEnvelopeV2 } from '@skyold/model-protocol';
+import type { AdapterTerminalOutcome, NormalizedStreamEventV1, PreparedMediaExecutionInputV2, ProtocolFamily, ProviderAsyncJobListInputV2, ProviderAsyncJobSnapshotV2, ProviderAsyncJobAdapterFactory, ProviderAcceptanceFacts, ProviderAdapterFactory, ProviderDispatchTargetV2, ProviderResponseMetadata, ProviderWireResponseV1, ProviderTransport, TaskEnvelopeV2 } from '@skyold/model-protocol';
 export declare const PROTOCOL_ENGINE_API_VERSION: "tokenforge-protocol-engine/v1";
 export type ProtocolEngineApiVersion = typeof PROTOCOL_ENGINE_API_VERSION;
 export type ProtocolEngineDispatchTargetV1 = ProviderDispatchTargetV2;
@@ -22,6 +22,7 @@ interface ProtocolEngineExecutionBaseV1 {
     readonly apiVersion: ProtocolEngineApiVersion;
     readonly acceptance: ProviderAcceptanceFacts;
     readonly responseMetadata: ProviderResponseMetadata;
+    readonly providerResponse?: ProviderWireResponseV1;
 }
 export interface ProtocolEngineResponseV1 extends ProtocolEngineExecutionBaseV1 {
     readonly kind: 'response';
@@ -70,11 +71,13 @@ export interface ProtocolEngineAsyncJobObservationV1 {
 }
 export interface ProtocolEngineAsyncJobListResultV1 {
     readonly apiVersion: ProtocolEngineApiVersion;
+    readonly providerResponse?: ProviderWireResponseV1;
     readonly items: readonly ProviderAsyncJobSnapshotV2[];
     readonly total: number;
 }
 export interface ProtocolEngineAsyncJobCancellationV1 {
     readonly apiVersion: ProtocolEngineApiVersion;
+    readonly providerResponse?: ProviderWireResponseV1;
 }
 export interface ProtocolEngineAsyncJobsV1 {
     get(input: ProtocolEngineAsyncJobInputV1): Promise<ProtocolEngineAsyncJobObservationV1>;

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { providerCapabilityFromTarget, validateProviderDispatchInputV2, validateProviderAsyncJobList, validateProviderAsyncJobSnapshot, validateProviderAsyncJobStart, validateProviderExecutionStart, } from '@skyold/model-protocol';
+import { isProviderWireResponseErrorV1, providerCapabilityFromTarget, validateProviderDispatchInputV2, validateProviderAsyncJobList, validateProviderAsyncJobSnapshot, validateProviderAsyncJobStart, validateProviderExecutionStart, validateProviderWireResponseV1, } from '@skyold/model-protocol';
 import { PROTOCOL_ENGINE_API_VERSION, } from './contracts.js';
 import { PROTOCOL_ENGINE_ERROR_CODES_V1, ProtocolEngineErrorV1, isProtocolEngineErrorV1, } from './errors.js';
 export function createProtocolEngineV1(input) {
@@ -28,14 +28,23 @@ export function createProtocolEngineV1(input) {
                 const result = validateAdapterOutput(() => validateProviderAsyncJobList(adapterResult));
                 return {
                     apiVersion: PROTOCOL_ENGINE_API_VERSION,
+                    ...(result.providerResponse === undefined
+                        ? {}
+                        : { providerResponse: result.providerResponse }),
                     items: result.items,
                     total: result.total,
                 };
             },
             async cancel(jobInput) {
                 const adapter = await bindAsyncJobAdapter(input.registry, jobInput.binding, jobInput.signal, protocolFamilies, 'cancel');
-                await callAdapter(() => adapter.cancel(jobInput.providerJobId, jobInput.signal), jobInput.signal);
-                return { apiVersion: PROTOCOL_ENGINE_API_VERSION };
+                const adapterResult = await callAdapter(() => adapter.cancel(jobInput.providerJobId, jobInput.signal), jobInput.signal);
+                const providerResponse = adapterResult === undefined
+                    ? undefined
+                    : validateAdapterOutput(() => validateProviderWireResponseV1(adapterResult));
+                return {
+                    apiVersion: PROTOCOL_ENGINE_API_VERSION,
+                    ...(providerResponse === undefined ? {} : { providerResponse }),
+                };
             },
         },
         async execute(executionInput) {
@@ -76,6 +85,9 @@ export function createProtocolEngineV1(input) {
                     kind: 'response',
                     acceptance: started.acceptance,
                     responseMetadata: started.responseMetadata,
+                    ...(started.providerResponse === undefined
+                        ? {}
+                        : { providerResponse: started.providerResponse }),
                     terminal: started.terminal,
                 };
                 return result;
@@ -180,6 +192,9 @@ async function executeAsync(registry, executionInput, binding, capability) {
             kind: 'accepted-job',
             acceptance: started.acceptance,
             responseMetadata: started.responseMetadata,
+            ...(started.providerResponse === undefined
+                ? {}
+                : { providerResponse: started.providerResponse }),
             providerJobId: started.providerJobId,
         };
     }
@@ -188,6 +203,9 @@ async function executeAsync(registry, executionInput, binding, capability) {
         kind: 'rejected',
         acceptance: started.acceptance,
         responseMetadata: started.responseMetadata,
+        ...(started.providerResponse === undefined
+            ? {}
+            : { providerResponse: started.providerResponse }),
         failureCode: started.failureCode,
         retryable: started.retryable,
     };
@@ -298,20 +316,44 @@ function abortAdapter(abort, reason) {
 }
 function wrapOperationError(code, cause, signal) {
     if (isProtocolEngineErrorV1(cause))
-        return cause;
+        return validateProtocolEngineError(cause);
     if (signal.aborted || (cause instanceof Error && cause.name === 'AbortError')) {
         return wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ABORTED, cause);
     }
+    if (isProviderWireResponseErrorV1(cause)) {
+        try {
+            const providerResponse = validateProviderWireResponseV1(cause.providerResponse);
+            return new ProtocolEngineErrorV1(code, { cause, providerResponse });
+        }
+        catch (validationCause) {
+            return wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_OUTPUT_INVALID, validationCause, adapterOutputCompatibilityMessage(validationCause));
+        }
+    }
     return wrapProtocolEngineError(code, cause);
 }
 function wrapProtocolEngineError(code, cause, compatibilityMessage) {
     if (isProtocolEngineErrorV1(cause))
-        return cause;
+        return validateProtocolEngineError(cause);
     return new ProtocolEngineErrorV1(code, {
         cause,
         ...(compatibilityMessage === undefined ? {} : { compatibilityMessage }),
     });
 }
+function validateProtocolEngineError(cause) {
+    if (cause.providerResponse === undefined)
+        return cause;
+    try {
+        validateProviderWireResponseV1(cause.providerResponse);
+        return cause;
+    }
+    catch (validationCause) {
+        const compatibilityMessage = adapterOutputCompatibilityMessage(validationCause);
+        return new ProtocolEngineErrorV1(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_OUTPUT_INVALID, {
+            cause: validationCause,
+            ...(compatibilityMessage === undefined ? {} : { compatibilityMessage }),
+        });
+    }
+}
 function protocolEngineError(code, compatibilityMessage) {
     return new ProtocolEngineErrorV1(code, {
         ...(compatibilityMessage === undefined ? {} : { compatibilityMessage }),
@@ -339,6 +381,7 @@ const ADAPTER_OUTPUT_COMPATIBILITY_MESSAGES = new Set([
     'ADAPTER_ASYNC_START_INVALID',
     'ADAPTER_ASYNC_JOB_SNAPSHOT_INVALID',
     'ADAPTER_ASYNC_JOB_LIST_INVALID',
+    'ADAPTER_PROVIDER_RESPONSE_INVALID',
 ]);
 function inputCompatibilityMessage(cause) {
     return cause instanceof Error && INPUT_COMPATIBILITY_MESSAGES.has(cause.message)

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import { type ProtocolEngineApiVersion } from './contracts.js';
+import type { ProviderWireResponseV1 } from '@skyold/model-protocol';
 export declare const PROTOCOL_ENGINE_ERROR_CODES_V1: Readonly<{
     readonly REGISTRY_INVALID: "PROTOCOL_ENGINE_REGISTRY_INVALID";
     readonly PROTOCOL_FAMILY_UNAVAILABLE: "PROTOCOL_ENGINE_PROTOCOL_FAMILY_UNAVAILABLE";
@@ -17,6 +18,8 @@ export type ProtocolEngineErrorPhaseV1 = 'configuration' | 'input' | 'transport'
 export interface ProtocolEngineErrorOptionsV1 {
     /** Internal diagnostic cause. Hosts must never serialize it to clients. */
     readonly cause?: unknown;
+    /** Complete Provider response available for explicit same-protocol Host egress. */
+    readonly providerResponse?: ProviderWireResponseV1;
     /**
      * Temporary compatibility message for Hosts that still classify historical
      * fixed-runtime failures by Error.message. New integrations must use code.
@@ -33,6 +36,7 @@ export declare class ProtocolEngineErrorV1 extends Error {
     readonly apiVersion: ProtocolEngineApiVersion;
     readonly code: ProtocolEngineErrorCodeV1;
     readonly phase: ProtocolEngineErrorPhaseV1;
+    readonly providerResponse?: ProviderWireResponseV1;
     constructor(code: ProtocolEngineErrorCodeV1, options?: ProtocolEngineErrorOptionsV1);
 }
 export declare function isProtocolEngineErrorV1(error: unknown): error is ProtocolEngineErrorV1;

package/dist/errors.js

@@ -22,11 +22,15 @@ export class ProtocolEngineErrorV1 extends Error {
     apiVersion = PROTOCOL_ENGINE_API_VERSION;
     code;
     phase;
+    providerResponse;
     constructor(code, options = {}) {
         super(options.compatibilityMessage ?? code, { cause: options.cause });
         this.name = 'ProtocolEngineErrorV1';
         this.code = code;
         this.phase = phaseForCode(code);
+        if (options.providerResponse !== undefined) {
+            this.providerResponse = options.providerResponse;
+        }
     }
 }
 export function isProtocolEngineErrorV1(error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyold/protocol-engine",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.2",
   "description": "Host-neutral execution kernel for normalized AI provider protocols.",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,17 +49,18 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsc -b",
+    "check": "pnpm build && pnpm test",
+    "prepack": "pnpm build",
+    "test": "vitest run"
+  },
   "dependencies": {
-    "@skyold/model-protocol": "^0.1.0-beta.0"
+    "@skyold/model-protocol": "workspace:^"
   },
   "devDependencies": {
     "@types/node": "22.19.19",
     "typescript": "5.9.3",
     "vitest": "2.1.9"
-  },
-  "scripts": {
-    "build": "tsc -b",
-    "check": "pnpm build && pnpm test",
-    "test": "vitest run"
   }
-}
+}

package/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 TokenForge Contributors
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.