@onlyworlds/sdk 4.25.0 → 4.27.0

package/AGENTS.md

@@ -89,6 +89,12 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   body that carries it has it dropped, never an error. A **contributor** can change only what
   they created: anything else is 403 `not_author` (`err.isNotAuthor`; retrying will not help).
   `/bulk` reports it per slot, not as a throw.
+- **If you are an agent, say so** (since 4.26.0): `new OwV2Client({ ..., agent: true })` sends
+  `X-OW-Agent` on every element write, and keel records those writes as agent-made. Every element read
+  carries `changed_by` and `changed_via` (the last write's membership and its door: `seat`,
+  `mcp`, `declared`, `api`, `v1`, `sync`, `server`), and a `/changes` delete carries
+  `deleted_by` and `deleted_via`; `isAgentDoor(door)` is true for the first three. An agent
+  seat's key is recorded as an agent without the option. Never set it in a tool people use.
 - A string holding an unpaired surrogate (text cut mid-emoji) is a 422 naming the field.
   Slice strings by code point, not by UTF-16 unit.
 - Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon

package/CHANGELOG.md

@@ -5,6 +5,28 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.27.0] — 2026-10-16
+
+### Added
+- `OwApiError.isIdempotencyInFlight` (keel #307, D105): a request with the same Idempotency-Key is still
+  running (409 `idempotency_in_flight`, `retryAfter` 1). Nothing was written by this one; send again with
+  the same key and body after `retryAfter` and it replays the first answer. `isIdempotencyConflict` stays
+  the different-body case only. The client still does not retry for you.
+
+## [4.26.0] — 2026-10-15
+
+### Added
+- **The door of every write** (keel #299, D104; keel 7c1b493). An opt-in
+  `agent: true` on `OwClientConfig` sends `X-OW-Agent` on every element write (create, upsert,
+  patch, delete, editLinks, bulk: the operations keel's document declares it on; never on reads,
+  account routes or the image edge); keel records such writes as `declared`, agent-made, and stores only that the header was
+  there. Off by default: it describes the caller, so a tool people use never sets it.
+- `OwElementBase` gains the read-only `changed_by` (the membership of the last write) and
+  `changed_via` (its door: `seat`, `mcp`, `declared`, `api`, `v1`, `sync`, `server`); a `/changes`
+  delete op gains `deleted_by` and `deleted_via`. Keel drops them from a write body, like `created_by`.
+- `OwWriteDoor`, `AGENT_DOORS` and `isAgentDoor(door)`: seat, mcp and declared are agent-made.
+- The two kinds of `/changes` item are named types, `OwChangeUpsert` and `OwChangeDelete` (`OwChange` is their union, as before), and both declare `change_seq`, which keel always sends and the type never named.
+
 ## [4.25.0] — 2026-10-15
 
 ### Changed

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** Every element carries these. The extension index signature admits namespaced
  *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server.
  *  Derived from base_properties.yaml: `World` is dropped (the API rejects it in
- *  bodies -- the key determines the world) and the five server-managed fields are
+ *  bodies -- the key determines the world) and the seven server-managed fields are
  *  added, since they ride every wire body and appear in no element YAML. */
 interface OwElementBase {
     /** Element type slug (server-managed, read-only). */
@@ -26,6 +26,10 @@ interface OwElementBase {
     change_seq?: number;
     /** The membership that created this element (server-managed, read-only); null for the world's owner and for anything created before memberships existed. */
     created_by?: string | null;
+    /** The membership whose write last changed this element (server-managed, read-only); null for the world's owner and for anything last changed before writes recorded it. */
+    changed_by?: string | null;
+    /** The door of the last write (server-managed, read-only): `seat` (an agent seat), `mcp`, `declared` (a client that sent X-OW-Agent), then `api`, `v1`, `sync`, or `server` (keel's own writes). The first three are agent-made. Null for anything last changed before writes recorded it. */
+    changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | null;
     /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
     [ext: string]: unknown;
 }
@@ -1905,20 +1909,43 @@ interface OwPage<T = OwElement> {
     next_cursor: string | null;
 }
 /** /changes feed -- discriminated union on `op`. Apply in order -> convergence. */
-type OwChange = {
+type OwChange = OwChangeUpsert | OwChangeDelete;
+/** A /changes item for an element written: the element whole, as GET returns it. */
+interface OwChangeUpsert {
     op: 'upsert';
     id: string;
     type: string;
     element: OwElement;
     updated_at: string;
+    /** The change's place in the world's feed. */
+    change_seq: number;
     [k: string]: unknown;
-} | {
+}
+/** A /changes item for an element deleted. */
+interface OwChangeDelete {
     op: 'delete';
     id: string;
     type: string;
     deleted_at: string;
+    /** The change's place in the world's feed. */
+    change_seq: number;
+    /** The membership whose write deleted it; null for the world's owner, and for deletes before writes recorded it (keel #299). */
+    deleted_by?: string | null;
+    /** The door the delete came through (see {@link OwWriteDoor}); null for deletes before writes recorded it. */
+    deleted_via?: OwWriteDoor | null;
     [k: string]: unknown;
-};
+}
+/**
+ * The door a write came through, as keel records it on every element (`changed_via`) and on a
+ * delete (`deleted_via`) since keel #299: `seat` (an agent seat), `mcp` (the MCP server),
+ * `declared` (a client that sent `X-OW-Agent`; see {@link OwClientConfig.agent}), then the
+ * surface for everything else: `api`, `v1`, `sync`, and `server` for keel's own writes.
+ */
+type OwWriteDoor = NonNullable<OwElementBase['changed_via']>;
+/** The doors that mean agent-made: an agent seat, the MCP server, or a client that declared itself. */
+declare const AGENT_DOORS: readonly OwWriteDoor[];
+/** Whether a write came through an agent's door (`changed_via` or `deleted_via`); false for null. */
+declare function isAgentDoor(door: OwWriteDoor | null | undefined): boolean;
 /**
  * /changes response. Wire shape verified in keel source (core/changes.py) and
  * pinned here: {cursor, changes, has_more, head}.
@@ -2308,6 +2335,15 @@ interface OwClientConfig {
     changesPageSize?: number;
     /** A fetch implementation to use instead of globalThis.fetch (for tests and other runtimes). */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Declare this client an AI agent: every element write (create, upsert, patch, delete,
+     * editLinks, bulk) carries `X-OW-Agent`, the operations keel declares it on, and keel
+     * records its writes as agent-made (`changed_via: 'declared'`; keel stores that the header
+     * was there, never its value). Off by default, and it must stay off in a tool people use:
+     * it describes the caller, so only the caller can set it. An agent seat's key is recorded
+     * as an agent without it.
+     */
+    agent?: boolean;
 }
 
 /**
@@ -2358,6 +2394,13 @@ declare class OwApiError extends Error {
      * conflict: keel also answers 409 `id_conflict` (see isIdConflict).
      */
     get isIdempotencyConflict(): boolean;
+    /**
+     * A request with this Idempotency-Key is still running (409 `idempotency_in_flight`, keel
+     * #307, D105): two sends of one create or bulk overlapped. Nothing was written by this one.
+     * Wait `retryAfter` seconds (keel sends 1) and send again with the SAME key and body: once
+     * the first has answered, that retry replays its answer. Not a key conflict (see above).
+     */
+    get isIdempotencyInFlight(): boolean;
     /**
      * The id is already taken (409 `id_conflict`): a create with an id that exists
      * (keel D39), or a PUT whose id belongs to another world (D70). Retrying will not
@@ -2481,6 +2524,7 @@ declare class OwV2Client {
     private readonly apiKey;
     private readonly apiPin;
     private readonly fetchImpl;
+    private readonly agent;
     constructor(config: OwClientConfig);
     /** GET /health -- unauthenticated liveness pulse. */
     health(): Promise<unknown>;
@@ -2764,6 +2808,8 @@ declare class OwV2Client {
         allowEmpty?: boolean;
         replayAware?: boolean;
         /** A `change_seq` to send as `If-Match` (keel #210); a whole number, else TypeError before sending. */
+        /** An element write (create, put, patch, delete, links, bulk): where an agent client sends X-OW-Agent. */
+        write?: boolean;
         ifMatch?: number;
     }): Promise<T>;
 }
