@harrylabsj/kiwi 0.6.0

package/dist/a2a/server/ucp.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * 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.
+ */
+import { WELL_KNOWN_UCP_PATH } from "../../discovery/ucp/resolver.js";
+import type { UcpProfile } from "../../discovery/ucp/types.js";
+import type { AgentCardConfig } from "./types.js";
+export { WELL_KNOWN_UCP_PATH };
+/** buildKiwiVendorProfile 透传选项（agentCardUrl 由本模块推导，不在此暴露）。 */
+export interface UcpVendorOptions {
+    authority?: string;
+    version?: string;
+    capabilityName?: string;
+    serviceName?: string;
+    ucpVersion?: string;
+}
+/** UCP Profile 发布选项（A2AServerOptions.ucp）。 */
+export interface UcpPublishOptions {
+    /** 是否发布（缺省 true）。 */
+    enabled?: boolean;
+    /** 本 server 的 Agent Card well-known 路径（默认 /.well-known/agent-card.json）。 */
+    wellKnownPath?: string;
+    /** Cache-Control max-age 秒（默认 300，必须 >= 60，UCP 规范强制）。 */
+    maxAgeSeconds?: number;
+    /** buildKiwiVendorProfile 透传选项（authority 等）。 */
+    vendor?: UcpVendorOptions;
+}
+/** buildUcpProfile 的产物：可发布 profile + 计算好的 Cache-Control 头。 */
+export interface BuiltUcpProfile {
+    profile: UcpProfile;
+    cacheControl: string;
+    maxAgeSeconds: number;
+}
+/**
+ * 从本地 Agent Card 配置生成 UCP Profile。构建结果强制过 validateUcpProfile
+ * 自洽校验（fail-closed：被拒条目存在即抛错，不发布坏 profile）。
+ */
+export declare function buildUcpProfile(config: AgentCardConfig, opts?: UcpPublishOptions): BuiltUcpProfile;

package/dist/a2a/server/ucp.js

@@ -0,0 +1,85 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * 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.
+ */
+/**
+ * UCP Profile 服务化（WP3，基线 §25 / §8.3 / §43）。
+ *
+ * merchant 侧从 AgentCardConfig 生成 UCP Profile 并在 `GET /.well-known/ucp`
+ * 上发布（UCP 规范强制的标准发现入口）：
+ *
+ *   - a2a service transport：endpoint 指向本 server 的 Agent Card well-known
+ *     URL（`<baseUrl>/.well-known/agent-card.json`），基线 §25；
+ *   - Kiwi vendor capability：`com.harrylabsj.kiwi.shopping.negotiation`（§8.3，
+ *     真实 authority `kiwi.harrylabsj.com`，spec/schema 需托管在该域名上）。
+ *
+ * 不声明任何 `dev.ucp.*` capability：该 namespace 为 UCP 治理机构保留，vendor
+ * 不得占用（`dev.ucp.shopping.*` 官方 capability 仅 checkout / cart / order /
+ * fulfillment / discount）；Kiwi 协商能力以 Vendor Root Capability 形态发布（§25.2）。
+ *
+ * 构建结果强制过 validateUcpProfile 自洽校验（fail-closed：过不了校验就不发）。
+ * 响应头 Cache-Control 由 buildUcpProfile 计算（`public, max-age=N`，N>=60）。
+ *
+ * 零新增依赖。
+ */
+import { buildKiwiVendorProfile } from "../../discovery/ucp/vendor.js";
+import { validateUcpProfile } from "../../discovery/ucp/validate.js";
+import { WELL_KNOWN_UCP_PATH } from "../../discovery/ucp/resolver.js";
+export { WELL_KNOWN_UCP_PATH };
+const DEFAULT_WELL_KNOWN_AGENT_CARD_PATH = "/.well-known/agent-card.json";
+const DEFAULT_MAX_AGE_SECONDS = 300;
+const MIN_MAX_AGE_SECONDS = 60;
+function requireHttpUrl(value, field) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`AgentCardConfig: ${field} must be a valid URL (got "${value}")`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`AgentCardConfig: ${field} must use http or https (got ${url.protocol})`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new Error(`AgentCardConfig: ${field} must not embed credentials (userinfo)`);
+    }
+    return url;
+}
+/**
+ * 从本地 Agent Card 配置生成 UCP Profile。构建结果强制过 validateUcpProfile
+ * 自洽校验（fail-closed：被拒条目存在即抛错，不发布坏 profile）。
+ */
+export function buildUcpProfile(config, opts = {}) {
+    const baseUrl = requireHttpUrl(config.baseUrl, "baseUrl");
+    const maxAgeSeconds = opts.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
+    if (!Number.isInteger(maxAgeSeconds) || maxAgeSeconds < MIN_MAX_AGE_SECONDS) {
+        throw new Error(`UCP profile Cache-Control max-age must be an integer >= ${MIN_MAX_AGE_SECONDS} (got ${maxAgeSeconds})`);
+    }
+    const wellKnownPath = opts.wellKnownPath ?? DEFAULT_WELL_KNOWN_AGENT_CARD_PATH;
+    const agentCardUrl = new URL(wellKnownPath, baseUrl).href;
+    const profile = buildKiwiVendorProfile({ agentCardUrl, ...opts.vendor });
+    const validation = validateUcpProfile(profile);
+    if (validation.rejected.length > 0) {
+        const detail = validation.rejected
+            .map((r) => `${r.name} (${r.code})`)
+            .join("; ");
+        throw new Error(`UCP profile failed validation: ${detail}`);
+    }
+    return {
+        profile: validation.profile,
+        cacheControl: `public, max-age=${maxAgeSeconds}`,
+        maxAgeSeconds,
+    };
+}
+//# sourceMappingURL=ucp.js.map

