@setluca/mcp 0.1.1 → 0.2.0

package/README.md

@@ -21,7 +21,7 @@ requires an explicit confirmation.
 Copy the block below and paste it to your assistant — it will walk you through
 the rest:
 
-````text
+```text
 Set up the Luca MCP server for me.
 
 Luca (setluca.com) is an AI setter for coaches; its MCP server exposes the
@@ -40,6 +40,9 @@ fits this client, or ask me which I prefer:
    Luca -> Settings -> Developer API keys). Never print the key back to me.
    Optional env var: LUCA_WORKSPACE_SLUG — only if my key can reach more
    than one workspace.
+   Optional env var: LUCA_TOOLSET=tasks — a smaller task-level surface
+   (triage, find, flag, book, analytics); recommended for coach-facing
+   assistants that don't need raw API coverage.
 
    Claude Code CLI:
      claude mcp add luca --env LUCA_API_KEY=<my-key> -- npx -y @setluca/mcp
@@ -58,7 +61,7 @@ After configuring, verify the connection: call the luca_capabilities_get tool
 and summarize what my key can do. If a call returns 401 the key is wrong or
 revoked; 403 scope_required means the key is missing a scope; 400
 workspace_required means you should set LUCA_WORKSPACE_SLUG.
-````
+```
 
 Prefer to do it yourself? The two manual paths are below.
 
@@ -95,35 +98,37 @@ screen (read-only up to full access). Manage or revoke connections anytime in
 }
 ```
 
-3. Ask your assistant *"What's in my Luca review queue?"* to confirm it works.
+3. Ask your assistant _"What's in my Luca review queue?"_ to confirm it works.
 
-Requires Node.js 18+ (for `npx`). Without a key the server still starts and
+Requires Node.js 20+ (for `npx`). Without a key the server still starts and
 lists tools; the first tool call returns a clear
 `Set LUCA_API_KEY to a Luca developer API key.` error instead of failing
 silently.
 
 ## First things to try
 
-- *"What needs my attention in Luca this morning?"*
-- *"Show me the review queue and recommend what to approve."*
-- *"Pull up everything about this lead before my call."*
-- *"Why did Luca mark this lead as hot?"*
-- *"How is my broadcast performing?"*
-- *"Draft a reply to this lead — keep it short and warm."*
+- _"What needs my attention in Luca this morning?"_
+- _"Show me the review queue and recommend what to approve."_
+- _"Pull up everything about this lead before my call."_
+- _"Why did Luca mark this lead as hot?"_
+- _"How is my broadcast performing?"_
+- _"Draft a reply to this lead — keep it short and warm."_
 
 Your client's prompt picker also gets one-click workflows:
 `luca-morning-report`, `luca-triage-queue`, `luca-draft-reply` (accepts
-optional tone/content guidance), and `luca-api-planner`.
+optional tone/content guidance), `luca-close-the-call-loop`, and
+`luca-api-planner`.
 
 ## Configuration
 
-| Variable | Required | What it does |
-|---|---|---|
-| `LUCA_API_KEY` | yes (local) | Your developer API key from Luca settings. |
-| `LUCA_API_BASE_URL` | no | Luca API origin. Defaults to `https://api.setluca.com`. |
-| `LUCA_AUTH_HEADER` | no | `x-api-key` (default) or `authorization`. |
-| `LUCA_WORKSPACE_ID` | no | Default workspace (uuid) when your key can access several. |
-| `LUCA_WORKSPACE_SLUG` | no | Same, by slug — handy for agencies. |
+| Variable              | Required    | What it does                                                                                         |
+| --------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
+| `LUCA_API_KEY`        | yes (local) | Your developer API key from Luca settings.                                                           |
+| `LUCA_API_BASE_URL`   | no          | Luca API origin. Defaults to `https://api.setluca.com`.                                              |
+| `LUCA_AUTH_HEADER`    | no          | `x-api-key` (default) or `authorization`.                                                            |
+| `LUCA_WORKSPACE_ID`   | no          | Default workspace (uuid) when your key can access several.                                           |
+| `LUCA_WORKSPACE_SLUG` | no          | Same, by slug — handy for agencies.                                                                  |
+| `LUCA_TOOLSET`        | no          | `full` (default) or `tasks` — trim the surface to the fourteen task tools plus capability discovery. |
 
 Every tool also accepts `workspaceId` / `workspaceSlug` arguments to override
 the default for a single call. If your key can reach multiple workspaces and