@@ -3711,4 +3757,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -26,6 +26,15 @@ var OwApiError = class extends Error {
   get isIdempotencyConflict() {
     return this.status === 409 && this.code === "idempotency_error";
   }
+  /**
+   * A request with this Idempotency-Key is still running (409 `idempotency_in_flight`, keel
+   * #307, D105): two sends of one create or bulk overlapped. Nothing was written by this one.
+   * Wait `retryAfter` seconds (keel sends 1) and send again with the SAME key and body: once
+   * the first has answered, that retry replays its answer. Not a key conflict (see above).
+   */
+  get isIdempotencyInFlight() {
+    return this.status === 409 && this.code === "idempotency_in_flight";
+  }
   /**
    * The id is already taken (409 `id_conflict`): a create with an id that exists
    * (keel D39), or a PUT whose id belongs to another world (D70). Retrying will not
@@ -191,6 +200,7 @@ var OwV2Client = class {
     this.pageSize = config.pageSize ?? DEFAULT_PAGE_SIZE;
     this.changesPageSize = config.changesPageSize ?? DEFAULT_CHANGES_PAGE_SIZE;
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.agent = config.agent === true;
     if (typeof this.fetchImpl !== "function") {
       throw new Error("OwV2Client: no fetch available -- supply config.fetch");
     }
@@ -276,13 +286,14 @@ var OwV2Client = class {
       body.id = mintUuid();
     }
     return this.request("POST", `/${type}/`, {
+      write: true,
       body,
       idempotencyKey: opts.idempotencyKey
     });
   }
   /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
   async upsert(type, id, element) {
-    return this.request("PUT", `/${type}/${id}/`, { body: sanitizePayload(element) });
+    return this.request("PUT", `/${type}/${id}/`, { write: true, body: sanitizePayload(element) });
   }
   /**
    * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
@@ -295,7 +306,7 @@ var OwV2Client = class {
    * it for today's unconditional write.
    */
   async patch(type, id, partial, opts = {}) {
-    return this.request("PATCH", `/${type}/${id}/`, { body: sanitizePayload(partial), ifMatch: opts.ifMatch });
+    return this.request("PATCH", `/${type}/${id}/`, { write: true, body: sanitizePayload(partial), ifMatch: opts.ifMatch });
   }
   /**
    * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
@@ -303,7 +314,7 @@ var OwV2Client = class {
    * transaction -- no client-side unlink pass needed, ever.
    */
   async delete(type, id) {
-    await this.request("DELETE", `/${type}/${id}/`, { allowEmpty: true });
+    await this.request("DELETE", `/${type}/${id}/`, { write: true, allowEmpty: true });
   }
   /**
    * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
@@ -313,7 +324,7 @@ var OwV2Client = class {
    * moves the element too.
    */
   async editLinks(type, id, field, edit, opts = {}) {
-    return this.request("POST", `/${type}/${id}/links/${field}`, { body: edit, ifMatch: opts.ifMatch });
+    return this.request("POST", `/${type}/${id}/links/${field}`, { write: true, body: edit, ifMatch: opts.ifMatch });
   }
   // -- Bulk ----------------------------------------------------------------
   /**
@@ -334,6 +345,7 @@ var OwV2Client = class {
       atomic: opts.atomic ?? false
     };
     return this.request("POST", "/bulk/", {
+      write: true,
       body,
       idempotencyKey: opts.idempotencyKey,
       replayAware: true
@@ -617,6 +629,7 @@ var OwV2Client = class {
     if (opts.body !== void 0) headers["Content-Type"] = "application/json";
     if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
     if (opts.ifMatch !== void 0) headers["If-Match"] = `"${opts.ifMatch}"`;
+    if (this.agent && opts.write) headers["X-OW-Agent"] = "1";
     let res;
     try {
       res = await this.fetchImpl(url, {
@@ -1431,6 +1444,10 @@ var FIELD_SCHEMA = {
 
 // src/v2/types.ts
 var SPATIAL_TYPES = ["map", "pin", "marker", "zone"];
+var AGENT_DOORS = ["seat", "mcp", "declared"];
+function isAgentDoor(door) {
+  return door != null && AGENT_DOORS.includes(door);
+}
 
 // src/v2/palette.ts
 var FAMILY_COLORS = {
@@ -2849,6 +2866,7 @@ var GameTier = /* @__PURE__ */ ((GameTier2) => {
   return GameTier2;
 })(GameTier || {});
 export {
+  AGENT_DOORS,
   ASK_LIMITS,
   CALENDAR_FIELD,
   CALENDAR_SUPERTYPE,
@@ -2893,6 +2911,7 @@ export {
   formatYearLabel,
   getElementIcon,
   getElementLabel,
+  isAgentDoor,
   isDemoKey,
   isLeapYear,
   isParseError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.25.0",
+  "version": "4.27.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {