@setluca/mcp 0.2.1 → 0.3.0

package/dist/resilience.js

@@ -1,5 +1,12 @@
-import { Duration, Effect, Match, Option, Schedule } from "effect";
-import { LucaHttpError, LucaTimeoutError } from "./errors.js";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as HashSet from "effect/HashSet";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import * as Str from "effect/String";
+import { formatError, LucaHttpError, LucaTimeoutError, } from "./errors.js";
 /**
  * The statuses worth sending again. All four mean the request never reached the
  * handler, so a replay cannot repeat an effect the first attempt already had.
@@ -8,9 +15,9 @@ import { LucaHttpError, LucaTimeoutError } from "./errors.js";
  * may well be after it wrote something. Replaying that without an idempotency
  * key can double the write.
  */
-const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+const RETRYABLE_STATUSES = HashSet.fromIterable([429, 502, 503, 504]);
 /** Methods with no effect to repeat, so a replay is safe with or without a key. */
-const REPLAYABLE_METHODS = new Set(["GET", "HEAD"]);
+const REPLAYABLE_METHODS = HashSet.fromIterable(["GET", "HEAD"]);
 /**
  * The longest server-requested wait we will sit through. Past this the server
  * is not asking for a retry, it is asking us to come back later. Holding a
@@ -24,7 +31,10 @@ const RETRY_ATTEMPTS = 3;
  * `Schedule.recurs` caps the number of attempts; `Schedule.upTo` caps elapsed
  * time instead, which is a different job.
  */
