@withpica/mcp-server 2.103.0 → 2.104.0

package/dist/tools/handovers.js

@@ -0,0 +1,302 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+/**
+ * ADR-333 D5 — building a catalogue for a client and handing it over, for
+ * assistants (plan #2808 §10).
+ *
+ * Organisation side: pica_handover_create, pica_handover_send. Client side:
+ * pica_handover_answer, which only says where to answer.
+ *
+ * Each organisation-side tool calls one /api/admin/handovers route, which
+ * holds no rules of its own: lib/services/catalogue-handovers.ts decides
+ * every step and refuses with a code and a plain sentence, passed on as is.
+ *
+ * Sending emails a client and offers them a catalogue, so it is the person's
+ * own decision (plan §10, "sending needs a human confirm"):
+ *  - from a connected app or agent grant, pica_handover_send is
+ *    `approvalMode: "human"`: the MCP route stages an approval, and on
+ *    approval lib/services/handover-approvals.ts sends through the service,
+ *    never this file;
+ *  - from a credential the route refuses as HUMAN_CONFIRMATION_REQUIRED, the
+ *    tool gives the screen to send it on.
+ *
+ * Accepting ownership is a person's own act (Orchestrator ruling 2026-10-12,
+ * option A): the client's routes take a signed-in session only, and no key
+ * reads them. pica_handover_answer therefore reads nothing and changes
+ * nothing; it gives the screen where the person answers.
+ */
+import { ApiError } from "@withpica/mcp-sdk";
+import { formatSuccess } from "@withpica/mcp-utils";
+import { typedError } from "./error-envelope.js";
+import { parseApiErrorBody } from "./api-error-body.js";
+import { webOrigin } from "./relationships.js";
+import { HANDOVERS_PATH, NEW_HANDOVER_PATH, handoverPath, } from "./relationship-copy.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const NAME_MAX = 200;
+const EMAIL_MAX = 320;
+/** The relationship the organisation keeps once the client accepts. */
+export const HANDOVER_KEPT_TYPES = [
+    "administrator",
+    "representative",
+    "viewer",
+];
+const HANDOVER_ID = {
+    type: "string",
+    format: "uuid",
+    description: "The hand-over's id (handover_id from pica_handover_create, or from the hand-over's link).",
+};
+function invalid(fields) {
+    return typedError("VALIDATION_ERROR", Object.values(fields).join(" "), {
+        fields,
+        nothing_written: true,
+    });
+}
+function text(args, key, max, what) {
+    const v = args[key];
+    if (typeof v !== "string" || v.trim().length === 0 || v.length > max)
+        return invalid({
+            [key]: `${key} is required: ${what}, at most ${max} characters.`,
+        });
+    return v.trim();
+}
+function isResult(v) {
+    return typeof v === "object" && v !== null && "content" in v;
+}
+/**
+ * A refusal from a hand-over route, as a typed result: the service's code
+ * and sentence as they are. HUMAN_CONFIRMATION_REQUIRED becomes the screen
+ * to do it on. A network failure or a 5xx is rethrown to the registry.
+ */
+function refusal(err, origin, screen) {
+    if (!(err instanceof ApiError) || err.status >= 500 || err.status === 0)
+        throw err;
+    const body = parseApiErrorBody(err);
+    const code = (body.code ?? `HTTP_${err.status}`).toUpperCase();
+    const message = body.message ?? "PICA refused this.";
+    if (code === "HUMAN_CONFIRMATION_REQUIRED") {
+        const url = `${origin}${screen.path}`;
+        return typedError(code, `Nothing was done: ${screen.doing} needs the person to confirm it themselves in PICA. Give them this link: ${url}`, { screen_url: url, nothing_written: true, retry_safe: false });
+    }
+    return typedError(code, message, {
+        nothing_written: true,
+        retry_safe: code === "RATE_LIMITED",
+    });
+}
+export class HandoverTools {
+    pica;
+    origin;
+    constructor(pica, apiUrl) {
+        this.pica = pica;
+        this.origin = webOrigin(apiUrl);
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_handover_create",
+                    scope: "write:catalog",
+                    audiences: ["stdio", "http", "public"],
+                    tier: "write",
+                    description: "Use when the user asks: 'set up a catalogue for my client', 'build Alice's catalogue so she can take it over', 'start a hand-over'. " +
+                        "For an organisation that prepares a catalogue for a client who will own it. Creates the catalogue, with your organisation as its temporary builder; nothing is sent and nobody is emailed. " +
+                        "While it is being prepared you can enter facts, but nothing can be published, agreed or signed in your organisation's favour. " +
+                        "relationship_type is what your organisation keeps once the client accepts. " +
+                        "To send again on a catalogue whose last hand-over was declined, expired or withdrawn, pass catalogue_org_id instead of catalogue_name. " +
+                        "When it is ready, send it with pica_handover_send.",
+                    workflows: "handover-required",
+                    vernacular_kind: "specialist",
+                    vernacular_reason: "Creates a catalogue owned by no one yet, for a named client; used by organisations that build catalogues for clients, by exact name.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            catalogue_name: {
+                                type: "string",
+                                maxLength: NAME_MAX,
+                                description: "The new catalogue's name, usually the client's name as they'd want to see it. Give this or catalogue_org_id, not both.",
+                            },
+                            catalogue_org_id: {
+                                type: "string",
+                                format: "uuid",
+                                description: "Instead of catalogue_name: a catalogue your organisation built whose last hand-over was declined, expired or withdrawn, to send again.",
+                            },
+                            client_name: {
+                                type: "string",
+                                maxLength: NAME_MAX,
+                                description: "The client's name.",
+                            },
+                            client_email: {
+                                type: "string",
+                                format: "email",
+                                maxLength: EMAIL_MAX,
+                                description: "The client's email. They accept by signing in to PICA with this address, once it is confirmed.",
+                            },
+                            relationship_type: {
+                                type: "string",
+                                enum: [...HANDOVER_KEPT_TYPES],
+                                description: "What your organisation keeps once they accept. administrator: keeps the details up to date and registers songs; split and custody changes need the owner's yes. representative: sees the catalogue and suggests changes the owner approves. viewer: sees it, nothing more.",
+                            },
+                        },
+                        required: ["client_name", "client_email", "relationship_type"],
+                    },
+                    requiredOneOf: [["catalogue_name", "catalogue_org_id"]],
+                },
+                executor: this.create.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_handover_send",
+                    scope: "write:catalog",
+                    audiences: ["stdio", "http", "public"],
+                    tier: "write",
+                    approvalMode: "human",
+                    description: "Send a catalogue your organisation prepared to its client, who then has 60 days to accept and become its owner. " +
+                        "It emails the client at the address given to pica_handover_create. You can withdraw it on screen until they answer. " +
+                        "Pass handover_id, and expected_version if you have it; if the hand-over changed since, nothing is sent. " +
+                        "From a connected app this asks the person to approve first; otherwise, when PICA needs the person to confirm, it gives the link to send it on screen.",
+                    workflows: "handover-required",
+                    vernacular_kind: "specialist",
+                    vernacular_reason: "Emails a client and offers them ownership of a catalogue; the organisation's own decision, invoked by exact name.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            handover_id: HANDOVER_ID,
+                            expected_version: {
+                                type: "integer",
+                                minimum: 1,
+                                description: "Optional. The hand-over's version as you last read it. If it changed since, nothing is sent.",
+                            },
+                        },
+                        required: ["handover_id"],
+                    },
+                },
+                executor: this.send.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_handover_answer",
+                    scope: "read:catalog",
+                    audiences: ["stdio", "http", "public"],
+                    tier: "read",
+                    description: "Use when the user asks: 'someone prepared a catalogue for me, how do I take it over?', 'I got an email to accept my catalogue', 'how do I accept my catalogue?'. " +
+                        "Shows where to accept a catalogue prepared for you. It does not accept or decline, and it reads nothing. " +
+                        "Accepting ownership is the person's own act: they sign in with the address it was sent to, keep or remove each item that names the organisation that built it, then accept or decline. " +
+                        "Give handover_id from the email's link to point at that one; without it, the link lists everything waiting for them. " +
+                        "For an organisation preparing one, use pica_handover_create.",
+                    workflows: "handover-required",
+                    vernacular_kind: "creator-entry",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            handover_id: {
+                                ...HANDOVER_ID,
+                                description: "Optional. The hand-over's id, from the link in the email they received.",
+                            },
+                        },
+                        required: [],
+                    },
+                },
+                executor: this.answer.bind(this),
+            },
+        ];
+    }
+    async create(args) {
+        const named = args.catalogue_name !== undefined;
+        const reissue = args.catalogue_org_id !== undefined;
+        if (named === reissue)
+            return invalid({
+                catalogue_name: "Give catalogue_name for a new catalogue, or catalogue_org_id to send one again; not both.",
+            });
+        let catalogue;
+        if (reissue) {
+            if (typeof args.catalogue_org_id !== "string" ||
+                !UUID.test(args.catalogue_org_id))
+                return invalid({
+                    catalogue_org_id: "catalogue_org_id must be a catalogue's id.",
+                });
+            catalogue = { catalogue_org_id: args.catalogue_org_id };
+        }
+        else {
+            const name = text(args, "catalogue_name", NAME_MAX, "the catalogue's name");
+            if (isResult(name))
+                return name;
+            catalogue = { catalogue_name: name };
+        }
+        const clientName = text(args, "client_name", NAME_MAX, "the client's name");
+        if (isResult(clientName))
+            return clientName;
+        const clientEmail = text(args, "client_email", EMAIL_MAX, "the client's email");
+        if (isResult(clientEmail))
+            return clientEmail;
+        if (!EMAIL.test(clientEmail))
+            return invalid({ client_email: "client_email is not an email address." });
+        const type = args.relationship_type;
+        if (!HANDOVER_KEPT_TYPES.includes(type))
+            return invalid({
+                relationship_type: `relationship_type must be one of: ${HANDOVER_KEPT_TYPES.join(", ")}.`,
+            });
+        let created;
+        try {
+            created = await this.pica.handovers.create({
+                ...catalogue,
+                client_name: clientName,
+                client_email: clientEmail,
+                relationship_type: type,
+            });
+        }
+        catch (err) {
+            return refusal(err, this.origin, {
+                path: NEW_HANDOVER_PATH,
+                doing: "preparing a catalogue for a client",
+            });
+        }
+        const url = `${this.origin}${handoverPath(created.handover_id)}`;
+        return formatSuccess(`Prepared a catalogue for ${clientName}. Nothing has been sent. When it's ready, send it with pica_handover_send; the person can also review and send it here: ${url}`, {
+            handover_id: created.handover_id,
+            catalogue_org_id: created.catalogue_org_id,
+            status: "building",
+            screen_url: url,
+        });
+    }
+    async send(args) {
+        const id = args.handover_id;
+        if (typeof id !== "string" || !UUID.test(id))
+            return invalid({
+                handover_id: "handover_id must be a hand-over's id.",
+            });
+        const v = args.expected_version;
+        if (v !== undefined &&
+            (typeof v !== "number" || !Number.isInteger(v) || v < 1))
+            return invalid({
+                expected_version: "expected_version must be a whole number from 1.",
+            });
+        let sent;
+        try {
+            sent = await this.pica.handovers.send(id, v === undefined ? {} : { expected_version: v });
+        }
+        catch (err) {
+            return refusal(err, this.origin, {
+                path: handoverPath(id),
+                doing: "sending a hand-over",
+            });
+        }
+        const url = `${this.origin}${handoverPath(id)}`;
+        return formatSuccess(`Sent to ${sent.client_name}. They have until ${sent.expires_at?.slice(0, 10) ?? "the deadline"} to accept. Withdraw it here until they answer: ${url}`, {
+            handover_id: sent.handover_id,
+            status: sent.status,
+            sent_at: sent.sent_at,
+            expires_at: sent.expires_at,
+            version: sent.version,
+            screen_url: url,
+        });
+    }
+    async answer(args) {
+        const id = args.handover_id;
+        if (id !== undefined && (typeof id !== "string" || !UUID.test(id)))
+            return invalid({
+                handover_id: "handover_id must be the id from the hand-over's link.",
+            });
+        const url = `${this.origin}${id ? handoverPath(id) : HANDOVERS_PATH}`;
+        return formatSuccess(`Nothing was accepted or declined: that's done by the person, signed in to PICA with the address it was sent to. Give them this link: ${url}`, { screen_url: url, nothing_written: true });
+    }
+}
+//# sourceMappingURL=handovers.js.map