package/dist/a2a/server/ucp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucp.js","sourceRoot":"","sources":["../../../src/a2a/server/ucp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAItE,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAE/B,MAAM,kCAAkC,GAAG,8BAA8B,CAAC;AAC1E,MAAM,uBAAuB,GAAG,GAAG,CAAC;AACpC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AA8B/B,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa;IAClD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,8BAA8B,KAAK,IAAI,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,gCAAgC,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,wCAAwC,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAuB,EACvB,OAA0B,EAAE;IAE5B,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,uBAAuB,CAAC;IACpE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,mBAAmB,EAAE,CAAC;QAC5E,MAAM,IAAI,KAAK,CACb,2DAA2D,mBAAmB,SAAS,aAAa,GAAG,CACxG,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,kCAAkC,CAAC;IAC/E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;IAC1D,MAAM,OAAO,GAAG,sBAAsB,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzE,MAAM,UAAU,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC;aACnC,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACL,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,YAAY,EAAE,mBAAmB,aAAa,EAAE;QAChD,aAAa;KACd,CAAC;AACJ,CAAC"}

package/dist/a2a/task/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * 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.
+ */
+/**
+ * a2a/task — A2A Task 生命周期模型 + 轮询器（WP3，基线 §18.3 / §23）。
+ */
+export { A2A_TASK_STATES_REAL, A2A_TASK_TERMINAL_STATES, A2A_TASK_TRANSITIONS, isRealTaskState, isTaskState, isTerminalTaskState, isWaitingTaskState, TaskLifecycleTracker, transitionTaskState, TaskStateError, } from "./state.js";
+export type { A2ATaskTerminalState, TaskStateErrorCode } from "./state.js";
+export { recordTaskObservation } from "./ledger.js";
+export type { TaskObservationInput } from "./ledger.js";
+export { A2ATaskPoller } from "./poller.js";
+export type { PollResult, PollStatus, TaskPollerClient, TaskPollerLedgerOptions, TaskPollerOptions, } from "./poller.js";

package/dist/a2a/task/index.js

@@ -0,0 +1,22 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * 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.
+ */
+/**
+ * a2a/task — A2A Task 生命周期模型 + 轮询器（WP3，基线 §18.3 / §23）。
+ */
+export { A2A_TASK_STATES_REAL, A2A_TASK_TERMINAL_STATES, A2A_TASK_TRANSITIONS, isRealTaskState, isTaskState, isTerminalTaskState, isWaitingTaskState, TaskLifecycleTracker, transitionTaskState, TaskStateError, } from "./state.js";
+export { recordTaskObservation } from "./ledger.js";
+export { A2ATaskPoller } from "./poller.js";
+//# sourceMappingURL=index.js.map

