@ganju/utils 0.0.13 → 0.0.15

package/dist/index.js

@@ -17,6 +17,8 @@ const coerce_1 = require("./coerce");
 const validateMessageVariables_1 = require("./validateMessageVariables");
 const jsonSchemaToZodShape_1 = require("./jsonSchemaToZodShape");
 const mcpProxy_1 = require("./mcpProxy");
+const toolCount_1 = require("./toolCount");
+const pagination_1 = require("./pagination");
 const customCodeToken_1 = require("./customCodeToken");
 const containmentToken_1 = require("./containmentToken");
 const oauthProviders_1 = require("./oauthProviders");
@@ -45,11 +47,15 @@ const l2Normalize_1 = require("./l2Normalize");
 const resourceRerank_1 = require("./resourceRerank");
 const retry_1 = require("./retry");
 const processQueueBatch_1 = require("./processQueueBatch");
+const queueFailure_1 = require("./queueFailure");
 const channelNotifier_1 = require("./channelNotifier");
 const channelDebounce_1 = require("./channelDebounce");
 const toolConfirmation_1 = require("./toolConfirmation");
+const untrustedContent_1 = require("./untrustedContent");
+const channelCustomer_1 = require("./channelCustomer");
 const toolLint_1 = require("./toolLint");
 const sources_1 = require("./sources");
+const citations_1 = require("./citations");
 const oauth_1 = require("./oauth");
 const vendorTimeZone_1 = require("./vendorTimeZone");
 const planLimitError_1 = require("./planLimitError");
