@zackbart/connecta 0.25.0 → 0.26.0

package/dist/catalog-service.js

@@ -1,11 +1,12 @@
-import { Deferred, Effect, Exit, Result } from "effect";
+import { Effect, Result } from "effect";
 import { compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, typescriptSignature, } from "./catalog.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { SharedRead } from "./runtime/shared-read.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, } from "./timeout.js";
-import { isExplicitlyReadOnly } from "./tool-safety.js";
+import { isApprovalExempt, isExplicitlyReadOnly, NO_EXEMPTIONS, } from "./tool-safety.js";
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
@@ -202,12 +203,13 @@ export class CatalogService {
     searchRoute;
     readOptions;
     requestSignal;
-    // The request-scoped catalog cache: one Deferred per connector asked about,
-    // completed by the first asker's registry read and joined by every later
-    // one. A success stays for the rest of the request, so a search and the call
-    // after it see one catalog; a failure is dropped so the next ask reads
-    // again. The service lives and dies with one request, so no Deferred here is
-    // ever awaited from another.
+    approval;
+    // The request-scoped catalog cache: one shared read per connector asked
+    // about, started by the first asker and joined by every later one. A
+    // success stays for the rest of the request, so a search and the call after
+    // it see one catalog; a failure, or a read cancelled because every asker
+    // left it, is dropped so the next ask reads again. The service lives and
+    // dies with one request, so no read here is ever awaited from another.
     //
     // Registry.getTools also joins concurrent reads in one request scope, which
     // the operator UI and status reads rely on. This map overlaps it only for
@@ -218,6 +220,7 @@ export class CatalogService {
     constructor(registry, baseUrl, options = {}) {
         this.registry = registry;
         this.baseUrl = baseUrl;
+        this.approval = options.approval ?? NO_EXEMPTIONS;
         this.requestScope = options.requestScope ?? {};
         this.probeTimeoutMs =
             normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
@@ -256,28 +259,27 @@ export class CatalogService {
         return runEdge(this.catalog(id, callOptions));
     }
     // One connector's catalog from the request-scoped cache, reading it through
-    // the registry when this request has not yet. The first asker's options
-    // govern the read and a joiner shares its outcome, as the registry's own
-    // flight below does. The read settles the Deferred itself, not the asker's
-    // fiber, so a probe deadline ends one asker's wait and never the read.
+    // the registry when this request has not yet. No asker's options govern the
+    // read: it carries its own signal and the catalog deadline, the probe
+    // timeout, whichever asker starts it. Each asker waits under its own signal
+    // and deadline, so a short-deadline call that starts the read and a search
+    // that joins it each end on their own terms, and the read is cancelled only
+    // once every asker has gone (#571).
     catalog(id, callOptions) {
         return Effect.suspend(() => {
-            const cached = this.catalogs.get(id);
-            if (cached)
-                return Deferred.await(cached);
-            const read = Deferred.makeUnsafe();
-            this.catalogs.set(id, read);
-            // The executor turns a synchronous throw from getTools into a rejection.
-            new Promise((resolve) => resolve(this.registry.getTools(id, this.baseUrl, this.requestScope, callOptions, this.readOptions))).then((tools) => {
-                Deferred.doneUnsafe(read, Exit.succeed(tools));
-            }, (cause) => {
-                // Evicted before the Deferred resumes anyone, so an asker that
-                // retries on hearing of the failure starts a fresh read.
-                if (this.catalogs.get(id) === read)
-                    this.catalogs.delete(id);
-                Deferred.doneUnsafe(read, Exit.fail(cause));
-            });
-            return Deferred.await(read);
+            let read = this.catalogs.get(id);
+            if (!read) {
+                const started = new SharedRead((signal) => this.registry.getTools(id, this.baseUrl, this.requestScope, { signal, timeoutMs: this.probeTimeoutMs }, this.readOptions), (succeeded) => {
+                    // Evicted before the read resumes anyone, so an asker that
+                    // retries on hearing of the failure starts a fresh read.
+                    if (!succeeded && this.catalogs.get(id) === started) {
+                        this.catalogs.delete(id);
+                    }
+                });
+                this.catalogs.set(id, started);
+                read = started;
+            }
+            return read.join(callOptions.signal);
         });
     }
     // Every named catalog under its own probe deadline, `concurrency` at a time,
@@ -286,7 +288,7 @@ export class CatalogService {
     // A probe also ends with its request, so no listing outlives the caller
     // that asked for it.
     discoveryCatalogs(ids, route) {
-        return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => this.catalog(id, { signal, timeoutMs: this.probeTimeoutMs }), {
+        return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => this.catalog(id, { signal }), {
             ...(this.requestSignal ? { signal: this.requestSignal } : {}),
             timeoutMs: this.probeTimeoutMs,
             timeoutError: new Error(`${route} probe of "${id}" timed out after ${this.probeTimeoutMs}ms`),
@@ -536,6 +538,11 @@ export class CatalogService {
                     ...(match.tool.annotations
                         ? { annotations: match.tool.annotations }
                         : {}),
+                    // Config lets a program call this write without pausing (#566).
+                    // A marker, not a class: the tool stays approval-required.
+                    ...(isApprovalExempt(this.approval, match.connector, match.tool.name, match.tool)
+                        ? { approval: "exempt" }
+                        : {}),
                     ...(requiredReasons
                         ? {
                             guideRequired: true,
@@ -847,6 +854,9 @@ export class CatalogService {
                     : {}),
                 ...(output.source ? { outputSchemaSource: output.source } : {}),
                 ...(tool.annotations ? { annotations: tool.annotations } : {}),
+                ...(isApprovalExempt(this.approval, addressResolution.connector, tool.name, tool)
+                    ? { approval: "exempt" }
+                    : {}),
             };
         });
     }

package/dist/catalog.js

@@ -14,6 +14,12 @@ class SchemaWork {
     remaining = MAX_SCHEMA_WORK;
     truncated = false;
     refs = new Map();
+    /**
+     * Renderings whose top level is a bare `|` or `&`, recorded as the walk
+     * produces them. Compact carries raw keys and `//` prose, so unlike the
+     * TypeScript dialect its text cannot be rescanned for a top-level operator.
+     */
+    ungrouped = new Set();
     constructor(byteLimit = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
         this.byteLimit = byteLimit;
     }
@@ -435,8 +441,11 @@ function renderEnum(values, work, byteLimit, onTruncated) {
         const full = prefix.join(" | ");
         if (schemaEncoder.encode(full).length > limit)
             break;
-        if (index === values.length - 1)
+        if (index === values.length - 1) {
+            if (index > 0)
+                work.ungrouped.add(full);
             return full;
+        }
         const omitted = values.length - prefix.length;
         const candidate = `(${full} | ${marker(omitted)})`;
         if (schemaEncoder.encode(candidate).length <= limit)
@@ -582,6 +591,12 @@ function renderSchema(schema, defs, seen, depth, options) {
 function renderSchemaNode(schema, defs, seen, depth, options) {
     const ts = options.typescript === true;
     const group = ts ? groupedType : grouped;
+    const ungrouped = options.work.ungrouped;
+    // A `[]` suffix binds tighter than `|` and `&`, so an element rendered at
+    // operator level needs parentheses or it reads as its last member's array.
+    const element = (rendered) => ts
+        ? groupedType(rendered)
+        : ungrouped.has(rendered) ? `(${rendered})` : rendered;
     if (depth > 4) {
         if (!ts)
             return "…";
@@ -607,9 +622,17 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             : "unknown";
         return rendered === "unknown" ? rendered : `${rendered} | null`;
     }
-    const constrain = (rendered) => options.renderConstraints
-        ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-        : rendered;
+    const constrain = (rendered) => {
+        if (!options.renderConstraints)
+            return rendered;
+        const result = renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated);
+        // Constraints parenthesize a union before their comment but leave an
+        // intersection bare, and a comment does not group what precedes it.
+        if (ungrouped.has(rendered) && !result.startsWith(`(${rendered})`)) {
+            ungrouped.add(result);
+        }
+        return result;
+    };
     // Conditions cannot be expressed by a single static shape. Preserve the
     // base and send callers to the exact schema instead of hiding the rules.
     if (s.dependentSchemas !== undefined || s.if !== undefined ||
@@ -623,7 +646,10 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         const rendered = declaresShape(base)
             ? renderSchema(base, defs, seen, depth, options)
             : "unknown";
-        return `${rendered} /* conditional */`;
+        const result = `${rendered} /* conditional */`;
+        if (ungrouped.has(rendered))
+            ungrouped.add(result);
+        return result;
     }
     // allOf composes rather than replaces: it is checked before every other
     // shape keyword, and renders the schema's own shape alongside its members instead
@@ -653,7 +679,10 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         }
         if (parts.length === 0)
             return "unknown";
-        return parts.finish();
+        const rendered = parts.finish();
+        if (parts.length > 1)
+            ungrouped.add(rendered);
+        return rendered;
     }
     const reference = s.$ref ?? s.$dynamicRef;
     if (typeof reference === "string") {
@@ -693,6 +722,8 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             parts.add(renderSchema(member, defs, seen, depth + 1, options));
         }
         const rendered = parts.finish() || "unknown";
+        if (parts.length > 1)
+            ungrouped.add(rendered);
         return constrain(rendered);
     }
     if (Array.isArray(s.enum)) {
@@ -743,7 +774,7 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             const rest = s.items === undefined || s.items === true
                 ? "unknown"
                 : renderSchema(s.items, defs, seen, depth + 1, options);
-            parts.add(`...${group(rest)}[]`);
+            parts.add(`...${element(rest)}[]`);
         }
         return parts.finish();
     }
@@ -751,7 +782,7 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         const items = s.items
             ? renderSchema(s.items, defs, seen, depth + 1, options)
             : "unknown";
-        return ts ? `${groupedType(items)}[]` : `${items}[]`;
+        return `${element(items)}[]`;
     }
     if (type === "object" || s.properties) {
         const props = (s.properties ?? {});
@@ -809,6 +840,8 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             parts.add(options.work.text(String(item)));
         }
         const rendered = parts.finish();
+        if (parts.length > 1)
+            ungrouped.add(rendered);
         return constrain(rendered);
     }
     if (options.renderConstraints && constraintEntries(s).length > 0) {
@@ -959,6 +992,7 @@ function boundedCompactSchema(schema, description, typescript = false) {
         // are memoized only within each pass because their text includes constraints.
         if (error === schemaSizeExceeded && !description) {
             work.refs.clear();
+            work.ungrouped.clear();
             try {
                 return {
                     text: renderSchema(schema, schema, new Set(), 0, {

package/dist/connector-access.d.ts

@@ -9,20 +9,33 @@ export declare const POOL_NAME_RE: RegExp;
 /**
  * One derived view: which connectors, and for connectors granted by address
  * only, which tools. A connector absent from `toolAccess` is visible whole.
+ * `guardedToolAccess` is a subset of `toolAccess` checked against the loaded
+ * catalog each time tools are discovered or invoked.
  */
 export interface ConnectorAccess {
     connectorIds: "all" | readonly string[];
     toolAccess?: ToolAccess;
+    /** Exact tool grants that also require a current explicit read-only annotation. */
+    guardedToolAccess?: ToolAccess;
 }
+interface ReadOnlyToolGrant {
+    tool: string;
+    requireReadOnly: true;
+}
+export type ConnectorGrant = string | ReadOnlyToolGrant;
 /**
  * Normalize a grant list. A bare connector id grants every tool on that
  * connector; a `connector.tool` address grants one tool. Grants are additive,
  * so a bare id beside addresses for the same connector means the whole
- * connector. Anything else — an unknown shape, an empty tool name, a
- * non-string — throws, and the caller decides whether that is a construction
- * failure or a 403: a grant that cannot be parsed must never fail open.
+ * connector. Identity resolution can opt into `{ tool, requireReadOnly: true }`
+ * for a fixed address that also needs a current explicit read-only annotation;
+ * pool declarations remain strings. Anything else throws, and the caller
+ * decides whether that is a construction failure or a 403: a grant that
+ * cannot be parsed must never fail open.
  */
-export declare function parseConnectorAccess(value: unknown): ConnectorAccess;
+export declare function parseConnectorAccess(value: unknown, options?: {
+    allowReadOnly?: boolean;
+}): ConnectorAccess;
 /**
  * The view a pool endpoint serves: the pool's grants, never wider than the
  * identity's own. A connector or tool outside either side is gone; a
@@ -30,3 +43,4 @@ export declare function parseConnectorAccess(value: unknown): ConnectorAccess;
  * only narrow what the identity resolver already allowed.
  */
 export declare function intersectAccess(ceiling: ConnectorAccess, pool: ConnectorAccess): ConnectorAccess;
+export {};

package/dist/connector-access.js

@@ -12,38 +12,69 @@ const hasControlCharacter = (value) => [...value].some((ch) => {
  * Normalize a grant list. A bare connector id grants every tool on that
  * connector; a `connector.tool` address grants one tool. Grants are additive,
  * so a bare id beside addresses for the same connector means the whole
- * connector. Anything else — an unknown shape, an empty tool name, a
- * non-string — throws, and the caller decides whether that is a construction
- * failure or a 403: a grant that cannot be parsed must never fail open.
+ * connector. Identity resolution can opt into `{ tool, requireReadOnly: true }`
+ * for a fixed address that also needs a current explicit read-only annotation;
+ * pool declarations remain strings. Anything else throws, and the caller
+ * decides whether that is a construction failure or a 403: a grant that
+ * cannot be parsed must never fail open.
  */
-export function parseConnectorAccess(value) {
+export function parseConnectorAccess(value, options = {}) {
     if (value === "all")
         return { connectorIds: "all" };
     if (!Array.isArray(value))
         throw new Error("invalid connector permission");
     const whole = new Set();
-    const partial = new Map();
+    const plain = new Map();
+    const guarded = new Map();
     for (const entry of value) {
-        if (typeof entry !== "string")
-            throw new Error("invalid connector permission");
-        if (CONNECTOR_ID_RE.test(entry)) {
+        if (typeof entry === "string" && CONNECTOR_ID_RE.test(entry)) {
             whole.add(entry);
             continue;
         }
-        if (!TOOL_ADDRESS_RE.test(entry) || hasControlCharacter(entry))
+        const isGuarded = typeof entry !== "string";
+        if (isGuarded && (!options.allowReadOnly || entry === null ||
+            typeof entry !== "object" || Array.isArray(entry) ||
+            !Object.hasOwn(entry, "tool") || !Object.hasOwn(entry, "requireReadOnly") ||
+            Object.keys(entry).length !== 2 || entry.requireReadOnly !== true)) {
+            throw new Error("invalid connector permission");
+        }
+        const address = isGuarded ? entry.tool : entry;
+        if (typeof address !== "string" || !TOOL_ADDRESS_RE.test(address) || hasControlCharacter(address)) {
             throw new Error("invalid connector permission");
-        const dot = entry.indexOf(".");
-        const connectorId = entry.slice(0, dot);
-        const tools = partial.get(connectorId) ?? new Set();
-        tools.add(entry.slice(dot + 1));
-        partial.set(connectorId, tools);
+        }
+        const dot = address.indexOf(".");
+        const connectorId = address.slice(0, dot);
+        const target = isGuarded ? guarded : plain;
+        const tools = target.get(connectorId) ?? new Set();
+        tools.add(address.slice(dot + 1));
+        target.set(connectorId, tools);
+    }
+    for (const id of whole) {
+        plain.delete(id);
+        guarded.delete(id);
+    }
+    for (const [id, names] of plain) {
+        const restricted = guarded.get(id);
+        if (!restricted)
+            continue;
+        for (const name of names)
+            restricted.delete(name);
+        if (restricted.size === 0)
+            guarded.delete(id);
+    }
+    const partial = new Map(plain);
+    for (const [id, names] of guarded) {
+        const combined = partial.get(id) ?? new Set();
+        for (const name of names)
+            combined.add(name);
+        partial.set(id, combined);
     }
-    for (const id of whole)
-        partial.delete(id);
     const connectorIds = [...new Set([...whole, ...partial.keys()])];
-    return partial.size > 0
-        ? { connectorIds, toolAccess: partial }
-        : { connectorIds };
+    return {
+        connectorIds,
+        ...(partial.size > 0 ? { toolAccess: partial } : {}),
+        ...(guarded.size > 0 ? { guardedToolAccess: guarded } : {}),
+    };
 }
 /**
  * The view a pool endpoint serves: the pool's grants, never wider than the
@@ -59,6 +90,7 @@ export function intersectAccess(ceiling, pool) {
         : new Set(ceiling.connectorIds);
     const connectorIds = [];
     const toolAccess = new Map();
+    const guardedToolAccess = new Map();
     for (const id of pool.connectorIds) {
         if (allowedIds && !allowedIds.has(id))
             continue;
@@ -73,7 +105,20 @@ export function intersectAccess(ceiling, pool) {
         else if (fromPool ?? fromCeiling) {
             toolAccess.set(id, (fromPool ?? fromCeiling));
         }
+        const guarded = ceiling.guardedToolAccess?.get(id);
+        if (guarded) {
+            const allowed = toolAccess.get(id);
+            const retained = allowed
+                ? new Set([...guarded].filter((name) => allowed.has(name)))
+                : guarded;
+            if (retained.size > 0)
+                guardedToolAccess.set(id, retained);
+        }
         connectorIds.push(id);
     }
-    return toolAccess.size > 0 ? { connectorIds, toolAccess } : { connectorIds };
+    return {
+        connectorIds,
+        ...(toolAccess.size > 0 ? { toolAccess } : {}),
+        ...(guardedToolAccess.size > 0 ? { guardedToolAccess } : {}),
+    };
 }

package/dist/connector-caller.d.ts

@@ -0,0 +1,8 @@
+import type { AuthenticatedIdentity, ConnectorContext } from "./types.js";
+export interface ConnectorCaller {
+    identity: AuthenticatedIdentity;
+    /** The `/mcp/<pool>` the call arrived on, when it was a pool. */
+    pool?: string;
+}
+export declare function attachCaller(ctx: ConnectorContext, caller: ConnectorCaller | undefined): ConnectorContext;
+export declare function callerOf(ctx: ConnectorContext): ConnectorCaller | undefined;

package/dist/connector-caller.js

@@ -0,0 +1,19 @@
+// Who is calling, for the connectors connecta ships and nothing else.
+//
+// `ConnectorContext` deliberately carries no identity: a deployment's own
+// connector acts for the deployment, and one that could read its caller would
+// invite per-user behavior the access rules never saw. The built-in artifacts
+// connector is the exception — every version it writes records who wrote it —
+// so the identity rides beside the context, the way the OAuth sealer does,
+// where only in-repo code can read it. Core sets it from the authorization
+// that admitted the request, on the scoped registry view that request
+// receives; no argument, header, or program can name it.
+const callers = new WeakMap();
+export function attachCaller(ctx, caller) {
+    if (caller)
+        callers.set(ctx, caller);
+    return ctx;
+}
+export function callerOf(ctx) {
+    return callers.get(ctx);
+}

package/dist/connectors/remote-mcp.js

@@ -775,6 +775,7 @@ export function remoteMcp(id, opts) {
             // SDK v2 selects its validator by runtime export condition: AJV on
             // Node and @cfworker/json-schema under workerd. The Workers-safe path
             // no longer needs Connecta-specific wiring.
+            const handshakeAbort = new AbortController();
             const c = new Client({ name: "connecta", version: CONNECTA_VERSION }, {
                 versionNegotiation: {
                     mode: opts.versionNegotiation ?? "auto",
@@ -783,6 +784,19 @@ export function remoteMcp(id, opts) {
                 // below as one structured, non-retryable connector failure.
                 inputRequired: { autoFulfill: false },
             });
+            // @modelcontextprotocol/client 2.0.0 can attempt the legacy initialized
+            // notification after we close its transport. Its rejected Promise is
+            // unhandled under workerd even though connect() has a caller. This
+            // connection is already abandoned, so skip only that final handshake
+            // notification after our abort. Remove when the SDK owns this race:
+            // https://github.com/modelcontextprotocol/typescript-sdk/issues/2864
+            const notify = c.notification.bind(c);
+            c.notification = (message, options) => {
+                if (handshakeAbort.signal.aborted && message.method === "notifications/initialized") {
+                    return Promise.resolve();
+                }
+                return notify(message, options);
+            };
             const t = buildTransport(ctx, provider, credentialFramed);
             if (!owned()) {
                 detach(closeConnection(null, t, ctx.logger));
@@ -794,11 +808,11 @@ export function remoteMcp(id, opts) {
             // what aborts a connect still in flight.
             const lease = Scope.forkUnsafe(state.scope);
             const held = { client: null };
-            yield* Scope.addFinalizer(lease, Effect.suspend(() => closeConnection(held.client, t, ctx.logger)));
+            yield* Scope.addFinalizer(lease, Effect.sync(() => handshakeAbort.abort()).pipe(Effect.andThen(Effect.suspend(() => closeConnection(held.client, t, ctx.logger)))));
             state.lease = lease;
             state.transport = t;
             return yield* Effect.gen(function* () {
-                yield* promised(() => c.connect(t));
+                yield* promised(() => c.connect(t, { signal: handshakeAbort.signal }));
                 // A probe deadline can end its scope while connect is still in flight.
                 // The transport is closed immediately by closeScope; if connect wins
                 // that race anyway, close the resulting client rather than resurrecting

package/dist/errors.d.ts

@@ -15,7 +15,14 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited
  * code stays `connector_call_failed` or `auth_required` with a message that
  * states the ambiguity (H11).
  */
- | "not_found" | "input_required_unsupported" | "connector_call_failed";
+ | "not_found"
+/**
+ * The write named a base version or revision that is no longer current:
+ * someone else changed the thing first. The caller re-reads, reapplies its
+ * change, and retries with the base `current` reports — repeating the same
+ * call can never succeed, and waiting will not help either.
+ */
+ | "conflict" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {
     /** JSON Pointer into the submitted arguments; "/" means the root value. */
@@ -88,12 +95,18 @@ export declare class ConnectorCallError extends Error {
     readonly validation: ArgumentValidationDetails | undefined;
     /** Sanitized transport diagnostics for `unavailable` only. */
     readonly details: UnavailableDetails | undefined;
+    /**
+     * For `conflict` only: where each thing the write touched stands now, e.g.
+     * `{ revision: 12, view: 7 }`. Bounded to 20 whole-number entries.
+     */
+    readonly current: Readonly<Record<string, number>> | undefined;
     constructor(code: ConnectorCallErrorCode, message: string, opts?: {
         retryable?: boolean;
         retryAfterMs?: number;
         cause?: unknown;
         validation?: ArgumentValidationDetails;
         details?: UnavailableDetails;
+        current?: Readonly<Record<string, number>>;
     });
 }
 /** The `error` object surfaced in value-mode call results and rejected promises. */
@@ -107,6 +120,8 @@ export interface CallErrorDetails {
     retryAfterMs?: number;
     /** Bounded input-schema findings; paths and expectations, never values. */
     validation?: ArgumentValidationDetails;
+    /** On a `conflict`: where each thing the write touched stands now. */
+    current?: Readonly<Record<string, number>>;
     /** Connector whose failed operation needs recovery. */
     connector?: string;
     /** Canonical downstream address the agent may retry after recovery. */

package/dist/errors.js

@@ -162,9 +162,30 @@ const RETRYABLE_BY_CODE = {
     auth_required: false,
     invalid_args: false,
     not_found: false,
+    conflict: false,
     input_required_unsupported: false,
     connector_call_failed: false,
 };
+/** Entries a conflict's `current` map may carry. */
+const MAX_CURRENT_ENTRIES = 20;
+const MAX_CURRENT_KEY_CHARS = 128;
+/**
+ * Where each thing a conflicting write touched stands now: short names to
+ * whole non-negative numbers, at most 20 of them. Anything else is dropped
+ * whole rather than clipped, because a truncated key names a different thing.
+ */
+function boundedCurrent(current) {
+    if (!current || typeof current !== "object")
+        return undefined;
+    const entries = Object.entries(current).filter(([key, value]) => key.length > 0 &&
+        key.length <= MAX_CURRENT_KEY_CHARS &&
+        key !== "__proto__" &&
+        Number.isSafeInteger(value) &&
+        value >= 0);
+    if (entries.length === 0)
+        return undefined;
+    return Object.freeze(Object.fromEntries(entries.slice(0, MAX_CURRENT_ENTRIES)));
+}
 /** Non-negative integer milliseconds, or undefined for anything else. */
 function normalizeRetryAfterMs(value) {
     if (value === undefined)
@@ -201,6 +222,11 @@ export class ConnectorCallError extends Error {
     validation;
     /** Sanitized transport diagnostics for `unavailable` only. */
     details;
+    /**
+     * For `conflict` only: where each thing the write touched stands now, e.g.
+     * `{ revision: 12, view: 7 }`. Bounded to 20 whole-number entries.
+     */
+    current;
     constructor(code, message, opts = {}) {
         super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
         this.name = "ConnectorCallError";
@@ -211,6 +237,7 @@ export class ConnectorCallError extends Error {
             code === "unavailable" ? sanitizedUnavailableDetails(opts.details) : undefined;
         this.validation =
             code === "invalid_args" ? boundedValidation(opts.validation) : undefined;
+        this.current = code === "conflict" ? boundedCurrent(opts.current) : undefined;
     }
 }
 /**
@@ -262,6 +289,7 @@ export function classifyCallError(err, fallbackCode = "connector_call_failed") {
                 : {}),
             ...(err.validation ? { validation: err.validation } : {}),
             ...(err.details ? { details: err.details } : {}),
+            ...(err.current ? { current: err.current } : {}),
         };
     }
     // An aborted fetch rejects with a DOMException named "AbortError" whose