@stigmer/sdk 3.12.3 → 3.12.5

package/src/execution/tool-view.ts

@@ -228,6 +228,58 @@ export function resolveToolKindByName(name: string, mcpServerSlug?: string): Too
   return ToolKind.UNSPECIFIED;
 }
 
+// ---------------------------------------------------------------------------
+// Intent: extractShellIntent
+// ---------------------------------------------------------------------------
+
+/**
+ * The tool-call argument that carries a model-authored intent phrase for
+ * SHELL tools (stigmer#276) — a short human description of what the command
+ * does and why, rendered as the row title with the command as secondary text.
+ *
+ * Two writers populate it, converged on one wire key by design: the native
+ * harness's tool-intent middleware (`backend/services/runner/src/middleware/
+ * tool-intent.ts`, `INTENT_ARG`) extends the shell tool's bind-time schema
+ * with it, and the Cursor harness's built-in Shell tool carries it natively.
+ * The shared, machine-checked contract is
+ * `test/fixtures/tool-view/intent-title.json` — keep the writers and this
+ * reader in lockstep.
+ */
+export const SHELL_INTENT_ARG_FIELD = "description";
+
+/**
+ * Args-level intent extraction: SHELL-kind-scoped on purpose, because
+ * `description` means other things on other tools (a task tool's description
+ * is the sub-agent subject, never a row title). Blank and non-string values
+ * degrade to null — callers fall back to their category label.
+ *
+ * The seam for surfaces that hold a pre-resolved kind and raw args instead of
+ * a full ToolCall: the CLI's headless snapshot projection and @stigmer/react's
+ * approval argsPreview path. Everything else should prefer
+ * {@link extractShellIntent}.
+ */
+export function shellIntentFromArgs(
+  kind: ToolKind,
+  args: Record<string, unknown> | undefined,
+): string | null {
+  if (kind !== ToolKind.SHELL || !args) return null;
+  const value = args[SHELL_INTENT_ARG_FIELD];
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Extracts the model-authored intent phrase from a SHELL tool call, or null
+ * when absent (legacy executions, models that skipped the optional arg, and
+ * every non-shell kind). See {@link SHELL_INTENT_ARG_FIELD}.
+ */
+export function extractShellIntent(
+  toolCall: Pick<ToolCall, "name" | "mcpServerSlug" | "toolKind" | "args">,
+): string | null {
+  return shellIntentFromArgs(resolveToolKind(toolCall), toolCall.args as Args);
+}
+
 // ---------------------------------------------------------------------------
 // Result: normalizeToolResult
 // ---------------------------------------------------------------------------

package/src/gen/agentexecution.ts

@@ -11,7 +11,7 @@ import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agen
 import { InteractionMode, ApprovalMode, ServiceTier } 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 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { AgentExecutionSpecSchema, ContextManagementConfigSchema, ExecutionConfigSchema, AttachmentSchema, ConversationCatchupSchema, DeclaredPreferencesSchema } 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";
@@ -192,6 +192,7 @@ export interface AgentExecutionInput {
   activityTaskQueue?: string;
   supersedesExecutionId?: string;
   conversationCatchup?: ConversationCatchupInput;
+  declaredPreferences?: DeclaredPreferencesInput;
 }
 
 /** SDK input type for SessionSpec. */
@@ -286,6 +287,12 @@ export interface ConversationCatchupInput {
   windowEnd?: Date | string;
 }
 
+/** SDK input type for DeclaredPreferences. */
+export interface DeclaredPreferencesInput {
+  orgContext?: string;
+  userContext?: string;
+}
+
 function buildGitRepoSourceProto(input: GitRepoSourceInput) {
   return Object.assign(create(GitRepoSourceSchema), stripUndefined({
     url: input.url,
@@ -392,6 +399,13 @@ function buildConversationCatchupProto(input: ConversationCatchupInput) {
   return msg;
 }
 
+function buildDeclaredPreferencesProto(input: DeclaredPreferencesInput) {
+  return Object.assign(create(DeclaredPreferencesSchema), stripUndefined({
+    orgContext: input.orgContext,
+    userContext: input.userContext,
+  }));
+}
+
 export function buildAgentExecutionProto(input: AgentExecutionInput): AgentExecution {
   const sessionSpec = input.sessionSpec ? buildSessionSpecProto(input.sessionSpec) : undefined;
   const executionConfig = input.executionConfig ? buildExecutionConfigProto(input.executionConfig) : undefined;
@@ -402,6 +416,7 @@ export function buildAgentExecutionProto(input: AgentExecutionInput): AgentExecu
   }
   const attachments = input.attachments?.map(buildAttachmentProto);
   const conversationCatchup = input.conversationCatchup ? buildConversationCatchupProto(input.conversationCatchup) : undefined;
+  const declaredPreferences = input.declaredPreferences ? buildDeclaredPreferencesProto(input.declaredPreferences) : undefined;
   return Object.assign(create(AgentExecutionSchema), {
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "AgentExecution",
@@ -427,6 +442,7 @@ export function buildAgentExecutionProto(input: AgentExecutionInput): AgentExecu
       activityTaskQueue: input.activityTaskQueue,
       supersedesExecutionId: input.supersedesExecutionId,
       conversationCatchup,
+      declaredPreferences,
     })),
   }) as AgentExecution;
 }

package/src/gen/client.ts

@@ -90,7 +90,7 @@ export { type AgentInput, type McpServerUsageInput, type ToolApprovalOverrideInp
 export { AgentChannelClient } from "./agentchannel.js";
 export { type AgentChannelInput, type SlackChannelConfigInput, type WhatsAppChannelConfigInput, type RunConfigInput } from "./agentchannel.js";
 export { AgentExecutionClient } from "./agentexecution.js";
-export { type AgentExecutionInput, type SessionSpecInput, type WorkspaceEntryInput, type WorkspaceSourceInput, type GitRepoSourceInput, type LocalPathSourceInput, type ExecutionConfigInput, type ContextManagementConfigInput, type AttachmentInput, type ConversationCatchupInput } from "./agentexecution.js";
+export { type AgentExecutionInput, type SessionSpecInput, type WorkspaceEntryInput, type WorkspaceSourceInput, type GitRepoSourceInput, type LocalPathSourceInput, type ExecutionConfigInput, type ContextManagementConfigInput, type AttachmentInput, type ConversationCatchupInput, type DeclaredPreferencesInput } from "./agentexecution.js";
 export { AgentInstanceClient } from "./agentinstance.js";
 export { type AgentInstanceInput } from "./agentinstance.js";
 export { AgentShareClient } from "./agentshare.js";
@@ -108,7 +108,7 @@ export { type ExecutionContextInput } from "./executioncontext.js";
 export { IamPolicyClient } from "./iampolicy.js";
 export { type IamPolicyInput, type ApiResourceRefInput } from "./iampolicy.js";
 export { IdentityAccountClient } from "./identityaccount.js";
-export { type IdentityAccountInput } from "./identityaccount.js";
+export { type IdentityAccountInput, type IdentityAccountPreferencesInput } from "./identityaccount.js";
 export { IdentityProviderClient } from "./identityprovider.js";
 export { type IdentityProviderInput } from "./identityprovider.js";
 export { InvitationClient } from "./invitation.js";
@@ -118,7 +118,7 @@ export { type McpServerInput, type StdioServerConfigInput, type HttpServerConfig
 export { OAuthAppClient } from "./oauthapp.js";
 export { type OAuthAppInput } from "./oauthapp.js";
 export { OrganizationClient } from "./organization.js";
-export { type OrganizationInput } from "./organization.js";
+export { type OrganizationInput, type OrganizationPreferencesInput } from "./organization.js";
 export { PlatformClientClient } from "./platformclient.js";
 export { type PlatformClientInput } from "./platformclient.js";
 export { ProjectClient } from "./project.js";
@@ -136,4 +136,4 @@ export { type WorkflowExecutionInput } from "./workflowexecution.js";
 export { WorkflowInstanceClient } from "./workflowinstance.js";
 export { type WorkflowInstanceInput } from "./workflowinstance.js";
 export { type ListParams, type ListResult, type DeleteResourceInput, type ResourceRef, type EnvSpecInput, type EnvVarInput, type Page } from "./types.js";
-export { StigmerError, type ErrorCode, isNotFound, isUnauthenticated, isPermissionDenied, isRetryable } from "./errors.js";
+export { StigmerError, type ErrorCode, isNotFound, isUnauthenticated, isPermissionDenied, isRetryable, isUnimplemented } from "./errors.js";

package/src/gen/errors.ts

@@ -74,3 +74,13 @@ export function isPermissionDenied(err: unknown): boolean {
 export function isRetryable(err: unknown): boolean {
   return err instanceof StigmerError && (err.code === "internal" || err.code === "unavailable");
 }
+
+/**
+ * The server does not implement the called RPC — the code clients key
+ * capability fallbacks on (e.g. the skill artifact transfer lane's unary
+ * fallback, stigmer#675/#701). Checks the raw connect code: Unimplemented
+ * deliberately has no ErrorCode mapping, so it surfaces as "unknown".
+ */
+export function isUnimplemented(err: unknown): boolean {
+  return err instanceof StigmerError && err.connectCode === Code.Unimplemented;
+}

package/src/gen/identityaccount.ts

@@ -15,7 +15,7 @@ import { IdentityAccountCommandController } from "@stigmer/protos/ai/stigmer/iam
 import { IdentityAccountProvisioningMode } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/enum_pb";
 import { IdentityAccountIdSchema, CreateFederatedAccountInputSchema, UpdateFederatedAccountInputSchema, DeprovisionFederatedAccountInputSchema, IdentityAccountEmailSchema, IdpIdSchema, ExternalSubLookupSchema, type CreateFederatedAccountInput, type UpdateFederatedAccountInput, type DeprovisionFederatedAccountInput, type IdentityAccountEmail, type ExternalSubLookup } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/io_pb";
 import { IdentityAccountQueryController } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/query_pb";
-import { IdentityAccountSpecSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
+import { IdentityAccountSpecSchema, IdentityAccountPreferencesSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/spec_pb";
 
 /** Provides operations on identityaccount resources. */
 export class IdentityAccountClient {
@@ -121,10 +121,29 @@ export interface IdentityAccountInput {
   isMachineAccount?: boolean;
   provisioningMode?: IdentityAccountProvisioningMode;
   identityProviderRef?: ResourceRef;
+  preferences?: IdentityAccountPreferencesInput;
+}
+
+/** SDK input type for IdentityAccountPreferences. */
+export interface IdentityAccountPreferencesInput {
+  standingContext?: string;
+  defaultHarness?: string;
+  defaultNativeModel?: string;
+  defaultCursorModel?: string;
+}
+
+function buildIdentityAccountPreferencesProto(input: IdentityAccountPreferencesInput) {
+  return Object.assign(create(IdentityAccountPreferencesSchema), stripUndefined({
+    standingContext: input.standingContext,
+    defaultHarness: input.defaultHarness,
+    defaultNativeModel: input.defaultNativeModel,
+    defaultCursorModel: input.defaultCursorModel,
+  }));
 }
 
 export function buildIdentityAccountProto(input: IdentityAccountInput): IdentityAccount {
   const identityProviderRef = (input.identityProviderRef?.slug || input.identityProviderRef?.org) ? create(ApiResourceReferenceSchema, input.identityProviderRef) : undefined;
+  const preferences = input.preferences ? buildIdentityAccountPreferencesProto(input.preferences) : undefined;
   return Object.assign(create(IdentityAccountSchema), {
     apiVersion: "iam.stigmer.ai/v1",
     kind: "IdentityAccount",
@@ -144,6 +163,7 @@ export function buildIdentityAccountProto(input: IdentityAccountInput): Identity
       isMachineAccount: input.isMachineAccount,
       provisioningMode: input.provisioningMode,
       identityProviderRef,
+      preferences,
     })),
   }) as IdentityAccount;
 }

package/src/gen/mcpserver.ts

@@ -71,6 +71,12 @@ export class McpServerClient {
     } catch (e) { throw wrapError(e); }
   }
 
+  async startConnect(input: ConnectInput): Promise<McpServer> {
+    try {
+      return await this.command.startConnect(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
   async initiateOAuthConnect(input: InitiateOAuthConnectInput): Promise<InitiateOAuthConnectOutput> {
     try {
       return await this.command.initiateOAuthConnect(input);

package/src/gen/oauthapp.ts

@@ -13,7 +13,7 @@ import { OAuthAppSchema, type OAuthApp } from "@stigmer/protos/ai/stigmer/iam/oa
 import { OAuthAppCommandController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/command_pb";
 import { ListOAuthAppsByOrgInputSchema, OAuthAppsSchema, type ListOAuthAppsByOrgInput, type OAuthApps } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/io_pb";
 import { OAuthAppQueryController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/query_pb";
-import { OAuthAppSpecSchema, VendorApprovalStatus } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/spec_pb";
+import { OAuthAppSpecSchema, VendorApprovalStatus, TokenEndpointAuthMethod } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/spec_pb";
 
 /** Provides operations on oauthapp resources. */
 export class OAuthAppClient {
@@ -89,6 +89,7 @@ export interface OAuthAppInput {
   scopeParameterName?: string;
   vendorApprovalStatus?: VendorApprovalStatus;
   vendorApprovalDocsUrl?: string;
+  tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
 }
 
 export function buildOAuthAppProto(input: OAuthAppInput): OAuthApp {
@@ -113,6 +114,7 @@ export function buildOAuthAppProto(input: OAuthAppInput): OAuthApp {
       scopeParameterName: input.scopeParameterName,
       vendorApprovalStatus: input.vendorApprovalStatus,
       vendorApprovalDocsUrl: input.vendorApprovalDocsUrl,
+      tokenEndpointAuthMethod: input.tokenEndpointAuthMethod,
     })),
   }) as OAuthApp;
 }

package/src/gen/organization.ts

@@ -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 } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/spec_pb";
+import { OrganizationSpecSchema, OrganizationPreferencesSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/spec_pb";
 
 /** Provides operations on organization resources. */
 export class OrganizationClient {
@@ -88,10 +88,23 @@ export interface OrganizationInput {
   identityProviderRef?: ResourceRef;
   externalOrgId?: string;
   isPersonal?: boolean;
+  preferences?: OrganizationPreferencesInput;
+}
+
+/** SDK input type for OrganizationPreferences. */
+export interface OrganizationPreferencesInput {
+  standingContext?: string;
+}
+
+function buildOrganizationPreferencesProto(input: OrganizationPreferencesInput) {
+  return Object.assign(create(OrganizationPreferencesSchema), stripUndefined({
+    standingContext: input.standingContext,
+  }));
 }
 
 export function buildOrganizationProto(input: OrganizationInput): Organization {
   const identityProviderRef = (input.identityProviderRef?.slug || input.identityProviderRef?.org) ? create(ApiResourceReferenceSchema, input.identityProviderRef) : undefined;
+  const preferences = input.preferences ? buildOrganizationPreferencesProto(input.preferences) : undefined;
   return Object.assign(create(OrganizationSchema), {
     apiVersion: "tenancy.stigmer.ai/v1",
     kind: "Organization",
@@ -109,6 +122,7 @@ export function buildOrganizationProto(input: OrganizationInput): Organization {
       identityProviderRef,
       externalOrgId: input.externalOrgId,
       isPersonal: input.isPersonal,
+      preferences,
     })),
   }) as Organization;
 }

package/src/gen/platformclient.ts

@@ -104,10 +104,12 @@ export interface PlatformClientInput {
   autoGrantOnOrg?: boolean;
   autoGrantRole?: IamRole;
   allowedOrigins?: string[];
+  environmentRefs?: ResourceRef[];
 }
 
 export function buildPlatformClientProto(input: PlatformClientInput): PlatformClient {
   const expiresAt = input.expiresAt !== undefined ? toTimestamp(input.expiresAt) : undefined;
+  const environmentRefs = input.environmentRefs?.map(r => create(ApiResourceReferenceSchema, { ...r, kind: 53 }));
   return Object.assign(create(PlatformClientSchema), {
     apiVersion: "iam.stigmer.ai/v1",
     kind: "PlatformClient",
@@ -128,6 +130,7 @@ export function buildPlatformClientProto(input: PlatformClientInput): PlatformCl
       autoGrantOnOrg: input.autoGrantOnOrg,
       autoGrantRole: input.autoGrantRole,
       allowedOrigins: input.allowedOrigins,
+      environmentRefs,
     })),
   }) as PlatformClient;
 }

package/src/index.ts

@@ -41,6 +41,7 @@ export {
   isUnauthenticated,
   isPermissionDenied,
   isRetryable,
+  isUnimplemented,
   type ErrorCategory,
   isConnectError,
   classifyError,
@@ -60,6 +61,12 @@ export {
   isResourceAvailable,
 } from "./resource-availability.js";
 
+// Complete update-input mappers (full-spec-replace round-trip safety)
+export {
+  toOrganizationUpdateInput,
+  toIdentityAccountUpdateInput,
+} from "./update-input.js";
+
 // Authorization config and IAM role utilities
 export {
   getGrantableRoles,
@@ -104,6 +111,9 @@ export {
   type SetCursorMemberKeyEnabledParams,
 } from "./cursor-accounts.js";
 
+// Provider standing client (platform operators only, read-only)
+export { ProviderStandingClient } from "./provider-standing.js";
+
 // Search client
 export {
   SearchClient,
@@ -231,6 +241,14 @@ export {
   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,
   type OrganizationInput,
@@ -271,6 +289,9 @@ export {
   resolveToolKind,
   resolveToolKindByName,
   normalizeToolResult,
+  SHELL_INTENT_ARG_FIELD,
+  extractShellIntent,
+  shellIntentFromArgs,
   type ToolResultView,
   type ToolSearchMatch,
   type ToolContentBlock,
@@ -287,6 +308,7 @@ export {
 } from "./execution/file-review-fold.js";
 export { toDisplayFileChange } from "./execution/to-display-file-change.js";
 export { SkillClient, type SkillInput } from "./gen/skill.js";
+export { RoutedSkillClient, MAX_INLINE_ARTIFACT_BYTES } from "./skill.js";
 export {
   WorkflowClient,
   type WorkflowInput,

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

package/src/provider-standing.ts

@@ -0,0 +1,37 @@
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { ProviderStandingQueryController } from "@stigmer/protos/ai/stigmer/platform/providerstanding/v1/query_pb";
+import {
+  GetProviderStandingViewInputSchema,
+  type ProviderStandingView,
+} from "@stigmer/protos/ai/stigmer/platform/providerstanding/v1/io_pb";
+import { wrapError } from "./gen/errors.js";
+
+/**
+ * Client for platform provider standing (platform operators only).
+ *
+ * Serves the read-only operator view of the platform's LLM provider
+ * account health: the latest canary-probe verdict per provider (status,
+ * HTTP status, latency, bounded error summary, probe time) recorded by
+ * the hourly standing probe. Requires `can_view_provider_standing` on
+ * `platform:stigmer`. Cloud-only — the OSS Go server does not implement
+ * this controller.
+ */
+export class ProviderStandingClient {
+  private readonly query: Client<typeof ProviderStandingQueryController>;
+
+  constructor(transport: Transport) {
+    this.query = createClient(ProviderStandingQueryController, transport);
+  }
+
+  /** Retrieve the latest probe verdict for every platform provider. */
+  async getStandingView(): Promise<ProviderStandingView> {
+    try {
+      return await this.query.getProviderStandingView(
+        create(GetProviderStandingViewInputSchema, {}),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+}