@@ -131,20 +136,45 @@ none is selected, calls return `workspace_required` — set one of the above.
 
 ## What's inside
 
-**67 tools** covering the Luca surface an API key can safely reach:
-
-| Group | What it covers |
-|---|---|
-| Leads | Profiles, timelines, notes, consent, imports, "explain this lead" |
-| Conversations | Message history and context (send requires confirmation) |
-| Review queue | Pending drafts, approve/edit signals, "explain this draft" |
-| Bookings | Create, reschedule, cancel |
-| Campaigns | Drafts, enrollment, analytics, comment automation |
-| Broadcasts | Draft → approve → launch flow, with confirmation gates |
-| Webhooks | Subscriptions, deliveries, replays, signature guide |
-| Integrations | CRM connections, mappings, sync runs |
-| Voice | Read-only voice-fingerprint summary |
-| Capabilities | Discover what this key can do |
+Tools cover the Luca surface an API key can safely reach. Most are generated
+1:1 from the public API; the rest are composed task tools. `docs/tools.md` is
+generated from the code and carries the current count.
+
+| Group         | What it covers                                                    |
+| ------------- | ----------------------------------------------------------------- |
+| Leads         | Profiles, timelines, notes, consent, imports, "explain this lead" |
+| Conversations | Message history and context (send requires confirmation)          |
+| Review queue  | Pending drafts, approve, reject, restore, media retry             |
+| Bookings      | Create, reschedule, cancel                                        |
+| Campaigns     | Drafts, enrollment, analytics, comment automation                 |
+| Broadcasts    | Draft → approve → launch flow, with confirmation gates            |
+| Webhooks      | Subscriptions, deliveries, events, replays, signature guide       |
+| Integrations  | CRM connections, mappings, sync runs                              |
+| Call events   | Post-call feedback, summaries, CRM push, outcome corrections      |
+| Analytics     | Funnel, revenue, forecast, call intelligence, ghosted leads       |
+| Voice         | Read-only voice-fingerprint summary                               |
+| Capabilities  | Discover what this key can do                                     |
+| Task tools    | Intent-level workflows over the operation tools — see below       |
+
+**Task tools** — start here; each composes several operation tools behind one
+intent-level call:
+
+| Tool                          | What it does                                                        |
+| ----------------------------- | ------------------------------------------------------------------- |
+| `luca_triage_inbox`           | Prioritized review queue with per-item explanations                 |
+| `luca_morning_report`         | Structured last-24h queue digest (no model call)                    |
+| `luca_find_leads`             | Search leads by free text and channel                               |
+| `luca_draft_reply`            | Draft a voice-matched reply and queue it for review                 |
+| `luca_approve_and_send`       | Approve a draft and send it (needs `confirm: true`)                 |
+| `luca_flag_for_human`         | Flag a lead for a human to review                                   |
+| `luca_book_call`              | Book a call with a lead                                             |
+| `luca_rescue_silent_leads`    | Enroll silent leads into the rescue cadence (needs `confirm: true`) |
+| `luca_pause_cadence`          | Pause a lead's running rescue cadence                               |
+| `luca_analytics_rollup`       | Roll up campaign and broadcast performance                          |
+| `luca_analytics_magic_monday` | The weekly report: funnel, revenue, speed, forecast, call intel     |
+| `luca_analytics_deep_dive`    | All seven analytics reads, for a specific question                  |
+| `luca_post_call_queue`        | Calls still needing a report, and calls needing a revenue outcome   |
+| `luca_close_call_loop`        | File a call's attendance and what it was worth, in one call         |
 
 **Resources** — attach context without a tool round-trip: a lead
 (`luca://lead/{leadId}`), a thread (`luca://thread/{conversationId}`), today's
