@harrylabsj/kiwi 0.6.0

package/dist/agent/merchant/types.d.ts

@@ -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.
+ */
+/**
+ * Merchant capability-pack types (design §14–§15).
+ *
+ * The merchant agent manages catalog, inventory, incoming consultations and
+ * the human-review queue through these DTOs. Connector payloads are untrusted
+ * external data: every response is strictly parsed, unknown fields isolated.
+ * Private merchant values (floor prices, costs) never appear here — they live
+ * in the Vault and are only ever served to the model as metadata_only.
+ */
+/** A merchant's own catalog product (shopping-cli catalog shape). */
+export interface MerchantCatalogProduct {
+    sku: string;
+    merchant_id: string;
+    title: string;
+    description: string;
+    category: string;
+    tags: string[];
+    price: number;
+    currency: string;
+    stock: number;
+    delivery_attributes: string[];
+    /** Listing active flag. When true the product is paused/hidden from search. */
+    paused: boolean;
+}
+export interface MerchantProductInput {
+    sku: string;
+    merchant_id: string;
+    title: string;
+    price: number;
+    stock: number;
+    currency?: string;
+    category?: string;
+    tags?: string[];
+    description?: string;
+    delivery_attributes?: string[];
+}
+export interface MerchantProductPatch {
+    title?: string;
+    price?: number;
+    stock?: number;
+    currency?: string;
+    category?: string;
+    tags?: string[];
+    description?: string;
+    delivery_attributes?: string[];
+    /** pause_or_resume_listing maps to this listing flag. */
+    paused?: boolean;
+}
+export interface IncomingConsultation {
+    conversation_id: string;
+    /** e.g. waiting_merchant / waiting_buyer / human_required / closed. */
+    status: string;
+    buyer_id?: string;
+    sku?: string;
+    last_message: string;
+    last_message_at: string;
+}
+export interface HumanReviewItem {
+    review_id: string | number;
+    conversation_id: string;
+    buyer_id: string;
+    sku: string;
+    reason: string;
+    severity: string;
+    created_at: string;
+    resolved_at?: string;
+    resolution?: string;
+}
+export interface InventorySnapshot {
+    sku: string;
+    stock: number;
+    /** Observed at — never present current state as timeless fact (§18.2). */
+    observed_at: string;
+}
+/**
+ * The merchant write surface. Read calls that are merchant-scoped (listing
+ * one's own catalog, inventory, consultations, human-review queue) require the
+ * catalog credential; negotiation reads/writes require the negotiation
+ * credential. `create/update/pause` require catalog; `updateInventory` is the
+ * inventory scope. All tokens are supplied by the CredentialBroker — this
+ * client never sees or stores a token beyond the per-call header.
+ */
+export interface MerchantClient {
+    listProducts(merchantId: string): Promise<MerchantCatalogProduct[]>;
+    getProduct(sku: string): Promise<MerchantCatalogProduct>;
+    createProduct(input: MerchantProductInput): Promise<MerchantCatalogProduct>;
+    updateProduct(sku: string, patch: MerchantProductPatch): Promise<MerchantCatalogProduct>;
+    getInventorySnapshot(sku: string): Promise<InventorySnapshot>;
+    /** Inventory-scope write: set the stock of a product. */
+    updateInventory(sku: string, stock: number): Promise<MerchantCatalogProduct>;
+    listIncomingConsultations(merchantId: string): Promise<IncomingConsultation[]>;
+    getHumanReviewQueue(merchantId: string): Promise<HumanReviewItem[]>;
+    /** Pause/resume a listing (fail closed on gateways without this endpoint). */
+    pauseListing(sku: string, paused: boolean): Promise<MerchantCatalogProduct>;
+}
+export declare class MerchantClientError extends Error {
+    readonly kind: "transient" | "validation" | "not_found" | "auth";
+    constructor(kind: MerchantClientError["kind"], message: string);
+}
+/** Parse a catalog product, tolerating both the public and merchant shapes. */
+export declare function parseMerchantCatalogProduct(value: unknown): MerchantCatalogProduct;
+export declare function parseInventorySnapshot(value: unknown, sku: string): InventorySnapshot;
+export declare function parseIncomingConsultation(value: unknown): IncomingConsultation;
+export declare function parseHumanReviewItem(value: unknown): HumanReviewItem;

package/dist/agent/merchant/types.js

