qyl-mcp-server 7.4.0 → 7.6.0

package/README.md

@@ -38,7 +38,10 @@ with PKCE S256, both `private_key_jwt` and `none` for ChatGPT CIMD compatibility
 `none` for Claude CIMD, and issuer identification. Auth0 owns registration and token
 issuance; this server validates resource-bound RFC 9068 access tokens on every
 MCP request. It rejects malformed/query credentials, invalid tokens and
-insufficient scopes with distinct 400/401/403 responses.
+insufficient scopes with distinct 400/401/403 responses. Every request needs
+`qyl:read`; a write tool called without `qyl:write` or `qyl:delete` gets a
+`403` with `error="insufficient_scope"` naming the scopes to request, in both
+protocol eras, before the handler runs.
 
 Optional resource-server integrations are selected explicitly:
 
@@ -97,12 +100,29 @@ with `cursor` like the telemetry lists.
 model. Its input is one of four shapes selected by `view` (`traces`, `trace`,
 `logs`, `mcp_stats`); the `trace` view requires `trace_id` at the schema layer.
 
+**Writes** — `create_annotation`, `update_annotation`, `create_saved_query`,
+`update_saved_query` and `delete` change only objects users create in qyl, in
+the caller's Collector project: annotations (plain-text notes of at most 2000
+characters on a trace, span or session) and saved queries (named filters for
+traces, logs or metrics). `delete` takes `kind` (`annotation` or
+`saved_query`; alert rules follow with Contract 11.7.0), `id` and `etag`. No
+tool deletes or edits traces, logs or metrics; retention removes telemetry.
+Updates and deletes send the `etag` as `If-Match`: a stale one fails with
+`precondition_failed`, a duplicate saved-query name with `conflict`.
+`list_saved_queries` and `run_saved_query` read saved queries; `get_trace` and
+`list_sessions` return the annotations on what they read. Demo mode keeps none
+of these objects and refuses these tools.
+
 **Failures** — every failed call returns `isError: true`, the message as text,
 and `structuredContent.error = { code, message, retryable }` with the
 contract's `ToolErrorCode`.
 
-Every tool is read-only: the server queries the configured collector and never
-mutates it. On the hosted server they all sit behind the single `qyl:read` scope.
+The thirteen read tools carry `readOnlyHint: true` and only query the
+configured collector. The create tools carry `destructiveHint: false` and
+`idempotentHint: false`; the update tools and `delete` carry
+`destructiveHint: true` and `idempotentHint: true`. On the hosted server
+`qyl:read` covers the read tools, `qyl:write` adds the create and update tools,
+and `qyl:delete` adds `delete`.
 
 The `display_*` tools return MCP Apps UI resources as single-file viewers.
 
@@ -134,7 +154,7 @@ multi-tenant audit log.
 | Variable | Meaning |
 | --- | --- |
 | `QYL_COLLECTOR_URL` | Collector read API base; default `http://127.0.0.1:5100`. Also the OTLP base when set. |
-| `QYL_API_KEY` | Collector read and OTLP credential. Outgoing only. |
+| `QYL_API_KEY` | Collector credential for reads and OTLP; the write tools need the Collector's `write` and `delete` roles on it. Outgoing only. |
 | `QYL_PROJECT` | Server-owned collector project scope. Unset, the server sends no project-scope header, so the Collector's default project applies; the Events subscription source key records that as `default`. Never accepted as tool input. This is the only place that states the default; other documents link here. |
 | `MCP_COLLECTOR_PROJECTS` | Optional secret JSON mapping validated Auth0 subjects to project-bound Collector keys; see account isolation below. |
 | `QYL_OTLP_ENDPOINT` | Optional OTLP base for self-telemetry. |
@@ -182,15 +202,49 @@ assignment revokes its Events subscription on the next access check. Project
 keys are redacted from text and structured results, including keys nested in
 this JSON configuration. Keep the map in host secrets and out of the plugin ZIP.
 
