@stigmer/sdk 3.2.2 → 3.3.0

package/src/__tests__/manifest.test.ts

@@ -0,0 +1,271 @@
+import { describe, it, expect } from "vitest";
+import { create, equals } from "@bufbuild/protobuf";
+import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { EnvironmentSchema, type Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { parse as parseYaml } from "yaml";
+import { parseManifest } from "../manifest/parse";
+import { serializeManifest } from "../manifest/serialize";
+import { manifestKinds, manifestHandlerForYamlKind } from "../manifest/registry";
+
+/**
+ * Manifest engine contract tests.
+ *
+ * The engine's core promise is *round-trip fidelity against the generated
+ * proto schemas*: any resource the server returns serializes to YAML that
+ * parses back to the same proto (minus system-managed state), and any
+ * repo-authored manifest (snake_case fields, `apiVersion` spelling) parses
+ * to a proto the `apply` RPC accepts. Fixtures mirror the real manifests
+ * in the whatsapp-doctor-assistant dogfooding repo.
+ */
+
+// ---------------------------------------------------------------------------
+// Fixtures — shaped like the whatsapp-doctor-assistant repo manifests
+// ---------------------------------------------------------------------------
+
+const AGENT_YAML = `
+apiVersion: agentic.stigmer.ai/v1
+kind: Agent
+metadata:
+  name: clinic-patient-assistant
+  org: rakeshreddi098
+spec:
+  description: Patient-facing WhatsApp assistant for the clinic.
+  instructions: |
+    You are the appointment assistant for the clinic.
+    Short messages. One question at a time.
+`;
+
+const ENVIRONMENT_YAML = `
+apiVersion: agentic.stigmer.ai/v1
+kind: Environment
+metadata:
+  name: clinic-patient-db
+  org: rakeshreddi098
+spec:
+  description: "Clinic records access for the patient assistant"
+  data:
+    POSTGRES_CONNECTION_URL:
+      value: "postgresql://patient_role:secret@host:5432/postgres"
+      is_secret: true
+      description: "Supabase Postgres connection URL for patient_role"
+`;
+
+const AGENT_CHANNEL_YAML = `
+apiVersion: agentic.stigmer.ai/v1
+kind: AgentChannel
+metadata:
+  name: clinic-patient-whatsapp
+  org: rakeshreddi098
+spec:
+  agent_ref:
+    kind: agent
+    org: rakeshreddi098
+    slug: clinic-patient-assistant
+  enabled: true
+  whatsapp:
+    phone_number_id: "1234567890"
+  app_ref:
+    kind: channel_app
+    org: rakeshreddi098
+    slug: hosipital
+  environment_refs:
+    - kind: environment
+      org: rakeshreddi098
+      slug: clinic-patient-db
+`;
+
+// ---------------------------------------------------------------------------
+// parseManifest
+// ---------------------------------------------------------------------------
+
+describe("parseManifest", () => {
+  it("parses a snake_case Agent manifest into a full Agent proto", () => {
+    const docs = parseManifest(AGENT_YAML);
+    expect(docs).toHaveLength(1);
+
+    const doc = docs[0];
+    expect(doc.handler.yamlKind).toBe("Agent");
+    expect(doc.name).toBe("clinic-patient-assistant");
+    expect(doc.org).toBe("rakeshreddi098");
+
+    const agent = doc.message as Agent;
+    expect(agent.spec?.description).toBe(
+      "Patient-facing WhatsApp assistant for the clinic.",
+    );
+    expect(agent.spec?.instructions).toContain("appointment assistant");
+  });
+
+  it("parses an AgentChannel manifest with enum-valued resource refs", () => {
+    const docs = parseManifest(AGENT_CHANNEL_YAML);
+    expect(docs).toHaveLength(1);
+    expect(docs[0].handler.yamlKind).toBe("AgentChannel");
+    expect(docs[0].slug).toBe("clinic-patient-whatsapp");
+  });
+
+  it("sorts multi-document manifests into dependency apply order", () => {
+    // Authored channel-first; the Environment must still apply first.
+    const docs = parseManifest(`${AGENT_CHANNEL_YAML}\n---\n${ENVIRONMENT_YAML}`);
+    expect(docs.map((d) => d.handler.yamlKind)).toEqual([
+      "Environment",
+      "AgentChannel",
+    ]);
+  });
+
+  it("injects the target org when the document omits it", () => {
+    const yaml = AGENT_YAML.replace("  org: rakeshreddi098\n", "");
+    const docs = parseManifest(yaml, { org: "acme" });
+    expect(docs[0].org).toBe("acme");
+    expect(docs[0].warning).toBeUndefined();
+  });
+
+  it("honors the document org and warns when it differs from the target", () => {
+    const docs = parseManifest(AGENT_YAML, { org: "acme" });
+    expect(docs[0].org).toBe("rakeshreddi098");
+    expect(docs[0].warning).toContain('"rakeshreddi098"');
+    expect(docs[0].warning).toContain('"acme"');
+  });
+
+  it("rejects unknown fields loudly (strict schema contract)", () => {
+    const yaml = AGENT_YAML.replace("spec:", "spec:\n  instrctions: typo");
+    expect(() => parseManifest(yaml)).toThrow(/Invalid Agent/);
+  });
+
+  it("rejects a document without a kind", () => {
+    expect(() => parseManifest("metadata:\n  name: x\n")).toThrow(/'kind'/);
+  });
+
+  it("rejects unsupported kinds with the supported list", () => {
+    expect(() => parseManifest("kind: Skill\nmetadata:\n  name: x\n")).toThrow(
+      /Unsupported resource kind "Skill".*Agent/s,
+    );
+  });
+
+  it("rejects empty input with actionable guidance", () => {
+    expect(() => parseManifest("   \n")).toThrow(/empty/i);
+  });
+
+  it("rejects malformed YAML", () => {
+    expect(() => parseManifest("kind: Agent\n  bad indent: [")).toThrow(
+      /Invalid YAML/,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// serializeManifest
+// ---------------------------------------------------------------------------
+
+describe("serializeManifest", () => {
+  const agent = create(AgentSchema, {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Agent",
+    metadata: {
+      id: "agt_01example",
+      name: "clinic-patient-assistant",
+      slug: "clinic-patient-assistant",
+      org: "rakeshreddi098",
+      version: { id: "ver_01", message: "server-managed" },
+    },
+    spec: {
+      description: "Patient-facing WhatsApp assistant.",
+      instructions: "Short messages.\nOne question at a time.\n",
+    },
+    status: { defaultInstanceId: "agi_01example" },
+  });
+
+  it("emits the canonical envelope: apiVersion spelling, no status", () => {
+    const yaml = serializeManifest(agent);
+    const doc = parseYaml(yaml) as Record<string, unknown>;
+
+    expect(Object.keys(doc)[0]).toBe("apiVersion");
+    expect(doc.apiVersion).toBe("agentic.stigmer.ai/v1");
+    expect(doc.kind).toBe("Agent");
+    expect(doc.status).toBeUndefined();
+    expect(yaml).not.toContain("api_version:");
+  });
+
+  it("keeps metadata.id but strips server-managed metadata.version", () => {
+    const doc = parseYaml(serializeManifest(agent)) as {
+      metadata: Record<string, unknown>;
+    };
+    expect(doc.metadata.id).toBe("agt_01example");
+    expect(doc.metadata.version).toBeUndefined();
+  });
+
+  it("fills apiVersion and kind from the registry when the proto omits them", () => {
+    const bare = create(AgentSchema, {
+      metadata: { name: "x", org: "acme" },
+    });
+    const doc = parseYaml(serializeManifest(bare)) as Record<string, unknown>;
+    expect(doc.apiVersion).toBe("agentic.stigmer.ai/v1");
+    expect(doc.kind).toBe("Agent");
+  });
+
+  it("round-trips through parseManifest to an equal proto", () => {
+    const docs = parseManifest(serializeManifest(agent));
+    expect(docs).toHaveLength(1);
+
+    // The round-tripped proto matches the original minus system-managed
+    // state (status, metadata.version) — exactly what apply consumes.
+    const expected = create(AgentSchema, {
+      ...agent,
+      status: undefined,
+      metadata: { ...agent.metadata!, version: undefined },
+    });
+    expect(equals(AgentSchema, docs[0].message as Agent, expected)).toBe(true);
+  });
+
+  it("round-trips Environment secret values byte-identically", () => {
+    const env = create(EnvironmentSchema, {
+      metadata: { name: "clinic-patient-db", org: "rakeshreddi098" },
+      spec: {
+        data: {
+          POSTGRES_CONNECTION_URL: {
+            value: "***REDACTED***",
+            isSecret: true,
+            description: "Supabase Postgres connection URL",
+          },
+        },
+      },
+    });
+
+    const docs = parseManifest(serializeManifest(env));
+    const roundTripped = docs[0].message as Environment;
+    expect(roundTripped.spec?.data.POSTGRES_CONNECTION_URL?.value).toBe(
+      "***REDACTED***",
+    );
+    expect(roundTripped.spec?.data.POSTGRES_CONNECTION_URL?.isSecret).toBe(true);
+  });
+
+  it("rejects messages of kinds outside the registry", () => {
+    // ApiResourceMetadata is a real proto message but not a manifest kind.
+    const notAResource = create(ApiResourceMetadataSchema, { name: "x" });
+    expect(() => serializeManifest(notAResource)).toThrow(/not.*registry/i);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Registry invariants
+// ---------------------------------------------------------------------------
+
+describe("manifest registry", () => {
+  it("every handler resolves by its own YAML kind", () => {
+    for (const handler of manifestKinds()) {
+      expect(manifestHandlerForYamlKind(handler.yamlKind)).toBe(handler);
+    }
+  });
+
+  it("apply order is strictly increasing (no accidental ties)", () => {
+    const orders = manifestKinds().map((h) => h.applyOrder);
+    for (let i = 1; i < orders.length; i++) {
+      expect(orders[i]).toBeGreaterThan(orders[i - 1]);
+    }
+  });
+
+  it("covers the kinds the console flows depend on", () => {
+    for (const kind of ["Agent", "McpServer", "Workflow", "Environment", "AgentChannel", "ChannelApp"]) {
+      expect(manifestHandlerForYamlKind(kind), `missing handler for ${kind}`).toBeDefined();
+    }
+  });
+});

package/src/billing.ts

@@ -12,12 +12,21 @@ import {
   SetAutoRechargeConfigInputSchema,
   GetBillingUsageReportInputSchema,
   GetCustomerModelPricingInputSchema,
+  GetModelPricingGovernanceInputSchema,
+  DecideModelPricingOverrideInputSchema,
+  UpsertModelPricingBaselineInputSchema,
+  RetireModelPricingBaselineInputSchema,
+  ListModelPricingBaselinesInputSchema,
   type CreateCreditCheckoutSessionResponse,
   type CreateBillingPortalSessionResponse,
   type CreditLedgerResponse,
   type BillingUsageReportResponse,
   type CustomerModelPricingResponse,
+  type ModelPricingGovernanceResponse,
+  type ModelPricingBaselinesResponse,
 } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import type { ModelPricingOverride } from "@stigmer/protos/ai/stigmer/billing/v1/pricing_override_pb";
+import type { ModelPricingBaseline } from "@stigmer/protos/ai/stigmer/billing/v1/model_pricing_baseline_pb";
 import type { BillingAccount, CreditBalance } from "@stigmer/protos/ai/stigmer/billing/v1/billing_account_pb";
 import type { LedgerEntryType, LedgerView } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
 import { PageInfoSchema } from "@stigmer/protos/ai/stigmer/commons/rpc/pagination_pb";
@@ -74,6 +83,49 @@ export interface GetCustomerModelPricingParams {
   readonly orgId?: string;
 }
 
+/** Parameters for creating or revising a model registry baseline entry. */
+export interface UpsertModelPricingBaselineParams {
+  /**
+   * The baseline entry to create or revise, keyed by
+   * (modelId, provider, harness). Lifecycle fields (baselineId, status,
+   * decision stamps, pricing effectiveAt) are server-owned and ignored.
+   */
+  readonly baseline: ModelPricingBaseline;
+  /** Optional operator note recorded on the revision for the audit trail. */
+  readonly revisionNote?: string;
+}
+
+/** Parameters for retiring a model from the registry catalog. */
+export interface RetireModelPricingBaselineParams {
+  readonly modelId: string;
+  readonly provider: string;
+  readonly harness: string;
+  /** Optional operator note recorded on the retirement. */
+  readonly revisionNote?: string;
+}
+
+/** Parameters for listing the model registry baseline catalog. */
+export interface ListModelPricingBaselinesParams {
+  /**
+   * When `true`, includes SUPERSEDED and RETIRED revisions (the full
+   * audit history). Default: ACTIVE documents only.
+   */
+  readonly includeHistory?: boolean;
+}
+
+/** Parameters for deciding a pending pricing override. */
+export interface DecideModelPricingOverrideParams {
+  /** The PENDING_SIGNOFF override to decide. */
+  readonly overrideId: string;
+  /**
+   * `true` approves (the override becomes ACTIVE and supersedes any
+   * current ACTIVE override on the same pricing key); `false` rejects.
+   */
+  readonly approve: boolean;
+  /** Optional note recorded on the decision for the audit trail. */
+  readonly decisionNote?: string;
+}
+
 /**
  * Client for the billing bounded context.
  *
@@ -270,4 +322,112 @@ export class BillingClient {
       throw wrapError(e);
     }
   }
+
+  /**
+   * Retrieve the platform pricing governance view: baseline vs effective
+   * rates per model, ACTIVE override provenance, and pending sign-off
+   * proposals from the pricing feedback loop.
+   *
+   * Platform-operator surface (`can_manage_model_pricing` on
+   * `platform:stigmer`): rates are raw provider prices, pre-markup.
+   */
+  async getModelPricingGovernance(): Promise<ModelPricingGovernanceResponse> {
+    try {
+      return await this.query.getModelPricingGovernance(
+        create(GetModelPricingGovernanceInputSchema, {}),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /**
+   * Record a human decision on a PENDING_SIGNOFF pricing override.
+   *
+   * Approving makes the override ACTIVE (superseding any current ACTIVE
+   * override on the same pricing key) and recomposes the effective
+   * registry; rejecting archives it for audit. Returns the decided
+   * override with the decision stamped.
+   */
+  async decideModelPricingOverride(
+    params: DecideModelPricingOverrideParams,
+  ): Promise<ModelPricingOverride> {
+    try {
+      return await this.command.decideModelPricingOverride(
+        create(DecideModelPricingOverrideInputSchema, {
+          overrideId: params.overrideId,
+          approve: params.approve,
+          decisionNote: params.decisionNote ?? "",
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /**
+   * Retrieve the model registry baseline catalog: ACTIVE entries by
+   * default, or the full append-only revision history with
+   * `includeHistory`.
+   *
+   * Platform-operator surface (`can_manage_model_pricing` on
+   * `platform:stigmer`): rates are raw provider prices, pre-markup.
+   */
+  async listModelPricingBaselines(
+    params?: ListModelPricingBaselinesParams,
+  ): Promise<ModelPricingBaselinesResponse> {
+    try {
+      return await this.query.listModelPricingBaselines(
+        create(ListModelPricingBaselinesInputSchema, {
+          includeHistory: params?.includeHistory ?? false,
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /**
+   * Create or revise one model registry baseline entry (catalog + list
+   * prices). Append-only: an existing ACTIVE entry for the same
+   * (modelId, provider, harness) key is superseded, never mutated, and
+   * the effective registry recomposes immediately. Returns the new
+   * revision with server-stamped lifecycle fields.
+   */
+  async upsertModelPricingBaseline(
+    params: UpsertModelPricingBaselineParams,
+  ): Promise<ModelPricingBaseline> {
+    try {
+      return await this.command.upsertModelPricingBaseline(
+        create(UpsertModelPricingBaselineInputSchema, {
+          baseline: params.baseline,
+          revisionNote: params.revisionNote ?? "",
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /**
+   * Retire one model from the registry catalog. The model disappears
+   * from every price surface on the next composition pass; the document
+   * is kept for audit and the key can be revived by a subsequent upsert.
+   */
+  async retireModelPricingBaseline(
+    params: RetireModelPricingBaselineParams,
+  ): Promise<ModelPricingBaseline> {
+    try {
+      return await this.command.retireModelPricingBaseline(
+        create(RetireModelPricingBaselineInputSchema, {
+          modelId: params.modelId,
+          provider: params.provider,
+          harness: params.harness,
+          revisionNote: params.revisionNote ?? "",
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
 }

package/src/cursor-accounts.ts

@@ -0,0 +1,207 @@
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { CursorAccountCommandController } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/command_pb";
+import { CursorAccountQueryController } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/query_pb";
+import {
+  UpsertCursorAccountInputSchema,
+  DeleteCursorAccountInputSchema,
+  AddCursorMemberKeyInputSchema,
+  RemoveCursorMemberKeyInputSchema,
+  SetCursorMemberKeyEnabledInputSchema,
+  SyncCursorAccountInputSchema,
+  ListCursorAccountsInputSchema,
+  GetCursorAccountViewInputSchema,
+  type CursorAccountsResponse,
+  type CursorAccountView,
+} from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/io_pb";
+import type { CursorAccount } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/cursor_account_pb";
+import { wrapError } from "./gen/errors.js";
+
+/** Parameters for creating or updating a Cursor account. */
+export interface UpsertCursorAccountParams {
+  /**
+   * The account to create (empty `accountId`) or update. The admin key is
+   * plaintext to set/rotate or `"***REDACTED***"` to keep the stored
+   * value; member keys on this message are ignored — use
+   * {@link CursorAccountsClient.addMemberKey} and friends.
+   */
+  readonly account: CursorAccount;
+}
+
+/** Parameters for deleting a Cursor account. */
+export interface DeleteCursorAccountParams {
+  readonly accountId: string;
+  /**
+   * Deletion is refused while live sessions are pinned to the account's
+   * keys. `force: true` overrides — their Cursor agent handles will be
+   * orphaned at disposal.
+   */
+  readonly force?: boolean;
+}
+
+/** Parameters for adding one member key. */
+export interface AddCursorMemberKeyParams {
+  readonly accountId: string;
+  /**
+   * Plaintext user-scoped Cursor API key. Validated live against Cursor's
+   * `/v1/me` and bound to its owning team member server-side; admin and
+   * service-account keys are rejected with Cursor's own explanation.
+   */
+  readonly apiKey: string;
+  /** Optional operator label (e.g. `"zane — stigmer-prod"`). */
+  readonly label?: string;
+}
+
+/** Parameters for removing one member key. */
+export interface RemoveCursorMemberKeyParams {
+  readonly accountId: string;
+  readonly keyId: string;
+  /**
+   * Removal is refused while live sessions are pinned to this key.
+   * `force: true` overrides — prefer disabling instead (always safe).
+   */
+  readonly force?: boolean;
+}
+
+/** Parameters for enabling/disabling one member key. */
+export interface SetCursorMemberKeyEnabledParams {
+  readonly accountId: string;
+  readonly keyId: string;
+  /**
+   * `false` blocks NEW sessions immediately; sessions already pinned to
+   * the key keep working (conversation continuity + disposal need it).
+   */
+  readonly enabled: boolean;
+}
+
+/**
+ * Client for managed Cursor accounts (platform operators only).
+ *
+ * A Cursor account is one managed Cursor team: its Admin API key (roster
+ * and spend, never executions), its member execution keys, and its org
+ * assignments. Every method requires `can_manage_cursor_accounts` on
+ * `platform:stigmer`; key material is always redacted in responses.
+ */
+export class CursorAccountsClient {
+  private readonly command: Client<typeof CursorAccountCommandController>;
+  private readonly query: Client<typeof CursorAccountQueryController>;
+
+  constructor(transport: Transport) {
+    this.command = createClient(CursorAccountCommandController, transport);
+    this.query = createClient(CursorAccountQueryController, transport);
+  }
+
+  /** List all Cursor accounts with routing/sync summaries. */
+  async listAccounts(): Promise<CursorAccountsResponse> {
+    try {
+      return await this.query.listCursorAccounts(
+        create(ListCursorAccountsInputSchema, {}),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /**
+   * Retrieve one account's detail view: the redacted account, the latest
+   * roster/spend snapshot, and the computed key-coverage join.
+   */
+  async getAccountView(accountId: string): Promise<CursorAccountView> {
+    try {
+      return await this.query.getCursorAccountView(
+        create(GetCursorAccountViewInputSchema, { accountId }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /**
+   * Create or update a Cursor account. The admin key is validated live
+   * against Cursor's `/teams/members` before persistence.
+   */
+  async upsertAccount(params: UpsertCursorAccountParams): Promise<CursorAccount> {
+    try {
+      return await this.command.upsertCursorAccount(
+        create(UpsertCursorAccountInputSchema, { account: params.account }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /** Delete a Cursor account (guarded against live session pins). */
+  async deleteAccount(params: DeleteCursorAccountParams): Promise<CursorAccount> {
+    try {
+      return await this.command.deleteCursorAccount(
+        create(DeleteCursorAccountInputSchema, {
+          accountId: params.accountId,
+          force: params.force ?? false,
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /** Add one execution-capable member key (identity bound via `/v1/me`). */
+  async addMemberKey(params: AddCursorMemberKeyParams): Promise<CursorAccount> {
+    try {
+      return await this.command.addCursorMemberKey(
+        create(AddCursorMemberKeyInputSchema, {
+          accountId: params.accountId,
+          apiKey: params.apiKey,
+          label: params.label ?? "",
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /** Remove one member key (guarded against live session pins). */
+  async removeMemberKey(params: RemoveCursorMemberKeyParams): Promise<CursorAccount> {
+    try {
+      return await this.command.removeCursorMemberKey(
+        create(RemoveCursorMemberKeyInputSchema, {
+          accountId: params.accountId,
+          keyId: params.keyId,
+          force: params.force ?? false,
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /** Enable or disable one member key for new-session selection. */
+  async setMemberKeyEnabled(
+    params: SetCursorMemberKeyEnabledParams,
+  ): Promise<CursorAccount> {
+    try {
+      return await this.command.setCursorMemberKeyEnabled(
+        create(SetCursorMemberKeyEnabledInputSchema, {
+          accountId: params.accountId,
+          keyId: params.keyId,
+          enabled: params.enabled,
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
+  /**
+   * Run an on-demand roster + spend sync and return the refreshed view.
+   * Rate-limited upstream (Cursor Admin API) — debounce in UIs.
+   */
+  async syncAccount(accountId: string): Promise<CursorAccountView> {
+    try {
+      return await this.command.syncCursorAccount(
+        create(SyncCursorAccountInputSchema, { accountId }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+}

package/src/errors.ts

@@ -303,6 +303,33 @@ export function getErrorReason(error: unknown): ErrorReason | null {
   return null;
 }
 
+/**
+ * The `google.rpc.ErrorInfo` domain attached by datastore record-RPC
+ * errors in both editions (a cross-edition contract; see the OSS
+ * `dserrors` package and its Java mirror).
+ */
+const RECORDS_ERROR_DOMAIN = "datastore.stigmer.ai";
+
+/**
+ * Extract the violated constraint's declared name from a datastore
+ * record-RPC error, or `null` when the error carries none.
+ *
+ * Record writes rejected by a declared constraint (`ALREADY_EXISTS` for
+ * uniques, `FAILED_PRECONDITION` for check/exists/not_exists) attach a
+ * `google.rpc.ErrorInfo` with reason `CONSTRAINT_VIOLATION` and the
+ * constraint's name in `metadata["constraint"]` — the same companion
+ * the MCP bridge's record tools surface to agents. Consumers map the
+ * name through the datastore spec to place the (verbatim) message next
+ * to the fields the constraint covers; `null` falls back to a
+ * form-level rendering of {@link getUserMessage}.
+ */
+export function getRecordConstraint(error: unknown): string | null {
+  const reason = getErrorReason(error);
+  if (!reason || reason.domain !== RECORDS_ERROR_DOMAIN) return null;
+  const constraint = reason.metadata["constraint"];
+  return constraint !== undefined && constraint !== "" ? constraint : null;
+}
+
 /**
  * Metadata about the RPC call that produced an error. Attached by the
  * SDK's metadata interceptor and readable via {@link getRpcMetadata}.