@rockhopper-co/mcp-server 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -4,9 +4,87 @@ All notable changes to this project are documented here. Follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] — 2026-08-10
+
+**No code changed between `0.10.0` and `1.0.0`.** This release exists to fix a
+versioning trap, and states a compatibility promise that was already true.
+
+### Why 1.0.0
+
+On a `0.x` version npm reads a caret range as **minor-locked**: `^0.9.0` means
+`>=0.9.0 <0.10.0`, not `<1.0.0`. Nobody reads it that way. It cost two releases
+— `mcp-gateway` sat on `^0.9.0` and could not receive `0.10.0`, the very release
+it was waiting for, and before that on the same coupling one release earlier
+(ENG-2165, ENG-2233). At `1.x` a caret finally means "any compatible version".
+
+### The compatibility promise
+
+From `1.0.0`, a breaking change to any of the following requires a major bump:
+
+- **Tool names and their input schemas.** These are the load-bearing ones. The
+  schemas are runtime `zod` validators that execute **on the caller's machine**,
+  before any request is sent, so narrowing one breaks that caller no matter how
+  compatible the backend is. Widening a schema is not breaking; narrowing it is.
+- **Resource URIs and templates**, and the prompts the server registers.
+- **The CLI's flags and its stdio contract.**
+
+Explicitly **not** covered, and free to change in a minor: internal modules, the
+`dist/` layout, anything reachable only by deep-importing a path this package
+does not document, and log output.
+
+### Note for consumers
+
+Move a `^0.x` range to `^1.0.0`. A `0.x` range will not pick this up.
+
 ## [Unreleased]
 
 ### Added
+- **User and team ids are accepted as uuids (ENG-2230).** `reviewerIds` on
+  `create_review_request` and `{teamId}` in `rockhopper://teams/{teamId}` now
+  take either the version-7 uuid or the legacy numeric internal id, mixed
+  freely. Rockhopper re-keyed `user`, `team` and `workspace` onto uuids
+  (ENG-1966); until this release the published tool schema validated
+  `reviewerIds` as `z.array(z.number().int().positive())`, so a uuid was
+  refused **on your machine** before any request was sent — every version from
+  0.2.0 through 0.10.0 is affected, and no server-side change could fix it.
+  `UserSummary`, `Team` and `Workspace` gained the optional `id` (uuid) field
+  the API already returns, and `ApiClient.getTeam()` /
+  `ApiClient.createReviewRequest()` widened from `number` to `number | string`
+  (exported as the new `RockhopperId` type).
+
+  **Nothing that works today stops working.** The numeric form is accepted
+  until **2027-09-14** and removed after that date; migrate to the uuid before
+  then. Version, comment and review ids are unaffected and stay numeric.
+
+- **Strict no-partial change history (`src/not-ready.ts`).** `get_cell_history`,
+  `search` and the `changes` resource refuse to answer while a file's change
+  history is still being built, instead of returning the fraction that happens
+  to be ready. Callers get an explicit not-ready answer they can retry.
+
+### Fixed
+- **The server announced version `0.1.0` to every client, at every release
+  (ENG-1955).** `createServer` passed a string literal to `McpServer`, so the
+  version in the MCP `initialize` response was `0.1.0` — unchanged since the
+  initial commit, so every published version (0.2.0 through 0.8.0) announced
+  itself as 0.1.0, both for the locally installed server and for every web
+  client reaching the same tools through `mcp-gateway`. It now reports
+  `package.json`'s version, which is what makes two builds distinguishable
+  at all.
+
+### Added
+- **Provenance-context emit on agent writes (ENG-1756 / decision 15).** Every
+  write call (`POST`/`PUT`/`PATCH`/`DELETE`) now carries
+  `X-Rockhopper-Surface` (`mcp`), a stable per-client-instance
+  `X-Rockhopper-Session-Id`, and — once the driving human is known —
+  `X-Driving-Human`. The CLI declares the PAT owner as the driving human from
+  its existing `/users/me` preflight. Reads are unchanged (no headers).
+  This satisfies the backend's decision-15 accountability invariant, which
+  rejects (403) an agent-surface write with no resolvable driving human, and
+  populates the `cell_change_provenance_context` sidecar for etymology reads.
+  New public API: `ApiClient` config `provenanceContext` +
+  `ApiClient.setDrivingHuman()` (used by `mcp-gateway` to declare the
+  `gateway` surface and its OAuth session id).
+
 - **Local rotating diagnostic logfile (KI-225).** The server now writes a
   local diagnostic log to `~/.rockhopper/mcp-server/` (rotated via
   `pino-roll`, ~5 MB × 5 files). It captures request latency plus the

package/README.md

@@ -183,6 +183,14 @@ npm run generate:postman
 | `cancel_review` | Cancel a pending review request (requester only) |
 | `update_file_description` | Update the display name of an enrolled file |
 
+## Identifiers
+
+Users and teams are named by a **uuid** (`id`) — for example `0198f3a1-2b4c-7d8e-9f01-23456789abcd`. This is the identifier to send as a `reviewerIds` entry on `create_review_request`, and as `{teamId}` in `rockhopper://teams/{teamId}`. Read it from the team resource, where every record carries both an `id` (uuid) and an `internalId` (number).
+
+The legacy numeric `internalId` is **also accepted** for users and teams, and the two spellings can be mixed in one `reviewerIds` array — nothing you have written today stops working. It is accepted until **2027-09-14** and removed after, so migrate to the uuid before then.
+
+Everything else keeps its existing type: `fileMsId` is a string, and version and comment ids stay numeric.
+
 ## Development
 
 ```bash

package/dist/api-client.d.ts

@@ -1,4 +1,4 @@
-import type { CellHistoryEntry, EnrolledFile, FileChat, FileVersion, PaginatedUnattributedResponse, ReviewActivity, ReviewRequest, Team, UnattributedChange, UserSummary } from './types.js';
+import type { CellHistoryEntry, EnrolledFile, FileChat, FileVersion, FoldStatus, PaginatedUnattributedResponse, ReviewActivity, ReviewRequest, RockhopperId, Team, UnattributedChange, UserSummary } from './types.js';
 export interface ApiClientConfig {
     baseUrl: string;
     token: string;
@@ -12,12 +12,53 @@ export interface ApiClientConfig {
      * a freshly minted UUID v4.
      */
     correlationId?: string;
+    /**
+     * ENG-1756 (plan §9 decision 15) — provenance-context EMIT config. Every
+     * WRITE call carries `X-Rockhopper-Surface` + `X-Rockhopper-Session-Id`
+     * (and `X-Driving-Human` once known) so the backend's decision-15
+     * admission never 403s a well-behaved agent client and the capture
+     * sidecar (`cell_change_provenance_context`) gets its surface/session.
+     * Defaults: surface `'mcp'`, a per-client-instance UUID session id, no
+     * driving human until {@link ApiClient.setDrivingHuman} is called (the
+     * backend then falls back to the PAT owner — the same human).
+     */
+    provenanceContext?: {
+        /** `'mcp'` (local server, default) | `'gateway'` (remote gateway). */
+        surface?: string;
+        /** Session correlation id for the sidecar; default: per-instance UUID. */
+        sessionId?: string;
+        /** Platform id (msId/googleId) of the human driving this agent. */
+        drivingHumanPlatformId?: string;
+    };
+}
+/**
+ * A non-OK HTTP answer, carrying its status so callers can tell a DEFINITIVE
+ * rejection (404 the file is not there, 403 no access) from an ambiguous one
+ * (5xx, transport). The strict no-partial gate needs that distinction: failing
+ * closed on an ambiguous probe is right, but reporting "retry later" for a file
+ * that does not exist would be a fabricated capacity signal. Message text is
+ * unchanged from the previous plain `Error` — callers render it verbatim.
+ */
+export declare class RockhopperApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
 }
 export declare class ApiClient {
     private readonly baseUrl;
     private readonly token;
     private readonly correlationId?;
+    private readonly surface;
+    private readonly sessionId;
+    private drivingHumanPlatformId;
     constructor(config: ApiClientConfig);
+    /**
+     * ENG-1756: declare (or clear) the human driving this agent. The CLI sets
+     * it from the `/users/me` preflight (`msId`/`googleId` — the PAT owner);
+     * subsequent writes then carry `X-Driving-Human`. While unset, the backend
+     * resolves the driving human as the PAT owner server-side, so writes keep
+     * working — this header is the explicit, forward-compatible form.
+     */
+    setDrivingHuman(platformId: string | null): void;
     /**
      * KI-096: optional `responseSchema` validates the response shape with
      * zod. When supplied, drift between backend's actual response and the
@@ -28,7 +69,13 @@ export declare class ApiClient {
      */
     private request;
     getMe(): Promise<UserSummary>;
-    getTeam(teamId: number): Promise<Team>;
+    /**
+     * ENG-2230 — `teamId` is either spelling: the version-7 uuid or the legacy
+     * numeric internal id. Both are interpolated into the path unchanged and
+     * both name the same row (backend #1717). Widened from `number`, so no
+     * existing caller changes.
+     */
+    getTeam(teamId: RockhopperId): Promise<Team>;
     listEnrolledFiles(params?: {
         search?: string;
         matchIn?: 'name' | 'comments' | 'versions' | 'all';
@@ -36,6 +83,13 @@ export declare class ApiClient {
     getEnrolledFile(fileMsId: string): Promise<EnrolledFile>;
     getFileVersions(fileMsId: string): Promise<FileVersion[]>;
     getFileVersion(versionInternalId: number): Promise<FileVersion>;
+    /**
+     * Plan 02 ruling 5 — the completeness probe for every change-history
+     * surface. `foldPending: true` means a commit-diff fold is queued, retrying
+     * or running, i.e. the change-log window is mid-rewrite: incomplete.
+     * Consumed by `assertChangeHistoryComplete`, never rendered to the user.
+     */
+    getFoldStatus(fileMsId: string): Promise<FoldStatus>;
     /**
      * KI-096: passes `?format=mcp` to opt into the backend's normalized
      * projection `{versionId, value, changedBy, changedAt}` (added by
@@ -43,6 +97,14 @@ export declare class ApiClient {
      * row shape the frontend cell-history popover consumes — we never
      * call that path. Zod-parses the response so future drift between
      * backend and mcp-server contracts fails loudly.
+     *
+     * ENG-1638 (P3-2) remainder: the backend now routes this read through the
+     * SAME ledger read-decision choke point as the webapp/add-in popovers
+     * (cross-surface parity). An eligible file serves the WIDENED entries
+     * (+ formula, provenance, actorKind, drivingHuman, formatted — including
+     * live events with versionId 'uncommitted'); a not-eligible file, a Google
+     * file, or an older backend serves the four-field legacy projection. The
+     * schema accepts both.
      */
     getCellHistory(fileMsId: string, sheetName: string, cellAddress: string): Promise<CellHistoryEntry[]>;
     getFileComments(fileMsId: string): Promise<FileChat[]>;
@@ -70,11 +132,18 @@ export declare class ApiClient {
     getReviewsForLatestVersion(fileMsId: string): Promise<ReviewRequest[]>;
     getReview(reviewId: number): Promise<ReviewRequest>;
     getReviewActivities(reviewId: number): Promise<ReviewActivity[]>;
+    /**
+     * ENG-2230 — `reviewerIds` accepts either spelling of a user id (uuid or
+     * legacy numeric internal id), mixed freely. Values are serialised
+     * verbatim; the backend resolves both (`@AcceptsResourceId({ reviewerIds:
+     * 'user' })` on `POST|PUT /reviews/requests`). `versionId` is a FILE
+     * VERSION id and is NOT re-keyed — it stays numeric.
+     */
     createReviewRequest(body: {
         versionId: number;
         subject: string;
         description?: string;
-        reviewerIds: number[];
+        reviewerIds: RockhopperId[];
     }): Promise<ReviewRequest>;
     approveReview(reviewId: number, body: {
         notes?: string;

package/dist/api-client.d.ts.map

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

package/dist/api-client.js

@@ -1,15 +1,67 @@
 import { randomUUID } from 'node:crypto';
 import { getCorrelationId } from './correlation.js';
 import { log } from './logger.js';
-import { CellHistoryEntryArraySchema, EnrolledFileSchema, FileChatSchema, } from './zod-schemas.js';
+import { CellHistoryEntryArraySchema, EnrolledFileSchema, FileChatSchema, FoldStatusSchema, } from './zod-schemas.js';
+import { ChangeHistoryNotReadyError, DEFAULT_RETRY_AFTER_SECONDS, } from './not-ready.js';
+/**
+ * Plan 02 ruling 5 — the poll hint comes from the SERVER's `Retry-After`
+ * (the produce ETA), never from a local guess. A missing/garbage header falls
+ * back to the shared default rather than inventing a shorter interval: a hint
+ * that is too short turns one waiting client into the herd the parser lease
+ * exists to prevent (SP02 adversarial S6).
+ */
+function parseRetryAfterSeconds(response) {
+    const raw = response.headers?.get('Retry-After');
+    if (!raw)
+        return DEFAULT_RETRY_AFTER_SECONDS;
+    const seconds = Number.parseInt(raw, 10);
+    return Number.isFinite(seconds) && seconds > 0
+        ? seconds
+        : DEFAULT_RETRY_AFTER_SECONDS;
+}
+/**
+ * A non-OK HTTP answer, carrying its status so callers can tell a DEFINITIVE
+ * rejection (404 the file is not there, 403 no access) from an ambiguous one
+ * (5xx, transport). The strict no-partial gate needs that distinction: failing
+ * closed on an ambiguous probe is right, but reporting "retry later" for a file
+ * that does not exist would be a fabricated capacity signal. Message text is
+ * unchanged from the previous plain `Error` — callers render it verbatim.
+ */
+export class RockhopperApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'RockhopperApiError';
+        this.status = status;
+    }
+}
+/** HTTP methods the decision-15 admission treats as agent writes. */
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 export class ApiClient {
     baseUrl;
     token;
     correlationId;
+    surface;
+    sessionId;
+    drivingHumanPlatformId;
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.token = config.token;
         this.correlationId = config.correlationId;
+        this.surface = config.provenanceContext?.surface ?? 'mcp';
+        this.sessionId = config.provenanceContext?.sessionId ?? randomUUID();
+        this.drivingHumanPlatformId =
+            config.provenanceContext?.drivingHumanPlatformId ?? null;
+    }
+    /**
+     * ENG-1756: declare (or clear) the human driving this agent. The CLI sets
+     * it from the `/users/me` preflight (`msId`/`googleId` — the PAT owner);
+     * subsequent writes then carry `X-Driving-Human`. While unset, the backend
+     * resolves the driving human as the PAT owner server-side, so writes keep
+     * working — this header is the explicit, forward-compatible form.
+     */
+    setDrivingHuman(platformId) {
+        this.drivingHumanPlatformId = platformId;
     }
     /**
      * KI-096: optional `responseSchema` validates the response shape with
@@ -39,6 +91,20 @@ export class ApiClient {
                     // id can't be dropped. Precedence: per-call > config > ALS > mint.
                     // Non-sensitive UUID — never co-logged with the bearer token above.
                     'X-Correlation-Id': this.correlationId ?? getCorrelationId() ?? randomUUID(),
+                    // ENG-1756 (decision 15): agent writes carry the provenance
+                    // context so the backend's anonymous-agent-write admission never
+                    // fires for this well-behaved client and the capture sidecar gets
+                    // its surface/session. Reads carry none (no admission on reads).
+                    // Placed before the spread so a per-call header still wins.
+                    ...(WRITE_METHODS.has(method)
+                        ? {
+                            'X-Rockhopper-Surface': this.surface,
+                            'X-Rockhopper-Session-Id': this.sessionId,
+                            ...(this.drivingHumanPlatformId
+                                ? { 'X-Driving-Human': this.drivingHumanPlatformId }
+                                : {}),
+                        }
+                        : {}),
                     ...init?.headers,
                 },
             });
@@ -53,9 +119,18 @@ export class ApiClient {
         if (!response.ok) {
             // KI-225: classify auth rejections (401/403) so they're greppable
             // separately from generic HTTP errors.
+            // Plan 02 ruling 5: 429/503 on a read lane is the backend's "outputs
+            // still producing" answer (SP02 maps the typed not-ready to 429 +
+            // Retry-After). It must NOT reach a formatter as a generic error string —
+            // an assistant reading `Rockhopper API 429: …` has no reliable way to
+            // tell a capacity signal from a real failure, and either way it is not
+            // data. Classified here, at the one place every call passes through.
+            const notReady = response.status === 429 || response.status === 503;
             const classification = response.status === 401 || response.status === 403
                 ? 'auth_failed'
-                : 'http_error';
+                : notReady
+                    ? 'not_ready'
+                    : 'http_error';
             log.warn({
                 event: 'api_request_failed',
                 method,
@@ -65,7 +140,14 @@ export class ApiClient {
                 classification,
             }, 'api_request_failed');
             const body = await response.text().catch(() => '');
-            throw new Error(`Rockhopper API ${response.status}: ${response.statusText} — ${body}`);
+            if (notReady) {
+                throw new ChangeHistoryNotReadyError({
+                    reason: 'still_producing',
+                    retryAfterSeconds: parseRetryAfterSeconds(response),
+                    detail: `${response.status} ${response.statusText} at ${pathname}`,
+                });
+            }
+            throw new RockhopperApiError(response.status, `Rockhopper API ${response.status}: ${response.statusText} — ${body}`);
         }
         log.info({ event: 'api_request', method, path: pathname, status: response.status, durationMs }, 'api_request');
         const json = await response.json();
@@ -98,6 +180,12 @@ export class ApiClient {
         return this.request('/users/me');
     }
     // --- Teams ---
+    /**
+     * ENG-2230 — `teamId` is either spelling: the version-7 uuid or the legacy
+     * numeric internal id. Both are interpolated into the path unchanged and
+     * both name the same row (backend #1717). Widened from `number`, so no
+     * existing caller changes.
+     */
     async getTeam(teamId) {
         return this.request(`/teams/${teamId}`);
     }
@@ -121,6 +209,15 @@ export class ApiClient {
     async getFileVersion(versionInternalId) {
         return this.request(`/file-versions/file/version/${versionInternalId}`);
     }
+    /**
+     * Plan 02 ruling 5 — the completeness probe for every change-history
+     * surface. `foldPending: true` means a commit-diff fold is queued, retrying
+     * or running, i.e. the change-log window is mid-rewrite: incomplete.
+     * Consumed by `assertChangeHistoryComplete`, never rendered to the user.
+     */
+    async getFoldStatus(fileMsId) {
+        return this.request(`/file-versions/file/${fileMsId}/fold-status`, undefined, FoldStatusSchema);
+    }
     /**
      * KI-096: passes `?format=mcp` to opt into the backend's normalized
      * projection `{versionId, value, changedBy, changedAt}` (added by
@@ -128,6 +225,14 @@ export class ApiClient {
      * row shape the frontend cell-history popover consumes — we never
      * call that path. Zod-parses the response so future drift between
      * backend and mcp-server contracts fails loudly.
+     *
+     * ENG-1638 (P3-2) remainder: the backend now routes this read through the
+     * SAME ledger read-decision choke point as the webapp/add-in popovers
+     * (cross-surface parity). An eligible file serves the WIDENED entries
+     * (+ formula, provenance, actorKind, drivingHuman, formatted — including
+     * live events with versionId 'uncommitted'); a not-eligible file, a Google
+     * file, or an older backend serves the four-field legacy projection. The
+     * schema accepts both.
      */
     async getCellHistory(fileMsId, sheetName, cellAddress) {
         const query = new URLSearchParams({
@@ -183,6 +288,13 @@ export class ApiClient {
     async getReviewActivities(reviewId) {
         return this.request(`/reviews/requests/${reviewId}/activities`);
     }
+    /**
+     * ENG-2230 — `reviewerIds` accepts either spelling of a user id (uuid or
+     * legacy numeric internal id), mixed freely. Values are serialised
+     * verbatim; the backend resolves both (`@AcceptsResourceId({ reviewerIds:
+     * 'user' })` on `POST|PUT /reviews/requests`). `versionId` is a FILE
+     * VERSION id and is NOT re-keyed — it stays numeric.
+     */
     async createReviewRequest(body) {
         return this.request('/reviews/requests', {
             method: 'POST',

package/dist/api-client.js.map

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

package/dist/cli.js

@@ -64,7 +64,13 @@ const apiClient = new ApiClient({
     token: resolved.accessToken,
 });
 try {
-    await apiClient.getMe();
+    const me = await apiClient.getMe();
+    // ENG-1756 (plan §9 decision 15): the PAT owner IS the human driving this
+    // local agent — reuse the preflight to declare them, so every write carries
+    // `X-Driving-Human` and the backend's anonymous-agent-write admission
+    // never fires for this client. Best-effort: while unset, the backend
+    // resolves the PAT owner server-side (same human).
+    apiClient.setDrivingHuman(me?.msId ?? me?.googleId ?? null);
 }
 catch (err) {
     const msg = err instanceof Error ? err.message : String(err);

package/dist/cli.js.map

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

package/dist/not-ready.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Plan 02 ruling 5 (David, 2026-08-04) — STRICT no-partial, on the machine
+ * surfaces.
+ *
+ * The rule David landed is "nothing serves change history until it is
+ * complete", and he chose STRICT specifically because THIS server is a
+ * consumer: rows leave here for Claude Desktop / Cursor, which get no banner,
+ * no colour and no human in the loop, and will narrate whatever arrives as
+ * fact. An empty list is the dangerous answer — "there are no changes" is a
+ * factual claim, and it is the claim an assistant makes when handed zero rows.
+ *
+ * So a not-ready answer here is a REFUSAL, not a value: `isError: true`, a
+ * shouting marker, an explicit "this is not an empty result", and a JSON
+ * object an assistant can branch on. A resource or prompt THROWS for the same
+ * reason a tool cannot return rows — a protocol error cannot be summarised as
+ * data.
+ *
+ * Vocabulary is deliberately the backend's, not a second one: the reasons
+ * mirror the SP02 `ParsedOutputNotReadyReason` family
+ * (`backend/src/common/parsed-output/parsed-output-not-ready.error.ts`), and
+ * `isNotReady` matches both the typed error and a wrapper carrying it as
+ * `cause`, exactly like the backend's `isParsedOutputNotReady`.
+ */
+/** Why a change-history answer is being refused. */
+export type NotReadyReason = 
+/** A commit-diff fold is still rewriting this file's change-log window. */
+'change_history_incomplete'
+/** The backend answered 429/503: parsed outputs are still being produced. */
+ | 'still_producing'
+/**
+ * The completeness probe itself could not answer. Fail CLOSED: under STRICT
+ * an unknown completeness state is not permission to serve rows. This is the
+ * one reason that is NOT a statement about the file.
+ */
+ | 'completeness_unknown';
+/** Grep marker; also the first token of every refusal an assistant sees. */
+export declare const NOT_READY_MARKER = "CHANGE_HISTORY_NOT_READY";
+/** Poll hint when the backend gave none — mirrors the backend's own default. */
+export declare const DEFAULT_RETRY_AFTER_SECONDS = 15;
+export declare class ChangeHistoryNotReadyError extends Error {
+    /** Structural marker, so a wrapper can be recognised without importing. */
+    readonly notReady: true;
+    readonly reason: NotReadyReason;
+    readonly retryAfterSeconds: number;
+    readonly fileMsId: string | null;
+    constructor(ctx: {
+        reason: NotReadyReason;
+        retryAfterSeconds?: number | null;
+        fileMsId?: string | null;
+        detail?: string;
+    });
+}
+/** Matches the typed error AND any error carrying one as `cause`. */
+export declare function isNotReady(err: unknown): err is ChangeHistoryNotReadyError;
+export interface NotReadyToolResult {
+    /** The SDK's `CallToolResult` carries an index signature; mirror it so this
+     * shape is assignable to a tool handler's return type. */
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError: true;
+}
+/**
+ * The tool answer for a refusal. Three defences, because one is not enough
+ * against a model that wants to be helpful: `isError`, prose that names the
+ * wrong inference explicitly, and a JSON object to branch on.
+ */
+export declare function notReadyToolResult(err: unknown): NotReadyToolResult;
+/** The completeness probe this module needs from the API client. */
+export interface CompletenessProbe {
+    getFoldStatus(fileMsId: string): Promise<{
+        foldPending: boolean;
+        foldTargetVersionId: number | null;
+    }>;
+}
+/**
+ * Throws {@link ChangeHistoryNotReadyError} unless the file's change history is
+ * complete.
+ *
+ * `foldPending` is the backend's own authoritative queue read
+ * (`GET /file-versions/file/:fileMsId/fold-status`, KI-1399) — while it is
+ * true a commit-diff fold is queued, retrying or running, and the change-log
+ * window is mid-rewrite. That is precisely the incomplete state, and after
+ * plan 02's write-path decoupling (David Q3, 2026-08-03: save the version row
+ * first, defer the fold) it is the NORMAL state immediately after any write.
+ *
+ * A probe that cannot answer refuses. The backend's own probe fails OPEN to
+ * not-pending on purpose — a UI lock that can hang is worse than a stale row —
+ * but that trade does not transfer here: for a machine consumer a wrong
+ * "complete" is a fabricated fact, so the client-side default is the opposite.
+ */
+export declare function assertChangeHistoryComplete(api: CompletenessProbe, fileMsId: string): Promise<void>;
+//# sourceMappingURL=not-ready.d.ts.map

package/dist/not-ready.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-ready.d.ts","sourceRoot":"","sources":["../src/not-ready.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,oDAAoD;AACpD,MAAM,MAAM,cAAc;AACxB,2EAA2E;AACzE,2BAA2B;AAC7B,6EAA6E;GAC3E,iBAAiB;AACnB;;;;GAIG;GACD,sBAAsB,CAAC;AAE3B,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AAE3D,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAG,IAAI,CAAU;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;gBAErB,GAAG,EAAE;QACf,MAAM,EAAE,cAAc,CAAC;QACvB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;CAeF;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,0BAA0B,CAI1E;AAyBD,MAAM,WAAW,kBAAkB;IACjC;8DAC0D;IAC1D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAwBnE;AAED,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QACvC,WAAW,EAAE,OAAO,CAAC;QACrB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;KACpC,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA4Bf"}