@harrylabsj/kiwi 0.6.0

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

@@ -0,0 +1,72 @@
+/**
+ * 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）。
+ *
+ * 完全使用 A2A 原生 Task lifecycle，Kiwi 不发明另一套任务状态（§18.3）。
+ * 六态 + `unknown` 作为 fail-closed 桶：
+ *
+ *   submitted → working → input-required → working → completed | canceled | failed
+ *
+ * 规则：
+ * - 终态（completed / canceled / failed）不可再转换（§18.3 语义）；
+ * - `unknown` 永远不是合法源/目标状态 —— 远端回 unknown 一律 fail-closed 拒绝，
+ *   绝不猜测（基线 §4.6）；
+ * - 同状态重复观察（如轮询时再次看到 working）是合法 no-op；
+ * - 状态机不自行产生商业承诺，只对观察到的远端状态做合法性判定。
+ */
+import { type A2ATaskState } from "../client/index.js";
+export declare const A2A_TASK_STATES_REAL: readonly Exclude<A2ATaskState, "unknown">[];
+/** 终态：任务生命周期结束，不可再转换。 */
+export declare const A2A_TASK_TERMINAL_STATES: readonly ["completed", "canceled", "failed"];
+export type A2ATaskTerminalState = (typeof A2A_TASK_TERMINAL_STATES)[number];
+/** A2A Task 转换表：源状态 → 允许的下一状态（不含同状态 no-op，见 transitionTaskState）。 */
+export declare const A2A_TASK_TRANSITIONS: Record<Exclude<A2ATaskState, "unknown">, readonly A2ATaskState[]>;
+export type TaskStateErrorCode = "unknown_state" | "illegal_transition";
+export declare class TaskStateError extends Error {
+    readonly code: TaskStateErrorCode;
+    constructor(code: TaskStateErrorCode, message: string);
+}
+/** 是否为 A2A_TASK_STATES 枚举内的字符串（含 unknown 桶）。 */
+export declare function isTaskState(value: unknown): value is A2ATaskState;
+/** 是否为真实可转换的任务状态（排除 unknown 桶）。 */
+export declare function isRealTaskState(value: unknown): value is Exclude<A2ATaskState, "unknown">;
+export declare function isTerminalTaskState(value: A2ATaskState | undefined): value is A2ATaskTerminalState;
+export declare function isWaitingTaskState(value: A2ATaskState | undefined): value is "input-required";
+/**
+ * 校验一次任务状态转换。fail-closed：
+ * - 源/目标任一为 `unknown` → unknown_state（不猜测）；
+ * - 转换不在转换表 → illegal_transition；
+ * - 源 === 目标 → 同状态 no-op，返回该状态（轮询重观察合法）。
+ */
+export declare function transitionTaskState(from: A2ATaskState, to: A2ATaskState): A2ATaskState;
+/**
+ * 任务状态追踪器：记录当前已知状态，并对每次新观察做转换校验。
+ * 轮询器用它判定远端状态变化是否合法；非法变化（如 completed → working）
+ * 是协议违规，fail-closed 拒绝。
+ */
+export declare class TaskLifecycleTracker {
+    private currentState;
+    /** 当前已知状态；尚无任何观察时为 null。 */
+    current(): A2ATaskState | null;
+    isTerminal(): boolean;
+    /**
+     * 观察一个新状态。返回观察后的当前状态（同状态 no-op 返回原值）。
+     * 首次观察接受任何真实状态；后续观察必须落在转换表内。
+     * `unknown` 或非法转换抛 TaskStateError。
+     */
+    observe(observed: A2ATaskState): A2ATaskState;
+}

package/dist/a2a/task/state.js