-`bun run smoke:projects` from the repository root checks all eleven tools,
-viewer query paths, both protocol eras and Events against a real local
-Collector with two temporary projects. Set `QYL_COLLECTOR_PROJECT` to its
+`bun run smoke:projects` from the repository root checks every tool, the
+writes included, viewer query paths, both protocol eras and Events against a
+real local Collector with two temporary projects. Set `QYL_COLLECTOR_PROJECT` to its
 `.csproj` when using a different checkout. The script uses local test identities
 and an in-process signed webhook receiver; the hosted reviewer OAuth login and
 real ChatGPT demonstration are separate checks before upload.
 
 ## Release notes
 
+### 7.6.0
+
+- Contract 12.0.0 (`@ancplua/qyl-api-schema` 12.0.0, revision
+  `sha256:b29439eba28e752b`): the server is generated from it and refuses a
+  Collector on another revision, so it deploys only after the Collector serves
+  12.0.0.
+- Every problem the Collector or the workbench reports is RFC 9457 with a
+  `type` URI (`https://qyl.at/problems/<name>`) and a stable `code`. A tool
+  error's code now follows the problem's `code` (`not_found`, `conflict`,
+  `precondition_failed`, `precondition_required`, `collector_unauthorized`,
+  `collector_error`) and falls back to the HTTP status only for a body
+  without one.
+- One page limit on every list: 1 to 1000, 100 when omitted. The workbench
+  reads Collector logs in pages of 1000 following `next_cursor` (up to ten
+  pages, the same bound as before), and its protocol-event page defaults to
+  100. `next_cursor` is absent on the last page.
+- The workbench's HTTP errors no longer carry `X-Request-Id`; no server sent
+  it.
+
+### 7.5.0
+
+- Write tools, each a separate tool so a host can approve it on its own:
+  `create_annotation` and `update_annotation` (notes on a trace, span or
+  session), `create_saved_query` and `update_saved_query` (named filters), and
+  one `delete` for either kind. They change only those objects, in the
+  caller's Collector project; no tool deletes or edits telemetry.
+  `list_saved_queries` and `run_saved_query` read saved queries, and
+  `get_trace` and `list_sessions` return annotations.
+- Scopes: `qyl:write` for create and update, `qyl:delete` for `delete`;
+  `qyl:read` alone keeps the read tools. The protected-resource metadata lists
+  all three, and a call without the scope it needs gets a `403`
+  `insufficient_scope` challenge. The Collector key needs the `write` and
+  `delete` roles.
+
 ### 7.4.0
 
 - Contract package `@ancplua/qyl-api-schema` 11.6.0 (revision

package/dist/cloudflare-access.d.ts

@@ -7,8 +7,9 @@ export interface AccessConfig {
 export declare function readAccessConfig(environment: Readonly<Record<string, string | undefined>>): AccessConfig | undefined;
 /** Access validates the client's opaque OAuth token at the edge. The origin
  * accepts only its signed assertion, including on the direct Railway hostname.
- * Membership of this Access app authorizes the server's read-only tool surface;
- * the assertion does not carry an OAuth client ID or qyl scopes.
+ * Membership of this Access app authorizes the read tools (`qyl:read`); the
+ * assertion carries no OAuth client ID or qyl scopes, so the write tools,
+ * which need `qyl:write` or `qyl:delete`, answer `insufficient_scope` here.
  */
 export declare function createCloudflareAccessAuth(params: AccessConfig & {
     resource: URL;

package/dist/cloudflare-access.js

@@ -28,8 +28,9 @@ export function readAccessConfig(environment) {
 }
 /** Access validates the client's opaque OAuth token at the edge. The origin
  * accepts only its signed assertion, including on the direct Railway hostname.
- * Membership of this Access app authorizes the server's read-only tool surface;
- * the assertion does not carry an OAuth client ID or qyl scopes.
+ * Membership of this Access app authorizes the read tools (`qyl:read`); the
+ * assertion carries no OAuth client ID or qyl scopes, so the write tools,
+ * which need `qyl:write` or `qyl:delete`, answer `insufficient_scope` here.
  */
 export function createCloudflareAccessAuth(params) {
     const { teamDomain, audience } = validateConfig(params);

package/dist/cloudflare-access.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare-access.js","sourceRoot":"","sources":["../src/cloudflare-access.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cloudflare-access.js","sourceRoot":"","sources":["../src/cloudflare-access.ts"],"names":[],"mappings":"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"}

package/dist/collector-resources.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Collector calls for the objects users create in qyl: annotations (notes on
+ * a trace, span or session) and saved queries (named filters).
+ *
+ * They live in the caller's Collector project like telemetry does, and every
+ * call reaches it with the options `runTool` resolved from the verified
+ * subject; no argument names a project or a credential. Nothing here changes
+ * telemetry: an annotation points at a trace, span or session and leaves it
+ * as recorded, and the one delete operation removes only these objects.
+ *
+ * Demo mode has no Collector and therefore no such objects. A call there is
+ * refused rather than answered from an invented store.
+ */
+import type { Annotation, CreateAnnotationInput, CreateSavedQueryInput, DeletableKind, ListSavedQueriesInput, RunSavedQueryInput, SavedQuery, SavedQueryRunResult, SessionId, TraceId, UpdateAnnotationInput, UpdateSavedQueryInput } from "@ancplua/qyl-api-schema/types";
+import { type CollectorRequestOptions } from "./collector.js";
+import { type ToolScope } from "./request-scope.js";
+export declare function createAnnotation(input: CreateAnnotationInput, options: CollectorRequestOptions): Promise<Annotation>;
+export declare function updateAnnotation(input: UpdateAnnotationInput, options: CollectorRequestOptions): Promise<Annotation>;
+export declare function createSavedQuery(input: CreateSavedQueryInput, options: CollectorRequestOptions): Promise<SavedQuery>;
+export declare function updateSavedQuery(input: UpdateSavedQueryInput, options: CollectorRequestOptions): Promise<SavedQuery>;
+export interface SavedQueryPage {
+    savedQueries: SavedQuery[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+export declare function listSavedQueries(input: ListSavedQueriesInput, options: CollectorRequestOptions): Promise<SavedQueryPage>;
+export declare function runSavedQuery(input: RunSavedQueryInput, options: CollectorRequestOptions): Promise<SavedQueryRunResult>;
+export declare function deleteResource(kind: DeletableKind, id: string, etag: string, options: CollectorRequestOptions): Promise<void>;
+/** What a read tool adds to its result: the annotations and one text line. */
+export interface AnnotationReadBack {
+    /** Present when the read succeeded; absent in demo mode and when it failed. */
+    annotations?: Annotation[];
+    /** Appended to the tool's text summary; empty when there is nothing to say. */
+    text: string;
+}
+/** The telemetry object an annotation names, in full. */
+export declare function describeTarget(target: Annotation["target"]): string;
+/** One text line per annotation: what it is on, how to change it, and the note. */
+export declare function annotationLine(annotation: Annotation): string;
+/** The text block for a list of annotations, newest first. */
+export declare function summarizeAnnotations(annotations: readonly Annotation[], truncated: boolean): string;
+/** The annotations on one trace and its spans, for get_trace. */
+export declare function readTraceAnnotations(traceId: TraceId, scope: ToolScope): Promise<AnnotationReadBack>;
+/** The annotations on the listed sessions, newest first, for list_sessions. */
+export declare function readSessionAnnotations(sessionIds: readonly SessionId[], scope: ToolScope): Promise<AnnotationReadBack>;

package/dist/collector-resources.js

@@ -0,0 +1,295 @@
+/**
+ * Collector calls for the objects users create in qyl: annotations (notes on
+ * a trace, span or session) and saved queries (named filters).
+ *
+ * They live in the caller's Collector project like telemetry does, and every
+ * call reaches it with the options `runTool` resolved from the verified
+ * subject; no argument names a project or a credential. Nothing here changes
+ * telemetry: an annotation points at a trace, span or session and leaves it
+ * as recorded, and the one delete operation removes only these objects.
+ *
+ * Demo mode has no Collector and therefore no such objects. A call there is
+ * refused rather than answered from an invented store.
+ */
+import { CollectorError, collectorDelete, collectorGet, collectorPatch, collectorPost, parseCollectorBody, parseCollectorPage, resolveMode, } from "./collector.js";
+import { createHash } from "node:crypto";
+import { IDEMPOTENCY_KEY_HEADER, IF_MATCH_HEADER } from "./contract-headers.js";
+import { contractSchema } from "./contract-validation.js";
+import { describeToolError } from "./request-scope.js";
+import { shortId } from "./summaries.js";
+import { redactTelemetry } from "./telemetry-redaction.js";
+const ANNOTATIONS_PATH = "/api/v1/annotations";
+const SAVED_QUERIES_PATH = "/api/v1/saved-queries";
+// The operations' own bodies. They are bound here rather than in
+// contract-validation.ts, which the dashboard and workbench bundles import.
+const AnnotationCreatedSchema = contractSchema("Operations.AnnotationsApi_create.Response.201");
+const AnnotationUpdatedSchema = contractSchema("Operations.AnnotationsApi_update.Response.200");
+const AnnotationsPageSchema = contractSchema("Operations.AnnotationsApi_list.Response.200");
+const SavedQueryCreatedSchema = contractSchema("Operations.SavedQueriesApi_create.Response.201");
+const SavedQueryUpdatedSchema = contractSchema("Operations.SavedQueriesApi_update.Response.200");
+const SavedQueriesPageSchema = contractSchema("Operations.SavedQueriesApi_list.Response.200");
+const SavedQueryRunSchema = contractSchema("Operations.SavedQueriesApi_run.Response.200");
+/** One page of the Collector's annotation listing per read-back. */
+const ANNOTATIONS_PER_READ = 100;
+/** Parallel annotation reads for one list_sessions page. */
+const SESSION_READ_CONCURRENCY = 8;
+/** Where each deletable kind lives on the Collector API. */
+const DELETE_PATHS = {
+    annotation: ANNOTATIONS_PATH,
+    saved_query: SAVED_QUERIES_PATH,
+};
+/** Refuses demo mode: its generated dataset has no project to keep these objects in. */
+async function requireLiveCollector(tool) {
+    if (await resolveMode() === "live")
+        return;
+    throw new CollectorError(`${tool} needs a live qyl Collector: annotations and saved queries are kept in a Collector ` +
+        "project, and demo mode (QYL_DEMO=1) has none. Set QYL_COLLECTOR_URL and unset QYL_DEMO.", false, undefined, "invalid_argument");
+}
+/**
+ * The If-Match value for a change. An etag is opaque, but it travels as an
+ * HTTP field value, so one that could not be sent is refused here instead of
+ * failing inside fetch as if the Collector were unreachable.
+ */
+function ifMatch(etag) {
+    if (!/^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/u.test(etag)) {
+        throw new CollectorError("etag is not a valid HTTP field value; pass the etag a qyl tool returned");
+    }
+    return { [IF_MATCH_HEADER]: etag };
+}
+/** JSON with object keys in one order at every depth, so equal bodies hash equal. */
+function canonicalJson(value) {
+    return JSON.stringify(value, (_key, item) => item !== null && typeof item === "object" && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0))
+        : item);
+}
+/**
+ * The retry key of a creating POST. A create's result can be lost after the
+ * Collector committed it (a timeout, a dropped connection), and the failure is
+ * reported retryable; the same intended create must then repeat the same key,
+ * so the Collector returns the first object instead of making a second one.
+ * The key is derived from the canonical body and the resolved project, never
+ * chosen by the model: an identical note on the same target within the
+ * Collector's 24-hour window is the same note.
+ */
+function idempotencyKey(body, options) {
+    const digest = createHash("sha256")
+        .update(`${options.access?.project ?? ""}\0${canonicalJson(body)}`)
+        .digest("hex");
+    return { [IDEMPOTENCY_KEY_HEADER]: digest };
+}
+function resourcePath(base, id, suffix = "") {
+    return `${base}/${encodeURIComponent(id)}${suffix}`;
+}
+/**
+ * Runs one Collector call and names its refusals for what the caller tried:
+ * a status listed in `messages` becomes that message, keeping the code the
+ * status decides (`not_found`, `conflict`, `precondition_failed`,
+ * `collector_unauthorized`). A body that breaks the contract stays a
+ * contract mismatch, and every other failure passes through unchanged.
+ */
+async function refusals(messages, request) {
+    try {
+        return await request();
+    }
+    catch (error) {
+        if (!(error instanceof CollectorError) || error.status === undefined || error.code === "contract_mismatch") {
+            throw error;
+        }
+        const message = messages[error.status];
+        if (message === undefined)
+            throw error;
+        throw new CollectorError(message, false, error.status);
+    }
+}
+/** The refusals every change to an existing object shares. */
+function changeRefusals(kind, id, role) {
+    return {
+        403: `the Collector refused the change: the server's Collector key needs the ${role} role`,
+        404: `${kind} not found: ${id}`,
+        412: `${kind} ${id} changed since that etag was read; read it again for its current etag`,
+    };
+}
+export async function createAnnotation(input, options) {
+    await requireLiveCollector("create_annotation");
+    // The create's 404 is its target: nothing by that id is recorded in this
+    // project, so there is nothing to attach the note to.
+    const create = { target: input.target, text: input.text };
+    const body = await refusals({
+        403: "the Collector refused the change: the server's Collector key needs the write role",
+        404: `${describeTarget(input.target)} is not recorded in this project`,
+    }, () => collectorPost(ANNOTATIONS_PATH, create, {
+        ...options,
+        headers: { ...options.headers, ...idempotencyKey(create, options) },
+    }));
+    return redactTelemetry(parseCollectorBody(body, `POST ${ANNOTATIONS_PATH}`, AnnotationCreatedSchema));
+}
+export async function updateAnnotation(input, options) {
+    await requireLiveCollector("update_annotation");
+    const path = resourcePath(ANNOTATIONS_PATH, input.id);
+    const body = await refusals(changeRefusals("annotation", input.id, "write"), () => collectorPatch(path, { text: input.text }, { ...options, headers: ifMatch(input.etag) }));
+    return redactTelemetry(parseCollectorBody(body, `PATCH ${path}`, AnnotationUpdatedSchema));
+}
+export async function createSavedQuery(input, options) {
+    await requireLiveCollector("create_saved_query");
+    const create = {
+        name: input.name,
+        ...(input.description === undefined ? {} : { description: input.description }),
+        filter: input.filter,
+    };
+    const body = await refusals({
+        403: "the Collector refused the change: the server's Collector key needs the write role",
+        409: `a saved query named "${input.name}" already exists in this project`,
+    }, () => collectorPost(SAVED_QUERIES_PATH, create, {
+        ...options,
+        headers: { ...options.headers, ...idempotencyKey(create, options) },
+    }));
+    return redactTelemetry(parseCollectorBody(body, `POST ${SAVED_QUERIES_PATH}`, SavedQueryCreatedSchema));
+}
+export async function updateSavedQuery(input, options) {
+    const { id, etag, ...changes } = input;
+    if (changes.name === undefined && changes.description === undefined && changes.filter === undefined) {
+        throw new CollectorError("update_saved_query changes nothing: pass a name, description or filter");
+    }
+    await requireLiveCollector("update_saved_query");
+    const path = resourcePath(SAVED_QUERIES_PATH, id);
+    const body = await refusals({
+        ...changeRefusals("saved query", id, "write"),
+        409: `a saved query named "${changes.name ?? ""}" already exists in this project`,
+    }, () => collectorPatch(path, changes, { ...options, headers: ifMatch(etag) }));
+    return redactTelemetry(parseCollectorBody(body, `PATCH ${path}`, SavedQueryUpdatedSchema));
+}
+export async function listSavedQueries(input, options) {
+    await requireLiveCollector("list_saved_queries");
+    const body = await collectorGet(SAVED_QUERIES_PATH, { signal: input.signal, limit: input.limit ?? 20, cursor: input.cursor }, options);
+    const page = parseCollectorPage(body, SAVED_QUERIES_PATH, SavedQueriesPageSchema, (item) => item);
+    return redactTelemetry({
+        savedQueries: page.items,
+        hasMore: page.hasMore,
+        ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+    });
+}
+export async function runSavedQuery(input, options) {
+    const { id, ...run } = input;
+    await requireLiveCollector("run_saved_query");
+    const path = resourcePath(SAVED_QUERIES_PATH, id, ":run");
+    const body = await refusals({ 404: `saved query not found: ${id}` }, () => collectorPost(path, run, options));
+    return redactTelemetry(parseCollectorBody(body, `POST ${path}`, SavedQueryRunSchema));
+}
+export async function deleteResource(kind, id, etag, options) {
+    await requireLiveCollector("delete");
+    const path = resourcePath(DELETE_PATHS[kind], id);
+    const body = await refusals(changeRefusals(kind === "annotation" ? "annotation" : "saved query", id, "delete"), () => collectorDelete(path, { ...options, headers: ifMatch(etag) }));
+    if (body !== undefined) {
+        throw new CollectorError(`collector contract mismatch for DELETE ${path}: expected 204 No Content`, false, undefined, "contract_mismatch");
+    }
+}
+/** The telemetry object an annotation names, in full. */
+export function describeTarget(target) {
+    switch (target.kind) {
+        case "trace":
+            return `trace ${target.trace_id}`;
+        case "span":
+            return `span ${target.span_id} of trace ${target.trace_id}`;
+        case "session":
+            return `session ${target.session_id}`;
+    }
+}
+function targetLabel(target) {
+    switch (target.kind) {
+        case "trace":
+            return `trace ${shortId(target.trace_id)}`;
+        case "span":
+            return `span ${target.span_id}`;
+        case "session":
+            return `session ${target.session_id}`;
+    }
+}
+/** One text line per annotation: what it is on, how to change it, and the note. */
+export function annotationLine(annotation) {
+    const note = annotation.text.replace(/\s+/gu, " ");
+    const text = note.length > 200 ? `${note.slice(0, 200)}…` : note;
+    return `- ${targetLabel(annotation.target)} · id ${annotation.id} · etag ${annotation.etag}: ${text}`;
+}
+/** The text block for a list of annotations, newest first. */
+export function summarizeAnnotations(annotations, truncated) {
+    if (annotations.length === 0)
+        return "\nAnnotations: none.";
+    return (`\nAnnotations (${annotations.length}, newest first${truncated ? `; the newest ${ANNOTATIONS_PER_READ} per object` : ""}):\n` +
+        annotations.map(annotationLine).join("\n"));
+}
+async function readAnnotationPage(params, options) {
+    const body = await collectorGet(ANNOTATIONS_PATH, { ...params, limit: ANNOTATIONS_PER_READ }, options);
+    const page = parseCollectorPage(body, ANNOTATIONS_PATH, AnnotationsPageSchema, (item) => item);
+    return { annotations: page.items, hasMore: page.hasMore };
+}
+/**
+ * An annotation read that fails leaves the telemetry result standing: the
+ * field is omitted and the text says why, instead of failing a trace read
+ * that succeeded or reporting "no annotations" that were never read.
+ */
+function unavailable(error) {
+    return { text: `\nAnnotations could not be read: ${describeToolError(error).message}` };
+}
+/** The annotations on one trace and its spans, for get_trace. */
+export async function readTraceAnnotations(traceId, scope) {
+    if (await resolveMode() === "demo") {
+        await scope.step("Demo data carries no annotations");
+        return { text: "" };
+    }
+    try {
+        const { annotations, hasMore } = await readAnnotationPage({ trace_id: traceId }, scope.collector);
+        await scope.step(`Read ${annotations.length} annotation(s) for trace ${traceId}`);
+        const safe = redactTelemetry(annotations);
+        return { annotations: safe, text: summarizeAnnotations(safe, hasMore) };
+    }
+    catch (error) {
+        await scope.step("Annotations unavailable");
+        return unavailable(error);
+    }
+}
+/** The annotations on the listed sessions, newest first, for list_sessions. */
+export async function readSessionAnnotations(sessionIds, scope) {
+    if (await resolveMode() === "demo") {
+        await scope.step("Demo data carries no annotations");
+        return { text: "" };
+    }
+    if (sessionIds.length === 0) {
+        await scope.step("No sessions to read annotations for");
+        return { annotations: [], text: "" };
+    }
+    try {
+        // One session's failed page costs that session's notes, not every session's.
+        const pages = [];
+        let failed = 0;
+        let firstFailure;
+        for (let start = 0; start < sessionIds.length; start += SESSION_READ_CONCURRENCY) {
+            const settled = await Promise.allSettled(sessionIds
+                .slice(start, start + SESSION_READ_CONCURRENCY)
+                .map((sessionId) => readAnnotationPage({ session_id: sessionId }, scope.collector)));
+            for (const outcome of settled) {
+                if (outcome.status === "fulfilled")
+                    pages.push(outcome.value);
+                else {
+                    failed += 1;
+                    firstFailure ??= outcome.reason;
+                }
+            }
+        }
+        if (pages.length === 0)
+            throw firstFailure;
+        const annotations = pages
+            .flatMap((page) => page.annotations)
+            .sort((left, right) => Date.parse(right.created_at) - Date.parse(left.created_at));
+        await scope.step(`Read ${annotations.length} annotation(s) for ${sessionIds.length} session(s)`);
+        const safe = redactTelemetry(annotations);
+        const partial = failed === 0
+            ? ""
+            : `\nAnnotations of ${failed} session(s) could not be read: ${describeToolError(firstFailure).message}`;
+        return { annotations: safe, text: summarizeAnnotations(safe, pages.some((page) => page.hasMore)) + partial };
+    }
+    catch (error) {
+        await scope.step("Annotations unavailable");
+        return unavailable(error);
+    }
+}
+//# sourceMappingURL=collector-resources.js.map

package/dist/collector-resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-resources.js","sourceRoot":"","sources":["../src/collector-resources.ts"],"names":[],"mappings":"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"}

package/dist/collector.d.ts

@@ -58,6 +58,11 @@ export interface CollectorRequestOptions {
     signal?: AbortSignal;
     /** Host-selected access for the verified caller; never a tool input. */
     access?: CollectorAccess;
+    /**
+     * Contract-named request headers one operation takes, such as `If-Match`.
+     * They never replace the credential or project headers.
+     */
+    headers?: Readonly<Record<string, string>>;
 }
 /**
  * Normalize endpoint items, then validate the complete operation-specific
@@ -69,8 +74,15 @@ export declare function parseCollectorPage<T, TPage extends {
     has_more: boolean;
     next_cursor?: string | null;
 }>(value: unknown, context: string, pageSchema: z.ZodType<TPage>, parseItem: (item: unknown, context: string) => T): ParsedCollectorPage<T>;
+/**
+ * Validate one whole response body against its generated operation schema,
+ * for the operations that answer with a single resource rather than a page.
+ */
+export declare function parseCollectorBody<T>(value: unknown, context: string, schema: z.ZodType<T>): T;
 /** Query values a published operation parameter can carry, repeatable included. */
 export type CollectorQueryParams = Record<string, string | number | boolean | readonly string[] | undefined>;
 export declare function collectorGet(pathname: string, params?: CollectorQueryParams, options?: CollectorRequestOptions): Promise<unknown>;
 export declare function collectorPost(pathname: string, body: unknown, options?: CollectorRequestOptions): Promise<unknown>;
+export declare function collectorPatch(pathname: string, body: unknown, options?: CollectorRequestOptions): Promise<unknown>;
+export declare function collectorDelete(pathname: string, options?: CollectorRequestOptions): Promise<unknown>;
 export declare function resolveMode(): Promise<Mode>;