@setluca/mcp 0.2.1 → 0.3.0

package/dist/config.js

@@ -1,73 +1,124 @@
-import { Context, Effect, Layer, Match, Option } from "effect";
-import * as z from "zod/v4";
+import * as Config from "effect/Config";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as HashMap from "effect/HashMap";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
 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");
+export const LucaConfig = Context.Service("@luca/mcp/LucaConfig");
 function nonEmpty(value) {
     // 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;
 }
+/** A variable's trimmed value, undefined when it is unset or blank. */
+function optionalVar(name) {
+    return Config.option(Config.String(name)).pipe(Config.map((value) => nonEmpty(Option.getOrUndefined(value))));
+}
+function trimmedSecret(secret) {
+    return Option.map(Option.fromNullishOr(nonEmpty(Redacted.value(secret))), (value) => Redacted.make(value));
+}
+/** A secret variable, trimmed and still redacted; None when unset or blank. */
+function optionalSecret(name) {
+    return Config.option(Config.Redacted(name)).pipe(Config.map(Option.flatMap(trimmedSecret)));
+}
+/** The URL with any trailing slashes removed, so paths can be appended to it. */
+export function withoutTrailingSlashes(url) {
+    return url.replace(TRAILING_SLASHES, "");
+}
 function normalizeBaseUrl(value) {
-    const raw = nonEmpty(value) ?? "https://api.setluca.com";
-    return raw.replace(TRAILING_SLASHES, "");
+    return withoutTrailingSlashes(value ?? "https://api.setluca.com");
 }
 /**
  * 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([
+const AUTH_HEADER_ALIASES = HashMap.fromIterable([
     ["x-api-key", "x-api-key"],
     ["authorization", "authorization"],
     ["bearer", "authorization"],
 ]);
+const decodeTimeoutMs = Schema.decodeUnknownOption(Schema.NumberFromString.check(Schema.isInt(), Schema.isGreaterThan(0)));
 /**
  * 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;
+function parseTimeoutMs(value) {
+    return Option.getOrUndefined(decodeTimeoutMs(value));
 }
 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: "LUCA_AUTH_HEADER must be x-api-key or authorization",
-        });
-    }), Match.orElse((header) => header));
+    const alias = value?.toLowerCase() ?? "x-api-key";
+    return Effect.fromNullishOr(Option.getOrUndefined(HashMap.get(AUTH_HEADER_ALIASES, alias))).pipe(Effect.mapError(() => new LucaConfigError({
+        message: "LUCA_AUTH_HEADER must be x-api-key or authorization",
+    })));
 }
-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.",
+/** LUCA_API_KEY, or the older LUCA_API_TOKEN when it is unset. */
+const ApiKeyConfig = Config.all([
+    optionalSecret("LUCA_API_KEY"),
+    optionalSecret("LUCA_API_TOKEN"),
+]).pipe(Config.map(([apiKey, legacy]) => Option.orElse(apiKey, () => legacy)));
+const RemoteSettingsConfig = Config.all({
+    apiBaseUrl: optionalVar("LUCA_API_BASE_URL"),
+    authHeader: optionalVar("LUCA_AUTH_HEADER"),
+    requestTimeoutMs: optionalVar("LUCA_REQUEST_TIMEOUT_MS"),
+});
+const WorkspaceConfig = Config.all({
+    workspaceId: optionalVar("LUCA_WORKSPACE_ID"),
+    workspaceSlug: optionalVar("LUCA_WORKSPACE_SLUG"),
+});
+/** Reads `config` from `env`, failing as {@link LucaConfigError}. */
+function readFrom(config, env) {
+    return config
+        .parse(ConfigProvider.fromEnvRecord(env))
+        .pipe(Effect.mapError((error) => new LucaConfigError({ message: error.message })));
+}
+function requireApiKey(env) {
+    return readFrom(ApiKeyConfig, env).pipe(Effect.flatMap(Option.match({
+        onNone: () => Effect.fail(new LucaConfigError({
+            message: "Set LUCA_API_KEY to a Luca developer API key.",
+        })),
+        onSome: Effect.succeed,
     })));
-    return {
-        apiBaseUrl: normalizeBaseUrl(env.LUCA_API_BASE_URL),
-        apiKey,
-        authHeader: parseAuthHeader(env.LUCA_AUTH_HEADER),
-        ...optionalField("workspaceId", nonEmpty(env.LUCA_WORKSPACE_ID)),
-        ...optionalField("workspaceSlug", nonEmpty(env.LUCA_WORKSPACE_SLUG)),
-        ...optionalField("requestTimeoutMs", parseTimeoutMs(env.LUCA_REQUEST_TIMEOUT_MS)),
-    };
 }
 /**
- * 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 is wrapped rather than escaping as an untyped
- * defect, whether that is a getter on the environment that throws or a future
- * caller of this helper raising something unexpected.
+ * Read the API settings that don't depend on the API key. The Worker reads
+ * them once and gives them to every token it resolves, so a remote call
+ * reaches the API exactly as a stdio call would. An unknown LUCA_AUTH_HEADER
+ * fails with {@link LucaConfigError}.
+ */
+export function loadRemoteSettings(env) {
+    return readFrom(RemoteSettingsConfig, env).pipe(Effect.flatMap((vars) => parseAuthHeader(vars.authHeader).pipe(Effect.map((authHeader) => ({
+        apiBaseUrl: normalizeBaseUrl(vars.apiBaseUrl),
+        authHeader,
+        ...optionalField("requestTimeoutMs", parseTimeoutMs(vars.requestTimeoutMs)),
+    })))));
+}
+/**
+ * Read the stdio server's configuration from the environment. A missing API
+ * key or an unknown LUCA_AUTH_HEADER fails with {@link LucaConfigError}; every
+ * other variable falls back to its default when unset or malformed.
  */
