@stigmer/sdk 3.12.4 → 3.12.6

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

@@ -0,0 +1,250 @@
+import { describe, it, expect } from "vitest";
+import { create, toJson } from "@bufbuild/protobuf";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import {
+  OrganizationSchema,
+  type Organization,
+} from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { OrganizationSpecSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/spec_pb";
+import { ManagementMode } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/enum_pb";
+import {
+  IdentityAccountSchema,
+  type IdentityAccount,
+} 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,
+  toOrganizationUpdateInput,
+} from "../gen/organization";
+import {
+  buildIdentityAccountProto,
+  toIdentityAccountUpdateInput,
+} from "../gen/identityaccount";
+
+/**
+ * Update RPCs are full-spec replacements, so a complete mapper must
+ * round-trip EVERY mutable field of a loaded resource through the generated
+ * builder without loss. These tests pin that contract: fully-populated
+ * resource → mapper → builder → spec (as JSON, defaults omitted) deep-equals
+ * the original. If a mapper drops a field, the wipe-bug class is back.
+ */
+
+function fullOrganization(): Organization {
+  return create(OrganizationSchema, {
+    apiVersion: "tenancy.stigmer.ai/v1",
+    kind: "Organization",
+    metadata: {
+      id: "acme",
+      name: "Acme Corp",
+      slug: "acme",
+      org: "acme",
+      labels: { tier: "gold" },
+      visibility: ApiResourceVisibility.visibility_private,
+    },
+    spec: {
+      description: "We make everything.",
+      logoUrl: "https://acme.example/logo.png",
+      managementMode: ManagementMode.self_managed,
+      identityProviderRef: {
+        org: "acme",
+        slug: "acme-okta",
+        kind: ApiResourceKind.identity_provider,
+      },
+      externalOrgId: "ext-org-1",
+      isPersonal: true,
+      preferences: { standingContext: "We deploy to us-east-1." },
+    },
+  });
+}
+
+function fullIdentityAccount(): IdentityAccount {
+  return create(IdentityAccountSchema, {
+    apiVersion: "iam.stigmer.ai/v1",
+    kind: "IdentityAccount",
+    metadata: {
+      id: "ia-123",
+      name: "Ada Lovelace",
+      slug: "ada-lovelace",
+      org: "acme",
+      labels: { team: "platform" },
+      visibility: ApiResourceVisibility.visibility_private,
+    },
+    spec: {
+      idpId: "auth0|abc123",
+      email: "ada@acme.example",
+      firstName: "Ada",
+      lastName: "Lovelace",
+      pictureUrl: "https://acme.example/ada.png",
+      isMachineAccount: true,
+      provisioningMode: IdentityAccountProvisioningMode.federated,
+      identityProviderRef: { org: "acme", slug: "acme-okta" },
+      preferences: {
+        standingContext: "Keep answers terse.",
+        defaultHarness: "cursor",
+        defaultNativeModel: "claude-sonnet-4.6",
+        defaultCursorModel: "composer-2.5",
+      },
+    },
+  });
+}
+
+describe("toOrganizationUpdateInput", () => {
+  it("round-trips a fully-populated organization spec through the builder", () => {
+    const org = fullOrganization();
+
+    const built = buildOrganizationProto(toOrganizationUpdateInput(org));
+
+    expect(toJson(OrganizationSpecSchema, built.spec!)).toEqual(
+      toJson(OrganizationSpecSchema, org.spec!),
+    );
+    expect(built.metadata?.name).toBe("Acme Corp");
+    expect(built.metadata?.slug).toBe("acme");
+    expect(built.metadata?.org).toBe("acme");
+    expect(built.metadata?.labels).toEqual({ tier: "gold" });
+    expect(built.metadata?.visibility).toBe(
+      ApiResourceVisibility.visibility_private,
+    );
+  });
+
+  it("preserves preferences when a caller overrides only profile fields (the wipe-bug class)", () => {
+    const org = fullOrganization();
+
+    const built = buildOrganizationProto({
+      ...toOrganizationUpdateInput(org),
+      description: "New description",
+    });
+
+    expect(built.spec?.preferences?.standingContext).toBe(
+      "We deploy to us-east-1.",
+    );
+    expect(built.spec?.description).toBe("New description");
+    expect(built.spec?.logoUrl).toBe("https://acme.example/logo.png");
+  });
+
+  it("maps an empty spec without inventing values", () => {
+    const org = create(OrganizationSchema, {
+      metadata: { name: "Bare", slug: "bare", org: "bare" },
+      spec: {},
+    });
+
+    const built = buildOrganizationProto(toOrganizationUpdateInput(org));
+
+    expect(toJson(OrganizationSpecSchema, built.spec!)).toEqual({});
+  });
+
+  it("falls back to the slug when metadata.org is empty", () => {
+    const org = create(OrganizationSchema, {
+      metadata: { name: "Bare", slug: "bare" },
+    });
+
+    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", () => {
+  it("round-trips a fully-populated identity account spec through the builder", () => {
+    const account = fullIdentityAccount();
+
+    const built = buildIdentityAccountProto(
+      toIdentityAccountUpdateInput(account),
+    );
+
+    expect(toJson(IdentityAccountSpecSchema, built.spec!)).toEqual(
+      toJson(IdentityAccountSpecSchema, account.spec!),
+    );
+    expect(built.metadata?.name).toBe("Ada Lovelace");
+    expect(built.metadata?.labels).toEqual({ team: "platform" });
+  });
+
+  it("carries org and slug — the update pipeline's fallback address", () => {
+    const input = toIdentityAccountUpdateInput(fullIdentityAccount());
+
+    expect(input.org).toBe("acme");
+    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);
+
+    const built = buildIdentityAccountProto({
+      ...mapped,
+      preferences: { ...mapped.preferences, standingContext: "Prefer bullet points." },
+    });
+
+    expect(built.spec?.preferences?.standingContext).toBe(
+      "Prefer bullet points.",
+    );
+    expect(built.spec?.email).toBe("ada@acme.example");
+    expect(built.spec?.idpId).toBe("auth0|abc123");
+    expect(built.spec?.provisioningMode).toBe(
+      IdentityAccountProvisioningMode.federated,
+    );
+  });
+
+  it("preserves structured defaults when only standing context is edited (nested wipe-bug class)", () => {
+    const account = fullIdentityAccount();
+    const mapped = toIdentityAccountUpdateInput(account);
+
+    // The correct editor pattern for a nested message: spread the mapper's
+    // COMPLETE preferences and override only the edited field. A bare
+    // `preferences: { standingContext }` literal would wipe the structured
+    // defaults — the session-4 wipe bug recurring one level down.
+    const built = buildIdentityAccountProto({
+      ...mapped,
+      preferences: { ...mapped.preferences, standingContext: "Terser still." },
+    });
+
+    expect(built.spec?.preferences?.standingContext).toBe("Terser still.");
+    expect(built.spec?.preferences?.defaultHarness).toBe("cursor");
+    expect(built.spec?.preferences?.defaultNativeModel).toBe("claude-sonnet-4.6");
+    expect(built.spec?.preferences?.defaultCursorModel).toBe("composer-2.5");
+  });
+
+  it("clears standing context to wire-absent when the text is emptied", () => {
+    const account = fullIdentityAccount();
+    const mapped = toIdentityAccountUpdateInput(account);
+
+    const built = buildIdentityAccountProto({
+      ...mapped,
+      preferences: { ...mapped.preferences, standingContext: "" },
+    });
+
+    // Proto3 empty string is the field default — wire-identical to absent,
+    // which the server compose steps treat as "no preference declared".
+    expect(built.spec?.preferences?.standingContext ?? "").toBe("");
+    // Clearing one field never disturbs its siblings.
+    expect(built.spec?.preferences?.defaultHarness).toBe("cursor");
+  });
+});

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,
+  };
+}