package/dist/a2a/task/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/a2a/task/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AAEH,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/a2a/task/ledger.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * 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.
+ */
+/**
+ * A2A Task 状态 → Ledger 落账（基线 §22 / §18.3 / 子规范 §28）。
+ *
+ * 轮询器每次观察到任务状态变化时调用 recordTaskObservation，把远端 taskId /
+ * contextId 引用与 task_state 一起落账（§22 要求的 remote contextId/taskId 引用）。
+ * event_kind 用 `system`：task 状态不是 KNP phase 转换（state_transition 是
+ * NegotiationPhase 维度），也不是消息收发；作为运行时观察证据记录。
+ *
+ * 不保存 raw chain-of-thought / Vault plaintext（§28 禁词由 LedgerStore.append
+ * 强制）。远端 contextId 只作 opaque 引用存储（基线 §9.2 / §6.6），不解析不推断。
+ */
+import type { LedgerCapabilitySnapshot, LedgerIdentitySnapshot, LedgerStore } from "../../negotiation/ledger/index.js";
+import type { A2ATaskState } from "../client/index.js";
+export interface TaskObservationInput {
+    ledger: LedgerStore;
+    negotiation_id: string;
+    task_id: string;
+    task_state: A2ATaskState;
+    /** 远端 A2A contextId（opaque）。 */
+    context_id?: string;
+    /** 观察时任务携带的最近 messageId（如有）。 */
+    message_id?: string;
+    identity?: LedgerIdentitySnapshot;
+    capability?: LedgerCapabilitySnapshot;
+    /** 业务发生时间（RFC 3339）。 */
+    occurred_at: string;
+}
+/**
+ * 记录一次任务状态观察。调用方保证 task_state 已通过状态机校验
+ * （recordTaskObservation 不对状态做业务判定，只落账）；task_state 为
+ * `unknown` 时 fail-closed 抛错，绝不把不确定状态写进审计链。
+ */
+export declare function recordTaskObservation(input: TaskObservationInput): void;

package/dist/a2a/task/ledger.js

@@ -0,0 +1,65 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * 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.
+ */
+const DEFAULT_IDENTITY = {
+    sender_identity: "kiwi.a2a.task",
+    counterparty_identity: "remote",
+};
+const DEFAULT_CAPABILITY = {
+    capability: "a2a.task.observation",
+    protocol_version: "1.0",
+};
+/**
+ * 单调观察序号（§22 内容寻址）。观测事件是「运行时证据」而非离散逻辑事件：
+ * 同一 task_state 可能被多次观察（轮询 / getState），若只按 (task_id,
+ * task_state, occurred_at) 寻址，同一毫秒（或冻结时钟）的第二次观测内容
+ * 完全相同 → ledger_duplicate_content。序号进入 outcome.result → 参与内容
+ * 寻址，使每次观察内容唯一。跨进程重启后从 1 重新开始：occurred_at 通常不同，
+ * 不再构成同内容；冻结时钟跨重启是测试态伪影，不作持久化保证。
+ */
+let observationSeq = 0;
+function nextObservationSeq() {
+    observationSeq += 1;
+    return observationSeq;
+}
+/**
+ * 记录一次任务状态观察。调用方保证 task_state 已通过状态机校验
+ * （recordTaskObservation 不对状态做业务判定，只落账）；task_state 为
+ * `unknown` 时 fail-closed 抛错，绝不把不确定状态写进审计链。
+ */
+export function recordTaskObservation(input) {
+    if (input.task_state === "unknown") {
+        throw new Error("recordTaskObservation refuses to record unknown task state");
+    }
+    input.ledger.append({
+        event_kind: "system",
+        negotiation_id: input.negotiation_id,
+        message_id: input.message_id,
+        remote_context_id: input.context_id,
+        remote_task_id: input.task_id,
+        identity: input.identity ?? DEFAULT_IDENTITY,
+        capability: input.capability ?? DEFAULT_CAPABILITY,
+        outcome: {
+            kind: "ok",
+            result: {
+                task_id: input.task_id,
+                task_state: input.task_state,
+                observation_seq: nextObservationSeq(),
+            },
+        },
+        occurred_at: input.occurred_at,
+    });
+}
+//# sourceMappingURL=ledger.js.map

