@withpica/mcp-server/dist/tools/write-receipt.d.ts

MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog

/**
 * Compact write receipts for MCP update tools (ops 61ce1dcc, 2026-09-28).
 *
 * A one-field `pica_works_update` used to answer with the whole work —
 * lyrics included — plus every open integrity gap rendered as "Next steps"
 * prose, identical on every call. An agent doing ten small edits read the
 * same record and the same three nags ten times.
 *
 * The receipt answers the question a write actually asks — "did my change
 * land, and did it open anything new?":
 *   - the entity id,
 *   - `changed`: each field the caller sent, with the value the API
 *     returned for it (so a normalised or dropped value is visible), and
 *     `unconfirmed` for fields the returned record did not echo,
 *   - prose hints ONLY for gaps that were not open before the write.
 *
 * `verbose: true` restores the full record and every hint. Only the MCP
 * tool result is shaped here — the REST routes the web UI calls are
 * unchanged. When this was written (2026-09-28) no app code read these two
 * tools' result payloads: the admin assistant's loopback passes results
 * through to its model, and `narrowToolResultForRefs` (mcp-utils
 * result-projection.ts) reads create/import results only.
 *
 * Used by pica_works_update (full receipt, including new-gaps-only) and
 * pica_credits_update (same `changed` shape; that tool's route result was
 * already small). Other write tools can adopt it by spreading
 * VERBOSE_PROPERTY into their schema and building the receipt with the
 * functions below — pica_credit_add / pica_credit_remove are the next
 * candidates, since they attach the same integrity pressure works_update did.
 */
import type { CompletionHint } from "@withpica/mcp-utils";
import type { IntegrityBlock } from "./integrity-hints.js";
/** Schema fragment every receipt-returning tool spreads into its properties. */
export declare const VERBOSE_PROPERTY: {
    readonly verbose: {
        readonly type: "boolean";
        readonly description: "Return the full updated record and every open gap instead of the compact receipt (id, changed fields, new gaps only). Default false.";
    };
};
/** Split the receipt switch off the write payload so it never reaches the API. */
export declare function takeVerbose<T extends Record<string, unknown>>(args: T): {
    verbose: boolean;
    rest: Omit<T, "verbose">;
};
/**
 * The hints in `after` whose gap was not already open in `before`. When the
 * before-state could not be read (`null`), every `after` hint counts as new —
 * PICA cannot claim a gap was already known if it never saw it.
 */
export declare function newHintsOnly(before: CompletionHint[] | null, after: CompletionHint[]): CompletionHint[];
/**
 * Each requested field with the value the API returned for it. A field the
 * returned record does not carry (e.g. one routed to a satellite table) is
 * listed in `unconfirmed` rather than echoed back as if it had been read.
 */
export declare function changedFields(requested: Record<string, unknown>, record: unknown): {
    changed: Record<string, unknown>;
    unconfirmed: string[];
};
/**
 * The integrity block trimmed to what an agent needs after a write: every
 * open gap as `{label, code, severity}` (a few bytes each, so a gap clearing
 * is still visible), the full detail only for gaps this write opened, and
 * the waived count.
 */
export declare function slimIntegrity(block: IntegrityBlock | null, openBefore: Set<string> | null): Record<string, unknown> | null;
export declare const RECEIPT_NOTE = "pass verbose: true for the full record";
//# sourceMappingURL=write-receipt.d.ts.map