@setluca/mcp 0.2.0 → 0.3.0

package/dist/task-tools/leads.js

@@ -1,120 +1,92 @@
-import * as z from "zod/v4";
-import { confirmInput, WORKSPACE_INPUT_FIELDS } from "../operations.js";
+import * as Schema from "effect/Schema";
+import { MessagingChannel, NonEmptyString, WORKSPACE_INPUT_FIELDS, } from "../fields.js";
 import { optionalField } from "../optional-field.js";
-import { numberInput, stringInput, taskRequest, textBody, } from "./runtime.js";
-const findLeads = {
+import { idempotencyKeyInput, numberInput, operationResult, stringInput, taskTool, textBody, } from "./runtime.js";
+const findLeads = taskTool({
     name: "luca_find_leads",
     title: "Find leads",
     description: "Search the coach's leads by free-text query and optional channel. Use this to locate a lead before drafting, booking, or flagging. Example: call with { query: \"maria instagram\" } to find Maria's Instagram lead.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
-        query: z
-            .string()
-            .min(1)
-            .describe("Free-text search: name, handle, or keyword."),
-        channel: z
-            .string()
-            .optional()
-            .describe("Optional channel filter (telegram, instagram, messenger, whatsapp)."),
-        limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(50)
-            .optional()
-            .describe("Max results (default 10)."),
+        query: NonEmptyString.annotate({
+            description: "Free-text search: name, handle, or keyword.",
+        }),
+        channel: Schema.optionalKey(MessagingChannel.annotate({ description: "Optional channel filter." })),
+        limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 50 })).annotate({
+            description: "Max results (default 10).",
+        })),
     },
-    readOnly: true,
-    untrustedContent: true,
+    outputSchema: operationResult("leads.list"),
     composes: ["leads.list"],
