@setluca/mcp 0.2.0 → 0.3.0

package/dist/task-tools/calls.js

@@ -1,30 +1,35 @@
-import { Effect, Option, Schema } from "effect";
-import * as z from "zod/v4";
-import { WORKSPACE_INPUT_FIELDS } from "../operations.js";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { isNotFound, LucaToolInputError } from "../errors.js";
+import { IanaTimeZone, IsoDateTime, NonEmptyString, WORKSPACE_INPUT_FIELDS, } from "../fields.js";
 import { optionalField } from "../optional-field.js";
-import { independentWrite, stringInput, taskRequest, textBody, } from "./runtime.js";
-const postCallQueue = {
+import { failureAsField, idempotencyKeyInput, operationResult, resultOrError, stringInput, taskTool, textBody, } from "./runtime.js";
+const isNonEmptyString = Schema.is(NonEmptyString);
+const postCallQueue = taskTool({
     name: "luca_post_call_queue",
     title: "List the post-call work",
     description: "Return everything waiting on the coach after a call: calls that still need a report on how they went, and attended calls with no revenue outcome recorded. The two halves are tracked separately by the API, so a call can sit on one list and not the other. Close an item with luca_close_call_loop. Example: call with {} after a day of calls.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
     },
-    readOnly: true,
-    untrustedContent: true,
+    outputSchema: Schema.Struct({
+        needingFeedback: operationResult("callEvents.needingFeedback"),
+        needingOutcome: operationResult("bookings.needsOutcome"),
+    }),
     composes: ["callEvents.needingFeedback", "bookings.needsOutcome"],
-    run: (api, operationById, input) => 
+    run: (call) => 
     // Neither read depends on the other, and Effect.all defaults to
     // concurrency 1, so without this the second waits on the first for nothing.
     Effect.all({
-        needingFeedback: api.request(taskRequest(operationById("callEvents.needingFeedback"), input)),
-        needingOutcome: api.request(taskRequest(operationById("bookings.needsOutcome"), input)),
+        needingFeedback: call("callEvents.needingFeedback"),
+        needingOutcome: call("bookings.needsOutcome"),
     }, { concurrency: "unbounded" }),
-};
+});
 /**
  * The id of the call event attached to a booking, if the API has one. A booking
  * whose call has not happened yet answers 404, which is the normal case rather
- * than a failure — so is any other read error here, because the outcome write
+ * than a failure. So is any other read error here, because the outcome write
  * below is worth doing on its own.
  */
 const CallEventId = Schema.Struct({
@@ -38,6 +43,25 @@ const ATTENDANCE_VALUES = [
     "cancelled",
 ];
 const OUTCOME_VALUES = ["won", "lost", "open"];
+const decodeOutcomeStatus = Schema.decodeUnknownOption(Schema.Literals(OUTCOME_VALUES));
+/**
+ * A field the chosen outcome status makes mandatory. The tool schema marks all
+ * three optional because which one is required depends on `outcome`, and a flat
+ * field list cannot say that, so the check lands here.
+ *
+ * It has to reach the error channel rather than throw. `outcomeBody` is built
+ * as an argument to the request the tool sends, so a throw would escape the
+ * `failureAsField` around that request and surface as a defect — after the
+ * attendance report had already landed, which is the one thing that call is
+ * there to prevent.
+ */
+function requiredFor(status, field, value) {
+    return isNonEmptyString(value)
+        ? Effect.succeed(value)
+        : Effect.fail(new LucaToolInputError({
+            message: `${field} is required when outcome is ${status}.`,
+        }));
+}
 /**
  * The revenue half of the body, shaped by the status it carries. The API takes
  * one of three variants and rejects a mix, so building it here keeps the tool
@@ -50,153 +74,136 @@ function outcomeBody(input) {
         ...optionalField("expectedVersion", input.expectedVersion),
     };
     if (input.status === "won") {
-        return {
+        return Effect.succeed({
             ...common,
             ...optionalField("amountMinor", input.amountMinor),
             ...textBody("currency", input.currency),
-        };
+        });
     }
     if (input.status === "lost") {
-        return {
-            ...common,
-            lossReasonDefinitionId: stringInput(input.lossReasonDefinitionId),
-        };
+        return Effect.map(requiredFor("lost", "lossReasonDefinitionId", input.lossReasonDefinitionId), (lossReasonDefinitionId) => ({ ...common, lossReasonDefinitionId }));
     }
-    return {
-        ...common,
-        nextFollowUpAt: stringInput(input.nextFollowUpAt),
-        followUpTimezone: stringInput(input.followUpTimezone),
-    };
+    return Effect.map(Effect.all({
+        nextFollowUpAt: requiredFor("open", "nextFollowUpAt", input.nextFollowUpAt),
+        followUpTimezone: requiredFor("open", "followUpTimezone", input.followUpTimezone),
+    }, { concurrency: 1 }), (followUp) => ({ ...common, ...followUp }));
 }
-const closeCallLoop = {
+const closeCallLoop = taskTool({
     name: "luca_close_call_loop",
     title: "Close the loop on a call",
-    description: 'File what happened on a call and what it was worth, in one call. Reports attendance on the call event (completed, no_show, rescheduled, or cancelled) and, when an outcome is given, records the booking outcome: won with an amount, lost with a reason id from luca_bookings_outcomeReasons_list, or open with the next follow-up. Nothing is sent to the lead. Example: { bookingId, attendance: "completed", outcome: "won", amountMinor: 250000, currency: "USD" }.',
+    description: 'File what happened on a call and what it was worth, in one call. Reports attendance on the call event (completed, no_show, rescheduled, or cancelled) and, when an outcome is given, records the booking outcome: won with an amount, lost with a reason id from luca_bookings_outcome_reasons_list, or open with the next follow-up. This tool sends no message to the lead itself, but the records it files start work in the API. Reporting a no_show can start no-show recovery, which schedules a message to the lead when the booking type has recovery on, so pass confirm: true only after the coach says to report the no-show. A completed call queues its summary, which can later sync to the connected CRM. A won or lost outcome queues a CRM deal-stage update, and lost also moves the lead to lost. Example: { bookingId, attendance: "completed", outcome: "won", amountMinor: 250000, currency: "USD" }.',
+    // Only a no_show can message the lead (through recovery), so only that
+    // report needs approval. The other attendance values stay ungated.
+    confirm: {
+        applies: (input) => input.attendance === "no_show",
+        description: "attendance is no_show (can start recovery messaging)",
+    },
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
-        bookingId: z
-            .string()
-            .min(1)
-            .describe("The booking whose call just happened."),
-        attendance: z
-            .enum(ATTENDANCE_VALUES)
-            .describe("What happened to the call itself."),
-        rating: z
-            .number()
-            .int()
-            .min(1)
-            .max(5)
-            .optional()
-            .describe("The coach's 1-5 rating of the call."),
-        notes: z
-            .string()
-            .min(1)
-            .max(4000)
-            .optional()
-            .describe("The coach's notes on the call, stored on the call event."),
-        outcome: z
-            .enum(OUTCOME_VALUES)
-            .optional()
-            .describe("The revenue outcome. Leave it off to report attendance only and record the money later."),
-        amountMinor: z
-            .number()
-            .int()
-            .min(0)
-            .optional()
-            .describe("Deal value in minor units (cents) when outcome is won."),
-        currency: z
-            .string()
-            .length(3)
-            .optional()
-            .describe("ISO-4217 currency for amountMinor, uppercase."),
-        lossReasonDefinitionId: z
-            .string()
-            .optional()
-            .describe("Required when outcome is lost: a reason id from luca_bookings_outcomeReasons_list."),
-        nextFollowUpAt: z
-            .string()
-            .optional()
-            .describe("Required when outcome is open: ISO-8601 follow-up time."),
-        followUpTimezone: z
-            .string()
-            .optional()
-            .describe("Required when outcome is open: IANA timezone the follow-up is scheduled in."),
-        outcomeNote: z
-            .string()
-            .min(1)
-            .max(5000)
-            .optional()
-            .describe("Note stored on the revenue outcome, separate from notes."),
-        expectedVersion: z
-            .number()
-            .int()
-            .min(0)
-            .optional()
-            .describe("The outcome version you read, when correcting an earlier outcome. A stale version returns 409 with the current one."),
-        idempotencyKey: z
-            .string()
-            .optional()
-            .describe("Reuse the same key when retrying this exact report. Both writes are scoped by route, so one key covers the pair."),
+        bookingId: NonEmptyString.annotate({
+            description: "The booking whose call just happened.",
+        }),
+        attendance: Schema.Literals(ATTENDANCE_VALUES).annotate({
+            description: "What happened to the call itself.",
+        }),
+        rating: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 5 })).annotate({
+            description: "The coach's 1-5 rating of the call.",
+        })),
+        notes: Schema.optionalKey(NonEmptyString.check(Schema.isMaxLength(4000)).annotate({
+            description: "The coach's notes on the call, stored on the call event.",
+        })),
+        outcome: Schema.optionalKey(Schema.Literals(OUTCOME_VALUES).annotate({
+            description: "The revenue outcome. Leave it off to report attendance only and record the money later.",
+        })),
+        amountMinor: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).annotate({
+            description: "Deal value in minor units (cents) when outcome is won.",
+        })),
+        currency: Schema.optionalKey(Schema.String.check(Schema.isMinLength(3), Schema.isMaxLength(3)).annotate({
+            description: "ISO-4217 currency for amountMinor, uppercase.",
+        })),
+        lossReasonDefinitionId: Schema.optionalKey(Schema.String.annotate({
+            description: "Required when outcome is lost: a reason id from luca_bookings_outcome_reasons_list.",
+        })),
+        nextFollowUpAt: Schema.optionalKey(IsoDateTime.annotate({
+            description: "Required when outcome is open: ISO-8601 follow-up time.",
+        })),
+        followUpTimezone: Schema.optionalKey(IanaTimeZone.annotate({
+            description: "Required when outcome is open: IANA timezone the follow-up is scheduled in.",
+        })),
+        outcomeNote: Schema.optionalKey(NonEmptyString.check(Schema.isMaxLength(5000)).annotate({
+            description: "Note stored on the revenue outcome, separate from notes.",
+        })),
+        expectedVersion: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).annotate({
+            description: "The outcome version you read, when correcting an earlier outcome. A stale version returns 409 with the current one.",
+        })),
+        ...idempotencyKeyInput("Reuse the same key when retrying this exact report. Both writes are scoped by route, so one key covers the pair."),
     },
-    readOnly: false,
-    untrustedContent: true,
+    outputSchema: Schema.Struct({
+        feedback: Schema.Union([
+            resultOrError("callEvents.feedback", "feedbackError"),
+            Schema.Struct({
+                reported: Schema.Literal(false),
+                reason: Schema.Literal("no_call_event_for_booking"),
+            }),
+        ]),
+        outcome: Schema.optionalKey(resultOrError("bookings.outcome.record", "outcomeError")),
+    }),
     composes: [
         "callEvents.byBooking",
         "callEvents.feedback",
         "bookings.outcome.record",
     ],
-    run: (api, operationById, input) => Effect.gen(function* () {
+    run: (call, input) => Effect.gen(function* () {
         const bookingId = stringInput(input.bookingId);
-        const page = yield* Effect.catchAll(api.request(taskRequest(operationById("callEvents.byBooking"), input, {
-            pathParams: { bookingId },
-        })), () => Effect.succeed(null));
-        const feedback = yield* Option.match(decodeCallEventId(page), {
+        const outcomeStatus = decodeOutcomeStatus(input.outcome);
+        // Built before either write. A revenue body this tool cannot assemble is
+        // a bad call rather than a failed write, and refusing it up front leaves
+        // nothing half-filed for the agent's retry to duplicate.
+        const body = Option.isSome(outcomeStatus)
+            ? yield* outcomeBody({
+                status: outcomeStatus.value,
+                note: input.outcomeNote,
+                amountMinor: input.amountMinor,
+                currency: input.currency,
+                lossReasonDefinitionId: input.lossReasonDefinitionId,
+                nextFollowUpAt: input.nextFollowUpAt,
+                followUpTimezone: input.followUpTimezone,
+                expectedVersion: input.expectedVersion,
+            })
+            : undefined;
+        // The revenue write below is worth doing even when the attendance half
+        // fails, so a failed lookup or report becomes a field rather than ending
+        // the tool call. Only a 404 means the booking has no call event; any
+        // other failure is reported as one, not mistaken for that answer.
+        const feedback = yield* failureAsField("feedbackError", call("callEvents.byBooking", { pathParams: { bookingId } }).pipe(Effect.catchIf(isNotFound, () => Effect.succeed(null)), Effect.flatMap((page) => Option.match(decodeCallEventId(page), {
             onNone: () => 
-            // No call event means attendance has nowhere to go. The revenue write
-            // below still runs — that is the half the coach is usually after.
+            // No call event means attendance has nowhere to go. The
+            // revenue write below still runs, and that is the half the
+            // coach is usually after.
             Effect.succeed({
                 reported: false,
                 reason: "no_call_event_for_booking",
             }),
-            onSome: (decoded) => 
-            // The revenue write below is worth doing even when the attendance
-            // report fails, so this failure becomes a field rather than ending
-            // the tool call.
-            independentWrite("feedbackError", api.request(taskRequest(operationById("callEvents.feedback"), input, {
+            onSome: (decoded) => call("callEvents.feedback", {
                 pathParams: { id: decoded.callEvent.id },
                 body: {
                     outcome: input.attendance,
                     ...optionalField("rating", input.rating),
                     ...textBody("notes", input.notes),
                 },
-            }))),
-        });
-        const outcomeStatus = z
-            .enum(OUTCOME_VALUES)
-            .safeParse(input.outcome ?? undefined);
-        if (!outcomeStatus.success) {
+            }),
+        }))));
+        if (body === undefined) {
             return { feedback };
         }
         // The attendance report already landed. Failing the whole tool here
         // would tell the agent nothing was written and invite a retry that files
         // the attendance twice under a fresh key.
-        const outcome = yield* independentWrite("outcomeError", api.request(taskRequest(operationById("bookings.outcome.record"), input, {
+        const outcome = yield* failureAsField("outcomeError", call("bookings.outcome.record", {
             pathParams: { id: bookingId },
-            body: outcomeBody({
-                status: outcomeStatus.data,
-                note: input.outcomeNote,
-                amountMinor: input.amountMinor,
-                currency: input.currency,
-                lossReasonDefinitionId: input.lossReasonDefinitionId,
-                nextFollowUpAt: input.nextFollowUpAt,
-                followUpTimezone: input.followUpTimezone,
-                expectedVersion: input.expectedVersion,
-            }),
-        })));
+            body,
+        }));
         return { feedback, outcome };
     }),
-};
-export const callTaskTools = [
-    postCallQueue,
-    closeCallLoop,
-];
+});
+export const callTaskTools = [postCallQueue, closeCallLoop];

package/dist/task-tools/inbox.js

@@ -1,74 +1,110 @@
-import { Effect, Record } from "effect";
-import * as z from "zod/v4";
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as R from "effect/Record";
+import * as Schema from "effect/Schema";
 import { formatError } from "../errors.js";
-import { WORKSPACE_INPUT_FIELDS } from "../operations.js";
-import { listingIds, numberInput, taskRequest, } from "./runtime.js";
+import { WORKSPACE_INPUT_FIELDS } from "../fields.js";
+import { logAgentSurfaceEvent } from "../observability.js";
+import { isPartialFailure, listingIds, numberInput, operationResult, resultOrError, taskTool, } from "./runtime.js";
 const DEFAULT_QUEUE_LIMIT = 20;
 const DEFAULT_EXPLAIN_TOP = 3;
+const TRIAGE_INBOX_TOOL_NAME = "luca_triage_inbox";
+/**
+ * One explanation, with a failed lookup carried in the result instead of
+ * cancelling the others. A queue the coach can read with two explanations
+ * missing beats no queue at all. An authorization failure still ends the call,
+ * see {@link isPartialFailure}.
+ */
+function explainOne(call, id) {
+    return call("reviewQueue.explain", { pathParams: { id } }).pipe(Effect.map((explanation) => ({
+        id,
+        explanation,
+        failed: false,
+    })), 
+    // Keep the structured formatter, not a lossy String(error): a
+    // LucaHttpError's status/requestId survive for debugging a partial
+    // failure inside the composed tool.
+    Effect.catchIf(isPartialFailure, (error) => Effect.succeed({
+        id,
+        explanation: { explainError: formatError(error) },
+        failed: true,
+    })));
+}
+/**
+ * How the explain fan-out went, as counts.
+ *
+ * `mcp.tool.called` reports this tool as a success even when every explanation
+ * inside it failed, because a failed lookup comes back as an `explainError`
+ * field rather than an error result. Without this line, an explain route that
+ * is broken for every caller looks identical in logs to one that works.
+ *
+ * The single-route explain tools need no line of their own: `mcp.tool.called`
+ * already carries their name and outcome. This fan-out is the only place where
+ * a failure has nowhere else to show up.
+ *
+ * Counts only, never an id or an explanation. Both are lead-derived.
+ */
+function logExplainFanOut(attempts) {
+    if (Arr.isReadonlyArrayEmpty(attempts)) {
+        return;
+    }
+    const failed = attempts.filter((attempt) => attempt.failed).length;
+    logAgentSurfaceEvent("mcp.explain", {
+        toolName: TRIAGE_INBOX_TOOL_NAME,
+        requested: attempts.length,
+        explained: attempts.length - failed,
+        failed,
+    });
+}
 /** The review session's entry point: the queue, with the top items explained. */
-const triageInbox = {
-    name: "luca_triage_inbox",
+const triageInbox = taskTool({
+    name: TRIAGE_INBOX_TOOL_NAME,
     title: "Triage the review queue",
-    description: "Return the coach's prioritized reply queue: pending drafts with lead context and, for the top items, why Luca drafted what it drafted. Start every review session here, then act on an item with luca_approve_and_send, luca_draft_reply, or luca_reviewQueue_reject. Example: call with { explainTop: 3 } to get the queue plus explanations for the three most urgent drafts.",
+    description: "Return the coach's prioritized reply queue: pending drafts with lead context and, for the top items, why Luca drafted what it drafted. Start every review session here, then act on an item with luca_approve_and_send, luca_draft_reply, or luca_review_queue_reject. Example: call with { explainTop: 3 } to get the queue plus explanations for the three most urgent drafts.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
-        limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(50)
-            .optional()
-            .describe("Max queue items to return (default 20)."),
-        explainTop: z
-            .number()
-            .int()
-            .min(0)
-            .max(5)
-            .optional()
-            .describe("How many of the top items to attach a full explanation to (default 3)."),
+        limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 50 })).annotate({
+            description: "Max queue items to return (default 20).",
+        })),
+        explainTop: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 5 })).annotate({
+            description: "How many of the top items to attach a full explanation to (default 3).",
+        })),
     },
