@cellarnode/ui 0.201.1 → 0.203.0

package/dist/agent/role-cards/fixtures.js

@@ -0,0 +1,401 @@
+import { z } from "zod";
+/** @internal Story and test fixtures for the role cards. Plain data, no behaviour. */
+const MASKED = { masked: true, display: "b***@buyer.example" };
+export const offerFull = {
+    offerId: "11111111-1111-4111-8111-111111111111",
+    status: "in_negotiation",
+    viewerRole: "producer",
+    product: "Riesling Spatlese 2022",
+    opportunity: "Nordic red wine tender, autumn 2026",
+    counterparty: "Nordic Wine Imports AB",
+    price: "9.40",
+    priceType: "per bottle",
+    currency: "EUR",
+    volume: "6,000 bottles",
+    validThrough: "2026-12-01",
+    round: 2,
+    awaiting: "you",
+    counts: { messages: 14, attachments: 2 },
+    link: "/offers/11111111-1111-4111-8111-111111111111",
+    detail: {
+        kind: "offer",
+        id: "11111111-1111-4111-8111-111111111111",
+        focus: ["terms.price"],
+    },
+    actions: [
+        {
+            id: "open-thread",
+            label: "Open the thread",
+            kind: "navigate",
+            href: "/offers/11111111-1111-4111-8111-111111111111/chat",
+        },
+        {
+            id: "counter",
+            label: "Counter this offer",
+            kind: "propose",
+            tool: "counter_received_offer",
+            args: { offerId: "11111111-1111-4111-8111-111111111111" },
+            tier: "reversible",
+        },
+    ],
+};
+export const offerMinimal = { offerId: "o-2", status: "draft" };
+export const offerMasked = {
+    ...offerFull,
+    counterparty: MASKED,
+    status: "awaiting_counterparty_acceptance",
+    awaiting: "counterparty",
+    actions: undefined,
+};
+export const offerAccepted = {
+    ...offerFull,
+    status: "accepted",
+    awaiting: "none",
+    actions: undefined,
+};
+export const offerRejected = {
+    ...offerFull,
+    status: "rejected",
+    awaiting: "none",
+    actions: undefined,
+};
+export const offerLongText = {
+    ...offerFull,
+    product: "Gewurztraminer Grand Cru Vendanges Tardives Cuvee Reserve de la Famille 2019 magnum in individual wooden gift box",
+    counterparty: "Internationale Weinhandelsgesellschaft fur Spezialitaten und Raritaten mbH & Co. KG",
+};
+export const offerProposal = {
+    ...offerFull,
+    actions: undefined,
+    proposal: {
+        kind: "offer",
+        id: "11111111-1111-4111-8111-111111111111",
+        changes: [
+            { path: "terms.price", before: "9.40", after: "9.10" },
+            { path: "terms.paymentTerms", before: null, after: "30 days" },
+        ],
+        tool: "counter_received_offer",
+        tier: "reversible",
+    },
+};
+export const productFull = {
+    name: "Riesling Spatlese",
+    producer: "Weingut Sonnenhang",
+    category: "wine",
+    subtype: "white",
+    vintage: 2022,
+    abv: "12.5%",
+    volume: "750 ml",
+    packaging: "bottle",
+    certifications: ["organic", "sustainable"],
+    variantCount: 3,
+    matchCount: 2,
+    validation: "pending_review",
+    readiness: {
+        percent: 80,
+        canApprove: false,
+        blockers: 1,
+        recommendations: 2,
+        acknowledgements: 1,
+    },
+    link: "/portfolio/p1",
+    detail: { kind: "variant", id: "v1", focus: ["readiness.blockers"] },
+    actions: [
+        {
+            id: "fix",
+            label: "Fix what is missing",
+            kind: "edit",
+            tool: "update_variant",
+            args: { variantId: "v1" },
+            tier: "reversible",
+        },
+    ],
+};
+export const productReady = {
+    ...productFull,
+    validation: "approved",
+    readiness: { percent: 100, canApprove: true },
+    actions: undefined,
+};
+export const productMinimal = { name: "Lager" };
+export const productProposal = {
+    ...productFull,
+    actions: undefined,
+    proposal: {
+        kind: "variant",
+        id: "v1",
+        changes: [
+            { path: "abv", before: "12.5", after: "13" },
+            { path: "productionVolume", before: null, after: 12000 },
+        ],
+        tool: "update_variant",
+        tier: "reversible",
+    },
+};
+export const opportunityOpen = {
+    name: "Red wine for the Nordic monopoly, autumn 2026",
+    buyer: MASKED,
+    market: "Sweden",
+    country: "SE",
+    category: "wine",
+    subtype: "red",
+    volume: "20,000 bottles",
+    priceRange: "8 to 11 EUR",
+    deadline: "2026-11-30",
+    daysRemaining: 49,
+    status: "open",
+    requirements: ["organic", "screw cap", "750 ml", "vintage 2023 or newer"],
+    link: "/opportunities/o1",
+    detail: { kind: "opportunity", id: "o1" },
+    actions: [
+        {
+            id: "match",
+            label: "See my matches",
+            kind: "navigate",
+            href: "/matches",
+        },
+    ],
+};
+export const opportunityExpired = {
+    ...opportunityOpen,
+    buyer: "Systembolaget",
+    status: "expired",
+    daysRemaining: -3,
+    actions: undefined,
+};
+export const opportunityMinimal = { name: "Tender" };
+export const matchStrong = {
+    matchId: "m-1",
+    score: 4.5,
+    label: "Strong fit",
+    product: { name: "Riesling Spatlese 2022", link: "/portfolio/p1" },
+    opportunity: {
+        name: "Nordic red wine tender",
+        buyer: "Buyer AB",
+        country: "SE",
+        link: "/opportunities/o1",
+    },
+    explanation: "Category, volume and price all sit inside what the buyer asked for; the organic certificate is on file.",
+    volume: "6,000 bottles",
+    price: "9 EUR",
+    deadline: "2026-11-30",
+    daysRemaining: 49,
+    link: "/matches/m-1",
+    detail: { kind: "match", id: "m-1" },
+    actions: [
+        {
+            id: "interested",
+            label: "Mark interested",
+            kind: "propose",
+            tool: "mark_match_interested",
+            args: { matchId: "m-1" },
+            tier: "reversible",
+        },
+    ],
+};
+export const matchWeak = {
+    ...matchStrong,
+    score: 1.8,
+    label: "Weak fit",
+    explanation: "Price is above the buyer's range.",
+    actions: undefined,
+};
+export const matchMid = {
+    ...matchStrong,
+    score: 3,
+    label: "Possible fit",
+    actions: undefined,
+};
+export const matchDeclined = {
+    ...matchStrong,
+    declined: true,
+    actions: undefined,
+};
+export const matchMasked = {
+    ...matchStrong,
+    opportunity: { name: "Private tender", buyer: MASKED },
+    actions: undefined,
+};
+export const matchMinimal = { matchId: "m-3", score: 0 };
+/**
+ * The tables the cellarnode-mcp agents emit for the link tools (`agents/src/role-result-cards.ts`, CEL-2447), as they shape them:
+ * a `link` that is the surface's own internal path, null for a field the tool did not have, a last row that says a list was cut
+ * short, and a file column keyed by who wrote it (`counterpartyFile`: the other side's offer file; `producerFile` and
+ * `producerBeverage`: a producer's public documents and beverages as an importer sees them; `file`: the caller's own).
+ */
+const fileColumns = (fileKey) => [
+    { key: fileKey, label: "File" },
+    { key: "type", label: "Type" },
+];
+const OFFER_ID = "11111111-1111-4111-8111-111111111111";
+const ORG_ID = "22222222-2222-4222-8222-222222222222";
+/** `get_offer_file_link`: the offer page, where the file opens. The file came from the other side of the offer. */
+export const tableOfferFile = {
+    columns: fileColumns("counterpartyFile"),
+    rows: [{ counterpartyFile: "Spec sheet Riesling 2022.pdf", type: "application/pdf" }],
+    link: `/offers/${OFFER_ID}`,
+};
+/** `get_org_document_link`, as the producer's agent draws it. The caller's own document. */
+export const tableOrgDocument = {
+    columns: fileColumns("file"),
+    rows: [{ file: "Certificate of registration", type: "registration" }],
+    link: "/organisation/profile",
+};
+/** `get_org_document_link`, as the importer's agent draws it: the importer has the same organisation profile page. */
+export const tableImporterOrgDocument = {
+    columns: fileColumns("file"),
+    rows: [{ file: "Company registration extract.pdf", type: "registration" }],
+    link: "/organisation/profile",
+};
+/** `get_attachment_link`, as the producer's agent draws it: where the file is shown (a product gallery). */
+export const tableAttachment = {
+    columns: fileColumns("file"),
+    rows: [{ file: "Front label.png", type: null }],
+    link: "/portfolio/p1/products/v1/gallery",
+};
+/** `list_producer_documents`, as the importer's agent draws it: three columns and the row that says the list was cut short. */
+export const tableProducerDocuments = {
+    columns: [...fileColumns("producerFile"), { key: "uploaded", label: "Uploaded" }],
+    rows: [
+        { producerFile: "Organic certificate 2026.pdf", type: "certificate", uploaded: "2026-08-02" },
+        { producerFile: "Price list autumn.xlsx", type: "price_list", uploaded: "2026-09-14" },
+        { producerFile: "Tasting notes.pdf", type: null, uploaded: null },
+        { producerFile: "More documents not shown", type: null, uploaded: null },
+    ],
+    link: `/producers/${ORG_ID}`,
+};
+/** `get_producer_showcase`, as the importer's agent draws it: a version count at the tool's cap on a cut list reads "20+". */
+export const tableProducerShowcase = {
+    columns: [
+        { key: "producerBeverage", label: "Beverage" },
+        { key: "category", label: "Category" },
+        { key: "country", label: "Country" },
+        { key: "versions", label: "Versions" },
+    ],
+    rows: [
+        { producerBeverage: "Riesling Spatlese", category: "wine", country: "DE", versions: 3 },
+        { producerBeverage: "Pinot Noir Reserve", category: "wine", country: "DE", versions: "20+" },
+        { producerBeverage: "Apfelschorle", category: null, country: "DE", versions: 1 },
+        {
+            producerBeverage: "More beverages or versions not shown",
+            category: null,
+            country: null,
+            versions: null,
+        },
+    ],
+    link: `/producers/${ORG_ID}`,
+};
+/** An e-label producer's attachment: the e-label app keeps its producer area under `/app`. */
+export const tableElabelAttachment = {
+    columns: fileColumns("file"),
+    rows: [{ file: "Lab report 2026-03.pdf", type: "lab_report" }],
+    link: "/app/portfolio/p1/products/v1",
+};
+export const tableEmpty = {
+    columns: fileColumns("file"),
+    rows: [],
+    link: "/offers/o1",
+};
+/** A file name that fills the card: it wraps inside its cell, and a table wider than the card scrolls inside the card. */
+export const tableLongText = {
+    columns: [...fileColumns("counterpartyFile"), { key: "uploaded", label: "Uploaded" }],
+    rows: [
+        {
+            counterpartyFile: "Gewurztraminer_Grand_Cru_Vendanges_Tardives_Cuvee_Reserve_de_la_Famille_2019_magnum_in_individual_wooden_gift_box_final_approved_v7.pdf",
+            type: "A very long description of what kind of document this is, written by the other side and run on well past any sensible length for a table cell",
+            uploaded: "2026-09-14",
+        },
+    ],
+    link: `/offers/${OFFER_ID}`,
+};
+/** A masked column, a masked cell in an open column, and a plain value the server forgot to mask. */
+export const tableMasked = {
+    columns: [
+        { key: "name", label: "Contact" },
+        { key: "email", label: "Email", masked: true },
+        { key: "phone", label: "Phone" },
+    ],
+    rows: [
+        {
+            name: "Anna Berg",
+            email: { masked: true, display: "a***@buyer.example" },
+            phone: { masked: true, display: "+46 ** *** 12" },
+        },
+        { name: "Karl Holm", email: "karl.holm@buyer.example", phone: null },
+    ],
+};
+/** Paths the story and test hosts accept. */
+export const allowFixtureLink = (path) => /^\/(offers|portfolio|opportunities|matches)(\/|$)/.test(path);
+const argsByLastSegment = (changes, id, idArg) => ({
+    [idArg]: id,
+    ...Object.fromEntries(changes.map((c) => [c.path.split(".").pop(), c.after])),
+});
+/** A host tool catalog for stories and tests. Tiers, titles and target kinds live HERE, never on a card. */
+export const fixtureCatalog = {
+    counter_received_offer: {
+        name: "counter_received_offer",
+        title: "Counter the received offer",
+        tier: "reversible",
+        inputSchema: z.object({
+            offerId: z.string().min(1),
+            price: z.string().optional(),
+            paymentTerms: z.string().optional(),
+        }),
+        targetArg: "offerId",
+        targetKind: "offer",
+        argsFromChanges: (changes, id) => argsByLastSegment(changes, id, "offerId"),
+    },
+    update_variant: {
+        name: "update_variant",
+        title: "Update product version",
+        tier: "reversible",
+        inputSchema: z.object({
+            variantId: z.string(),
+            abv: z.string().optional(),
+            productionVolume: z.number().optional(),
+        }),
+        targetArg: "variantId",
+        targetKind: "variant",
+        argsFromChanges: (changes, id) => argsByLastSegment(changes, id, "variantId"),
+    },
+    mark_match_interested: {
+        name: "mark_match_interested",
+        title: "Mark the match as interested",
+        tier: "reversible",
+        inputSchema: z.object({ matchId: z.string() }),
+        targetArg: "matchId",
+        targetKind: "match",
+    },
+    discard_offer: {
+        name: "discard_offer",
+        title: "Discard the offer",
+        tier: "destructive",
+        inputSchema: z.object({ offerId: z.string() }),
+        targetArg: "offerId",
+        targetKind: "offer",
+    },
+    delete_product: {
+        name: "delete_product",
+        title: "Delete the product",
+        tier: "destructive",
+        inputSchema: z.object({ productId: z.string() }),
+        targetArg: "productId",
+        targetKind: "product",
+    },
+    get_offer: {
+        name: "get_offer",
+        title: "Read an offer",
+        tier: "read",
+        inputSchema: z.object({ offerId: z.string() }),
+    },
+};
+/** The records a story host would fetch for a proposal's Apply, keyed `kind:id`. */
+export const fixtureRecords = {
+    "offer:11111111-1111-4111-8111-111111111111": {
+        name: "Riesling Spatlese 2022 for Nordic Wine Imports",
+        terms: { price: "9.40", paymentTerms: null },
+    },
+    "variant:v1": { name: "Riesling Spatlese 2022", abv: "12.5", productionVolume: null },
+};
+export const fixtureFetchRecord = async (kind, id) => fixtureRecords[`${kind}:${id}`] ?? null;
+//# sourceMappingURL=fixtures.js.map