package/dist/a2a/task/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../src/a2a/task/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAqBH,MAAM,gBAAgB,GAA2B;IAC/C,eAAe,EAAE,eAAe;IAChC,qBAAqB,EAAE,QAAQ;CAChC,CAAC;AAEF,MAAM,kBAAkB,GAA6B;IACnD,UAAU,EAAE,sBAAsB;IAClC,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,IAAI,cAAc,GAAG,CAAC,CAAC;AAEvB,SAAS,kBAAkB;IACzB,cAAc,IAAI,CAAC,CAAC;IACpB,OAAO,cAAc,CAAC;AACxB,CAAC;AAiBD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAA2B;IAC/D,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;QAClB,UAAU,EAAE,QAAQ;QACpB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,iBAAiB,EAAE,KAAK,CAAC,UAAU;QACnC,cAAc,EAAE,KAAK,CAAC,OAAO;QAC7B,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,gBAAgB;QAC5C,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,kBAAkB;QAClD,OAAO,EAAE;YACP,IAAI,EAAE,IAAI;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,eAAe,EAAE,kBAAkB,EAAE;aACtC;SACF;QACD,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAC,CAAC;AACL,CAAC"}

package/dist/a2a/task/poller.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * 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.
+ */
+import type { A2ATask, A2ATaskState } from "../client/index.js";
+import type { LedgerCapabilitySnapshot, LedgerIdentitySnapshot, LedgerStore } from "../../negotiation/ledger/index.js";
+/** 轮询客户端最小面：tasks/get 足够。 */
+export interface TaskPollerClient {
+    getTask(taskId: string): Promise<A2ATask>;
+}
+export type PollStatus = "completed" | "canceled" | "failed" | "input-required" | "timeout" | "budget_exhausted" | "rejected";
+export interface PollResult {
+    status: PollStatus;
+    /** 到达终态 / input-required / 最近一次成功取回的任务。 */
+    task?: A2ATask;
+    /** 最后一次观察到的真实状态（若有）。 */
+    state?: A2ATaskState;
+    /** 已消耗的 attempt 数（含失败与成功的轮询）。 */
+    attempts: number;
+    /** rejected / budget_exhausted 时的根因。 */
+    lastError?: unknown;
+    /** rejected 时的人读原因（未知状态 / 非法转换 / schema 失败等）。 */
+    reason?: string;
+}
+export interface TaskPollerLedgerOptions {
+    ledger: LedgerStore;
+    negotiation_id: string;
+    identity?: LedgerIdentitySnapshot;
+    capability?: LedgerCapabilitySnapshot;
+}
+export interface TaskPollerOptions {
+    client: TaskPollerClient;
+    taskId: string;
+    /** 轮询带上 contextId（opaque，落账引用用）。 */
+    contextId?: string;
+    /** 轮询预算（attempt 数，默认 10）。 */
+    maxAttempts?: number;
+    /** 相对截止 ms；缺省不设墙钟截止（仅受 maxAttempts 约束）。 */
+    deadlineMs?: number;
+    baseBackoffMs?: number;
+    maxBackoffMs?: number;
+    backoffMultiplier?: number;
+    /** 可注入时钟（ms epoch）；缺省 Date.now()。 */
+    now?: () => number;
+    /** 可注入 sleep；缺省 setTimeout。测试传瞬时 sleep。 */
+    sleep?: (ms: number) => Promise<void>;
+    /** 任务状态变化时调用（Ledger 落账 + 观察者钩子）。 */
+    onStateChanged?: (info: {
+        task: A2ATask;
+        from: A2ATaskState | null;
+        to: A2ATaskState;
+    }) => void | Promise<void>;
+    /** 提供 ledger + negotiation_id 时，状态变化自动落账。 */
+    ledger?: TaskPollerLedgerOptions;
+}
+export declare class A2ATaskPoller {
+    private readonly client;
+    private readonly taskId;
+    private readonly contextId?;
+    private readonly maxAttempts;
+    private readonly deadlineMs?;
+    private readonly baseBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly backoffMultiplier;
+    private readonly now;
+    private readonly sleep;
+    private readonly onStateChanged?;
+    private readonly ledger?;
+    constructor(options: TaskPollerOptions);
+    /** 第 attempt 次（1-based）尝试后的退避延迟。 */
+    private backoffFor;
+    private recordObservation;
+    /**
+     * 轮询到稳定观察点。返回：
+     *   completed/canceled/failed    远端终态；
+     *   input-required               远端等待输入（稳定点，轮询不再推进）；
+     *   timeout                      墙钟截止先于终态；
+     *   budget_exhausted             瞬态错误耗尽 attempt 预算；
+     *   rejected                     fail-closed（未知状态 / 非法转换 / 不可重试错误）。
+     */
+    poll(): Promise<PollResult>;
+}