-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 function loadConfig(env = process.env) {
+    return Effect.all({
+        apiKey: requireApiKey(env),
+        settings: loadRemoteSettings(env),
+        workspace: readFrom(WorkspaceConfig, env),
+    }, { concurrency: 1 }).pipe(Effect.map(({ apiKey, settings, workspace }) => ({
+        ...settings,
+        apiKey,
+        ...optionalField("workspaceId", workspace.workspaceId),
+        ...optionalField("workspaceSlug", workspace.workspaceSlug),
+    })));
 }
-export const LucaConfigLive = Layer.effect(LucaConfig, Effect.try({ try: () => loadConfig(), catch: toConfigError }));
+/** The stdio server's configuration, read from `process.env` when built. */
+export const LucaConfigLive = Layer.effect(LucaConfig, Effect.suspend(() => loadConfig()));

package/dist/errors.js

@@ -1,13 +1,33 @@
-import { Data, Match, Option } from "effect";
-import * as z from "zod/v4";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import * as P from "effect/Predicate";
+import * as Schema from "effect/Schema";
 import { toJsonPayload } from "./serialization.js";
-export class LucaConfigError extends Data.TaggedError("LucaConfigError") {
+export class LucaConfigError extends Schema.TaggedError()("LucaConfigError", {
+    message: Schema.String,
+}) {
 }
-export class LucaNetworkError extends Data.TaggedError("LucaNetworkError") {
+export class LucaNetworkError extends Schema.TaggedError()("LucaNetworkError", {
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Unknown),
+}) {
 }
-export class LucaDecodeError extends Data.TaggedError("LucaDecodeError") {
+export class LucaDecodeError extends Schema.TaggedError()("LucaDecodeError", {
+    message: Schema.String,
+    body: Schema.String,
+}) {
 }
-export class LucaHttpError extends Data.TaggedError("LucaHttpError") {
+export class LucaHttpError extends Schema.TaggedError()("LucaHttpError", {
+    status: Schema.Number,
+    statusText: Schema.String,
+    body: Schema.Json,
+    requestId: Schema.optionalKey(Schema.String),
+    /**
+     * How long the server asked us to wait, from its `Retry-After` header. Absent
+     * when the header was missing or unreadable.
+     */
+    retryAfterMs: Schema.optionalKey(Schema.Number),
+}) {
 }
 /**
  * One attempt ran past the request timeout and was cancelled. It is its own
@@ -15,7 +35,9 @@ export class LucaHttpError extends Data.TaggedError("LucaHttpError") {
  * the same rules but cannot tell from a network failure whether the request
  * reached the API.
  */
-export class LucaTimeoutError extends Data.TaggedError("LucaTimeoutError") {
+export class LucaTimeoutError extends Schema.TaggedError()("LucaTimeoutError", {
+    message: Schema.String,
+}) {
 }
 /**
  * A tool was called with arguments that are not a JSON object. The MCP SDK
@@ -23,14 +45,73 @@ export class LucaTimeoutError extends Data.TaggedError("LucaTimeoutError") {
  * 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") {
+export class LucaToolInputError extends Schema.TaggedError()("LucaToolInputError", {
+    message: Schema.String,
+}) {
 }
-const DECODE_BODY_EXCERPT = 500;
+/**
+ * A gated tool was called without `confirm: true`. It stays out of
+ * {@link LucaError} because no request was sent: the tool pipeline turns it
+ * into its own result telling the agent which argument to add.
+ */
+export class LucaConfirmationRequired extends Schema.TaggedError()("LucaConfirmationRequired", {
+    toolName: Schema.String,
+}) {
+}
+/**
+ * The service that verifies bearer tokens could not give an answer: it was
+ * unreachable, timed out, or answered with a server error. This is not a
+ * verdict on the token. The transport replies 503 so a client retries instead
+ * of discarding a token that may be valid and starting a new sign-in.
+ */
+export class TokenVerificationUnavailable extends Schema.TaggedError()("TokenVerificationUnavailable", {
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Unknown),
+}) {
+}
+/** Whether the API answered that the thing asked for does not exist. */
+export function isNotFound(error) {
+    return P.isTagged(error, "LucaHttpError") && error.status === 404;
+}
+/**
+ * An API error body whose code means the key is valid but its scopes fall
+ * short: `scope_required` for a missing API scope, `needs_scope` for a
+ * capability tier below the route's.
+ */
+const ScopeErrorBody = Schema.Struct({
+    error: Schema.Struct({
+        code: Schema.Literals(["scope_required", "needs_scope"]),
+    }),
+});
+const isScopeErrorBody = Schema.is(ScopeErrorBody);
+/**
+ * Whether the API answered 403 because the caller's scopes fall short. Any
+ * other 403 covers plan limits and workspace access, which re-authorizing
+ * cannot fix.
+ */
+export function isScopeRefusal(error) {
+    return (P.isTagged(error, "LucaHttpError") &&
+        error.status === 403 &&
+        isScopeErrorBody(error.body));
+}
+/**
+ * Whether the API refused the caller's credentials rather than the request: a
+ * 401, or a scope refusal. Re-authorizing fixes these.
+ */
+export function isAuthorizationFailure(error) {
+    return ((P.isTagged(error, "LucaHttpError") && error.status === 401) ||
+        isScopeRefusal(error));
+}
+/**
+ * A body the API could not send as JSON, named by its length only. It is
+ * usually an edge or proxy page, text no Luca schema shaped, and quoting it
+ * would hand the agent instructions with nothing marking them as untrusted.
+ */
 function formatDecodeError(error) {
-    return `${error.message}: ${error.body.slice(0, DECODE_BODY_EXCERPT)}`;
+    return `${error.message} (${error.body.length} characters)`;
 }
 function formatHttpError(error) {
-    const request = Option.fromNullable(error.requestId).pipe(Option.match({
+    const request = Option.fromNullishOr(error.requestId).pipe(Option.match({
         onNone: () => "",
         onSome: (requestId) => ` requestId=${requestId}`,
     }));
@@ -44,11 +125,11 @@ function formatHttpError(error) {
  * their own: JSON renders each of them exactly as `String` would.
  */
 function formatJsonValue(error) {
-    const text = z.string().safeParse(error);
-    return text.success ? text.data : toJsonPayload(error);
+    return P.isString(error) ? error : toJsonPayload(error);
 }
 /** Any failure this server can hand a client, as one line of text. */
 export function formatError(error) {
+    // oxlint-disable-next-line effect/avoid-untagged-errors -- boundary narrows an unknown thrown value that carries no tag
     return error instanceof Error ? formatThrown(error) : formatJsonValue(error);
 }
 /**

package/dist/fields.js

@@ -0,0 +1,68 @@
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+/**
+ * Input field schemas that operation tools and task tools share. Both kinds of
+ * tool reach a client in one list, so a field means the same thing wherever it
+ * appears.
+ */
+/** A UUID in its canonical 8-4-4-4-12 hex form. */
+export const UUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** A leap year: divisible by 4, except centuries not divisible by 400. */
+const LEAP_YEAR = String.raw `(?:\d{2}(?:0[48]|[2468][048]|[13579][26])|(?:[02468][048]|[13579][26])00)`;
+/**
+ * A calendar date that exists: each month's own last day, and 29 February
+ * only in a leap year. `Date` cannot check this, because it rolls 31 February
+ * over to early March instead of refusing it.
+ */
+const CALENDAR_DATE = [
+    String.raw `\d{4}-(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])`,
+    String.raw `\d{4}-(?:0[469]|11)-(?:0[1-9]|[12]\d|30)`,
+    String.raw `\d{4}-02-(?:0[1-9]|1\d|2[0-8])`,
+    `${LEAP_YEAR}-02-29`,
+].join("|");
+const CLOCK_TIME = String.raw `(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?`;
+const UTC_OFFSET = String.raw `(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)`;
+/**
+ * An ISO-8601 instant with an explicit offset, such as `2026-07-14T15:00:00Z`,
+ * that names a real moment: no month 13, no 31 February, no hour 25. It is one
+ * pattern rather than a pattern plus a filter so the generated input schemas,
+ * which can only print patterns, enforce the same rule as the task tools.
+ */
+// fallow-ignore-next-line security-sink -- the pattern is built from three fixed string constants in this file, never from caller input
+export const ISO_DATE_TIME_PATTERN = new RegExp(`^(?:${CALENDAR_DATE})T${CLOCK_TIME}${UTC_OFFSET}$`);
+/** A string of at least one character. */
+export const NonEmptyString = Schema.String.check(Schema.isMinLength(1));
+const Uuid = Schema.String.check(Schema.isPattern(UUID_PATTERN)).annotate({
+    format: "uuid",
+});
+/** An instant matching {@link ISO_DATE_TIME_PATTERN}. */
+export const IsoDateTime = Schema.String.check(Schema.isPattern(ISO_DATE_TIME_PATTERN)).annotate({ format: "date-time" });
+/** An IANA time zone name the runtime knows, such as `America/New_York`. */
+export const IanaTimeZone = NonEmptyString.check(
+// oxlint-disable-next-line effect/require-filter-metadata -- an identifier turns this field into a `$ref` in every tool's input schema.
+Schema.makeFilter((value) => Option.isSome(DateTime.zoneMakeNamed(value)), { expected: "an IANA time zone name" }));
+/** The messaging channels a lead can arrive on. */
+export const MESSAGING_CHANNELS = [
+    "telegram",
+    "instagram",
+    "messenger",
+    "whatsapp",
+];
+export const MessagingChannel = Schema.Literals(MESSAGING_CHANNELS);
+export const WORKSPACE_INPUT_FIELDS = {
+    workspaceId: Schema.optionalKey(Uuid.annotate({ description: "Optional Luca workspace id override." })),
+    workspaceSlug: Schema.optionalKey(NonEmptyString.annotate({
+        description: "Optional Luca workspace slug override.",
+    })),
+};
+/**
+ * The confirmation gate's input field. One wording covers both kinds of tool
+ * because a client sees one tool list: the effects named here are the union of
+ * what either kind can do, not a guess at which one the reader is holding.
+ */
+export const confirmInput = {
+    confirm: Schema.optionalKey(Schema.Boolean.annotate({
+        description: "This tool has a real-world side effect: it messages real leads, books, moves, or cancels a call, changes a lead's consent, imports leads, writes to a connected calendar or CRM, sends workspace events to an outside URL, or re-triggers downstream automations. Pass confirm: true to proceed; the call is rejected without it.",
+    })),
+};

package/dist/fixed-window.js

@@ -0,0 +1,46 @@
+/** Table bound shared by the local limiters and the key-check cache. */
+const MAX_FIXED_WINDOW_KEYS = 10_000;
+export function createFixedWindowTable(windowMs) {
+    // oxlint-disable-next-line effect/avoid-native-object-helpers -- Evicts windows in insertion order; restarting a key moves it to the end.
+    const windows = new Map();
+    const live = (key, now) => {
+        const window = windows.get(key);
+        return window !== undefined && now - window.windowStartedAt < windowMs
+            ? window
+            : undefined;
+    };
+    /**
+     * Drops expired windows. A window is re-inserted when it restarts, so Map
+     * order is start order and the sweep stops at the first live one.
+     */
+    const sweepExpired = (now) => {
+        // oxlint-disable-next-line effect/imperative-loops -- stops at the first live entry, which a combinator cannot express
+        for (const [key, window] of windows) {
+            if (now - window.windowStartedAt < windowMs) {
+                return;
+            }
+            windows.delete(key);
+        }
+    };
+    return {
+        charge: (key, now) => {
+            const current = live(key, now);
+            if (current !== undefined) {
+                current.count += 1;
+                return current.count;
+            }
+            windows.delete(key);
+            if (windows.size >= MAX_FIXED_WINDOW_KEYS) {
+                sweepExpired(now);
+            }
+            if (windows.size >= MAX_FIXED_WINDOW_KEYS) {
+                return undefined;
+            }
+            windows.set(key, { windowStartedAt: now, count: 1 });
+            return 1;
+        },
+        isLive: (key, now) => live(key, now) !== undefined,
+        size: () => windows.size,
+        keys: () => [...windows.keys()],
+    };
+}