@@ -167,20 +197,56 @@ review queue (`luca://queue/today`), the voice profile
   to continue.
 - **Scopes are enforced.** A key only reaches the tool groups its scopes
   allow; everything else returns a clear `403`.
+- **Redacted keys see less, and say so.** A key's data-sensitivity tier
+  decides whether it gets verbatim lead content or summaries only. A
+  `redacted`-tier key still lists the queue, reads a conversation, or explains
+  a lead, but content-bearing fields come back blanked. Tools whose output can
+  be redacted mark those fields in their `outputSchema` with
+  `x-luca-redacted-fields`, so a client can tell "blanked for your tier" from
+  "no data" — treat a blanked field as unknown, not as an empty/negative
+  signal.
 - **The boundary is the public API.** This server cannot touch Luca's
   database, internal routes, webhook secrets, or browser sessions — it is
   exactly as powerful as the API key you give it.
 
+## Privacy Policy
+
+Full policy: **https://setluca.com/privacy**. What it means for this server
+specifically:
+
+- **What it collects.** Nothing of its own. The server holds no database and
+  writes no store. It forwards a tool call to the Luca API under your key and
+  returns the response. The hosted server at `mcp.setluca.com` is stateless:
+  each request carries its own credential and nothing survives it.
+- **How it is used and stored.** Your workspace data stays in Luca, governed by
+  the policy above. A tool call emits one structured log line carrying the tool
+  name, the toolset, the outcome, and how long it took. Tool arguments, lead
+  message text, and drafted replies never reach a log line.
+- **What is shared.** This server sends your data to one place: the Luca API.
+  Luca's own sub-processors are named in the policy above. The other party in
+  the exchange is your MCP client, and what it does with a tool result is
+  governed by that client's policy — read it before pointing a hosted client at
+  a live workspace.
+- **How long it is kept.** Nothing is retained here. Retention of the
+  underlying records is Luca's, and the policy above states it: conversations
+  and the voice profile live as long as the account does, and deletion on
+  request removes them.
+- **Your key is the boundary.** This server is exactly as powerful as the key
+  you give it. Revoke a key in Luca settings and every client holding it stops
+  working immediately.
+- **Contact.** hello@setluca.com.
+
 ## Troubleshooting
 
-| Symptom | Fix |
-|---|---|
-| `Set LUCA_API_KEY to a Luca developer API key.` | Add the env var to your client config (see Connect). |
-| `401 unauthorized` | The key is wrong or revoked — mint a new one in Luca settings. |
-| `403 scope_required` | The key lacks a scope for that tool — re-mint with the scopes you need. |
-| `400 workspace_required` | The key reaches several workspaces — set `LUCA_WORKSPACE_SLUG` or pass `workspaceSlug`. |
-| Confirmation error on send/launch | Expected: re-call the tool with `confirm: true` once a human approved. |
-| Tools list but every call fails | Check the key first (`401`), then scopes (`403`) — the error body names the missing scope. |
+| Symptom                                         | Fix                                                                                                                                                                                     |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Set LUCA_API_KEY to a Luca developer API key.` | Add the env var to your client config (see Connect).                                                                                                                                    |
+| `401 unauthorized`                              | The key is wrong or revoked — mint a new one in Luca settings.                                                                                                                          |
+| `403 scope_required`                            | The key lacks a scope for that tool — re-mint with the scopes you need.                                                                                                                 |
+| `403 needs_scope`                               | The key's granted capability tier is too low for that tool (for example a read-only tier calling a queue-operating tool like launch or send) — re-mint or reconnect with a higher tier. |
+| `400 workspace_required`                        | The key reaches several workspaces — set `LUCA_WORKSPACE_SLUG` or pass `workspaceSlug`.                                                                                                 |
+| Confirmation error on send/launch               | Expected: re-call the tool with `confirm: true` once a human approved.                                                                                                                  |
+| Tools list but every call fails                 | Check the key first (`401`), then scopes (`403`) — the error body names the missing scope.                                                                                              |
 
 ## For contributors
 
@@ -191,7 +257,8 @@ The deep technical material lives in [docs/](./docs):
 [Configuration](./docs/configuration.md) ·
 [Security boundary](./docs/security.md) ·
 [Tool reference](./docs/tools.md) ·
-[Release](./docs/release.md)
+[Release](./docs/release.md) ·
+[Connector directory](./docs/connector-directory.md)
 
 From the repo root: `bun --filter @setluca/mcp verify` runs the full local
 gate (docs + schema drift, typecheck, tests, build, stdio smoke test).
@@ -199,6 +266,7 @@ gate (docs + schema drift, typecheck, tests, build, stdio smoke test).
 ## Links
 
 - Luca: https://setluca.com
+- Privacy policy: https://setluca.com/privacy
 - API docs: https://api.setluca.com/docs
 - OpenAPI: https://api.setluca.com/openapi.json
-- MCP registry listing: `io.github.leonardomso/luca-mcp`
+- MCP registry listing: `io.github.setluca/luca-mcp`

package/dist/annotations.js

@@ -0,0 +1,45 @@
+/**
+ * MCP tool annotations, so a client can reason about a tool before calling it
+ * (auto-approve reads, flag destructive writes). Hints only — never a security
+ * boundary; the Luca API still enforces scopes and safety server-side.
+ */
+export function toolAnnotations(source) {
+    return {
+        title: source.title,
+        readOnlyHint: source.readOnly,
+        // MCP defines the non-destructive half as additive-only, so anything that
+        // overwrites or removes existing state reads true here: a delete, a PATCH,
+        // a PUT replace, or a write whose real-world effect we gate on a confirm.
+        // A create is a write and still reads false, because nothing it touches
+        // existed before the call.
+        destructiveHint: !source.readOnly && (source.confirmRequired || source.mutatesExisting),
+        // Reads are naturally idempotent; flagged writes carry an idempotency-key
+        // contract that makes a repeat with the same key a no-op.
+        idempotentHint: source.readOnly || source.idempotencyRequired,
+        // Every tool reaches the external Luca API, outside this server's control.
+        openWorldHint: true,
+    };
+}
+/**
+ * The HTTP methods that change state a caller already had. POST is absent on
+ * purpose: it creates, and a create has nothing prior to overwrite.
+ */
+const MUTATING_METHODS = new Set([
+    "DELETE",
+    "PATCH",
+    "PUT",
+]);
+/** True when this route's method changes or removes an existing record. */
+export function mutatesExisting(method) {
+    return MUTATING_METHODS.has(method);
+}
+/** The annotation facts an operation carries, read off its method and flags. */
+export function operationAnnotations(operation) {
+    return toolAnnotations({
+        title: operation.title,
+        readOnly: operation.method === "GET",
+        mutatesExisting: mutatesExisting(operation.method),
+        confirmRequired: operation.confirmRequired,
+        idempotencyRequired: operation.idempotencyRequired,
+    });
+}

package/dist/completions.js

@@ -0,0 +1,90 @@
+import { Effect, Option, Schema } from "effect";
+import { LucaApi } from "./http.js";
+/**
+ * Argument completion for the two ids a coach types by hand. MCP completes
+ * prompt arguments and resource-template variables; there is no tool-argument
+ * completion in the protocol, so a tool's enum fields stay documented in their
+ * own JSON Schema and only these two names get a live source.
+ *
+ * Ids only. A completion list is rendered by the client, so offering a lead's
+ * name or a message would put lead-authored text somewhere the untrusted
+ * framing every tool result carries does not reach.
+ *
+ * Each name maps to the list operation its ids are read from. The field those
+ * ids arrive in is not named here — it is the operation's own page shape, so a
+ * route that renames its array cannot leave this file behind.
+ */
+const COMPLETION_SOURCES = {
+    leadId: "leads.list",
+    conversationId: "conversations.list",
+};
+/** One page is enough to complete from, and it is the API's own cap. */
+const COMPLETION_PAGE_SIZE = 100;
+/**
+ * Reads a list page down to the ids in one array field, ignoring every other
+ * field on the page and every other field on a record. A page that arrives in
+ * any other shape decodes to nothing, which the caller offers as no
+ * suggestions.
+ */
+function idsDecoder(itemsKey) {
+    const decode = Schema.decodeUnknownOption(Schema.Struct({
+        [itemsKey]: Schema.Array(Schema.Struct({ id: Schema.String })),
+    }));
+    return (page) => Option.match(decode(page), {
+        onNone: () => [],
+        onSome: (decoded) => decoded[itemsKey]?.map((record) => record.id) ?? [],
+    });
+}
+/**
+ * The completion callbacks for one server, closed over the layer that serves
+ * the reads.
+ *
+ * A failed read answers with no suggestions rather than an error. A completion
+ * fires on a keystroke, so a transient 500 would otherwise surface as a failure
+ * for something the next character retries anyway.
+ */
+export function completionCallbacks(operationById, lucaLayer) {
+    function callbackFor(operationId) {
+        return (value) => Effect.runPromise(Effect.gen(function* () {
+            const operation = operationById(operationId);
+            // A source that does not paginate carries no array of records, so
+            // there is nothing to read ids out of.
+            const itemsKey = operation.pageShape?.itemsKey;
+            if (itemsKey === undefined) {
+                return [];
+            }
+            const idsOn = idsDecoder(itemsKey);
+            const api = yield* LucaApi;
+            const page = yield* api.request({
+                operation,
+                ...operation.buildRequest({
+                    query: { limit: COMPLETION_PAGE_SIZE },
+                }),
+            });
+            const typed = value ?? "";
+            return idsOn(page).filter((id) => id.startsWith(typed));
+        }).pipe(Effect.provide(lucaLayer), Effect.catchAllCause(() => Effect.succeed([]))));
+    }
+    return {
+        leadId: callbackFor(COMPLETION_SOURCES.leadId),
+        conversationId: callbackFor(COMPLETION_SOURCES.conversationId),
+    };
+}
+/** Whether `name` is a template variable or prompt argument we can complete. */
+export function isCompletionVariable(name) {
+    return Object.hasOwn(COMPLETION_SOURCES, name);
+}
+/**
+ * The `complete` map for one URI template: every `{variable}` in it that has a
+ * source. Returns undefined when none do, so a template with nothing to
+ * complete registers without the key at all.
+ */
+export function templateCompletions(template, callbacks) {
+    const complete = {};
+    for (const [, variable] of template.matchAll(/\{([^}]+)\}/g)) {
+        if (variable && isCompletionVariable(variable)) {
+            complete[variable] = callbacks[variable];
+        }
+    }
+    return Object.keys(complete).length > 0 ? complete : undefined;
+}

package/dist/config.js

@@ -1,47 +1,73 @@
-import { Context, Effect, Layer } from "effect";
+import { Context, Effect, Layer, Match, Option } from "effect";
+import * as z from "zod/v4";
 import { LucaConfigError } from "./errors.js";
+import { optionalField } from "./optional-field.js";
 const TRAILING_SLASHES = /\/+$/;
+/** How long one HTTP attempt may run before it is cancelled and retried. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 export const LucaConfig = Context.GenericTag("@luca/mcp/LucaConfig");
 function nonEmpty(value) {
-    const trimmed = value?.trim();
-    return trimmed ? trimmed : undefined;
+    // An all-whitespace variable is the same as an unset one, so it collapses to
+    // undefined and lets every caller's `??` fallback take over.
+    return value?.trim() || undefined;
 }
 function normalizeBaseUrl(value) {
     const raw = nonEmpty(value) ?? "https://api.setluca.com";
     return raw.replace(TRAILING_SLASHES, "");
 }
-function parseAuthHeader(value) {
-    const normalized = nonEmpty(value)?.toLowerCase();
-    if (!normalized || normalized === "x-api-key") {
-        return "x-api-key";
-    }
-    if (normalized === "authorization" || normalized === "bearer") {
-        return "authorization";
-    }
-    throw new LucaConfigError({
-        message: "LUCA_AUTH_HEADER must be x-api-key or authorization",
-    });
+/**
+ * Every spelling of LUCA_AUTH_HEADER we accept, mapped to the header the client
+ * actually sends. "bearer" is here because it is what people write when they
+ * mean the Authorization header, and refusing it would be a papercut.
+ */
+const AUTH_HEADER_ALIASES = new Map([
+    ["x-api-key", "x-api-key"],
+    ["authorization", "authorization"],
+    ["bearer", "authorization"],
+]);
+/**
+ * The per-attempt timeout a variable asks for, absent when it is unset or is
+ * not a positive whole number of milliseconds. Absent means the caller's
+ * default applies, so a typo degrades to the default rather than to no timeout
+ * at all.
+ */
+export function parseTimeoutMs(value) {
+    const parsed = z.coerce
+        .number()
+        .int()
+        .positive()
+        .safeParse(nonEmpty(value) ?? undefined);
+    return parsed.success ? parsed.data : undefined;
 }
-export function loadConfig(env = process.env) {
-    const apiKey = nonEmpty(env.LUCA_API_KEY) ?? nonEmpty(env.LUCA_API_TOKEN);
-    if (!apiKey) {
+function parseAuthHeader(value) {
+    const alias = nonEmpty(value)?.toLowerCase() ?? "x-api-key";
+    return Match.value(AUTH_HEADER_ALIASES.get(alias)).pipe(Match.when(Match.undefined, () => {
         throw new LucaConfigError({
-            message: "Set LUCA_API_KEY to a Luca developer API key.",
+            message: "LUCA_AUTH_HEADER must be x-api-key or authorization",
         });
-    }
-    const workspaceId = nonEmpty(env.LUCA_WORKSPACE_ID);
-    const workspaceSlug = nonEmpty(env.LUCA_WORKSPACE_SLUG);
+    }), Match.orElse((header) => header));
+}
+export function loadConfig(env = process.env) {
+    const apiKey = Option.fromNullable(nonEmpty(env.LUCA_API_KEY) ?? nonEmpty(env.LUCA_API_TOKEN)).pipe(Option.getOrThrowWith(() => new LucaConfigError({
+        message: "Set LUCA_API_KEY to a Luca developer API key.",
+    })));
     return {
         apiBaseUrl: normalizeBaseUrl(env.LUCA_API_BASE_URL),
         apiKey,
         authHeader: parseAuthHeader(env.LUCA_AUTH_HEADER),
-        ...(workspaceId ? { workspaceId } : {}),
-        ...(workspaceSlug ? { workspaceSlug } : {}),
+        ...optionalField("workspaceId", nonEmpty(env.LUCA_WORKSPACE_ID)),
+        ...optionalField("workspaceSlug", nonEmpty(env.LUCA_WORKSPACE_SLUG)),
+        ...optionalField("requestTimeoutMs", parseTimeoutMs(env.LUCA_REQUEST_TIMEOUT_MS)),
     };
 }
-export const LucaConfigLive = Layer.effect(LucaConfig, Effect.try({
-    try: () => loadConfig(),
-    catch: (cause) => cause instanceof LucaConfigError
-        ? cause
-        : new LucaConfigError({ message: String(cause) }),
-}));
+/**
+ * Every way `loadConfig` can fail has to reach the caller as a `LucaConfigError`
+ * so the layer's error channel stays one type. A config error passes through
+ * untouched; anything else — a getter on the environment that throws, a future
+ * caller of this helper that raises something unexpected — is wrapped rather
+ * than escaping as an untyped defect.
+ */
+export function toConfigError(cause) {
+    return Match.value(cause).pipe(Match.when(Match.instanceOf(LucaConfigError), (error) => error), Match.orElse((other) => new LucaConfigError({ message: String(other) })));
+}
+export const LucaConfigLive = Layer.effect(LucaConfig, Effect.try({ try: () => loadConfig(), catch: toConfigError }));

package/dist/errors.js

@@ -1,4 +1,6 @@
-import { Data } from "effect";
+import { Data, Match, Option } from "effect";
+import * as z from "zod/v4";
+import { toJsonPayload } from "./serialization.js";
 export class LucaConfigError extends Data.TaggedError("LucaConfigError") {
 }
 export class LucaNetworkError extends Data.TaggedError("LucaNetworkError") {
@@ -7,19 +9,62 @@ export class LucaDecodeError extends Data.TaggedError("LucaDecodeError") {
 }
 export class LucaHttpError extends Data.TaggedError("LucaHttpError") {
 }
-export function formatError(error) {
-    if (error instanceof LucaConfigError) {
-        return error.message;
-    }
-    if (error instanceof LucaNetworkError) {
-        return error.message;
-    }
-    if (error instanceof LucaDecodeError) {
-        return `${error.message}: ${error.body.slice(0, 500)}`;
+/**
+ * One attempt ran past the request timeout and was cancelled. It is its own
+ * error rather than a network error because a caller can retry it safely under
+ * the same rules but cannot tell from a network failure whether the request
+ * reached the API.
+ */
+export class LucaTimeoutError extends Data.TaggedError("LucaTimeoutError") {
+}
+/**
+ * A tool was called with arguments that are not a JSON object. The MCP SDK
+ * validates against the tool's own input schema before the handler runs, so a
+ * real client cannot reach this. It exists so no code ahead of `runPromise` can
+ * throw where the error channel cannot see it.
+ */
+export class LucaToolInputError extends Data.TaggedError("LucaToolInputError") {
+}
+const DECODE_BODY_EXCERPT = 500;
+function formatDecodeError(error) {
+    return `${error.message}: ${error.body.slice(0, DECODE_BODY_EXCERPT)}`;
+}
+function formatHttpError(error) {
+    const request = Option.fromNullable(error.requestId).pipe(Option.match({
+        onNone: () => "",
+        onSome: (requestId) => ` requestId=${requestId}`,
+    }));
+    return `Luca API returned ${error.status} ${error.statusText}${request}: ${toJsonPayload(error.body)}`;
+}
+/**
+ * A value that carries no message of its own, rendered for a human. Anything
+ * that is not already a string comes back as JSON rather than "[object Object]".
+ */
+function formatJsonValue(error) {
+    const text = z.string().safeParse(error);
+    if (text.success) {
+        return text.data;
     }
-    if (error instanceof LucaHttpError) {
-        const request = error.requestId ? ` requestId=${error.requestId}` : "";
-        return `Luca API returned ${error.status} ${error.statusText}${request}: ${JSON.stringify(error.body)}`;
+    const scalar = z.union([z.number(), z.boolean()]).safeParse(error);
+    if (scalar.success) {
+        return String(scalar.data);
     }
-    return error instanceof Error ? error.message : String(error);
+    return toJsonPayload(error);
+}
+/** Any failure this server can hand a client, as one line of text. */
+export function formatError(error) {
+    return error instanceof Error ? formatThrown(error) : formatJsonValue(error);
+}
+/**
+ * A thrown value rendered for a human. The two structured errors get their own
+ * rendering; every other tagged error carries a `message`, and one branch
+ * covers all of them rather than a case per tag that would all say the same
+ * thing.
+ *
+ * The match is on the class, not on `_tag`. This takes any `Error`, including
+ * one thrown by a dependency that carries no tag at all, so there is no tagged
+ * union here for `Match.tag` to narrow.
+ */
+function formatThrown(error) {
+    return Match.value(error).pipe(Match.when(Match.instanceOf(LucaDecodeError), formatDecodeError), Match.when(Match.instanceOf(LucaHttpError), formatHttpError), Match.orElse((thrown) => thrown.message));
 }