package/dist/agent/role-cards/fixtures.js.map

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

package/dist/agent/role-cards/host-contract.d.ts

@@ -0,0 +1,214 @@
+import type { CardAction, CardDetail, CardProposal, DataTableData, MatchCardData, OfferCardData, OpportunityCardData, ProductCardData } from "@cellarnode/agent-cards/zod4";
+/**
+ * @internal The HOST side of the card contract (CEL-2445, `@cellarnode/agent-cards` README "Host contract (MUST)").
+ * A card's `actions` and `proposal` are claims by the model. These pure helpers are where a host turns a claim into
+ * something it may act on, or refuses. The card composites call them THEMSELVES, so the safe path is the only path:
+ * `AgentCardActions` hands the host a `CardConfirmPlan` (never the raw action) and `AgentProposalDiff` hands it the result of
+ * `planProposalApply` (never the raw proposal).
+ *
+ * 1. the tier comes ONLY from the host catalog, by `tool` (`card.tier` is advisory; a mismatch or unknown tool drops the action);
+ * 2. the confirm plan is built from the catalog's tool title and the ACTUAL validated args, never the model's `label`;
+ * 3. `open` and `navigate` never run a tool;
+ * 4. a proposal's Apply re-fetches the record, diffs server truth against `after`, binds the tool's target-id arg to `proposal.id`,
+ *    and binds the proposal to the card's subject (`expected`) and to the tool's `targetKind`;
+ * 5. args go through the tool's own input schema.
+ *
+ * No I/O except the host-supplied `fetchRecord`; nothing here runs a tool.
+ */
+export type CatalogTier = "read" | "reversible" | "destructive" | "costly";
+export type DetailKind = CardProposal["kind"];
+export interface AgentToolCatalogEntry {
+    name: string;
+    /** What the confirm UI calls the tool. Comes from the catalog, never from a card. */
+    title: string;
+    tier: CatalogTier;
+    /** The tool's own input schema (any zod 3.25 or 4 schema, or anything with `safeParse`). */
+    inputSchema: {
+        safeParse: (value: unknown) => {
+            success: true;
+            data: unknown;
+        } | {
+            success: false;
+            error?: unknown;
+        };
+    };
+    /** The argument that carries the id of the record the tool acts on. Required for any tool a proposal may name. */
+    targetArg?: string;
+    /** The kind of record the tool acts on. Required for any tool a proposal may name; a proposal of another kind is refused. */
+    targetKind?: DetailKind;
+    /** How a proposal's changes become this tool's args. Default: one arg per change path. `targetArg` is bound to `proposal.id` AFTER this runs. */
+    argsFromChanges?: (changes: CardProposal["changes"], id: string) => Record<string, unknown>;
+    /** The human label of a fetched record for the confirm title. Default: its `name`, `title` or `label` string. */
+    recordLabel?: (record: Record<string, unknown>) => string | undefined;
+}
+export type AgentToolCatalog = Readonly<Record<string, AgentToolCatalogEntry>>;
+export type DropReason = "unknown_tool" | "tier_mismatch" | "tool_on_navigation" | "tool_missing";
+export interface DroppedAction {
+    id: string;
+    reason: DropReason;
+}
+/**
+ * Rules 1 and 3 over a card's actions. Keeps an action only when it is safe to offer: an `open`/`navigate` carries no tool,
+ * an `edit`/`propose` names a tool the catalog knows, and a declared `tier` equals the catalog's. Everything else is dropped
+ * (never "corrected"), and the reasons are returned for logging.
+ */
+export declare function resolveCardActions(actions: readonly CardAction[] | undefined, catalog: AgentToolCatalog): {
+    actions: CardAction[];
+    dropped: DroppedAction[];
+};
+/**
+ * `resolveCardActions`, then what the person SEES comes from the catalog, not the model: a write is labelled with the catalog
+ * title ("Tidy up" cannot front a delete) and its `tier` is stamped from the catalog, so danger styling and the confirm hint
+ * never depend on what the model declared. A read tool keeps the model's caption and carries no tier.
+ */
+export declare function actionsForDisplay(actions: readonly CardAction[] | undefined, catalog: AgentToolCatalog | undefined): CardAction[];
+/**
+ * The actions a card actually OFFERS the person: what `actionsForDisplay` accepts, and then only what the host can act on. A tool
+ * action needs the host's `onAction` (`canRunTools`); a link needs the host's `allowLink` to accept its `href`. The one rule behind
+ * both the action row and anything that decides whether to draw a row at all.
+ */
+export declare function offeredActions(actions: readonly CardAction[] | undefined, catalog: AgentToolCatalog | undefined, host: {
+    canRunTools: boolean;
+    allowLink?: (path: string) => boolean;
+}): CardAction[];
+export interface ConfirmRow {
+    /** The argument name. */
+    label: string;
+    value: string;
+}
+export interface CardConfirmPlan {
+    tool: string;
+    /** The catalog's title for the tool, followed by the fetched record's name when there is one. NEVER the card's `label`. */
+    title: string;
+    /** The catalog's tier. */
+    tier: CatalogTier;
+    /** Every non-read tool confirms. */
+    requiresConfirm: boolean;
+    /** The validated arguments the tool would receive. */
+    args: Record<string, unknown>;
+    /** The same arguments, one row each, for the confirm UI. */
+    rows: ConfirmRow[];
+    /** The fetched record's label (a proposal's subject), when it has one. */
+    subject?: string;
+}
+export type BuildConfirmFailure = "not_a_tool_action" | "unknown_tool" | "tier_mismatch" | "invalid_args";
+/**
+ * Rules 1, 2, 3 and 5 for one action: the plan the confirm UI renders. Its title, tier and rows come from the catalog and
+ * the tool's validated args; the action's `label` is not read.
+ */
+export declare function buildConfirm(action: CardAction, catalog: AgentToolCatalog): {
+    ok: true;
+    plan: CardConfirmPlan;
+} | {
+    ok: false;
+    reason: BuildConfirmFailure;
+};
+/**
+ * Find a dotted or bracketed path (`a.b[0].c`) in a record. `found` is false for a missing key, so "absent" is not confused with
+ * a present `null`. Refuses prototype keys and array `length`.
+ */
+export declare function lookupPath(record: unknown, path: string): {
+    found: boolean;
+    value: unknown;
+};
+/** The value at a path, or `undefined` when absent. */
+export declare function readPath(record: unknown, path: string): unknown;
+/** The record's own name: the first of `name`, `title`, `label` that is a string. Not yet cleaned. */
+export declare const recordName: (record: Record<string, unknown>) => string | undefined;
+/**
+ * The host's own label for a fetched record, when its catalog has one: the `recordLabel` of a tool that acts on this kind of record
+ * (the tools a card names come first). Cleaned like a confirm title. `undefined` when no tool has one or it yields nothing. A
+ * `recordLabel` is host code: one that throws is skipped, never allowed to take the drawer down.
+ */
+export declare function catalogRecordLabel(catalog: AgentToolCatalog | undefined, kind: DetailKind, record: Record<string, unknown>, toolsNamedByCard?: readonly (string | undefined)[]): string | undefined;
+export interface ProposalDiffRow {
+    path: string;
+    /** What the SERVER has now (from the re-fetched record). The model's `before` is never shown as truth. */
+    before: unknown;
+    after: CardProposal["changes"][number]["after"];
+    /** What the model claimed `before` was ("proposed from"); kept so a stale refusal can show the mismatch. */
+    claimedBefore: CardProposal["changes"][number]["before"];
+    /** `already_applied`: the server already has `after`. `pending`: the server still has what the model said. */
+    state: "pending" | "already_applied";
+}
+export type ApplyProposalFailure = "unknown_tool" | "tier_mismatch" | "no_target_arg" | "no_target_kind" | "kind_mismatch" | "subject_mismatch" | "target_override" | "record_unavailable" | "unknown_path" | "stale" | "nothing_to_apply" | "invalid_args";
+export interface ProposalApplyPlan {
+    plan: CardConfirmPlan;
+    /** Server truth against `after`, one row per change (already-applied rows included, marked). */
+    diff: ProposalDiffRow[];
+    /** The proposal this plan was built for. */
+    proposal: CardProposal;
+}
+export type PlanProposalResult = ({
+    ok: true;
+} & ProposalApplyPlan) | {
+    ok: false;
+    reason: ApplyProposalFailure;
+    conflicts?: ProposalDiffRow[];
+    paths?: string[];
+};
+/**
+ * Rule 4 (with 1, 2 and 5): what a proposal's Apply may do. `expected` is the subject the CARD is about (its `detail`, or its
+ * offerId or matchId): a proposal for any other record is refused, as is one whose `kind` is not the tool's `targetKind`.
+ * Re-fetches the record by `kind` + `id`; a change whose path is absent from it is refused, a change whose `before` no longer
+ * matches is STALE and refuses the whole proposal, one already at `after` is skipped; the tool's `targetArg` is bound to
+ * `proposal.id` (a change that tries to set it is refused); the args go through the tool's input schema; the plan title names
+ * the fetched record.
+ */
+export declare function planProposalApply(proposal: CardProposal, catalog: AgentToolCatalog, fetchRecord: (kind: DetailKind, id: string) => Promise<unknown>, expected: Pick<CardDetail, "kind" | "id">): Promise<PlanProposalResult>;
+/** The subject a card is about: its `detail` pointer. Cards that carry an id of their own (offer, match) pass it explicitly. */
+export declare const subjectOf: (detail: CardDetail | undefined, fallback?: Pick<CardDetail, "kind" | "id">) => Pick<CardDetail, "kind" | "id"> | undefined;
+/**
+ * Rules 1 and 3 over a whole parsed card: keeps only the actions `actionsForDisplay` accepts and drops a `proposal` whose tool is
+ * unknown, whose tier differs from the catalog's or whose tool lacks a `targetArg` or `targetKind`. With NO catalog every
+ * tool-bearing action and every proposal is dropped (secure default): only `open`/`navigate`/tool-less actions remain.
+ */
+export declare function sanitizeCardForHost<T extends {
+    actions?: CardAction[];
+    proposal?: CardProposal;
+}>(card: T, catalog: AgentToolCatalog | undefined): T;
+export declare const ROLE_AGENT_CARD_TYPES: readonly ["OfferCard", "ProductCard", "OpportunityCard", "MatchCard", "DataTable"];
+export type RoleAgentCardType = (typeof ROLE_AGENT_CARD_TYPES)[number];
+/** The cards that are about ONE record. A `DataTable` is a list: it has no subject, and `readRoleCard` drops any pointer it carries. */
+type RecordCardType = Exclude<RoleAgentCardType, "DataTable">;
+/**
+ * Does the card's `detail` pointer name what the card is about? An offer's or a match's must name its own id, a product's must be a
+ * product or a variant, an opportunity's an opportunity. A card with no pointer agrees (nothing to disagree with). The cards and
+ * `readRoleCard` both call this, so a disagreeing card is refused the same way everywhere, never reconciled.
+ */
+export declare function detailAgrees(cardType: RecordCardType, data: {
+    detail?: CardDetail;
+    offerId?: string;
+    matchId?: string;
+}): boolean;
+type Subject = Pick<CardDetail, "kind" | "id">;
+export type RoleCardRead = {
+    cardType: "OfferCard";
+    data: OfferCardData;
+    subject: Subject;
+} | {
+    cardType: "MatchCard";
+    data: MatchCardData;
+    subject: Subject;
+} | {
+    cardType: "ProductCard";
+    data: ProductCardData;
+    subject: Subject | undefined;
+} | {
+    cardType: "OpportunityCard";
+    data: OpportunityCardData;
+    subject: Subject | undefined;
+} | {
+    cardType: "DataTable";
+    data: DataTableData;
+    subject: undefined;
+};
+/**
+ * The ONE way a host turns what an agent sent into a role card it may draw: parse against the agent-cards schema, refuse a card
+ * whose `detail` disagrees with it (`detailAgrees`), then `sanitizeCardForHost` against the host catalog. `null` for an unknown
+ * type, data that fails the schema, or a disagreeing card. `subject` is the record THIS card is about (its offerId or matchId, or its
+ * `detail`), what a proposal is bound to. `renderRoleAgentCard` and the inspector drawer both read through here.
+ */
+export declare function readRoleCard(cardType: string, data: unknown, catalog: AgentToolCatalog | undefined): RoleCardRead | null;
+export {};
+//# sourceMappingURL=host-contract.d.ts.map

package/dist/agent/role-cards/host-contract.d.ts.map

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