@stigmer/sdk 3.12.5 → 3.12.6

package/src/__tests__/update-input.test.ts

@@ -14,12 +14,14 @@ import {
 } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
 import { IdentityAccountSpecSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
 import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/enum_pb";
-import { buildOrganizationProto } from "../gen/organization";
-import { buildIdentityAccountProto } from "../gen/identityaccount";
 import {
+  buildOrganizationProto,
   toOrganizationUpdateInput,
+} from "../gen/organization";
+import {
+  buildIdentityAccountProto,
   toIdentityAccountUpdateInput,
-} from "../update-input";
+} from "../gen/identityaccount";
 
 /**
  * Update RPCs are full-spec replacements, so a complete mapper must
@@ -139,6 +141,14 @@ describe("toOrganizationUpdateInput", () => {
 
     expect(toOrganizationUpdateInput(org).org).toBe("bare");
   });
+
+  it("carries metadata.id for exact update addressing", () => {
+    const built = buildOrganizationProto(
+      toOrganizationUpdateInput(fullOrganization()),
+    );
+
+    expect(built.metadata?.id).toBe("acme");
+  });
 });
 
 describe("toIdentityAccountUpdateInput", () => {
@@ -163,6 +173,27 @@ describe("toIdentityAccountUpdateInput", () => {
     expect(input.slug).toBe("ada-lovelace");
   });
 
+  it("carries metadata.id — the ONLY address that works for a real (org-less) account", () => {
+    // Identity accounts are platform-scoped: metadata.org is never set in
+    // production, so the pipeline's org+slug fallback structurally cannot
+    // match one. Without the id, this update is NOT_FOUND by construction.
+    const account = create(IdentityAccountSchema, {
+      metadata: {
+        id: "ida_01JEXAMPLE",
+        name: "ada@acme.example",
+        slug: "ada-acme-example",
+      },
+      spec: { idpId: "auth0|abc123" },
+    });
+
+    const built = buildIdentityAccountProto(
+      toIdentityAccountUpdateInput(account),
+    );
+
+    expect(built.metadata?.id).toBe("ida_01JEXAMPLE");
+    expect(built.metadata?.slug).toBe("ada-acme-example");
+  });
+
   it("preserves the rest of the spec when a caller overrides only preferences", () => {
     const account = fullIdentityAccount();
     const mapped = toIdentityAccountUpdateInput(account);

package/src/gen/agent.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, toResourceRefInputs } from "./proto-utils.js";
 import { type ListParams, type ListResult, type ResourceRef } from "./types.js";
 import { create } from "@bufbuild/protobuf";
 import { createClient, type Client, type Transport } from "@connectrpc/connect";
@@ -9,8 +9,8 @@ import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agen
 import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
 import { AgentIdSchema, GetDefaultAgentRequestSchema, type GetDefaultAgentRequest } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
 import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
-import { AgentSpecSchema, ToolApprovalOverrideSchema, McpServerUsageSchema, McpAccessSchema, SubAgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
-import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { AgentSpecSchema, ToolApprovalOverrideSchema, McpServerUsageSchema, McpAccessSchema, SubAgentSchema, type ToolApprovalOverride, type McpServerUsage, type McpAccess, type SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { EnvVarDeclarationSchema, type EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/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 { ApiResourceReferenceSchema, type UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -100,6 +100,14 @@ export class AgentClient {
 
 /** Input for creating/updating a Agent. */
 export interface AgentInput {
+  /**
+   * 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;
@@ -205,6 +213,7 @@ export function buildAgentProto(input: AgentInput): Agent {
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "Agent",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -222,3 +231,80 @@ export function buildAgentProto(input: AgentInput): Agent {
     })),
   }) as Agent;
 }
+
+function toToolApprovalOverrideInput(msg: ToolApprovalOverride): ToolApprovalOverrideInput {
+  return {
+    toolName: msg.toolName || undefined,
+    requiresApproval: msg.requiresApproval || undefined,
+    message: msg.message || undefined,
+  };
+}
+
+function toMcpServerUsageInput(msg: McpServerUsage): McpServerUsageInput {
+  return {
+    mcpServerRef: toResourceRefInput(msg.mcpServerRef) ?? { org: "", slug: "" },
+    enabledTools: msg.enabledTools?.length ? [...msg.enabledTools] : undefined,
+    toolApprovalOverrides: msg.toolApprovalOverrides?.length ? msg.toolApprovalOverrides.map(toToolApprovalOverrideInput) : undefined,
+  };
+}
+
+function toMcpAccessInput(msg: McpAccess): McpAccessInput {
+  return {
+    mcpServer: msg.mcpServer ?? "",
+    enabledTools: msg.enabledTools?.length ? [...msg.enabledTools] : undefined,
+  };
+}
+
+function toSubAgentInput(msg: SubAgent): SubAgentInput {
+  return {
+    name: msg.name ?? "",
+    description: msg.description || undefined,
+    instructions: msg.instructions || undefined,
+    mcpAccess: msg.mcpAccess?.length ? msg.mcpAccess.map(toMcpAccessInput) : undefined,
+    skillRefs: toResourceRefInputs(msg.skillRefs),
+    modelOverride: msg.modelOverride || undefined,
+  };
+}
+
+function toEnvVarDeclarationInput(msg: EnvVarDeclaration): EnvVarDeclarationInput {
+  return {
+    isSecret: msg.isSecret || undefined,
+    description: msg.description || undefined,
+    optional: msg.optional || undefined,
+  };
+}
+
+/**
+ * Maps a fetched {@link Agent} to a complete {@link AgentInput} 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({ ...toAgentUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toAgentUpdateInput(resource: Agent): AgentInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(AgentSpecSchema);
+  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,
+    instructions: spec.instructions || undefined,
+    mcpServerUsages: spec.mcpServerUsages?.length ? spec.mcpServerUsages.map(toMcpServerUsageInput) : undefined,
+    skillRefs: toResourceRefInputs(spec.skillRefs),
+    subAgents: spec.subAgents?.length ? spec.subAgents.map(toSubAgentInput) : undefined,
+    env: Object.keys(spec.env ?? {}).length > 0 ? Object.fromEntries(Object.entries(spec.env).map(([k, v]) => [k, toEnvVarDeclarationInput(v)])) : undefined,
+  };
+}

package/src/gen/agentchannel.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, 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";
@@ -15,9 +15,9 @@ import { ChannelMessageCommandController } from "@stigmer/protos/ai/stigmer/agen
 import { SendChannelMessageOutputSchema, SendChannelMessageInputSchema, ListChannelTemplatesInputSchema, ChannelTemplatesSchema, ListMessagingChannelsInputSchema, MessagingChannelsSchema, type SendChannelMessageOutput, type SendChannelMessageInput, type ListChannelTemplatesInput, type ChannelTemplates, type ListMessagingChannelsInput, type MessagingChannels } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
 import { ChannelMessageQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_query_pb";
 import { AgentChannelQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/query_pb";
-import { AgentChannelSpecSchema, SlackChannelConfigSchema, WhatsAppChannelConfigSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/spec_pb";
-import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { RunConfigSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/invocation_pb";
+import { AgentChannelSpecSchema, SlackChannelConfigSchema, WhatsAppChannelConfigSchema, type SlackChannelConfig, type WhatsAppChannelConfig } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/spec_pb";
+import { ServiceTier, ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { RunConfigSchema, type RunConfig } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/invocation_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 { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -176,6 +176,14 @@ export class AgentChannelClient {
 
 /** Input for creating/updating a AgentChannel. */
 export interface AgentChannelInput {
+  /**
+   * 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;
@@ -206,6 +214,7 @@ export interface RunConfigInput {
   maxCostUsd?: number;
   maxToolRounds?: number;
   serviceTier?: ServiceTier;
+  thinkingMode?: ThinkingMode;
 }
 
 function buildSlackChannelConfigProto(input: SlackChannelConfigInput) {
@@ -225,6 +234,7 @@ function buildRunConfigProto(input: RunConfigInput) {
     maxCostUsd: input.maxCostUsd,
     maxToolRounds: input.maxToolRounds,
     serviceTier: input.serviceTier,
+    thinkingMode: input.thinkingMode,
   }));
 }
 
@@ -250,6 +260,7 @@ export function buildAgentChannelProto(input: AgentChannelInput): AgentChannel {
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "AgentChannel",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -259,3 +270,60 @@ export function buildAgentChannelProto(input: AgentChannelInput): AgentChannel {
     spec,
   }) as AgentChannel;
 }
+
+function toSlackChannelConfigInput(msg: SlackChannelConfig): SlackChannelConfigInput {
+  return {
+  };
+}
+
+function toWhatsAppChannelConfigInput(msg: WhatsAppChannelConfig): WhatsAppChannelConfigInput {
+  return {
+    phoneNumberId: msg.phoneNumberId || undefined,
+  };
+}
+
+function toRunConfigInput(msg: RunConfig): RunConfigInput {
+  return {
+    modelName: msg.modelName || undefined,
+    maxCostUsd: msg.maxCostUsd || undefined,
+    maxToolRounds: msg.maxToolRounds || undefined,
+    serviceTier: msg.serviceTier || undefined,
+    thinkingMode: msg.thinkingMode || undefined,
+  };
+}
+
+/**
+ * Maps a fetched {@link AgentChannel} to a complete {@link AgentChannelInput} 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({ ...toAgentChannelUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toAgentChannelUpdateInput(resource: AgentChannel): AgentChannelInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(AgentChannelSpecSchema);
+  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,
+    agentRef: toResourceRefInput(spec.agentRef) ?? { org: "", slug: "" },
+    enabled: spec.enabled || undefined,
+    slack: spec.providerConfig?.case === "slack" ? toSlackChannelConfigInput(spec.providerConfig.value) : undefined,
+    whatsapp: spec.providerConfig?.case === "whatsapp" ? toWhatsAppChannelConfigInput(spec.providerConfig.value) : undefined,
+    environmentRefs: toResourceRefInputs(spec.environmentRefs),
+    appRef: toResourceRefInput(spec.appRef),
+    proactiveMessagingEnabled: spec.proactiveMessagingEnabled || undefined,
+    runConfig: spec.runConfig ? toRunConfigInput(spec.runConfig) : undefined,
+  };
+}

package/src/gen/agentexecution.ts

@@ -1,21 +1,22 @@
 // Code generated by stigmer-codegen. DO NOT EDIT.
 
 import { wrapError } from "./errors.js";
-import { stripUndefined, toTimestamp } from "./proto-utils.js";
+import { stripUndefined, toTimestamp, toResourceRefInput, toResourceRefInputs, toExecVarInputMap } from "./proto-utils.js";
 import { type ResourceRef, type EnvVarInput } from "./types.js";
 import { create, type JsonObject } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
 import { createClient, type Client, type Transport } from "@connectrpc/connect";
-import { ToolApprovalOverrideSchema, McpServerUsageSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { ToolApprovalOverrideSchema, McpServerUsageSchema, type ToolApprovalOverride, type McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import { AgentExecutionSchema, type AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
-import { InteractionMode, ApprovalMode, ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { InteractionMode, ApprovalMode, ServiceTier, ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { AgentExecutionIdSchema, AgentExecutionUpdateStatusInputSchema, UpdateStatusResponseSchema, SubmitApprovalInputSchema, SubmitFileDecisionInputSchema, CancelAgentExecutionInputSchema, TerminateAgentExecutionInputSchema, RecoverAgentExecutionInputSchema, PauseAgentExecutionInputSchema, ResumeAgentExecutionInputSchema, UploadAttachmentRequestSchema, UploadAttachmentResponseSchema, ListAgentExecutionsRequestSchema, AgentExecutionListSchema, ListAgentExecutionsBySessionRequestSchema, GetArtifactDownloadUrlRequestSchema, GetArtifactDownloadUrlResponseSchema, GetArtifactContentRequestSchema, GetArtifactContentResponseSchema, GetExecutionUsageReportInputSchema, GetExecutionUsageReportOutputSchema, GetSessionUsageReportInputSchema, GetSessionUsageReportOutputSchema, GetAgentUsageReportInputSchema, GetAgentUsageReportOutputSchema, GetOrgUsageReportInputSchema, GetOrgUsageReportOutputSchema, GetAgentExecutionSummaryRequestSchema, AgentExecutionSummarySchema, type AgentExecutionUpdateStatusInput, type UpdateStatusResponse, type SubmitApprovalInput, type SubmitFileDecisionInput, type CancelAgentExecutionInput, type TerminateAgentExecutionInput, type RecoverAgentExecutionInput, type PauseAgentExecutionInput, type ResumeAgentExecutionInput, type UploadAttachmentRequest, type UploadAttachmentResponse, type ListAgentExecutionsRequest, type AgentExecutionList, type ListAgentExecutionsBySessionRequest, type GetArtifactDownloadUrlRequest, type GetArtifactDownloadUrlResponse, type GetArtifactContentRequest, type GetArtifactContentResponse, type GetExecutionUsageReportInput, type GetExecutionUsageReportOutput, type GetSessionUsageReportInput, type GetSessionUsageReportOutput, type GetAgentUsageReportInput, type GetAgentUsageReportOutput, type GetOrgUsageReportInput, type GetOrgUsageReportOutput, type GetAgentExecutionSummaryRequest, type AgentExecutionSummary } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
 import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
-import { AgentExecutionSpecSchema, ContextManagementConfigSchema, ExecutionConfigSchema, AttachmentSchema, ConversationCatchupSchema, DeclaredPreferencesSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { AgentExecutionSpecSchema, ContextManagementConfigSchema, ExecutionConfigSchema, AttachmentSchema, ConversationCatchupSchema, DeclaredPreferencesSchema, type ContextManagementConfig, type ExecutionConfig, type Attachment, type ConversationCatchup, type DeclaredPreferences } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
 import { Harness, CursorMode, ExecutionTarget, GitWriteBackMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
-import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
-import { GitRepoSourceSchema, LocalPathSourceSchema, WorkspaceSourceSchema, WorkspaceEntrySchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import { SessionSpecSchema, type SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
+import { GitRepoSourceSchema, LocalPathSourceSchema, WorkspaceSourceSchema, WorkspaceEntrySchema, type GitRepoSource, type LocalPathSource, type WorkspaceSource, type WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { ApiResourceIdSchema, ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
@@ -173,6 +174,14 @@ export class AgentExecutionClient {
 
 /** Input for creating/updating a AgentExecution. */
 export interface AgentExecutionInput {
+  /**
+   * 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;
@@ -262,6 +271,7 @@ export interface ExecutionConfigInput {
   buildFromPlan?: boolean;
   approvalMode?: ApprovalMode;
   serviceTier?: ServiceTier;
+  thinkingMode?: ThinkingMode;
 }
 
 /** SDK input type for ContextManagementConfig. */
@@ -378,6 +388,7 @@ function buildExecutionConfigProto(input: ExecutionConfigInput) {
   if (input.buildFromPlan !== undefined) msg.buildFromPlan = input.buildFromPlan;
   if (input.approvalMode !== undefined) msg.approvalMode = input.approvalMode;
   if (input.serviceTier !== undefined) msg.serviceTier = input.serviceTier;
+  if (input.thinkingMode !== undefined) msg.thinkingMode = input.thinkingMode;
   return msg;
 }
 
@@ -421,6 +432,7 @@ export function buildAgentExecutionProto(input: AgentExecutionInput): AgentExecu
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "AgentExecution",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -446,3 +458,157 @@ export function buildAgentExecutionProto(input: AgentExecutionInput): AgentExecu
     })),
   }) as AgentExecution;
 }
