@setluca/mcp 0.2.0 → 0.3.0

package/dist/generated/route-catalog.js

@@ -141,6 +141,14 @@ export const ROUTE_CATALOG = {
         ],
         "idempotencyRequired": true
     },
+    "conversations.summary": {
+        "method": "GET",
+        "path": "/api/conversations/summary",
+        "scopes": [
+            "conversations:read"
+        ],
+        "idempotencyRequired": false
+    },
     "conversations.list": {
         "method": "GET",
         "path": "/api/conversations",
@@ -165,6 +173,14 @@ export const ROUTE_CATALOG = {
         ],
         "idempotencyRequired": false
     },
+    "conversations.profile_refresh": {
+        "method": "POST",
+        "path": "/api/conversations/{id}/profile-refresh",
+        "scopes": [
+            "conversations:write"
+        ],
+        "idempotencyRequired": true
+    },
     "conversations.send": {
         "method": "POST",
         "path": "/api/conversations/{id}/send",
@@ -173,6 +189,22 @@ export const ROUTE_CATALOG = {
         ],
         "idempotencyRequired": true
     },
+    "conversations.partial_send_retry": {
+        "method": "POST",
+        "path": "/api/conversations/{id}/messages/{messageId}/retry",
+        "scopes": [
+            "conversations:write"
+        ],
+        "idempotencyRequired": true
+    },
+    "reviewQueue.composer": {
+        "method": "GET",
+        "path": "/api/review-queue/{id}/composer",
+        "scopes": [
+            "review_queue:read"
+        ],
+        "idempotencyRequired": false
+    },
     "reviewQueue.list": {
         "method": "GET",
         "path": "/api/review-queue",
@@ -1117,6 +1149,38 @@ export const ROUTE_CATALOG = {
         ],
         "idempotencyRequired": false
     },
+    "channels.list": {
+        "method": "GET",
+        "path": "/api/channels",
+        "scopes": [
+            "channels:read"
+        ],
+        "idempotencyRequired": false
+    },
+    "channels.catalog": {
+        "method": "GET",
+        "path": "/api/channels/catalog",
+        "scopes": [
+            "channels:read"
+        ],
+        "idempotencyRequired": false
+    },
+    "channels.features": {
+        "method": "GET",
+        "path": "/api/channels/features",
+        "scopes": [
+            "channels:read"
+        ],
+        "idempotencyRequired": false
+    },
+    "channels.get": {
+        "method": "GET",
+        "path": "/api/channels/{id}",
+        "scopes": [
+            "channels:read"
+        ],
+        "idempotencyRequired": false
+    },
     "reports.morning": {
         "method": "GET",
         "path": "/api/reports/morning",
@@ -1197,6 +1261,22 @@ export const ROUTE_CATALOG = {
         ],
         "idempotencyRequired": false
     },
