@setluca/mcp 0.2.0 → 0.3.0

package/dist/standard-schema.js

@@ -0,0 +1,215 @@
+import * as Arr from "effect/Array";
+import * as Option from "effect/Option";
+import * as P from "effect/Predicate";
+import * as R from "effect/Record";
+import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+import { fieldsWhen } from "./optional-field.js";
+import { isJsonObject, isJsonArray, } from "./serialization.js";
+/**
+ * Annotation keys that reach the JSON Schema a client reads. Effect drops
+ * annotations it does not know unless they are named here.
+ */
+function isLucaAnnotation(key) {
+    return key.startsWith("x-luca-");
+}
+/**
+ * Whether an `allOf` entry only says "this object takes other keys too". Effect
+ * writes an open object that also lists properties as the object plus such an
+ * entry; the key on the object says the same thing with less nesting.
+ */
+function isOpenObjectEntry(entry) {
+    return (isJsonObject(entry) &&
+        entry.type === "object" &&
+        "additionalProperties" in entry &&
+        Arr.every(R.keys(entry), (key) => key === "type" || key === "additionalProperties"));
+}
+/**
+ * Folds an open-object `allOf` entry back into its object. Every other node
+ * comes back unchanged.
+ */
+function foldOpenObject(node) {
+    const allOf = node.allOf;
+    if (!isJsonArray(allOf) ||
+        allOf.length !== 1 ||
+        !isOpenObjectEntry(allOf[0]) ||
+        "additionalProperties" in node) {
+        return node;
+    }
+    const { allOf: _folded, ...rest } = node;
+    const extra = allOf[0].additionalProperties;
+    return {
+        ...rest,
+        additionalProperties: isJsonObject(extra) && R.isEmptyRecord(extra) ? true : extra,
+    };
+}
+/**
+ * An `allOf` entry's keywords, flattened through any `allOf` of its own, or
+ * `undefined` when it repeats a keyword and so has to stay a separate entry.
+ */
+function flatKeywords(entry) {
+    if (!isJsonObject(entry)) {
+        return undefined;
+    }
+    const { allOf, ...own } = entry;
+    if (allOf === undefined) {
+        return own;
+    }
+    if (!isJsonArray(allOf)) {
+        return undefined;
+    }
+    return Arr.reduce(allOf, own, (merged, child) => {
+        const keywords = flatKeywords(child);
+        return merged === undefined ||
+            keywords === undefined ||
+            Arr.some(R.keys(keywords), (key) => key in merged)
+            ? undefined
+            : { ...merged, ...keywords };
+    });
+}
+/**
+ * Lifts `allOf` entries onto their node when no keyword collides. Effect
+ * writes each check, and a check group such as `isLengthBetween`, as its own
+ * entry; `{ minLength: 3, maxLength: 3, description }` says what three nested
+ * `allOf` levels say, in one level.
+ */
+function flattenAllOf(node) {
+    const { allOf, ...rest } = node;
+    if (!isJsonArray(allOf)) {
+        return node;
+    }
+    const keywords = flatKeywords({ allOf });
+    return keywords === undefined ||
+        Arr.some(R.keys(keywords), (key) => key in rest)
+        ? node
+        : { ...rest, ...keywords };
+}
+/**
+ * States the safe-integer range Effect's `isInt` already enforces, on whichever
+ * side the schema leaves open, so a client sees the same bounds the server
+ * checks.
+ */
+function safeIntegerBounds(node) {
+    if (node.type !== "integer") {
+        return node;
+    }
+    return {
+        ...node,
+        ...fieldsWhen(!("minimum" in node || "exclusiveMinimum" in node), {
+            minimum: Number.MIN_SAFE_INTEGER,
+        }),
+        ...fieldsWhen(!("maximum" in node || "exclusiveMaximum" in node), {
+            maximum: Number.MAX_SAFE_INTEGER,
+        }),
+    };
+}
+/** Applies the node rewrites above through the whole tree. */
+function tidy(value) {
+    if (isJsonArray(value)) {
+        return value.map(tidy);
+    }
+    if (!isJsonObject(value)) {
+        return value;
+    }
+    return safeIntegerBounds(flattenAllOf(foldOpenObject(R.map(value, tidy))));
+}
+/** The annotations {@link restoreAnnotations} puts back. */
+const RESTORED_ANNOTATIONS = ["title", "description", "format"];
+/**
+ * Puts back each property's title, description, and format where Effect
+ * dropped them. Effect reads annotations off the schema's last check, and a
+ * check with no JSON Schema form, such as the time-zone check on
+ * `IanaTimeZone`, takes them down with it. Walks struct properties only, which
+ * is where these annotations sit.
+ */
+function restoreAnnotations(ast, value) {
+    const properties = isJsonObject(value) ? value.properties : undefined;
+    if (!isJsonObject(value) ||
+        !isJsonObject(properties) ||
+        !SchemaAST.isObjects(ast)) {
+        return value;
+    }
+    return R.set(value, "properties", R.map(properties, (property, key) => {
+        const signature = Arr.findFirst(ast.propertySignatures, (candidate) => candidate.name === key);
+        if (Option.isNone(signature)) {
+            return property;
+        }
+        const restored = restoreAnnotations(signature.value.type, property);
+        const annotations = SchemaAST.resolve(signature.value.type) ?? {};
+        if (!isJsonObject(restored)) {
+            return restored;
+        }
+        return Arr.reduce(RESTORED_ANNOTATIONS, restored, (node, key) => {
+            const annotation = annotations[key];
+            return P.isString(annotation) && !(key in node)
+                ? R.set(node, key, annotation)
+                : node;
+        });
+    }));
+}
+/**
+ * The JSON Schema a client reads for `schema`. An object closes to the keys it
+ * declares, since the decoder drops the rest before a handler sees them.
+ */
+function jsonSchemaOf(schema) {
+    const document = Schema.toJsonSchemaDocument(schema, {
+        includeAnnotationKey: isLucaAnnotation,
+        onExcessProperty: "error",
+    });
+    const root = {
+        ...document.schema,
+        ...fieldsWhen(!R.isEmptyRecord(document.definitions), {
+            $defs: document.definitions,
+        }),
+    };
+    // SAFETY: Effect builds the document from JSON values only, though its type
+    // leaves keyword values open. Both passes map an object node to an object
+    // node.
+    return restoreAnnotations(schema.ast, tidy(root));
+}
+/**
+ * Runs `build` on the first call and returns that result from then on. The
+ * catalog defines hundreds of schemas at import, and a client lists the tools
+ * it needs, so each JSON Schema is built when the SDK first asks for it.
+ */
+function lazily(build) {
+    let built;
+    return () => {
+        built ??= { value: build() };
+        return built.value;
+    };
+}
+/**
+ * The shape a schema reaches the MCP SDK in: Effect validates the arguments,
+ * and the JSON Schema clients see is generated from the same Effect schema,
+ * with Luca's `x-luca-*` markers kept.
+ *
+ * `Schema.toStandardJSONSchemaV1` would do the same, but it takes no options
+ * and drops the markers, so the JSON half is built here instead.
+ */
+export function toStandardSchema(schema, parseOptions) {
+    const standard = Schema.toStandardSchemaV1(schema, { parseOptions })["~standard"];
+    return {
+        schema,
+        "~standard": {
+            ...standard,
+            jsonSchema: {
+                input: lazily(() => jsonSchemaOf(schema)),
+                output: lazily(() => jsonSchemaOf(Schema.toType(schema))),
+            },
+        },
+    };
+}
+/** A tool's result object as a {@link toStandardSchema}. */
+export function toolSchema(fields) {
+    return toStandardSchema(Schema.Struct(fields));
+}
+/**
+ * A tool's argument object as a {@link toStandardSchema}. A key the schema does
+ * not declare, at any depth, fails the call with an issue naming it: the JSON
+ * Schema a client reads already closes every object, and dropping a misspelt
+ * field in silence would run the call without it.
+ */
+export function toolInputSchema(fields) {
+    return toStandardSchema(Schema.Struct(fields), { onExcessProperty: "error" });
+}