+
+function toGitRepoSourceInput(msg: GitRepoSource): GitRepoSourceInput {
+  return {
+    url: msg.url ?? "",
+    branch: msg.branch || undefined,
+    commit: msg.commit || undefined,
+    depth: msg.depth || undefined,
+    writeBackMode: msg.writeBackMode || undefined,
+  };
+}
+
+function toLocalPathSourceInput(msg: LocalPathSource): LocalPathSourceInput {
+  return {
+    path: msg.path || undefined,
+  };
+}
+
+function toWorkspaceSourceInput(msg: WorkspaceSource): WorkspaceSourceInput {
+  return {
+    gitRepo: msg.source?.case === "gitRepo" ? toGitRepoSourceInput(msg.source.value) : undefined,
+    localPath: msg.source?.case === "localPath" ? toLocalPathSourceInput(msg.source.value) : undefined,
+  };
+}
+
+function toWorkspaceEntryInput(msg: WorkspaceEntry): WorkspaceEntryInput {
+  return {
+    name: msg.name || undefined,
+    source: toWorkspaceSourceInput(msg.source ?? create(WorkspaceSourceSchema)),
+  };
+}
+
+function toToolApprovalOverrideInput(msg: ToolApprovalOverride): ToolApprovalOverrideInput {
+  return {
+    toolName: msg.toolName || undefined,
+    requiresApproval: msg.requiresApproval || undefined,
+    message: msg.message || undefined,
+  };
+}
+
+function toMcpServerUsageInput(msg: McpServerUsage): McpServerUsageInput {
+  return {
+    mcpServerRef: toResourceRefInput(msg.mcpServerRef) ?? { org: "", slug: "" },
+    enabledTools: msg.enabledTools?.length ? [...msg.enabledTools] : undefined,
+    toolApprovalOverrides: msg.toolApprovalOverrides?.length ? msg.toolApprovalOverrides.map(toToolApprovalOverrideInput) : undefined,
+  };
+}
+
+function toSessionSpecInput(msg: SessionSpec): SessionSpecInput {
+  return {
+    agentInstanceId: msg.agentInstanceId || undefined,
+    subject: msg.subject || undefined,
+    harnessStateId: msg.harnessStateId || undefined,
+    harnessStateIdHistory: msg.harnessStateIdHistory?.length ? [...msg.harnessStateIdHistory] : undefined,
+    metadata: Object.keys(msg.metadata ?? {}).length > 0 ? { ...msg.metadata } : undefined,
+    workspaceEntries: msg.workspaceEntries?.length ? msg.workspaceEntries.map(toWorkspaceEntryInput) : undefined,
+    mcpServerUsages: msg.mcpServerUsages?.length ? msg.mcpServerUsages.map(toMcpServerUsageInput) : undefined,
+    skillRefs: toResourceRefInputs(msg.skillRefs),
+    harness: msg.harness || undefined,
+    cursorMode: msg.cursorMode || undefined,
+    executionTarget: msg.executionTarget || undefined,
+  };
+}
+
+function toContextManagementConfigInput(msg: ContextManagementConfig): ContextManagementConfigInput {
+  return {
+    disableSummarization: msg.disableSummarization || undefined,
+    customTriggerThreshold: msg.customTriggerThreshold || undefined,
+    customTargetTokens: msg.customTargetTokens || undefined,
+  };
+}
+
+function toExecutionConfigInput(msg: ExecutionConfig): ExecutionConfigInput {
+  return {
+    modelName: msg.modelName || undefined,
+    contextManagement: msg.contextManagement ? toContextManagementConfigInput(msg.contextManagement) : undefined,
+    maxToolRounds: msg.maxToolRounds || undefined,
+    maxToolResultChars: msg.maxToolResultChars || undefined,
+    maxCostUsd: msg.maxCostUsd || undefined,
+    interactionMode: msg.interactionMode || undefined,
+    structuredOutputSchema: msg.structuredOutputSchema,
+    buildFromPlan: msg.buildFromPlan || undefined,
+    approvalMode: msg.approvalMode || undefined,
+    serviceTier: msg.serviceTier || undefined,
+    thinkingMode: msg.thinkingMode || undefined,
+  };
+}
+
+function toAttachmentInput(msg: Attachment): AttachmentInput {
+  return {
+    filename: msg.filename || undefined,
+    storageKey: msg.storageKey || undefined,
+    mountPath: msg.mountPath || undefined,
+    contentType: msg.contentType || undefined,
+    extract: msg.extract || undefined,
+    localPath: msg.localPath || undefined,
+  };
+}
+
+function toConversationCatchupInput(msg: ConversationCatchup): ConversationCatchupInput {
+  return {
+    digest: msg.digest || undefined,
+    windowEnd: msg.windowEnd ? timestampDate(msg.windowEnd) : undefined,
+  };
+}
+
+function toDeclaredPreferencesInput(msg: DeclaredPreferences): DeclaredPreferencesInput {
+  return {
+    orgContext: msg.orgContext || undefined,
+    userContext: msg.userContext || undefined,
+  };
+}
+
+/**
+ * Maps a fetched {@link AgentExecution} to a complete {@link AgentExecutionInput} 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({ ...toAgentExecutionUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toAgentExecutionUpdateInput(resource: AgentExecution): AgentExecutionInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(AgentExecutionSpecSchema);
+  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,
+    sessionId: spec.sessionId || undefined,
+    agentId: spec.agentId || undefined,
+    sessionSpec: spec.sessionSpec ? toSessionSpecInput(spec.sessionSpec) : undefined,
+    message: spec.message || undefined,
+    executionConfig: spec.executionConfig ? toExecutionConfigInput(spec.executionConfig) : undefined,
+    runtimeEnv: toExecVarInputMap(spec.runtimeEnv),
+    callbackToken: spec.callbackToken?.length ? spec.callbackToken : undefined,
+    autoApproveAll: spec.autoApproveAll || undefined,
+    parentWorkflowId: spec.parentWorkflowId || undefined,
+    attachments: spec.attachments?.length ? spec.attachments.map(toAttachmentInput) : undefined,
+    workspaceFileRefs: spec.workspaceFileRefs?.length ? [...spec.workspaceFileRefs] : undefined,
+    activityTaskQueue: spec.activityTaskQueue || undefined,
+    supersedesExecutionId: spec.supersedesExecutionId || undefined,
+    conversationCatchup: spec.conversationCatchup ? toConversationCatchupInput(spec.conversationCatchup) : undefined,
+    declaredPreferences: spec.declaredPreferences ? toDeclaredPreferencesInput(spec.declaredPreferences) : undefined,
+  };
+}

package/src/gen/agentinstance.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";
@@ -82,6 +82,14 @@ export class AgentInstanceClient {
 
 /** Input for creating/updating a AgentInstance. */
 export interface AgentInstanceInput {
+  /**
+   * 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;
@@ -98,6 +106,7 @@ export function buildAgentInstanceProto(input: AgentInstanceInput): AgentInstanc
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "AgentInstance",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -111,3 +120,34 @@ export function buildAgentInstanceProto(input: AgentInstanceInput): AgentInstanc
     })),
   }) as AgentInstance;
 }
+
+/**
+ * Maps a fetched {@link AgentInstance} to a complete {@link AgentInstanceInput} 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({ ...toAgentInstanceUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toAgentInstanceUpdateInput(resource: AgentInstance): AgentInstanceInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(AgentInstanceSpecSchema);
+  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,
+    agentId: spec.agentId || undefined,
+    description: spec.description || undefined,
+    environmentRefs: toResourceRefInputs(spec.environmentRefs),
+  };
+}