+    "learning.abTests.list": {
+        "method": "GET",
+        "path": "/api/ab-tests",
+        "scopes": [
+            "learning:read"
+        ],
+        "idempotencyRequired": false
+    },
+    "learning.abTests.get": {
+        "method": "GET",
+        "path": "/api/ab-tests/{id}",
+        "scopes": [
+            "learning:read"
+        ],
+        "idempotencyRequired": false
+    },
     "learning.proposals.list": {
         "method": "GET",
         "path": "/api/learning-proposals",

package/dist/http.js

@@ -1,56 +1,92 @@
-import { Context, Effect, Layer, Match, Option } from "effect";
-import * as z from "zod/v4";
+import * as Arr from "effect/Array";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+// oxlint-disable effect/avoid-native-fetch -- MCP remote API transport; its tests assert the native fetch request shape
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import * as R from "effect/Record";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import * as Str from "effect/String";
 import { DEFAULT_REQUEST_TIMEOUT_MS, LucaConfig } from "./config.js";
-import { LucaDecodeError, LucaHttpError, LucaNetworkError, } from "./errors.js";
+import { LucaDecodeError, LucaHttpError, LucaNetworkError, LucaToolInputError, } from "./errors.js";
 import { optionalField } from "./optional-field.js";
 import { resilient } from "./resilience.js";
-import { fromJson, toJsonPayload } from "./serialization.js";
+import { parseJson, toJsonPayload } from "./serialization.js";
 import { LUCA_MCP_USER_AGENT } from "./version.js";
-export const LucaApi = Context.GenericTag("@luca/mcp/LucaApi");
+export const LucaApi = Context.Service("@luca/mcp/LucaApi");
 function isPresent(value) {
     return value !== undefined && value !== null && value !== "";
 }
+const PATH_PARAM = /\{([^}]+)\}/g;
+/**
+ * The operation path with each `{param}` filled in and encoded. An absent or
+ * empty param fails rather than collapsing the route onto a different
+ * endpoint, such as the collection URL in place of one record.
+ */
 function encodePath(path, params) {
-    return path.replaceAll(/\{([^}]+)\}/g, (_, key) => Option.fromNullable(params?.[key]).pipe(Option.filter((value) => value.length > 0), Option.map(encodeURIComponent), Option.getOrThrowWith(() => new Error(`Missing path parameter: ${key}`))));
+    const valueOf = (key) => Option.fromNullishOr(params?.[key]).pipe(Option.filter(Str.isNonEmpty));
+    const missing = Arr.findFirst(Arr.map(Arr.fromIterable(path.matchAll(PATH_PARAM)), ([, key = ""]) => key), (key) => Option.isNone(valueOf(key)));
+    if (Option.isSome(missing)) {
+        return Effect.fail(new LucaToolInputError({
+            message: `Missing path parameter: ${missing.value}`,
+        }));
+    }
+    return Effect.succeed(path.replaceAll(PATH_PARAM, (_, key) => encodeURIComponent(Option.getOrElse(valueOf(key), () => ""))));
 }
 function appendQuery(url, query) {
-    for (const [key, value] of Object.entries(query ?? {})) {
+    // oxlint-disable-next-line effect/imperative-loops -- loop mutates surrounding state per item in a way a combinator cannot express without changing timing
+    for (const [key, value] of R.toEntries(query ?? {})) {
         // A scalar is a one-element list here, so array and single-value params take
         // the same path: append every value the caller actually set.
         const values = Array.isArray(value) ? value : [value];
-        for (const item of values.filter(isPresent)) {
+        Arr.forEach(values.filter(isPresent), (item) => {
             url.searchParams.append(key, String(item));
-        }
+        });
     }
 }
 function buildUrl(config, input) {
-    const path = encodePath(input.operation.path, input.pathParams);
-    const url = new URL(path, `${config.apiBaseUrl}/`);
-    appendQuery(url, input.query);
-    return url;
+    return encodePath(input.operation.path, input.pathParams).pipe(Effect.map((path) => {
+        const url = new URL(path, `${config.apiBaseUrl}/`);
+        appendQuery(url, input.query);
+        return url;
+    }));
 }
 /** The API key, under whichever header this config authenticates with. */
 function authFields(config) {
     return Match.value(config.authHeader).pipe(Match.when("authorization", () => ({
-        authorization: `Bearer ${config.apiKey}`,
-    })), Match.orElse(() => ({ "x-api-key": config.apiKey })));
+        authorization: `Bearer ${Redacted.value(config.apiKey)}`,
+    })), Match.orElse(() => ({ "x-api-key": Redacted.value(config.apiKey) })));
 }
 const RETRY_AFTER_MS_PER_SECOND = 1000;
