@stigmer/sdk 3.12.4 → 3.12.6

package/mcpserver-connect.d.ts

@@ -0,0 +1,79 @@
+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";
+/**
+ * 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 declare const CONNECT_POLL_INTERVAL_MS = 2500;
+/**
+ * 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 declare const CONNECT_SETTLE_BOUND_MS: number;
+/**
+ * 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 declare class ConnectStillRunningError extends Error {
+    readonly mcpServerId: string;
+    constructor(mcpServerId: string, waitedMs: number);
+}
+/** 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 declare function connectAndWait(client: McpServerConnectLane, input: ConnectInput, options?: ConnectAndWaitOptions): Promise<McpServer>;
+//# sourceMappingURL=mcpserver-connect.d.ts.map

package/mcpserver-connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpserver-connect.d.ts","sourceRoot":"","sources":["../src/mcpserver-connect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wDAAwD,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uDAAuD,CAAC;AAI1F;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACtD,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,QAAc,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAQlD;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,SAAS,CAAC,CA2BpB"}

package/mcpserver-connect.js

@@ -0,0 +1,114 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import { ConnectPhase } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+import { isUnimplemented, wrapError } from "./gen/errors.js";
+/**
+ * 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 {
+    mcpServerId;
+    constructor(mcpServerId, waitedMs) {
+        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;
+    }
+}
+/**
+ * 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, input, options) {
+    const pollIntervalMs = options?.pollIntervalMs ?? CONNECT_POLL_INTERVAL_MS;
+    const waitMs = Math.min(options?.deadlineMs ?? CONNECT_SETTLE_BOUND_MS, CONNECT_SETTLE_BOUND_MS);
+    let started;
+    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, input, waitMs) {
+    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;
+    const timeout = new Promise((_, 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, failureMessage) {
+    const code = Code[failureCode];
+    return wrapError(new ConnectError(failureMessage, typeof code === "number" ? code : Code.Unknown));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=mcpserver-connect.js.map

package/mcpserver-connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpserver-connect.js","sourceRoot":"","sources":["../src/mcpserver-connect.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/sdk",
-  "version": "3.12.4",
+  "version": "3.12.6",
   "description": "Stigmer TypeScript SDK — typed API client for all Stigmer platform resources",
   "license": "Apache-2.0",
   "type": "module",
@@ -45,6 +45,6 @@
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
-    "@stigmer/protos": "3.12.4"
+    "@stigmer/protos": "3.12.6"
   }
 }

package/src/__tests__/mcpserver-connect.test.ts

@@ -0,0 +1,181 @@
+// Pins the shared async-connect protocol (stigmer/stigmer#425): start + poll,
+// terminal-failure rehydration, the UNIMPLEMENTED blocking fallback, and the
+// still-running bound. Every SDK surface (CLI, React hooks, host apps) rides
+// this one implementation, so its contract is pinned here rather than
+// re-tested per consumer.
+
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { ConnectInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import { ConnectPhase } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+import { StigmerError, wrapError } from "../gen/errors.js";
+import {
+  connectAndWait,
+  ConnectStillRunningError,
+  type McpServerConnectLane,
+} from "../mcpserver-connect.js";
+
+const INPUT = create(ConnectInputSchema, { mcpServerId: "mcp-1", org: "test-org" });
+
+function server(overrides?: {
+  phase?: ConnectPhase;
+  failureCode?: string;
+  failureMessage?: string;
+  warning?: string;
+  toolName?: string;
+}): McpServer {
+  return create(McpServerSchema, {
+    metadata: { id: "mcp-1", name: "Test Server" },
+    status: {
+      ...(overrides?.toolName !== undefined
+        ? { discoveredCapabilities: { tools: [{ name: overrides.toolName }] } }
+        : {}),
+      connectStatus: {
+        phase: overrides?.phase ?? ConnectPhase.connecting,
+        workflowId: "stigmer/mcp-server/connect/mcp-1",
+        failureCode: overrides?.failureCode ?? "",
+        failureMessage: overrides?.failureMessage ?? "",
+        warning: overrides?.warning ?? "",
+      },
+    },
+  });
+}
+
+function unimplemented(): StigmerError {
+  return wrapError(new ConnectError("startConnect is not implemented", Code.Unimplemented));
+}
+
+const NEVER = () => new Promise<McpServer>(() => {});
+
+describe("connectAndWait", () => {
+  it("resolves with the settled resource once connect_status reports success", async () => {
+    const polled = [
+      server({ phase: ConnectPhase.connecting }),
+      server({ phase: ConnectPhase.succeeded, toolName: "search_code" }),
+    ];
+    const lane: McpServerConnectLane = {
+      startConnect: async () => server(),
+      connect: NEVER,
+      get: async () => polled.shift() ?? server({ phase: ConnectPhase.succeeded }),
+    };
+
+    const settled = await connectAndWait(lane, INPUT, { pollIntervalMs: 1 });
+    expect(settled.status?.connectStatus?.phase).toBe(ConnectPhase.succeeded);
+    expect(settled.status?.discoveredCapabilities?.tools[0]?.name).toBe("search_code");
+  });
+
+  it("surfaces the CONNECTING snapshot (dead-runner warning) via onStarted", async () => {
+    const lane: McpServerConnectLane = {
+      startConnect: async () => server({ warning: "no runner appears to be polling the task queue" }),
+      connect: NEVER,
+      get: async () => server({ phase: ConnectPhase.succeeded }),
+    };
+
+    let warning = "";
+    await connectAndWait(lane, INPUT, {
+      pollIntervalMs: 1,
+      onStarted: (started) => {
+        warning = started.status?.connectStatus?.warning ?? "";
+      },
+    });
+    expect(warning).toContain("no runner");
+  });
+
+  it("rehydrates a failed operation into the classification the blocking RPC would have thrown", async () => {
+    const lane: McpServerConnectLane = {
+      startConnect: async () => server(),
+      connect: NEVER,
+      get: async () =>
+        server({
+          phase: ConnectPhase.failed,
+          failureCode: "FailedPrecondition",
+          failureMessage: "connect failed for MCP server 'Test Server': missing credentials",
+        }),
+    };
+
+    const err = await connectAndWait(lane, INPUT, { pollIntervalMs: 1 }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(StigmerError);
+    const stigmerErr = err as StigmerError;
+    // Byte-parity with the blocking lane: same code mapping, same raw message.
+    expect(stigmerErr.code).toBe("failed-precondition");
+    expect(stigmerErr.message).toBe("connect failed for MCP server 'Test Server': missing credentials");
+  });
+
+  it("maps an unknown failure_code to the unknown classification instead of crashing", async () => {
+    const lane: McpServerConnectLane = {
+      startConnect: async () => server(),
+      connect: NEVER,
+      get: async () =>
+        server({
+          phase: ConnectPhase.failed,
+          failureCode: "SomeFutureCode",
+          failureMessage: "boom",
+        }),
+    };
+
+    const err = await connectAndWait(lane, INPUT, { pollIntervalMs: 1 }).catch((e: unknown) => e);
+    expect((err as StigmerError).code).toBe("unknown");
+    expect((err as StigmerError).message).toBe("boom");
+  });
+
+  it("falls back to the blocking connect when the backend answers UNIMPLEMENTED", async () => {
+    let blockingCalled = false;
+    const lane: McpServerConnectLane = {
+      startConnect: async () => {
+        throw unimplemented();
+      },
+      connect: async () => {
+        blockingCalled = true;
+        return server({ phase: ConnectPhase.succeeded, toolName: "search_code" });
+      },
+      get: NEVER,
+    };
+
+    const settled = await connectAndWait(lane, INPUT);
+    expect(blockingCalled).toBe(true);
+    expect(settled.status?.discoveredCapabilities?.tools[0]?.name).toBe("search_code");
+  });
+
+  it("propagates non-UNIMPLEMENTED start failures untouched", async () => {
+    const startFailure = wrapError(new ConnectError("no such server", Code.NotFound));
+    const lane: McpServerConnectLane = {
+      startConnect: async () => {
+        throw startFailure;
+      },
+      connect: NEVER,
+      get: NEVER,
+    };
+
+    await expect(connectAndWait(lane, INPUT)).rejects.toBe(startFailure);
+  });
+
+  it("throws ConnectStillRunningError when the deadline elapses while CONNECTING", async () => {
+    const lane: McpServerConnectLane = {
+      startConnect: async () => server(),
+      connect: NEVER,
+      get: async () => server({ phase: ConnectPhase.connecting }),
+    };
+
+    const err = await connectAndWait(lane, INPUT, { pollIntervalMs: 1, deadlineMs: 20 }).catch(
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(ConnectStillRunningError);
+    expect((err as ConnectStillRunningError).mcpServerId).toBe("mcp-1");
+  });
+
+  it("bounds the blocking fallback with the same still-running semantics (soft, non-cancelling)", async () => {
+    const lane: McpServerConnectLane = {
+      startConnect: async () => {
+        throw unimplemented();
+      },
+      connect: NEVER,
+      get: NEVER,
+    };
+
+    const err = await connectAndWait(lane, INPUT, { deadlineMs: 20 }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(ConnectStillRunningError);
+  });
+});