@setluca/mcp 0.2.0 → 0.3.0

package/dist/page-contract.js

@@ -0,0 +1,74 @@
+import * as HashMap from "effect/HashMap";
+import * as Option from "effect/Option";
+import * as R from "effect/Record";
+import { OPENAPI_CURSOR_QUERY_PARAMS } from "./generated/openapi-inputs.js";
+import { OPENAPI_OUTPUTS } from "./generated/openapi-outputs.js";
+const CURSOR_QUERY_PARAMS_BY_ROUTE = HashMap.fromIterable(R.toEntries(OPENAPI_CURSOR_QUERY_PARAMS));
+const OUTPUTS_BY_ROUTE = HashMap.fromIterable(R.toEntries(OPENAPI_OUTPUTS));
+/**
+ * The records field for a page whose body declares more than one array. Every
+ * other paging route declares exactly one, so it needs no entry here.
+ */
+// oxlint-disable-next-line anti-slop/no-known-value-widening -- looked up by a route string built at runtime, so the keys must stay open
+const ITEMS_KEY_BY_ROUTE = {
+    // `availableChannels` is the filter's option list, not a page of records.
+    "GET /api/conversations": "conversations",
+};
+/**
+ * The array field a page carries its records in, absent when the body hands
+ * back no cursor or declares no array.
+ *
+ * A body with one array has an obvious answer. A body with more than one needs
+ * `declared` to name it: guessing by declaration order would start merging the
+ * wrong array the day the API adds a field above the records. An undeclared
+ * tie, or a declared key the body does not carry as an array, throws while the
+ * catalog is built, so the mistake fails every test instead of reaching a
+ * client.
+ */
+export function itemsKeyOf(body, declared) {
+    if (body?.type !== "object" || body.properties?.nextCursor === undefined) {
+        return;
+    }
+    const arrays = R.toEntries(body.properties)
+        .filter(([key, schema]) => key !== "nextCursor" && schema?.type === "array")
+        .map(([key]) => key);
+    if (declared !== undefined) {
+        if (!arrays.includes(declared)) {
+            // oxlint-disable-next-line effect/avoid-untagged-errors -- a stale catalog entry is a programming error, not a runtime failure
+            throw new Error(`Page items key "${declared}" is not an array field of this response (arrays: ${arrays.join(", ") || "none"}).`);
+        }
+        return declared;
+    }
+    if (arrays.length > 1) {
+        // oxlint-disable-next-line effect/avoid-untagged-errors -- an ambiguous page shape is a programming error, not a runtime failure
+        throw new Error(`A paged response declares several arrays (${arrays.join(", ")}). Name its records field in ITEMS_KEY_BY_ROUTE.`);
+    }
+    return arrays[0];
+}
+/**
+ * The page shape of a route, absent when the route does not paginate.
+ *
+ * Walking a list needs both halves: a body that hands back a cursor and an
+ * array to merge, and a query field to send the cursor in. Guessing from the
+ * operation id used to answer this, and was wrong fourteen times: twelve routes
+ * that answer with a plain array and no cursor, and two that paginate under an
+ * id that does not end in `.list`.
+ */
+export function pageContractFor(method, path) {
+    const route = `${method} ${path}`;
+    return pageContractOf(Option.getOrUndefined(HashMap.get(CURSOR_QUERY_PARAMS_BY_ROUTE, route)), Option.getOrUndefined(HashMap.get(OUTPUTS_BY_ROUTE, route)), ITEMS_KEY_BY_ROUTE[route]);
+}
+/**
+ * The page shape a cursor query field and a response schema describe, absent
+ * when either half is missing. Split from {@link pageContractFor} so both halves can be
+ * withheld independently: the manifest happens to carry no route that takes a
+ * cursor and answers without one, and that asymmetry is a fact about today's
+ * API rather than a rule this function may assume.
+ */
+export function pageContractOf(cursorQueryParam, body, declaredItemsKey) {
+    const itemsKey = itemsKeyOf(body, declaredItemsKey);
+    if (cursorQueryParam === undefined || itemsKey === undefined) {
+        return;
+    }
+    return { cursorQueryParam, itemsKey };
+}

package/dist/pagination.js

@@ -1,127 +1,195 @@
-import { Effect, Option, Record } from "effect";
-import * as z from "zod/v4";
+import * as Arr from "effect/Array";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as HashSet from "effect/HashSet";
+import * as Option from "effect/Option";
+import * as R from "effect/Record";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { formatError, isAuthorizationFailure, } from "./errors.js";
+import { NonEmptyString } from "./fields.js";
 import { LucaApi } from "./http.js";
 import { logAgentSurfaceEvent } from "./observability.js";
 import { DEFAULT_MAX_PAGES, } from "./operations.js";