-    readOnly: true,
-    untrustedContent: true,
+    outputSchema: Schema.Struct({
+        queue: operationResult("reviewQueue.list"),
+        explanations: Schema.Record(Schema.String, resultOrError("reviewQueue.explain", "explainError")),
+    }),
     composes: ["reviewQueue.list", "reviewQueue.explain"],
-    run: (api, operationById, input) => Effect.gen(function* () {
-        const queue = yield* api.request(taskRequest(operationById("reviewQueue.list"), input, {
-            query: { limit: input.limit ?? DEFAULT_QUEUE_LIMIT },
-        }));
+    run: (call, input) => Effect.gen(function* () {
+        const queue = yield* call("reviewQueue.list", {
+            query: { limit: numberInput(input.limit, DEFAULT_QUEUE_LIMIT) },
+        });
         const ids = listingIds(queue, numberInput(input.explainTop, DEFAULT_EXPLAIN_TOP));
-        const explained = yield* Effect.forEach(ids, (id) => api
-            .request(taskRequest(operationById("reviewQueue.explain"), input, {
-            pathParams: { id },
-        }))
-            .pipe(Effect.catchAll((error) => 
-        // Keep the structured formatter, not a lossy String(error): a
-        // LucaHttpError's status/requestId survive for debugging a
-        // partial failure inside the composed tool.
-        Effect.succeed({ explainError: formatError(error) })), Effect.map((explanation) => [
-            id,
-            explanation,
-        ])), 
+        const attempts = yield* Effect.forEach(ids, (id) => explainOne(call, id), 
         // Effect.forEach defaults to concurrency 1 (sequential). `explainTop`
-        // caps this fan-out at 5 independent lookups, so unbounded is fine —
-        // there's no unbounded caller input that could turn this into a
-        // thundering herd.
+        // caps this fan-out at 5 independent lookups, so unbounded is fine.
+        // No caller input can grow it into a thundering herd.
         { concurrency: "unbounded" });
-        return { queue, explanations: Record.fromEntries(explained) };
+        logExplainFanOut(attempts);
+        return {
+            queue,
+            explanations: R.fromEntries(attempts.map((attempt) => [
+                attempt.id,
+                attempt.explanation,
+            ])),
+        };
     }),
-};
+});
 /** The day's opening read: the last 24h of queue activity, already counted. */
-const morningReport = {
+const morningReport = taskTool({
     name: "luca_morning_report",
     title: "Get the morning digest",
     description: "Return the coach's structured last-24h review-queue digest: queued drafts with status and confidence, plus counts by status. No model call — summarize it client-side. Example: call with {} at the start of the day.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
     },
-    readOnly: true,
-    untrustedContent: true,
+    outputSchema: operationResult("reports.morning"),
     composes: ["reports.morning"],
-    run: (api, operationById, input) => api.request(taskRequest(operationById("reports.morning"), input)),
-};
-export const inboxTaskTools = [
-    triageInbox,
-    morningReport,
-];
+    run: (call) => call("reports.morning"),
+});
+export const inboxTaskTools = [triageInbox, morningReport];