package/dist/task-tools/analytics.js

@@ -1,59 +1,15 @@
-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 Option from "effect/Option";
+import * as R from "effect/Record";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
 import { formatError } from "../errors.js";
-import { WORKSPACE_INPUT_FIELDS } from "../operations.js";
+import { NonEmptyString, WORKSPACE_INPUT_FIELDS } from "../fields.js";
 import { optionalField } from "../optional-field.js";
-import { listingIds, numberInput, taskRequest, } from "./runtime.js";
+import { failureAsField, listingIds, numberInput, operationResult, resultOrError, sectionResult, taskTool, } from "./runtime.js";
 const DEFAULT_CAMPAIGN_LIMIT = 5;
 const CAMPAIGN_BROADCAST_LIMIT = 10;
-const getAnalytics = {
-    name: "luca_analytics_rollup",
-    title: "Get campaign and broadcast analytics",
-    description: "Roll up performance across the coach's campaigns (per-campaign analytics for up to 5 recent campaigns) and recent broadcasts. Example: call with {} for the default rollup, or { campaignLimit: 3 }.",
-    inputSchema: {
-        ...WORKSPACE_INPUT_FIELDS,
-        campaignLimit: z
-            .number()
-            .int()
-            .min(1)
-            .max(5)
-            .optional()
-            .describe("How many recent campaigns to include (default 5)."),
-    },
-    readOnly: true,
-    untrustedContent: false,
-    composes: ["campaigns.list", "campaigns.analytics", "broadcasts.list"],
-    run: (api, operationById, input) => Effect.gen(function* () {
-        const campaignLimit = numberInput(input.campaignLimit, DEFAULT_CAMPAIGN_LIMIT);
-        const campaignPage = yield* api.request(taskRequest(operationById("campaigns.list"), input, {
-            query: { limit: campaignLimit },
-        }));
-        // broadcasts.list doesn't depend on the per-campaign analytics loop, so
-        // it runs alongside it instead of after it. Effect.all defaults to
-        // concurrency 1 (sequential) — without `concurrency: "unbounded"` here
-        // the broadcasts call would still wait on the whole loop below.
-        const [perCampaign, broadcasts] = yield* Effect.all([
-            Effect.forEach(listingIds(campaignPage, campaignLimit), (id) => api
-                .request(taskRequest(operationById("campaigns.analytics"), input, {
-                pathParams: { id },
-            }))
-                .pipe(Effect.catchAll((error) => 
-            // Structured formatter (see draft-belt note above): preserves
-            // the failing campaign's status/requestId instead of "[object …]".
-            Effect.succeed({ analyticsError: formatError(error) })), Effect.map((analytics) => [
-                id,
-                analytics,
-            ])), 
-            // Effect.forEach also defaults to concurrency 1. campaignLimit caps
-            // this at 5 independent per-campaign lookups, so unbounded is fine.
-            { concurrency: "unbounded" }),
-            api.request(taskRequest(operationById("broadcasts.list"), input, {
-                query: { limit: CAMPAIGN_BROADCAST_LIMIT },
-            })),
-        ], { concurrency: "unbounded" });
-        return { campaigns: Record.fromEntries(perCampaign), broadcasts };
-    }),
-};
 const ANALYTICS_PERIOD_VALUES = [
     "this_week",
     "this_month",
@@ -61,11 +17,12 @@ const ANALYTICS_PERIOD_VALUES = [
     "last_month",
     "last_30_days",
 ];
+const decodeAnalyticsPeriod = Schema.decodeUnknownOption(Schema.Literals(ANALYTICS_PERIOD_VALUES));
 /**
  * Every analytics read either task tool below can compose. magic_monday and
- * deep_dive each build their own list from these entries rather than
- * hand-listing operation ids a second time, so the two tools cannot drift
- * apart on order, ids, or which reads are period-scoped.
+ * deep_dive each build their own list from these entries, so the two tools
+ * cannot drift apart on order or on which reads are period-scoped. A read whose
+ * id is missing from the tool's `composes` does not compile.
  */
 const ANALYTICS_READS = {
     funnel: { key: "funnel", id: "analytics.funnel", periodScoped: true },
@@ -110,57 +67,159 @@ const DEEP_DIVE_READS = [
     ANALYTICS_READS.ghostedLeads,
     ANALYTICS_READS.trustScore,
 ];
+/** A section the report left out because its read failed. */
+const FailedSection = Schema.Struct({
+    section: Schema.String,
+    error: Schema.String,
+});
+/**
+ * Each read's response under the key it lands at, present when the read
+ * succeeded, plus `failedSections` naming each read that did not.
+ */
+function analyticsOutput(reads) {
+    return Schema.Struct({
+        ...R.fromEntries(reads.map((read) => [
+            read.key,
+            Schema.optionalKey(operationResult(read.id)),
+        ])),
+        failedSections: Schema.optionalKey(Schema.Array(FailedSection).annotate({
+            description: "Sections missing from this report because their read failed. The report is partial whenever this is present.",
+        })),
+    });
+}
+/**
+ * Fold the outcome of each section into one report. A failed section is left
+ * out and named in `failedSections`, so the numbers that did load still reach
+ * the coach. The call fails only when every section does, since an empty
+ * report answers nothing.
+ */
+function collectSections(outcomes) {
+    const sections = outcomes.flatMap(({ key, result }) => Result.isSuccess(result) ? [[key, result.success]] : []);
+    const failures = outcomes.flatMap(({ key, result }) => Result.isFailure(result) ? [{ key, error: result.failure }] : []);
+    return Arr.match(failures, {
+        onEmpty: () => Effect.succeed(R.fromEntries(sections)),
+        onNonEmpty: (failed) => Arr.isReadonlyArrayEmpty(sections)
+            ? Effect.fail(Arr.headNonEmpty(failed).error)
+            : Effect.succeed({
+                ...R.fromEntries(sections),
+                failedSections: failed.map(({ key, error }) => ({
+                    section: key,
+                    error: formatError(error),
+                })),
+            }),
+    });
+}
 /**
  * Run a list of analytics reads in parallel and return them keyed by `key`.
  * Effect.all defaults to concurrency 1 (sequential); these reads don't depend
  * on each other, so serializing them would only add latency, not correctness.
+ *
+ * One failed read leaves its section out and names it in `failedSections`; see
+ * {@link collectSections}. A refused token or missing scope fails the whole
+ * report instead, see {@link sectionResult}.
  */
-function analyticsFanOut(api, operationById, input, period, reads) {
-    return Effect.all(reads.map((read) => api
-        .request(taskRequest(operationById(read.id), input, {
+function analyticsFanOut(call, period, reads) {
+    return Effect.forEach(reads, (read) => sectionResult(call(read.id, {
         ...optionalField("query", read.periodScoped ? { period } : undefined),
-    }))
-        .pipe(Effect.map((value) => [read.key, value]))), { concurrency: "unbounded" }).pipe(Effect.map((entries) => Record.fromEntries(entries)));
+    })).pipe(Effect.map((result) => ({ key: read.key, result }))), { concurrency: "unbounded" }).pipe(Effect.flatMap(collectSections));
 }
-const magicMonday = {
+/**
+ * Analytics for each campaign on a listing page, keyed by campaign id. One
+ * campaign's failure is reported in its slot rather than dropping the rollup
+ * for every other campaign, unless it is an authorization failure, see
+ * {@link failureAsField}.
+ */
+function campaignAnalytics(call, page, limit) {
+    return Effect.forEach(listingIds(page, limit), (id) => failureAsField("analyticsError", call("campaigns.analytics", { pathParams: { id } })).pipe(Effect.map((analytics) => [id, analytics])), 
+    // Effect.forEach also defaults to concurrency 1. The limit caps this at 5
+    // independent per-campaign lookups, so unbounded is fine.
+    { concurrency: "unbounded" }).pipe(Effect.map(R.fromEntries));
+}
+const getAnalytics = taskTool({
+    name: "luca_analytics_rollup",
+    title: "Get campaign and broadcast analytics",
+    description: "Roll up performance across the coach's campaigns (per-campaign analytics for up to 5 recent campaigns) and recent broadcasts. When one half fails to load, the other still comes back and failedSections names the one that is missing. Example: call with {} for the default rollup, or { campaignLimit: 3 }.",
+    inputSchema: {
+        ...WORKSPACE_INPUT_FIELDS,
+        campaignLimit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 5 })).annotate({
+            description: "How many recent campaigns to include (default 5).",
+        })),
+    },
+    outputSchema: Schema.Struct({
+        campaigns: Schema.optionalKey(Schema.Record(Schema.String, resultOrError("campaigns.analytics", "analyticsError"))),
+        broadcasts: Schema.optionalKey(operationResult("broadcasts.list")),
+        failedSections: Schema.optionalKey(Schema.Array(FailedSection).annotate({
+            description: "Sections missing from this rollup because their read failed (campaigns, broadcasts). The rollup is partial whenever this is present.",
+        })),
+    }),
+    composes: ["campaigns.list", "campaigns.analytics", "broadcasts.list"],
+    run: (call, input) => Effect.gen(function* () {
+        const campaignLimit = numberInput(input.campaignLimit, DEFAULT_CAMPAIGN_LIMIT);
+        const campaignPage = yield* sectionResult(call("campaigns.list", { query: { limit: campaignLimit } }));
+        // broadcasts.list doesn't depend on the per-campaign analytics loop, so
+        // it runs alongside it instead of after it. Effect.all defaults to
+        // concurrency 1 (sequential), so without `concurrency: "unbounded"` here
+        // the broadcasts call would still wait on the whole loop below.
+        const [campaigns, broadcasts] = yield* Effect.all([
+            Result.match(campaignPage, {
+                onFailure: (error) => Effect.succeed(Result.fail(error)),
+                onSuccess: (page) => sectionResult(campaignAnalytics(call, page, campaignLimit)),
+            }),
+            sectionResult(call("broadcasts.list", {
+                query: { limit: CAMPAIGN_BROADCAST_LIMIT },
+            })),
+        ], { concurrency: "unbounded" });
+        return yield* collectSections([
+            { key: "campaigns", result: campaigns },
+            { key: "broadcasts", result: broadcasts },
+        ]);
+    }),
+});
+const magicMonday = taskTool({
     name: "luca_analytics_magic_monday",
     title: "Get the Magic Monday report",
     description: "Return the coach's weekly business intelligence report: pipeline funnel, revenue and ROI, response-speed impact, a point-in-time revenue forecast, and call intelligence (show/close rates), all for the current week. Composes five analytics reads into a single call. Example: call with {} on Monday morning for the week's report.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
     },
-    readOnly: true,
-    untrustedContent: false,
-    composes: MAGIC_MONDAY_READS.map((read) => read.id),
-    run: (api, operationById, input) => analyticsFanOut(api, operationById, input, "this_week", MAGIC_MONDAY_READS),
-};
-const analyticsDeepDive = {
+    outputSchema: analyticsOutput(MAGIC_MONDAY_READS),
+    composes: [
+        "analytics.funnel",
+        "analytics.revenue",
+        "analytics.speedImpact",
+        "analytics.forecast",
+        "analytics.callIntelligence",
+    ],
+    run: (call) => analyticsFanOut(call, "this_week", MAGIC_MONDAY_READS),
+});
+const analyticsDeepDive = taskTool({
     name: "luca_analytics_deep_dive",
     title: "Run a deep-dive analytics investigation",
     description: 'Answer a specific business question by composing all seven analytics reads in one call: pipeline funnel, revenue and ROI, response-speed impact, a point-in-time revenue forecast, call intelligence (show/close rates), ghosted-lead recovery, and coach trust/auto-send status. Broader than luca_analytics_magic_monday (which is the fixed weekly report); use this when the coach asks a specific question that needs cross-referencing several of these numbers together. Example: call with {question: "why did close rate drop this month?", period: "this_month"}.',
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
-        question: z
-            .string()
-            .min(1)
-            .max(500)
-            .describe("The coach's specific question driving this investigation, e.g. 'why did close rate drop this month?'. Not sent to any API — captured so the caller's reasoning stays anchored to what the coach actually asked."),
-        period: z
-            .enum(ANALYTICS_PERIOD_VALUES)
-            .optional()
-            .describe("Period for the period-scoped reads (funnel, revenue, speedImpact, callIntelligence, ghostedLeads, trustScore). Forecast ignores this — it is always point-in-time. Defaults to this_month."),
+        question: Schema.optionalKey(NonEmptyString.check(Schema.isMaxLength(500)).annotate({
+            description: "Optional. The coach's question behind this investigation, e.g. 'why did close rate drop this month?'. Not sent to any API; it only records what the coach asked.",
+        })),
+        period: Schema.optionalKey(Schema.Literals(ANALYTICS_PERIOD_VALUES).annotate({
+            description: "Period for the period-scoped reads (funnel, revenue, speedImpact, callIntelligence, ghostedLeads, trustScore). Forecast ignores this — it is always point-in-time. Defaults to this_month.",
+        })),
     },
-    readOnly: true,
-    untrustedContent: false,
-    composes: DEEP_DIVE_READS.map((read) => read.id),
-    run: (api, operationById, input) => {
-        const parsedPeriod = z
-            .enum(ANALYTICS_PERIOD_VALUES)
-            .safeParse(input.period);
-        const period = parsedPeriod.success ? parsedPeriod.data : "this_month";
-        return analyticsFanOut(api, operationById, input, period, DEEP_DIVE_READS);
+    outputSchema: analyticsOutput(DEEP_DIVE_READS),
+    composes: [
+        "analytics.funnel",
+        "analytics.revenue",
+        "analytics.speedImpact",
+        "analytics.forecast",
+        "analytics.callIntelligence",
+        "analytics.ghostedLeads",
+        "analytics.trustScore",
+    ],
+    run: (call, input) => {
+        const period = Option.getOrElse(decodeAnalyticsPeriod(input.period), () => "this_month");
+        return analyticsFanOut(call, period, DEEP_DIVE_READS);
     },
-};
+});
 export const analyticsTaskTools = [
     getAnalytics,
     magicMonday,