-import { JsonValueSchema, JsonObjectSchema, } from "./serialization.js";
-const JsonArraySchema = z.array(JsonValueSchema);
+import { optionalField } from "./optional-field.js";
+import { isJsonObject, JsonValue } from "./serialization.js";
+const decodeItems = Schema.decodeUnknownOption(Schema.Array(JsonValue));
+const isCursor = Schema.is(NonEmptyString);
 function pageItems(page, itemsKey) {
-    const parsed = JsonArraySchema.safeParse(page[itemsKey]);
-    return parsed.success ? parsed.data : [];
+    return Option.getOrElse(decodeItems(page[itemsKey]), () => []);
 }
 /**
- * The page as something the walk can follow, or nothing when the body is not an
- * object or declares no cursor. An `Option` rather than a nullable, because both
- * call sites below branch on it and would otherwise each have to lift it first.
+ * The page as something the walk can merge, or nothing when the body is not an
+ * object or does not carry the array the route's page shape names. Merging a
+ * shape the paginator cannot read would corrupt it.
  */
-function parsePaginatablePage(value) {
-    const parsed = JsonObjectSchema.safeParse(value);
-    if (!parsed.success) {
-        return Option.none();
-    }
-    const nextCursor = parsed.data.nextCursor;
-    if (nextCursor === undefined) {
-        return Option.none();
-    }
-    return Option.some({ ...parsed.data, nextCursor });
+function readablePage(value, itemsKey) {
+    return isJsonObject(value) && Array.isArray(value[itemsKey])
+        ? Option.some(value)
+        : Option.none();
 }
 /**
- * Whether a page actually carries the array the route's page shape names. A
- * body that does not is handed back untouched rather than merged, because
- * aggregating a shape the paginator cannot read would corrupt it.
+ * The cursor to the page after this one. A page that leaves `nextCursor` out,
+ * or sends it null or empty, is the last page.
  */
-function carriesItems(page, itemsKey) {
-    return Array.isArray(page[itemsKey]);
-}
 function cursorOf(page) {
-    const parsed = z.string().min(1).safeParse(page.nextCursor);
-    return parsed.success ? parsed.data : undefined;
+    const cursor = page.nextCursor;
+    return isCursor(cursor) ? cursor : undefined;
 }
-function walkOf(api, operation, pageShape, baseRequest, maxPages) {
+/**
+ * The longest one walk may take across all of its pages. Each request is bound
+ * on its own by the transport, so this caps the sum: a slow API cannot hold a
+ * tool call open for ten pages at that limit each.
+ */
+const WALK_BUDGET_MS = 120_000;
+function walkOf(api, operation, pageContract, baseRequest, maxPages) {
     return {
-        itemsKey: pageShape.itemsKey,
+        itemsKey: pageContract.itemsKey,
         maxPages,
         nextPage: (cursor) => api.request({
             operation,
             ...baseRequest,
             query: {
                 ...baseRequest.query,
-                [pageShape.cursorQueryParam]: cursor,
+                [pageContract.cursorQueryParam]: cursor,
             },
         }),
     };
 }
 /**
  * Follows `nextCursor` from the first page onward, merging each page's items
- * until the cursor runs out or the `maxPages` guard is hit. Kept as its own
- * Effect generator so the aggregation loop's branching lives apart from the
- * outer program's first-page setup and result assembly.
+ * until the cursor runs out, the `maxPages` guard is hit, or the walk's time
+ * budget is spent. Kept as its own Effect generator so the aggregation loop's
+ * branching lives apart from the outer program's first-page setup and result
+ * assembly.
+ *
+ * The state lives in a `Ref` so the budget can cut the loop off mid-page and
+ * still hand back the pages collected so far.
  */
 function collectRemainingPages(walk, first) {
     const { itemsKey } = walk;
+    const firstCursor = cursorOf(first);
     const initial = {
         items: pageItems(first, itemsKey),
-        cursor: cursorOf(first),
+        cursor: firstCursor,
         pagesFetched: 1,
-        // A page we cannot read stops the walk while keeping the cursor that led to
-        // it, so the caller still reports the result as truncated and hands the
-        // client a cursor to continue from.
-        stopped: false,
+        seen: HashSet.fromIterable(firstCursor === undefined ? [] : [firstCursor]),
+        halt: undefined,
     };
-    return Effect.iterate(initial, {
-        while: (state) => !state.stopped &&
-            state.cursor !== undefined &&
-            state.pagesFetched < walk.maxPages,
-        body: (state) => walk
-            .nextPage(state.cursor)
-            .pipe(Effect.map((page) => foldPage(state, page, itemsKey))),
+    return Ref.make(initial).pipe(Effect.flatMap((ref) => walkPages(walk, ref).pipe(Effect.timeoutOrElse({
+        duration: Duration.millis(WALK_BUDGET_MS),
+        orElse: () => Ref.get(ref).pipe(Effect.map((state) => haltWalk(state, {
+            reason: "time_budget_exceeded",
+            what: `the ${WALK_BUDGET_MS / 1000}s time budget for walking pages ran out before page ${state.pagesFetched + 1} arrived`,
+            continuable: true,
+        }))),
+    }))));
+}
+/** The page-by-page loop, writing each step to `ref` so a cut-off keeps it. */
+function walkPages(walk, ref) {
+    return Effect.gen(function* () {
+        // oxlint-disable-next-line effect/imperative-loops -- condition-driven loop over a mutable cursor; not a collection transform
+        while (true) {
+            const state = yield* Ref.get(ref);
+            if (state.halt !== undefined ||
+                state.cursor === undefined ||
+                state.pagesFetched >= walk.maxPages) {
+                return state;
+            }
+            // A failed later page must not throw away the pages already fetched.
+            // The result says it is partial and carries the cursor to retry from.
+            const page = yield* Effect.result(walk.nextPage(state.cursor));
+            // A refused token or a missing scope fails the call instead. A partial
+            // list would read as "page 3 is down", and only a failed tool result
+            // carries the challenge that sends the client back through sign-in.
+            if (Result.isFailure(page) && isAuthorizationFailure(page.failure)) {
+                return yield* Effect.fail(page.failure);
+            }
+            yield* Ref.set(ref, Result.match(page, {
+                onFailure: (error) => failedPage(state, formatError(error)),
+                onSuccess: (body) => foldPage(state, body, walk.itemsKey),
+            }));
+        }
+    });
+}
+function failedPage(state, reason) {
+    return haltWalk(state, {
+        reason,
+        what: `page ${state.pagesFetched + 1} failed (${reason})`,
+        continuable: true,
     });
 }
 /**
  * One more page folded into the walk's accumulated state, or a halt when the
- * page came back in a shape the paginator cannot read.
+ * page came back in a shape the paginator cannot read or broke the cursor
+ * chain.
  */
 function foldPage(state, page, itemsKey) {
-    return parsePaginatablePage(page).pipe(Option.match({
-        onNone: () => haltWalk(state),
+    return readablePage(page, itemsKey).pipe(Option.match({
+        onNone: () => haltWalk(state, {
+            reason: "unreadable_page",
+            what: `page ${state.pagesFetched + 1} came back in a shape that could not be read (unreadable_page)`,
+            continuable: true,
+        }),
         onSome: (readable) => mergePage(state, readable, itemsKey),
     }));
 }
 /** The walk stopped where it stands, keeping the cursor that led to the halt. */
-function haltWalk(state) {
-    return {
-        items: state.items,
-        cursor: state.cursor,
-        pagesFetched: state.pagesFetched,
-        stopped: true,
-    };
+function haltWalk(state, halt) {
+    return { ...state, halt };
 }
-/** The walk carried one page further. */
+/**
+ * The walk carried one page further. A server that answers an empty page with a
+ * cursor, or hands back a cursor it already sent, would have the walk spin until
+ * `maxPages`, so either one halts it instead.
+ */
 function mergePage(state, page, itemsKey) {
-    return {
-        items: [...state.items, ...pageItems(page, itemsKey)],
-        cursor: cursorOf(page),
+    const items = pageItems(page, itemsKey);
+    const cursor = cursorOf(page);
+    const advanced = {
+        items: [...state.items, ...items],
+        cursor,
         pagesFetched: state.pagesFetched + 1,
-        stopped: false,
+        seen: cursor === undefined ? state.seen : HashSet.add(state.seen, cursor),
+        halt: undefined,
     };
+    if (cursor === undefined) {
+        return advanced;
+    }
+    if (HashSet.has(state.seen, cursor)) {
+        return haltWalk(advanced, {
+            reason: "repeated_cursor",
+            what: `page ${advanced.pagesFetched} sent back a cursor the walk had already followed (repeated_cursor)`,
+            continuable: false,
+        });
+    }
+    return Arr.isReadonlyArrayNonEmpty(items)
+        ? advanced
+        : haltWalk(advanced, {
+            reason: "empty_page_with_cursor",
+            what: `page ${advanced.pagesFetched} was empty but offered another cursor (empty_page_with_cursor)`,
+            continuable: false,
+        });
 }
 /**
  * Bounded server-side auto-pagination for list tools. Follows nextCursor up to
  * maxPages, merging the items array, then returns a single aggregated result.
  * If more pages remain past the guard, the result is explicitly marked
- * `truncated` with a `nextCursor` to continue — never a silent partial result.
+ * `truncated` and carries a `nextCursor` to continue from, so a partial result
+ * always says it is one.
  */
-export function paginatedProgram(operation, pageShape, baseRequest, requestedMaxPages) {
+export function paginatedProgram(operation, pageContract, baseRequest, requestedMaxPages) {
     return Effect.gen(function* () {
         const api = yield* LucaApi;
-        const walk = walkOf(api, operation, pageShape, baseRequest, requestedMaxPages ?? DEFAULT_MAX_PAGES);
+        const walk = walkOf(api, operation, pageContract, baseRequest, requestedMaxPages ?? DEFAULT_MAX_PAGES);
         const first = yield* api.request({ operation, ...baseRequest });
-        const walkable = parsePaginatablePage(first).pipe(Option.filter((page) => carriesItems(page, pageShape.itemsKey)));
+        // A first page that carries no `nextCursor` key at all, or none of the
+        // array its page shape names, is returned exactly as the API sent it.
+        const walkable = readablePage(first, pageContract.itemsKey).pipe(Option.filter((page) => "nextCursor" in page));
         return yield* Option.match(walkable, {
-            // A response that carries no cursor, or none of the array its page shape
-            // names, is returned exactly as the API sent it.
             onNone: () => Effect.succeed(first),
-            onSome: (page) => collectRemainingPages(walk, page).pipe(Effect.map((collected) => aggregatePages(operation, page, pageShape.itemsKey, collected))),
+            onSome: (page) => collectRemainingPages(walk, page).pipe(Effect.map((collected) => aggregatePages(operation, page, pageContract.itemsKey, collected))),
         });
     });
 }
@@ -130,6 +198,11 @@ function aggregatePages(operation, first, itemsKey, collected) {
     const truncated = collected.cursor !== undefined;
     logPaginationTruncation(operation, collected.pagesFetched, truncated);
     return {
+        // Placed first so it leads the JSON text a model reads. A list that stopped
+        // on a failed page must not read as the whole list.
+        ...optionalField("warning", collected.halt === undefined
+            ? undefined
+            : incompleteWarning(collected, collected.halt, itemsKey)),
         // Preserve every non-item, non-cursor top-level field from the first page
         // (e.g. analytics totals on comment-event lists). The first page's own
         // `nextCursor` is dropped in favor of the aggregated `pagination` below,
@@ -140,16 +213,24 @@ function aggregatePages(operation, first, itemsKey, collected) {
             pagesFetched: collected.pagesFetched,
             truncated,
             nextCursor: collected.cursor ?? null,
+            ...optionalField("error", collected.halt?.reason),
         },
     };
 }
+/** What a caller reads first when the walk stopped early. */
+function incompleteWarning(collected, halt, itemsKey) {
+    const continueFrom = collected.cursor === undefined || !halt.continuable
+        ? ""
+        : ` Call again with cursor "${collected.cursor}" to fetch the rest.`;
+    return `INCOMPLETE LIST: ${halt.what}. \`${itemsKey}\` holds only the ${collected.items.length} items from the first ${collected.pagesFetched} page(s); do not treat it as the full list.${continueFrom}`;
+}
 /** Top-level first-page fields to carry through, minus items and nextCursor. */
 function passthroughFields(first, itemsKey) {
     // Dropping the `key !== itemsKey` guard is unobservable: the sole caller
     // spreads this result and then re-assigns `[itemsKey]: items` immediately
     // after (see the aggregation assembly), so any items value copied through here
     // is overwritten before it can reach the output.
-    return Record.filter(first, 
+    return R.filter(first, 
     // Stryker disable next-line ConditionalExpression: the items key is overwritten by the caller, so excluding it here changes nothing
     (_value, key) => key !== itemsKey && key !== "nextCursor");
 }