package/dist/tools/handovers.js.map

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

package/dist/tools/index.d.ts

@@ -46,7 +46,7 @@ export interface NextStepHint {
  * Optional in W1; W4 flips it to required after W2's resource registry
  * lands so every tool is forced to declare its workflow at compile time.
  */
-export type WorkflowTag = "work-required" | "recording-required" | "work-credits-required" | "recording-credits-required" | "person-required" | "audio-upload-required" | "enrichment-resolve-required" | "agreement-required" | "multimedia-required" | "export-required" | "claim-required" | "session-required" | "split-sheet-required" | "recording-splits-required" | "sync-placement-required" | "infrastructure";
+export type WorkflowTag = "work-required" | "recording-required" | "work-credits-required" | "recording-credits-required" | "person-required" | "audio-upload-required" | "enrichment-resolve-required" | "agreement-required" | "multimedia-required" | "export-required" | "claim-required" | "session-required" | "split-sheet-required" | "recording-splits-required" | "sync-placement-required" | "relationship-required" | "handover-required" | "infrastructure";
 /**
  * ADR-226 Decision 2 — vernacular intent posture for every tool.
  *
@@ -606,6 +606,11 @@ export declare class ToolRegistry {
      * mutable state that would race between concurrent requests.
      */
     executeTool(name: string, args: Record<string, any>, ctx?: ToolExecutorContext): Promise<any>;
+    /**
+     * `executeTool` after the catalogue is settled. `args` are the arguments as
+     * called (gates, tokens, audit); `executorArgs` are what the tool receives.
+     */
+    private executeToolInCatalogue;
 }
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

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