-const httpRetrySchedule = Schedule.exponential(Duration.millis(200), 2).pipe(Schedule.jittered, Schedule.intersect(Schedule.recurs(RETRY_ATTEMPTS)));
+const httpRetrySchedule = Schedule.max([
+    Schedule.exponential(Duration.millis(200), 2).pipe(Schedule.jittered),
+    Schedule.recurs(RETRY_ATTEMPTS),
+]);
 /**
  * The idempotency key an attempt carries, absent for operations that do not
  * require one. An operation that requires a key the caller did not supply gets
@@ -38,12 +48,12 @@ function idempotencyKeyFor(request) {
 }
 /** How long the server asked us to wait, absent when it asked for nothing. */
 function requestedDelay(error) {
-    return Match.value(error).pipe(Match.when(Match.instanceOf(LucaHttpError), (http) => Option.fromNullable(http.retryAfterMs)), Match.orElse(() => Option.none()));
+    return Match.value(error).pipe(Match.when(Match.instanceOf(LucaHttpError), (http) => Option.fromNullishOr(http.retryAfterMs)), Match.orElse(() => Option.none()));
 }
 /**
  * The wait to sit out before replaying. No cap is applied here: {@link mayRetry}
- * already refused an overlong wait, and this only runs for a failure it agreed
- * to replay.
+ * already refused an overlong wait, and the schedule only reads this for a
+ * failure it agreed to replay.
  */
 function serverDelay(error) {
     return Option.map(requestedDelay(error), Duration.millis);
@@ -53,12 +63,15 @@ function serverDelay(error) {
  * timeout both leave the request's fate unknown; every other tag means the
  * server answered, so the answer is the outcome.
  */
-const TRANSIENT_TAGS = new Set(["LucaNetworkError", "LucaTimeoutError"]);
+const TRANSIENT_TAGS = HashSet.fromIterable([
+    "LucaNetworkError",
+    "LucaTimeoutError",
+]);
 /** A failure that says nothing about whether the request was handled. */
 function isTransient(error) {
-    return error._tag === "LucaHttpError"
-        ? RETRYABLE_STATUSES.has(error.status)
-        : TRANSIENT_TAGS.has(error._tag);
+    return error instanceof LucaHttpError
+        ? HashSet.has(RETRYABLE_STATUSES, error.status)
+        : HashSet.has(TRANSIENT_TAGS, error._tag);
 }
 /**
  * Whether this failure may be sent again. Reads are always replayable. A write
@@ -67,7 +80,7 @@ function isTransient(error) {
  * replay which cannot file the same write twice.
  *
  * A server that asked for a wait longer than we are willing to hold is refused
- * here too, so the sleep below and this decision never disagree.
+ * here too, so the schedule's wait and this decision never disagree.
  */
 export function mayRetry(policy, error) {
     if (!isTransient(error)) {
@@ -76,52 +89,94 @@ export function mayRetry(policy, error) {
     if (Option.exists(requestedDelay(error), (ms) => ms > MAX_RETRY_AFTER_MS)) {
         return false;
     }
-    return (REPLAYABLE_METHODS.has(policy.method) || policy.idempotencyKey !== undefined);
+    return (HashSet.has(REPLAYABLE_METHODS, policy.method) ||
+        policy.idempotencyKey !== undefined);
 }
 /**
- * Fails with the error the attempt produced, after sitting out a `Retry-After`
- * the server named. The wait only happens when the replay it is waiting for can
- * actually happen: a write with no idempotency key is refused above, so holding
- * the request open for the server's delay would spend the time and then fail
- * anyway.
+ * The backoff schedule with a `Retry-After` folded in: the next replay waits
+ * for whichever is longer, the backoff or the server's delay. The delay is read
+ * only when the schedule recurs, so the last attempt fails at once instead of
+ * sitting out a wait no replay will follow.
  */
-function failAfterServerDelay(policy, error) {
-    const delay = mayRetry(policy, error) ? serverDelay(error) : Option.none();
-    return Option.match(delay, {
-        onNone: () => Effect.fail(error),
-        onSome: (wait) => Effect.sleep(wait).pipe(Effect.zipRight(Effect.fail(error))),
+const retrySchedule = httpRetrySchedule.pipe(Schedule.modifyDelay(({ input, duration }) => Effect.succeed(Option.match(serverDelay(input), {
+    onNone: () => duration,
+    onSome: (wait) => Duration.max(duration, wait),
+}))));
+/**
+ * The longest one call may take across every attempt and every wait between
+ * them. Each attempt is still bounded on its own; this caps the sum, so a slow
+ * API cannot hold a tool call open past the point a hosted client gives up.
+ */
+const CALL_DEADLINE_MS = 45_000;
+const LAST_FAILURE_EXCERPT = 300;
+/**
+ * What the last failed attempt said, for a deadline that cut the call short. A
+ * 503 or 429 that was being retried is the real reason the call went nowhere,
+ * and the bare deadline message would hide it. A timeout adds nothing the
+ * message does not already say, so it is left out.
+ */
+function lastFailureNote(lastFailure) {
+    return Option.match(lastFailure, {
+        onNone: () => "",
+        onSome: (error) => error instanceof LucaTimeoutError
+            ? ""
+            : `. Last failure: ${Str.slice(0, LAST_FAILURE_EXCERPT)(formatError(error))}`,
+    });
+}
+/**
+ * The timeout a caller reads. A read can be sent again. A write that timed out
+ * may or may not have landed, so the message says so and names the key that
+ * makes a second send safe.
+ */
+function timeoutError(policy, ms, lastFailure = Option.none()) {
+    const base = `Luca API did not answer within ${ms}ms${lastFailureNote(lastFailure)}`;
+    if (HashSet.has(REPLAYABLE_METHODS, policy.method)) {
+        return new LucaTimeoutError({ message: base });
+    }
+    const replay = policy.idempotencyKey === undefined
+        ? "Check whether it took effect before sending it again."
+        : `Check whether it took effect, or send it again with idempotencyKey "${policy.idempotencyKey}" so the API cannot apply it twice.`;
+    return new LucaTimeoutError({
+        message: `${base}. The outcome is unknown: this ${policy.method} may or may not have been applied. ${replay}`,
     });
 }
 /**
- * One attempt, bounded and replayed under the rules above.
+ * One request, bounded and replayed under the rules above.
  *
- * The timeout is per attempt rather than over the whole retry: the attempt cap
- * already bounds total wall time, and the failure this guards is one socket that
- * never answers. `timeoutFail` keeps the failure inside `LucaError` instead of
- * leaking a `TimeoutException` as a defect.
+ * Two bounds apply. The per-attempt timeout guards one socket that never
+ * answers, and lets a replayable request try again. {@link CALL_DEADLINE_MS}
+ * caps the whole run, waits included. `timeoutOrElse` keeps both failures
+ * inside `LucaError` instead of leaking a `TimeoutError` as a defect.
  *
- * `Retry-After` is honoured with a sleep in front of the replay rather than
- * folded into the schedule. Carrying a per-error delay into a `Schedule` needs
- * `modifyDelayEffect` over a `Ref` to move the error across, and the result is
- * harder to read than the sleep for the same behaviour.
+ * `Retry-After` is honoured by {@link retrySchedule}, which stretches the
+ * backoff to the server's delay before a replay.
  */
-export function resilient(request, timeoutMs, attempt) {
-    // Minted here, once for the request rather than once per attempt, and handed
-    // to the sender. The API dedupes a write by this key, so a header and a
-    // replay decision derived from two different values would file the same
-    // write twice.
-    const idempotencyKey = idempotencyKeyFor(request);
-    const policy = {
-        method: request.operation.method,
-        idempotencyKey,
-    };
-    return attempt(idempotencyKey).pipe(Effect.timeoutFail({
-        duration: Duration.millis(timeoutMs),
-        onTimeout: () => new LucaTimeoutError({
-            message: `Luca API did not answer within ${timeoutMs}ms`,
-        }),
-    }), Effect.catchAll((error) => failAfterServerDelay(policy, error)), Effect.retry({
-        schedule: httpRetrySchedule,
-        while: (error) => mayRetry(policy, error),
-    }));
+export function resilient(request, timeoutMs, attempt, deadlineMs = CALL_DEADLINE_MS) {
+    // Minted when the program runs, once per run rather than once per attempt,
+    // and handed to the sender. The API dedupes a write by this key, so a header
+    // and a replay decision derived from two different values would file the
+    // same write twice. Minting at build time instead would hand every run of
+    // the same program one key, and the API would drop the second run as a
+    // replay of the first.
+    return Effect.gen(function* () {
+        const idempotencyKey = idempotencyKeyFor(request);
+        const lastFailure = yield* Ref.make(Option.none());
+        const policy = {
+            method: request.operation.method,
+            idempotencyKey,
+        };
+        return yield* attempt(idempotencyKey).pipe(Effect.timeoutOrElse({
+            duration: Duration.millis(timeoutMs),
+            orElse: () => Effect.fail(timeoutError(policy, timeoutMs)),
+        }), 
+        // Recorded after the per-attempt timeout so a hung attempt counts too,
+        // and before the retry so every failure the schedule swallows is seen.
+        Effect.tapError((error) => Ref.set(lastFailure, Option.some(error))), Effect.retry({
+            schedule: retrySchedule,
+            while: (error) => mayRetry(policy, error),
+        }), Effect.timeoutOrElse({
+            duration: Duration.millis(deadlineMs),
+            orElse: () => Ref.get(lastFailure).pipe(Effect.flatMap((last) => Effect.fail(timeoutError(policy, deadlineMs, last)))),
+        }));
+    });
 }

package/dist/resolvers.js

@@ -0,0 +1,125 @@
+import * as Arr from "effect/Array";
+import * as Clock from "effect/Clock";
+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 { createFixedWindowTable, } from "./fixed-window.js";
+import { callApi, sha256Hex, unavailable, } from "./token-verification.js";
+/**
+ * Whether a token belongs to `apiKeyResolver` rather than `oauthResolver`.
+ * Developer keys start with `luca_`. Refresh tokens start with `luca_ort_` and
+ * are not developer keys, so they go to the OAuth resolver, which refuses them
+ * without a network call. A malformed `luca_` token goes to `apiKeyResolver`
+ * and is refused there, so it never leaves the process.
+ */
+export function looksLikeDeveloperKey(token) {
+    return /^luca_(?!ort_)/i.test(token);
+}
+const DEVELOPER_KEY = /^luca_[a-f0-9]{64}$/i;
+/** The cheapest authenticated read in the public API. */
+const KEY_CHECK_PATH = "/api/capabilities";
+/** How long a passed key check is trusted. */
+const KEY_CHECK_TTL_MS = 60_000;
+export function createKeyCheckCache() {
+    return createFixedWindowTable(KEY_CHECK_TTL_MS);
+}
+/** One cache per isolate: the Worker builds a resolver per request. */
+const ISOLATE_KEY_CHECKS = createKeyCheckCache();
+/**
+ * The shape of an error from the Luca API. A 403 carrying it is the API's own
+ * scope answer, as opposed to an edge rule's.
+ */
+const LucaErrorBody = Schema.Struct({
+    error: Schema.Struct({
+        code: Schema.String,
+        message: Schema.String,
+        requestId: Schema.String,
+    }),
+});
+/** The session middleware's answer to a key with several workspaces and none chosen. */
+const WorkspaceRequiredBody = Schema.Struct({
+    error: Schema.Literal("workspace_required"),
+});
+/** The session middleware's answer to a key that reaches no workspace. */
+const NoWorkspaceAccessBody = Schema.Struct({
+    error: Schema.Literal("forbidden"),
+});
+/**
+ * The verdict an error answer carries, by status and body. Any other pairing
+ * (an edge rule's page, an unknown body) says nothing about the key.
+ */
+const BODY_VERDICTS = [
+    // The key authenticated; the check request named no workspace.
+    [400, Schema.is(WorkspaceRequiredBody), true],
+    // The key authenticated but lacks a scope for this route.
+    [403, Schema.is(LucaErrorBody), true],
+    // The key authenticated but reaches no workspace, so no call can succeed.
+    [403, Schema.is(NoWorkspaceAccessBody), false],
+];
+function keyHeaders(settings, apiKey) {
+    return settings.authHeader === "authorization"
+        ? { accept: "application/json", authorization: `Bearer ${apiKey}` }
+        : { accept: "application/json", "x-api-key": apiKey };
+}
+const verdictFromBody = (response) => Effect.tryPromise({
+    try: () => response.json(),
+    catch: unavailable("Key verification returned non-JSON content"),
+}).pipe(Effect.flatMap((body) => Arr.findFirst(BODY_VERDICTS, ([status, matches]) => status === response.status && matches(body)).pipe(Option.match({
+    onNone: () => Effect.fail(new TokenVerificationUnavailable({
+        message: `Key verification answered ${response.status} outside the Luca API`,
+    })),
+    onSome: ([, , valid]) => Effect.succeed(valid),
+}))));
+/** Whether the API vouches for the key: `false` is a refusal, sent as a 401. */
+const keyVerdict = (response) => {
+    if (response.status === 401) {
+        return Effect.succeed(false);
+    }
+    if (response.ok) {
+        return Effect.succeed(true);
+    }
+    return response.status === 400 || response.status === 403
+        ? verdictFromBody(response)
+        : Effect.fail(new TokenVerificationUnavailable({
+            message: `Key verification answered ${response.status}`,
+        }));
+};
+/**
+ * Resolver where the bearer token IS a Luca developer API key. Zero new
+ * privilege surface: the token resolves to exactly the coach scope that key
+ * already grants, enforced server-side by the Luca API on each call. A token
+ * that is not a well-formed key resolves to `None` with no network call. A
+ * well-formed one is checked with one authenticated API call first, so a
+ * fabricated key gets a 401 instead of a server.
+ *
+ * A 2xx accepts the key, and so do a 400 `workspace_required` and a 403 in the
+ * API's error shape, because both mean the key authenticated. A 401, or a 403
+ * `forbidden` for a key with no workspace, resolves to `None`. Anything else
+ * fails as {@link TokenVerificationUnavailable}. A passed check is trusted for
+ * 60 seconds, so only acceptances are cached.
+ */
+export function apiKeyResolver(settings, fetchImpl = fetch, checks = ISOLATE_KEY_CHECKS) {
+    const accepted = (token) => Option.some({ ...settings, apiKey: Redacted.make(token) });
+    const verify = (token, fingerprint) => callApi(settings, fetchImpl, {
+        path: KEY_CHECK_PATH,
+        init: { method: "GET", headers: keyHeaders(settings, token) },
+    }, keyVerdict).pipe(Effect.flatMap((valid) => valid
+        ? Effect.map(Clock.currentTimeMillis, (now) => {
+            // A full table skips the entry, so the key is checked again
+            // next time.
+            checks.charge(fingerprint, now);
+            return accepted(token);
+        })
+        : Effect.succeedNone));
+    return (token) => DEVELOPER_KEY.test(token)
+        ? Effect.gen(function* () {
+            const fingerprint = yield* sha256Hex(token).pipe(Effect.mapError(unavailable("Could not fingerprint the key")));
+            const now = yield* Clock.currentTimeMillis;
+            return checks.isLive(fingerprint, now)
+                ? accepted(token)
+                : yield* verify(token, fingerprint);
+        })
+        : Effect.succeedNone;
+}

package/dist/scopes.js

@@ -1,3 +1,5 @@
+import * as Arr from "effect/Array";
+import * as Order from "effect/Order";
 /**
  * The OAuth scopes this server advertises, and the API-key scopes each one
  * grants.
@@ -28,6 +30,13 @@ export const LUCA_OAUTH_SCOPES = [
     "luca:full_content",
     "offline_access",
 ];
+/**
+ * The scopes this resource accepts, for the RFC 9728 `scopes_supported` list.
+ * `offline_access` asks the authorization server for a refresh token and
+ * grants nothing here, so a client that copied it from this list onto its
+ * access-token request would be asking the resource for a scope it never checks.
+ */
+export const LUCA_RESOURCE_SCOPES = Arr.filter(LUCA_OAUTH_SCOPES, (scope) => scope !== "offline_access");
 /** Least-privilege default for a new OAuth connection. */
 export const OAUTH_DEFAULT_SCOPE = "luca:read luca:draft";
 const READ_TIER_SCOPES = [
@@ -36,6 +45,7 @@ const READ_TIER_SCOPES = [
     "broadcasts:read",
     "call_events:read",
     "campaigns:read",
+    "channels:read",
     "coach:read",
     "conversations:read",
     "integrations:read",
@@ -88,6 +98,18 @@ const FULL_TIER_SCOPES = [
     "integrations:write",
     "webhooks:write",
 ];
+/** The capability tiers from least to most privilege. */
+const CAPABILITY_TIERS = [
+    "read",
+    "draft",
+    "queue_ops",
+    "full",
+];
+function scopeForTier(tier) {
+    return `luca:${tier}`;
+}
+/** The capability scopes from least to most privilege. */
+export const CAPABILITY_LADDER = CAPABILITY_TIERS.map(scopeForTier);
 /**
  * Capability scope to the API scopes it grants. The tiers are strict supersets,
  * so `luca:full` covers everything `luca:queue_ops` does.
@@ -117,19 +139,57 @@ export const NON_TIER_OAUTH_SCOPES = {
 export function allGrantedApiScopes() {
     return OAUTH_CAPABILITY_SCOPES["luca:full"];
 }
+/** Whether a capability scope grants `apiScope`. */
+export function tierGrants(scope, apiScope) {
+    return Arr.contains(OAUTH_CAPABILITY_SCOPES[scope], apiScope);
+}
+/** A capability scope's position on the ladder, `0` for `luca:read`. */
+export function capabilityRank(scope) {
+    return CAPABILITY_LADDER.indexOf(scope);
+}
 /**
  * The lowest capability scope that grants `apiScope`, or `undefined` when no
  * tier grants it. Reading the ladder from the bottom is what makes the answer
  * the least-privilege one rather than merely a correct one.
  */
 export function lowestCapabilityScopeFor(apiScope) {
-    const ladder = [
-        "luca:read",
-        "luca:draft",
-        "luca:queue_ops",
-        "luca:full",
-    ];
-    return ladder.find((scope) => OAUTH_CAPABILITY_SCOPES[scope].includes(apiScope));
+    return CAPABILITY_LADDER.find((scope) => tierGrants(scope, apiScope));
+}
+/** The higher of two capability scopes. */
+function higherCapabilityScope(left, right) {
+    return capabilityRank(left) >= capabilityRank(right) ? left : right;
+}
+/**
+ * The least-privilege capability tier that lets an OAuth connection call an
+ * operation. Two rules apply, and the answer is the higher of the two:
+ *
+ * - The API accepts a key holding any one of the route's API scopes
+ *   (`apps/api/src/middleware/api-access.ts` checks `policy.scopes.some`), and
+ *   the tiers nest, so the lowest tier granting any of them is enough.
+ * - The tier the operation's own effect asks for (`requiredScope.capability`),
+ *   which the API checks once agent-scope enforcement is on.
+ *
+ * An operation whose API scopes no tier grants needs `full`. `docs:generate`
+ * already fails on that drift, so the fallback only keeps the answer
+ * conservative.
+ */
+export function effectiveCapability(operation) {
+    const routeTier = CAPABILITY_TIERS.find((tier) => operation.scopes.some((apiScope) => tierGrants(scopeForTier(tier), apiScope))) ?? "full";
+    return CAPABILITY_TIERS.indexOf(routeTier) >=
+        CAPABILITY_TIERS.indexOf(operation.requiredScope.capability)
+        ? routeTier
+        : operation.requiredScope.capability;
+}
+/** The OAuth scope that requests {@link effectiveCapability}. */
+export function oauthScopeForOperation(operation) {
+    return scopeForTier(effectiveCapability(operation));
+}
+/**
+ * The least-privilege capability scope for a task tool: the highest scope any
+ * operation it composes needs, because the tool runs all of them.
+ */
+export function oauthScopeForTool(operations) {
+    return Arr.reduce(operations, scopeForTier("read"), (scope, operation) => higherCapabilityScope(scope, oauthScopeForOperation(operation)));
 }
 /**
  * API scopes the operations need that no capability tier grants, sorted and
@@ -141,14 +201,7 @@ export function lowestCapabilityScopeFor(apiScope) {
  * with a hole in it.
  */
 export function unknownApiScopes(operations) {
-    const granted = new Set(allGrantedApiScopes());
-    const unknown = new Set();
-    for (const operation of operations) {
-        for (const scope of operation.scopes) {
-            if (!granted.has(scope)) {
-                unknown.add(scope);
-            }
-        }
-    }
-    return [...unknown].sort();
+    const granted = allGrantedApiScopes();
+    const unknown = Arr.filter(Arr.flatMap(operations, (operation) => operation.scopes), (scope) => !Arr.contains(granted, scope));
+    return Arr.sort(Arr.dedupe(unknown), Order.String);
 }

package/dist/serialization.js

@@ -3,34 +3,44 @@
  *
  * Every JSON boundary the server has is a wire boundary it does not control:
  * MCP content blocks are specified as text, an HTTP request body is a string,
- * and a rejection Response carries a JSON body. Keeping the three `JSON.*`
- * calls here means the rest of the package works in values, and a change to
- * how Luca serializes (indentation, replacer, a schema-encode step) has exactly
- * one place to happen.
+ * and a rejection Response carries a JSON body. Keeping the `JSON.*` calls and
+ * the JSON schemas here means the rest of the package works in values, and a
+ * change to how Luca serializes has exactly one place to happen.
  */
-import * as z from "zod/v4";
-export const JsonValueSchema = z.lazy(() => z.union([
-    z.string(),
-    z.number(),
-    z.boolean(),
-    z.null(),
-    z.array(JsonValueSchema),
-    z.record(z.string(), JsonValueSchema),
-]));
-/** The runtime counterpart of `JsonObject`: any JSON value keyed by string. */
-export const JsonObjectSchema = z.record(z.string(), JsonValueSchema);
+import * as Arr from "effect/Array";
+import * as P from "effect/Predicate";
+import * as Schema from "effect/Schema";
+/** Any JSON value. */
+export const JsonValue = Schema.Json;
+/** Any JSON value keyed by string. */
+export const JsonObject = Schema.JsonObject;
+/**
+ * Whether a JSON value is an object rather than an array or a scalar. The
+ * value is JSON already, so one shallow check is enough: validating the whole
+ * subtree again on every call would make a recursive walk quadratic.
+ */
+export function isJsonObject(value) {
+    return P.isObject(value);
+}
+/** Recognize a JSON array while retaining the type of its elements. */
+export function isJsonArray(value) {
+    return Arr.isArray(value);
+}
+const decodeJsonText = Schema.decodeUnknownEffect(Schema.fromJsonString(JsonValue));
+/**
+ * Parses JSON text into a JSON value. Malformed text fails with a
+ * `SchemaError` rather than throwing.
+ */
+export function parseJson(text) {
+    return decodeJsonText(text);
+}
 /** Pretty JSON for a human- or agent-readable text block. */
 export function toJsonText(value) {
+    // oxlint-disable-next-line effect/avoid-direct-json -- this file is the package's one JSON boundary. The input may hold `undefined` fields, which `JSON.stringify` drops and a `Schema.Json` encoder would reject.
     return JSON.stringify(value, null, 2) ?? "null";
 }
 /** Compact JSON for a wire payload: a request body, a response body, a log line. */
 export function toJsonPayload(value) {
+    // oxlint-disable-next-line effect/avoid-direct-json -- this file is the package's one JSON boundary. The input may hold `undefined` fields, which `JSON.stringify` drops and a `Schema.Json` encoder would reject.
     return JSON.stringify(value) ?? "null";
 }
-/**
- * Parses JSON text, throwing on malformed input. Callers run this inside an
- * `Effect.try` so the throw becomes a typed decode failure rather than a defect.
- */
-export function fromJson(raw) {
-    return JsonValueSchema.parse(JSON.parse(raw));
-}