package/dist/a2a/task/poller.js

@@ -0,0 +1,184 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * 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.
+ */
+/**
+ * A2A Task 轮询器（基线 §18.3 / §23 恢复第 4 步 "re-fetch remote task state"）。
+ *
+ * 风格对齐仓库 Task Scheduler（src/agent/buyer/scheduler.ts）：确定性核心 +
+ * 预算/截止约束 + 错误分类收敛，不崩整个 tick。本模块把「预算」具体化为：
+ *
+ *   - maxAttempts     轮询预算（attempt 上限，含首轮）；
+ *   - deadlineMs      从 start 起的绝对截止（墙钟），截止前不再发起新一轮；
+ *   - baseBackoffMs / maxBackoffMs / backoffMultiplier
+ *                     指数退避（delay = min(base * mult^(attempt-1), max)）。
+ *
+ * 行为：
+ *   - 每个 attempt 调 client.getTask(taskId)；解析出的状态经
+ *     TaskLifecycleTracker 校验转换合法性（completed → working 这类非法回退
+ *     fail-closed，协议违规不猜测）。
+ *   - 终态（completed/canceled/failed）与 input-required 都是稳定观察点：
+ *     input-required 表示远端在等输入，轮询不会推进它，返回后由调用方决定。
+ *   - 瞬态错误（timeout / network / http_status / jsonrpc_error）退避重试；
+ *     schema_invalid / invalid_response / unsafe_target 或未知状态是
+ *     fail-closed 的「不可重试」错误 —— 拒绝，不猜测。
+ *   - 每次任务状态变化经 onStateChanged（含 Ledger 落账）记录证据。
+ */
+import { A2AClientError } from "../client/index.js";
+import { isTerminalTaskState, isWaitingTaskState, TaskLifecycleTracker, TaskStateError, } from "./state.js";
+import { recordTaskObservation } from "./ledger.js";
+const DEFAULTS = {
+    maxAttempts: 10,
+    baseBackoffMs: 250,
+    maxBackoffMs: 5000,
+    backoffMultiplier: 2,
+};
+export class A2ATaskPoller {
+    client;
+    taskId;
+    contextId;
+    maxAttempts;
+    deadlineMs;
+    baseBackoffMs;
+    maxBackoffMs;
+    backoffMultiplier;
+    now;
+    sleep;
+    onStateChanged;
+    ledger;
+    constructor(options) {
+        this.client = options.client;
+        this.taskId = options.taskId;
+        this.contextId = options.contextId;
+        this.maxAttempts = options.maxAttempts ?? DEFAULTS.maxAttempts;
+        this.deadlineMs = options.deadlineMs;
+        this.baseBackoffMs = options.baseBackoffMs ?? DEFAULTS.baseBackoffMs;
+        this.maxBackoffMs = options.maxBackoffMs ?? DEFAULTS.maxBackoffMs;
+        this.backoffMultiplier = options.backoffMultiplier ?? DEFAULTS.backoffMultiplier;
+        this.now = options.now ?? (() => Date.now());
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.onStateChanged = options.onStateChanged;
+        this.ledger = options.ledger;
+    }
+    /** 第 attempt 次（1-based）尝试后的退避延迟。 */
+    backoffFor(attempt) {
+        const raw = this.baseBackoffMs * Math.pow(this.backoffMultiplier, Math.max(0, attempt - 1));
+        return Math.min(raw, this.maxBackoffMs);
+    }
+    async recordObservation(task, from, to) {
+        if (this.ledger !== undefined) {
+            recordTaskObservation({
+                ledger: this.ledger.ledger,
+                negotiation_id: this.ledger.negotiation_id,
+                task_id: this.taskId,
+                task_state: to,
+                context_id: this.contextId ?? task.contextId,
+                message_id: task.status.message?.messageId,
+                identity: this.ledger.identity,
+                capability: this.ledger.capability,
+                occurred_at: new Date(this.now()).toISOString(),
+            });
+        }
+        if (this.onStateChanged !== undefined) {
+            await this.onStateChanged({ task, from, to });
+        }
+    }
+    /**
+     * 轮询到稳定观察点。返回：
+     *   completed/canceled/failed    远端终态；
+     *   input-required               远端等待输入（稳定点，轮询不再推进）；
+     *   timeout                      墙钟截止先于终态；
+     *   budget_exhausted             瞬态错误耗尽 attempt 预算；
+     *   rejected                     fail-closed（未知状态 / 非法转换 / 不可重试错误）。
+     */
+    async poll() {
+        const start = this.now();
+        const deadline = this.deadlineMs === undefined ? Number.POSITIVE_INFINITY : start + this.deadlineMs;
+        const tracker = new TaskLifecycleTracker();
+        let lastError;
+        let lastTask;
+        let attempts = 0;
+        for (;;) {
+            // 截止与预算在每次尝试前检查：attempts 语义 = 已执行的轮询次数。
+            if (this.now() >= deadline) {
+                return { status: "timeout", attempts, lastError, state: tracker.current() ?? undefined, task: lastTask };
+            }
+            if (attempts >= this.maxAttempts) {
+                return {
+                    status: "budget_exhausted",
+                    attempts,
+                    lastError,
+                    state: tracker.current() ?? undefined,
+                    task: lastTask,
+                };
+            }
+            attempts += 1;
+            let task;
+            try {
+                task = await this.client.getTask(this.taskId);
+            }
+            catch (err) {
+                lastError = err;
+                lastTask = undefined;
+                if (err instanceof A2AClientError) {
+                    const kind = err.kind;
+                    if (kind === "schema_invalid" ||
+                        kind === "invalid_response" ||
+                        kind === "unsafe_target") {
+                        // 响应不可信：不重试，fail-closed。
+                        return { status: "rejected", attempts, lastError: err, reason: kind };
+                    }
+                    // timeout / network / http_status / jsonrpc_error → 瞬态，退避重试。
+                }
+                else {
+                    return { status: "rejected", attempts, lastError: err, reason: "unknown_error" };
+                }
+                if (attempts >= this.maxAttempts) {
+                    return { status: "budget_exhausted", attempts, lastError: err };
+                }
+                await this.sleep(this.backoffFor(attempts));
+                continue;
+            }
+            lastTask = task;
+            const observed = task.status.state;
+            const before = tracker.current();
+            let after;
+            try {
+                after = tracker.observe(observed);
+            }
+            catch (err) {
+                lastError = err;
+                return {
+                    status: "rejected",
+                    attempts,
+                    lastError: err,
+                    reason: err instanceof TaskStateError ? err.code : "invalid_state",
+                    task,
+                };
+            }
+            if (after !== before) {
+                await this.recordObservation(task, before, after);
+            }
+            if (isTerminalTaskState(after) || isWaitingTaskState(after)) {
+                return { status: after, attempts, task, state: after };
+            }
+            // submitted / working：继续轮询。先检查截止，再退避。
+            if (this.now() >= deadline) {
+                return { status: "timeout", attempts, lastError, state: after, task };
+            }
+            await this.sleep(this.backoffFor(attempts));
+        }
+    }
+}
+//# sourceMappingURL=poller.js.map

package/dist/a2a/task/poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.js","sourceRoot":"","sources":["../../../src/a2a/task/poller.ts"],"names":[],"mappings":"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"}