+/** Delta-seconds: a whole, non-negative number of seconds. */
+const decodeRetryAfterSeconds = Schema.decodeUnknownOption(Schema.NumberFromString.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0)));
+const HTTP_DATE_START = /^[a-z]/i;
 /**
  * The wait a `Retry-After` header asks for, in milliseconds. The header comes
- * in two forms — delta-seconds and an HTTP date — and both are read here so the
+ * in two forms, delta-seconds and an HTTP date, and both are read here so the
  * retry rules never have to look at a header again. An unreadable value is the
  * same as no header: the client falls back to its own backoff.
  */
 function retryAfterMs(response, now) {
-    const header = response.headers.get("retry-after")?.trim();
+    // `Headers` has already trimmed the value, so a header of nothing but spaces
+    // arrives as the empty string and is treated as no header at all.
+    const header = response.headers.get("retry-after");
     if (!header) {
         return;
     }
-    const seconds = z.coerce.number().int().min(0).safeParse(header);
-    if (seconds.success) {
-        return seconds.data * RETRY_AFTER_MS_PER_SECOND;
+    const seconds = decodeRetryAfterSeconds(header);
+    if (Option.isSome(seconds)) {
+        return seconds.value * RETRY_AFTER_MS_PER_SECOND;
+    }
+    // Every HTTP date form opens with a day name. Without this check `Date.parse`
+    // would read a malformed delta such as "1.5" or "-1" as a calendar date.
+    if (!HTTP_DATE_START.test(header)) {
+        return;
     }
+    // oxlint-disable-next-line effect/use-clock-service -- parse stored timestamp
     const at = Date.parse(header);
     return Number.isNaN(at) ? undefined : Math.max(0, at - now);
 }
@@ -78,55 +114,83 @@ function buildRequestInit(config, input, requestIdempotencyKey) {
         ...optionalField("body", Option.getOrUndefined(body)),
     };
 }
