@stigmer/sdk 3.2.2 → 3.3.0

package/manifest/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../../src/manifest/redaction.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAErE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,gBAAgB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,OAAO,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC;AAClD,CAAC"}

package/manifest/registry.d.ts

@@ -0,0 +1,44 @@
+import type { DescMessage, DescService, Message } from "@bufbuild/protobuf";
+import type { Client } from "@connectrpc/connect";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+/**
+ * Accessor for a raw Connect client over a generated service controller.
+ * Implementations cache clients per service (see `ManifestClient`).
+ */
+export type ServiceClientFn = <Desc extends DescService>(service: Desc) => Client<Desc>;
+/**
+ * Binds one YAML `kind` to everything the manifest engine needs:
+ * the proto schema (strict marshalling), the command controller's `apply`
+ * RPC, and the query controller's `getByReference` RPC (create-vs-update
+ * preview).
+ */
+export interface ManifestKindHandler {
+    /** The platform resource kind enum value. */
+    readonly kind: ApiResourceKind;
+    /** The YAML discriminator, e.g. `"Agent"`. */
+    readonly yamlKind: string;
+    /** Human-facing name for messages, e.g. `"MCP Server"`. */
+    readonly displayName: string;
+    /** Canonical `apiVersion` for this kind, e.g. `"agentic.stigmer.ai/v1"`. */
+    readonly apiVersion: string;
+    /** Proto schema for strict YAML↔proto conversion. */
+    readonly schema: DescMessage;
+    /**
+     * Position in the dependency apply order (ascending). Referenced kinds
+     * apply before their dependents, e.g. an McpServer before the Agent that
+     * uses it, and everything an AgentChannel references before the channel.
+     */
+    readonly applyOrder: number;
+    /** Drive the command controller's `apply` RPC with the full resource. */
+    apply(clientFor: ServiceClientFn, message: Message): Promise<Message>;
+    /** Load the current server state by org/slug reference. */
+    getByReference(clientFor: ServiceClientFn, ref: ApiResourceReference): Promise<Message>;
+}
+/** All kinds the manifest engine supports, in dependency apply order. */
+export declare function manifestKinds(): readonly ManifestKindHandler[];
+/** Resolve a handler by its YAML `kind` discriminator (e.g. `"Agent"`). */
+export declare function manifestHandlerForYamlKind(yamlKind: string): ManifestKindHandler | undefined;
+/** Resolve a handler from a proto message's fully-qualified type name. */
+export declare function manifestHandlerForTypeName(typeName: string): ManifestKindHandler | undefined;
+//# sourceMappingURL=registry.d.ts.map

package/manifest/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/manifest/registry.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qFAAqF,CAAC;AACtH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sDAAsD,CAAC;AAoCjG;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,SAAS,WAAW,EAAE,OAAO,EAAE,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,KAAK,CAAC,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,2DAA2D;IAC3D,cAAc,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzF;AAiID,yEAAyE;AACzE,wBAAgB,aAAa,IAAI,SAAS,mBAAmB,EAAE,CAE9D;AAED,2EAA2E;AAC3E,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,GACf,mBAAmB,GAAG,SAAS,CAEjC;AAED,0EAA0E;AAC1E,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,GACf,mBAAmB,GAAG,SAAS,CAEjC"}

package/manifest/registry.js

