@stigmer/sdk 3.12.5 → 3.12.7

package/src/gen/mcpserver.ts

@@ -1,16 +1,16 @@
 // Code generated by stigmer-codegen. DO NOT EDIT.
 
 import { wrapError } from "./errors.js";
-import { stripUndefined } from "./proto-utils.js";
+import { stripUndefined, toResourceRefInput } from "./proto-utils.js";
 import { type DeleteResourceInput, type ListParams, type ListResult, type ResourceRef } from "./types.js";
 import { create } from "@bufbuild/protobuf";
 import { createClient, type Client, type Transport } from "@connectrpc/connect";
-import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { EnvVarDeclarationSchema, type EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import { McpServerSchema, type McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
 import { ConnectInputSchema, InitiateOAuthConnectInputSchema, InitiateOAuthConnectOutputSchema, CompleteOAuthConnectInputSchema, CompleteOAuthConnectOutputSchema, DisconnectOAuthInputSchema, DisconnectOAuthOutputSchema, SetOrgOAuthAppInputSchema, SetOrgOAuthAppOutputSchema, DeleteOrgOAuthAppInputSchema, DeleteOrgOAuthAppOutputSchema, GetOAuthGrantStatusInputSchema, GetOAuthGrantStatusOutputSchema, GetOrgOAuthAppInputSchema, GetOrgOAuthAppOutputSchema, type ConnectInput, type InitiateOAuthConnectInput, type InitiateOAuthConnectOutput, type CompleteOAuthConnectInput, type CompleteOAuthConnectOutput, type DisconnectOAuthInput, type DisconnectOAuthOutput, type SetOrgOAuthAppInput, type SetOrgOAuthAppOutput, type DeleteOrgOAuthAppInput, type DeleteOrgOAuthAppOutput, type GetOAuthGrantStatusInput, type GetOAuthGrantStatusOutput, type GetOrgOAuthAppInput, type GetOrgOAuthAppOutput } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
-import { McpServerSpecSchema, StdioServerConfigSchema, HttpServerConfigSchema, ToolApprovalPolicySchema, McpServerAuthSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import { McpServerSpecSchema, StdioServerConfigSchema, HttpServerConfigSchema, ToolApprovalPolicySchema, McpServerAuthSchema, type StdioServerConfig, type HttpServerConfig, type ToolApprovalPolicy, type McpServerAuth } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { ApiResourceIdSchema, ApiResourceReferenceSchema, ApiResourceDeleteInputSchema, type UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -152,6 +152,14 @@ export class McpServerClient {
 
 /** Input for creating/updating a McpServer. */
 export interface McpServerInput {
+  /**
+   * The resource's `metadata.id`, for exact update addressing when set
+   * from a loaded resource. Required for updates to platform-scoped
+   * (org-less) kinds, where the org+slug fallback cannot match. On
+   * create, the cloud server stamps its own id regardless; the OSS
+   * server honors a caller-supplied id (existing apply semantics).
+   */
+  id?: string;
   name: string;
   slug?: string;
   org: string;
@@ -280,6 +288,7 @@ export function buildMcpServerProto(input: McpServerInput): McpServer {
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "McpServer",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -289,3 +298,86 @@ export function buildMcpServerProto(input: McpServerInput): McpServer {
     spec,
   }) as McpServer;
 }
+
+function toStdioServerConfigInput(msg: StdioServerConfig): StdioServerConfigInput {
+  return {
+    command: msg.command ?? "",
+    args: msg.args?.length ? [...msg.args] : undefined,
+    workingDir: msg.workingDir || undefined,
+  };
+}
+
+function toHttpServerConfigInput(msg: HttpServerConfig): HttpServerConfigInput {
+  return {
+    url: msg.url ?? "",
+    headers: Object.keys(msg.headers ?? {}).length > 0 ? { ...msg.headers } : undefined,
+    queryParams: Object.keys(msg.queryParams ?? {}).length > 0 ? { ...msg.queryParams } : undefined,
+    timeoutSeconds: msg.timeoutSeconds || undefined,
+  };
+}
+
+function toEnvVarDeclarationInput(msg: EnvVarDeclaration): EnvVarDeclarationInput {
+  return {
+    isSecret: msg.isSecret || undefined,
+    description: msg.description || undefined,
+    optional: msg.optional || undefined,
+  };
+}
+
+function toToolApprovalPolicyInput(msg: ToolApprovalPolicy): ToolApprovalPolicyInput {
+  return {
+    toolName: msg.toolName || undefined,
+    message: msg.message || undefined,
+    fromDestructiveHint: msg.fromDestructiveHint || undefined,
+  };
+}
+
+function toMcpServerAuthInput(msg: McpServerAuth): McpServerAuthInput {
+  return {
+    oauthAppRef: toResourceRefInput(msg.oauthAppRef),
+    targetEnvVar: msg.targetEnvVar || undefined,
+    tokenLifetimeHint: msg.tokenLifetimeHint || undefined,
+    scopeHints: msg.scopeHints?.length ? [...msg.scopeHints] : undefined,
+    discoveryUrl: msg.discoveryUrl || undefined,
+    oauthOnly: msg.oauthOnly || undefined,
+  };
+}
+
+/**
+ * Maps a fetched {@link McpServer} to a complete {@link McpServerInput} for `update()`.
+ *
+ * The update RPC replaces the ENTIRE spec — spread this mapper's output
+ * and override only the fields you edit (spread nested objects the same
+ * way):
+ *
+ *   await client.update({ ...toMcpServerUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toMcpServerUpdateInput(resource: McpServer): McpServerInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(McpServerSpecSchema);
+  return {
+    // Exact update addressing (id-first in the update pipeline) — for
+    // platform-scoped (org-less) kinds the org+slug fallback cannot
+    // match, so the id is the ONLY working address.
+    id: meta?.id || undefined,
+    name: meta?.name ?? "",
+    slug: meta?.slug || undefined,
+    org: meta?.org ?? "",
+    labels: meta?.labels && Object.keys(meta.labels).length > 0 ? { ...meta.labels } : undefined,
+    visibility: meta?.visibility || undefined,
+    description: spec.description || undefined,
+    iconUrl: spec.iconUrl || undefined,
+    tags: spec.tags?.length ? [...spec.tags] : undefined,
+    stdio: spec.serverType?.case === "stdio" ? toStdioServerConfigInput(spec.serverType.value) : undefined,
+    http: spec.serverType?.case === "http" ? toHttpServerConfigInput(spec.serverType.value) : undefined,
+    defaultEnabledTools: spec.defaultEnabledTools?.length ? [...spec.defaultEnabledTools] : undefined,
+    env: Object.keys(spec.env ?? {}).length > 0 ? Object.fromEntries(Object.entries(spec.env).map(([k, v]) => [k, toEnvVarDeclarationInput(v)])) : undefined,
+    pinnedToolApprovals: spec.pinnedToolApprovals?.length ? spec.pinnedToolApprovals.map(toToolApprovalPolicyInput) : undefined,
+    repositoryUrl: spec.repositoryUrl || undefined,
+    githubStars: spec.githubStars || undefined,
+    auth: spec.auth ? toMcpServerAuthInput(spec.auth) : undefined,
+  };
+}

package/src/gen/memory.ts

@@ -0,0 +1,164 @@
+// Code generated by stigmer-codegen. DO NOT EDIT.
+
+import { wrapError } from "./errors.js";
+import { stripUndefined } from "./proto-utils.js";
+import { create } from "@bufbuild/protobuf";
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { MemorySchema, type Memory } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
+import { MemoryCommandController } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/command_pb";
+import { MemoryIdSchema, ListMemoriesRequestSchema, MemoryListSchema, type ListMemoriesRequest, type MemoryList } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/io_pb";
+import { MemoryQueryController } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/query_pb";
+import { MemorySpecSchema, MemoryProvenanceSchema, type MemoryProvenance } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/spec_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+/** Provides operations on memory resources. */
+export class MemoryClient {
+  private readonly command: Client<typeof MemoryCommandController>;
+  private readonly query: Client<typeof MemoryQueryController>;
+
+  constructor(transport: Transport) {
+    this.command = createClient(MemoryCommandController, transport);
+    this.query = createClient(MemoryQueryController, transport);
+  }
+
+  async create(input: MemoryInput): Promise<Memory> {
+    try {
+      return await this.command.create(buildMemoryProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async update(input: MemoryInput): Promise<Memory> {
+    try {
+      return await this.command.update(buildMemoryProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async delete(id: string): Promise<Memory> {
+    try {
+      return await this.command.delete(create(MemoryIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async confirm(id: string): Promise<Memory> {
+    try {
+      return await this.command.confirm(create(MemoryIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async reject(id: string): Promise<Memory> {
+    try {
+      return await this.command.reject(create(MemoryIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async get(id: string): Promise<Memory> {
+    try {
+      return await this.query.get(create(MemoryIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async list(input: ListMemoriesRequest): Promise<MemoryList> {
+    try {
+      return await this.query.list(input);
+    } catch (e) { throw wrapError(e); }
+  }
+}
+
+/** Input for creating/updating a Memory. */
+export interface MemoryInput {
+  /**
+   * The resource's `metadata.id`, for exact update addressing when set
+   * from a loaded resource. Required for updates to platform-scoped
+   * (org-less) kinds, where the org+slug fallback cannot match. On
+   * create, the cloud server stamps its own id regardless; the OSS
+   * server honors a caller-supplied id (existing apply semantics).
+   */
+  id?: string;
+  name: string;
+  slug?: string;
+  org: string;
+  labels?: Record<string, string>;
+  visibility?: ApiResourceVisibility;
+  content?: string;
+  subjectIdentityAccountId?: string;
+  provenance?: MemoryProvenanceInput;
+}
+
+/** SDK input type for MemoryProvenance. */
+export interface MemoryProvenanceInput {
+  agentId?: string;
+  sessionId?: string;
+  agentExecutionId?: string;
+  toolCallId?: string;
+}
+
+function buildMemoryProvenanceProto(input: MemoryProvenanceInput) {
+  return Object.assign(create(MemoryProvenanceSchema), stripUndefined({
+    agentId: input.agentId,
+    sessionId: input.sessionId,
+    agentExecutionId: input.agentExecutionId,
+    toolCallId: input.toolCallId,
+  }));
+}
+
+export function buildMemoryProto(input: MemoryInput): Memory {
+  const provenance = input.provenance ? buildMemoryProvenanceProto(input.provenance) : undefined;
+  return Object.assign(create(MemorySchema), {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Memory",
+    metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
+      name: input.name,
+      org: input.org,
+      ...(input.slug && { slug: input.slug }),
+      ...(input.labels && { labels: input.labels }),
+      ...(input.visibility && { visibility: input.visibility }),
+    }),
+    spec: Object.assign(create(MemorySpecSchema), stripUndefined({
+      content: input.content,
+      subjectIdentityAccountId: input.subjectIdentityAccountId,
+      provenance,
+    })),
+  }) as Memory;
+}
+
+function toMemoryProvenanceInput(msg: MemoryProvenance): MemoryProvenanceInput {
+  return {
+    agentId: msg.agentId || undefined,
+    sessionId: msg.sessionId || undefined,
+    agentExecutionId: msg.agentExecutionId || undefined,
+    toolCallId: msg.toolCallId || undefined,
+  };
+}
+
+/**
+ * Maps a fetched {@link Memory} to a complete {@link MemoryInput} for `update()`.
+ *
+ * The update RPC replaces the ENTIRE spec — spread this mapper's output
+ * and override only the fields you edit (spread nested objects the same
+ * way):
+ *
+ *   await client.update({ ...toMemoryUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toMemoryUpdateInput(resource: Memory): MemoryInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(MemorySpecSchema);
+  return {
+    // Exact update addressing (id-first in the update pipeline) — for
+    // platform-scoped (org-less) kinds the org+slug fallback cannot
+    // match, so the id is the ONLY working address.
+    id: meta?.id || undefined,
+    name: meta?.name ?? "",
+    slug: meta?.slug || undefined,
+    org: meta?.org ?? "",
+    labels: meta?.labels && Object.keys(meta.labels).length > 0 ? { ...meta.labels } : undefined,
+    visibility: meta?.visibility || undefined,
+    content: spec.content || undefined,
+    subjectIdentityAccountId: spec.subjectIdentityAccountId || undefined,
+    provenance: spec.provenance ? toMemoryProvenanceInput(spec.provenance) : undefined,
+  };
+}

package/src/gen/oauthapp.ts

@@ -74,6 +74,14 @@ export class OAuthAppClient {
 
 /** Input for creating/updating a OAuthApp. */
 export interface OAuthAppInput {
+  /**
+   * The resource's `metadata.id`, for exact update addressing when set
+   * from a loaded resource. Required for updates to platform-scoped
+   * (org-less) kinds, where the org+slug fallback cannot match. On
+   * create, the cloud server stamps its own id regardless; the OSS
+   * server honors a caller-supplied id (existing apply semantics).
+   */
+  id?: string;
   name: string;
   slug?: string;
   org: string;
@@ -97,6 +105,7 @@ export function buildOAuthAppProto(input: OAuthAppInput): OAuthApp {
     apiVersion: "iam.stigmer.ai/v1",
     kind: "OAuthApp",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -118,3 +127,42 @@ export function buildOAuthAppProto(input: OAuthAppInput): OAuthApp {
     })),
   }) as OAuthApp;
 }
+
+/**
+ * Maps a fetched {@link OAuthApp} to a complete {@link OAuthAppInput} for `update()`.
+ *
+ * The update RPC replaces the ENTIRE spec — spread this mapper's output
+ * and override only the fields you edit (spread nested objects the same
+ * way):
+ *
+ *   await client.update({ ...toOAuthAppUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toOAuthAppUpdateInput(resource: OAuthApp): OAuthAppInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(OAuthAppSpecSchema);
+  return {
+    // Exact update addressing (id-first in the update pipeline) — for
+    // platform-scoped (org-less) kinds the org+slug fallback cannot
+    // match, so the id is the ONLY working address.
+    id: meta?.id || undefined,
+    name: meta?.name ?? "",
+    slug: meta?.slug || undefined,
+    org: meta?.org ?? "",
+    labels: meta?.labels && Object.keys(meta.labels).length > 0 ? { ...meta.labels } : undefined,
+    visibility: meta?.visibility || undefined,
+    provider: spec.provider || undefined,
+    clientId: spec.clientId || undefined,
+    clientSecret: spec.clientSecret || undefined,
+    authorizationUrl: spec.authorizationUrl || undefined,
+    tokenUrl: spec.tokenUrl || undefined,
+    scopes: spec.scopes?.length ? [...spec.scopes] : undefined,
+    userinfoUrl: spec.userinfoUrl || undefined,
+    scopeParameterName: spec.scopeParameterName || undefined,
+    vendorApprovalStatus: spec.vendorApprovalStatus || undefined,
+    vendorApprovalDocsUrl: spec.vendorApprovalDocsUrl || undefined,
+    tokenEndpointAuthMethod: spec.tokenEndpointAuthMethod || undefined,
+  };
+}

package/src/gen/organization.ts

@@ -1,7 +1,7 @@
 // Code generated by stigmer-codegen. DO NOT EDIT.
 
 import { wrapError } from "./errors.js";
-import { stripUndefined } from "./proto-utils.js";
+import { stripUndefined, toResourceRefInput } from "./proto-utils.js";
 import { type ResourceRef } from "./types.js";
 import { create } from "@bufbuild/protobuf";
 import { EmptySchema } from "@bufbuild/protobuf/wkt";
@@ -14,7 +14,7 @@ import { OrganizationCommandController } from "@stigmer/protos/ai/stigmer/tenanc
 import { ManagementMode } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/enum_pb";
 import { OrganizationIdSchema, OrganizationListSchema, OrganizationsSchema, OrganizationExternalLookupSchema, type OrganizationList, type Organizations, type OrganizationExternalLookup } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/io_pb";
 import { OrganizationQueryController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/query_pb";
-import { OrganizationSpecSchema, OrganizationPreferencesSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/spec_pb";
+import { OrganizationSpecSchema, OrganizationPreferencesSchema, type OrganizationPreferences } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/spec_pb";
 
 /** Provides operations on organization resources. */
 export class OrganizationClient {
@@ -77,6 +77,14 @@ export class OrganizationClient {
 
 /** Input for creating/updating a Organization. */
 export interface OrganizationInput {
+  /**
+   * The resource's `metadata.id`, for exact update addressing when set
+   * from a loaded resource. Required for updates to platform-scoped
+   * (org-less) kinds, where the org+slug fallback cannot match. On
+   * create, the cloud server stamps its own id regardless; the OSS
+   * server honors a caller-supplied id (existing apply semantics).
+   */
+  id?: string;
   name: string;
   slug?: string;
   org: string;
@@ -94,11 +102,13 @@ export interface OrganizationInput {
 /** SDK input type for OrganizationPreferences. */
 export interface OrganizationPreferencesInput {
   standingContext?: string;
+  memoryEnabled?: boolean;
 }
 
 function buildOrganizationPreferencesProto(input: OrganizationPreferencesInput) {
   return Object.assign(create(OrganizationPreferencesSchema), stripUndefined({
     standingContext: input.standingContext,
+    memoryEnabled: input.memoryEnabled,
   }));
 }
 
@@ -109,6 +119,7 @@ export function buildOrganizationProto(input: OrganizationInput): Organization {
     apiVersion: "tenancy.stigmer.ai/v1",
     kind: "Organization",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -126,3 +137,45 @@ export function buildOrganizationProto(input: OrganizationInput): Organization {
     })),
   }) as Organization;
 }
+
+function toOrganizationPreferencesInput(msg: OrganizationPreferences): OrganizationPreferencesInput {
+  return {
+    standingContext: msg.standingContext || undefined,
+    memoryEnabled: msg.memoryEnabled || undefined,
+  };
+}
+
+/**
+ * Maps a fetched {@link Organization} to a complete {@link OrganizationInput} for `update()`.
+ *
+ * The update RPC replaces the ENTIRE spec — spread this mapper's output
+ * and override only the fields you edit (spread nested objects the same
+ * way):
+ *
+ *   await client.update({ ...toOrganizationUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toOrganizationUpdateInput(resource: Organization): OrganizationInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(OrganizationSpecSchema);
+  return {
+    // Exact update addressing (id-first in the update pipeline) — for
+    // platform-scoped (org-less) kinds the org+slug fallback cannot
+    // match, so the id is the ONLY working address.
+    id: meta?.id || undefined,
+    name: meta?.name ?? "",
+    slug: meta?.slug || undefined,
+    org: meta?.org || meta?.slug || "",
+    labels: meta?.labels && Object.keys(meta.labels).length > 0 ? { ...meta.labels } : undefined,
+    visibility: meta?.visibility || undefined,
+    description: spec.description || undefined,
+    logoUrl: spec.logoUrl || undefined,
+    managementMode: spec.managementMode || undefined,
+    identityProviderRef: toResourceRefInput(spec.identityProviderRef),
+    externalOrgId: spec.externalOrgId || undefined,
+    isPersonal: spec.isPersonal || undefined,
+    preferences: spec.preferences ? toOrganizationPreferencesInput(spec.preferences) : undefined,
+  };
+}

package/src/gen/platformclient.ts

@@ -1,9 +1,10 @@
 // Code generated by stigmer-codegen. DO NOT EDIT.
 
 import { wrapError } from "./errors.js";
-import { stripUndefined, toTimestamp } from "./proto-utils.js";
+import { stripUndefined, toTimestamp, toResourceRefInputs } from "./proto-utils.js";
 import { type DeleteResourceInput, type ResourceRef } from "./types.js";
 import { create } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
 import { createClient, type Client, type Transport } from "@connectrpc/connect";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
@@ -90,6 +91,14 @@ export class PlatformClientClient {
 
 /** Input for creating/updating a PlatformClient. */
 export interface PlatformClientInput {
+  /**
+   * The resource's `metadata.id`, for exact update addressing when set
+   * from a loaded resource. Required for updates to platform-scoped
+   * (org-less) kinds, where the org+slug fallback cannot match. On
+   * create, the cloud server stamps its own id regardless; the OSS
+   * server honors a caller-supplied id (existing apply semantics).
+   */
+  id?: string;
   name: string;
   slug?: string;
   org: string;
@@ -114,6 +123,7 @@ export function buildPlatformClientProto(input: PlatformClientInput): PlatformCl
     apiVersion: "iam.stigmer.ai/v1",
     kind: "PlatformClient",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -134,3 +144,41 @@ export function buildPlatformClientProto(input: PlatformClientInput): PlatformCl
     })),
   }) as PlatformClient;
 }
+
+/**
+ * Maps a fetched {@link PlatformClient} to a complete {@link PlatformClientInput} for `update()`.
+ *
+ * The update RPC replaces the ENTIRE spec — spread this mapper's output
+ * and override only the fields you edit (spread nested objects the same
+ * way):
+ *
+ *   await client.update({ ...toPlatformClientUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toPlatformClientUpdateInput(resource: PlatformClient): PlatformClientInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(PlatformClientSpecSchema);
+  return {
+    // Exact update addressing (id-first in the update pipeline) — for
+    // platform-scoped (org-less) kinds the org+slug fallback cannot
+    // match, so the id is the ONLY working address.
+    id: meta?.id || undefined,
+    name: meta?.name ?? "",
+    slug: meta?.slug || undefined,
+    org: meta?.org ?? "",
+    labels: meta?.labels && Object.keys(meta.labels).length > 0 ? { ...meta.labels } : undefined,
+    visibility: meta?.visibility || undefined,
+    clientId: spec.clientId || undefined,
+    clientSecretHash: spec.clientSecretHash || undefined,
+    secretFingerprint: spec.secretFingerprint || undefined,
+    expiresAt: spec.expiresAt ? timestampDate(spec.expiresAt) : undefined,
+    neverExpires: spec.neverExpires || undefined,
+    autoProvisionAccounts: spec.autoProvisionAccounts || undefined,
+    autoGrantOnOrg: spec.autoGrantOnOrg || undefined,
+    autoGrantRole: spec.autoGrantRole || undefined,
+    allowedOrigins: spec.allowedOrigins?.length ? [...spec.allowedOrigins] : undefined,
+    environmentRefs: toResourceRefInputs(spec.environmentRefs),
+  };
+}

package/src/gen/project.ts

@@ -1,7 +1,7 @@
 // Code generated by stigmer-codegen. DO NOT EDIT.
 
 import { wrapError } from "./errors.js";
-import { stripUndefined } from "./proto-utils.js";
+import { stripUndefined, toResourceRefInputs } from "./proto-utils.js";
 import { type ResourceRef } from "./types.js";
 import { create } from "@bufbuild/protobuf";
 import { createClient, type Client, type Transport } from "@connectrpc/connect";
@@ -64,6 +64,14 @@ export class ProjectClient {
 
 /** Input for creating/updating a Project. */
 export interface ProjectInput {
+  /**
+   * The resource's `metadata.id`, for exact update addressing when set
+   * from a loaded resource. Required for updates to platform-scoped
+   * (org-less) kinds, where the org+slug fallback cannot match. On
+   * create, the cloud server stamps its own id regardless; the OSS
+   * server honors a caller-supplied id (existing apply semantics).
+   */
+  id?: string;
   name: string;
   slug?: string;
   org: string;
@@ -80,6 +88,7 @@ export function buildProjectProto(input: ProjectInput): Project {
     apiVersion: "tenancy.stigmer.ai/v1",
     kind: "Project",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -93,3 +102,34 @@ export function buildProjectProto(input: ProjectInput): Project {
     })),
   }) as Project;
 }
+
+/**
+ * Maps a fetched {@link Project} to a complete {@link ProjectInput} for `update()`.
+ *
+ * The update RPC replaces the ENTIRE spec — spread this mapper's output
+ * and override only the fields you edit (spread nested objects the same
+ * way):
+ *
+ *   await client.update({ ...toProjectUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toProjectUpdateInput(resource: Project): ProjectInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(ProjectSpecSchema);
+  return {
+    // Exact update addressing (id-first in the update pipeline) — for
+    // platform-scoped (org-less) kinds the org+slug fallback cannot
+    // match, so the id is the ONLY working address.
+    id: meta?.id || undefined,
+    name: meta?.name ?? "",
+    slug: meta?.slug || undefined,
+    org: meta?.org ?? "",
+    labels: meta?.labels && Object.keys(meta.labels).length > 0 ? { ...meta.labels } : undefined,
+    visibility: meta?.visibility || undefined,
+    entryPoint: spec.entryPoint || undefined,
+    description: spec.description || undefined,
+    members: toResourceRefInputs(spec.members),
+  };
+}

package/src/gen/proto-utils.ts

@@ -1,6 +1,10 @@
 // Code generated by stigmer-codegen. DO NOT EDIT.
 
 import { timestampFromDate, type Timestamp } from "@bufbuild/protobuf/wkt";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { EnvironmentSpec, EnvironmentValue } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import type { ExecutionValue } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import type { EnvSpecInput, EnvVarInput, ResourceRef } from "./types.js";
 
 /**
  * Remove keys whose values are `undefined` so that `Object.assign`
@@ -24,3 +28,63 @@ export function toTimestamp(value: Date | string): Timestamp {
   const date = value instanceof Date ? value : new Date(value);
   return timestampFromDate(date);
 }
+
+/**
+ * Narrow a fetched ApiResourceReference to the ResourceRef input shape,
+ * or `undefined` when the reference is absent/empty (the builders treat a
+ * ref without org and slug as "no reference"). `version` is preserved —
+ * dropping it would reset a pinned reference to "latest". `kind` is also
+ * preserved: builders overwrite it where the proto annotates a reference
+ * kind, but refs without that annotation (e.g. an organization's
+ * identityProviderRef) carry the stored kind, so dropping it would be
+ * lossy.
+ */
+export function toResourceRefInput(ref: ApiResourceReference | undefined): ResourceRef | undefined {
+  if (!ref || (!ref.org && !ref.slug)) return undefined;
+  return {
+    org: ref.org,
+    slug: ref.slug,
+    ...(ref.version && { version: ref.version }),
+    ...(ref.kind && { kind: ref.kind }),
+  };
+}
+
+/**
+ * Map a repeated ApiResourceReference to ResourceRef inputs, or `undefined`
+ * when the list is absent/empty (the mappers' canonical shape for empty
+ * lists).
+ */
+export function toResourceRefInputs(refs: ApiResourceReference[] | undefined): ResourceRef[] | undefined {
+  if (!refs || refs.length === 0) return undefined;
+  return refs.map((r) => toResourceRefInput(r) ?? { org: "", slug: "" });
+}
+
+/**
+ * Convert a fetched EnvironmentSpec to the EnvSpecInput shape, or
+ * `undefined` when absent/empty.
+ */
+export function toEnvSpecInput(spec: EnvironmentSpec | undefined): EnvSpecInput | undefined {
+  if (!spec) return undefined;
+  const variables = toEnvVarInputMap(spec.data);
+  return variables ? { variables } : undefined;
+}
+
+/**
+ * Convert a map of EnvironmentValue to EnvVarInput entries, or `undefined`
+ * when the map is absent/empty.
+ */
+export function toEnvVarInputMap(data: Record<string, EnvironmentValue> | undefined): Record<string, EnvVarInput> | undefined {
+  if (!data || Object.keys(data).length === 0) return undefined;
+  return Object.fromEntries(Object.entries(data).map(([k, v]) =>
+    [k, { value: v.value, isSecret: v.isSecret || undefined, description: v.description || undefined }]));
+}
+
+/**
+ * Convert a map of ExecutionValue to EnvVarInput entries, or `undefined`
+ * when the map is absent/empty.
+ */
+export function toExecVarInputMap(data: Record<string, ExecutionValue> | undefined): Record<string, EnvVarInput> | undefined {
+  if (!data || Object.keys(data).length === 0) return undefined;
+  return Object.fromEntries(Object.entries(data).map(([k, v]) =>
+    [k, { value: v.value, isSecret: v.isSecret || undefined }]));
+}