+/**
+ * The most of a non-JSON error body a tool error carries. A gateway's HTML page
+ * says no more past this, and the whole page would crowd the agent's context.
+ */
+const MAX_RAW_ERROR_BODY_LENGTH = 500;
+/**
+ * The body of an error response: its JSON when it parses, else the raw text
+ * cut to {@link MAX_RAW_ERROR_BODY_LENGTH} characters. An empty body is null,
+ * as it is on success.
+ */
+function errorBody(text) {
+    return Option.liftPredicate(text, (raw) => Str.isNonEmpty(raw)).pipe(Option.match({
+        onNone: () => Effect.succeed(null),
+        onSome: (raw) => parseJson(raw).pipe(Effect.orElseSucceed(() => raw.slice(0, MAX_RAW_ERROR_BODY_LENGTH))),
+    }));
+}
+/**
+ * The URL a network error names: origin and path only. The query string can
+ * carry a search term such as a lead's name, which a tool error must not echo.
+ */
+const describeUrl = (url) => `${url.origin}${url.pathname}`;
 /** One trip to the API, with no retry and no timeout of its own. */
 function sendOnce(config, input, requestIdempotencyKey) {
     return Effect.gen(function* () {
-        const url = buildUrl(config, input);
+        const url = yield* buildUrl(config, input);
         const init = buildRequestInit(config, input, requestIdempotencyKey);
         const response = yield* Effect.tryPromise({
             try: (signal) => 
             // fallow-ignore-next-line security-sink -- the origin is the configured Luca api base url and the path comes from the generated operation manifest with its params encoded, so a tool argument can never move the destination host
             fetch(url, {
                 ...init,
+                // A redirect would carry the API key to a host we never named.
+                redirect: "error",
                 signal,
             }),
             catch: (cause) => new LucaNetworkError({
-                message: `Could not reach Luca API at ${url.toString()}`,
+                message: `Could not reach Luca API at ${describeUrl(url)}`,
                 cause,
             }),
         });
-        const text = yield* Effect.tryPromise({
+        const readText = Effect.tryPromise({
             try: () => response.text(),
             catch: (cause) => new LucaNetworkError({
                 message: "Could not read Luca API response body",
                 cause,
             }),
         });
-        // An empty body is not a decode failure — several endpoints answer with
+        if (!response.ok) {
+            // The status and `Retry-After` are read before the body is. A gateway
+            // answers 502, 503 and 504 with HTML and a rate limiter may answer 429
+            // with plain text; neither is a decode failure, and both must reach the
+            // retry rules with their status and wait intact. A body that cannot be
+            // read is treated as empty for the same reason.
+            const now = yield* Clock.currentTimeMillis;
+            const waitMs = retryAfterMs(response, now);
+            const text = yield* readText.pipe(Effect.orElseSucceed(() => ""));
+            return yield* Effect.fail(new LucaHttpError({
+                status: response.status,
+                statusText: response.statusText,
+                body: yield* errorBody(text),
+                ...optionalField("requestId", response.headers.get("x-request-id")),
+                ...optionalField("retryAfterMs", waitMs),
+            }));
+        }
+        const text = yield* readText;
+        // An empty body is not a decode failure. Several endpoints answer with
         // no content at all, and null is the JSON value that stands for it.
-        const json = yield* Option.liftPredicate(text, (raw) => raw.length > 0).pipe(Option.match({
+        return yield* Option.liftPredicate(text, (raw) => Str.isNonEmpty(raw)).pipe(Option.match({
             onNone: () => Effect.succeed(null),
-            onSome: (raw) => Effect.try({
-                try: () => fromJson(raw),
-                catch: () => new LucaDecodeError({
-                    message: "Luca API returned non-JSON content",
-                    body: raw,
-                }),
-            }),
-        }));
-        if (response.ok) {
-            return json;
-        }
-        return yield* Effect.fail(new LucaHttpError({
-            status: response.status,
-            statusText: response.statusText,
-            body: json,
-            ...optionalField("requestId", response.headers.get("x-request-id")),
-            ...optionalField("retryAfterMs", retryAfterMs(response, Date.now())),
+            onSome: (raw) => parseJson(raw).pipe(Effect.mapError(() => new LucaDecodeError({
+                message: "Luca API returned non-JSON content",
+                body: raw,
+            }))),
         }));
     });
 }
-export function makeLucaApi(config) {
+export function createLucaApi(config) {
     const timeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     return {
         // The key each attempt carries is minted by `resilient`, which also decides
@@ -136,5 +200,5 @@ export function makeLucaApi(config) {
 }
 export const LucaApiLive = Layer.effect(LucaApi, Effect.gen(function* () {
     const config = yield* LucaConfig;
-    return makeLucaApi(config);
+    return createLucaApi(config);
 }));

package/dist/index.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { setEventSink, stderrEventSink } from "./observability.js";
 import { createLucaServer, parseToolset } from "./server.js";
+// stdout carries the protocol, so event lines go to stderr.
+setEventSink(stderrEventSink);
 /**
  * `serveStdio` owns the era decision for the connection: the opening exchange
  * picks either the 2026-07-28 protocol or the 2025 `initialize` handshake, and
@@ -13,6 +16,6 @@ serveStdio(() => createLucaServer({ toolset: parseToolset(process.env.LUCA_TOOLS
     // are out-of-band errors: reporting them never changes what the client
     // receives, and the connection stays up.
     onerror: (error) => {
-        console.error("Luca MCP server error:", error);
+        stderrEventSink(`Luca MCP server error: ${error.stack ?? error.message}`);
     },
 });

package/dist/oauth-challenge.js

@@ -0,0 +1,74 @@
+import { isScopeRefusal, LucaHttpError } from "./errors.js";
+/**
+ * The `_meta` key a tool error uses to ask the client to re-authorize. ChatGPT
+ * reads it to show its account-linking UI when a call fails for lack of a
+ * valid token or a broad enough scope. The value is a list of RFC 6750
+ * `WWW-Authenticate` challenges, the same header a 401 from the transport
+ * carries.
+ */
+const WWW_AUTHENTICATE_META_KEY = "mcp/www_authenticate";
+/**
+ * The OAuth error a failed tool call maps to, or `undefined` when the failure
+ * has nothing to do with authorization. A 401 means the token is no longer
+ * accepted. A 403 counts only when the API says a scope is missing.
+ */
+function oauthErrorFor(error) {
+    if (error instanceof LucaHttpError && error.status === 401) {
+        return "invalid_token";
+    }
+    return isScopeRefusal(error) ? "insufficient_scope" : undefined;
+}
+const ERROR_DESCRIPTIONS = {
+    invalid_token: "The access token is invalid or expired",
+    insufficient_scope: "The connection's scopes do not cover this tool",
+};
+/**
+ * An RFC 6750 `Bearer` challenge, for the transport's `WWW-Authenticate`
+ * header and for a tool error's `_meta`. Both name the same realm, so a client
+ * sees one protected resource however the challenge reached it. A request that
+ * sent no token gets no `error`; one whose token was refused gets
+ * `invalid_token`, which tells the client to refresh or re-authorize rather
+ * than rediscover the server.
+ */
+export function bearerChallenge(params) {
+    const { error, resourceMetadataUrl, scope } = params;
+    const fields = [
+        'realm="luca-mcp"',
+        resourceMetadataUrl === undefined
+            ? undefined
+            : `resource_metadata="${resourceMetadataUrl}"`,
+        error === undefined ? undefined : `error="${error}"`,
+        error === undefined
+            ? undefined
+            : `error_description="${ERROR_DESCRIPTIONS[error]}"`,
+        scope === undefined ? undefined : `scope="${scope}"`,
+    ];
+    return `Bearer ${fields.filter((field) => field !== undefined).join(", ")}`;
+}
+/**
+ * The `_meta` for a tool error that re-authorizing could fix, or `undefined`
+ * for every other failure. An `insufficient_scope` challenge names the scope
+ * the tool needs, so the client can ask for it when the coach reconnects. An
+ * `invalid_token` challenge names none: the client must refresh or
+ * re-authorize, not ask for a different scope, the same rule the transport's
+ * 401 follows.
+ *
+ * It needs the resource-metadata URL, which only the remote Worker knows. A
+ * stdio server has no OAuth flow to send the client into, so it passes none
+ * and its errors carry no challenge.
+ */
+export function authChallengeMeta(error, scope, resourceMetadataUrl) {
+    const oauthError = oauthErrorFor(error);
+    if (oauthError === undefined || resourceMetadataUrl === undefined) {
+        return undefined;
+    }
+    return {
+        [WWW_AUTHENTICATE_META_KEY]: [
+            bearerChallenge({
+                resourceMetadataUrl,
+                error: oauthError,
+                scope: oauthError === "insufficient_scope" ? scope : undefined,
+            }),
+        ],
+    };
+}

package/dist/oauth-resolver.js

@@ -1,77 +1,74 @@
-import { Duration, Effect, Option } from "effect";
-import * as z from "zod/v4";
-import { DEFAULT_REQUEST_TIMEOUT_MS, parseTimeoutMs, } from "./config.js";
-const TRAILING_SLASHES = /\/+$/;
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import { TokenVerificationUnavailable } from "./errors.js";
+import { NonEmptyString } from "./fields.js";
+import { callApi, unavailable, } from "./token-verification.js";
 /**
- * Developer API keys are handled by apiKeyResolver and never leave this
- * process via the resolve endpoint. Refresh tokens (luca_ort_) are not
- * developer keys — they fall through to the resolver, which rejects them
- * server-side (fail closed, no client-side oracle).
+ * The body POST /oauth/resolve answers with for a token it accepted. The API
+ * also sends the grant's scopes; the Luca API enforces them on every call, so
+ * this resolver does not read them. An empty key is an API fault, not a key,
+ * so it fails as unavailable instead of reaching the API as a blank header.
  */
-const API_KEY_FIELDS = /^luca_(?!ort_)[a-f0-9]/i;
-const ResolvePayloadSchema = z.object({
-    apiKey: z.string().optional(),
-    scopes: z.array(z.string()).optional(),
+const ResolvePayload = Schema.Struct({
+    apiKey: Schema.optionalKey(NonEmptyString),
 });
+const decodeResolvePayload = Schema.decodeUnknownEffect(ResolvePayload);
 /**
- * The body of a resolve response, absent when the API refused the token. A
- * refusal is not read at all: its body carries nothing this resolver acts on.
+ * The body of a resolve response, absent when the API refused the token. Only
+ * a 401 is that verdict: any other non-2xx (a 404 from a misrouted base URL, a
+ * 403 from an edge rule, a 429, a 5xx) says nothing about the token, so it must
+ * not send the client back through sign-in. A refusal is not read at all. A
+ * 2xx with a body this resolver cannot read is an API fault, not a verdict, so
+ * it fails as unavailable.
  */
 function resolvePayload(response) {
-    return Option.match(Option.liftPredicate(response, (res) => res.ok), {
-        onNone: () => Effect.succeed(Option.none()),
-        onSome: (res) => Effect.tryPromise(() => res.json()).pipe(Effect.map((payload) => ResolvePayloadSchema.parse(payload)), Effect.map(Option.some)),
-    });
-}
-/** The identity a payload names, absent when it names no vended key. */
-function identityFromPayload(apiBaseUrl, authHeader, payload) {
-    return Option.map(Option.fromNullable(payload.apiKey), (apiKey) => ({
-        config: { apiBaseUrl, apiKey, authHeader },
-        scopes: payload.scopes ?? [],
-    }));
+    if (response.status === 401) {
+        return Effect.succeed(Option.none());
+    }
+    if (!response.ok) {
+        return Effect.fail(new TokenVerificationUnavailable({
+            message: `Token verification answered ${response.status}`,
+        }));
+    }
+    return Effect.tryPromise({
+        try: () => response.json(),
+        catch: unavailable("Token verification returned non-JSON content"),
+    }).pipe(Effect.flatMap((body) => decodeResolvePayload(body).pipe(Effect.mapError(unavailable("Token verification returned an unexpected body")))), Effect.map(Option.some));
 }
 /**
- * One authenticated call to POST /oauth/resolve, answered with the identity the
- * token maps to. A network failure, a refusal, and an unreadable body are all
- * the same answer — no identity — because the transport replies 401 to each of
- * them and telling them apart would hand a caller an oracle.
+ * One authenticated call to POST /oauth/resolve, answered with the config for
+ * the vended key the token maps to. A 401, or a payload with no key, is no
+ * config, which the transport turns into 401. A network failure, a timeout, or
+ * any other non-2xx is {@link TokenVerificationUnavailable}, which the transport
+ * turns into 503. Both fail closed. Telling them apart reveals nothing about
+ * the token, and it stops an outage from sending every connected client back
+ * through sign-in.
  */
-function requestIdentity(apiBaseUrl, authHeader, fetchImpl, token, timeoutMs) {
-    return Effect.tryPromise(() => fetchImpl(`${apiBaseUrl}/oauth/resolve`, {
-        method: "POST",
-        headers: { authorization: `Bearer ${token}` },
-    })).pipe(Effect.flatMap(resolvePayload), Effect.map((payload) => Option.flatMap(payload, (body) => identityFromPayload(apiBaseUrl, authHeader, body))), 
-    // Timeout but no retry. This call sits on the auth path of every request,
-    // has no idempotency to reason about, and already answers "no identity" for
-    // every failure — a plain `timeout` is enough because `orElseSucceed`
-    // discards the error shape anyway.
-    Effect.timeout(Duration.millis(timeoutMs)), Effect.orElseSucceed(() => Option.none()));
+function requestConfig(settings, fetchImpl, token) {
+    return callApi(settings, fetchImpl, {
+        path: "/oauth/resolve",
+        init: { method: "POST", headers: { authorization: `Bearer ${token}` } },
+    }, resolvePayload).pipe(Effect.map((payload) => Option.flatMapNullishOr(payload, (body) => body.apiKey).pipe(Option.map((apiKey) => ({
+        ...settings,
+        apiKey: Redacted.make(apiKey),
+    })))));
 }
+/** Three base64url segments: the form a JWT access token takes. */
+const JWT_ACCESS_TOKEN = /^[\w-]+\.[\w-]+\.[\w-]+$/;
 /**
  * Resolver for OAuth access tokens (docs/runbooks/mcp-oauth-authorization-server.md
  * §5.2): one authenticated call to the Luca API's POST /oauth/resolve, which
  * verifies the JWT and returns the hidden vended key for the token's own
- * grant. Fail closed: any error, non-200, or malformed body → null → 401.
+ * grant. The config it returns carries the same settings the stdio path reads,
+ * so the vended key reaches the API with the same base URL, auth header, and
+ * timeout. Developer keys never come here: the Worker sends them to
+ * `apiKeyResolver` by shape (see `looksLikeDeveloperKey`). A token that is not
+ * JWT-shaped is refused without calling the API.
  */
-export function oauthResolver(env, fetchImpl = fetch) {
-    const apiBaseUrl = (env.LUCA_API_BASE_URL ?? "https://api.setluca.com").replace(TRAILING_SLASHES, "");
-    const authHeader = env.LUCA_AUTH_HEADER ?? "x-api-key";
-    // Read through the same parser the API client uses, so the stdio and Worker
-    // paths cannot end up bounding their requests differently.
-    const timeoutMs = parseTimeoutMs(env.LUCA_REQUEST_TIMEOUT_MS) ?? DEFAULT_REQUEST_TIMEOUT_MS;
-    // A developer API key is another resolver's business, so it is refused here
-    // without a network call rather than sent to an endpoint that would reject it
-    // anyway.
-    return (token) => Option.match(Option.liftPredicate(token, (candidate) => !API_KEY_FIELDS.test(candidate)), {
-        onNone: () => Effect.succeed(Option.none()),
-        onSome: (candidate) => requestIdentity(apiBaseUrl, authHeader, fetchImpl, candidate, timeoutMs),
-    }).pipe(Effect.map(Option.getOrNull), Effect.runPromise);
-}
-/** Try resolvers in order; the first non-null identity wins. */
-export function chainResolvers(...resolvers) {
-    return (token) => Effect.reduce(resolvers, Option.none(), (identity, resolve) => Option.match(identity, {
-        // Once one resolver has answered, the rest are never called.
-        onSome: (present) => Effect.succeed(Option.some(present)),
-        onNone: () => Effect.promise(() => resolve(token)).pipe(Effect.map(Option.fromNullable)),
-    })).pipe(Effect.map(Option.getOrNull), Effect.runPromise);
+export function oauthResolver(settings, fetchImpl = fetch) {
+    return (token) => JWT_ACCESS_TOKEN.test(token)
+        ? requestConfig(settings, fetchImpl, token)
+        : Effect.succeedNone;
 }

package/dist/observability.js

@@ -1,6 +1,31 @@
+import * as P from "effect/Predicate";
+import * as R from "effect/Record";
+import { toJsonPayload } from "./serialization.js";
+/**
+ * Writes one line to stdout or stderr. Event lines are emitted from plain
+ * callbacks as well as from Effect programs, so this is the one place the
+ * package touches the console directly.
+ */
+function writeLine(stream, line) {
+    console[stream](line);
+}
+/** The Worker's sink: stdout is the platform log there. */
+export const stdoutEventSink = (line) => writeLine("log", line);
+/** The stdio sink: stdout carries the MCP protocol there, so lines go to stderr. */
+export const stderrEventSink = (line) => writeLine("error", line);
+let sink = stdoutEventSink;
+/**
+ * Sends event lines somewhere other than stdout. The stdio entry calls this
+ * with a stderr writer before it starts serving, because stdout carries the
+ * MCP protocol there and a log line on it corrupts the stream. The Worker
+ * keeps the default, where stdout is the platform log.
+ */
+export function setEventSink(next) {
+    sink = next;
+}
 /**
  * One structured line per agent-surface event. PII-safe by contract: pass only
- * names, booleans, counts, and already-coach-scoped ids — never message text,
+ * names, booleans, counts, and already-coach-scoped ids. Never message text,
  * guidance text, or reasoning strings.
  *
  * A local mirror of `@luca/observability`'s `logAgentSurfaceEvent`: this package
@@ -9,19 +34,9 @@
  * contract (event names + payload shape).
  */
 export function logAgentSurfaceEvent(event, fields) {
-    const clean = new Map([
-        ["msg", "mcp.agent_surface"],
-        ["event", event],
-    ]);
-    for (const [k, v] of Object.entries(fields)) {
-        // Equivalent to always assigning: `JSON.stringify` omits own properties whose
-        // value is `undefined`, so guarding here vs. assigning an undefined value to
-        // the accumulator key yields byte-identical logged output. The guard keeps
-        // the object tidy.
-        // Stryker disable next-line ConditionalExpression: JSON.stringify drops undefined-valued keys regardless
-        if (v !== undefined) {
-            clean.set(k, v);
-        }
-    }
-    console.log(JSON.stringify(Object.fromEntries(clean)));
+    sink(toJsonPayload({
+        msg: "mcp.agent_surface",
+        event,
+        ...R.filter(fields, P.isNotUndefined),
+    }));
 }