@@ -93,6 +99,12 @@ exports.utils = {
     jsonSchemaToZodShape: jsonSchemaToZodShape_1.jsonSchemaToZodShape,
     validateAgainstJsonSchema: jsonSchemaToZodShape_1.validateAgainstJsonSchema,
     buildProxyToolName: mcpProxy_1.buildProxyToolName,
+    countInstallTools: toolCount_1.countInstallTools,
+    capText: pagination_1.capText,
+    findNextCursor: pagination_1.findNextCursor,
+    paginate: pagination_1.paginate,
+    InvalidCursorError: pagination_1.InvalidCursorError,
+    listResourcesPage: pagination_1.listResourcesPage,
     mintCustomCodeToken: customCodeToken_1.mintCustomCodeToken,
     verifyCustomCodeToken: customCodeToken_1.verifyCustomCodeToken,
     customCodeScriptName: customCodeToken_1.customCodeScriptName,
@@ -117,6 +129,7 @@ exports.utils = {
     validateProjectPath: customCodeProject_1.validateProjectPath,
     projectPathIssue: customCodeProject_1.projectPathIssue,
     ipv4InPrivateRange: ssrf_1.ipv4InPrivateRange,
+    isBlockedUrl: ssrf_1.isBlockedUrl,
     isBlockedHost: ssrf_1.isBlockedHost,
     requiresLlmBaseUrl: llmBaseUrl_1.requiresLlmBaseUrl,
     isAllowedLlmBaseUrl: llmBaseUrl_1.isAllowedLlmBaseUrl,
@@ -158,6 +171,8 @@ exports.utils = {
     isRateLimitError: retry_1.isRateLimitError,
     withRateLimitRetry: retry_1.withRateLimitRetry,
     processQueueBatch: processQueueBatch_1.processQueueBatch,
+    PermanentJobError: queueFailure_1.PermanentJobError,
+    isPermanentJobError: queueFailure_1.isPermanentJobError,
     getToolStatusMessage: channelNotifier_1.getToolStatusMessage,
     resolveDebounceMs: channelDebounce_1.resolveDebounceMs,
     channelBufferKey: channelDebounce_1.channelBufferKey,
@@ -172,7 +187,59 @@ exports.utils = {
     annotationsForEffect: toolConfirmation_1.annotationsForEffect,
     TOOL_EFFECTS: toolConfirmation_1.TOOL_EFFECTS,
     isSensitiveTool: toolConfirmation_1.isSensitiveTool,
+    proxiedToolAnnotations: toolConfirmation_1.proxiedToolAnnotations,
+    proxiedToolTrust: toolConfirmation_1.proxiedToolTrust,
+    isSensitiveProxiedTool: toolConfirmation_1.isSensitiveProxiedTool,
+    keepProxiedToolMarks: toolConfirmation_1.keepProxiedToolMarks,
+    toolApprovalStatus: toolConfirmation_1.toolApprovalStatus,
+    toolApprovalUrl: toolConfirmation_1.toolApprovalUrl,
     stableJson: toolConfirmation_1.stableJson,
+    wrapUntrustedContent: untrustedContent_1.wrapUntrustedContent,
+    unwrapUntrustedContent: untrustedContent_1.unwrapUntrustedContent,
+    isUntrustedToolResult: untrustedContent_1.isUntrustedToolResult,
+    findInstructionLikeText: untrustedContent_1.findInstructionLikeText,
+    UNTRUSTED_CONTENT_TAG: untrustedContent_1.UNTRUSTED_CONTENT_TAG,
+    UNTRUSTED_CONTENT_META_KEY: untrustedContent_1.UNTRUSTED_CONTENT_META_KEY,
+    UNTRUSTED_CONTENT_NOTE: untrustedContent_1.UNTRUSTED_CONTENT_NOTE,
+    INSTRUCTION_WARNING_METADATA_KEY: untrustedContent_1.INSTRUCTION_WARNING_METADATA_KEY,
+    untrustedToolResult: untrustedContent_1.untrustedToolResult,
+    ownWritingToolResult: untrustedContent_1.ownWritingToolResult,
+    labelOwnToolResult: untrustedContent_1.labelOwnToolResult,
+    labelProxiedToolResult: untrustedContent_1.labelProxiedToolResult,
+    untrustedErrorResult: untrustedContent_1.untrustedErrorResult,
+    readsLikeInstructions: untrustedContent_1.readsLikeInstructions,
+    labelResourceContents: untrustedContent_1.labelResourceContents,
+    PARTICIPANT_DAILY_LIMIT_DEFAULT: channelCustomer_1.PARTICIPANT_DAILY_LIMIT_DEFAULT,
+    PARTICIPANT_DAILY_LIMIT_MAX: channelCustomer_1.PARTICIPANT_DAILY_LIMIT_MAX,
+    PARTICIPANT_DAILY_LIMIT_OFF: channelCustomer_1.PARTICIPANT_DAILY_LIMIT_OFF,
+    PARTICIPANT_DAILY_LIMIT_WINDOW_MS: channelCustomer_1.PARTICIPANT_DAILY_LIMIT_WINDOW_MS,
+    PARTICIPANT_LIMIT_METADATA_KEY: channelCustomer_1.PARTICIPANT_LIMIT_METADATA_KEY,
+    resolveParticipantDailyLimit: channelCustomer_1.resolveParticipantDailyLimit,
+    resolveParticipantMemoryEnabled: channelCustomer_1.resolveParticipantMemoryEnabled,
+    VOICE_NOTE_MAX_BYTES: channelCustomer_1.VOICE_NOTE_MAX_BYTES,
+    VOICE_NOTE_MAX_SECONDS: channelCustomer_1.VOICE_NOTE_MAX_SECONDS,
+    audioDurationSeconds: channelCustomer_1.audioDurationSeconds,
+    oggDurationSeconds: channelCustomer_1.oggDurationSeconds,
+    VOICE_NOTE_TRANSCRIPTION_PROMPT: channelCustomer_1.VOICE_NOTE_TRANSCRIPTION_PROMPT,
+    VOICE_NOTE_METADATA_KEY: channelCustomer_1.VOICE_NOTE_METADATA_KEY,
+    VOICE_NOTE_UNREADABLE_METADATA_KEY: channelCustomer_1.VOICE_NOTE_UNREADABLE_METADATA_KEY,
+    PARTICIPANT_MEMORY_TOOL_NAME: channelCustomer_1.PARTICIPANT_MEMORY_TOOL_NAME,
+    PARTICIPANT_MEMORY_MAX_FACTS: channelCustomer_1.PARTICIPANT_MEMORY_MAX_FACTS,
+    PARTICIPANT_MEMORY_TOOL_DESCRIPTION: channelCustomer_1.PARTICIPANT_MEMORY_TOOL_DESCRIPTION,
+    PARTICIPANT_MEMORY_TOOL_SCHEMA: channelCustomer_1.PARTICIPANT_MEMORY_TOOL_SCHEMA,
+    PARTICIPANT_MEMORY_GROUP_NOTE: channelCustomer_1.PARTICIPANT_MEMORY_GROUP_NOTE,
+    readParticipantMemory: channelCustomer_1.readParticipantMemory,
+    applyParticipantMemoryUpdate: channelCustomer_1.applyParticipantMemoryUpdate,
+    redactParticipantMemoryArgs: channelCustomer_1.redactParticipantMemoryArgs,
+    redactParticipantMemoryConfirmation: channelCustomer_1.redactParticipantMemoryConfirmation,
+    participantMemoryUpdateReadsLikeInstructions: channelCustomer_1.participantMemoryUpdateReadsLikeInstructions,
+    CONVERSATION_UNTRUSTED_WINDOW_MS: channelCustomer_1.CONVERSATION_UNTRUSTED_WINDOW_MS,
+    CONVERSATION_UNTRUSTED_READ_AT_KEY: channelCustomer_1.CONVERSATION_UNTRUSTED_READ_AT_KEY,
+    conversationReadUntrustedRecently: channelCustomer_1.conversationReadUntrustedRecently,
+    formatParticipantMemoryPrompt: channelCustomer_1.formatParticipantMemoryPrompt,
+    participantLimitNotice: channelCustomer_1.participantLimitNotice,
+    voiceNoteUnreadableNotice: channelCustomer_1.voiceNoteUnreadableNotice,
+    voiceNoteTooLongNotice: channelCustomer_1.voiceNoteTooLongNotice,
     lintTools: toolLint_1.lintTools,
     TOOL_LINT_RULES: toolLint_1.TOOL_LINT_RULES,
     TOOL_LINT_MAX_TOOLS: toolLint_1.TOOL_LINT_MAX_TOOLS,
@@ -183,6 +250,9 @@ exports.utils = {
     buildResourceDownloadUrl: sources_1.buildResourceDownloadUrl,
     formatSourcesAsMarkdown: sources_1.formatSourcesAsMarkdown,
     formatSourcesAsButtons: sources_1.formatSourcesAsButtons,
+    citesUrl: citations_1.citesUrl,
+    citedPages: citations_1.citedPages,
+    selectCitedSources: citations_1.selectCitedSources,
     refreshOAuthToken: oauth_1.refreshOAuthToken,
     OAuthReauthRequiredError: oauth_1.OAuthReauthRequiredError,
     buildReauthMetadata: oauth_1.buildReauthMetadata,

package/dist/jsonSchemaToZodShape.d.ts

@@ -1,6 +1,6 @@
 import * as z from 'zod';
 export type JsonSchemaProperty = {
-    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
     description?: string;
     minimum?: number;
     maximum?: number;
@@ -9,6 +9,10 @@ export type JsonSchemaProperty = {
     pattern?: string;
     enum?: string[];
     items?: JsonSchemaProperty;
+    minItems?: number;
+    maxItems?: number;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
 };
 export type JsonSchema = {
     type: 'object';

package/dist/jsonSchemaToZodShape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsonSchemaToZodShape.d.ts","sourceRoot":"","sources":["../src/jsonSchemaToZodShape.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAChD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AA8CF,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,UAAU,KACjB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAY7B,CAAC;AAEF,MAAM,WAAW,eAAe;IAE9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,UAAU,EAClB,OAAO,OAAO,KACb,eAAe,EAOjB,CAAC"}
+{"version":3,"file":"jsonSchemaToZodShape.d.ts","sourceRoot":"","sources":["../src/jsonSchemaToZodShape.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAChD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAChD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAuEF,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,UAAU,KACjB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CACe,CAAC;AAE9C,MAAM,WAAW,eAAe;IAE9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,UAAU,EAClB,OAAO,OAAO,KACb,eAAe,EAOjB,CAAC"}

package/dist/jsonSchemaToZodShape.js

@@ -54,8 +54,9 @@ const propertyToZod = (prop) => {
             }
             break;
         }
-        case 'number': {
-            let num = z.number();
+        case 'number':
+        case 'integer': {
+            let num = prop.type === 'integer' ? z.number().int() : z.number();
             if (prop.minimum !== undefined)
                 num = num.min(prop.minimum);
             if (prop.maximum !== undefined)
@@ -66,11 +67,23 @@ const propertyToZod = (prop) => {
         case 'boolean':
             field = z.boolean();
             break;
-        case 'array':
-            field = z.array(prop.items ? propertyToZod(prop.items) : z.any());
+        case 'array': {
+            let arr = z.array(prop.items ? propertyToZod(prop.items) : z.any());
+            if (prop.minItems !== undefined)
+                arr = arr.min(prop.minItems);
+            if (prop.maxItems !== undefined)
+                arr = arr.max(prop.maxItems);
+            field = arr;
             break;
+        }
         case 'object':
-            field = z.record(z.string(), z.any());
+            // With declared properties, keep them: this shape is also what
+            // `tools/list` advertises, and a bare record there tells the model an
+            // item is any object at all, so it invents the field names. Loose,
+            // because a schema without `additionalProperties: false` allows extras.
+            field = prop.properties
+                ? z.looseObject(shapeOf(prop.properties, prop.required))
+                : z.record(z.string(), z.any());
             break;
         default:
             field = z.any();
@@ -80,16 +93,15 @@ const propertyToZod = (prop) => {
     }
     return field;
 };
-const jsonSchemaToZodShape = (schema) => {
-    const properties = schema.properties ?? {};
-    const required = schema.required ?? [];
+function shapeOf(properties = {}, required = []) {
     const shape = {};
     for (const [key, prop] of Object.entries(properties)) {
         const field = propertyToZod(prop);
         shape[key] = required.includes(key) ? field : field.optional();
     }
     return shape;
-};
+}
+const jsonSchemaToZodShape = (schema) => shapeOf(schema.properties, schema.required);
 exports.jsonSchemaToZodShape = jsonSchemaToZodShape;
 /**
  * Check a value against a declared JSON schema, returning the violations.

package/dist/pagination.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The cursor for the next page a JSON result names at its top level, if any.
+ * Cut text can lose it, so it is read from the parsed value before cutting.
+ */
+export declare const findNextCursor: (value: unknown) => string | undefined;
+/**
+ * `text` within `maxBytes` of UTF-8, or its start with a note that says it was
+ * cut. A character split by the cut is dropped rather than shown broken.
+ * `next` names the result's own cursor, for "call again with it".
+ */
+export declare const capText: (text: string, maxBytes: number, next?: string) => string;
+export declare class InvalidCursorError extends Error {
+    constructor();
+}
+/**
+ * What `list-resources` answers, wherever it runs (the MCP worker, and the
+ * channel runner, which lists proxied resources too): one page by uri, how many
+ * there are in all, and the cursor for the next page when there is one.
+ */
+export declare const listResourcesPage: (resources: Array<{
+    uri: string;
+    title?: string | null;
+    description?: string | null;
+    mimeType?: string | null;
+}>, args: {
+    cursor?: unknown;
+    limit?: unknown;
+}, limits: {
+    defaultLimit: number;
+    maxLimit: number;
+}) => string;
+/**
+ * One page of `items`, ordered by `keyOf`, starting after the item the cursor
+ * names. Keyed rather than counted, so an item added or removed between calls
+ * doesn't shift the next page onto ones already seen.
+ */
+export declare const paginate: <T>(items: T[], keyOf: (item: T) => string, options: {
+    cursor?: string;
+    limit?: number;
+    defaultLimit: number;
+    maxLimit: number;
+}) => {
+    page: T[];
+    nextCursor?: string;
+    total: number;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAUxD,CAAC;AAIF;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,MAAM,EACZ,UAAU,MAAM,EAChB,OAAO,MAAM,KACZ,MAaF,CAAC;AAmCF,qBAAa,kBAAmB,SAAQ,KAAK;;CAO5C;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,WAAW,KAAK,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC,EACF,MAAM;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,EAC3C,QAAQ;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,KACjD,MAgBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACxB,OAAO,CAAC,EAAE,EACV,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAC1B,SAAS;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,KACA;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CA4CjD,CAAC"}

package/dist/pagination.js

@@ -0,0 +1,160 @@
+"use strict";
+// Large tool results, in one shape: a list a tool owns is paged by a cursor the
+// model passes back, and text that has to be cut says so, how much was left
+// out, and where to continue when the result itself carried a cursor.
+//
+// Imports nothing, so node --test runs it directly.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paginate = exports.listResourcesPage = exports.InvalidCursorError = exports.capText = exports.findNextCursor = void 0;
+// Keys a paged API commonly answers with. Read at the top level only: deeper
+// than that, a key with one of these names is somebody's data.
+const NEXT_CURSOR_KEYS = [
+    'nextCursor',
+    'next_cursor',
+    'nextPageToken',
+    'next_page_token',
+    'nextPage',
+    'next_page',
+    'next'
+];
+/**
+ * The cursor for the next page a JSON result names at its top level, if any.
+ * Cut text can lose it, so it is read from the parsed value before cutting.
+ */
+const findNextCursor = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    for (const key of NEXT_CURSOR_KEYS) {
+        const found = value[key];
+        if (typeof found === 'string' && found)
+            return `${key}: ${found}`;
+        if (typeof found === 'number')
+            return `${key}: ${found}`;
+    }
+    return undefined;
+};
+exports.findNextCursor = findNextCursor;
+const kb = (bytes) => `${Math.max(1, Math.round(bytes / 1024))} KB`;
+/**
+ * `text` within `maxBytes` of UTF-8, or its start with a note that says it was
+ * cut. A character split by the cut is dropped rather than shown broken.
+ * `next` names the result's own cursor, for "call again with it".
+ */
+const capText = (text, maxBytes, next) => {
+    const bytes = new TextEncoder().encode(text);
+    if (bytes.byteLength <= maxBytes)
+        return text;
+    const kept = new TextDecoder()
+        .decode(bytes.slice(0, maxBytes))
+        .replace(/�+$/, '');
+    const continueWith = next
+        ? ` The result names its next page (${next}): call again with it to continue.`
+        : ' To see the rest, call again asking for less — narrower filters, a smaller page or fewer fields.';
+    return `${kept}\n\n[Truncated: showing the first ${kb(maxBytes)} of ${kb(bytes.byteLength)}.${continueWith}]`;
+};
+exports.capText = capText;
+// Opaque to the model, so it is passed back as given rather than edited.
+const encodeCursor = (key) => btoa(String.fromCharCode(...new TextEncoder().encode(key)))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+const decodeCursor = (cursor) => {
+    try {
+        const base64 = cursor.replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(base64);
+        return new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(binary, char => char.charCodeAt(0)));
+    }
+    catch {
+        return null;
+    }
+};
+// Between a cursor's key and the count of items with that key already served.
+// A key is a uri or a name, never a NUL.
+const CURSOR_SEEN_SEPARATOR = '\u0000';
+// A cursor with no count (one issued before the count was added) resumes
+// after every item with its key.
+const splitCursorKey = (decoded) => {
+    const at = decoded.lastIndexOf(CURSOR_SEEN_SEPARATOR);
+    if (at === -1)
+        return { key: decoded, seen: Infinity };
+    const count = decoded.slice(at + 1);
+    if (!/^\d+$/.test(count))
+        throw new InvalidCursorError();
+    return { key: decoded.slice(0, at), seen: Number(count) };
+};
+class InvalidCursorError extends Error {
+    constructor() {
+        super('That cursor is not valid. Call again without a cursor to start from the first page.');
+        this.name = 'InvalidCursorError';
+    }
+}
+exports.InvalidCursorError = InvalidCursorError;
+/**
+ * What `list-resources` answers, wherever it runs (the MCP worker, and the
+ * channel runner, which lists proxied resources too): one page by uri, how many
+ * there are in all, and the cursor for the next page when there is one.
+ */
+const listResourcesPage = (resources, args, limits) => {
+    const { page, total, nextCursor } = (0, exports.paginate)(resources, r => r.uri, {
+        cursor: typeof args.cursor === 'string' ? args.cursor : undefined,
+        limit: typeof args.limit === 'number' ? args.limit : undefined,
+        ...limits
+    });
+    return JSON.stringify({
+        resources: page.map(r => ({
+            uri: r.uri,
+            title: r.title || undefined,
+            description: r.description || undefined,
+            mimeType: r.mimeType || undefined
+        })),
+        total,
+        ...(nextCursor ? { nextCursor } : {})
+    });
+};
+exports.listResourcesPage = listResourcesPage;
+/**
+ * One page of `items`, ordered by `keyOf`, starting after the item the cursor
+ * names. Keyed rather than counted, so an item added or removed between calls
+ * doesn't shift the next page onto ones already seen.
+ */
+const paginate = (items, keyOf, options) => {
+    const limit = Math.min(Math.max(Math.floor(Number(options.limit) || options.defaultLimit), 1), options.maxLimit);
+    const sorted = [...items].sort((a, b) => {
+        const left = keyOf(a);
+        const right = keyOf(b);
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
+    let start = 0;
+    if (options.cursor) {
+        const decoded = decodeCursor(options.cursor);
+        if (decoded === null)
+            throw new InvalidCursorError();
+        const { key: after, seen } = splitCursorKey(decoded);
+        start = sorted.findIndex(item => keyOf(item) >= after);
+        if (start === -1)
+            start = sorted.length;
+        // Items that share the cursor's key: skip the ones already served, in the
+        // order the sort (which is stable) keeps them.
+        for (let skipped = 0; start < sorted.length && keyOf(sorted[start]) === after && skipped < seen; skipped++) {
+            start++;
+        }
+    }
+    const page = sorted.slice(start, start + limit);
+    const more = start + limit < sorted.length;
+    if (!more || page.length === 0)
+        return { page, total: sorted.length };
+    // The last key served, and how many items with that key have been served
+    // so far, so a run of equal keys split across pages resumes inside the run.
+    const end = start + page.length;
+    const lastKey = keyOf(page[page.length - 1]);
+    let seen = 0;
+    for (let i = end - 1; i >= 0 && keyOf(sorted[i]) === lastKey; i--)
+        seen++;
+    return {
+        page,
+        total: sorted.length,
+        nextCursor: encodeCursor(`${lastKey}${CURSOR_SEEN_SEPARATOR}${seen}`)
+    };
+};
+exports.paginate = paginate;

package/dist/processQueueBatch.d.ts

@@ -1,5 +1,6 @@
 export interface QueueMessageLike<T> {
     body: T;
+    attempts?: number;
     ack: () => void;
     retry: (opts?: {
         delaySeconds?: number;
@@ -9,9 +10,13 @@ export interface QueueBatchLike<T> {
     queue: string;
     messages: readonly QueueMessageLike<T>[];
 }
+export interface QueueFailureContext {
+    final: boolean;
+}
 export interface ProcessQueueBatchHandlers<T> {
     process: (body: T) => Promise<void>;
-    onError: (error: unknown, body: T, queueName: string) => Promise<void>;
+    onError: (error: unknown, body: T, queueName: string, context: QueueFailureContext) => Promise<void>;
+    maxRetries?: number;
 }
 export declare const processQueueBatch: <T>(batch: QueueBatchLike<T>, handlers: ProcessQueueBatchHandlers<T>) => Promise<void>;
 //# sourceMappingURL=processQueueBatch.d.ts.map

package/dist/processQueueBatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"processQueueBatch.d.ts","sourceRoot":"","sources":["../src/processQueueBatch.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAED,eAAO,MAAM,iBAAiB,GAAU,CAAC,EACvC,OAAO,cAAc,CAAC,CAAC,CAAC,EACxB,UAAU,yBAAyB,CAAC,CAAC,CAAC,KACrC,OAAO,CAAC,IAAI,CAuBd,CAAC"}
+{"version":3,"file":"processQueueBatch.d.ts","sourceRoot":"","sources":["../src/processQueueBatch.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IAER,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAmB;IAIlC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,EAAE,CACP,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,mBAAmB,KACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AASD,eAAO,MAAM,iBAAiB,GAAU,CAAC,EACvC,OAAO,cAAc,CAAC,CAAC,CAAC,EACxB,UAAU,yBAAyB,CAAC,CAAC,CAAC,KACrC,OAAO,CAAC,IAAI,CA4Bd,CAAC"}

package/dist/processQueueBatch.js

@@ -3,25 +3,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.processQueueBatch = void 0;
 const retry_1 = require("./retry");
 const constants_1 = require("./constants");
+const queueFailure_1 = require("./queueFailure");
+const failureKind = (error) => {
+    if ((0, queueFailure_1.isPermanentJobError)(error))
+        return 'permanent';
+    if ((0, retry_1.isTransientInfraError)(error))
+        return 'transient';
+    if ((0, retry_1.isRateLimitError)(error))
+        return 'rateLimit';
+    return 'other';
+};
 const processQueueBatch = async (batch, handlers) => {
+    const maxRetries = handlers.maxRetries ?? constants_1.constants.QUEUE_MAX_RETRIES;
     for (const message of batch.messages) {
         try {
             await handlers.process(message.body);
             message.ack();
         }
         catch (error) {
-            if ((0, retry_1.isTransientInfraError)(error)) {
-                // Transient Cloudflare platform hiccup (e.g. a Durable Object /
-                // Container reset). The job itself is fine, so re-run it after a short
-                // backoff without reporting an error or marking the work failed.
+            const plan = (0, queueFailure_1.planQueueFailure)(failureKind(error), message.attempts, maxRetries);
+            if (plan.report) {
+                await handlers.onError(error, message.body, batch.queue, {
+                    final: plan.final
+                });
+            }
+            if (plan.action === 'ack') {
+                message.ack();
+            }
+            else if (plan.backoff === 'transient') {
                 message.retry({ delaySeconds: constants_1.constants.TRANSIENT_BACKOFF_SECONDS });
-                continue;
             }
-            await handlers.onError(error, message.body, batch.queue);
-            if ((0, retry_1.isRateLimitError)(error)) {
-                message.retry({
-                    delaySeconds: constants_1.constants.RATE_LIMIT_BACKOFF_SECONDS
-                });
+            else if (plan.backoff === 'rateLimit') {
+                message.retry({ delaySeconds: constants_1.constants.RATE_LIMIT_BACKOFF_SECONDS });
             }
             else {
                 message.retry();

package/dist/queueFailure.d.ts

@@ -0,0 +1,14 @@
+export declare class PermanentJobError extends Error {
+    readonly permanent = true;
+    constructor(message: string);
+}
+export declare const isPermanentJobError: (error: unknown) => boolean;
+export type QueueFailureKind = 'permanent' | 'transient' | 'rateLimit' | 'other';
+export interface QueueFailurePlan {
+    report: boolean;
+    final: boolean;
+    action: 'ack' | 'retry';
+    backoff: 'transient' | 'rateLimit' | null;
+}
+export declare const planQueueFailure: (kind: QueueFailureKind, attempts: number | undefined, maxRetries: number) => QueueFailurePlan;
+//# sourceMappingURL=queueFailure.d.ts.map

package/dist/queueFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queueFailure.d.ts","sourceRoot":"","sources":["../src/queueFailure.ts"],"names":[],"mappings":"AASA,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,SAAS,QAAQ;gBAEd,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,OAGE,CAAC;AAExD,MAAM,MAAM,gBAAgB,GACxB,WAAW,GACX,WAAW,GACX,WAAW,GACX,OAAO,CAAC;AAEZ,MAAM,WAAW,gBAAgB;IAE/B,MAAM,EAAE,OAAO,CAAC;IAEhB,KAAK,EAAE,OAAO,CAAC;IAEf,MAAM,EAAE,KAAK,GAAG,OAAO,CAAC;IAExB,OAAO,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAAC;CAC3C;AAID,eAAO,MAAM,gBAAgB,GAC3B,MAAM,gBAAgB,EACtB,UAAU,MAAM,GAAG,SAAS,EAC5B,YAAY,MAAM,KACjB,gBAgBF,CAAC"}

package/dist/queueFailure.js

@@ -0,0 +1,43 @@
+"use strict";
+// How a failed queue job is handled: retried, given up on, or reported. Kept
+// apart from processQueueBatch, which applies it, so the decision is testable
+// on its own.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planQueueFailure = exports.isPermanentJobError = exports.PermanentJobError = void 0;
+// A failure that no retry can fix — a credential that needs the user to
+// reconnect, a resource that no longer exists. The job is reported once and
+// acknowledged rather than retried into the dead-letter queue. Recognised by
+// its `permanent` flag rather than its class, so an error built by another
+// copy of this module still counts.
+class PermanentJobError extends Error {
+    permanent = true;
+    constructor(message) {
+        super(message);
+        this.name = 'PermanentJobError';
+    }
+}
+exports.PermanentJobError = PermanentJobError;
+const isPermanentJobError = (error) => !!error &&
+    typeof error === 'object' &&
+    error.permanent === true;
+exports.isPermanentJobError = isPermanentJobError;
+// `attempts` is the queue's own count, 1 on the first delivery; a consumer
+// with `maxRetries` retries gets maxRetries + 1 deliveries in all.
+const planQueueFailure = (kind, attempts, maxRetries) => {
+    if (kind === 'permanent') {
+        return { report: true, final: true, action: 'ack', backoff: null };
+    }
+    const final = (attempts ?? 1) > maxRetries;
+    if (kind === 'transient') {
+        // A platform hiccup is retried quietly; only the last one is worth a
+        // report, since nothing will run the job after it.
+        return { report: final, final, action: 'retry', backoff: 'transient' };
+    }
+    return {
+        report: true,
+        final,
+        action: 'retry',
+        backoff: kind === 'rateLimit' ? 'rateLimit' : null
+    };
+};
+exports.planQueueFailure = planQueueFailure;

package/dist/resourceRerank.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resourceRerank.d.ts","sourceRoot":"","sources":["../src/resourceRerank.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAI1C,MAAM,WAAW,eAAe;IAC9B,GAAG,CACD,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,SAAS,KAEf,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,GAClE,SAyBH,CAAC"}
+{"version":3,"file":"resourceRerank.d.ts","sourceRoot":"","sources":["../src/resourceRerank.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAI1C,MAAM,WAAW,eAAe;IAC9B,GAAG,CACD,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,SAAS,KAEf,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,GAClE,SA6BH,CAAC"}

package/dist/resourceRerank.js

@@ -20,7 +20,9 @@ const createResourceReranker = (source) => {
             contexts: documents.map(text => ({ text })),
             top_k: documents.length
         }));
-        const scores = new Array(documents.length);
+        // Filled, not just sized: `some` skips the holes of a bare new Array(n), so
+        // a document the response left out would pass the check below unscored.
+        const scores = new Array(documents.length).fill(undefined);
         for (const item of result?.response ?? []) {
             if (typeof item.id === 'number' &&
                 typeof item.score === 'number' &&