@@ -0,0 +1,133 @@
+/**
+ * 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.
+ */
+export class MerchantClientError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "MerchantClientError";
+        this.kind = kind;
+    }
+}
+// ---- strict parsing (isolate unknown fields) -------------------------------
+function fail(message) {
+    throw new MerchantClientError("validation", `merchant client payload rejected: ${message}`);
+}
+function reqString(value, at) {
+    if (typeof value !== "string")
+        fail(`${at} must be a string`);
+    return value;
+}
+function reqNumber(value, at) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        fail(`${at} must be a finite number`);
+    return value;
+}
+function stringArray(value, at) {
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+        fail(`${at} must be a string array`);
+    }
+    return value;
+}
+/** Parse a catalog product, tolerating both the public and merchant shapes. */
+export function parseMerchantCatalogProduct(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        fail("product must be an object");
+    }
+    const v = value;
+    return {
+        sku: reqString(v.sku, "product.sku"),
+        merchant_id: reqString(v.merchant_id, "product.merchant_id"),
+        title: reqString(v.title, "product.title"),
+        description: typeof v.description === "string" ? v.description : "",
+        category: typeof v.category === "string" ? v.category : "",
+        tags: Array.isArray(v.tags) ? stringArray(v.tags, "product.tags") : [],
+        price: reqNumber(v.price, "product.price"),
+        currency: typeof v.currency === "string" ? v.currency : "CNY",
+        stock: reqNumber(v.stock, "product.stock"),
+        delivery_attributes: Array.isArray(v.delivery_attributes)
+            ? stringArray(v.delivery_attributes, "product.delivery_attributes")
+            : [],
+        paused: typeof v.paused === "boolean" ? v.paused : v.active === false,
+    };
+}
+export function parseInventorySnapshot(value, sku) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        fail("inventory snapshot must be an object");
+    }
+    const v = value;
+    return {
+        sku: typeof v.sku === "string" ? v.sku : sku,
+        stock: reqNumber(v.stock ?? v.quantity, "inventory.stock"),
+        observed_at: typeof v.observed_at === "string" ? v.observed_at : new Date().toISOString(),
+    };
+}
+export function parseIncomingConsultation(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        fail("consultation must be an object");
+    }
+    const v = value;
+    // shopping-cli conversation summaries use `id`; the agent DTO uses
+    // `conversation_id` — accept both (fail closed only when both are absent).
+    const conversationId = typeof v.conversation_id === "string"
+        ? v.conversation_id
+        : typeof v.id === "string" || typeof v.id === "number"
+            ? String(v.id)
+            : undefined;
+    if (conversationId === undefined)
+        fail("consultation.conversation_id/id is required");
+    // Last message may be nested in `messages` (real gateway) or flat.
+    const messages = Array.isArray(v.messages) ? v.messages : [];
+    const lastMsg = messages.length > 0 ? (messages[messages.length - 1] ?? {}) : {};
+    const nestedText = typeof lastMsg.public_message === "string" ? lastMsg.public_message : "";
+    return {
+        conversation_id: conversationId,
+        status: typeof v.status === "string" ? v.status : "",
+        ...(typeof v.buyer_id === "string" ? { buyer_id: v.buyer_id } : {}),
+        ...(typeof v.sku === "string" ? { sku: v.sku } : {}),
+        last_message: typeof v.last_message === "string" ? v.last_message : nestedText,
+        last_message_at: typeof v.last_message_at === "string"
+            ? v.last_message_at
+            : typeof v.updated_at === "string"
+                ? v.updated_at
+                : new Date().toISOString(),
+    };
+}
+function reqId(value, at) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+        return value;
+    fail(`${at} must be a positive integer or non-empty string`);
+}
+export function parseHumanReviewItem(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        fail("review must be an object");
+    }
+    const v = value;
+    return {
+        // shopping-cli summaries use `id`; the DTO uses `review_id` — accept both.
+        review_id: reqId(v.review_id ?? v.id, "review.review_id/id"),
+        conversation_id: reqString(v.conversation_id ?? v.id, "review.conversation_id/id"),
+        buyer_id: reqString(v.buyer_id, "review.buyer_id"),
+        sku: reqString(v.sku, "review.sku"),
+        reason: typeof v.reason === "string" ? v.reason : "",
+        severity: typeof v.severity === "string" ? v.severity : "info",
+        created_at: reqString(v.created_at, "review.created_at"),
+        ...(typeof v.resolved_at === "string" ? { resolved_at: v.resolved_at } : {}),
+        ...(typeof v.resolution === "string" ? { resolution: v.resolution } : {}),
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/agent/merchant/types.js.map

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

package/dist/agent/mode.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/**
+ * Main-conversation runtime mode (design §16).
+ *
+ * Reuses the operator control-plane's three modes. Writes route by mode:
+ *   manual      -> advice only, never executes;
+ *   supervised  -> every write creates a content-hashed WriteApprovalCandidate that
+ *                  the operator must approve (/approve) before execution;
+ *   autopilot   -> writes within HardPolicy auto-execute; risk escalations
+ *                  still require approval.
+ *
+ * `supervised` is the safe default — a restart never silently widens
+ * authority.
+ */
+export declare const AGENT_MODES: readonly ["manual", "supervised", "autopilot"];
+export type AgentMode = (typeof AGENT_MODES)[number];
+export declare const DEFAULT_AGENT_MODE: AgentMode;
+export declare function isAgentMode(value: unknown): value is AgentMode;

package/dist/agent/mode.js

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+/**
+ * Main-conversation runtime mode (design §16).
+ *
+ * Reuses the operator control-plane's three modes. Writes route by mode:
+ *   manual      -> advice only, never executes;
+ *   supervised  -> every write creates a content-hashed WriteApprovalCandidate that
+ *                  the operator must approve (/approve) before execution;
+ *   autopilot   -> writes within HardPolicy auto-execute; risk escalations
+ *                  still require approval.
+ *
+ * `supervised` is the safe default — a restart never silently widens
+ * authority.
+ */
+export const AGENT_MODES = ["manual", "supervised", "autopilot"];
+export const DEFAULT_AGENT_MODE = "supervised";
+export function isAgentMode(value) {
+    return typeof value === "string" && AGENT_MODES.includes(value);
+}
+//# sourceMappingURL=mode.js.map

package/dist/agent/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../src/agent/mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,WAAW,CAAU,CAAC;AAG1E,MAAM,CAAC,MAAM,kBAAkB,GAAc,YAAY,CAAC;AAE1D,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzF,CAAC"}

package/dist/agent/negotiation-chat.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+/**
+ * Negotiation tools for the main conversation (design §15.1/§15.2/§15.4).
+ *
+ * `get_negotiation_snapshot` is a read-only view of an authoritative
+ * Marketplace Conversation: it claims the pending message, reads the snapshot
+ * and releases the claim so the message stays reclaimable.
+ *
+ * `submit_negotiation_decision` is a write. It reuses the existing negotiation
+ * runtime's claim -> (buyer local policy gate) -> gateway policy gate ->
+ * settlement path — it never bypasses the strategy gates. Like every write it
+ * is routed through the WriteApprovalCandidate approval gate (§16): supervised
+ * requires /approve, autopilot auto-executes within HardPolicy, manual is
+ * advice-only. Execution re-reads the marketplace routing state; if the
+ * conversation moved on, the old approval is stale.
+ *
+ * The model only ever sees these tools — never the negotiation token, which
+ * lives in the CredentialBroker.
+ */
+import type { AgentHarnessTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { AgentProfile } from "../config/profile.js";
+import { type CommerceClient } from "../commerce/types.js";
+import { type PolicyResult } from "../negotiation/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";
+type Tool = AgentHarnessTool<undefined>;
+export interface NegotiationChatDeps {
+    profile: AgentProfile;
+    commerceClient: CommerceClient;
+    broker: CredentialBroker;
+    approvals: WriteApprovalCandidateStore;
+    mode: () => AgentMode;
+    now: () => string;
+    /** Register /approve execution hooks for pending candidates. */
+    registerPending?: WriteGateDeps["registerPending"];
+    /** Buyer-side hook to update consultation_links after a decision settles. */
+    afterSettle?: (info: {
+        conversation_id: string;
+        result: PolicyResult;
+        settlement: "completed" | "failed";
+    }) => void;
+}
+export declare function buildNegotiationChatTools(deps: NegotiationChatDeps): Tool[];
+/** Render a write-gate outcome for the model and operator (no secrets). */
+export declare function writeGateText(outcome: {
+    kind: "executed";
+    candidate: {
+        candidate_id: string;
+    };
+    output: unknown;
+} | {
+    kind: "pending_approval";
+    candidate: {
+        candidate_id: string;
+    };
+} | {
+    kind: "advice_only";
+    candidate: {
+        candidate_id: string;
+    };
+} | {
+    kind: "forbidden";
+    reason: string;
+}): AgentToolResult<unknown>;
+export {};