@@ -0,0 +1,178 @@
+// Explicit manifest-kind registry: the single place that binds a YAML `kind`
+// to its proto schema and controller RPCs.
+//
+// This is the SDK home of the pattern the CLIs already rely on (Go CLI,
+// TS CLI `resources/apply/handlers.ts`, mcp-server): strict YAML→proto
+// marshalling against the *generated schema*, and apply through the raw
+// command controller with the full resource message. The high-level
+// `*Input` wrappers are intentionally bypassed — they are lossy (they drop
+// `metadata.id` and any field codegen hasn't projected), while the `apply`
+// RPC takes the complete resource and the server upserts by slug.
+//
+// Registration is explicit — to support a new kind, add one entry here.
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { AgentChannelSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentChannelCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/command_pb";
+import { AgentChannelQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/query_pb";
+import { AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { AgentInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/command_pb";
+import { AgentInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/query_pb";
+import { AgentShareSchema } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { AgentShareCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/command_pb";
+import { AgentShareQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/query_pb";
+import { ChannelAppSchema } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { ChannelAppCommandController } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/command_pb";
+import { ChannelAppQueryController } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/query_pb";
+import { DatastoreSchema } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/api_pb";
+import { DatastoreCommandController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/command_pb";
+import { DatastoreQueryController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/query_pb";
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
+import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/query_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import { IdentityProviderSchema } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/api_pb";
+import { IdentityProviderCommandController } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/command_pb";
+import { IdentityProviderQueryController } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/query_pb";
+import { OAuthAppSchema } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/api_pb";
+import { OAuthAppCommandController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/command_pb";
+import { OAuthAppQueryController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/query_pb";
+const AGENTIC_V1 = "agentic.stigmer.ai/v1";
+const IAM_V1 = "iam.stigmer.ai/v1";
+const HANDLERS = [
+    {
+        kind: ApiResourceKind.mcp_server,
+        yamlKind: "McpServer",
+        displayName: "MCP Server",
+        apiVersion: AGENTIC_V1,
+        schema: McpServerSchema,
+        applyOrder: 1,
+        apply: (c, m) => c(McpServerCommandController).apply(m),
+        getByReference: (c, ref) => c(McpServerQueryController).getByReference(ref),
+    },
+    // A Datastore applies before the Agents that reference it via
+    // datastore_usages (the McpServer-before-Agent pattern).
+    {
+        kind: ApiResourceKind.datastore,
+        yamlKind: "Datastore",
+        displayName: "Datastore",
+        apiVersion: AGENTIC_V1,
+        schema: DatastoreSchema,
+        applyOrder: 2,
+        apply: (c, m) => c(DatastoreCommandController).apply(m),
+        getByReference: (c, ref) => c(DatastoreQueryController).getByReference(ref),
+    },
+    {
+        kind: ApiResourceKind.agent,
+        yamlKind: "Agent",
+        displayName: "Agent",
+        apiVersion: AGENTIC_V1,
+        schema: AgentSchema,
+        applyOrder: 3,
+        apply: (c, m) => c(AgentCommandController).apply(m),
+        getByReference: (c, ref) => c(AgentQueryController).getByReference(ref),
+    },
+    {
+        kind: ApiResourceKind.workflow,
+        yamlKind: "Workflow",
+        displayName: "Workflow",
+        apiVersion: AGENTIC_V1,
+        schema: WorkflowSchema,
+        applyOrder: 4,
+        apply: (c, m) => c(WorkflowCommandController).apply(m),
+        getByReference: (c, ref) => c(WorkflowQueryController).getByReference(ref),
+    },
+    {
+        kind: ApiResourceKind.environment,
+        yamlKind: "Environment",
+        displayName: "Environment",
+        apiVersion: AGENTIC_V1,
+        schema: EnvironmentSchema,
+        applyOrder: 5,
+        apply: (c, m) => c(EnvironmentCommandController).apply(m),
+        getByReference: (c, ref) => c(EnvironmentQueryController).getByReference(ref),
+    },
+    {
+        kind: ApiResourceKind.identity_provider,
+        yamlKind: "IdentityProvider",
+        displayName: "Identity Provider",
+        apiVersion: IAM_V1,
+        schema: IdentityProviderSchema,
+        applyOrder: 6,
+        apply: (c, m) => c(IdentityProviderCommandController).apply(m),
+        getByReference: (c, ref) => c(IdentityProviderQueryController).getByReference(ref),
+    },
+    {
+        kind: ApiResourceKind.oauth_app,
+        yamlKind: "OAuthApp",
+        displayName: "OAuth App",
+        apiVersion: IAM_V1,
+        schema: OAuthAppSchema,
+        applyOrder: 7,
+        apply: (c, m) => c(OAuthAppCommandController).apply(m),
+        getByReference: (c, ref) => c(OAuthAppQueryController).getByReference(ref),
+    },
+    {
+        kind: ApiResourceKind.channel_app,
+        yamlKind: "ChannelApp",
+        displayName: "Channel App",
+        apiVersion: AGENTIC_V1,
+        schema: ChannelAppSchema,
+        applyOrder: 8,
+        apply: (c, m) => c(ChannelAppCommandController).apply(m),
+        getByReference: (c, ref) => c(ChannelAppQueryController).getByReference(ref),
+    },
+    {
+        kind: ApiResourceKind.agent_instance,
+        yamlKind: "AgentInstance",
+        displayName: "Agent Instance",
+        apiVersion: AGENTIC_V1,
+        schema: AgentInstanceSchema,
+        applyOrder: 9,
+        apply: (c, m) => c(AgentInstanceCommandController).apply(m),
+        getByReference: (c, ref) => c(AgentInstanceQueryController).getByReference(ref),
+    },
+    {
+        kind: ApiResourceKind.agent_share,
+        yamlKind: "AgentShare",
+        displayName: "Agent Share",
+        apiVersion: AGENTIC_V1,
+        schema: AgentShareSchema,
+        applyOrder: 10,
+        apply: (c, m) => c(AgentShareCommandController).apply(m),
+        getByReference: (c, ref) => c(AgentShareQueryController).getByReference(ref),
+    },
+    // Last: an AgentChannel references an Agent, a ChannelApp, and Environments.
+    {
+        kind: ApiResourceKind.agent_channel,
+        yamlKind: "AgentChannel",
+        displayName: "Agent Channel",
+        apiVersion: AGENTIC_V1,
+        schema: AgentChannelSchema,
+        applyOrder: 11,
+        apply: (c, m) => c(AgentChannelCommandController).apply(m),
+        getByReference: (c, ref) => c(AgentChannelQueryController).getByReference(ref),
+    },
+];
+const BY_YAML_KIND = new Map(HANDLERS.map((h) => [h.yamlKind, h]));
+const BY_TYPE_NAME = new Map(HANDLERS.map((h) => [h.schema.typeName, h]));
+/** All kinds the manifest engine supports, in dependency apply order. */
+export function manifestKinds() {
+    return HANDLERS;
+}
+/** Resolve a handler by its YAML `kind` discriminator (e.g. `"Agent"`). */
+export function manifestHandlerForYamlKind(yamlKind) {
+    return BY_YAML_KIND.get(yamlKind);
+}
+/** Resolve a handler from a proto message's fully-qualified type name. */
+export function manifestHandlerForTypeName(typeName) {
+    return BY_TYPE_NAME.get(typeName);
+}
+//# sourceMappingURL=registry.js.map

package/manifest/registry.js.map

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

package/manifest/serialize.d.ts

@@ -0,0 +1,24 @@
+import { type Message } from "@bufbuild/protobuf";
+/**
+ * Serialize a resource proto into the canonical, editable Stigmer YAML form.
+ *
+ * The resource kind is derived from the message's proto type, so any
+ * registry-supported resource (an `Agent` from `stigmer.agent.get()`, an
+ * `Environment` from `stigmer.environment.get()`, …) serializes with the
+ * same call. `metadata.id` is preserved — the output is a full-fidelity
+ * representation of the stored resource, minus system-managed state.
+ *
+ * @param message - A resource proto of a registry-supported kind.
+ * @returns YAML text suitable for editing and re-applying.
+ * @throws {Error} When the message's kind is not in the manifest registry.
+ *
+ * @example
+ * ```ts
+ * import { serializeManifest } from "@stigmer/sdk";
+ *
+ * const agent = await stigmer.agent.get(agentId);
+ * const yaml = serializeManifest(agent);
+ * ```
+ */
+export declare function serializeManifest(message: Message): string;
+//# sourceMappingURL=serialize.d.ts.map

package/manifest/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/manifest/serialize.ts"],"names":[],"mappings":"AAeA,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAoC1D"}

package/manifest/serialize.js

@@ -0,0 +1,78 @@
+// Proto → canonical Stigmer YAML serialization.
+//
+// Follows the platform-wide protojson parity contract (Go CLI, TS CLI
+// output/proto.ts, mcp-server marshal.ts): `toJson` with
+// `useProtoFieldName: true` emits snake_case field names and omits unset
+// defaults, so the output round-trips through `parseManifest`'s strict
+// `fromJson` without loss.
+//
+// Two deliberate departures from the raw protojson projection, both for
+// the *editable manifest* use case:
+//   - `status` and `metadata.version` are stripped — they are system-managed
+//     and would be ignored (or rejected) on apply.
+//   - the envelope field is spelled `apiVersion` (the canonical form used in
+//     every repo manifest and doc); `fromJson` accepts both spellings.
+import { toJson } from "@bufbuild/protobuf";
+import { stringify as stringifyYaml } from "yaml";
+import { manifestHandlerForTypeName, manifestKinds } from "./registry.js";
+/**
+ * Serialize a resource proto into the canonical, editable Stigmer YAML form.
+ *
+ * The resource kind is derived from the message's proto type, so any
+ * registry-supported resource (an `Agent` from `stigmer.agent.get()`, an
+ * `Environment` from `stigmer.environment.get()`, …) serializes with the
+ * same call. `metadata.id` is preserved — the output is a full-fidelity
+ * representation of the stored resource, minus system-managed state.
+ *
+ * @param message - A resource proto of a registry-supported kind.
+ * @returns YAML text suitable for editing and re-applying.
+ * @throws {Error} When the message's kind is not in the manifest registry.
+ *
+ * @example
+ * ```ts
+ * import { serializeManifest } from "@stigmer/sdk";
+ *
+ * const agent = await stigmer.agent.get(agentId);
+ * const yaml = serializeManifest(agent);
+ * ```
+ */
+export function serializeManifest(message) {
+    const handler = manifestHandlerForTypeName(message.$typeName);
+    if (handler === undefined) {
+        const supported = manifestKinds()
+            .map((h) => h.yamlKind)
+            .join(", ");
+        throw new Error(`Cannot serialize ${message.$typeName} as a manifest: kind is not ` +
+            `in the manifest registry. Supported kinds: ${supported}.`);
+    }
+    const json = toJson(handler.schema, message, { useProtoFieldName: true });
+    if (json === null || typeof json !== "object" || Array.isArray(json)) {
+        throw new Error(`Cannot serialize ${handler.displayName}: unexpected non-object ` +
+            "protojson projection.");
+    }
+    const { api_version, kind, status, metadata, ...rest } = json;
+    void status;
+    const doc = {
+        apiVersion: typeof api_version === "string" && api_version !== ""
+            ? api_version
+            : handler.apiVersion,
+        kind: typeof kind === "string" && kind !== "" ? kind : handler.yamlKind,
+        ...(isPlainObject(metadata) && { metadata: stripSystemMetadata(metadata) }),
+        ...rest,
+    };
+    // lineWidth: 0 disables wrapping (long instruction lines stay intact);
+    // blockQuote: "literal" renders multi-line strings as readable `|` blocks.
+    return stringifyYaml(doc, { lineWidth: 0, blockQuote: "literal" });
+}
+// metadata.version (version id, previous-version pointer, tag) is written by
+// the server on every mutation; round-tripping it through an edit would be
+// misleading at best. Everything else — including id — is user-meaningful.
+function stripSystemMetadata(metadata) {
+    const { version, ...rest } = metadata;
+    void version;
+    return rest;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=serialize.js.map

package/manifest/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../src/manifest/serialize.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,sEAAsE;AACtE,yDAAyD;AACzD,yEAAyE;AACzE,uEAAuE;AACvE,2BAA2B;AAC3B,EAAE;AACF,wEAAwE;AACxE,oCAAoC;AACpC,6EAA6E;AAC7E,mDAAmD;AACnD,6EAA6E;AAC7E,uEAAuE;AAEvE,OAAO,EAAE,MAAM,EAAgB,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,MAAM,OAAO,GAAG,0BAA0B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,aAAa,EAAE;aAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;aACtB,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,CAAC,SAAS,8BAA8B;YACjE,8CAA8C,SAAS,GAAG,CAC7D,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,CAAC,WAAW,0BAA0B;YAC/D,uBAAuB,CAC1B,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GACpD,IAA+B,CAAC;IAClC,KAAK,MAAM,CAAC;IAEZ,MAAM,GAAG,GAA4B;QACnC,UAAU,EAAE,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,EAAE;YAC/D,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,OAAO,CAAC,UAAU;QACtB,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ;QACvE,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3E,GAAG,IAAI;KACR,CAAC;IAEF,uEAAuE;IACvE,2EAA2E;IAC3E,OAAO,aAAa,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,6EAA6E;AAC7E,2EAA2E;AAC3E,2EAA2E;AAC3E,SAAS,mBAAmB,CAC1B,QAAiC;IAEjC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC;IACtC,KAAK,OAAO,CAAC;IACb,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/sdk",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "description": "Stigmer TypeScript SDK — typed API client for all Stigmer platform resources",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,11 +39,12 @@
   },
   "dependencies": {
     "@connectrpc/connect": "^2.0.0",
-    "@connectrpc/connect-web": "^2.0.0"
+    "@connectrpc/connect-web": "^2.0.0",
+    "yaml": "^2.8.2"
   },
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
-    "@stigmer/protos": "3.2.2"
+    "@stigmer/protos": "3.3.0"
   }
 }

package/src/__tests__/errors.test.ts

@@ -8,6 +8,7 @@ import {
   isTransientStreamError,
   getUserMessage,
   getErrorReason,
+  getRecordConstraint,
   annotateRpcError,
   getRpcMetadata,
   type ErrorCategory,
@@ -328,6 +329,63 @@ describe("getErrorReason", () => {
   });
 });
 
+describe("getRecordConstraint", () => {
+  const recordViolation = (metadata: Record<string, string>) =>
+    new ConnectError("that slot is already booked", Code.AlreadyExists, undefined, [
+      {
+        desc: ErrorInfoSchema,
+        value: {
+          domain: "datastore.stigmer.ai",
+          reason: "CONSTRAINT_VIOLATION",
+          metadata,
+        },
+      },
+    ]);
+
+  it("extracts the constraint name from a record-RPC violation", () => {
+    expect(getRecordConstraint(recordViolation({ constraint: "one_confirmed_per_slot" })))
+      .toBe("one_confirmed_per_slot");
+  });
+
+  it("walks the cause chain of an SDK-wrapped StigmerError", () => {
+    const connectError = recordViolation({ constraint: "one_confirmed_per_slot" });
+    const wrapped = new StigmerError(
+      "already-exists",
+      connectError.rawMessage,
+      Code.AlreadyExists,
+      { cause: connectError },
+    );
+    expect(getRecordConstraint(wrapped)).toBe("one_confirmed_per_slot");
+  });
+
+  it("returns null when the ErrorInfo domain is not the records domain", () => {
+    const foreign = new ConnectError("workspace taken", Code.FailedPrecondition, undefined, [
+      {
+        desc: ErrorInfoSchema,
+        value: {
+          domain: "stigmer.ai",
+          reason: "SLACK_WORKSPACE_ALREADY_CONNECTED",
+          metadata: { constraint: "should_not_leak" },
+        },
+      },
+    ]);
+    expect(getRecordConstraint(foreign)).toBeNull();
+  });
+
+  it("returns null when the violation carries no constraint metadata", () => {
+    expect(getRecordConstraint(recordViolation({}))).toBeNull();
+    expect(getRecordConstraint(recordViolation({ constraint: "" }))).toBeNull();
+  });
+
+  it("returns null for errors without ErrorInfo", () => {
+    expect(
+      getRecordConstraint(new ConnectError("bare", Code.AlreadyExists)),
+    ).toBeNull();
+    expect(getRecordConstraint(new Error("plain"))).toBeNull();
+    expect(getRecordConstraint(null)).toBeNull();
+  });
+});
+
 describe("annotateRpcError / getRpcMetadata", () => {
   it("roundtrips metadata on an error object", () => {
     const err = new Error("test");