@@ -0,0 +1,119 @@
+/**
+ * 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）。
+ *
+ * 完全使用 A2A 原生 Task lifecycle，Kiwi 不发明另一套任务状态（§18.3）。
+ * 六态 + `unknown` 作为 fail-closed 桶：
+ *
+ *   submitted → working → input-required → working → completed | canceled | failed
+ *
+ * 规则：
+ * - 终态（completed / canceled / failed）不可再转换（§18.3 语义）；
+ * - `unknown` 永远不是合法源/目标状态 —— 远端回 unknown 一律 fail-closed 拒绝，
+ *   绝不猜测（基线 §4.6）；
+ * - 同状态重复观察（如轮询时再次看到 working）是合法 no-op；
+ * - 状态机不自行产生商业承诺，只对观察到的远端状态做合法性判定。
+ */
+import { A2A_TASK_STATES } from "../client/index.js";
+export const A2A_TASK_STATES_REAL = A2A_TASK_STATES.filter((s) => s !== "unknown");
+/** 终态：任务生命周期结束，不可再转换。 */
+export const A2A_TASK_TERMINAL_STATES = ["completed", "canceled", "failed"];
+/** A2A Task 转换表：源状态 → 允许的下一状态（不含同状态 no-op，见 transitionTaskState）。 */
+export const A2A_TASK_TRANSITIONS = {
+    submitted: ["working", "input-required", "completed", "canceled", "failed"],
+    working: ["input-required", "completed", "canceled", "failed"],
+    "input-required": ["working", "completed", "canceled", "failed"],
+    completed: [],
+    canceled: [],
+    failed: [],
+};
+export class TaskStateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "TaskStateError";
+        this.code = code;
+    }
+}
+/** 是否为 A2A_TASK_STATES 枚举内的字符串（含 unknown 桶）。 */
+export function isTaskState(value) {
+    return typeof value === "string" && A2A_TASK_STATES.includes(value);
+}
+/** 是否为真实可转换的任务状态（排除 unknown 桶）。 */
+export function isRealTaskState(value) {
+    return isTaskState(value) && value !== "unknown";
+}
+export function isTerminalTaskState(value) {
+    return (value !== undefined && A2A_TASK_TERMINAL_STATES.includes(value));
+}
+export function isWaitingTaskState(value) {
+    return value === "input-required";
+}
+/**
+ * 校验一次任务状态转换。fail-closed：
+ * - 源/目标任一为 `unknown` → unknown_state（不猜测）；
+ * - 转换不在转换表 → illegal_transition；
+ * - 源 === 目标 → 同状态 no-op，返回该状态（轮询重观察合法）。
+ */
+export function transitionTaskState(from, to) {
+    if (!isRealTaskState(from)) {
+        throw new TaskStateError("unknown_state", `source task state ${String(from)} is unknown`);
+    }
+    if (!isRealTaskState(to)) {
+        throw new TaskStateError("unknown_state", `target task state ${String(to)} is unknown`);
+    }
+    if (from === to)
+        return to;
+    const allowed = A2A_TASK_TRANSITIONS[from];
+    if (!allowed.includes(to)) {
+        throw new TaskStateError("illegal_transition", `illegal A2A task transition: ${from} -> ${to}`);
+    }
+    return to;
+}
+/**
+ * 任务状态追踪器：记录当前已知状态，并对每次新观察做转换校验。
+ * 轮询器用它判定远端状态变化是否合法；非法变化（如 completed → working）
+ * 是协议违规，fail-closed 拒绝。
+ */
+export class TaskLifecycleTracker {
+    currentState = null;
+    /** 当前已知状态；尚无任何观察时为 null。 */
+    current() {
+        return this.currentState;
+    }
+    isTerminal() {
+        return isTerminalTaskState(this.currentState ?? undefined);
+    }
+    /**
+     * 观察一个新状态。返回观察后的当前状态（同状态 no-op 返回原值）。
+     * 首次观察接受任何真实状态；后续观察必须落在转换表内。
+     * `unknown` 或非法转换抛 TaskStateError。
+     */
+    observe(observed) {
+        if (this.currentState === null) {
+            if (!isRealTaskState(observed)) {
+                throw new TaskStateError("unknown_state", `observed task state ${String(observed)} is unknown`);
+            }
+            this.currentState = observed;
+            return observed;
+        }
+        const next = transitionTaskState(this.currentState, observed);
+        this.currentState = next;
+        return next;
+    }
+}
+//# sourceMappingURL=state.js.map

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

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

package/dist/a2a/ucp-agent.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.
+ */
+/**
+ * UCP-Agent 头（RFC 8941 Structured Field Dictionary）—— 基线 §25.1 Platform
+ * Profile Advertisement。HTTP-based A2A bindings 用它声明 platform（buyer）的
+ * UCP profile URI。
+ *
+ * Wire 形状：
+ *
+ *   UCP-Agent: profile="https://buyer.example/.well-known/ucp"
+ *
+ *   - RFC 8941 Dictionary：`key=value` 成员，逗号分隔；
+ *   - `profile` 成员是 String 类型 → 必须用双引号包裹、内部 `\` 与 `"` 转义；
+ *   - 成员可带参数（`;...`），解析时忽略参数。
+ *
+ * 出站：A2AClientOptions.ucpAgentProfile 配置时由 client 注入。
+ * 入站：server 解析并暴露给 handler（不强制 —— 头缺失/畸形只当未声明，绝不拒绝）。
+ *
+ * 零新增依赖；纯函数，无 I/O。
+ */
+export declare const UCP_AGENT_HEADER = "ucp-agent";
+export declare const UCP_AGENT_PROFILE_MEMBER = "profile";
+/** RFC 8941 §4.2.6 String 序列化：转义 `\` 与 `"` 后加引号。 */
+export declare function serializeRfc8941String(value: string): string;
+/** 单成员 `profile="<uri>"` 的字典序列化（§25.1）。 */
+export declare function serializeUcpAgentHeader(profileUri: string): string;
+/** RFC 8941 §4.2.6 String 反序列化（宽容：引号内非 `\"`/`\\` 转义按原样保留）。 */
+export declare function unquoteRfc8941String(raw: string): string;
+/**
+ * 解析 UCP-Agent 头（RFC 8941 dictionary），取 `profile` 成员的值。
+ * 头缺失 / 空 / 无 `profile` 成员 → undefined。成员参数（`;...`）被忽略。
+ *
+ * 只读解析（不强制）：畸形头返回 undefined，绝不导致请求被拒绝（§25.1
+ * "缺省不拒绝"）。
+ */
+export declare function parseUcpAgentHeader(value: string | string[] | undefined): string | undefined;

package/dist/a2a/ucp-agent.js

