@stigmer/sdk 3.12.4 → 3.12.6

package/src/gen/workflowexecution.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, toExecVarInputMap } from "./proto-utils.js";
 import { type EnvVarInput } from "./types.js";
 import { create } from "@bufbuild/protobuf";
 import { createClient, type Client, type Transport } from "@connectrpc/connect";
@@ -160,6 +160,14 @@ export class WorkflowExecutionClient {
 
 /** Input for creating/updating a WorkflowExecution. */
 export interface WorkflowExecutionInput {
+  /**
+   * 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;
@@ -184,6 +192,7 @@ export function buildWorkflowExecutionProto(input: WorkflowExecutionInput): Work
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "WorkflowExecution",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -201,3 +210,38 @@ export function buildWorkflowExecutionProto(input: WorkflowExecutionInput): Work
     })),
   }) as WorkflowExecution;
 }
+
+/**
+ * Maps a fetched {@link WorkflowExecution} to a complete {@link WorkflowExecutionInput} 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({ ...toWorkflowExecutionUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toWorkflowExecutionUpdateInput(resource: WorkflowExecution): WorkflowExecutionInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(WorkflowExecutionSpecSchema);
+  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,
+    workflowInstanceId: spec.workflowInstanceId || undefined,
+    workflowId: spec.workflowId || undefined,
+    triggerMessage: spec.triggerMessage || undefined,
+    triggerMetadata: Object.keys(spec.triggerMetadata ?? {}).length > 0 ? { ...spec.triggerMetadata } : undefined,
+    runtimeEnv: toExecVarInputMap(spec.runtimeEnv),
+    callbackToken: spec.callbackToken?.length ? spec.callbackToken : undefined,
+    executionTarget: spec.executionTarget || undefined,
+  };
+}

package/src/gen/workflowinstance.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 WorkflowInstanceClient {
 
 /** Input for creating/updating a WorkflowInstance. */
 export interface WorkflowInstanceInput {
+  /**
+   * 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;
@@ -99,6 +107,7 @@ export function buildWorkflowInstanceProto(input: WorkflowInstanceInput): Workfl
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "WorkflowInstance",
     metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
       name: input.name,
       org: input.org,
       ...(input.slug && { slug: input.slug }),
@@ -113,3 +122,35 @@ export function buildWorkflowInstanceProto(input: WorkflowInstanceInput): Workfl
     })),
   }) as WorkflowInstance;
 }
+
+/**
+ * Maps a fetched {@link WorkflowInstance} to a complete {@link WorkflowInstanceInput} 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({ ...toWorkflowInstanceUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toWorkflowInstanceUpdateInput(resource: WorkflowInstance): WorkflowInstanceInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(WorkflowInstanceSpecSchema);
+  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,
+    workflowId: spec.workflowId || undefined,
+    description: spec.description || undefined,
+    environmentRefs: toResourceRefInputs(spec.environmentRefs),
+    executionVisibility: spec.executionVisibility || undefined,
+  };
+}

package/src/index.ts

@@ -160,10 +160,14 @@ export {
   type EnvVarInput,
 } from "./gen/types.js";
 
-// Re-export all resource client classes and input types
+// Re-export all resource client classes and input types. The
+// toXxxUpdateInput mappers are the full-spec-replace safety layer: they
+// rebuild a COMPLETE input from a fetched resource so subset editors can
+// spread-and-override without wiping unlisted fields.
 export {
   AgentClient,
   buildAgentProto,
+  toAgentUpdateInput,
   type AgentInput,
   type McpServerUsageInput,
   type ToolApprovalOverrideInput,
@@ -173,11 +177,13 @@ export {
 } from "./gen/agent.js";
 export {
   AgentChannelClient,
+  toAgentChannelUpdateInput,
   type AgentChannelInput,
   type SlackChannelConfigInput,
 } from "./gen/agentchannel.js";
 export {
   AgentExecutionClient,
+  toAgentExecutionUpdateInput,
   type AgentExecutionInput,
   type ExecutionConfigInput,
   type ContextManagementConfigInput,
@@ -185,21 +191,25 @@ export {
 } from "./gen/agentexecution.js";
 export {
   AgentInstanceClient,
+  toAgentInstanceUpdateInput,
   type AgentInstanceInput,
 } from "./gen/agentinstance.js";
 export {
   AgentShareClient,
+  toAgentShareUpdateInput,
   type AgentShareInput,
   type AgentShareMessagesInput,
 } from "./gen/agentshare.js";
-export { ApiKeyClient, type ApiKeyInput } from "./gen/apikey.js";
+export { ApiKeyClient, toApiKeyUpdateInput, type ApiKeyInput } from "./gen/apikey.js";
 export {
   ChannelAppClient,
+  toChannelAppUpdateInput,
   type ChannelAppInput,
   type SlackChannelAppConfigInput,
 } from "./gen/channelapp.js";
 export {
   EnvironmentClient,
+  toEnvironmentUpdateInput,
   type EnvironmentInput,
 } from "./gen/environment.js";
 export {
@@ -213,6 +223,7 @@ export {
 } from "./gen/iampolicy.js";
 export {
   IdentityAccountClient,
+  toIdentityAccountUpdateInput,
   type IdentityAccountInput,
 } from "./gen/identityaccount.js";
 export {
@@ -221,38 +232,53 @@ export {
 } from "./gen/invitation.js";
 export {
   IdentityProviderClient,
+  toIdentityProviderUpdateInput,
   type IdentityProviderInput,
 } from "./gen/identityprovider.js";
 export {
   OAuthAppClient,
+  toOAuthAppUpdateInput,
   type OAuthAppInput,
 } from "./gen/oauthapp.js";
 export {
   McpServerClient,
   buildMcpServerProto,
+  toMcpServerUpdateInput,
   type McpServerInput,
   type StdioServerConfigInput,
   type HttpServerConfigInput,
   type ToolApprovalPolicyInput,
 } from "./gen/mcpserver.js";
+export {
+  connectAndWait,
+  ConnectStillRunningError,
+  CONNECT_POLL_INTERVAL_MS,
+  CONNECT_SETTLE_BOUND_MS,
+  type ConnectAndWaitOptions,
+  type McpServerConnectLane,
+} from "./mcpserver-connect.js";
 export {
   OrganizationClient,
+  toOrganizationUpdateInput,
   type OrganizationInput,
 } from "./gen/organization.js";
 export {
   PlatformClientClient,
+  toPlatformClientUpdateInput,
   type PlatformClientInput,
 } from "./gen/platformclient.js";
-export { ProjectClient, type ProjectInput } from "./gen/project.js";
+export { ProjectClient, toProjectUpdateInput, type ProjectInput } from "./gen/project.js";
 export {
   ScheduleClient,
   buildScheduleProto,
+  toScheduleUpdateInput,
   type ScheduleInput,
   type AgentInvocationInput,
   type RunConfigInput,
 } from "./gen/schedule.js";
 export {
   SessionClient,
+  toSessionUpdateInput,
   type SessionInput,
   type WorkspaceEntryInput,
   type WorkspaceSourceInput,
@@ -297,6 +323,7 @@ export { SkillClient, type SkillInput } from "./gen/skill.js";
 export { RoutedSkillClient, MAX_INLINE_ARTIFACT_BYTES } from "./skill.js";
 export {
   WorkflowClient,
+  toWorkflowUpdateInput,
   type WorkflowInput,
   type WorkflowDocumentInput,
   type WorkflowTaskInput,
@@ -305,9 +332,11 @@ export {
 } from "./gen/workflow.js";
 export {
   WorkflowExecutionClient,
+  toWorkflowExecutionUpdateInput,
   type WorkflowExecutionInput,
 } from "./gen/workflowexecution.js";
 export {
   WorkflowInstanceClient,
+  toWorkflowInstanceUpdateInput,
   type WorkflowInstanceInput,
 } from "./gen/workflowinstance.js";

package/src/mcpserver-connect.ts

@@ -0,0 +1,159 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { ConnectInput } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import { ConnectPhase } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+import { isUnimplemented, wrapError } from "./gen/errors.js";
+
+/**
+ * The slice of {@link McpServerClient} the connect protocol needs — the
+ * async-lane pair plus the blocking fallback. Structural on purpose: the
+ * full client satisfies it, and tests can hand in three functions.
+ */
+export interface McpServerConnectLane {
+  startConnect(input: ConnectInput): Promise<McpServer>;
+  connect(input: ConnectInput): Promise<McpServer>;
+  get(id: string): Promise<McpServer>;
+}
+
+/**
+ * How often {@link connectAndWait} re-reads the resource while a connect
+ * operation runs. Discovery legitimately takes tens of seconds to minutes;
+ * a few seconds of staleness is invisible next to that, and each poll is
+ * one cheap get.
+ */
+export const CONNECT_POLL_INTERVAL_MS = 2_500;
+
+/**
+ * Absolute bound on waiting for a connect to settle: the backend's async
+ * connect ceiling (its asyncConnectTimeout, 60 min) plus margin. Every
+ * operation settles within the ceiling by construction; only a
+ * connect_status orphaned by a backend restart can still read CONNECTING
+ * past it, and this bound turns that into a typed error instead of an
+ * infinite wait.
+ */
+export const CONNECT_SETTLE_BOUND_MS = 65 * 60_000;
+
+/**
+ * Thrown by {@link connectAndWait} when it stopped waiting while the
+ * server-side operation was still running. NOT a failure: the backend
+ * finishes the connect on its own and persists the result — re-read the
+ * resource (or re-run the connect) to observe the outcome.
+ */
+export class ConnectStillRunningError extends Error {
+  readonly mcpServerId: string;
+
+  constructor(mcpServerId: string, waitedMs: number) {
+    super(
+      `the connect of MCP server '${mcpServerId}' is still running server-side after ${Math.round(waitedMs / 1000)}s — ` +
+        "it will persist its result on its own; re-read the server to observe the outcome",
+    );
+    this.name = "ConnectStillRunningError";
+    this.mcpServerId = mcpServerId;
+  }
+}
+
+/** Options for {@link connectAndWait}. */
+export interface ConnectAndWaitOptions {
+  /** Poll cadence. Defaults to {@link CONNECT_POLL_INTERVAL_MS}. */
+  readonly pollIntervalMs?: number;
+  /**
+   * Stop waiting after this long (soft bound — the server-side operation
+   * keeps running). Defaults to {@link CONNECT_SETTLE_BOUND_MS}, and is
+   * capped by it: waiting longer than the backend's own ceiling can only
+   * ever observe an orphaned record.
+   */
+  readonly deadlineMs?: number;
+  /**
+   * Observe the CONNECTING snapshot the moment the operation is accepted —
+   * the place to read `status.connect_status.warning` (the dead-runner
+   * advisory) before the wait begins. Not called on the blocking fallback,
+   * which has no start-time snapshot.
+   */
+  readonly onStarted?: (started: McpServer) => void;
+}
+
+/**
+ * Connect an MCP server and wait for the operation to settle, without any
+ * long-lived RPC (stigmer/stigmer#425).
+ *
+ * Uses the async lane — `startConnect` returns immediately with
+ * `status.connect_status = CONNECTING`, then the resource is polled until
+ * the operation settles — so the wait survives transport limits that kill
+ * a long-blocking unary call (browsers drop no-bytes responses around
+ * ~300s, below the server's discovery ceiling). Callers never see the
+ * mechanics: the promise resolves with the updated server exactly as the
+ * blocking `connect` RPC resolved, and a failed operation rejects with the
+ * same {@link StigmerError} classification the blocking RPC would have
+ * thrown (`connect_status.failure_code` is the Go gRPC code name, which
+ * matches connect-es `Code` member names — rehydration is lossless).
+ *
+ * Backends that predate the async lane answer UNIMPLEMENTED for
+ * `startConnect`; this falls back to the blocking `connect` RPC — the same
+ * edition capability-probe idiom as the skill artifact-transfer lane
+ * (skill.ts) and the org-OAuth-app surface.
+ */
+export async function connectAndWait(
+  client: McpServerConnectLane,
+  input: ConnectInput,
+  options?: ConnectAndWaitOptions,
+): Promise<McpServer> {
+  const pollIntervalMs = options?.pollIntervalMs ?? CONNECT_POLL_INTERVAL_MS;
+  const waitMs = Math.min(options?.deadlineMs ?? CONNECT_SETTLE_BOUND_MS, CONNECT_SETTLE_BOUND_MS);
+
+  let started: McpServer;
+  try {
+    started = await client.startConnect(input);
+  } catch (err) {
+    if (!isUnimplemented(err)) throw err;
+    return blockingConnect(client, input, waitMs);
+  }
+  options?.onStarted?.(started);
+
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    if (Date.now() >= deadline) {
+      throw new ConnectStillRunningError(input.mcpServerId, waitMs);
+    }
+    await sleep(Math.min(pollIntervalMs, Math.max(1, deadline - Date.now())));
+
+    const current = await client.get(input.mcpServerId);
+    const cs = current.status?.connectStatus;
+    if (cs?.phase === ConnectPhase.succeeded) return current;
+    if (cs?.phase === ConnectPhase.failed) {
+      throw rehydrateConnectFailure(cs.failureCode, cs.failureMessage);
+    }
+  }
+}
+
+// The pre-async-lane path, kept behaviorally identical for old backends: one
+// blocking RPC, raced (not cancelled — the server finishes and persists on
+// its own) against the caller's soft bound.
+async function blockingConnect(client: McpServerConnectLane, input: ConnectInput, waitMs: number): Promise<McpServer> {
+  const push = client.connect(input);
+  // The losing push may settle after the caller has moved on; swallow its
+  // late rejection so it cannot surface as an unhandled-rejection crash.
+  void push.catch(() => {});
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new ConnectStillRunningError(input.mcpServerId, waitMs)), waitMs);
+  });
+  try {
+    return await Promise.race([push, timeout]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+// Rebuild the failure the blocking connect RPC would have thrown, from the
+// classification the backend persisted on connect_status. Routing the
+// rehydrated ConnectError through wrapError makes the result byte-identical
+// to a live RPC failure (same StigmerError code mapping, same raw message).
+function rehydrateConnectFailure(failureCode: string, failureMessage: string) {
+  const code = (Code as Record<string, unknown>)[failureCode];
+  return wrapError(new ConnectError(failureMessage, typeof code === "number" ? (code as Code) : Code.Unknown));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}