-    run: (api, operationById, input) => api.request(taskRequest(operationById("leads.list"), input, {
+    run: (call, input) => call("leads.list", {
         query: {
             q: stringInput(input.query),
             ...optionalField("channel", input.channel),
             limit: numberInput(input.limit, 10),
         },
-    })),
-};
-const flagForHuman = {
+    }),
+});
+const flagForHuman = taskTool({
     name: "luca_flag_for_human",
     title: "Flag a lead for human attention",
     description: 'Add a note to a lead, tagged [needs-human], that the coach sees on the lead\'s timeline. This is an ordinary note with a prefix — it does not route, alert, or reprioritize anything. Use when a conversation needs judgment an agent should not exercise (payment claims, distress, legal), and tell the coach directly if it is urgent. Example: call with { leadId, reason: "lead mentioned a refund dispute" }.',
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
-        leadId: z.string().min(1).describe("The lead to flag."),
-        reason: z
-            .string()
-            .min(1)
-            .describe("Why a human should look — shown to the coach verbatim."),
-        idempotencyKey: z
-            .string()
-            .optional()
-            .describe("Reuse the same key when retrying this exact flag."),
+        leadId: NonEmptyString.annotate({ description: "The lead to flag." }),
+        reason: NonEmptyString.annotate({
+            description: "Why a human should look — shown to the coach verbatim.",
+        }),
+        ...idempotencyKeyInput("Reuse the same key when retrying this exact flag."),
     },
-    readOnly: false,
-    untrustedContent: false,
+    outputSchema: operationResult("leads.notes.add"),
     composes: ["leads.notes.add"],
-    run: (api, operationById, input) => api.request(taskRequest(operationById("leads.notes.add"), input, {
+    run: (call, input) => call("leads.notes.add", {
         pathParams: { id: stringInput(input.leadId) },
         body: { body: `[needs-human] ${stringInput(input.reason)}` },
-    })),
-};
-const draftReply = {
+    }),
+});
+const draftReply = taskTool({
     name: "luca_draft_reply",
     title: "Draft a reply for a lead",
     description: 'Draft a voice-matched reply for a lead on demand and queue it for review — the middle step of the reply loop (triage → draft → approve). Optional guidance steers tone or content. Nothing is sent; approve it with luca_approve_and_send. Example: call with { leadId, guidance: "keep it short and warm" }.',
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
-        leadId: z.string().min(1).describe("The lead to draft a reply for."),
-        guidance: z
-            .string()
-            .min(1)
-            .max(500)
-            .optional()
-            .describe("Optional steer for tone or content of the draft."),
-        idempotencyKey: z
-            .string()
-            .optional()
-            .describe("Reuse the same key when retrying this exact draft."),
+        leadId: NonEmptyString.annotate({
+            description: "The lead to draft a reply for.",
+        }),
+        guidance: Schema.optionalKey(NonEmptyString.check(Schema.isMaxLength(500)).annotate({
+            description: "Optional steer for tone or content of the draft.",
+        })),
+        ...idempotencyKeyInput("Reuse the same key when retrying this exact draft."),
     },
-    readOnly: false,
-    untrustedContent: false,
+    outputSchema: operationResult("leads.draft"),
     composes: ["leads.draft"],
-    run: (api, operationById, input) => api.request(taskRequest(operationById("leads.draft"), input, {
+    run: (call, input) => call("leads.draft", {
         pathParams: { id: stringInput(input.leadId) },
         body: textBody("guidance", input.guidance),
-    })),
-};
-const approveAndSend = {
+    }),
+});
+const approveAndSend = taskTool({
     name: "luca_approve_and_send",
     title: "Approve a drafted reply and send it",
     description: "Approve a pending review-queue draft and dispatch it through the lead's channel. THIS SENDS A REAL MESSAGE TO A REAL PERSON — only call it after a human has reviewed and intends to send. Pass confirm: true to proceed. Optional finalBody replaces the draft text before sending. Example: { reviewQueueId, confirm: true }.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
-        reviewQueueId: z
-            .string()
-            .min(1)
-            .describe("The review-queue item to approve."),
-        finalBody: z
-            .string()
-            .min(1)
-            .optional()
-            .describe("Optional edited body to send instead of the drafted text."),
-        ...confirmInput,
-        idempotencyKey: z
-            .string()
-            .optional()
-            .describe("Reuse the same key when retrying this exact approval."),
+        reviewQueueId: NonEmptyString.annotate({
+            description: "The review-queue item to approve.",
+        }),
+        finalBody: Schema.optionalKey(NonEmptyString.annotate({
+            description: "Optional edited body to send instead of the drafted text.",
+        })),
+        ...idempotencyKeyInput("Reuse the same key when retrying this exact approval."),
     },
-    readOnly: false,
-    untrustedContent: false,
-    confirmRequired: true,
+    outputSchema: operationResult("reviewQueue.approve"),
     composes: ["reviewQueue.approve"],
-    run: (api, operationById, input) => api.request(taskRequest(operationById("reviewQueue.approve"), input, {
+    run: (call, input) => call("reviewQueue.approve", {
         pathParams: { id: stringInput(input.reviewQueueId) },
         body: textBody("finalBody", input.finalBody),
-    })),
-};
+    }),
+});
 export const leadTaskTools = [
     findLeads,
     flagForHuman,

package/dist/task-tools/runtime.js

@@ -1,7 +1,38 @@
-import { Effect, Option, Schema } from "effect";
-import * as z from "zod/v4";
-import { formatError } from "../errors.js";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as P from "effect/Predicate";
+import * as R from "effect/Record";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Str from "effect/String";
+import { formatError, isAuthorizationFailure, } from "../errors.js";
+import { NonEmptyString } from "../fields.js";
+import { operationById, } from "../operations.js";
 import { optionalField } from "../optional-field.js";
+/**
+ * Declares a task tool, inferring the id union from `composes` so `run` can
+ * only call what the tool declares.
+ */
+export function taskTool(tool) {
+    return tool;
+}
+/**
+ * The `result` an operation tool declares, for a task tool that hands that
+ * response back unchanged or nests it in its own output.
+ */
+export function operationResult(id) {
+    return operationById(id).outputSchema.result ?? Schema.Unknown;
+}
+/**
+ * A field that holds an operation's response, or the error a tool recorded in
+ * its place under `errorKey`.
+ */
+export function resultOrError(id, errorKey) {
+    return Schema.Union([
+        operationResult(id),
+        Schema.Struct({ [errorKey]: Schema.String }),
+    ]);
+}
 function workspaceOverride(input) {
     const override = {
         ...optionalField("workspaceId", input.workspaceId),
@@ -9,7 +40,7 @@ function workspaceOverride(input) {
     };
     // An override naming neither field is no override at all, and sending an
     // empty one would pin the request to nothing.
-    if (Object.keys(override).length === 0) {
+    if (R.isEmptyReadonlyRecord(override)) {
         return;
     }
     return override;
@@ -18,7 +49,7 @@ function workspaceOverride(input) {
  * Assemble the request a task tool sends: the resolved operation plus its
  * path/query/body, with the workspace override and idempotency key folded in
  * the same way for every tool. This is the task-tool analogue of operations.ts
- * `commonInput` — one seam owns "how a task request is built", so a tool body
+ * `commonInput`. One seam owns "how a task request is built", so a tool body
  * reads as the fields it maps, not the plumbing. Pass `body: undefined` to omit
  * the body entirely (an absent optional field, never `{ body: undefined }`).
  */
@@ -35,8 +66,8 @@ export function taskRequest(operation, input, parts = {}) {
 /**
  * The only part of a listing page a composing tool reads for itself: the ids of
  * the items it then fans out over. Decoding that alone leaves the raw page
- * intact for the caller — it is returned exactly as the API sent it — while the
- * ids the tool acts on are validated rather than asserted.
+ * intact for the caller, returned exactly as the API sent it, while the ids the
+ * tool acts on are validated rather than asserted.
  */
 const ListingIds = Schema.Struct({
     items: Schema.optional(Schema.Array(Schema.Struct({ id: Schema.optional(Schema.String) }))),
@@ -44,7 +75,7 @@ const ListingIds = Schema.Struct({
 const decodeListingIds = Schema.decodeUnknownOption(ListingIds);
 /**
  * Ids of the first `limit` items on a listing page. A page whose fields we
- * cannot read, or whose items carry no id, contributes nothing — the tool still
+ * cannot read, or whose items carry no id, contributes nothing. The tool still
  * returns the page itself rather than failing over a fan-out it cannot do.
  */
 export function listingIds(page, limit) {
@@ -66,27 +97,56 @@ export function listingIds(page, limit) {
 }
 /**
  * A request body carrying a single text field, or no body at all when the input
- * is absent or blank — sending an empty string would mean something different to
+ * is absent or blank. Sending an empty string would mean something different to
  * the API than leaving the field off.
  */
 export function textBody(key, value) {
-    return Option.fromNullable(value).pipe(Option.map(String), Option.filter((text) => text.length > 0), Option.map((text) => ({ [key]: text })), Option.getOrUndefined);
+    return Option.fromNullishOr(value).pipe(Option.map(String), Option.filter((text) => Str.isNonEmpty(text)), Option.map((text) => ({ [key]: text })), Option.getOrUndefined);
 }
 /** Reads a numeric tool input, falling back when it is absent or not a number. */
 export function numberInput(value, fallback) {
-    const parsed = z.number().safeParse(value);
-    return parsed.success ? parsed.data : fallback;
+    return P.isNumber(value) ? value : fallback;
 }
-/** Required string arguments have already passed the registered tool schema. */
+/**
+ * A required string argument. The registered tool schema has already checked
+ * it, so a non-string here is a bug in this package and dies as a defect.
+ */
 export function stringInput(value) {
-    return z.string().parse(value);
+    return decodeString(value);
+}
+const decodeString = Schema.decodeUnknownSync(Schema.String);
+/**
+ * The `idempotencyKey` input of a task tool that writes. An empty key is
+ * refused by the schema rather than read as "no key", because a keyed call
+ * skips checks a fresh call runs.
+ */
+export function idempotencyKeyInput(description) {
+    return {
+        idempotencyKey: Schema.optionalKey(NonEmptyString.annotate({ description })),
+    };
+}
+/**
+ * A failure a partial-result tool can report in place of one section, or a
+ * failure that has to end the tool call. A refused token or a missing scope
+ * fails every other request in the tool too, and only a failed tool result
+ * carries the challenge that sends the client back through sign-in.
+ */
+export const isPartialFailure = (error) => !isAuthorizationFailure(error);
+/**
+ * One section of a partial-result tool, as a `Result` the tool folds into its
+ * report. An authorization failure stays in the error channel, see
+ * {@link isPartialFailure}.
+ */
+export function sectionResult(effect) {
+    return effect.pipe(Effect.map((value) => Result.succeed(value)), Effect.catchIf(isPartialFailure, (error) => Effect.succeed(Result.fail(error))));
 }
 /**
- * A write whose failure must not cancel the writes around it. A tool that files
- * two independent reports has to keep the second one reachable when the first
- * fails, so the failure comes back as a field the agent can read instead of a
- * dead tool call that invites a retry of the half that already landed.
+ * A request whose failure comes back as a field under `errorKey` instead of
+ * ending the tool call. A tool that files two independent writes keeps the
+ * second one reachable when the first fails, so the agent reads what failed
+ * instead of retrying the half that already landed. An authorization failure
+ * still ends the call, see {@link isPartialFailure}.
  */
-export function independentWrite(errorKey, effect) {
-    return Effect.catchAll(effect, (error) => Effect.succeed({ [errorKey]: formatError(error) }));
+export function failureAsField(errorKey, effect) {
+    return Effect.catchIf(effect, isPartialFailure, (error) => Effect.succeed({ [errorKey]: formatError(error) }));
 }

package/dist/task-tools.js

@@ -1,7 +1,7 @@
 // The task-tool registry: composed, intent-level entry points layered over the
 // generated 1:1 operation tools. It is deliberately NOT `LUCA_OPERATIONS`,
 // whose entries the OpenAPI drift checker matches one-to-one against REST
-// routes — a task tool has no route of its own. Each tool hand-writes its
+// routes, and a task tool has no route of its own. Each tool hand-writes its
 // input fields and composes existing operations through `LucaApi.request`, and
 // they are split one file per domain under `task-tools/`. The shape they all
 // share, and the request plumbing they all use, lives in `task-tools/runtime.ts`.

package/dist/token-verification.js

@@ -0,0 +1,42 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { TokenVerificationUnavailable } from "./errors.js";
+/**
+ * The longest a verification call may run. It sits in front of every remote
+ * request, so a slow API answers 503 within seconds instead of holding the
+ * client for the full API timeout. A shorter configured timeout still wins.
+ */
+const VERIFY_TIMEOUT_MS = 5000;
+export function unavailable(message) {
+    return (cause) => new TokenVerificationUnavailable({ message, cause });
+}
+/** SHA-256 of a secret as hex, so a limiter or cache never stores it. */
+export const sha256Hex = (value) => Effect.tryPromise(() => crypto.subtle.digest("SHA-256", new TextEncoder().encode(value))).pipe(Effect.map((digest) => Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")));
+/**
+ * One bounded call to the Luca API that carries a token, with `read` turning
+ * the response into the verdict. Timeout but no retry: this is on the auth
+ * path of every request, and the client retries a 503 on its own schedule. A
+ * redirect is an error, because it would carry the token to a host we never
+ * named.
+ */
+export function callApi(settings, fetchImpl, request, read) {
+    const controller = new AbortController();
+    const timeoutMs = Math.min(settings.requestTimeoutMs ?? VERIFY_TIMEOUT_MS, VERIFY_TIMEOUT_MS);
+    return Effect.tryPromise({
+        try: () => fetchImpl(`${settings.apiBaseUrl}${request.path}`, {
+            ...request.init,
+            redirect: "error",
+            signal: controller.signal,
+        }),
+        catch: unavailable("Could not reach token verification"),
+    }).pipe(Effect.flatMap(read), Effect.timeoutOrElse({
+        duration: Duration.millis(timeoutMs),
+        orElse: () => Effect.fail(new TokenVerificationUnavailable({
+            message: `Token verification did not answer within ${timeoutMs}ms`,
+        })),
+    }), 
+    // The signal belongs to the whole exchange, body read included, so abort
+    // on every exit: a timed-out or unread response cannot outlive the auth
+    // decision it was made for.
+    Effect.ensuring(Effect.sync(() => controller.abort())));
+}

package/dist/tool-cache.js

@@ -1,3 +1,4 @@
+import * as Arr from "effect/Array";
 function cache() {
     let entries = new WeakMap();
     return {
@@ -33,7 +34,7 @@ export function buildCache() {
  * changed underneath it, which is exactly what a mutation run does.
  */
 export function clearToolBuildCache() {
-    for (const reset of resets) {
+    Arr.forEach(resets, (reset) => {
         reset();
-    }
+    });
 }