@@ -0,0 +1,78 @@
+/**
+ * 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-Agent 头（RFC 8941 Structured Field Dictionary）—— 基线 §25.1 Platform
+ * Profile Advertisement。HTTP-based A2A bindings 用它声明 platform（buyer）的
+ * UCP profile URI。
+ *
+ * Wire 形状：
+ *
+ *   UCP-Agent: profile="https://buyer.example/.well-known/ucp"
+ *
+ *   - RFC 8941 Dictionary：`key=value` 成员，逗号分隔；
+ *   - `profile` 成员是 String 类型 → 必须用双引号包裹、内部 `\` 与 `"` 转义；
+ *   - 成员可带参数（`;...`），解析时忽略参数。
+ *
+ * 出站：A2AClientOptions.ucpAgentProfile 配置时由 client 注入。
+ * 入站：server 解析并暴露给 handler（不强制 —— 头缺失/畸形只当未声明，绝不拒绝）。
+ *
+ * 零新增依赖；纯函数，无 I/O。
+ */
+export const UCP_AGENT_HEADER = "ucp-agent";
+export const UCP_AGENT_PROFILE_MEMBER = "profile";
+/** RFC 8941 §4.2.6 String 序列化：转义 `\` 与 `"` 后加引号。 */
+export function serializeRfc8941String(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** 单成员 `profile="<uri>"` 的字典序列化（§25.1）。 */
+export function serializeUcpAgentHeader(profileUri) {
+    return `${UCP_AGENT_PROFILE_MEMBER}=${serializeRfc8941String(profileUri)}`;
+}
+/** RFC 8941 §4.2.6 String 反序列化（宽容：引号内非 `\"`/`\\` 转义按原样保留）。 */
+export function unquoteRfc8941String(raw) {
+    if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+        return raw.slice(1, -1).replace(/\\(["\\])/g, "$1");
+    }
+    return raw;
+}
+/**
+ * 解析 UCP-Agent 头（RFC 8941 dictionary），取 `profile` 成员的值。
+ * 头缺失 / 空 / 无 `profile` 成员 → undefined。成员参数（`;...`）被忽略。
+ *
+ * 只读解析（不强制）：畸形头返回 undefined，绝不导致请求被拒绝（§25.1
+ * "缺省不拒绝"）。
+ */
+export function parseUcpAgentHeader(value) {
+    if (value === undefined)
+        return undefined;
+    const joined = Array.isArray(value) ? value.join(",") : value;
+    const members = joined
+        .split(",")
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0);
+    for (const member of members) {
+        const eq = member.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = member.slice(0, eq).trim().toLowerCase();
+        if (key !== UCP_AGENT_PROFILE_MEMBER)
+            continue;
+        const valuePart = member.slice(eq + 1).split(";")[0].trim();
+        return unquoteRfc8941String(valuePart);
+    }
+    return undefined;
+}
+//# sourceMappingURL=ucp-agent.js.map

package/dist/a2a/ucp-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucp-agent.js","sourceRoot":"","sources":["../../src/a2a/ucp-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAC5C,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAAC;AAElD,oDAAoD;AACpD,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC;AAClE,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACxD,OAAO,GAAG,wBAAwB,IAAI,sBAAsB,CAAC,UAAU,CAAC,EAAE,CAAC;AAC7E,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAChE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAoC;IACtE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9D,MAAM,OAAO,GAAG,MAAM;SACnB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,EAAE,IAAI,CAAC;YAAE,SAAS;QACtB,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrD,IAAI,GAAG,KAAK,wBAAwB;YAAE,SAAS;QAC/C,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;QAC7D,OAAO,oBAAoB,CAAC,SAAS,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/agent/agent-db.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { DatabaseSync } from "node:sqlite";
+export declare const DEFAULT_AGENTS_ROOT: string;
+/** Sanitize an agent_id for filesystem use; refuses traversal outright. */
+export declare function agentDirName(agentId: string): string;
+export declare function agentDataDir(agentId: string, root?: string): string;
+export interface AgentPaths {
+    dir: string;
+    db: string;
+    sessionsDir: string;
+    mainSession: string;
+}
+/** Create (0700) and describe one concrete agent data directory. */
+export declare function ensurePathsForDir(dir: string): AgentPaths;
+export declare function ensureAgentPaths(agentId: string, root?: string): AgentPaths;
+/** Open (and migrate) the agent's memory database; file mode 0600, fail closed on corruption. */
+export declare function openAgentDatabase(dbPath: string): DatabaseSync;

package/dist/agent/agent-db.js

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+/**
+ * Per-agent data layout and database opening (design §8):
+ *
+ *   .kiwi/agents/<agent_id>/state.sqlite        (0600; dir 0700)
+ *   .kiwi/agents/<agent_id>/sessions/main.jsonl (0600)
+ *
+ * Buyer and Merchant agents get physically separate directories, databases,
+ * session files and keys (design §17) — path components derived from the
+ * agent_id are sanitized so a profile can never escape its own directory.
+ */
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { migrateMemorySchema, MigrationError } from "./memory/schema.js";
+import { MemoryError } from "./memory/types.js";
+export const DEFAULT_AGENTS_ROOT = path.resolve(".kiwi", "agents");
+/** Sanitize an agent_id for filesystem use; refuses traversal outright. */
+export function agentDirName(agentId) {
+    if (agentId.includes("..") || agentId.includes("/") || agentId.includes("\\")) {
+        throw new MemoryError("validation", `agent_id ${agentId} is not safe for a data directory`);
+    }
+    const safe = agentId.replace(/[^A-Za-z0-9_.:-]/g, "_");
+    if (safe.length === 0) {
+        throw new MemoryError("validation", "agent_id produces an empty data directory name");
+    }
+    return safe;
+}
+export function agentDataDir(agentId, root = DEFAULT_AGENTS_ROOT) {
+    return path.join(root, agentDirName(agentId));
+}
+/** Create (0700) and describe one concrete agent data directory. */
+export function ensurePathsForDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700); // recursive mkdir only applies the mode to new components
+    const sessionsDir = path.join(dir, "sessions");
+    mkdirSync(sessionsDir, { recursive: true, mode: 0o700 });
+    chmodSync(sessionsDir, 0o700);
+    return {
+        dir,
+        db: path.join(dir, "state.sqlite"),
+        sessionsDir,
+        mainSession: path.join(sessionsDir, "main.jsonl"),
+    };
+}
+export function ensureAgentPaths(agentId, root = DEFAULT_AGENTS_ROOT) {
+    return ensurePathsForDir(agentDataDir(agentId, root));
+}
+/** Open (and migrate) the agent's memory database; file mode 0600, fail closed on corruption. */
+export function openAgentDatabase(dbPath) {
+    let db;
+    try {
+        db = new DatabaseSync(dbPath);
+    }
+    catch (err) {
+        throw new MemoryError("store_corrupted", `cannot open memory database ${dbPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (existsSync(dbPath))
+        chmodSync(dbPath, 0o600);
+    try {
+        db.exec("PRAGMA foreign_keys = ON");
+        migrateMemorySchema(db);
+    }
+    catch (err) {
+        try {
+            db.close();
+        }
+        catch {
+            // already broken; preserve the original error
+        }
+        if (err instanceof MigrationError)
+            throw err;
+        throw new MemoryError("store_corrupted", `cannot migrate memory database ${dbPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return db;
+}
+//# sourceMappingURL=agent-db.js.map

package/dist/agent/agent-db.js.map

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

package/dist/agent/buyer/buyer-tools.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 { AgentHarnessTool } from "@earendil-works/pi-agent-core";
+import { HandoffIdempotencyStore, HandoffEventStore } from "../../handoff/index.js";
+import type { AgentProfile } from "../../config/profile.js";
+import type { CommerceClient } from "../../commerce/types.js";
+import type { KiwiCatalogSource } from "../../discovery/catalog-source/index.js";
+import type { CommerceConnector } from "../connector/types.js";
+import type { AgentMode } from "../mode.js";
+import type { WriteApprovalCandidateStore } from "../merchant/action-candidate.js";
+import type { CredentialBroker } from "../merchant/credential-broker.js";
+import { type WriteGateDeps } from "../write-gate.js";
+import type { BuyerTaskStore } from "./task-store.js";
+type Tool = AgentHarnessTool<undefined>;
+export interface BuyerToolDeps {
+    store: BuyerTaskStore;
+    connector: CommerceConnector;
+    profile: AgentProfile;
+    commerceClient?: CommerceClient;
+    broker?: CredentialBroker;
+    approvals?: WriteApprovalCandidateStore;
+    mode?: () => AgentMode;
+    now: () => string;
+    /** Register /approve execution hooks for pending candidates. */
+    registerPending?: WriteGateDeps["registerPending"];
+    /** agent catalog base URL（`negotiate_buyer_task` 的 A2A 商家发现用）。 */
+    catalog?: string;
+    /**
+     * kiwi-catalog listing 源（rev1.5 CD #27 Product-first）。注入时挂载
+     * `search_listings` / `shortlist_listing` 工具；缺失时工具不挂载
+     * （fail-closed，legacy marketplace 搜索路径不变）。
+     */
+    catalogSource?: KiwiCatalogSource;
+    /**
+     * 磋商结果写记忆（kernel 注入，复用 recordNegotiation 的 remember 形状）。
+     * 记忆是尽力而为：失败不影响任务推进。
+     */
+    recordNegotiation?: (input: {
+        negotiationId: string;
+        catalogAgentId: string;
+        sku: string;
+        quantity: number;
+        offerPriceMinor?: number;
+        dealPriceMinor?: number;
+        agreementId?: string;
+    }) => Promise<string>;
+    /**
+     * KTH/0.1 Handoff 存储（v0.7.0；kernel 注入）。提供时挂载 `handoff_agreement`
+     * 工具（agreement → 审批门 → 安全交接）；缺失时工具不挂载（fail closed）。
+     */
+    handoff?: {
+        ledger: HandoffEventStore;
+        idempotency: HandoffIdempotencyStore;
+    };
+}
+export declare function buildBuyerTools(deps: BuyerToolDeps): Tool[];
+export {};