package/dist/tools/index.js

@@ -1,4 +1,6 @@
 // Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+import { currentCatalogue, runInCatalogue, } from "@withpica/mcp-sdk";
+import { CATALOGUE_ARG, CATALOGUE_PROPERTY, catalogueRefusal, settleCatalogueAnswer, takesCatalogue, } from "./catalogue-argument.js";
 import { WorksTools } from "./works.js";
 import { PeopleTools } from "./people.js";
 import { ApprovalsTools } from "./approvals.js";
@@ -56,6 +58,8 @@ import { MyRecentQuestionsTools } from "./my-recent-questions.js";
 import { AgentIdentityTools } from "./agent-identity.js";
 import { RoyaltiesTools } from "./royalties.js";
 import { RightsTools } from "./rights.js";
+import { RelationshipTools } from "./relationships.js";
+import { HandoverTools } from "./handovers.js";
 import { StatementsTools } from "./statements.js";
 import { SelectionsTools } from "./selections.js";
 import { ShareLinksTools } from "./share-links.js";
@@ -963,6 +967,34 @@ export class ToolRegistry {
         syncFitTools.getTools().forEach((tool) => {
             this.tools.set(tool.definition.name, tool);
         });
+        // ADR-333 — who looks after whose catalogue (both sides).
+        const relationshipTools = new RelationshipTools(pica, this.config?.picaApiUrl);
+        relationshipTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // ADR-333 D5 — a catalogue built for a client, then handed over.
+        const handoverTools = new HandoverTools(pica, this.config?.picaApiUrl);
+        handoverTools.getTools().forEach((tool) => {
+            this.tools.set(tool.definition.name, tool);
+        });
+        // ADR-333 D7 — every tool that acts on a catalogue's own records takes an
+        // optional `catalogue` (./catalogue-argument.ts). Added here, once, so
+        // tools/list, pica_tool_details and pica_execute all see the same schema,
+        // and before aliases are cloned so an alias carries it too.
+        for (const tool of this.tools.values()) {
+            if (!takesCatalogue(tool.definition))
+                continue;
+            tool.definition = {
+                ...tool.definition,
+                inputSchema: {
+                    ...tool.definition.inputSchema,
+                    properties: {
+                        ...tool.definition.inputSchema.properties,
+                        [CATALOGUE_ARG]: CATALOGUE_PROPERTY,
+                    },
+                },
+            };
+        }
         // Discovery meta-tools — registered last so pica_tool_details can look up
         // all tool definitions. Only active when discoveryMode is enabled.
         if (this.config?.discoveryMode) {
@@ -1585,6 +1617,13 @@ export class ToolRegistry {
         const cacheKey = this.getSessionCacheKey();
         if (!cacheKey)
             return;
+        // Not in a client's catalogue: the counts read (catalog/stats) does not
+        // open through a relationship, so it would be refused, and that refusal
+        // would be judged as part of the tool's own answer (settleCatalogueAnswer
+        // reads every request the call made). The counts would be the caller's
+        // own catalogue's anyway, not the client's.
+        if (currentCatalogue() !== undefined)
+            return;
         try {
             incrementSessionMutations(cacheKey);
             const sessionState = await buildSessionState(cacheKey, this.fetchSessionCounts);
@@ -1611,6 +1650,44 @@ export class ToolRegistry {
      * mutable state that would race between concurrent requests.
      */
     async executeTool(name, args, ctx) {
+        // ADR-333 D7 — a call naming a client catalogue runs entirely inside it:
+        // the confirmation preview, the executor and the session-state read all
+        // make their requests for that catalogue. The argument stays in the
+        // confirmation token's arguments (so a token confirmed for one client
+        // cannot be replayed for another) and in the audit row, but is removed
+        // before the executor, which would otherwise send it on to the app.
+        const catalogue = args?.[CATALOGUE_ARG];
+        // pica_execute may carry the wrapped tool's arguments flat, `catalogue`
+        // among them; it reaches this method again for the wrapped tool, which
+        // is where the argument is checked and applied.
+        if (catalogue === undefined || name === "pica_execute") {
+            return this.executeToolInCatalogue(name, args, args, ctx);
+        }
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new ToolExecutionError(`Tool not found: ${name}`);
+        }
+        const refusal = catalogueRefusal(tool.definition, catalogue);
+        if (refusal) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "CATALOGUE_NOT_SUPPORTED", message: refusal }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { [CATALOGUE_ARG]: _catalogue, ...executorArgs } = args;
+        const { value, report } = await runInCatalogue(catalogue, () => this.executeToolInCatalogue(name, args, executorArgs, ctx));
+        return settleCatalogueAnswer(name, value, report);
+    }
+    /**
+     * `executeTool` after the catalogue is settled. `args` are the arguments as
+     * called (gates, tokens, audit); `executorArgs` are what the tool receives.
+     */
+    async executeToolInCatalogue(name, args, executorArgs, ctx) {
         const startTime = Date.now();
         const tool = this.tools.get(name);
         if (!tool) {
@@ -1743,7 +1820,7 @@ export class ToolRegistry {
         }
         // ── Normal execution ──
         try {
-            const result = await tool.executor(args, ctx);
+            const result = await tool.executor(executorArgs, ctx);
             // Guard response size — envelope-aware (ops 41ff656c / 893e3e29): list
             // responses over the 100KB cap get whole-item trimming + a real resume
             // cursor (next_offset / recovery_hint) in both views; non-list shapes